hyj-STAR / voiceshell-muse-bridge

# VoiceShell Muse Bridge
### Pair on a board. Run the connection on your server.
**A path from your devices to your Muse, without an ESP32 in every message hop.**
English · 简体中文
Evidence · Get started · Hardware and roadmap · Collaborate
## Why a bridge?
We're building VoiceShell, wearable voice-input hardware and companion software for quieter, less conspicuous conversations with your own agents. When we saw Muse Gadgets, we wanted to find out whether the device we were already building could connect to it.
Our headset isn't an ESP32. That led to a more specific question: **could we use an ESP32 for the initial pairing, then let our own Linux server handle the conversation?** If that worked, we could build adapters for our software and hardware around the server, rather than keep a development board in every message path.
So we followed the official SDK examples and tried it. Getting there took a few detours.
On the Mac, a successful advertising callback didn't mean the phone could find the device. On Windows, the adapter reported peripheral support, but GATT advertising still failed. A physical ESP32-S3 finally appeared in the Muse app—only for setup to get stuck again after joining Wi-Fi.
Eventually, we completed three text round trips through the ESP32. Then we stopped its application and ran two separate sessions on Linux. **Linux sent the messages and received the replies without the board forwarding them.**
That's the experiment we're sharing here: the code, the steps that worked, and the dead ends worth knowing about before you try it yourself. Other client adapters, long-running operation and headset audio are still ahead of us.
## Where we got stuck
### Connected to Wi-Fi, but not to Muse
The board joined the hotspot, while the app kept waiting. Its logs showed a VM lookup timeout and HTTP status 0—not an authentication rejection. Being able to use Muse on the phone didn't tell us whether a device tethered to that phone had a working route to the same service.
We eventually completed setup using a working Windows hotspot/proxy path. That is a result from our setup, not a promise that phone tethering shares a VPN or that every connection failure has the same cause. If you get stuck here, check discovery, Wi-Fi association and cloud connectivity separately before changing credentials.
### The reply was on the phone, not back at the device
Sending a message worked. Reading the answer back was a different problem: the device's chat-history request returned `403: path not allowed for device token`.
We added a small device tool, `voiceshell.reply`, that Muse can call to return text. Each request gets a fresh correlation ID so we can tell which reply belongs to which request. This gave us a working text round trip without accessing the blocked history endpoint. It still depends on Muse invoking the tool; it isn't token-by-token streaming.
The Chinese walkthrough covers the setup sequence and network troubleshooting in more detail. The compatib