Firmware for turning the MouthPad^ wearable into a wired USB HID device. The microcontroller sits between the tablet/PC and the MouthPad^, bridging BLE HID + NUS traffic to USB HID + CDC, without changing the MouthPad^ firmware.
This repository contains two platform implementations that expose identical USB interfaces:
| Platform | MCU / SDK | Status | Documentation |
|---|---|---|---|
| Nordic nRF52840 | NCS / Zephyr RTOS | ✅ Production | ncs/README.md |
| ESP32-S3 | ESP-IDF | ✅ Feature parity | esp/README.md |
Both firmwares expose the same HID descriptors, CDC command set, LED semantics, and bond-management behavior, so you can swap hardware without reconfiguring the host.
Pick the platform that matches your hardware:
Ships on Seeed XIAO nRF52840. Also supports Adafruit Feather nRF52840 and Nordic/April dongles.
cd ncs
docker-compose run --rm mouthpad-build
# Flash: drag build/app/zephyr/zephyr.uf2 to bootloader driveAlternative implementation for Seeed XIAO ESP32-S3 and LilyGo T-Dongle-S3.
cd esp
source env.sh # Source ESP-IDF environment
make xiao # Build for XIAO ESP32-S3
make flash # Flash firmware- USB HID – Mouse + consumer control (standard multi-interface HID device)
- USB CDC Port 0 – Protobuf/text tunnel mirroring BLE NUS link
- USB CDC Port 1 – Maintenance console (
dfu,clear,serial) + logs
- BLE HID client – Discovers and connects to MouthPad^ HID service
- Nordic UART Service (NUS) – Bidirectional data tunnel for configuration/telemetry
- Bond management – Stores pairing and auto-reconnects
- RSSI monitoring – Tracks connection quality
- LED indicators – Scanning (blink), connected (solid), activity (flicker)
- NeoPixel support (nRF) – Battery-level colors when available
- Console logging – Real-time diagnostics on CDC port 1
| Platform | Method |
|---|---|
| nRF52840 (UF2) | UF2 bootloader (drag-and-drop) or type dfu command |
| nRF52840 (Nordic DFU) | Nordic DFU bootloader via nrfutil or nRF Connect Desktop |
| ESP32-S3 | ROM serial downloader via dfu command or idf.py flash |
.
├── ncs/ # Nordic Connect SDK workspace (nRF52840)
│ ├── app/ # Application source
│ ├── Makefile # Build helpers
│ ├── docker-compose.yml # Containerized builds
│ └── README.md # 👈 nRF52840 documentation
├── esp/ # ESP-IDF workspace (ESP32-S3)
│ ├── main/ # Application source
│ ├── Makefile # Build helpers
│ └── README.md # 👈 ESP32-S3 documentation
├── resources/ # Additional documentation and assets
│ ├── notes/ # Technical documentation
│ └── images/ # Diagrams and photos
└── web/ # Web-based configuration tool
Both firmwares expose a maintenance console on the second CDC port:
| Command | Description |
|---|---|
dfu |
Reboot into bootloader (UF2 for nRF, ROM downloader for ESP32) |
reset |
Disconnect MouthPad^, erase BLE bonds, return to pairing mode |
restart |
Restart firmware (software reset) |
serial |
Print USB serial number |
version |
Display firmware version, build timestamp, and platform info |
Port names:
- macOS:
/dev/cu.usbmodem<serial>3 - Linux:
/dev/ttyACM1 - Windows:
COM<n>(check Device Manager)
| Board | Status | Notes | Purchase |
|---|---|---|---|
| Seeed XIAO nRF52840 | ✅ Production | Primary shipping target (expansion board supported) | Seeed Studio |
| Adafruit Feather nRF52840 Express | ✅ Production | Requires custom bootloader config | Adafruit |
| Nordic nRF52840 Dongle (PCA10059) | ✅ Production | Stock Nordic LED pins | Digi-Key |
| April Brothers nRF52840 Dongle (PCA10059) | ✅ Production | Non-standard LED wiring | April Brother |
| Raytac MDBT50Q-RX Dongle | ✅ Production | UF2 bootloader, single LED | Raytac |
| Raytac MDBT50Q-CX-40 Dongle | ✅ Production | Nordic DFU bootloader, blue+red LEDs | Raytac |
| MakerDiary nRF52840 MDK USB Dongle | ✅ Production | RGB LED support | MakerDiary |
| Board | Status | Notes | Purchase |
|---|---|---|---|
| Seeed XIAO ESP32-S3 | ✅ Supported | Mirrors nRF feature set | Seeed Studio |
| LilyGo T-Dongle-S3 | ✅ Supported | Alternative form factor | Amazon |
GitHub Actions builds firmware for all board variants on every push to main:
nRF52840 builds:
mouthpad^usb_seeed_xiao_nrf52840_<commit>.uf2mouthpad^usb_adafruit_feather_nrf52840_<commit>.uf2mouthpad^usb_nordic_nrf52840dongle_<commit>.uf2mouthpad^usb_aprbrother_nrf52840_<commit>.uf2mouthpad^usb_raytac_mdbt50q_rx_<commit>.uf2mouthpad^usb_raytac_mdbt50q_cx_40_<commit>.zip(Nordic DFU)mouthpad^usb_makerdiary_nrf52840mdk_<commit>.uf2
Artifacts are available in the Actions tab for 90 days.
- Choose your platform – Work in either
ncs/oresp/directory - Follow build instructions – See platform-specific README
- Test on hardware – Verify USB enumeration and BLE connection
- Submit PR – Include board(s) tested in description
Both platforms should maintain behavioral parity for USB/BLE interfaces.
- Platform-specific issues: See ncs/README.md or esp/README.md
- General questions: Open an issue with reproduction steps
- Build problems: Check platform-specific troubleshooting sections
MIT License – See LICENSE for details.