Merge pull request #4 from RobertDaleSmith/esp32

Starts porting firmware to ESP-IDF based firmware for the Seeed XIAO ESP32-S3 board.

Author: RobertDaleSmith

AGENTS.md

@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `app/src/` carries the firmware modules (BLE transport, USB HID, inputs); pair each new driver with a matching header.
+- `app/prj.conf` and `CMakeLists.txt` hold Zephyr configuration, while optional board overlays sit beside the sources they affect.
+- `docs/` stores build notes and assets; `scripts/`, `tools/`, the `Dockerfile`, and `docker-compose.yml` provide repeatable workflows.
+- Dependency trees (`modules/`, `zephyr/`, `nrf/`, `nrfxlib/`) are managed by `west` and should remain untouched except through updates.
+
+## Build, Test, and Development Commands
+- `docker-compose run --rm mouthpad-build` rebuilds both supported boards inside a containerized Zephyr environment.
+- `docker-compose run --rm mouthpad-dev` drops you into an interactive shell with the toolchain and `west` installed.
+- `make build BOARD=xiao_ble` (or `adafruit_feather_nrf52840`) wraps `west build -b <board> app --pristine=always`; results land in `build/app`.
+- `make flash`, `make flash-uf2`, and `make monitor` program hardware via J-Link, UF2 mass storage, or RTT logging respectively.
+- For lighter iterations, invoke `west build -b xiao_ble app` directly and clean with `rm -rf build` when switching boards.
+
+## Coding Style & Naming Conventions
+- Follow Zephyr C style: tabs for indentation, 100-character lines, `UPPER_SNAKE_CASE` macros, and module-prefixed statics such as `ble_transport_*`.
+- Keep headers limited to public interfaces, declare file-local helpers as `static`, and minimize cross-module coupling.
+- Run `clang-format -i <files>` from the repo root so the Zephyr `.clang-format` is honored before sending patches.
+- Log through `LOG_INF`, `LOG_DBG`, and friends with concise, hardware-focused phrasing.
+
+## Testing Guidelines
+- After flashing, confirm BLE pairing and USB enumeration on a host; capture RTT or USB CDC logs for regressions.
+- Place automated checks under `app/tests` with Zephyr `ztest`; reuse the `test/cmock` utilities for mocking hardware seams.
+- Execute `west twister -p native_posix_64 --testsuite-root app/tests` to run suites locally and gate pull requests.
+
+## Commit & Pull Request Guidelines
+- Adopt Conventional Commit prefixes (`feat`, `fix`, `chore`, `docs`, etc.) consistent with the current history.
+- Keep commits focused, exclude generated artefacts (`build/`, `*.uf2`), and ensure `west.yml` changes are intentional.
+- PRs should outline tested hardware, configuration implications, and include logs or screenshots when touching DFU or user-visible flows.
+
+## DFU & Hardware Tips
+- Copy `build/app/zephyr/app.uf2` to the board’s storage volume (double-tap reset first) for UF2 updates.
+- When using J-Link, verify probe firmware and power stability before `make flash`; erratic RTT output usually signals cabling issues.

README.md

@@ -188,8 +188,9 @@ This project includes GitHub Actions that automatically build and test your code
 2. Create a feature branch
 3. Make your changes
 4. Test thoroughly using one of the build methods
-5. Submit a pull request
+5. Review the [Repository Guidelines](AGENTS.md) for coding, testing, and PR expectations
+6. Submit a pull request
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.

app/prj.conf

@@ -24,7 +24,7 @@ CONFIG_USB_CDC_ACM_RINGBUF_SIZE=4096
 CONFIG_USB_DEVICE_HID=y # USB HID
 CONFIG_USB_DEVICE_INITIALIZE_AT_BOOT=y
 CONFIG_USB_DEVICE_PRODUCT="MouthPad^USB"
-CONFIG_USB_DEVICE_MANUFACTURER="Augmental.Tech"
+CONFIG_USB_DEVICE_MANUFACTURER="Augmental Tech"
 CONFIG_USB_DEVICE_SN="12345678901234567890"
 CONFIG_USB_DEVICE_PID=0xEEEE
 CONFIG_USB_DEVICE_VID=0x1915

esp32/CMakeLists.txt

@@ -0,0 +1,4 @@
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mouthpad_esp32_ble_hid_central)

esp32/Makefile

