de23e5199d
* Add USB camera and uhubctl support for new test suite. Also added some bug fixes * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Refactor test messages for clarity and consistency in regex tests --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
620 lines
38 KiB
Markdown
620 lines
38 KiB
Markdown
# Meshtastic Firmware - Copilot Instructions
|
||
|
||
This document provides context and guidelines for AI assistants working with the Meshtastic firmware codebase.
|
||
|
||
## Project Overview
|
||
|
||
Meshtastic is an open-source LoRa mesh networking project for long-range, low-power communication without relying on internet or cellular infrastructure. The firmware enables text messaging, location sharing, and telemetry over a decentralized mesh network. The project uses **C++17** as its language standard across all platforms.
|
||
|
||
### Supported Hardware Platforms
|
||
|
||
- **ESP32** (ESP32, ESP32-S3, ESP32-C3, ESP32-C6) - Most common platform
|
||
- **nRF52** (nRF52840, nRF52833) - Low power Nordic chips
|
||
- **RP2040/RP2350** - Raspberry Pi Pico variants
|
||
- **STM32WL** - STM32 with integrated LoRa
|
||
- **Linux/Portduino** - Native Linux builds (Raspberry Pi, etc.)
|
||
|
||
### Supported Radio Chips
|
||
|
||
- **SX1262/SX1268** - Sub-GHz LoRa (868/915 MHz regions)
|
||
- **SX1280** - 2.4 GHz LoRa
|
||
- **LR1110/LR1120/LR1121** - Wideband radios (sub-GHz and 2.4 GHz capable, but not simultaneously)
|
||
- **RF95** - Legacy RFM95 modules
|
||
- **LLCC68** - Low-cost LoRa
|
||
|
||
### MQTT Integration
|
||
|
||
MQTT provides a bridge between Meshtastic mesh networks and the internet, enabling nodes with network connectivity to share messages with remote meshes or external services.
|
||
|
||
#### Key Components
|
||
|
||
- **`src/mqtt/MQTT.cpp`** - Main MQTT client singleton, handles connection and message routing
|
||
- **`src/mqtt/ServiceEnvelope.cpp`** - Protobuf wrapper for mesh packets sent over MQTT
|
||
- **`moduleConfig.mqtt`** - MQTT module configuration
|
||
|
||
#### MQTT Topic Structure
|
||
|
||
Messages are published/subscribed using a hierarchical topic format:
|
||
|
||
```
|
||
{root}/{channel_id}/{gateway_id}
|
||
```
|
||
|
||
- `root` - Configurable prefix (default: `msh`)
|
||
- `channel_id` - Channel name/identifier
|
||
- `gateway_id` - Node ID of the publishing gateway
|
||
|
||
#### Configuration Defaults (from `Default.h`)
|
||
|
||
```cpp
|
||
#define default_mqtt_address "mqtt.meshtastic.org"
|
||
#define default_mqtt_username "meshdev"
|
||
#define default_mqtt_password "large4cats"
|
||
#define default_mqtt_root "msh"
|
||
#define default_mqtt_encryption_enabled true
|
||
#define default_mqtt_tls_enabled false
|
||
```
|
||
|
||
#### Key Concepts
|
||
|
||
- **Uplink** - Mesh packets sent TO the MQTT broker (controlled by `uplink_enabled` per channel)
|
||
- **Downlink** - MQTT messages received and injected INTO the mesh (controlled by `downlink_enabled` per channel)
|
||
- **Encryption** - When `encryption_enabled` is true, only encrypted packets are sent; plaintext JSON is disabled
|
||
- **ServiceEnvelope** - Protobuf wrapper containing packet + channel_id + gateway_id for routing
|
||
- **JSON Support** - Optional JSON encoding for integration with external systems (disabled on nRF52 by default)
|
||
|
||
#### PKI Messages
|
||
|
||
PKI (Public Key Infrastructure) messages have special handling:
|
||
|
||
- Accepted on a special "PKI" channel
|
||
- Allow encrypted DMs between nodes that discovered each other on downlink-enabled channels
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
firmware/
|
||
├── src/ # Main source code
|
||
│ ├── main.cpp # Application entry point
|
||
│ ├── mesh/ # Core mesh networking
|
||
│ │ ├── NodeDB.* # Node database management
|
||
│ │ ├── Router.* # Packet routing
|
||
│ │ ├── Channels.* # Channel management
|
||
│ │ ├── CryptoEngine.* # AES-CCM encryption
|
||
│ │ ├── *Interface.* # Radio interface implementations
|
||
│ │ ├── api/ # WiFi/Ethernet server APIs (ServerAPI, PacketAPI)
|
||
│ │ ├── http/ # HTTP server (WebServer, ContentHandler)
|
||
│ │ ├── wifi/ # WiFi support (WiFiAPClient)
|
||
│ │ ├── eth/ # Ethernet support (ethClient)
|
||
│ │ ├── udp/ # UDP multicast
|
||
│ │ ├── compression/ # Message compression (unishox2)
|
||
│ │ └── generated/ # Protobuf generated code
|
||
│ ├── modules/ # Feature modules (Position, Telemetry, etc.)
|
||
│ │ └── Telemetry/ # Telemetry subsystem
|
||
│ │ └── Sensor/ # 50+ I2C sensor drivers
|
||
│ ├── gps/ # GPS handling
|
||
│ ├── graphics/ # Display drivers and UI
|
||
│ │ └── niche/ # Specialized UIs (InkHUD e-ink framework)
|
||
│ ├── platform/ # Platform-specific code (esp32, nrf52, rp2xx0, stm32wl, portduino)
|
||
│ ├── input/ # Input device handling (InputBroker, keyboards, buttons)
|
||
│ ├── detect/ # I2C hardware auto-detection (80+ device types)
|
||
│ ├── motion/ # Accelerometer drivers (BMA423, BMI270, MPU6050, etc.)
|
||
│ ├── mqtt/ # MQTT bridge client
|
||
│ ├── power/ # Power HAL
|
||
│ ├── nimble/ # BLE via NimBLE
|
||
│ ├── buzz/ # Audio/notification (buzzer, RTTTL)
|
||
│ ├── serialization/ # JSON serialization, COBS encoding
|
||
│ ├── watchdog/ # Hardware watchdog thread
|
||
│ ├── concurrency/ # Threading utilities (OSThread, Lock)
|
||
│ ├── PowerFSM.* # Power finite state machine
|
||
│ └── Observer.h # Observer/Observable event pattern
|
||
├── variants/ # Hardware variant definitions
|
||
│ ├── esp32/ # ESP32 variants
|
||
│ ├── esp32s3/ # ESP32-S3 variants
|
||
│ ├── esp32c3/ # ESP32-C3 variants
|
||
│ ├── esp32c6/ # ESP32-C6 variants
|
||
│ ├── nrf52840/ # nRF52 variants
|
||
│ ├── rp2040/ # RP2040/RP2350 variants
|
||
│ ├── stm32/ # STM32WL variants
|
||
│ └── native/ # Linux/Portduino variants
|
||
├── protobufs/ # Protocol buffer definitions
|
||
├── boards/ # Custom PlatformIO board definitions
|
||
├── test/ # Unit tests (12 test suites)
|
||
└── bin/ # Build and utility scripts
|
||
```
|
||
|
||
## Coding Conventions
|
||
|
||
### General Style
|
||
|
||
- Follow existing code style - run `trunk fmt` before commits
|
||
- Prefer `LOG_DEBUG`, `LOG_INFO`, `LOG_WARN`, `LOG_ERROR` for logging
|
||
- Use `assert()` for invariants that should never fail
|
||
- C++17 features are available (`std::optional`, structured bindings, `if constexpr`, etc.)
|
||
|
||
### Naming Conventions
|
||
|
||
- Classes: `PascalCase` (e.g., `PositionModule`, `NodeDB`)
|
||
- Functions/Methods: `camelCase` (e.g., `sendOurPosition`, `getNodeNum`)
|
||
- Constants/Defines: `UPPER_SNAKE_CASE` (e.g., `MAX_INTERVAL`, `ONE_DAY`)
|
||
- Member variables: `camelCase` (e.g., `lastGpsSend`, `nodeDB`)
|
||
- Config defines: `USERPREFS_*` for user-configurable options
|
||
|
||
### Key Patterns
|
||
|
||
#### Module System
|
||
|
||
Modules use a three-tier class hierarchy:
|
||
|
||
1. **`MeshModule`** - Base class. Implement `wantPacket()` and `handleReceived()`. Returns `ProcessMessage::STOP` or `ProcessMessage::CONTINUE`.
|
||
2. **`SinglePortModule`** - Handles a single portnum. Simplified `wantPacket()` that checks `decoded.portnum`.
|
||
3. **`ProtobufModule<T>`** - Template for protobuf-based modules. Handles encoding/decoding automatically.
|
||
|
||
Most modules also inherit from **`OSThread`** for periodic tasks (the "mixin" pattern):
|
||
|
||
```cpp
|
||
class MyModule : public ProtobufModule<meshtastic_MyMessage>, private concurrency::OSThread
|
||
{
|
||
public:
|
||
MyModule();
|
||
|
||
protected:
|
||
virtual bool handleReceivedProtobuf(const meshtastic_MeshPacket &mp, meshtastic_MyMessage *msg) override;
|
||
virtual meshtastic_MeshPacket *allocReply() override; // Generate response packets
|
||
virtual int32_t runOnce() override; // Periodic task (returns next interval in ms)
|
||
virtual bool alterReceivedProtobuf(meshtastic_MeshPacket &mp, meshtastic_MyMessage *msg); // Modify in-flight
|
||
virtual bool wantUIFrame(); // Request a UI display frame
|
||
};
|
||
```
|
||
|
||
Modules are registered in `src/modules/Modules.cpp` guarded by `MESHTASTIC_EXCLUDE_*` flags.
|
||
|
||
#### Observer/Observable Pattern
|
||
|
||
Event-driven communication between subsystems uses `src/Observer.h`:
|
||
|
||
```cpp
|
||
// Observable emits events
|
||
Observable<const meshtastic::Status *> newStatus;
|
||
newStatus.notifyObservers(&status);
|
||
|
||
// Observer receives events via callback
|
||
CallbackObserver<MyClass, const meshtastic::Status *> statusObserver =
|
||
CallbackObserver<MyClass, const meshtastic::Status *>(this, &MyClass::handleStatusUpdate);
|
||
```
|
||
|
||
#### Configuration Access
|
||
|
||
- `config.*` - Device configuration (LoRa, position, power, etc.)
|
||
- `moduleConfig.*` - Module-specific configuration
|
||
- `channels.*` - Channel configuration and management
|
||
- `owner` - Device owner info
|
||
- `myNodeInfo` - Local node info
|
||
|
||
#### Default Values
|
||
|
||
Use the `Default` class helpers in `src/mesh/Default.h`:
|
||
|
||
- `Default::getConfiguredOrDefaultMs(configured, default)` - Returns ms, using default if configured is 0
|
||
- `Default::getConfiguredOrDefault(configured, default)` - Generic configured/default getter
|
||
- `Default::getConfiguredOrMinimumValue(configured, min)` - Enforces minimum values
|
||
- `Default::getConfiguredOrDefaultMsScaled(configured, default, numNodes)` - Scales based on network size
|
||
|
||
#### Thread Safety
|
||
|
||
- Use `concurrency::Lock` and `concurrency::LockGuard` for mutex protection
|
||
- Radio SPI access uses `SPILock`
|
||
- Prefer `OSThread` for background tasks
|
||
|
||
### Hardware Detection
|
||
|
||
`src/detect/ScanI2C` automatically enumerates 80+ I2C device types at boot including displays, sensors, RTCs, keyboards, PMUs, and touch controllers. This drives automatic initialization of the correct drivers.
|
||
|
||
### Graphics/UI System
|
||
|
||
Multiple display driver families in `src/graphics/`:
|
||
|
||
- **OLED**: SSD1306, SH1106, ST7567
|
||
- **TFT**: TFTDisplay (LovyanGFX-based)
|
||
- **E-Ink**: EInkDisplay2, EInkDynamicDisplay, EInkParallelDisplay
|
||
|
||
**InkHUD** (`src/graphics/niche/InkHUD/`) is an event-driven e-ink UI framework:
|
||
|
||
- Applet-based architecture — modular display tiles
|
||
- Read-only, static display optimized for minimal refreshes and low power
|
||
- Configured per-variant via `nicheGraphics.h`
|
||
- Separate PlatformIO config: `src/graphics/niche/InkHUD/PlatformioConfig.ini`
|
||
|
||
### Input System
|
||
|
||
`src/input/InputBroker` is the centralized input event dispatcher. Supports multiple input sources: buttons, keyboards (BBQ10, Cardputer, TCA8418), touch screens, rotary encoders, and matrix keyboards.
|
||
|
||
### Power Management
|
||
|
||
`src/PowerFSM.*` implements a finite state machine with states: `stateON`, `statePOWER`, `stateSERIAL`, `stateDARK`. Key events: `EVENT_PRESS`, `EVENT_WAKE_TIMER`, `EVENT_LOW_BATTERY`, `EVENT_RECEIVED_MSG`, `EVENT_SHUTDOWN`. Conditionally excluded with `MESHTASTIC_EXCLUDE_POWER_FSM` (falls back to `FakeFsm`).
|
||
|
||
### Motion Sensors
|
||
|
||
`src/motion/AccelerometerThread` provides background motion monitoring with automatic screen wake and double-tap button press detection. Supports 10+ accelerometer/gyroscope chips (BMA423, BMI270, MPU6050, LIS3DH, LSM6DS3, STK8XXX, QMA6100P, ICM20948, BMX160).
|
||
|
||
### Telemetry Sensor Library
|
||
|
||
`src/modules/Telemetry/Sensor/` contains 50+ I2C sensor drivers organized by category:
|
||
|
||
- **Power monitoring**: INA219/226/260/3221, MAX17048
|
||
- **Environmental**: BME280/680, SCD4X (CO₂), SEN5X (particulate)
|
||
- **Humidity/Temperature**: SHT3X/4X, AHT10, MCP9808, MLX90614
|
||
- **Light**: BH1750, TSL2561/2591, VEML7700, LTR390UV, OPT3001
|
||
- **Air quality**: PMSA003I, SFA30
|
||
- **Specialized**: CGRadSens (radiation), NAU7802 (weight scale)
|
||
|
||
### API/Networking
|
||
|
||
`src/mesh/api/` provides a template-based `ServerAPI` for client communication over WiFi (`WiFiServerAPI`) and Ethernet (`ethServerAPI`). Default port: **4403**. HTTP server in `src/mesh/http/`. JSON serialization in `src/serialization/MeshPacketSerializer`.
|
||
|
||
### Hardware Variants
|
||
|
||
Each hardware variant has:
|
||
|
||
- `variant.h` - Pin definitions and hardware capabilities
|
||
- `platformio.ini` - Build configuration
|
||
- Optional: `pins_arduino.h`, `rfswitch.h`, `nicheGraphics.h` (for InkHUD variants)
|
||
|
||
Key defines in variant.h:
|
||
|
||
```cpp
|
||
#define USE_SX1262 // Radio chip selection
|
||
#define HAS_GPS 1 // Hardware capabilities
|
||
#define HAS_SCREEN 1 // Display present
|
||
#define LORA_CS 36 // Pin assignments
|
||
#define SX126X_DIO1 14 // Radio-specific pins
|
||
```
|
||
|
||
### Protobuf Messages
|
||
|
||
- Defined in `protobufs/meshtastic/*.proto` (~32 proto files)
|
||
- Generated code in `src/mesh/generated/meshtastic/`
|
||
- Regenerate with `bin/regen-protos.sh`
|
||
- Message types prefixed with `meshtastic_`
|
||
- Nanopb `.options` files control field sizes and encoding
|
||
|
||
### Conditional Compilation
|
||
|
||
```cpp
|
||
#if !MESHTASTIC_EXCLUDE_GPS // Feature exclusion
|
||
#if !MESHTASTIC_EXCLUDE_WIFI // Network feature exclusion
|
||
#if !MESHTASTIC_EXCLUDE_BLUETOOTH // BLE exclusion
|
||
#if !MESHTASTIC_EXCLUDE_POWER_FSM // Power FSM exclusion
|
||
#ifdef ARCH_ESP32 // Architecture-specific
|
||
#ifdef ARCH_NRF52 // Nordic platform
|
||
#ifdef ARCH_RP2040 // Raspberry Pi Pico
|
||
#ifdef ARCH_PORTDUINO // Linux native
|
||
#if defined(USE_SX1262) // Radio-specific
|
||
#ifdef HAS_SCREEN // Hardware capability
|
||
#if USERPREFS_EVENT_MODE // User preferences
|
||
```
|
||
|
||
## Build System
|
||
|
||
Uses **PlatformIO** with custom scripts:
|
||
|
||
- `bin/platformio-pre.py` - Pre-build script
|
||
- `bin/platformio-custom.py` - Custom build logic, manifest generation
|
||
|
||
Build commands:
|
||
|
||
```bash
|
||
pio run -e tbeam # Build specific target
|
||
pio run -e tbeam -t upload # Build and upload
|
||
pio run -e native # Build native/Linux version
|
||
```
|
||
|
||
### Build Manifest
|
||
|
||
`bin/platformio-custom.py` emits a build manifest with metadata:
|
||
|
||
- `hasMui`, `hasInkHud` - UI capability flags (overridable via `custom_meshtastic_has_mui`, `custom_meshtastic_has_ink_hud`)
|
||
- Architecture normalization (e.g., `esp32s3` → `esp32-s3` for API compatibility)
|
||
|
||
## Common Tasks
|
||
|
||
### Adding a New Module
|
||
|
||
1. Create `src/modules/MyModule.cpp` and `.h`
|
||
2. Inherit from appropriate base class (`MeshModule`, `SinglePortModule`, or `ProtobufModule<T>`)
|
||
3. Mix in `concurrency::OSThread` if periodic work is needed
|
||
4. Register in `src/modules/Modules.cpp` guarded by `#if !MESHTASTIC_EXCLUDE_MYMODULE`
|
||
5. Add protobuf messages if needed in `protobufs/meshtastic/`
|
||
6. Add test suite in `test/test_mymodule/` if applicable
|
||
|
||
### Adding a New Hardware Variant
|
||
|
||
1. Create directory under `variants/<arch>/<name>/`
|
||
2. Add `variant.h` with pin definitions and hardware capability defines
|
||
3. Add `platformio.ini` with build config — use `extends` to reference common base (e.g., `esp32s3_base`)
|
||
4. Set `custom_meshtastic_support_level = 1` (PR builds) or `2` (merge builds)
|
||
5. For e-ink displays, add `nicheGraphics.h` for InkHUD configuration
|
||
|
||
### Adding a New Telemetry Sensor
|
||
|
||
1. Create driver in `src/modules/Telemetry/Sensor/` following existing sensor pattern
|
||
2. Register I2C address in `src/detect/ScanI2C` for auto-detection
|
||
3. Integrate with the appropriate telemetry module (Environment, Health, Power, AirQuality)
|
||
4. Add proto fields in `protobufs/meshtastic/telemetry.proto` if new data types are needed
|
||
|
||
### Modifying Configuration Defaults
|
||
|
||
- Check `src/mesh/Default.h` for default value defines
|
||
- Check `src/mesh/NodeDB.cpp` for initialization logic
|
||
- Consider `isDefaultChannel()` checks for public channel restrictions
|
||
|
||
## Important Considerations
|
||
|
||
### Traffic Management
|
||
|
||
The mesh network has limited bandwidth. When modifying broadcast intervals:
|
||
|
||
- Respect minimum intervals on default/public channels
|
||
- Use `Default::getConfiguredOrMinimumValue()` to enforce minimums
|
||
- Consider `numOnlineNodes` scaling for congestion control
|
||
|
||
### Power Management
|
||
|
||
Many devices are battery-powered:
|
||
|
||
- Use `IF_ROUTER(routerVal, normalVal)` for role-based defaults
|
||
- Check `config.power.is_power_saving` for power-saving modes
|
||
- Implement proper `sleep()` methods in radio interfaces
|
||
|
||
### Channel Security
|
||
|
||
- `channels.isDefaultChannel(index)` - Check if using default/public settings
|
||
- Default channels get stricter rate limits to prevent abuse
|
||
- Private channels may have relaxed limits
|
||
|
||
## GitHub Actions CI/CD
|
||
|
||
The project uses GitHub Actions extensively for CI/CD. Key workflows are in `.github/workflows/`:
|
||
|
||
### Core CI Workflows
|
||
|
||
- **`main_matrix.yml`** - Main CI pipeline, runs on push to `master`/`develop` and PRs
|
||
- Uses `bin/generate_ci_matrix.py` to dynamically generate build targets
|
||
- Builds all supported hardware variants
|
||
- PRs build a subset (`--level pr`) for faster feedback
|
||
|
||
- **`trunk_check.yml`** - Code quality checks on PRs
|
||
- Runs Trunk.io for linting and formatting
|
||
- Must pass before merge
|
||
|
||
- **`tests.yml`** - End-to-end and hardware tests
|
||
- Runs daily on schedule
|
||
- Includes native tests and hardware-in-the-loop testing
|
||
|
||
- **`test_native.yml`** - Native platform unit tests
|
||
- Runs `pio test -e native`
|
||
|
||
### Release Workflows
|
||
|
||
- **`release_channels.yml`** - Triggered on GitHub release publish
|
||
- Builds Docker images
|
||
- Packages for PPA (Ubuntu), OBS (openSUSE), and COPR (Fedora)
|
||
- Handles Alpha/Beta/Stable release channels
|
||
|
||
- **`nightly.yml`** - Nightly builds from develop branch
|
||
|
||
- **`docker_build.yml`** / **`docker_manifest.yml`** - Docker image builds
|
||
|
||
### Build Matrix Generation
|
||
|
||
The CI uses `bin/generate_ci_matrix.py` to dynamically select which targets to build:
|
||
|
||
```bash
|
||
# Generate full build matrix
|
||
./bin/generate_ci_matrix.py all
|
||
|
||
# Generate PR-level matrix (subset for faster builds)
|
||
./bin/generate_ci_matrix.py all --level pr
|
||
```
|
||
|
||
Variants can specify their support level in `platformio.ini`:
|
||
|
||
- `custom_meshtastic_support_level = 1` - Actively supported, built on every PR
|
||
- `custom_meshtastic_support_level = 2` - Supported, built on merge to main branches
|
||
- `board_level = extra` - Extra builds, only on full releases
|
||
|
||
### Running Workflows Locally
|
||
|
||
Most workflows can be triggered manually via `workflow_dispatch` for testing.
|
||
|
||
## Testing
|
||
|
||
### Native unit tests (C++)
|
||
|
||
Unit tests in `test/` directory with 12 test suites:
|
||
|
||
- `test_crypto/` - Cryptography
|
||
- `test_mqtt/` - MQTT integration
|
||
- `test_radio/` - Radio interface
|
||
- `test_mesh_module/` - Module framework
|
||
- `test_meshpacket_serializer/` - Packet serialization
|
||
- `test_transmit_history/` - Retransmission tracking
|
||
- `test_atak/` - ATAK integration
|
||
- `test_default/` - Default configuration
|
||
- `test_http_content_handler/` - HTTP handling
|
||
- `test_serial/` - Serial communication
|
||
|
||
Run with: `pio test -e native`
|
||
|
||
Simulation testing: `bin/test-simulator.sh`
|
||
|
||
### Hardware-in-the-loop tests (`mcp-server/tests/`)
|
||
|
||
Separate pytest suite that exercises real USB-connected Meshtastic devices. See the **MCP Server & Hardware Test Harness** section below for invocation, tier layout, and agent usage rules.
|
||
|
||
## MCP Server & Hardware Test Harness
|
||
|
||
The `mcp-server/` directory houses a firmware-aware [MCP](https://modelcontextprotocol.io/) server plus a pytest-based integration suite. AI agents that speak MCP get a well-defined tool surface for flashing, configuring, and inspecting physical Meshtastic devices — use it instead of hand-rolling `pio` or `meshtastic --port` calls where possible. `mcp-server/README.md` is the operator-facing setup doc; this section is the agent-facing usage contract.
|
||
|
||
The repo registers the server via `.mcp.json` at the repo root — Claude Code picks it up automatically once `mcp-server/.venv/` is built (`cd mcp-server && python3 -m venv .venv && .venv/bin/pip install -e '.[test]'`).
|
||
|
||
### When to use which surface
|
||
|
||
| Goal | Tool |
|
||
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||
| Find a connected device | `mcp__meshtastic__list_devices` |
|
||
| Read a live node's config/state | `mcp__meshtastic__device_info`, `list_nodes`, `get_config` |
|
||
| Mutate a device (owner, region, channels, reboot) | `set_owner`, `set_config`, `set_channel_url`, `reboot`, `shutdown`, `factory_reset` — all require `confirm=True` |
|
||
| Flash firmware to a variant | `pio_flash` (any arch) or `erase_and_flash` (ESP32 factory install) |
|
||
| Stream serial logs while debugging | `serial_open` → `serial_read` loop → `serial_close` |
|
||
| Administer `userPrefs.jsonc` build-time constants | `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest` |
|
||
| Run the regression suite | `./mcp-server/run-tests.sh` (or `/test` slash command) |
|
||
| Diagnose a specific device | `/diagnose [role]` slash command (read-only) |
|
||
| Triage a flaky test | `/repro <node-id> [count]` slash command |
|
||
|
||
**One MCP call per port at a time.** `SerialInterface` holds an exclusive OS-level lock on the serial port for its lifetime. If a `serial_*` session is open on `/dev/cu.usbmodem101`, calling `device_info` on the same port will fail fast pointing at the active session. Sequence calls: open → read/mutate → close, then next device. Never parallelize tool calls on the same port.
|
||
|
||
### MCP tool surface (43 tools)
|
||
|
||
Grouped by purpose. Full argument shapes in `mcp-server/README.md`; a few high-value signatures are called out here.
|
||
|
||
- **Discovery & metadata**: `list_devices`, `list_boards`, `get_board`
|
||
- **Build & flash**: `build`, `clean`, `pio_flash`, `erase_and_flash` (ESP32 only), `update_flash` (ESP32 OTA), `touch_1200bps`
|
||
- **Serial sessions** (long-running, 10k-line ring buffer): `serial_open`, `serial_read`, `serial_list`, `serial_close`
|
||
- **Device reads**: `device_info`, `list_nodes`
|
||
- **Device writes**: `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `send_input_event` (inject a button/key press via the firmware's InputBroker), `set_debug_log_api`; destructive/power-state writes require `confirm=True`: `reboot`, `shutdown`, `factory_reset`
|
||
- **userPrefs admin** (build-time constants, not runtime config): `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`, `userprefs_testing_profile`
|
||
- **Vendor escape hatches**: `esptool_chip_info`, `esptool_erase_flash`, `esptool_raw`, `nrfutil_dfu`, `nrfutil_raw`, `picotool_info`, `picotool_load`, `picotool_raw`
|
||
- **USB power control** (via `uhubctl`, per-port PPPS toggle): `uhubctl_list` (read-only), `uhubctl_power(action='on'|'off', confirm=True)`, `uhubctl_cycle(delay_s, confirm=True)`. Target by raw `(location, port)` or by `role` (`"nrf52"`, `"esp32s3"`); role lookup checks `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` + `_PORT_<ROLE>` env vars first, falls back to VID auto-detection.
|
||
- **Observability** (UI tier + operator ad-hoc): `capture_screen(role, ocr=True)` — grabs a USB-webcam frame of the device OLED and optionally OCRs it. Requires `mcp-server[ui]` extras (`opencv-python-headless`, `easyocr`) and `MESHTASTIC_UI_CAMERA_DEVICE_<ROLE>` env var; falls through to a 1×1 black PNG `NullBackend` when unconfigured.
|
||
|
||
`confirm=True` is a tool-level gate on top of whatever permission prompt your MCP host shows. **Don't bypass it** by asking the host to auto-approve — it exists specifically because MCP hosts sometimes remember "always allow this tool" and that's dangerous for `factory_reset`, `erase_and_flash`, `uhubctl_power(action='off')`, and `uhubctl_cycle`.
|
||
|
||
### Hardware test suite (`mcp-server/run-tests.sh`)
|
||
|
||
The wrapper auto-detects connected devices (VID → role map: `0x239A` → `nrf52`, `0x303A`/`0x10C4` → `esp32s3`), maps each role to a PlatformIO env (`nrf52` → `rak4631`, `esp32s3` → `heltec-v3`, overridable via `MESHTASTIC_MCP_ENV_<ROLE>`), then invokes pytest. Zero pre-flight config needed from the operator.
|
||
|
||
Suite tiers (collected + run in this order via `pytest_collection_modifyitems`):
|
||
|
||
1. `tests/unit/` — pure Python (boards parse, pio wrapper, userPrefs parse, testing profile, uhubctl parser). No hardware.
|
||
2. `tests/test_00_bake.py` — flashes each detected device with current `userPrefs.jsonc` merged with the session's test profile. Has its own skip-if-already-baked check comparing region + primary channel to the session profile; skips cheaply on warm devices.
|
||
3. `tests/mesh/` — multi-device mesh: bidirectional send, broadcast delivery, direct-with-ACK, mesh formation within 60s. Parametrized `[nrf52->esp32s3]` and `[esp32s3->nrf52]`. Includes `test_peer_offline_recovery` which uses uhubctl to physically power off one peer mid-conversation (requires uhubctl; skips without).
|
||
4. `tests/telemetry/` — `DEVICE_METRICS_APP` broadcast timing.
|
||
5. `tests/monitor/` — boot-log panic check.
|
||
6. `tests/recovery/` — `uhubctl` power-cycle round-trip + NVS persistence across hard reset. Requires `uhubctl` installed and a PPPS-capable hub; entire tier auto-skips otherwise.
|
||
7. `tests/ui/` — input-broker-driven screen navigation with camera + OCR evidence.
|
||
8. `tests/fleet/` — PSK seed session isolation.
|
||
9. `tests/admin/` — channel URL roundtrip, owner persistence across reboot.
|
||
10. `tests/provisioning/` — region + modem + slot bake, admin key presence, `UNSET` region blocks TX, userPrefs survive factory reset.
|
||
|
||
Invocation patterns:
|
||
|
||
```bash
|
||
./mcp-server/run-tests.sh # full suite (auto-bake-if-needed)
|
||
./mcp-server/run-tests.sh --force-bake # reflash before testing
|
||
./mcp-server/run-tests.sh --assume-baked # skip bake (caller vouches for device state)
|
||
./mcp-server/run-tests.sh tests/mesh # one tier
|
||
./mcp-server/run-tests.sh tests/mesh/test_direct_with_ack.py # one file
|
||
./mcp-server/run-tests.sh -k telemetry # name filter
|
||
```
|
||
|
||
**No hardware detected?** The wrapper auto-narrows to `tests/unit/` only and prints `detected hub : (none)` in the pre-flight header. Agents interpreting the output should call this out explicitly — a 52-test green run without hardware is qualitatively different from a 12-unit-test green run.
|
||
|
||
**Artifacts every run produces:**
|
||
|
||
- `mcp-server/tests/report.html` — self-contained pytest-html. Each test gets a `Meshtastic debug` section with the tail of firmware log + device state dump. **Open this first** on failures; it's the canonical evidence source.
|
||
- `mcp-server/tests/junit.xml` — CI-parseable.
|
||
- `mcp-server/tests/reportlog.jsonl` — pytest-reportlog stream (`$report_type` keyed JSONL). Consumed by the live TUI.
|
||
- `mcp-server/tests/fwlog.jsonl` — firmware log mirror from the `meshtastic.log.line` pubsub topic. Populated by the `_firmware_log_stream` autouse session fixture.
|
||
|
||
### Live TUI (`meshtastic-mcp-test-tui`)
|
||
|
||
A Textual-based live view that wraps `run-tests.sh`. Tails reportlog for per-test state, streams firmware logs, polls device state at startup + post-run (gated out of the active run because `hub_devices` holds exclusive port locks). Key bindings:
|
||
|
||
| Key | Action |
|
||
| --- | ------------------------------------------------------------------------------------------------------------ |
|
||
| `r` | re-run focused test (leaf → that node id; internal node → directory or `-k`) |
|
||
| `f` | filter tree by substring |
|
||
| `d` | failure detail modal (pulls `longrepr` + captured stdout from the reportlog) |
|
||
| `g` | export reproducer bundle (tar.gz with README, test_report.json, time-filtered fwlog, devices.json, env.json) |
|
||
| `l` | toggle firmware log pane |
|
||
| `x` | tool coverage modal |
|
||
| `c` | cross-run history sparkline |
|
||
| `q` | quit (SIGINT → SIGTERM → SIGKILL escalation, 5-s windows each) |
|
||
|
||
Launch:
|
||
|
||
```bash
|
||
cd mcp-server
|
||
.venv/bin/meshtastic-mcp-test-tui # full suite
|
||
.venv/bin/meshtastic-mcp-test-tui tests/mesh # args pass through to pytest
|
||
```
|
||
|
||
The plain CLI stays primary; the TUI is for operators who want a live dashboard. Both consume the same `run-tests.sh`.
|
||
|
||
### Slash commands (Claude Code + Copilot)
|
||
|
||
Three AI-assisted workflows wrap the test harness. Claude Code operators get `/test`, `/diagnose`, `/repro`; Copilot operators get `/mcp-test`, `/mcp-diagnose`, `/mcp-repro`. Bodies:
|
||
|
||
- `.claude/commands/{test,diagnose,repro}.md`
|
||
- `.github/prompts/mcp-{test,diagnose,repro}.prompt.md`
|
||
|
||
`.claude/commands/README.md` is the index.
|
||
|
||
House rules for agents running these prompts:
|
||
|
||
- **Interpret failures, don't just echo them.** Pull firmware log tails from `report.html` and classify each failure as transient / environmental / regression. Use the exact format in `.claude/commands/test.md`.
|
||
- **No destructive writes without operator approval.** Any skill that could reflash, factory-reset, or reboot a device must describe the action and stop. The operator authorizes.
|
||
- **Sequential MCP calls per port.** See above.
|
||
- **"Unknown" is a valid classification.** If evidence doesn't support a root cause, say so and list what would disambiguate. Do not invent.
|
||
|
||
### Key fixtures (test authors + agents debugging)
|
||
|
||
`mcp-server/tests/conftest.py` provides:
|
||
|
||
- **`_session_userprefs`** (autouse session) — snapshots `userPrefs.jsonc` at session start, merges the session test profile via `userprefs.merge_active(test_profile)`, restores at teardown. Four layers of safety: pytest teardown + `atexit` + sidecar file (`userPrefs.jsonc.mcp-session-bak`) + startup self-heal in `run-tests.sh`. **Do not edit `userPrefs.jsonc` from inside a test.**
|
||
- **`_firmware_log_stream`** (autouse session) — subscribes to `meshtastic.log.line` pubsub on every connected `SerialInterface` and mirrors lines to `tests/fwlog.jsonl`. Drives the TUI firmware-log pane.
|
||
- **`_debug_log_buffer`** (autouse per-test) — captures last 200 firmware log lines + device state for attachment to the pytest-html `Meshtastic debug` section on failure.
|
||
- **`hub_devices`** (session) — `dict[role, SerialInterface]` with session-long exclusive port locks. Reason the TUI's device poller is gated to startup + post-run only.
|
||
- **`baked_mesh`** — parametrized mesh-pair fixture; depends on `test_00_bake`. `pytest_generate_tests` in `conftest.py` auto-generates `[nrf52->esp32s3]` and `[esp32s3->nrf52]` variants.
|
||
- **`test_profile`** — session-scoped dict: region, primary channel, admin key, PSK seed. Derived from `MESHTASTIC_MCP_SEED` (defaults to `mcp-<user>-<host>`).
|
||
|
||
### Firmware integration points tied to the test harness
|
||
|
||
Two firmware changes exist specifically so the test harness works reliably. **Keep these in mind when touching related code.**
|
||
|
||
- **`src/mesh/StreamAPI.cpp` + `StreamAPI.h`** — `emitLogRecord` uses a dedicated `fromRadioScratchLog` + `txBufLog` pair and a `concurrency::Lock streamLock`. Before this fix, `debug_log_api_enabled=true` would tear `FromRadio` protobufs on the serial transport because `emitTxBuffer` and `emitLogRecord` shared a single scratch buffer. The conftest enables the log stream session-wide; without this fix the device would corrupt its own FromRadio replies mid-session.
|
||
- **`src/mesh/PhoneAPI.cpp`** — `ToRadio` `Heartbeat(nonce=1)` triggers `nodeInfoModule->sendOurNodeInfo(NODENUM_BROADCAST, true, 0, true)` for serial clients, mirroring the pre-existing behavior for TCP/UDP clients in `PacketAPI.cpp`. The mesh tests rely on this to force a NodeInfo broadcast right after connect so the peer discovers them before the test's first assertion.
|
||
|
||
If you're modifying `StreamAPI`, `PhoneAPI`, `NodeInfoModule`, or `userPrefs` flow, run `./mcp-server/run-tests.sh` at minimum before asking for review.
|
||
|
||
### Recovery playbooks
|
||
|
||
| Symptom | First check | Fix |
|
||
| --------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `userPrefs.jsonc` dirty after test run | `git status --porcelain userPrefs.jsonc` | If non-empty, re-run `./mcp-server/run-tests.sh` once — the pre-flight self-heal restores from sidecar. If still dirty, `git checkout userPrefs.jsonc`. |
|
||
| Port busy / wedged CP2102 on macOS | `lsof /dev/cu.usbserial-0001` | Kill the holder. USB replug if the kernel still reports busy. Often a stale `pio device monitor` or zombie `meshtastic_mcp` process. |
|
||
| nRF52 appears unresponsive | `list_devices` shows VID `0x239A` but `device_info` times out | `touch_1200bps(port=...)` drops it into the DFU bootloader → `pio_flash` re-installs. |
|
||
| Device fully wedged (Guru Meditation, frozen CDC, no DFU) | `list_devices` shows the VID but every admin call times out | `uhubctl_cycle(role="nrf52", confirm=True)` hard-power-cycles the port via USB hub PPPS. `baked_single`'s auto-recovery hook does this once automatically if uhubctl is installed. Falls back to physical replug if no PPPS hub. |
|
||
| Multiple MCP server processes | `ps aux \| grep meshtastic_mcp` shows >1 | Kill all but the one your MCP host spawned. Zombies hold ports and break tests. |
|
||
| Mesh formation fails, one side sees peer but other doesn't | `/diagnose` (or `list_nodes` on both sides) | Asymmetric NodeInfo. `test_direct_with_ack` has a heal path; `/repro` it a few times. If persistent, both devices' clocks may be out of sync with their NodeInfo cooldown. |
|
||
| "role not present on hub" in skip reasons | `list_devices` | Expected if a device is unplugged. Reconnect before re-running the tier. |
|
||
| Entire `tests/recovery/` tier skipped | `command -v uhubctl` | Expected if `uhubctl` isn't on PATH. Install via `brew install uhubctl` (macOS) or `apt install uhubctl` (Debian/Ubuntu). Also skips if no hub advertises PPPS. |
|
||
| Entire `tests/ui/` tier skipped ("firmware not baked with USERPREFS_UI_TEST_LOG") | reportlog.jsonl for the skip reason | Re-run with `--force-bake` so the UI-log macro gets compiled into the fresh firmware. First run after the Round-3 landing always re-bakes. |
|
||
| `tests/ui/` runs but captures are all 1×1 black PNGs | `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3` | Env var not set → `NullBackend`. Point a USB webcam at the heltec-v3 OLED and set the device index; `.venv/bin/python -c "import cv2; [print(i, cv2.VideoCapture(i).read()[0]) for i in range(5)]"` discovers it. |
|
||
| Tests fail only on first attempt then pass on rerun | — | State leak from a prior session. Run with `--force-bake` to reset to a known state. |
|
||
|
||
### Never do these without asking
|
||
|
||
- `factory_reset` — wipes node identity; regenerates PKI keypair. Mesh peers will reject old DMs until re-exchange. Legitimate only when the operator explicitly wants it.
|
||
- `erase_and_flash` — full chip erase; destroys all on-device state.
|
||
- `esptool_erase_flash` / `esptool_raw` write/erase — bypasses pio's safety chain.
|
||
- `set_config` on `lora.region` — changes regulatory domain; requires physical-location context the operator has and the agent doesn't.
|
||
- `reboot` / `shutdown` mid-test — breaks fixture invariants.
|
||
- `push -f`, `rebase -i`, `reset --hard`, or any history-rewriting git operation.
|
||
- Clicking computer-use tools on web links in Mail/Messages/PDFs — open URLs via the claude-in-chrome MCP so the extension's link-safety checks apply.
|
||
|
||
## Resources
|
||
|
||
- [Documentation](https://meshtastic.org/docs/)
|