hermes-gadget-sdk README

The project's README from github.com/Adolanium/hermes-gadget-sdk. As one markdown file: README.md.

Hermes Gadget logo

Hermes Gadget

Hold a button. Ask Hermes. Hear the answer.
A small device for your own Hermes Agent, with its tools, memory, and skills.

Set up a board · Try the simulator · Read the docs

The round simulator display, ready for a question
The desktop simulator runs the same device core. No board needed to try it.

Choose your starting point

I have a board I want to try it first I want to build with it
Open the browser installer Start the desktop simulator Explore the SDK
Install over USB, connect Wi-Fi, and pair with your Hermes. Try a scripted demo, then connect your own Hermes. Add a board, device actions, sensors, or your own face.
Chrome or Edge, a USB data cable, 2.4 GHz Wi-Fi, and Hermes. No firmware toolchain. Python 3.10+, CMake 3.16+, and a C++17 compiler. Start with the development guide and tests.

What you can do

Your Hermes does the thinking. Real conversations need Hermes Agent and the Gadget plugin. Voice also needs speech recognition and text-to-speech configured. The demo server gives scripted replies. Follow Connect Hermes when you are ready.

Supported hardware

Board How you talk Audio
Waveshare ESP32-S3-LCD-1.54 Hold BOOT Onboard microphones and speaker
Waveshare ESP32-S3-Touch-AMOLED-1.75 Hold the screen Onboard microphones; speaker output
Waveshare ESP32-S3-Touch-AMOLED-1.75C Hold the screen Onboard microphones and speaker; experimental
Espressif ESP32-S3-BOX-3 Hold the screen or BOOT Onboard microphones and speaker; experimental
M5Stack CoreS3 Hold the screen Onboard audio and battery management; experimental
ESP32-S3 breadboard build Hold TALK Wire the microphone and optional speaker

Check the exact model and connections in the hardware guide. Other boards need a port.

Raspberry Pi 4 and 5 have an experimental Linux client for 64-bit Raspberry Pi OS Lite Trixie. Add USB audio, GPIO controls, or a display as needed. ARM64 release packages include the native core and a service installer.

These ports build in CI. Physical verification reports are not yet recorded; treat them as experimental until the hardware verification table links a report for your revision.

Try the demo from a checkout

Already have Python, CMake, and a compiler? Start here.

In your activated environment at the repository root:

python -m pip install -e ".[dev]"
hermes-gadget build-sim --test
hermes-gadget devserver --pairing

In a second terminal with the same environment activated:

hermes-gadget sim --url ws://127.0.0.1:8765/gadget --board sim-466x466-round

Type approve <CODE> in the first terminal, using the code on the device. Type a message in the simulator to receive a streamed echo. The desktop guide covers platform-specific prerequisites and live audio.

On the screen

Ready Listening Thinking Speaking
Ready Listening Thinking Speaking

These images show the simulator's device display. The simulator guide covers its desktop controls, board profiles, and scripted runs.

Find the right guide

Use a gadget Build with the SDK
Choose a starting point Development and tests
Set up a board Add a board, actions, or sensors
Try the simulator Customize the face
Run a Linux gadget Hardware verification
Connect Hermes Architecture
Talk, type, and interrupt Protocol
Change Wi-Fi or update firmware Hermes integration reference
Troubleshooting Hardware and wiring

Project status

Releases include prebuilt firmware for the profiles listed in that release. Newly merged profiles need a source build until the next release. After the first USB flash, hermes gadget update installs new firmware over the air. A build that cannot reach Hermes rolls itself back.

The simulator and firmware share a portable C++17 core. CI tests the core, Python tools, installer, and plugin against a real Hermes gateway, and builds every supported board. The development guide describes the test suites and pinned Hermes version.

After installing firmware, you can configure Wi-Fi from your phone through the gadget's temporary network. USB setup remains available. Wake-word activation is not included.

The Home Assistant and MQTT examples expose a configured lamp and temperature sensor through a Linux gadget. They include pairing instructions, fixed action targets, asynchronous completion and local integration tests.