@@ -0,0 +1,53 @@
+# ESP32 BLE HID central prototype Makefile
+
+IDF_PATH ?= $(HOME)/esp-idf
+IDF_PY ?= idf.py
+PYTHON ?= python3
+ESP32_TARGET ?= esp32s3
+ESP32_PORT ?=
+ESP32_BAUD ?= 921600
+
+# Prefer the ROM USB-Serial/JTAG interface (VID:PID 0x303a:0x1001) when a
+# device path is not provided. When pyserial is unavailable or no matching port
+# is detected we simply fall back to idf.py's own auto-detection.
+ifeq ($(strip $(ESP32_PORT)),)
+AUTO_SERIAL_JTAG_PORT := $(shell $(PYTHON) -c "import sys\ntry:\n    from serial.tools import list_ports\nexcept Exception:\n    sys.exit(0)\nports = list_ports.comports()\nfor p in ports:\n    if getattr(p, 'vid', None) == 0x303a and getattr(p, 'pid', None) == 0x1001:\n        sys.stdout.write(p.device)\n        break\nelse:\n    for p in ports:\n        desc = ((p.description or p.device) or '').lower()\n        if 'usb-serial/jtag' in desc or 'usb_serial_jtag' in desc:\n            sys.stdout.write(p.device)\n            break\n" 2>/dev/null)
+endif
+
+ifeq ($(strip $(ESP32_PORT)),)
+ESP32_PORT := $(AUTO_SERIAL_JTAG_PORT)
+ifneq ($(strip $(ESP32_PORT)),)
+$(info Auto-detected ESP32 USB-Serial/JTAG port: $(ESP32_PORT))
+endif
+endif
+
+IDF_PORT_ARG := $(if $(strip $(ESP32_PORT)),-p $(ESP32_PORT),)
+
+.PHONY: init set-target build flash monitor flash-monitor clean fullclean
+
+init:
+	. $(IDF_PATH)/export.sh && $(IDF_PY) --version
+
+set-target:
+	$(IDF_PY) set-target $(ESP32_TARGET)
+
+build: set-target
+	$(IDF_PY) build
+
+flash:
+	$(IDF_PY) $(IDF_PORT_ARG) -b $(ESP32_BAUD) flash
+
+build-flash: build
+	$(IDF_PY) $(IDF_PORT_ARG) -b $(ESP32_BAUD) flash
+
+monitor:
+	$(IDF_PY) $(IDF_PORT_ARG) monitor
+
+flash-monitor: build
+	$(IDF_PY) $(IDF_PORT_ARG) -b $(ESP32_BAUD) flash monitor
+
+clean:
+	$(IDF_PY) clean
+
+fullclean:
+	$(IDF_PY) fullclean

esp32/README.md

