mouthpad usb - Moses Yebei

The Problem

Bleeding‑edge wearable devices often expose a BLE HID stream for low‑power use, but many host devices lack native support for BLE. An adapter that bridges BLE HID and UART to a wired USB HID/CDC interface removes this gap without modifying the wearable firmware.

What This Does

esp/main/main.c and ncs/app/src/main.c implement a dual‑stack firmware that runs on an ESP32‑S3 or an nRF52840. The code:

Registers a BLE HID client (ble_hid.c) to connect to the MouthPad’s HID service.
Tunnels the Nordic UART Service (ble_nus.c) into a USB CDC port.
Exposes a standard HID mouse/consumer device (ble_hid.c + main.c) and two CDC ports: one for configuration/telemetry, the other for maintenance.
Handles LED status, NeoPixel battery display, and button events (leds.c, button.c).
Provides DFU and reset commands over the maintenance CDC port (main.c).

All protobuf traffic is generated with NanoPB (esp/main/mouthpad-proto/nanopb/).

How It Is Wired

Entry point – esp/main/main.c (or ncs/app/src/main.c).

main() calls esp_idf_init() → prepares the kernel and peripherals.
ble_init() → creates the BLE stack, then ble_hid_init() and ble_nus_init() register GATT services and callbacks.
usb_init() sets up the USB HID descriptor (in main.c) and the two CDC interfaces.
The event loop (app_main()) dispatches BLE events to ble_hid.c/ble_nus.c, which forward payloads to the USB endpoints via usb_hid_send() and cdc_write().
Button presses trigger button_event() → updates LEDs (leds.c) and may send a DFU command to the USB side.
Maintenance commands received on CDC port 1 are parsed in main.c and invoke dfu_start(), reset_bonds(), etc.

The most widely used functions are ble_hid_send() and cdc_write(), each called from both the BLE and main loops. The USB stack is the single point of failure; any change to usb_init() or the descriptor files can break compatibility with host drivers.

How To Use It

Setup

# For the nRF52840 build
cd ncs
docker-compose run --rm mouthpad-build
# Flash: copy build/app/zephyr/zephyr.uf2 to the bootloader drive

# For the ESP32‑S3 build
cd esp
source env.sh          # Loads ESP‑IDF environment
make xiao              # Build for the XIAO ESP32‑S3
make flash             # Upload firmware

The Dockerfile and docker-compose.yml live in ncs/. The Makefile and env.sh in esp/ drive the ESP‑IDF build.

Configuration

No external config files are required; the firmware discovers the MouthPad over BLE automatically. For custom USB descriptors, edit esp/main/main.c or ncs/app/src/main.c.

Running It

After flashing the MCU, the device presents two USB interfaces: HID and two CDC ports. Use screen /dev/ttyACM1 115200 (Linux) or a serial terminal to interact with the maintenance console. The device will auto‑reconnect to a previously bonded MouthPad.

Real-World Use

In an assistive‑technology lab, the dongle is plugged into a laptop. The MouthPad sends BLE HID data; the dongle translates this into a standard USB mouse that the OS can use without extra drivers. A technician can upload new firmware via the DFU command on the maintenance CDC port.

# Trigger DFU on the ESP32‑S3
printf "dfu\n" > /dev/ttyACM1

The laptop then reboots into the bootloader, ready for a fresh flash.

Code Health & Issues

Low – Dependencies declared without a lockfile (esp/main/mouthpad-proto/nanopb/extra/poetry/pyproject.toml).
Extensive test suite (971 files) suggests good coverage, but CI (.github/workflows/ci.yml) is minimal.
No secrets or sensitive data are committed.
The project is licensed under an MIT‑style license (LICENSE).

The Bottom Line

This repository delivers a production‑grade dual‑platform bridge that turns a BLE‑only wearable into a wired USB HID device. The code is well‑structured around clear entry points (main.c), with dedicated modules for BLE, USB, and hardware abstraction. The main risk is the absence of a lockfile for the NanoPB Python dependencies, which can affect reproducibility. Engineers can adopt the firmware on either an nRF52840 or ESP32‑S3 with minimal effort, using the provided Docker or Makefile workflows.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,436 files

Protocol Buffers302
C296
C/C++ Header91
Python44
Markdown36
Shell13

ExpressDocker

Module dependencies

The 10 most depended-upon modules of 45, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_anopb_generator_proto__utils["_utils"] n1_anopb_generator_proto__utils["_utils"] n2_opb_generator_proto___init__["__init__"] n3_opb_generator_proto___init__["__init__"] n4_to_nanopb_generator___init__["__init__"] n5_to_nanopb_generator___init__["__init__"] n6_b_generator_nanopb_generator["nanopb_generator"] n7_b_generator_nanopb_generator["nanopb_generator"] n8__mouthpad_proto_nanopb_build["build"] n9_thpad_proto_nanopb_conanfile["conanfile"] n6_b_generator_nanopb_generator --> n4_to_nanopb_generator___init__ n6_b_generator_nanopb_generator --> n0_anopb_generator_proto__utils n6_b_generator_nanopb_generator --> n2_opb_generator_proto___init__ n2_opb_generator_proto___init__ --> n0_anopb_generator_proto__utils n7_b_generator_nanopb_generator --> n5_to_nanopb_generator___init__ n7_b_generator_nanopb_generator --> n1_anopb_generator_proto__utils n7_b_generator_nanopb_generator --> n3_opb_generator_proto___init__ n3_opb_generator_proto___init__ --> n1_anopb_generator_proto__utils

Dependencies

2 of 3 declared dependencies are a major version behind. Resolved 3 of 3 against the registry.

Package	Declared	Latest	Behind
`setuptools`	>= 66.1.0	84.0.0	18 major
`protobuf`	>=3.19	7.35.1	4 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds esp/main/mouthpad-proto/nanopb/extra/poetry/pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh3 occurrences

.github/workflows

stefanzweifel/git-auto-commit-action@v5, espressif/esp-idf-ci-action@v1, softprops/action-gh-release@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

esp/main/mouthpad-proto/nanopb/extra/poetry/pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Make CI invoke the test suite it hashigh958 occurrences

.github/workflows

958 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Enable Dependabot or Renovatemedium

8 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

esp/main/mouthpad-proto/nanopb/tests/docker_images/ubuntu1804/Dockerfile

ubuntu:bionic

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Pin the resolution so a vulnerable version cannot installmedium12 occurrences

no lockfile, and the declared ranges reach protobuf@3.19 CVE-2026-0994 (high) +5 more; setuptools@66.1.0 CVE-2025-47273 (high) +5 more

The range includes versions with published advisories and nothing in the repository records which one was resolved, so two installs a month apart can differ in whether they are vulnerable and neither is reproducible from what is committed.

Fix: Commit the lockfile, which fixes the resolution and makes this answerable.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.