CI Hermes integration

Contributing

Bug reports from real boards, new boards, fixes, and docs are welcome. Read CONTRIBUTING.md. Report security problems privately through SECURITY.md.

Affiliation and trademarks

Hermes Gadget is an independent, community-made project. It is not affiliated with, endorsed by, sponsored by or supported by Nous Research.

"Hermes", "Hermes Agent", "Nous Research" and the Hermes Agent mascot (the girl with the headphones, sometimes called "Nous Girl") are trademarks or brand assets of Nous Research. They appear here only to describe compatibility with Hermes Agent.

License

Project code and documentation are licensed under the MIT license.

Third-party dependencies, adapted drivers, and artwork retain their respective licenses. See Third-party licenses and attribution and NOTICE for details.

The MIT license grants no rights to Nous Research's names or marks.

hermes-gadget-sdk (Adolanium/hermes-gadget-sdk)

Searching Database…

403 ·GitHub
Hermes-gadget-sdk
Что это?Hermes Gadget SDK позволяет собирать голосовые и текстовые аппаратные устройства (платы ESP32, Linux-клиент на Raspberry Pi или настольный симулятор), которые подключаются к вашему собственному Hermes Agent: зажимаете кнопку, задаёте вопрос и слышите или видите ответ.
Как запустить гаджет?Если плата у вас уже есть, прошейте её через браузерный установщик (Chrome или Edge) по USB и подключите её к Wi-Fi; чтобы попробовать без железа, запустите настольный симулятор из клона репозитория с Python, CMake и компилятором C++.
Что нужно на моей машине, чтобы собрать или запустить симулятор?Для симулятора и работы с SDK нужны Python 3.10+, CMake 3.16+ и компилятор C++17; для прошивки реальной платы достаточно браузера на базе Chromium, USB data-кабеля и Wi-Fi на 2,4 ГГц.
Работает ли он с настоящим Hermes Agent сразу из коробки?Не полностью: для настоящих разговоров нужны Hermes Agent и плагин Gadget, а для голоса — настроенные распознавание речи и синтез речи; без этого демо-сервер отвечает только заготовленными фразами, а активация по кодовому слову вообще не входит в комплект.
Какие платы и платформы реально поддерживаются?Прошивка нацелена на несколько плат Waveshare ESP32-S3, Espressif ESP32-S3-BOX-3 и M5Stack CoreS3 (большинство пока экспериментально), плюс экспериментальный 64-битный Linux-клиент для Raspberry Pi 4/5 под Raspberry Pi OS Lite; другие платы требуют нового портирования.
Достаточно ли лицензии MIT, чтобы переиспользовать всё это?Собственный код и документация проекта — под MIT, но сторонние зависимости, адаптированные драйверы и графика сохраняют свои лицензии, а MIT не даёт прав на имя «Hermes» и маскота Nous Research.
Можно ли обновить прошивку без повторной прошивки по USB?Да, после первой прошивки по USB можно выполнить «hermes gadget update», чтобы передать новую прошивку по воздуху, а сборка, которая не может связаться с Hermes, сама откатывается.
Может ли гаджет управлять устройствами умного дома?В репозитории есть примеры для Home Assistant и MQTT, которые открывают доступ к настроенной лампе и датчику температуры через Linux-гаджет, с инструкциями по сопряжению и локальными интеграционными тестами.
Что на самом деле показывает экран устройства?Экран переключается между состояниями Ready, Listening, Thinking и Speaking, чтобы было видно, чем занят гаджет, пока он говорит.
What are similar projects?arduino-esp32, muse-gadget-sdk, mongoose, ESP32Marauder, xiaozhi-esp32, esphome, WLED, awesome-esp32
Which topics is it in?simulator, esp32-s3, cpp17, mqtt, home-assistant, microcontroller, esp32, voice-assistant, hermes-agent, firmware, iot, raspberry-pi
Creator
Adolanium
Size
1.8 MB
Stars
403
Updated
CommitOct 17Releasev0.2.0Oct 05
Age
15d
Commits · 90 Days