@@ -0,0 +1,77 @@
+# ESP32 BLE HID Central Prototype
+
+This directory hosts an ESP-IDF project that scans for BLE HID peripherals (e.g., the MouthPad mouse),
+connects to the first device discovered, and logs incoming HID reports with the received signal strength
+indicator (RSSI). It is adapted from the official `bluetooth/esp_hid_host` example in ESP-IDF; unnecessary
+USB/Bluetooth Classic handling has been trimmed so you can focus on BLE performance testing with the
+ESP32-S3 and an external antenna.
+
+## Prerequisites
+
+1. Install ESP-IDF v5.1 or later and export the environment (`. $IDF_PATH/export.sh`).
+2. Connect the ESP32-S3 board over USB and note its serial port (e.g., `/dev/cu.usbserial-0001`).
+3. Optional: adjust defaults in `sdkconfig.defaults` for scan timing, stack size, or other HID host
+   parameters mirrored from the upstream example.
+
+## Hardware
+
+- Seeed Studio XIAO ESP32-S3 dev board [[amazon](https://www.amazon.com/gp/product/B0BYSB66S5)]
+- External 2.4 GHz antenna with MHF4/IPX-to-SMA pigtail adaptor [[amazon](https://www.amazon.com/gp/product/B07R21LN5P)]
+
+Attach the pigtail to the XIAO’s on-board antenna connector. The built-in single-colour user LED on GPIO 21 provides
+status feedback (slow blink while scanning, solid on when connected, quick pulses on HID traffic).
+
+## Build, Flash, and Monitor
+
+```bash
+# Activate ESP-IDF with the pinned Python environment
+. ./env.sh
+
+# (First time only) fetch TinyUSB device stack component
+idf.py add-dependency espressif/esp_tinyusb^1.4.2
+
+# Initialise ESP-IDF for this shell
+make init
+
+# Build the firmware (defaults to target esp32s3)
+make build
+
+# Flash the device (override ESP32_PORT if the default wildcard does not match)
+ESP32_PORT=/dev/cu.usbserial-0001 make flash
+
+# Attach a serial monitor (Ctrl+] to quit)
+ESP32_PORT=/dev/cu.usbserial-0001 make monitor
+```
+
+`make init` sources `$(IDF_PATH)/export.sh` (default `~/esp-idf`) so subsequent
+targets run in the ESP-IDF environment. Override `IDF_PATH` when ESP-IDF lives
+elsewhere.
+
+### Status LED
+
+The single user LED on the XIAO ESP32-S3 (GPIO 21) behaves like the nRF build:
+- slow blink while scanning for a MouthPad
+- solid on when connected, with a quick off/on pulse whenever USB HID traffic is forwarded
+
+### Entering DFU without the BOOT button
+
+Open the TinyUSB CDC console (e.g., `screen /dev/cu.usbmodemXXXX 115200`) and send
+`dfu` followed by Enter. Close the terminal so the port is free. The firmware
+reboots, hands USB back to the ROM loader, and enumerates as the USB-Serial/JTAG
+download port. Run `idf.py flash` (or `make flash`) against that port—because the
+flasher no longer tries to reset before flashing, the ROM stays available until
+the transfer completes, after which the application restarts normally.
+
+`make flash-monitor` combines flashing and monitoring for quicker cycles. Reports are truncated to 32
+bytes for readability; adjust the helper in `main/main.c` if full reports are needed.
+
+## Expected Output
+
+Once powered, the firmware scans continuously. When a BLE HID device is detected, the logs show the peer
+address, connection events, and HID reports alongside their RSSI value. Connected reports are forwarded
+verbatim to the TinyUSB HID interface using the same descriptor and report IDs as the nRF firmware, so a
+host sees identical mouse/consumer-control behaviour. A CDC ACM interface is enumerated in parallel and
+serves as the default console (the device now appears as both a HID mouse and USB serial port). Use these
+logs to compare signal strength under different antenna setups. If you need richer diagnostics, cross-
+reference the upstream `esp_hid_host` README for optional features (battery events, Classic Bluetooth)
+that can be re-enabled here as needed.

esp32/dependencies.lock

@@ -0,0 +1,38 @@
+dependencies:
+  espressif/esp_tinyusb:
+    component_hash: 6a50305bc61c7a361da8c0833642be824e92dacb0a6001719a832a4e96e471bf
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=5.0'
+    - name: espressif/tinyusb
+      registry_url: https://components.espressif.com
+      require: public
+      version: '>=0.14.2'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 1.7.6~2
+  espressif/tinyusb:
+    component_hash: aa65639878f27a44d349044afd9c3fc134a92bd560874fdac1d836019b5c07ca
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=5.0'
+    source:
+      registry_url: https://components.espressif.com
+      type: service
+    targets:
+    - esp32s2
+    - esp32s3
+    - esp32p4
+    version: 0.18.0~4
+  idf:
+    source:
+      type: idf
+    version: 6.0.0
+direct_dependencies:
+- espressif/esp_tinyusb
+manifest_hash: 61a10bf894cb9a8962af9f2822661e2560f5364adff5dd5520c0e5f2c6ac9a84
+target: esp32s3
+version: 2.0.0

esp32/env.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Helper to activate ESP-IDF with the pinned Python 3.13 environment
+export IDF_PYTHON_ENV_PATH="$HOME/.espressif/python_env/idf6.0_py3.13_env"
+source "$HOME/esp-idf/export.sh"

esp32/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(SRCS "bootloader_trigger.c" "ble_bas.c" "leds.c" "main.c" "ble_transport.c" "usb_hid.c" "usb_cdc.c"
+                       INCLUDE_DIRS "."
+                       REQUIRES bt esp_hid nvs_flash)

esp32/main/ble_bas.c

@@ -0,0 +1,92 @@
+#include "ble_bas.h"
+
+#include "esp_log.h"
+
+#define TAG "ble_bas"
+
+static bool s_ready;
+static uint8_t s_battery_level;
+
+static inline uint8_t clamp_u8(int value)
+{
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 255) {
+        return 255;
+    }
+    return (uint8_t)value;
+}
+
+esp_err_t ble_bas_init(void)
+{
+    s_ready = false;
+    s_battery_level = 0xFF;
+    ESP_LOGI(TAG, "Battery Service helper initialised");
+    return ESP_OK;
+}
+
+void ble_bas_reset(void)
+{
+    s_ready = false;
+    s_battery_level = 0xFF;
+    ESP_LOGI(TAG, "Battery Service reset");
+}
+
+void ble_bas_handle_level(uint8_t level)
+{
+    if (level == 0xFF) {
+        ESP_LOGW(TAG, "Invalid battery level received");
+        s_ready = false;
+        s_battery_level = 0xFF;
+        return;
+    }
+
+    s_ready = true;
+    s_battery_level = level;
+    ESP_LOGI(TAG, "Battery level: %u%%", level);
+}
+
+bool ble_bas_is_ready(void)
+{
+    return s_ready;
+}
+
+uint8_t ble_bas_get_battery_level(void)
+{
+    return s_battery_level;
+}
+
+ble_bas_rgb_color_t ble_bas_get_battery_color(ble_bas_color_mode_t mode)
+{
+    ble_bas_rgb_color_t color = {0, 0, 0};
+
+    if (!s_ready || s_battery_level == 0xFF || s_battery_level > 100) {
+        color.green = 255;
+        return color;
+    }
+
+    if (mode == BLE_BAS_COLOR_MODE_DISCRETE) {
+        if (s_battery_level >= 50) {
+            color.green = 255;
+        } else if (s_battery_level >= 10) {
+            color.red = 255;
+            color.green = 255;
+        } else {
+            color.red = 255;
+        }
+    } else {
+        if (s_battery_level >= 50) {
+            color.green = 255;
+            int red = (255 * (100 - s_battery_level)) / 50;
+            color.red = clamp_u8(red);
+        } else {
+            color.red = 255;
+            int green = (255 * s_battery_level) / 50;
+            color.green = clamp_u8(green);
+        }
+    }
+
+    return color;
+}
+