Robot Bridge

What Robot Bridge does

Robot Bridge is a webhook-driven voice conversation bridge between an M5Stack/ESP32 StackChan robot and Hermes Agent. The ESP32 connects over the XiaoZhi WebSocket protocol, streaming Opus audio and JSON. The bridge on port 8081 is a pure execution layer with no decision logic. It runs speech recognition locally with SenseVoiceSmall, posts the transcript to a Hermes webhook subscription named stackchan on port 8644, and leaves every decision to the agent.

Hermes, with its SOUL.md, skills, memory and MCP tools, answers by calling tools served by the bridge. There are 11 of them, covering listen, speak, see, face, look, led, emote, idle, track, face_register and status. Speech comes from a local Sherpa-ONNX Matcha voice, and barge-in lets the user interrupt playback. Camera features include face tracking that makes the servos follow a face, plus stranger detection and LBPH face registration. The service also exposes an /ota endpoint for initial ESP32 configuration and a Prometheus metrics module. The README shows the Hermes config.yaml, the hermes webhook subscribe command and the start commands.

Key features

• Full-duplex XiaoZhi WebSocket link with Opus audio to an ESP32 robot
• Local Chinese speech recognition with SenseVoiceSmall
• Local text-to-speech with Sherpa-ONNX Matcha and ffmpeg resampling
• 11 MCP tools including speak, emote, look, led, track and face_register
• Camera face tracking with servo follow, and LBPH face registration for strangers
• Barge-in and an /ota endpoint that serves initial ESP32 configuration

When to use it

• Giving a Hermes agent a voice and a physical face on a desk robot
• Letting an agent control a robot's LEDs, expressions and head movement through MCP tools
• Running a Chinese-language voice assistant with a SOUL.md persona on a StackChan

Who it is for: Makers who own a StackChan or another M5Stack/ESP32 robot and want Hermes Agent to control it by voice.

How it fits with Hermes Agent

Built for Hermes Agent: it forwards transcripts to a Hermes webhook and gives the agent MCP tools to control the robot.

How to install Robot Bridge

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Requirements: Python 3.12+, Hermes Agent with the webhook and api_server platforms enabled, FunASR / Sherpa-ONNX models, FFmpeg, and a StackChan ESP32 device

Note: The README is written in Chinese, and its clone command uses a placeholder path (github.com/user/robot-bridge) rather than this repository's path.

FAQ