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
What is this?Hermes Gadget SDK lets you build voice and text hardware devices (ESP32 boards, a Raspberry Pi Linux client, or a desktop simulator) that connect to your own Hermes Agent: hold a button, ask it something, and hear or see the reply.
How do I get a gadget running?If you already own a board, flash it through the browser-based installer (Chrome or Edge) over USB and pair it with Wi-Fi; to try it without hardware, run the desktop simulator from a checkout with Python, CMake, and a C++ compiler.
What do I need on my machine to build or simulate it?For the simulator and SDK work you need Python 3.10+, CMake 3.16+, and a C++17 compiler; flashing a physical board only needs a Chromium-based browser, a USB data cable, and 2.4 GHz Wi-Fi.
Does it talk to a real Hermes Agent out of the box?Not fully: real conversations need Hermes Agent plus the Gadget plugin, and voice needs speech recognition and text-to-speech configured; without that the demo server only gives scripted replies, and wake-word activation isn't included at all.
Which boards and platforms are actually supported?Firmware targets several Waveshare ESP32-S3 boards, the Espressif ESP32-S3-BOX-3, and M5Stack CoreS3 (most still experimental), plus an experimental 64-bit Linux client for Raspberry Pi 4/5 running Raspberry Pi OS Lite; other boards need a new port.
Is the MIT license enough to reuse everything here?The project's own code and docs are MIT, but third-party dependencies, adapted drivers, and artwork keep their own licenses, and MIT grants no rights to Nous Research's 'Hermes' name or mascot.
Can firmware be updated without re-flashing over USB?Yes, after the first USB flash you can run 'hermes gadget update' to push new firmware over the air, and a build that can't reach Hermes rolls itself back.
Can a gadget control smart-home devices?The repo includes Home Assistant and MQTT examples that expose a configured lamp and temperature sensor through a Linux gadget, with pairing instructions and local integration tests.
What does the device screen actually show?The display cycles through Ready, Listening, Thinking, and Speaking states so you can see what the gadget is doing while it talks.
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