Refactor test messages for clarity and consistency in regex tests

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

.claude/commands/README.md

@@ -0,0 +1,49 @@
+# Claude Code slash commands for the mcp-server test suite
+
+Three AI-assisted workflows wrapping `mcp-server/run-tests.sh` and the meshtastic MCP tools. Each one has a twin in `.github/prompts/` for Copilot users.
+
+| Slash command         | What it does                                                              | Copilot equivalent                       |
+| --------------------- | ------------------------------------------------------------------------- | ---------------------------------------- |
+| `/test [args]`        | Runs the test suite (auto-detects hardware) and interprets failures       | `.github/prompts/mcp-test.prompt.md`     |
+| `/diagnose [role]`    | Read-only device health report via the meshtastic MCP tools               | `.github/prompts/mcp-diagnose.prompt.md` |
+| `/repro <test> [n=5]` | Re-runs one test N times, diffs firmware logs between passes and failures | `.github/prompts/mcp-repro.prompt.md`    |
+
+## Why two surfaces
+
+The Claude Code commands and Copilot prompts cover the same three workflows but each speaks its host's idiom:
+
+- **Claude Code** (`/test`) uses `$ARGUMENTS` for pass-through, has direct access to Bash + all MCP tools registered in the user's settings, and runs in the terminal context.
+- **Copilot** (`/mcp-test`) runs in VS Code's agent mode; it has terminal + MCP access too but typically asks the operator to confirm inputs interactively.
+
+A contributor using either IDE gets equivalent assistance. Keep the two in sync when behavior changes — the diff of intent should be minimal.
+
+## House rules
+
+- **No destructive writes without explicit operator approval.** Skills that could reflash, factory-reset, or reboot a device must describe the action and stop — the operator authorizes.
+- **Interpret failures, don't just echo them.** The skill body should pull firmware log lines from `mcp-server/tests/report.html` (the `Meshtastic debug` section, attached by `tests/conftest.py::pytest_runtest_makereport`) and classify the failure.
+- **Keep MCP tool calls sequential per port.** SerialInterface holds an exclusive port lock; two parallel tool calls on the same port deadlock.
+- **Never speculate about root cause.** If the evidence doesn't support a classification, say "unknown" and list what you'd need to disambiguate.
+
+## Adding a new command
+
+1. Write the Claude Code version at `.claude/commands/<name>.md` with YAML frontmatter:
+
+   ```yaml
+   ---
+   description: one-line purpose (used for auto-invocation by the model)
+   argument-hint: [optional-hint]
+   ---
+   ```
+
+2. Write the Copilot equivalent at `.github/prompts/mcp-<name>.prompt.md` with:
+
+   ```yaml
+   ---
+   mode: agent
+   description: ...
+   ---
+   ```
+
+3. Add the row to the table above. Cross-link in both bodies.
+
+4. Smoke-test on Claude Code first (`/<name>` should appear in autocomplete), then in VS Code Copilot (`/mcp-<name>` in Chat).

.claude/commands/diagnose.md

@@ -0,0 +1,62 @@
+---
+description: Produce a device health report using the meshtastic MCP tools (device_info, list_nodes, get_config, short serial log capture)
+argument-hint: [role=all|nrf52|esp32s3|<port>]
+---
+
+# `/diagnose` — device health report
+
+Call the meshtastic MCP tool bundle and format a structured health report for one or all detected devices. Zero guesswork for the operator.
+
+## What to do
+
+1. **Enumerate hardware.** Call `mcp__meshtastic__list_devices(include_unknown=True)`. For each entry where `likely_meshtastic=True`, capture `port`, `vid`, `pid`, `description`.
+
+2. **Filter by `$ARGUMENTS`**:
+   - No args, `all` → every likely-meshtastic device.
+   - `nrf52` → only devices with `vid == 0x239a`.
+   - `esp32s3` → only devices with `vid == 0x303a` or `vid == 0x10c4`.
+   - A `/dev/cu.*` path → only that one port.
+   - Anything else → treat as a substring match against the `port` string.
+
+3. **For each selected device, in sequence (NOT parallel — SerialInterface holds an exclusive port lock):**
+   - `mcp__meshtastic__device_info(port=<p>)` — captures `my_node_num`, `long_name`, `short_name`, `firmware_version`, `hw_model`, `region`, `num_nodes`, `primary_channel`.
+   - `mcp__meshtastic__list_nodes(port=<p>)` — count of peers, which ones have `publicKey` set, SNR/RSSI distribution.
+   - `mcp__meshtastic__get_config(section="lora", port=<p>)` — region, preset, channel_num, tx_power, hop_limit.
+   - Optionally, if the device seems unhappy (fails to connect, `num_nodes==1` when ≥2 are plugged in, missing firmware*version), open a short firmware log window: `mcp__meshtastic__serial_open(port=<p>, env=<inferred-env>)`, wait 3s, `serial_read(session_id=<s>, max_lines=100)`, `serial_close(session_id=<s>)`. The env should be inferred from the VID map in `mcp-server/run-tests.sh` (nrf52 → rak4631, esp32s3 → heltec-v3) unless `MESHTASTIC_MCP_ENV*<ROLE>` is set.
+
+4. **Hub health** (call once, not per-device): `mcp__meshtastic__uhubctl_list()` — enumerates every USB hub the host can see. Note which hubs advertise `ppps=true` and which hub hosts each Meshtastic device (cross-reference by VID). Flag it in the report if:
+   - No hub advertises PPPS → `tests/recovery/` can't run on this setup; hard-recovery via `uhubctl_cycle` isn't available.
+   - A Meshtastic device is on a non-PPPS hub → note it; operator may want to move the device to a PPPS hub to unlock auto-recovery.
+   - `uhubctl_list` raises `ConfigError: uhubctl not found` → just say `uhubctl not installed` in the report; don't treat as a fault.
+
+5. **Render per-device report** as:
+
+   ```text
+   [nrf52 @ /dev/cu.usbmodem1101]      fw=2.7.23.bce2825, hw=RAK4631
+     owner       : Meshtastic 40eb / 40eb
+     region/band : US, channel 88, LONG_FAST
+     tx_power    : 30 dBm, hop_limit=3
+     peers       : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm)
+     primary ch  : McpTest
+     hub         : 1-1.3 port 2 (PPPS, uhubctl-controllable)
+     firmware    : no panics in last 3s; NodeInfoModule emitted 2 broadcasts
+   ```
+
+   Keep it scannable. If a field is missing or abnormal (no pubkey for a known peer, region=UNSET, num_nodes inconsistent with the hub, device on non-PPPS hub), flag it inline with a short `⚠︎ <one-line reason>`.
+
+6. **Cross-device correlation** (only when >1 device is inspected):
+   - Do both sides see each other in `nodesByNum`? If one does and the other doesn't, that's asymmetric NodeInfo — flag it.
+   - Do the LoRa configs match? (region, channel_num, modem_preset should all agree; mismatch = no mesh)
+   - Do the primary channel NAMES match? Mismatch = different PSK = no decode.
+
+7. **Suggest next actions only for specific, recognisable failure modes**:
+   - Stale PKI pubkey one-way → "run `/test tests/mesh/test_direct_with_ack.py` — the retry + nodeinfo-ping heals this in the test path."
+   - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`."
+   - Device unreachable, reachable via DFU → `touch_1200bps(port=...)` + `pio_flash`. If not even DFU responds AND the device is on a PPPS hub, escalate to `uhubctl_cycle(role=..., confirm=True)`.
+   - CP2102-wedged-driver on macOS → see the note in `run-tests.sh`.
+
+## What NOT to do
+
+- No writes. No `set_config`, no `reboot`, no `factory_reset`. This is a read-only diagnostic skill — if the operator wants to change state, they'll ask explicitly.
+- No `flash` / `erase_and_flash`. Those are separate escalations.
+- No holding SerialInterface across tool calls — open, query, close; next device. The port lock is exclusive.

.claude/commands/repro.md

@@ -0,0 +1,66 @@
+---
+description: Re-run a specific test N times in isolation to triage flakes, diff firmware logs between passes and failures
+argument-hint: <test-node-id> [count=5]
+---
+
+# `/repro` — flakiness triage for one test
+
+Re-run a single pytest node ID N times in isolation, track pass rate, and surface what's _different_ in the firmware logs between the passing attempts and the failing ones. Turns "it's flaky, I guess" into "it fails when X, passes when Y."
+
+## What to do
+
+1. **Parse `$ARGUMENTS`**: first token is the pytest node id (e.g. `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[nrf52->esp32s3]`); second token is an integer count (default `5`, cap at `20`). If the first token doesn't look like a test path (no `::` and no `tests/` prefix), treat the whole `$ARGUMENTS` as a `-k` filter instead.
+
+2. **Sanity-check the hub first** (so we're not measuring "nothing plugged in" N times): call `mcp__meshtastic__list_devices`. If the test name contains `nrf52` or `esp32s3` and the matching VID isn't present, stop and report — re-running won't help.
+
+3. **Loop N times**. For each iteration:
+
+   ```bash
+   ./mcp-server/run-tests.sh <test-id> --tb=short -p no:cacheprovider
+   ```
+
+   Capture: exit code, duration, and (on failure) the `Meshtastic debug` firmware log section from `mcp-server/tests/report.html`. `-p no:cacheprovider` suppresses pytest's `.pytest_cache` writes so iterations don't influence each other.
+
+4. **Track a small structured tally**:
+
+   ```text
+   attempt 1: PASS (42s)
+   attempt 2: FAIL (128s)  ← firmware log 200-line tail captured
+   attempt 3: PASS (39s)
+   attempt 4: FAIL (121s)
+   attempt 5: PASS (41s)
+   --------------------------------------
+   pass rate: 3/5 (60%)   |   mean duration: 74s
+   ```
+
+5. **On mixed outcomes**: diff the firmware log tails between a representative passing attempt and a representative failing attempt. Focus on:
+   - Error-level lines only present in failures (`PKI_UNKNOWN_PUBKEY`, `Alloc an err=`, `Skip send`, `No suitable channel`)
+   - Timing around the assertion event — did a broadcast go out, was there an ACK, did NAK fire?
+   - Device state fields that changed (nodesByNum entries, region/preset, channel_num)
+
+   Surface the top 3 differences as a "passes when / fails when" table. Don't dump full logs — pull specific lines with uptime timestamps.
+
+6. **Classify the flake** into one of:
+   - **LoRa airtime collision** → pass rate improves with fewer concurrent transmitters; propose a `time.sleep` gap or retry bump in the test body.
+   - **PKI key staleness** → fails on first attempt, passes after self-heal; existing retry loop in `test_direct_with_ack.py` handles this.
+   - **NodeInfo cooldown** → `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs `broadcast_nodeinfo_ping()` warmup.
+   - **Hardware-specific** (one direction fails, other passes; one device's firmware is older; driver wedged) → specific recovery pointer. For a device that's wedged past `touch_1200bps`, the next escalation is `uhubctl_cycle(role=..., confirm=True)` to hard-power-cycle its hub port (requires `uhubctl` installed).
+   - **Device went dark mid-run** → fails from some attempt onward, never recovers, firmware log stops arriving. Almost always hardware: a Guru crash + frozen CDC. Hard-power-cycle via `uhubctl_cycle(role=..., confirm=True)` before the next iteration; if that also fails, escalate to replug.
+   - **Genuinely unknown** → say so; don't invent a root cause.
+
+7. **Report back** with:
+   - Pass rate and mean duration.
+   - Classification + evidence (the specific log lines that support it).
+   - A suggested next step (re-run with specific args, open `/diagnose`, edit a specific test file, nothing).
+
+## Examples
+
+- `/repro tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[esp32s3->nrf52] 10` — runs 10 times, diffs firmware logs.
+- `/repro broadcast_delivers` — no `::`, no `tests/`, so interpreted as `-k broadcast_delivers`; runs every matching test the default 5 times.
+- `/repro tests/telemetry/test_device_telemetry_broadcast.py 3` — shorter run for a slow test.
+
+## Constraints
+
+- Don't exceed `count=20` per invocation — airtime and USB wear add up. If the user asks for 50, negotiate down.
+- Don't rebuild firmware as part of triage; flakes that only reproduce under different firmware belong in a separate session.
+- If the FIRST attempt fails AND the rest all pass, that's a classic "state leak from a prior test" → say so and suggest running with `--force-bake` or starting from a clean state rather than chasing the first failure.

.claude/commands/test.md

@@ -0,0 +1,47 @@
+---
+description: Run the mcp-server test suite (auto-detects devices) and interpret the results
+argument-hint: [pytest-args]
+---
+
+# `/test` — mcp-server test runner with interpretation
+
+Run `mcp-server/run-tests.sh` and make sense of the output so the operator doesn't have to.
+
+## What to do
+
+1. **Invoke the wrapper.** From the firmware repo root, run:
+
+   ```bash
+   ./mcp-server/run-tests.sh $ARGUMENTS
+   ```
+
+   The wrapper auto-detects connected Meshtastic devices, maps each to its PlatformIO env, exports the required `MESHTASTIC_MCP_ENV_*` env vars, and invokes pytest. If the user passed no arguments, the wrapper supplies a sensible default set (`tests/ --html=tests/report.html --self-contained-html --junitxml=tests/junit.xml -v --tb=short`). A `--report-log=tests/reportlog.jsonl` arg is always appended (unless the operator passed their own). `--assume-baked` is deliberately NOT in the defaults — `test_00_bake.py` has its own skip-if-already-baked check and runs the ~8 s verification by default. Operators can opt into the fast path with `--assume-baked`, or force a reflash with `--force-bake`.
+
+2. **Read the pre-flight header.** First ~6 lines print the detected hub (role → port → env). If that line reads `detected hub : (none)`, the wrapper will narrow to `tests/unit` only — say so explicitly in your summary so the operator knows hardware tiers were skipped.
+
+3. **On pass**: one-line summary of the form `N passed, M skipped in <duration>`. Don't enumerate the test names — the user can read those. Do mention any SKIPPED tests and name the cause:
+   - `"role not present on hub"` → device unplugged; operator knows to reconnect.
+   - `"firmware not baked with USERPREFS_UI_TEST_LOG"` → tests/ui skipped because the macro isn't in firmware yet; suggest `--force-bake`.
+   - `"uhubctl not installed"` → tests/recovery + peer-offline skipped; suggest `brew install uhubctl` / `apt install uhubctl`.
+   - `"no PPPS-capable hubs detected"` → tests/recovery skipped because the hub doesn't support per-port power; the tier will never run on that setup.
+   - `"opencv-python-headless is not installed"` → tests/ui auto-deselected by run-tests.sh; suggest `pip install -e 'mcp-server/.[ui]'`.
+
+4. **On failure**: for every FAILED test, open `mcp-server/tests/report.html` and extract the `Meshtastic debug` section for that test. pytest-html embeds the firmware log stream + device state dump there; the 200-line firmware log tail is usually enough to explain the failure. Summarise: which test, one-line assertion message, the firmware log lines that matter (things like `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`). For UI-tier failures also glance at `mcp-server/tests/ui_captures/<session>/<test>/transcript.md` — it records each step's frame + OCR.
+
+5. **Classify the failure** as one of:
+   - **Transient/flake**: LoRa collision, timing-sensitive assertion, first-attempt NAK + successful retry pattern. Propose `/repro <test_node_id>` to confirm.
+   - **Environmental**: device unreachable, port busy, CP2102 driver wedged. Suggest the specific recovery in escalation order: (a) replug USB, (b) `touch_1200bps(port=...)` + `pio_flash` for nRF52 DFU, (c) `uhubctl_cycle(role="nrf52", confirm=True)` when a device is fully wedged past DFU (needs `uhubctl` installed — `baked_single`'s auto-recovery hook does this once automatically). Also check `git status userPrefs.jsonc`.
+   - **Regression**: same assertion fails repeatedly, firmware log shows a new/unusual error. Surface the diff between expected and observed, identify the module likely responsible.
+
+6. **Never run destructive recovery automatically.** If a failure looks like it needs a reflash, factory*reset, `uhubctl_cycle`, or USB replug, \_describe what to do* — don't execute. The operator decides.
+
+## Arguments handling
+
+- No args → wrapper's defaults (full suite).
+- `$ARGUMENTS` passed verbatim to the wrapper, which passes them to pytest.
+- Common operator invocations: `/test tests/mesh`, `/test tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip`, `/test --force-bake`, `/test -k telemetry`.
+
+## Side-effects to mention in summary
+
+- The session fixture snapshots `userPrefs.jsonc` at session start and restores at teardown (plus on `atexit`). After a clean run, `git status userPrefs.jsonc` should be empty. If the wrapper's pre-flight printed a warning about a stale sidecar, call that out — means a prior session crashed.
+- `mcp-server/tests/report.html` and `junit.xml` are regenerated on every run; the HTML is self-contained (shareable).

.github/actions/setup-base/action.yml

@@ -8,8 +8,6 @@ runs:
       uses: actions/checkout@v6
       with:
         submodules: recursive
-        ref: ${{github.event.pull_request.head.ref}}
-        repository: ${{github.event.pull_request.head.repo.full_name}}
 
     - name: Install dependencies
       shell: bash

.github/copilot-instructions.md

@@ -4,11 +4,11 @@ This document provides context and guidelines for AI assistants working with the
 
 ## 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.
+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) - Most common platform
+- **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
@@ -80,21 +80,46 @@ firmware/
 │   │   ├── 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
-│   ├── platform/          # Platform-specific code
-│   ├── input/             # Input device handling
-│   └── concurrency/       # Threading utilities
+│   │   └── 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
-│   ├── nrf52/            # nRF52 variants
-│   └── rp2xxx/           # RP2040/RP2350 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
 ```
 
@@ -105,6 +130,7 @@ firmware/
 - 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
 
@@ -118,70 +144,151 @@ firmware/
 
 #### Module System
 
-Modules inherit from `MeshModule` or `ProtobufModule<T>` and implement:
+Modules use a three-tier class hierarchy:
 
-- `handleReceivedProtobuf()` - Process incoming packets
-- `allocReply()` - Generate response packets
-- `runOnce()` - Periodic task execution (returns next run interval in ms)
+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>
+class MyModule : public ProtobufModule<meshtastic_MyMessage>, private concurrency::OSThread
 {
+  public:
+    MyModule();
+
   protected:
     virtual bool handleReceivedProtobuf(const meshtastic_MeshPacket &mp, meshtastic_MyMessage *msg) override;
-    virtual int32_t runOnce() 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` for mutex protection
+- 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`
+- 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`
-- Generated code in `src/mesh/generated/`
+- 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
@@ -192,7 +299,7 @@ Key defines in variant.h:
 Uses **PlatformIO** with custom scripts:
 
 - `bin/platformio-pre.py` - Pre-build script
-- `bin/platformio-custom.py` - Custom build logic
+- `bin/platformio-custom.py` - Custom build logic, manifest generation
 
 Build commands:
 
@@ -202,21 +309,38 @@ 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
-3. Register in `src/modules/Modules.cpp`
-4. Add protobuf messages if needed in `protobufs/`
+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
-3. Add `platformio.ini` with build config
-4. Reference common configs with `extends`
+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
 
@@ -305,9 +429,190 @@ Most workflows can be triggered manually via `workflow_dispatch` for testing.
 
 ## Testing
 
-- Unit tests in `test/` directory
-- Run with `pio test -e native`
-- Use `bin/test-simulator.sh` for simulation 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
 

.github/prompts/mcp-diagnose.prompt.md

@@ -0,0 +1,64 @@
+---
+mode: agent
+description: Device health report via the meshtastic MCP tools (Copilot equivalent of the Claude Code /diagnose slash command)
+---
+
+# `/mcp-diagnose` — device health report
+
+Equivalent of `.claude/commands/diagnose.md`. Use when the operator asks to "check the devices", "what's the mesh looking like", "is nrf52 alive", etc.
+
+This prompt assumes the meshtastic MCP server is registered with your VS Code Copilot agent. If it isn't, fall back to running `./mcp-server/run-tests.sh tests/unit` plus a short `device_info` script via the terminal.
+
+## What to do
+
+1. **Enumerate hardware** via the `list_devices` MCP tool (with `include_unknown=True`). For each entry where `likely_meshtastic=True`, capture `port`, `vid`, `pid`, `description`.
+
+2. **Apply the operator's filter** (if any):
+   - No filter → every likely-meshtastic device.
+   - `nrf52` → `vid == 0x239a`
+   - `esp32s3` → `vid == 0x303a` or `vid == 0x10c4`
+   - A `/dev/cu.*` path → only that port.
+   - Anything else → substring match on port.
+
+3. **For each selected device, in sequence (don't parallelize — SerialInterface holds an exclusive port lock):**
+   - `device_info(port=<p>)` → `my_node_num`, `long_name`, `short_name`, `firmware_version`, `hw_model`, `region`, `num_nodes`, `primary_channel`
+   - `list_nodes(port=<p>)` → peer count, which peers have `publicKey`, SNR/RSSI distribution
+   - `get_config(section="lora", port=<p>)` → region, preset, channel_num, tx_power, hop_limit
+   - If anything looks off (can't connect, `num_nodes` wrong, missing `firmware_version`), open a short firmware-log window: `serial_open(port=<p>, env=<inferred>)`, wait 3 seconds, `serial_read(session_id, max_lines=100)`, `serial_close(session_id)`. Infer env from VID (0x239a → `rak4631`, 0x303a/0x10c4 → `heltec-v3`) unless an `MESHTASTIC_MCP_ENV_<ROLE>` env var overrides it.
+
+4. **Hub health** (call once, not per-device): `uhubctl_list()` — enumerates every USB hub the host sees. Cross-reference each Meshtastic device's VID to find which hub + port it's on. Flag in the report if:
+   - No hub advertises `ppps=true` → `tests/recovery/` can't run; hard-recovery via `uhubctl_cycle` isn't available.
+   - A Meshtastic device is on a non-PPPS hub → note it; moving to a PPPS hub unlocks auto-recovery.
+   - `uhubctl_list` raises `ConfigError: uhubctl not found` → report as "uhubctl not installed"; don't treat as a device fault.
+
+5. **Render per-device report** as a compact block:
+
+   ```text
+   [nrf52 @ /dev/cu.usbmodem1101]      fw=2.7.23.bce2825, hw=RAK4631
+     owner       : Meshtastic 40eb / 40eb
+     region/band : US, channel 88, LONG_FAST
+     tx_power    : 30 dBm, hop_limit=3
+     peers       : 1 (esp32s3 0x433c2428, pubkey ✓, SNR 6.0 / RSSI -24 dBm)
+     primary ch  : McpTest
+     hub         : 1-1.3 port 2 (PPPS, uhubctl-controllable)
+     firmware    : no panics in last 3s
+   ```
+
+   Flag abnormalities inline with `⚠︎ <short reason>` — missing pubkey on a known peer, region UNSET, mismatched channel name, device on non-PPPS hub, etc.
+
+6. **Cross-device correlation** (when >1 device selected):
+   - Do both see each other in `nodesByNum`?
+   - Do `region`, `channel_num`, `modem_preset` match across devices?
+   - Do the primary channel names match? (Different name → different PSK → no decode.)
+
+7. **Suggest next steps only for recognizable failure modes**, never speculatively:
+   - Stale PKI one-way → "`/mcp-test tests/mesh/test_direct_with_ack.py` — the test's retry+nodeinfo-ping heals this."
+   - Region mismatch → "re-bake one side via `./mcp-server/run-tests.sh --force-bake`."
+   - Device unreachable, DFU reachable → `touch_1200bps(port=...)` + `pio_flash`. If not even DFU responds and the device is on a PPPS hub, escalate to `uhubctl_cycle(role=..., confirm=True)`.
+   - CP2102-wedged-driver on macOS → see `run-tests.sh` notes.
+
+## Hard constraints
+
+- **Read-only.** No `set_config`, no `reboot`, no `factory_reset`, no `flash`. If the operator wants mutation, they'll escalate explicitly.
+- **Open/query/close per device.** Never hold multiple SerialInterfaces to the same port. The port lock is exclusive.
+- **Don't infer env beyond the VID map** — if the operator has an unusual board, ask them which env to use rather than guessing.

.github/prompts/mcp-repro.prompt.md

@@ -0,0 +1,68 @@
+---
+mode: agent
+description: Re-run a specific test N times to triage flakes; diff firmware logs between passes and failures (Copilot equivalent of the Claude Code /repro slash command)
+---
+
+# `/mcp-repro` — flakiness triage for one test
+
+Equivalent of `.claude/commands/repro.md`. Use when the operator says "that one test is flaky — dig in", "repro the direct_with_ack failure", "why does X sometimes fail?".
+
+## What to do
+
+1. **Parse the operator's input** into two pieces:
+   - **Test identifier** — either a pytest node id (has `::` or starts with `tests/`) or a `-k`-style filter (plain substring like `direct_with_ack`).
+   - **Count** — integer, default `5`, cap at `20`. If the operator asks for 50, negotiate down and explain (airtime + USB wear).
+
+2. **Sanity-check the hub** via the `list_devices` MCP tool. If the test name references `nrf52` or `esp32s3` and the matching VID isn't present, stop and report — re-running won't help.
+
+3. **Loop** N times. Each iteration:
+
+   ```bash
+   ./mcp-server/run-tests.sh <test-id> --tb=short -p no:cacheprovider
+   ```
+
+   `-p no:cacheprovider` keeps pytest from caching anything between iterations. Capture: exit code, duration, and (on failure) the `Meshtastic debug` firmware-log section from `mcp-server/tests/report.html`.
+
+4. **Tally** results as you go:
+
+   ```text
+   attempt 1: PASS (42s)
+   attempt 2: FAIL (128s)    ← fw log captured
+   attempt 3: PASS (39s)
+   attempt 4: FAIL (121s)
+   attempt 5: PASS (41s)
+   --------------------------------------------------
+   pass rate: 3/5 (60%)  |  mean duration: 74s
+   ```
+
+5. **On mixed outcomes, diff the firmware logs** between one representative pass and one representative fail. Focus on:
+   - Error-level lines present only in failures (`PKI_UNKNOWN_PUBKEY`, `Alloc an err=`, `Skip send`, `No suitable channel`, `NAK`)
+   - Timing around the assertion point (broadcast sent? ACK received? retry fired?)
+   - Device-state fields that changed between attempts
+
+   Surface the top 3 differences as a compact "passes when / fails when" table with uptime timestamps. Don't dump full logs.
+
+6. **Classify** the flake into one of:
+   - **LoRa airtime collision** — pass rate improves with fewer concurrent transmitters. Suggest a `time.sleep` gap or retry bump in the test body.
+   - **PKI key staleness** — first attempt fails, subsequent ones pass; existing retry-loop pattern in `test_direct_with_ack.py` is the fix.
+   - **NodeInfo cooldown** — `Skip send NodeInfo since we sent it <600s ago` in fail-only logs; needs a `broadcast_nodeinfo_ping()` warmup.
+   - **Hardware-specific** — one direction consistently fails, firmware versions differ, CP2102 driver wedged, etc. For a device wedged past `touch_1200bps`, recommend `uhubctl_cycle(role=..., confirm=True)` to hard-power-cycle its hub port (requires `uhubctl` installed).
+   - **Device went dark mid-run** — fails from some iteration onward and never recovers; firmware log stops arriving. Almost always a Guru crash with frozen CDC. Recommend `uhubctl_cycle` before the next iteration; escalate to replug if that also fails.
+   - **Unknown** — say so. Don't invent a root cause.
+
+7. **Report back** with:
+   - Pass rate + mean duration.
+   - Classification + the specific log evidence for it.
+   - A concrete next step (tighter assertion, more retries, open `/mcp-diagnose`, file a bug, nothing).
+
+## Examples
+
+- `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip[esp32s3->nrf52] 10` — 10 runs of that parametrized case.
+- `broadcast_delivers` — no `::`, no `tests/`; treat as `-k broadcast_delivers`; runs every match 5 times.
+- `tests/telemetry/test_device_telemetry_broadcast.py 3` — shorter count for a slow test.
+
+## Notes
+
+- If the FIRST attempt fails and the rest pass, that's a state-leak signature — suggest starting from `--force-bake` or a clean device state rather than chasing the first-failure firmware logs.
+- If ALL N fail, this isn't a flake — it's a regression. Say so, stop iterating, escalate to `/mcp-test` for full-suite context.
+- Don't rebuild firmware during triage. Flakes that only reproduce under different firmware belong in a separate session with a plan.

.github/prompts/mcp-test.prompt.md

@@ -0,0 +1,57 @@
+---
+mode: agent
+description: Run the mcp-server test suite and interpret results (Copilot equivalent of the Claude Code /test slash command)
+---
+
+# `/mcp-test` — mcp-server test runner with interpretation
+
+Equivalent of the Claude Code `/test` slash command in `.claude/commands/test.md`. Use this when the operator asks you to "run the tests", "check the mcp test suite", "run the mesh tests", etc.
+
+## What to do
+
+1. **Invoke the wrapper** from the firmware repo root:
+
+   ```bash
+   ./mcp-server/run-tests.sh [pytest-args]
+   ```
+
+   If the operator specified a subset (e.g. "just the mesh tests"), pass it through as `tests/mesh` or a pytest `-k filter`. If they said nothing, use the wrapper's defaults (full suite with pytest-html report).
+
+   The wrapper auto-detects connected Meshtastic devices, maps each to its PlatformIO env, exports the required env vars, and invokes pytest. Zero pre-flight config needed from the operator.
+
+2. **Read the pre-flight header** (first few lines of wrapper output). The `detected hub :` line lists role → port → env mappings. If it reads `(none)`, the wrapper narrowed to `tests/unit` only — call that out explicitly so the operator knows hardware tiers were skipped.
+
+3. **On pass**: one-line summary like `N passed, M skipped in <duration>`. Don't enumerate test names. DO mention any non-placeholder SKIPs and name the cause:
+   - `"role not present on hub"` → device unplugged; operator should reconnect.
+   - `"firmware not baked with USERPREFS_UI_TEST_LOG"` → tests/ui skipped; the UI-log compile macro isn't in the baked firmware. Suggest `--force-bake`.
+   - `"uhubctl not installed"` → tests/recovery + `test_peer_offline_recovery` skipped. Suggest `brew install uhubctl` / `apt install uhubctl`.
+   - `"no PPPS-capable hubs detected"` → tests/recovery skipped because the attached hub doesn't support per-port power switching; won't run on that setup.
+   - `"opencv-python-headless is not installed"` → tests/ui auto-deselected by `run-tests.sh`. Suggest `pip install -e 'mcp-server/.[ui]'`.
+
+4. **On failure**: open `mcp-server/tests/report.html` (pytest-html output, self-contained) and extract the `Meshtastic debug` section for each failed test. That section includes a firmware log stream (last 200 lines) and device state dump. For each failure, summarise:
+   - test name
+   - one-line assertion message
+   - the specific firmware log lines that explain why (look for `PKI_UNKNOWN_PUBKEY`, `Skip send NodeInfo`, `Error=`, `Guru Meditation`, `assertion failed`, `No suitable channel`)
+   - for UI-tier failures also check `mcp-server/tests/ui_captures/<session>/<test>/transcript.md` (per-step frame + OCR)
+
+5. **Classify each failure** as one of:
+   - **Transient flake** — LoRa collision, first-attempt NAK with self-heal pattern, timing-sensitive assertion. Suggest `/mcp-repro <test-id>` to confirm.
+   - **Environmental** — device unreachable, port busy, CP2102 driver wedged on macOS. Suggest recovery in escalation order: (a) replug USB, (b) `touch_1200bps` + `pio_flash` for nRF52 DFU, (c) `uhubctl_cycle(role=..., confirm=True)` for a device wedged past DFU (needs `uhubctl` installed; `baked_single` does this once automatically when available). Also check `git status userPrefs.jsonc`.
+   - **Regression** — same assertion fails repeatedly on re-runs, firmware log shows novel errors. Identify the firmware module likely responsible.
+
+6. **Do NOT run destructive recovery automatically**. If a failure looks like it needs a reflash, factory*reset, `uhubctl_cycle`, or replug — \_describe the steps* and let the operator decide. Never burn airtime or flash cycles without approval.
+
+## Arguments convention
+
+Operators generally invoke this prompt either with no arguments (full suite) or with a specific subset. Examples:
+
+- `tests/mesh` — one tier
+- `tests/mesh/test_direct_with_ack.py::test_direct_with_ack_roundtrip` — one test
+- `--force-bake` — reflash devices first
+- `-k telemetry` — name-filter
+
+## Side-effects to confirm in your summary
+
+- `userPrefs.jsonc` should be clean after a successful run. The session fixture in `mcp-server/tests/conftest.py` (`_session_userprefs`) snapshots and restores. Check `git status --porcelain userPrefs.jsonc` and report if it's non-empty.
+- `mcp-server/tests/report.html` and `junit.xml` regenerate on every run.
+- The wrapper prints a warning if a `.mcp-session-bak` sidecar was left over from a crashed prior session and auto-restores from it — mention that if it happened.

.github/prompts/new-module.prompt.md

@@ -0,0 +1,138 @@
+# New Meshtastic Module
+
+Guide for developing a new Meshtastic firmware module.
+
+## Module Hierarchy
+
+Choose the appropriate base class:
+
+1. **`MeshModule`** — Raw base class. Override `wantPacket()` and `handleReceived()`. Returns `ProcessMessage::STOP` or `ProcessMessage::CONTINUE`.
+2. **`SinglePortModule`** — Handles a single `meshtastic_PortNum`. Constructor takes `(name, portNum)`. Simplified `wantPacket()` checking `decoded.portnum`. Use `allocDataPacket()` to create outgoing packets.
+3. **`ProtobufModule<T>`** — Template for protobuf-encoded modules. Constructor takes `(name, portNum, fields)`. Override `handleReceivedProtobuf()`. Use `allocDataProtobuf(payload)` to create outgoing packets.
+
+Most modules also mix in `concurrency::OSThread` for periodic background tasks.
+
+## Implementation Pattern
+
+```cpp
+// src/modules/MyModule.h
+#pragma once
+#include "ProtobufModule.h"
+#include "concurrency/OSThread.h"
+
+class MyModule : public ProtobufModule<meshtastic_MyMessage>, private concurrency::OSThread
+{
+  public:
+    MyModule();
+
+  protected:
+    // Process incoming protobuf packet. Return true to stop further processing.
+    virtual bool handleReceivedProtobuf(const meshtastic_MeshPacket &mp, meshtastic_MyMessage *msg) override;
+
+    // Generate response packet (optional)
+    virtual meshtastic_MeshPacket *allocReply() override;
+
+    // Periodic task — return next run interval in ms, or disable()
+    virtual int32_t runOnce() override;
+
+    // Modify packet in-flight before delivery (optional)
+    virtual bool alterReceivedProtobuf(meshtastic_MeshPacket &mp, meshtastic_MyMessage *msg);
+
+    // Request a UI display frame (optional)
+    virtual bool wantUIFrame();
+};
+```
+
+## Registration
+
+Register in `src/modules/Modules.cpp` inside `setupModules()`:
+
+```cpp
+#if !MESHTASTIC_EXCLUDE_MYMODULE
+    new MyModule();
+#endif
+```
+
+If other code needs to reference the module instance:
+
+```cpp
+#if !MESHTASTIC_EXCLUDE_MYMODULE
+    myModule = new MyModule();
+#endif
+```
+
+And declare the global in the header:
+
+```cpp
+extern MyModule *myModule;
+```
+
+Some modules also conditionally instantiate based on `moduleConfig`:
+
+```cpp
+#if !MESHTASTIC_EXCLUDE_MYMODULE
+    if (moduleConfig.has_my_module && moduleConfig.my_module.enabled) {
+        new MyModule();
+    }
+#endif
+```
+
+## Conditional Compilation
+
+Add a `MESHTASTIC_EXCLUDE_MYMODULE` guard. This allows the module to be excluded from constrained builds. The flag name must follow the pattern: `MESHTASTIC_EXCLUDE_` + uppercase module name.
+
+## Protobuf Messages (if needed)
+
+1. Define messages in `protobufs/meshtastic/` (e.g., `mymodule.proto`)
+2. Add a `.options` file for nanopb field size constraints
+3. Regenerate with `bin/regen-protos.sh`
+4. Generated code appears in `src/mesh/generated/meshtastic/`
+5. Assign a `meshtastic_PortNum` if the module uses a new port number
+
+## Timing and Defaults
+
+Use `Default` class helpers for configurable intervals:
+
+```cpp
+int32_t MyModule::runOnce()
+{
+    uint32_t interval = Default::getConfiguredOrDefaultMs(moduleConfig.my_module.update_interval,
+                                                          default_my_module_interval);
+    // ... do work ...
+    return interval;
+}
+```
+
+On public/default channels, enforce minimums with `Default::getConfiguredOrMinimumValue()`.
+
+## Observer Pattern
+
+Subscribe to system events:
+
+```cpp
+CallbackObserver<MyModule, const meshtastic::Status *> statusObserver =
+    CallbackObserver<MyModule, const meshtastic::Status *>(this, &MyModule::handleStatusUpdate);
+```
+
+## Testing
+
+Add test suite in `test/test_mymodule/`:
+
+```
+test/
+└── test_mymodule/
+    └── test_main.cpp
+```
+
+Run with: `pio test -e native`
+
+## Checklist
+
+- [ ] Header and implementation files in `src/modules/`
+- [ ] Inherit from appropriate base class (MeshModule / SinglePortModule / ProtobufModule)
+- [ ] Mix in OSThread if periodic work is needed
+- [ ] Register in `src/modules/Modules.cpp` with `MESHTASTIC_EXCLUDE_` guard
+- [ ] Add protobuf definitions if needed (`protobufs/meshtastic/`)
+- [ ] Use `Default::getConfiguredOrDefaultMs()` for timing
+- [ ] Respect bandwidth limits on public channels
+- [ ] Add test suite in `test/`

.github/prompts/new-sensor.prompt.md

@@ -0,0 +1,149 @@
+# New Telemetry Sensor
+
+Guide for adding a new I2C telemetry sensor driver to Meshtastic firmware.
+
+## Overview
+
+Telemetry sensors live in `src/modules/Telemetry/Sensor/`. There are 50+ existing drivers organized by measurement type. Each sensor integrates with one of the telemetry modules:
+
+- **EnvironmentTelemetryModule** — Temperature, humidity, pressure, gas, light
+- **AirQualityTelemetryModule** — Particulate matter, VOCs
+- **PowerTelemetryModule** — Voltage, current, power monitoring
+- **HealthTelemetryModule** — Heart rate, SpO2, body temperature
+
+## Sensor Driver Pattern
+
+Each sensor has a `.h` and `.cpp` file pair following this pattern:
+
+```cpp
+// src/modules/Telemetry/Sensor/MySensor.h
+#pragma once
+#include "TelemetrySensor.h"
+#include <MySensorLibrary.h>  // Arduino/PlatformIO library
+
+class MySensor : virtual public TelemetrySensor
+{
+  private:
+    MySensorLibrary sensor;
+
+  public:
+    MySensor() : TelemetrySensor(meshtastic_TelemetrySensorType_MY_SENSOR, "MySensor") {}
+
+    // Initialize sensor hardware. Return true on success.
+    virtual void setup() override;
+
+    // Read sensor data into the telemetry protobuf. Return true on success.
+    virtual bool getMetrics(meshtastic_Telemetry *measurement) override;
+};
+```
+
+```cpp
+// src/modules/Telemetry/Sensor/MySensor.cpp
+#include "MySensor.h"
+#include "TelemetrySensor.h"
+
+void MySensor::setup()
+{
+    sensor.begin();
+    // Configure sensor parameters...
+}
+
+bool MySensor::getMetrics(meshtastic_Telemetry *measurement)
+{
+    // Read from hardware
+    float value = sensor.readValue();
+
+    // Populate the appropriate protobuf variant
+    measurement->variant.environment_metrics.temperature = value;
+    // ... other fields ...
+
+    return true;
+}
+```
+
+## I2C Address Registration
+
+Register the sensor's I2C address(es) in `src/detect/ScanI2C` so it's auto-detected at boot:
+
+1. Add a `DeviceType` enum entry in `src/detect/ScanI2C.h`
+2. Add the I2C address mapping in `src/detect/ScanI2CTwoWire.cpp`
+
+The scan runs at boot and populates a device map that telemetry modules use to decide which sensors to initialize.
+
+## Protobuf Fields
+
+If the sensor provides data not covered by existing telemetry fields:
+
+1. Add fields to the appropriate message in `protobufs/meshtastic/telemetry.proto`:
+   - `EnvironmentMetrics` — Environmental measurements
+   - `AirQualityMetrics` — Air quality data
+   - `PowerMetrics` — Power/energy data
+   - `HealthMetrics` — Health/biometric data
+2. Add a `.options` constraint if needed (field sizes for nanopb)
+3. Regenerate: `bin/regen-protos.sh`
+
+## Sensor Type Enum
+
+Add the sensor to `meshtastic_TelemetrySensorType` enum in `protobufs/meshtastic/telemetry.proto`:
+
+```protobuf
+enum TelemetrySensorType {
+    // ... existing entries ...
+    MY_SENSOR = XX;
+}
+```
+
+## Integration with Telemetry Module
+
+Wire the sensor into the appropriate telemetry module. For environment sensors, this is typically in `src/modules/Telemetry/EnvironmentTelemetry.cpp`:
+
+1. Include the sensor header
+2. Add initialization in `setupSensor()` guarded by detection results
+3. Call `getMetrics()` in the measurement collection path
+
+Example pattern from existing sensors:
+
+```cpp
+#include "Sensor/MySensor.h"
+
+MySensor mySensor;
+
+// In setup:
+if (nodeTelemetrySensorsMap[meshtastic_TelemetrySensorType_MY_SENSOR].first > 0) {
+    mySensor.setup();
+}
+
+// In measurement collection:
+if (nodeTelemetrySensorsMap[meshtastic_TelemetrySensorType_MY_SENSOR].first > 0) {
+    mySensor.getMetrics(&measurement);
+}
+```
+
+## Library Dependencies
+
+If the sensor needs an external library, add it to the `lib_deps` in the relevant base platformio.ini configs:
+
+```ini
+lib_deps =
+    ${env.lib_deps}
+    mysensorlibrary@^1.0.0
+```
+
+Or use a conditional dependency if it's platform-specific.
+
+## Unit Conversions
+
+If the sensor reports values in non-standard units, use `src/modules/Telemetry/UnitConversions.h` for conversion helpers (e.g., Celsius ↔ Fahrenheit, hPa ↔ inHg).
+
+## Checklist
+
+- [ ] Create `src/modules/Telemetry/Sensor/MySensor.h` and `.cpp`
+- [ ] Inherit from `TelemetrySensor` base class
+- [ ] Implement `setup()` and `getMetrics()` methods
+- [ ] Add `meshtastic_TelemetrySensorType` enum entry in `telemetry.proto`
+- [ ] Add I2C address to `src/detect/ScanI2C` for auto-detection
+- [ ] Add protobuf fields in `telemetry.proto` if new data types needed
+- [ ] Regenerate protos: `bin/regen-protos.sh`
+- [ ] Wire into the appropriate telemetry module (Environment/AirQuality/Power/Health)
+- [ ] Add library dependency if external library required
+- [ ] Test on hardware or native build

.github/prompts/new-variant.prompt.md

@@ -0,0 +1,178 @@
+# New Hardware Variant
+
+Guide for adding a new Meshtastic hardware variant to the firmware.
+
+## Directory Structure
+
+Create under `variants/<arch>/<name>/`:
+
+```
+variants/
+├── esp32/          # ESP32
+├── esp32s3/        # ESP32-S3
+├── esp32c3/        # ESP32-C3
+├── esp32c6/        # ESP32-C6
+├── nrf52840/       # nRF52840
+├── rp2040/         # RP2040/RP2350
+├── stm32/          # STM32WL
+└── native/         # Linux/Portduino
+```
+
+Each variant needs at minimum:
+
+- `variant.h` — Pin definitions and hardware capabilities
+- `platformio.ini` — Build configuration
+
+Optional files:
+
+- `pins_arduino.h` — Arduino pin mapping overrides
+- `rfswitch.h` — RF switch control for multi-band radios
+- `nicheGraphics.h` — InkHUD e-ink configuration
+
+## variant.h Template
+
+```cpp
+// Pin definitions
+#define I2C_SDA 21
+#define I2C_SCL 22
+
+// LoRa radio
+#define USE_SX1262              // Radio chip: USE_SX1262, USE_SX1268, USE_SX1280, USE_RF95, USE_LLCC68, USE_LR1110, USE_LR1120, USE_LR1121
+#define LORA_CS   18
+#define LORA_SCK  5
+#define LORA_MOSI 27
+#define LORA_MISO 19
+#define LORA_DIO1 33            // SX126x: DIO1, SX128x: DIO1, RF95: IRQ
+#define LORA_RESET 23
+#define LORA_BUSY 32            // SX126x/SX128x only
+#define SX126X_DIO2_AS_RF_SWITCH // Common for SX1262 boards
+
+// GPS
+#define HAS_GPS 1
+#define GPS_RX_PIN 34
+#define GPS_TX_PIN 12
+// #define PIN_GPS_EN 47         // Optional GPS enable pin
+// #define GPS_BAUDRATE 9600     // Override default 9600
+
+// Display
+#define HAS_SCREEN 1
+// #define USE_SSD1306            // OLED type
+// #define USE_SH1106             // Alternative OLED
+// #define USE_ST7789             // TFT type
+// #define SCREEN_WIDTH 128
+// #define SCREEN_HEIGHT 64
+
+// LEDs
+#define LED_PIN 2               // Status LED (optional)
+// #define HAS_NEOPIXEL 1        // WS2812 support
+
+// Buttons
+#define BUTTON_PIN 38
+// #define BUTTON_PIN_ALT 0      // Secondary button
+
+// Power management
+// #define HAS_AXP192 1          // AXP192 PMU (T-Beam v1.0)
+// #define HAS_AXP2101 1         // AXP2101 PMU (T-Beam v1.2+)
+// #define BATTERY_PIN 35        // ADC battery voltage pin
+// #define ADC_MULTIPLIER 2.0    // Voltage divider ratio
+
+// Optional I2C devices
+// #define HAS_RTC 1             // Real-time clock
+// #define HAS_TELEMETRY 1       // Enable telemetry sensor support
+// #define HAS_SENSOR 1          // I2C sensors present
+```
+
+## platformio.ini Template
+
+```ini
+[env:my_variant]
+extends = esp32s3_base            ; Use architecture-specific base
+board = esp32-s3-devkitc-1        ; PlatformIO board definition (or custom in boards/)
+board_level = extra               ; Build level: extra, or omit for default
+custom_meshtastic_support_level = 1  ; 1 = PR builds, 2 = merge builds only
+
+build_flags =
+    ${esp32s3_base.build_flags}
+    -D MY_VARIANT_SPECIFIC_FLAG=1
+    -I variants/esp32s3/my_variant  ; Include path for variant.h
+
+upload_speed = 921600
+```
+
+### Common Base Configs
+
+- `esp32_base` / `esp32-common.ini` — ESP32
+- `esp32s3_base` — ESP32-S3
+- `esp32c3_base` — ESP32-C3
+- `esp32c6_base` — ESP32-C6
+- `nrf52840_base` / `nrf52.ini` — nRF52840
+- `rp2040_base` — RP2040/RP2350
+
+### Support Levels
+
+- `custom_meshtastic_support_level = 1` — Built on every PR (actively supported)
+- `custom_meshtastic_support_level = 2` — Built only on merge to main branches
+- `board_level = extra` — Only built on full releases
+
+## Build Manifest Metadata
+
+`bin/platformio-custom.py` emits UI capability flags in the build manifest:
+
+- `custom_meshtastic_has_mui = true/false` — Override MUI detection
+- `custom_meshtastic_has_ink_hud = true/false` — Override InkHUD detection
+- Architecture names are normalized (e.g., `esp32s3` → `esp32-s3`)
+
+## InkHUD E-Ink Variants
+
+For e-ink display variants using the InkHUD framework, add `nicheGraphics.h`:
+
+```cpp
+// nicheGraphics.h — InkHUD configuration for this variant
+#define INKHUD                     // Enable InkHUD
+// Configure display, applets, and refresh behavior per device
+```
+
+InkHUD has its own PlatformIO config: `src/graphics/niche/InkHUD/PlatformioConfig.ini`
+
+## I2C Device Detection
+
+If the variant has I2C devices, ensure `src/detect/ScanI2C` will detect them. The auto-detection system handles 80+ device types including displays, sensors, RTCs, keyboards, PMUs, and touch controllers at boot.
+
+## Custom Board Definitions
+
+If the PlatformIO board doesn't exist, create a custom board JSON in `boards/`:
+
+```json
+{
+  "build": {
+    "arduino": { "ldscript": "esp32s3_out.ld" },
+    "core": "esp32",
+    "f_cpu": "240000000L",
+    "f_flash": "80000000L",
+    "flash_mode": "qio",
+    "mcu": "esp32s3",
+    "variant": "esp32s3"
+  },
+  "connectivity": ["wifi", "bluetooth"],
+  "frameworks": ["arduino", "espidf"],
+  "name": "My Custom Board",
+  "upload": {
+    "flash_size": "8MB",
+    "maximum_ram_size": 327680,
+    "maximum_size": 8388608
+  },
+  "url": "https://example.com",
+  "vendor": "MyVendor"
+}
+```
+
+## Checklist
+
+- [ ] Create `variants/<arch>/<name>/variant.h` with pin definitions
+- [ ] Create `variants/<arch>/<name>/platformio.ini` extending correct base
+- [ ] Set `custom_meshtastic_support_level` (1 or 2)
+- [ ] Verify radio chip define matches hardware (`USE_SX1262`, etc.)
+- [ ] Set hardware capability flags (`HAS_GPS`, `HAS_SCREEN`, etc.)
+- [ ] Add custom board JSON in `boards/` if needed
+- [ ] Test build: `pio run -e my_variant`
+- [ ] For e-ink: add `nicheGraphics.h` with InkHUD config

.github/workflows/build_debian_src.yml

@@ -16,8 +16,7 @@ on:
         type: string
 
 permissions:
-  contents: write
-  packages: write
+  contents: read
 
 jobs:
   build-debian-src:
@@ -28,8 +27,6 @@ jobs:
         with:
           submodules: recursive
           path: meshtasticd
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - name: Install deps
         shell: bash
@@ -42,6 +39,7 @@ jobs:
           sudo mk-build-deps --install --remove --tool='apt-get -o Debug::pkgProblemResolver=yes --no-install-recommends --yes' debian/control
 
       - name: Import GPG key
+        if: github.event_name != 'pull_request' && github.event_name != 'pull_request_target'
         uses: crazy-max/ghaction-import-gpg@v7
         with:
           gpg_private_key: ${{ secrets.PPA_GPG_PRIVATE_KEY }}
@@ -60,7 +58,7 @@ jobs:
         run: debian/ci_pack_sdeb.sh
         env:
           SERIES: ${{ inputs.series }}
-          GPG_KEY_ID: ${{ steps.gpg.outputs.keyid }}
+          GPG_KEY_ID: ${{ steps.gpg.outputs.keyid || '' }}
           PKG_VERSION: ${{ steps.version.outputs.deb }}
 
       - name: Store binaries as an artifact

.github/workflows/build_firmware.yml

@@ -26,8 +26,6 @@ jobs:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - name: Build ${{ inputs.platform }}
         id: build

.github/workflows/build_one_target.yml

@@ -87,7 +87,7 @@ jobs:
 
   gather-artifacts:
     permissions:
-      contents: write
+      contents: read
       pull-requests: write
     runs-on: ubuntu-latest
     needs: [version, build]

.github/workflows/daily_packaging.yml

@@ -5,7 +5,7 @@ on:
   workflow_dispatch:
   push:
     branches:
-      - master
+      - develop # Default branch, same as 'cron' above
     paths:
       - debian/**
       - "*.rpkg"
@@ -16,7 +16,7 @@ on:
       - .github/workflows/hook_copr.yml
 
 permissions:
-  contents: write
+  contents: read
   packages: write
 
 jobs:

.github/workflows/docker_build.yml

@@ -37,7 +37,7 @@ on:
         value: ${{ jobs.docker-build.outputs.digest }}
 
 permissions:
-  contents: write
+  contents: read
   packages: write
 
 jobs:
@@ -50,14 +50,31 @@ jobs:
         uses: actions/checkout@v6
         with:
           submodules: recursive
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - name: Get release version string
         run: |
           echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
         id: version
 
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+        with:
+          cache-image: true
+
+      - name: Docker setup
+        uses: docker/setup-buildx-action@v4
+        with:
+          # Add Google/Amazon DockerHub mirrors to buildkit config
+          # https://docs.docker.com/build/ci/github-actions/configure-builder/#registry-mirror
+          buildkitd-config-inline: |
+            [registry."docker.io"]
+              mirrors = ["mirror.gcr.io", "public.ecr.aws"]
+
+      - name: Sanitize platform string
+        id: sanitize_platform
+        # Replace slashes with underscores
+        run: echo "cleaned_platform=${{ inputs.platform }}" | sed 's/\//_/g' >> $GITHUB_OUTPUT
+
       - name: Docker login
         if: ${{ inputs.push }}
         uses: docker/login-action@v4
@@ -65,17 +82,6 @@ jobs:
           username: meshtastic
           password: ${{ secrets.DOCKER_FIRMWARE_TOKEN }}
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
-
-      - name: Docker setup
-        uses: docker/setup-buildx-action@v4
-
-      - name: Sanitize platform string
-        id: sanitize_platform
-        # Replace slashes with underscores
-        run: echo "cleaned_platform=${{ inputs.platform }}" | sed 's/\//_/g' >> $GITHUB_OUTPUT
-
       - name: Docker tag
         id: meta
         uses: docker/metadata-action@v6
@@ -97,3 +103,6 @@ jobs:
           platforms: ${{ inputs.platform }}
           build-args: |
             PIO_ENV=${{ inputs.pio_env }}
+          # Cache image layers in GitHub Actions cache to speed up subsequent builds.
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/docker_manifest.yml

@@ -12,7 +12,7 @@ on:
         type: string
 
 permissions:
-  contents: write
+  contents: read
   packages: write
 
 jobs:
@@ -86,8 +86,6 @@ jobs:
         uses: actions/checkout@v6
         with:
           submodules: recursive
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - name: Get release version string
         run: |

.github/workflows/hook_copr.yml

@@ -11,8 +11,7 @@ on:
         type: string
 
 permissions:
-  contents: write
-  packages: write
+  contents: read
 
 jobs:
   build-copr-hook:
@@ -22,8 +21,6 @@ jobs:
         uses: actions/checkout@v6
         with:
           submodules: recursive
-          ref: ${{ github.ref }}
-          repository: ${{ github.repository }}
 
       - name: Trigger COPR build
         uses: vidplace7/copr-build@main

.github/workflows/main_matrix.yml

@@ -15,8 +15,7 @@ on:
       - "**.md"
       - version.properties
 
-  # Note: This is different from "pull_request". Need to specify ref when doing checkouts.
-  pull_request_target:
+  pull_request:
     branches:
       - master
       - develop
@@ -29,6 +28,8 @@ on:
 
   workflow_dispatch:
 
+permissions: read-all
+
 jobs:
   setup:
     strategy:
@@ -88,8 +89,6 @@ jobs:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
       - name: Check ${{ matrix.check.board }}
         uses: meshtastic/gh-action-firmware@main
         with:
@@ -126,9 +125,16 @@ jobs:
 
   test-native:
     if: ${{ !contains(github.ref_name, 'event/') && github.repository == 'meshtastic/firmware' }}
+    permissions: # Needed for dorny/test-reporter.
+      contents: read
+      actions: read
+      checks: write
     uses: ./.github/workflows/test_native.yml
 
   docker:
+    permissions: # Needed for pushing to GHCR.
+      contents: read
+      packages: write
     strategy:
       fail-fast: false
       matrix:
@@ -153,9 +159,6 @@ jobs:
   gather-artifacts:
     # trunk-ignore(checkov/CKV2_GHA_1)
     if: github.repository == 'meshtastic/firmware'
-    permissions:
-      contents: write
-      pull-requests: write
     strategy:
       fail-fast: false
       matrix:
@@ -173,9 +176,6 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
-        with:
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - uses: actions/download-artifact@v8
         with:
@@ -231,13 +231,6 @@ jobs:
           path: ./*.elf
           retention-days: 30
 
-      - uses: scruplelesswizard/comment-artifact@main
-        if: ${{ github.event_name == 'pull_request' }}
-        with:
-          name: firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}
-          description: "Download firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip. This artifact will be available for 90 days from creation"
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
   shame:
     if: github.repository == 'meshtastic/firmware'
     continue-on-error: true
@@ -245,7 +238,7 @@ jobs:
     needs: [build]
     steps:
       - uses: actions/checkout@v6
-        if: github.event_name == 'pull_request_target'
+        if: github.event_name == 'pull_request'
         with:
           filter: blob:none # means we download all the git history but none of the commit (except ones with checkout like the head)
           fetch-depth: 0
@@ -263,24 +256,26 @@ jobs:
           overwrite: true
           path: manifests-new/*.mt.json
       - name: Find the merge base
-        if: github.event_name == 'pull_request_target'
+        if: github.event_name == 'pull_request'
         run: echo "MERGE_BASE=$(git merge-base "origin/$base" "$head")" >> $GITHUB_ENV
         env:
           base: ${{ github.base_ref }}
           head: ${{ github.sha }}
       # Currently broken (for-loop through EVERY artifact -- rate limiting)
       # - name: Download the old manifests
-      #   if: github.event_name == 'pull_request_target'
+      #   if: github.event_name == 'pull_request'
       #   run: gh run download -R "$repo" --name "manifests-$merge_base" --dir manifest-old/
       #   env:
       #     GH_TOKEN: ${{ github.token }}
       #     merge_base: ${{ env.MERGE_BASE }}
       #     repo: ${{ github.repository }}
       # - name: Do scan and post comment
-      #   if: github.event_name == 'pull_request_target'
+      #   if: github.event_name == 'pull_request'
       #   run: python3 bin/shame.py ${{ github.event.pull_request.number }} manifests-old/ manifests-new/
 
   release-artifacts:
+    permissions: # Needed for 'gh release upload'.
+      contents: write
     runs-on: ubuntu-latest
     if: ${{ github.event_name == 'workflow_dispatch' && github.repository == 'meshtastic/firmware' }}
     outputs:
@@ -306,15 +301,17 @@ jobs:
         id: release_notes
         run: |
           chmod +x ./bin/generate_release_notes.py
-          NOTES=$(./bin/generate_release_notes.py ${{ needs.version.outputs.long }})
+          NOTES=$(./bin/generate_release_notes.py ${{ needs.version.outputs.long }} --compare-ref HEAD 2>release_notes.log)
           echo "notes<<EOF" >> $GITHUB_OUTPUT
           echo "$NOTES" >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
+          echo "### Release note range" >> $GITHUB_STEP_SUMMARY
+          cat release_notes.log >> $GITHUB_STEP_SUMMARY
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Create release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         id: create_release
         with:
           draft: true
@@ -372,6 +369,8 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   release-firmware:
+    permissions: # Needed for 'gh release upload'.
+      contents: write
     strategy:
       fail-fast: false
       matrix:
@@ -469,7 +468,7 @@ jobs:
       - name: Generate release notes
         run: |
           chmod +x ./bin/generate_release_notes.py
-          ./bin/generate_release_notes.py ${{ needs.version.outputs.long }} > ./publish/release_notes.md
+          ./bin/generate_release_notes.py ${{ needs.version.outputs.long }} --compare-ref HEAD > ./publish/release_notes.md
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/merge_queue.yml

@@ -1,371 +0,0 @@
-name: Merge Queue
-# Not sure how concurrency works in merge_queue, removing for now.
-# concurrency:
-#   group: merge-queue-${{ github.head_ref || github.run_id }}
-#   cancel-in-progress: true
-on:
-  # Merge group is a special trigger that is used to trigger the workflow when a merge group is created.
-  merge_group:
-
-jobs:
-  setup:
-    strategy:
-      fail-fast: true
-      matrix:
-        arch:
-          - all
-          - check
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
-        with:
-          python-version: 3.x
-          cache: pip
-      - run: pip install -U platformio
-      - name: Generate matrix
-        id: jsonStep
-        run: |
-          if [[ "$GITHUB_HEAD_REF" == "" ]]; then
-            TARGETS=$(./bin/generate_ci_matrix.py ${{matrix.arch}})
-          else  
-            TARGETS=$(./bin/generate_ci_matrix.py ${{matrix.arch}} --level pr)
-          fi
-          echo "Name: $GITHUB_REF_NAME Base: $GITHUB_BASE_REF Ref: $GITHUB_REF"
-          echo "${{matrix.arch}}=$TARGETS" >> $GITHUB_OUTPUT
-    outputs:
-      all: ${{ steps.jsonStep.outputs.all }}
-      check: ${{ steps.jsonStep.outputs.check }}
-
-  version:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Get release version string
-        run: |
-          echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
-          echo "deb=$(./bin/buildinfo.py deb)" >> $GITHUB_OUTPUT
-        id: version
-        env:
-          BUILD_LOCATION: local
-    outputs:
-      long: ${{ steps.version.outputs.long }}
-      deb: ${{ steps.version.outputs.deb }}
-
-  check:
-    needs: setup
-    strategy:
-      fail-fast: true
-      matrix:
-        check: ${{ fromJson(needs.setup.outputs.check) }}
-
-    runs-on: ubuntu-latest
-    if: ${{ github.event_name != 'workflow_dispatch' }}
-    steps:
-      - uses: actions/checkout@v6
-      - name: Build base
-        id: base
-        uses: ./.github/actions/setup-base
-      - name: Check ${{ matrix.check.board }}
-        run: bin/check-all.sh ${{ matrix.check.board }}
-
-  build:
-    needs: [setup, version]
-    strategy:
-      matrix:
-        build: ${{ fromJson(needs.setup.outputs.all) }}
-    uses: ./.github/workflows/build_firmware.yml
-    with:
-      version: ${{ needs.version.outputs.long }}
-      pio_env: ${{ matrix.build.board }}
-      platform: ${{ matrix.build.platform }}
-
-  build-debian-src:
-    if: github.repository == 'meshtastic/firmware'
-    uses: ./.github/workflows/build_debian_src.yml
-    with:
-      series: UNRELEASED
-      build_location: local
-    secrets: inherit
-
-  package-pio-deps-native-tft:
-    if: ${{ github.event_name == 'workflow_dispatch' }}
-    uses: ./.github/workflows/package_pio_deps.yml
-    with:
-      pio_env: native-tft
-    secrets: inherit
-
-  test-native:
-    if: ${{ !contains(github.ref_name, 'event/') }}
-    uses: ./.github/workflows/test_native.yml
-
-  docker:
-    strategy:
-      fail-fast: false
-      matrix:
-        distro: [debian, alpine]
-        platform: [linux/amd64, linux/arm64, linux/arm/v7]
-        pio_env: [native, native-tft]
-        exclude:
-          - distro: alpine
-            platform: linux/arm/v7
-          - pio_env: native-tft
-            platform: linux/arm64
-          - pio_env: native-tft
-            platform: linux/arm/v7
-    uses: ./.github/workflows/docker_build.yml
-    with:
-      distro: ${{ matrix.distro }}
-      platform: ${{ matrix.platform }}
-      runs-on: ${{ contains(matrix.platform, 'arm') && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}
-      pio_env: ${{ matrix.pio_env }}
-      push: false
-
-  gather-artifacts:
-    # trunk-ignore(checkov/CKV2_GHA_1)
-    permissions:
-      contents: write
-      pull-requests: write
-    strategy:
-      fail-fast: false
-      matrix:
-        arch:
-          - esp32
-          - esp32s3
-          - esp32c3
-          - esp32c6
-          - nrf52840
-          - rp2040
-          - rp2350
-          - stm32
-    runs-on: ubuntu-latest
-    needs: [version, build]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-        with:
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
-
-      - uses: actions/download-artifact@v8
-        with:
-          path: ./
-          pattern: firmware-${{matrix.arch}}-*
-          merge-multiple: true
-
-      - name: Display structure of downloaded files
-        run: ls -R
-
-      - name: Move files up
-        run: mv -b -t ./ ./bin/device-*.sh ./bin/device-*.bat
-
-      - name: Repackage in single firmware zip
-        uses: actions/upload-artifact@v7
-        with:
-          name: firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}
-          overwrite: true
-          path: |
-            ./firmware-*.bin
-            ./firmware-*.uf2
-            ./firmware-*.hex
-            ./firmware-*.zip
-            ./device-*.sh
-            ./device-*.bat
-            ./littlefs-*.bin
-            ./bleota*bin
-            ./Meshtastic_nRF52_factory_erase*.uf2
-          retention-days: 30
-
-      - uses: actions/download-artifact@v8
-        with:
-          name: firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}
-          merge-multiple: true
-          path: ./output
-
-      # For diagnostics
-      - name: Show artifacts
-        run: ls -lR
-
-      - name: Device scripts permissions
-        run: |
-          chmod +x ./output/device-install.sh || true
-          chmod +x ./output/device-update.sh || true
-
-      - name: Zip firmware
-        run: zip -j -9 -r ./firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip ./output
-
-      - name: Repackage in single elfs zip
-        uses: actions/upload-artifact@v7
-        with:
-          name: debug-elfs-${{matrix.arch}}-${{ needs.version.outputs.long }}
-          overwrite: true
-          path: ./*.elf
-          retention-days: 30
-
-      - uses: scruplelesswizard/comment-artifact@main
-        if: ${{ github.event_name == 'pull_request' }}
-        with:
-          name: firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}
-          description: "Download firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip. This artifact will be available for 90 days from creation"
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-  release-artifacts:
-    runs-on: ubuntu-latest
-    if: ${{ github.event_name == 'workflow_dispatch' }}
-    outputs:
-      upload_url: ${{ steps.create_release.outputs.upload_url }}
-    needs:
-      - version
-      - gather-artifacts
-      - build-debian-src
-      - package-pio-deps-native-tft
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Create release
-        uses: softprops/action-gh-release@v2
-        id: create_release
-        with:
-          draft: true
-          prerelease: true
-          name: Meshtastic Firmware ${{ needs.version.outputs.long }} Alpha
-          tag_name: v${{ needs.version.outputs.long }}
-          body: |
-            Autogenerated by github action, developer should edit as required before publishing...
-
-      - name: Download source deb
-        uses: actions/download-artifact@v8
-        with:
-          pattern: firmware-debian-${{ needs.version.outputs.deb }}~UNRELEASED-src
-          merge-multiple: true
-          path: ./output/debian-src
-
-      - name: Download `native-tft` pio deps
-        uses: actions/download-artifact@v8
-        with:
-          pattern: platformio-deps-native-tft-${{ needs.version.outputs.long }}
-          merge-multiple: true
-          path: ./output/pio-deps-native-tft
-
-      - name: Zip Linux sources
-        working-directory: output
-        run: |
-          zip -j -9 -r ./meshtasticd-${{ needs.version.outputs.deb }}-src.zip ./debian-src
-          zip -9 -r ./platformio-deps-native-tft-${{ needs.version.outputs.long }}.zip ./pio-deps-native-tft
-
-      # For diagnostics
-      - name: Display structure of downloaded files
-        run: ls -lR
-
-      - name: Add Linux sources to GtiHub Release
-        # Only run when targeting master branch with workflow_dispatch
-        if: ${{ github.ref_name == 'master' }}
-        run: |
-          gh release upload v${{ needs.version.outputs.long }} ./output/meshtasticd-${{ needs.version.outputs.deb }}-src.zip
-          gh release upload v${{ needs.version.outputs.long }} ./output/platformio-deps-native-tft-${{ needs.version.outputs.long }}.zip
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  release-firmware:
-    strategy:
-      fail-fast: false
-      matrix:
-        arch:
-          - esp32
-          - esp32s3
-          - esp32c3
-          - esp32c6
-          - nrf52840
-          - rp2040
-          - rp2350
-          - stm32
-    runs-on: ubuntu-latest
-    if: ${{ github.event_name == 'workflow_dispatch' }}
-    needs: [release-artifacts, version]
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: 3.x
-
-      - uses: actions/download-artifact@v8
-        with:
-          pattern: firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}
-          merge-multiple: true
-          path: ./output
-
-      - name: Display structure of downloaded files
-        run: ls -lR
-
-      - name: Device scripts permissions
-        run: |
-          chmod +x ./output/device-install.sh || true
-          chmod +x ./output/device-update.sh || true
-
-      - name: Zip firmware
-        run: zip -j -9 -r ./firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip ./output
-
-      - uses: actions/download-artifact@v8
-        with:
-          name: debug-elfs-${{matrix.arch}}-${{ needs.version.outputs.long }}
-          merge-multiple: true
-          path: ./elfs
-
-      - name: Zip debug elfs
-        run: zip -j -9 -r ./debug-elfs-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip ./elfs
-
-      # For diagnostics
-      - name: Display structure of downloaded files
-        run: ls -lR
-
-      - name: Add bins and debug elfs to GitHub Release
-        # Only run when targeting master branch with workflow_dispatch
-        if: ${{ github.ref_name == 'master' }}
-        run: |
-          gh release upload v${{ needs.version.outputs.long }} ./firmware-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip
-          gh release upload v${{ needs.version.outputs.long }} ./debug-elfs-${{matrix.arch}}-${{ needs.version.outputs.long }}.zip
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  publish-firmware:
-    runs-on: ubuntu-24.04
-    if: ${{ github.event_name == 'workflow_dispatch' }}
-    needs: [release-firmware, version]
-    env:
-      targets: |-
-        esp32,esp32s3,esp32c3,esp32c6,nrf52840,rp2040,rp2350,stm32
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: 3.x
-
-      - uses: actions/download-artifact@v8
-        with:
-          pattern: firmware-{${{ env.targets }}}-${{ needs.version.outputs.long }}
-          merge-multiple: true
-          path: ./publish
-
-      - name: Publish firmware to meshtastic.github.io
-        uses: peaceiris/actions-gh-pages@v4
-        env:
-          # On event/* branches, use the event name as the destination prefix
-          DEST_PREFIX: ${{ contains(github.ref_name, 'event/') && format('{0}/', github.ref_name) || '' }}
-        with:
-          deploy_key: ${{ secrets.DIST_PAGES_DEPLOY_KEY }}
-          external_repository: meshtastic/meshtastic.github.io
-          publish_branch: master
-          publish_dir: ./publish
-          destination_dir: ${{ env.DEST_PREFIX }}firmware-${{ needs.version.outputs.long }}
-          keep_files: true
-          user_name: github-actions[bot]
-          user_email: github-actions[bot]@users.noreply.github.com
-          commit_message: ${{ needs.version.outputs.long }}
-          enable_jekyll: true

.github/workflows/models_issue_triage.yml

@@ -38,7 +38,7 @@ jobs:
 
       - name: Apply quality label if needed
         if: steps.quality.outputs.response != '' && steps.quality.outputs.response != 'ok'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         env:
           QUALITY_LABEL: ${{ steps.quality.outputs.response }}
         with:
@@ -80,7 +80,7 @@ jobs:
       # ─────────────────────────────────────────────────────────────────────────
       - name: Determine if completeness check should be skipped
         if: steps.quality.outputs.response == 'ok' || steps.quality.outputs.response == ''
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         id: check-skip
         with:
           script: |
@@ -134,7 +134,7 @@ jobs:
 
       - name: Process analysis result
         if: (steps.quality.outputs.response == 'ok' || steps.quality.outputs.response == '') && steps.check-skip.outputs.should_skip != 'true' && steps.analysis.outputs.response != ''
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         id: process
         env:
           AI_RESPONSE: ${{ steps.analysis.outputs.response }}
@@ -174,7 +174,7 @@ jobs:
 
       - name: Apply triage label
         if: steps.process.outputs.label != '' && steps.process.outputs.label != 'none'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         env:
           LABEL_NAME: ${{ steps.process.outputs.label }}
         with:
@@ -200,7 +200,7 @@ jobs:
 
       - name: Comment on issue
         if: steps.process.outputs.should_comment == 'true'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         env:
           COMMENT_BODY: ${{ steps.process.outputs.comment_body }}
         with:

.github/workflows/models_pr_triage.yml

@@ -22,7 +22,7 @@ jobs:
       # Step 1: Check if PR already has automation/type labels (skip if so)
       # ─────────────────────────────────────────────────────────────────────────
       - name: Check existing labels
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         id: check-labels
         with:
           script: |
@@ -58,7 +58,7 @@ jobs:
 
       - name: Apply quality label if needed
         if: steps.check-labels.outputs.skip_all != 'true' && steps.quality.outputs.response != '' && steps.quality.outputs.response != 'ok'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         id: quality-label
         env:
           QUALITY_LABEL: ${{ steps.quality.outputs.response }}
@@ -113,7 +113,7 @@ jobs:
 
       - name: Apply type label
         if: steps.check-labels.outputs.skip_all != 'true' && steps.check-labels.outputs.has_type_label != 'true' && steps.classify.outputs.response != ''
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         env:
           TYPE_LABEL: ${{ steps.classify.outputs.response }}
         with:

.github/workflows/package_obs.yml

@@ -18,8 +18,7 @@ on:
         type: string
 
 permissions:
-  contents: write
-  packages: write
+  contents: read
 
 jobs:
   build-debian-src:

.github/workflows/package_pio_deps.yml

@@ -16,8 +16,7 @@ on:
         type: string
 
 permissions:
-  contents: write
-  packages: write
+  contents: read
 
 jobs:
   pkg-pio-libdeps:
@@ -27,8 +26,6 @@ jobs:
         uses: actions/checkout@v6
         with:
           submodules: recursive
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - name: Setup Python
         uses: actions/setup-python@v6

.github/workflows/package_ppa.yml

@@ -5,6 +5,8 @@ on:
     secrets:
       PPA_GPG_PRIVATE_KEY:
         required: true
+      PPA_SFTP_PRIVATE_KEY:
+        required: true
     inputs:
       ppa_repo:
         description: Meshtastic PPA to target
@@ -16,8 +18,7 @@ on:
         type: string
 
 permissions:
-  contents: write
-  packages: write
+  contents: read
 
 jobs:
   build-debian-src:
@@ -28,6 +29,7 @@ jobs:
       build_location: ppa
 
   package-ppa:
+    if: ${{ github.event_name != 'pull_request_target' && github.event_name != 'pull_request' }}
     runs-on: ubuntu-24.04
     needs: build-debian-src
     steps:
@@ -36,14 +38,12 @@ jobs:
         with:
           submodules: recursive
           path: meshtasticd
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - name: Install deps
         shell: bash
         run: |
           sudo apt-get update -y --fix-missing
-          sudo apt-get install -y dput
+          sudo apt-get install -y dput openssh-client
 
       - name: Import GPG key
         uses: crazy-max/ghaction-import-gpg@v7
@@ -68,7 +68,42 @@ jobs:
       - name: Display structure of downloaded files
         run: ls -lah
 
-      - name: Publish with dput
-        if: ${{ github.event_name != 'pull_request_target' && github.event_name != 'pull_request' }}
+      - name: Trust Launchpad's SSH key
         run: |
-          dput ${{ inputs.ppa_repo }} meshtasticd_${{ steps.version.outputs.deb }}~${{ inputs.series }}_source.changes
+          mkdir -p ~/.ssh
+          ssh-keyscan -H ppa.launchpad.net >> ~/.ssh/known_hosts
+
+      - name: Setup dput config
+        env:
+          ppa_login: meshtasticorg
+        run: |
+          sudo tee /etc/meshtastic-dput.cf >/dev/null <<EOF
+          [ppa]
+          fqdn                    = ppa.launchpad.net
+          method                  = ftp
+          incoming                = ~%(ppa)s
+          login                   = anonymous
+
+          [ssh-ppa]
+          fqdn                    = ppa.launchpad.net
+          method                  = sftp
+          incoming                = ~%(ssh-ppa)s
+          login                   = ${ppa_login}
+          EOF
+
+      - name: Import SSH key
+        uses: webfactory/ssh-agent@v0.10.0
+        with:
+          ssh-private-key: ${{ secrets.PPA_SFTP_PRIVATE_KEY }}
+        id: ssh
+
+      - name: Publish with dput (sftp)
+        timeout-minutes: 30 # dput is terrible, sometimes runs 'forever'
+        env:
+          up_ppa_repo: ${{ inputs.ppa_repo }}
+          up_series: ${{ inputs.series }}
+          up_version: ${{ steps.version.outputs.deb }}
+        run: >
+          dput -c /etc/meshtastic-dput.cf
+          ssh-${up_ppa_repo}
+          meshtasticd_${up_version}~${up_series}_source.changes

.github/workflows/pr_enforce_labels.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check for PR labels
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const labels = context.payload.pull_request.labels.map(label => label.name);

.github/workflows/pr_tests.yml

@@ -177,7 +177,7 @@ jobs:
 
       - name: Comment test results on PR
         if: github.event_name == 'pull_request' && needs.native-tests.result != 'skipped'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const fs = require('fs');

.github/workflows/test_native.yml

@@ -16,8 +16,6 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
           submodules: recursive
 
       - name: Setup native build
@@ -72,8 +70,6 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
           submodules: recursive
 
       - name: Setup native build
@@ -128,9 +124,6 @@ jobs:
     if: always()
     steps:
       - uses: actions/checkout@v6
-        with:
-          ref: ${{github.event.pull_request.head.ref}}
-          repository: ${{github.event.pull_request.head.repo.full_name}}
 
       - name: Get release version string
         run: echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
@@ -143,7 +136,7 @@ jobs:
           merge-multiple: true
 
       - name: Test Report
-        uses: dorny/test-reporter@v2.6.0
+        uses: dorny/test-reporter@v3.0.0
         with:
           name: PlatformIO Tests
           path: testreport.xml

.github/workflows/tests.yml

@@ -52,7 +52,7 @@ jobs:
           node-version: 24
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v6
         with:
           version: latest
 

.github/workflows/update_protobufs.yml

@@ -6,7 +6,7 @@ permissions: read-all
 jobs:
   update-protobufs:
     runs-on: ubuntu-latest
-    permissions:
+    permissions: # Needed for peter-evans/create-pull-request.
       contents: write
       pull-requests: write
     steps:

.gitignore

@@ -54,3 +54,5 @@ CMakeLists.txt
 
 # PYTHONPATH used by the Nix shell
 .python3
+.claude/scheduled_tasks.lock
+userPrefs.jsonc.mcp-session-bak

.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "meshtastic": {
+      "command": "./mcp-server/.venv/bin/python",
+      "args": ["-m", "meshtastic_mcp"],
+      "env": {
+        "MESHTASTIC_FIRMWARE_ROOT": "."
+      }
+    }
+  }
+}

.trunk/configs/.bandit

@@ -1,2 +1,28 @@
 [bandit]
-skips = B101
+# Rule IDs: https://bandit.readthedocs.io/en/latest/plugins/index.html
+#
+# B101 assert_used
+#   pytest assertions + internal invariants; required for pytest.
+# B110 try_except_pass
+#   best-effort cleanup paths (atexit handlers, pubsub unsubscribe,
+#   session-end file close, socket shutdown). Logging inside the
+#   except block would be worse than the silent pass — teardown is
+#   already at end-of-session and the surrounding caller has context.
+# B112 try_except_continue
+#   defensive loops over flaky sources (pubsub handlers, device
+#   re-enumeration polls). One failed iteration shouldn't abort the loop.
+# B404 import_subprocess
+#   mcp-server wraps PlatformIO, esptool, nrfutil, picotool, and the
+#   pytest test-runner — subprocess is a load-bearing import here, not
+#   a smell. The "consider possible security implications" advisory is
+#   redundant given the file-level review already applied.
+# B603 subprocess_without_shell_equals_true
+#   all subprocess calls use a static argv list; `shell=False` is the
+#   default and we never string-interpolate user input into the command.
+# B606 start_process_with_no_shell
+#   same invariant as B603 — running a binary via argv list (not
+#   `shell=True`) is the safe pattern bandit is asking for.
+#
+# Higher-severity checks (B102 exec_used, B301 pickle, B307 eval,
+# B602 shell=True, etc.) remain enabled.
+skips = B101,B110,B112,B404,B603,B606

.trunk/trunk.yaml

@@ -8,27 +8,27 @@ plugins:
       uri: https://github.com/trunk-io/plugins
 lint:
   enabled:
-    - checkov@3.2.508
-    - renovate@43.76.3
+    - checkov@3.2.517
+    - renovate@43.110.9
     - prettier@3.8.1
-    - trufflehog@3.93.8
+    - trufflehog@3.94.3
     - yamllint@1.38.0
     - bandit@1.9.4
     - trivy@0.69.3
     - taplo@0.10.0
-    - ruff@0.15.6
+    - ruff@0.15.9
     - isort@8.0.1
     - markdownlint@0.48.0
     - oxipng@10.1.0
     - svgo@4.0.1
-    - actionlint@1.7.11
+    - actionlint@1.7.12
     - flake8@7.3.0
     - hadolint@2.14.0
     - shfmt@3.6.0
     - shellcheck@0.11.0
     - black@26.3.1
     - git-diff-check
-    - gitleaks@8.30.0
+    - gitleaks@8.30.1
     - clang-format@16.0.3
   ignore:
     - linters: [ALL]

AGENTS.md

@@ -0,0 +1,130 @@
+# Agent instructions
+
+This repository is the [Meshtastic](https://meshtastic.org) firmware — a C++17 embedded codebase targeting ESP32 / nRF52 / RP2040 / STM32WL / Linux-Portduino LoRa mesh radios — plus a Python MCP server in `mcp-server/` that AI agents use to flash, configure, and test connected devices.
+
+## Primary instruction file
+
+**Read `.github/copilot-instructions.md` first.** That file is the canonical agent-facing document for this repo. It covers project layout, coding conventions (naming, module framework, Observer pattern, thread safety), the build system, CI/CD, the native C++ test suite, and — most importantly for automation work — the **MCP Server & Hardware Test Harness** section. Read it top-to-bottom before starting any non-trivial change.
+
+This file (`AGENTS.md`) is a short pointer + quick reference for agents that don't read `.github/copilot-instructions.md` by default.
+
+## Quick command reference
+
+| Action                           | Command                                                                             |
+| -------------------------------- | ----------------------------------------------------------------------------------- |
+| Build a firmware variant         | `pio run -e <env>` (e.g. `pio run -e rak4631`, `pio run -e heltec-v3`)              |
+| Clean + rebuild                  | `pio run -e <env> -t clean && pio run -e <env>`                                     |
+| Flash a device                   | `pio run -e <env> -t upload --upload-port <port>` (or use the `pio_flash` MCP tool) |
+| Run firmware unit tests (native) | `pio test -e native`                                                                |
+| Run MCP hardware tests           | `./mcp-server/run-tests.sh`                                                         |
+| Live TUI test runner             | `mcp-server/.venv/bin/meshtastic-mcp-test-tui`                                      |
+| Format before commit             | `trunk fmt`                                                                         |
+| Regenerate protobuf bindings     | `bin/regen-protos.sh`                                                               |
+| Generate CI matrix               | `./bin/generate_ci_matrix.py all [--level pr]`                                      |
+
+## MCP server (device + test automation)
+
+The `mcp-server/` package exposes ~32 MCP tools for device discovery, building, flashing, serial monitoring, and live-node administration. Tools are grouped as:
+
+- **Discovery**: `list_devices`, `list_boards`, `get_board`
+- **Build & flash**: `build`, `clean`, `pio_flash`, `erase_and_flash` (ESP32 factory), `update_flash` (ESP32 OTA), `touch_1200bps`
+- **Serial sessions**: `serial_open`, `serial_read`, `serial_list`, `serial_close`
+- **Device reads**: `device_info`, `list_nodes`
+- **Device writes** (require `confirm=True`): `set_owner`, `get_config`, `set_config`, `get_channel_url`, `set_channel_url`, `send_text`, `reboot`, `shutdown`, `factory_reset`, `set_debug_log_api`
+- **userPrefs admin**: `userprefs_get`, `userprefs_set`, `userprefs_reset`, `userprefs_manifest`, `userprefs_testing_profile`
+- **Vendor escape hatches**: `esptool_*`, `nrfutil_*`, `picotool_*`
+
+Setup: `cd mcp-server && python3 -m venv .venv && .venv/bin/pip install -e '.[test]'`. The repo registers the server via `.mcp.json` — Claude Code picks it up automatically.
+
+See `mcp-server/README.md` for argument shapes and the **MCP Server & Hardware Test Harness** section of `.github/copilot-instructions.md` for agent usage rules (tool surface, fixture contract, firmware integration points, recovery playbooks).
+
+## Slash commands (AI-assisted workflows)
+
+Three test-and-diagnose workflows exist as slash commands:
+
+- **`/test` (Claude Code) / `/mcp-test` (Copilot)** — run the hardware test suite and interpret failures
+- **`/diagnose` / `/mcp-diagnose`** — read-only device health report
+- **`/repro` / `/mcp-repro`** — flakiness triage: re-run one test N times, diff firmware logs between passes and failures
+
+Bodies live in `.claude/commands/` and `.github/prompts/` respectively. `.claude/commands/README.md` is the index.
+
+## House rules
+
+- **No destructive device operations without operator approval.** `factory_reset`, `erase_and_flash`, `reboot`, `shutdown`, history-rewriting git ops — describe the action and stop. Operator authorizes.
+- **One MCP call per serial port at a time.** The port lock is exclusive; concurrent calls deadlock. Sequence: open → read/mutate → close, then next device.
+- **`userPrefs.jsonc` is session state during tests.** The `_session_userprefs` fixture snapshots + restores it; never edit it from inside a test.
+- **Don't speculate about firmware root causes.** When evidence doesn't support a classification, say "unknown" and list what would disambiguate.
+- **Run `trunk fmt` before proposing a commit.** The `trunk_check` CI gate will reject unformatted code.
+- **`confirm=True` on destructive MCP tools is a real gate, not a formality.** Don't bypass it via auto-approve settings.
+
+## Typical agent workflows
+
+### Flashing a device
+
+1. `list_devices` → find the port + likely VID
+2. `list_boards` → confirm the env, or use the known default for the hardware
+3. `pio_flash(env=..., port=..., confirm=True)` for any arch, or `erase_and_flash(env=..., port=..., confirm=True)` for an ESP32 factory install
+
+### Inspecting live node state
+
+1. `device_info(port=...)` — short summary (node num, firmware version, region, peer count)
+2. `list_nodes(port=...)` — full peer table (SNR, RSSI, pubkey presence, last_heard)
+3. `get_config(section="lora", port=...)` — LoRa settings for cross-device comparison
+
+Sequence these; don't parallelize on the same port.
+
+### Testing a firmware change
+
+1. Build locally: `pio run -e <env>`
+2. Flash the test device: `pio_flash(env=..., port=..., confirm=True)`
+3. Run the suite: `./mcp-server/run-tests.sh tests/<tier>` or `/test tests/<tier>`
+4. On failure, open `mcp-server/tests/report.html` → `Meshtastic debug` section for the firmware log tail + device state dump
+5. Iterate
+
+### Debugging a flaky test
+
+1. `/repro <test-node-id> [count]` — re-runs the test N times, diffs firmware logs between passes and failures
+2. If the first attempt always fails and the rest pass, that's a state-leak pattern → suggest `--force-bake` or a clean device state, don't chase the first failure
+3. If all N fail, this isn't a flake — it's a regression. Stop iterating and escalate to `/test` for full-suite context.
+
+## Where to look
+
+| Path                              | What's there                                                                                                             |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `src/`                            | Firmware C++ source (`mesh/`, `modules/`, `platform/`, `graphics/`, `gps/`, `motion/`, `mqtt/`, …)                       |
+| `src/mesh/`                       | Core: NodeDB, Router, Channels, CryptoEngine, radio interfaces, StreamAPI, PhoneAPI                                      |
+| `src/modules/`                    | Feature modules; `Telemetry/Sensor/` has 50+ I2C sensor drivers                                                          |
+| `variants/`                       | 200+ hardware variant definitions (`variant.h` + `platformio.ini` per board)                                             |
+| `protobufs/`                      | `.proto` definitions; regenerate with `bin/regen-protos.sh`                                                              |
+| `test/`                           | Firmware unit tests (12 suites; `pio test -e native`)                                                                    |
+| `mcp-server/`                     | Python MCP server + pytest hardware integration tests                                                                    |
+| `mcp-server/tests/`               | Tiered pytest suite: `unit/`, `mesh/`, `telemetry/`, `monitor/`, `recovery/`, `ui/`, `fleet/`, `admin/`, `provisioning/` |
+| `.claude/commands/`               | Claude Code slash command bodies                                                                                         |
+| `.github/prompts/`                | Copilot prompt bodies (mirrors of the Claude Code ones)                                                                  |
+| `.github/copilot-instructions.md` | **Primary agent instructions — read this**                                                                               |
+| `.github/workflows/`              | CI pipelines                                                                                                             |
+| `.mcp.json`                       | MCP server registration for Claude Code                                                                                  |
+
+## Recovery one-liners
+
+- **`userPrefs.jsonc` dirty after a test run?** Re-run `./mcp-server/run-tests.sh` once (pre-flight self-heals from the sidecar). If still dirty: `git checkout userPrefs.jsonc`.
+- **nRF52 not responding?** `mcp__meshtastic__touch_1200bps(port=...)` drops it into the DFU bootloader, then `pio_flash` re-installs.
+- **Device fully wedged (no DFU)?** `mcp__meshtastic__uhubctl_cycle(role="nrf52", confirm=True)` hard-power-cycles it via USB hub PPPS. Needs `uhubctl` installed (`brew install uhubctl` / `apt install uhubctl`); on Linux without udev rules, permission errors fail fast, so use `sudo uhubctl` yourself or configure udev access.
+- **Port busy?** `lsof <port>` to find the holder. Usually a stale `pio device monitor` or zombie `meshtastic_mcp` process. Kill it.
+- **Multiple MCP servers running?** `ps aux | grep meshtastic_mcp` — zombies hold ports. Kill all but the one your host spawned.
+
+## Environment variables (test harness)
+
+| Var                                  | Purpose                                                                                                                                        |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MESHTASTIC_MCP_ENV_<ROLE>`          | Override PlatformIO env for a role (e.g. `MESHTASTIC_MCP_ENV_NRF52=rak4631-dap`). Default map: `nrf52→rak4631`, `esp32s3→heltec-v3`.           |
+| `MESHTASTIC_MCP_SEED`                | PSK seed for the session test profile. Defaults to `mcp-<user>-<host>`.                                                                        |
+| `MESHTASTIC_MCP_FLASH_LOG`           | File path to tee pio/esptool/nrfutil/picotool output. `run-tests.sh` sets this to `tests/flash.log` so the TUI can stream live flash progress. |
+| `MESHTASTIC_UHUBCTL_BIN`             | Absolute path to `uhubctl` binary. Default: PATH lookup.                                                                                       |
+| `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` | Pin a role to a specific uhubctl hub location (e.g. `1-1.3`). Wins over VID auto-detection — use when multiple devices share a VID.            |
+| `MESHTASTIC_UHUBCTL_PORT_<ROLE>`     | Pin a role to a specific hub port number. Required alongside `LOCATION_<ROLE>`.                                                                |
+| `MESHTASTIC_UI_CAMERA_BACKEND`       | Camera backend for UI tier + `capture_screen` tool: `opencv` / `ffmpeg` / `null` / `auto` (default).                                           |
+| `MESHTASTIC_UI_CAMERA_DEVICE`        | Generic camera device (index or path). Used by the UI tier when no per-role var is set.                                                        |
+| `MESHTASTIC_UI_CAMERA_DEVICE_<ROLE>` | Per-role camera pinning (e.g. `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=0` for the OLED-bearing heltec-v3).                                         |
+| `MESHTASTIC_UI_OCR_BACKEND`          | OCR engine selection: `easyocr` / `pytesseract` / `null` / `auto` (default).                                                                   |
+| `MESHTASTIC_UI_TUI_CAMERA`           | Set to `1` to mount the live camera-feed panel in `meshtastic-mcp-test-tui`.                                                                   |

bin/config.d/OpenWRT/BananaPi-BPI-R4-sx1262.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: BananaPi-BPI-R4-sx1262
+  support: community
+  compatible:
+    - bananapi_bpi-r4 # OpenWrt target
+
 Lora:
   Module: sx1262  # BananaPi-BPI-R4 SPI via 26p GPIO Header
 ##  CS: 28

bin/config.d/OpenWRT/OpenWRT-One-mikroBUS-LR-IOT-CLICK.yaml

@@ -1,4 +1,10 @@
 ##  https://www.mikroe.com/lr-iot-click
+Meta:
+  name: OpenWRT One mikroBUS LR-IOT-CLICK
+  support: community
+  compatible:
+    - openwrt_one # OpenWrt target
+
 Lora:
   Module: lr1110  # OpenWRT ONE mikroBUS with LR-IOT-CLICK
 #  CS: 25

bin/config.d/OpenWRT/OpenWRT_One_mikroBUS_sx1262.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: OpenWRT One mikroBUS sx1262
+  support: community
+  compatible:
+    - openwrt_one # OpenWrt target
+
 Lora:
   Module: sx1262
   IRQ: 10

bin/config.d/README.md

@@ -0,0 +1,28 @@
+# meshtasticd configuration files
+
+This directory contains YAML configuration files for meshtasticd. Each file describes a specific hardware configuration, including the LoRa module and pin assignments. These configurations are used by meshtasticd to correctly interface with the hardware.
+
+## Metadata structure
+
+Each configuration file includes a `Meta` section that provides information about the configuration.
+This configuration is consumed by configuration-selection tools.
+
+```yaml
+Meta:
+  name: MeshAdv-Pi E22-900M30S # A unique identifier for this configuration.
+  support: community # community, official, or deprecated; determined by Meshtastic Leads.
+  compatible: # A list of compatible products or platforms.
+    - raspberry-pi
+```
+`name`: A unique identifier for the configuration, typically reflecting the hardware it supports.
+
+`support`: Indicates the level of support for this configuration. It can be one of the following:
+
+- `community`: Supported by the Meshtastic community. Meshtastic Members may not possess, or have not tested this configuration.
+- `official`: Fully supported by Meshtastic. Meshtastic Members have tested and verified this configuration.
+- `deprecated`: No longer recommended for deployment by Meshtastic.
+
+`compatible`: A list of compatible products or platforms that can use this configuration.
+This will vary depending on the intended use case / platform.
+Multiple compatible entries can be included. E.g. Armbian `BOARD` value or OpenWrt `TARGET` value.
+These tags can be consumed by different configuration-selection tools, filtering based upon their platform/etc.

bin/config.d/display-waveshare-1-44.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: Waveshare 1.44inch LCD HAT
+  support: community
+  compatible:
+    - raspberry-pi
+
 ### Waveshare 1.44inch LCD HAT
 Display:
   Panel: ST7735S

bin/config.d/display-waveshare-2.8.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: Waveshare 2.8inch LCD HAT
+  support: community
+  compatible:
+    - raspberry-pi
+
 Display:
 
 ### Waveshare 2.8inch RPi LCD

bin/config.d/lora-Adafruit-RFM9x.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: Adafruit RFM9x
+  support: deprecated
+  compatible:
+    - raspberry-pi
+
 Lora:
   Module: RF95  # Adafruit RFM9x
   Reset: 25

bin/config.d/lora-MeshAdv-900M30S.yaml

@@ -1,5 +1,11 @@
 # MeshAdv-Pi E22-900M30S
 # https://github.com/chrismyers2000/MeshAdv-Pi-Hat
+Meta:
+  name: MeshAdv-Pi E22-900M30S
+  support: community
+  compatible:
+    - raspberry-pi
+
 Lora:
   Module: sx1262
   CS: 21

bin/config.d/lora-MeshAdv-Mini-900M22S.yaml

@@ -1,5 +1,11 @@
 # MeshAdv Mini E22-900M22S
 # https://github.com/chrismyers2000/MeshAdv-Mini
+Meta:
+  name: MeshAdv Mini E22-900M22S
+  support: community
+  compatible:
+    - raspberry-pi
+
 Lora:
   Module: sx1262  # Ebyte E22-900M22S 
   CS: 8

bin/config.d/lora-RAK6421-13300-slot1.yaml

@@ -1,6 +1,12 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 1
+  support: official
+  compatible:
+    - raspberry-pi
+
 Lora:
 
-  ### RAK13300in Slot 1
+  ### RAK13300 in Slot 1
   Module: sx1262
   IRQ: 22 #IO6
   Reset: 16 # IO4

bin/config.d/lora-RAK6421-13300-slot2.yaml

@@ -1,5 +1,11 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 2
+  support: official
+  compatible:
+    - raspberry-pi
+
 Lora:
-  ### RAK13300in Slot 2 pins
+  ### RAK13300 in Slot 2 pins
   IRQ: 18 #IO6
   Reset: 24 # IO4
   Busy: 19 # IO5

bin/config.d/lora-RAK6421-13302-slot1.yaml

@@ -1,6 +1,12 @@
+Meta:
+  name: RAK6421 + RAK13302 Slot 1
+  support: official
+  compatible:
+    - raspberry-pi
+
 Lora:
 
-  ### RAK13300in Slot 1
+  ### RAK13302 in Slot 1
   Module: sx1262
   IRQ: 22 #IO6
   Reset: 16 # IO4

bin/config.d/lora-RAK6421-13302-slot2.yaml

@@ -1,5 +1,11 @@
+Meta:
+  name: RAK6421 + RAK13302 Slot 2
+  support: official
+  compatible:
+    - raspberry-pi
+
 Lora:
-  ### RAK13300in Slot 2 pins
+  ### RAK13302 in Slot 2 pins
   IRQ: 18 #IO6
   Reset: 24 # IO4
   Busy: 19 # IO5

bin/config.d/lora-ecb41-pge-MeshAdv-900M30S.yaml

@@ -0,0 +1,39 @@
+# MeshAdv-Pi E22-900M30S
+# https://github.com/chrismyers2000/MeshAdv-Pi-Hat
+Meta:
+  name: MeshAdv-Pi E22-900M30S
+  support: community
+  compatible:
+    - ebyte-ecb41-pge # Armbian
+
+Lora:
+  Module: sx1262
+  CS: # GPIO0_A1 (physical 40)
+    pin: 1
+    gpiochip: 0
+    line: 1
+  IRQ: # GPIO0_A3 (physical 36)
+    pin: 3
+    gpiochip: 0
+    line: 3
+  Busy: # GPIO0_A0 (physical 38)
+    pin: 0
+    gpiochip: 0
+    line: 0
+  Reset: # GPIO0_B4 (physical 12)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  TXen: # GPIO1_D1 (physical 33)
+    pin: 57
+    gpiochip: 1
+    line: 25
+  RXen: # GPIO1_B3 (physical 32)
+    pin: 43
+    gpiochip: 1
+    line: 11
+  DIO3_TCXO_VOLTAGE: true
+  # Only for E22-900M33S:
+  # Limit the output power to 8 dBm
+  # SX126X_MAX_POWER: 8
+  spidev: spidev0.0

bin/config.d/lora-ecb41-pge-MeshAdv-Mini-900M22S.yaml

@@ -0,0 +1,33 @@
+# MeshAdv Mini E22-900M22S
+# https://github.com/chrismyers2000/MeshAdv-Mini
+Meta:
+  name: MeshAdv Mini E22-900M22S
+  support: community
+  compatible:
+    - ebyte-ecb41-pge # Armbian
+
+Lora:
+  Module: sx1262 # Ebyte E22-900M22S
+  CS: # GPIO0_B6 (physical 24, SPI1_CSN0)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  IRQ: # GPIO0_A3 (physical 36)
+    pin: 3
+    gpiochip: 0
+    line: 3
+  Busy: # GPIO0_A0 (physical 38)
+    pin: 0
+    gpiochip: 0
+    line: 0
+  Reset: # GPIO1_C3 (physical 18)
+    pin: 51
+    gpiochip: 1
+    line: 19
+  RXen: # GPIO1_B3 (physical 32)
+    pin: 43
+    gpiochip: 1
+    line: 11
+  DIO2_AS_RF_SWITCH: true
+  DIO3_TCXO_VOLTAGE: true
+  spidev: spidev0.0

bin/config.d/lora-ecb41-pge-RAK6421-13300-slot1.yaml

@@ -0,0 +1,38 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 1
+  support: community # Promote when tested
+  compatible:
+    - ebyte-ecb41-pge # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_A5 (IO6, physical 15)
+    pin: 5
+    gpiochip: 0
+    line: 5
+  Reset: # GPIO0_A3 (IO4, physical 36)
+    pin: 3
+    gpiochip: 0
+    line: 3
+  Busy: # GPIO1_C3 (IO5, physical 18)
+    pin: 51
+    gpiochip: 1
+    line: 19
+  # Ant_sw: # GPIO1_C2 (IO3, physical 16)
+  #   pin: 50
+  #   gpiochip: 1
+  #   line: 18
+  Enable_Pins:
+    - pin: 43 # GPIO1_B3 (physical 32)
+      gpiochip: 1
+      line: 11
+    - pin: 57 # GPIO1_D1 (physical 33)
+      gpiochip: 1
+      line: 25
+  DIO3_TCXO_VOLTAGE: true
+  DIO2_AS_RF_SWITCH: true
+  spidev: spidev0.0
+  # CS: # GPIO0_B6 (SPI1_CSN0, physical 24)
+  #   pin: 14
+  #   gpiochip: 0
+  #   line: 14

bin/config.d/lora-ecb41-pge-RAK6421-13300-slot2.yaml

@@ -0,0 +1,36 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 2
+  support: community # Promote when tested
+  compatible:
+    - ebyte-ecb41-pge # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_B4 (IO6, physical 12)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  Reset: # GPIO1_C3 (IO4, physical 18)
+    pin: 51
+    gpiochip: 1
+    line: 19
+  Busy: # GPIO0_B3 (IO5, physical 35)
+    pin: 11
+    gpiochip: 0
+    line: 11
+  # Ant_sw: # GPIO1_C2 (IO3, physical 16)
+  #   pin: 50
+  #   gpiochip: 1
+  #   line: 18
+  Enable_Pins:
+    - pin: 2 # GPIO0_A2 (physical 37)
+      gpiochip: 0
+      line: 2
+    - pin: 50 # GPIO1_C2 (physical 16)
+      gpiochip: 1
+      line: 18
+  spidev: spidev0.1
+  # CS: # GPIO0_A7 (SPI1_CSN1, physical 26)
+  #   pin: 7
+  #   gpiochip: 0
+  #   line: 7

bin/config.d/lora-ecb41-pge-RAK6421-13302-slot1.yaml

@@ -0,0 +1,39 @@
+Meta:
+  name: RAK6421 + RAK13302 Slot 1
+  support: community # Promote when tested
+  compatible:
+    - ebyte-ecb41-pge # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_A5 (IO6, physical 15)
+    pin: 5
+    gpiochip: 0
+    line: 5
+  Reset: # GPIO0_A3 (IO4, physical 36)
+    pin: 3
+    gpiochip: 0
+    line: 3
+  Busy: # GPIO1_C3 (IO5, physical 18)
+    pin: 51
+    gpiochip: 1
+    line: 19
+  # Ant_sw: # GPIO1_C2 (IO3, physical 16)
+  #   pin: 50
+  #   gpiochip: 1
+  #   line: 18
+  Enable_Pins:
+    - pin: 43 # GPIO1_B3 (physical 32)
+      gpiochip: 1
+      line: 11
+    - pin: 57 # GPIO1_D1 (physical 33)
+      gpiochip: 1
+      line: 25
+  DIO3_TCXO_VOLTAGE: true
+  DIO2_AS_RF_SWITCH: true
+  spidev: spidev0.0
+  # CS: # GPIO0_B6 (SPI1_CSN0, physical 24)
+  #   pin: 14
+  #   gpiochip: 0
+  #   line: 14
+  TX_GAIN_LORA: [9, 9, 10, 11, 9, 8, 9, 10, 10, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12, 10, 9, 8]

bin/config.d/lora-ecb41-pge-RAK6421-13302-slot2.yaml

@@ -0,0 +1,37 @@
+Meta:
+  name: RAK6421 + RAK13302 Slot 2
+  support: community # Promote when tested
+  compatible:
+    - ebyte-ecb41-pge # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_B4 (IO6, physical 12)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  Reset: # GPIO1_C3 (IO4, physical 18)
+    pin: 51
+    gpiochip: 1
+    line: 19
+  Busy: # GPIO0_B3 (IO5, physical 35)
+    pin: 11
+    gpiochip: 0
+    line: 11
+  # Ant_sw: # GPIO1_C2 (IO3, physical 16)
+  #   pin: 50
+  #   gpiochip: 1
+  #   line: 18
+  Enable_Pins:
+    - pin: 2 # GPIO0_A2 (physical 37)
+      gpiochip: 0
+      line: 2
+    - pin: 50 # GPIO1_C2 (physical 16)
+      gpiochip: 1
+      line: 18
+  spidev: spidev0.1
+  # CS: # GPIO0_A7 (SPI1_CSN1, physical 26)
+  #   pin: 7
+  #   gpiochip: 0
+  #   line: 7
+  TX_GAIN_LORA: [9, 9, 10, 11, 9, 8, 9, 10, 10, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12, 10, 9, 8]

bin/config.d/lora-ecb41-pge-waveshare-sxxx.yaml

@@ -0,0 +1,30 @@
+Meta:
+  name: Waveshare SX1262
+  support: deprecated
+  compatible:
+    - ebyte-ecb41-pge # Armbian
+
+Lora:
+  Module: sx1262  # Waveshare SX126X XXXM
+  DIO2_AS_RF_SWITCH: true
+  CS: # GPIO0_A1 (physical 40)
+    pin: 1
+    gpiochip: 0
+    line: 1
+  IRQ: # GPIO0_A3 (physical 36)
+    pin: 3
+    gpiochip: 0
+    line: 3
+  Busy: # GPIO0_A0 (physical 38)
+    pin: 0
+    gpiochip: 0
+    line: 0
+  Reset: # GPIO0_B4 (physical 12)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  SX126X_ANT_SW: # GPIO1_B2 (physical 31)
+    pin: 42
+    gpiochip: 1
+    line: 10
+  spidev: spidev0.0

bin/config.d/lora-femtofox_LR1121_TCXO.yaml

@@ -1,20 +1,22 @@
----
-Lora:
-## Ebyte E80-900M22S
-## This is a bit experimental
-## 
-##
-  Module: lr1121
-  gpiochip: 1 # subtract 32 from the gpio numbers
-  DIO3_TCXO_VOLTAGE: 1.8
-  CS: 16 #pin6 / GPIO48 1C0
-  IRQ: 23  #pin17 / GPIO55 1C7
-  Busy: 22 #pin16 / GPIO54 1C6
-  Reset: 25 #pin13 / GPIO57 1D1
-
-
-  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
-  spiSpeed: 2000000
-  
-General:
-  MACAddressSource: eth0
+---
+Meta:
+  name: Femtofox Ebyte E80-900M22S with TCXO
+  support: community
+  compatible:
+    - luckfox-pico-mini # Armbian
+
+Lora:
+## Ebyte E80-900M22S
+## This is a bit experimental
+## 
+##
+  Module: lr1121
+  gpiochip: 1 # subtract 32 from the gpio numbers
+  DIO3_TCXO_VOLTAGE: 1.8
+  CS: 16 #pin6 / GPIO48 1C0
+  IRQ: 23  #pin17 / GPIO55 1C7
+  Busy: 22 #pin16 / GPIO54 1C6
+  Reset: 25 #pin13 / GPIO57 1D1
+
+  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
+  spiSpeed: 2000000

bin/config.d/lora-femtofox_SX1262_TCXO.yaml

@@ -1,21 +1,24 @@
----
-Lora:
-## Ebyte E22-900M30S, E22-900M22S with or without external RF switching setup
-## HT-RA62 (Has internal switching, but whatever)
-## Seeed WIO SX1262 (already has TXEN-DIO2 link, but needs RXEN)
-## Will work with any module with or without RF switching, and with TCXO
-  Module: sx1262
-  gpiochip: 1 # subtract 32 from the gpio numbers
-  DIO2_AS_RF_SWITCH: true
-  DIO3_TCXO_VOLTAGE: true
-  CS: 16 #pin6 / GPIO48 1C0
-  IRQ: 23  #pin17 / GPIO55 1C7
-  Busy: 22 #pin16 / GPIO54 1C6
-  Reset: 25 #pin13 / GPIO57 1D1
-  RXen: 24 #pin12 / GPIO56 1D0 # Not strictly needed for auto-switching, but why complicate things?
-#  TXen: bridge to DIO2 on E22 module
-  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
-  spiSpeed: 2000000
-  
-General:
-  MACAddressSource: eth0
+---
+Meta:
+  name: Femtofox SX1262 TCXO
+  support: community
+  compatible:
+    - luckfox-pico-mini # Armbian
+
+Lora:
+## Ebyte E22-900M30S, E22-900M22S with or without external RF switching setup
+## HT-RA62 (Has internal switching, but whatever)
+## Seeed WIO SX1262 (already has TXEN-DIO2 link, but needs RXEN)
+## Will work with any module with or without RF switching, and with TCXO
+  Module: sx1262
+  gpiochip: 1 # subtract 32 from the gpio numbers
+  DIO2_AS_RF_SWITCH: true
+  DIO3_TCXO_VOLTAGE: true
+  CS: 16 #pin6 / GPIO48 1C0
+  IRQ: 23  #pin17 / GPIO55 1C7
+  Busy: 22 #pin16 / GPIO54 1C6
+  Reset: 25 #pin13 / GPIO57 1D1
+  RXen: 24 #pin12 / GPIO56 1D0 # Not strictly needed for auto-switching, but why complicate things?
+#  TXen: bridge to DIO2 on E22 module
+  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
+  spiSpeed: 2000000

bin/config.d/lora-femtofox_SX1262_XTAL.yaml

@@ -1,21 +1,24 @@
----
-Lora:
-## Ebyte E22-900MM22S with no external RF switching setup
-## Waveshare SX126X XXXM, AI Thinker RA-01SH
-## Will work with any module with or without RF switching and no TCXO
-
-  Module: sx1262  
-  gpiochip: 1 # subtract 32 from the gpio numbers
-  DIO2_AS_RF_SWITCH: true
-  DIO3_TCXO_VOLTAGE: false
-  CS: 16 #pin6 / GPIO48 1C0
-  IRQ: 23  #pin17 / GPIO55 1C7
-  Busy: 22 #pin16 / GPIO54 1C6
-  Reset: 25 #pin13 / GPIO57 1D1 
-  RXen: 24 #pin12 / GPIO56 1D0 # Not strictly needed for auto-switching, but why complicate things?
-#  TXen: bridge to DIO2 on E22 module
-  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
-  spiSpeed: 2000000
-
-General:
-  MACAddressSource: eth0
+---
+Meta:
+  name: Femtofox SX1262 XTAL
+  support: community
+  compatible:
+    - luckfox-pico-mini # Armbian
+
+Lora:
+## Ebyte E22-900MM22S with no external RF switching setup
+## Waveshare SX126X XXXM, AI Thinker RA-01SH
+## Will work with any module with or without RF switching and no TCXO
+
+  Module: sx1262  
+  gpiochip: 1 # subtract 32 from the gpio numbers
+  DIO2_AS_RF_SWITCH: true
+  DIO3_TCXO_VOLTAGE: false
+  CS: 16 #pin6 / GPIO48 1C0
+  IRQ: 23  #pin17 / GPIO55 1C7
+  Busy: 22 #pin16 / GPIO54 1C6
+  Reset: 25 #pin13 / GPIO57 1D1 
+  RXen: 24 #pin12 / GPIO56 1D0 # Not strictly needed for auto-switching, but why complicate things?
+#  TXen: bridge to DIO2 on E22 module
+  spidev: spidev0.0 #pins are (CS=16, CLK=17, MOSI=18, MISO=19)
+  spiSpeed: 2000000

bin/config.d/lora-hat-rak-6421-pi-hat.yaml

@@ -1,6 +1,12 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 1 (Autoconf default)
+  support: official
+  compatible:
+    - raspberry-pi
+
 Lora:
 
-  ### RAK13300in Slot 1
+  ### RAK13300 in Slot 1
   Module: sx1262
   IRQ: 22 #IO6
   Reset: 16 # IO4

bin/config.d/lora-lyra-picocalc-wio-sx1262.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: Luckfox Lyra PicoCalc Wio LoRa SX1262
+  support: official
+  compatible:
+    - luckfox-lyra-plus # Armbian
+
 Lora:
   Module: sx1262
   DIO2_AS_RF_SWITCH: true

bin/config.d/lora-lyra-ultra_1w.yaml

@@ -2,6 +2,13 @@
 # Enable overlay 'luckfox-lyra-ultra-w-spi0-cs0-spidev' with armbian-config
 # https://github.com/wehooper4/Meshtastic-Hardware/tree/main/Luckfox%20Ultra%20Hat
 # 1 Watt Lyra Ultra hat
+Meta:
+  name: wehooper4 Luckfox Ultra 1W
+  support: community
+  compatible:
+    - luckfox-pico-ultra # Armbian
+    - luckfox-lyra-ultra # Armbian
+
 Lora:
   Module: sx1262
   DIO2_AS_RF_SWITCH: true

bin/config.d/lora-lyra-ultra_2w.yaml

@@ -2,6 +2,13 @@
 # Enable overlay 'luckfox-lyra-ultra-w-spi0-cs0-spidev' with armbian-config
 # https://github.com/wehooper4/Meshtastic-Hardware/tree/main/Luckfox%20Ultra%20Hat
 # 2 Watt Lyra Ultra hat
+Meta:
+  name: wehooper4 Luckfox Ultra 2W
+  support: community
+  compatible:
+    - luckfox-pico-ultra # Armbian
+    - luckfox-lyra-ultra # Armbian
+
 Lora:
   Module: sx1262
   DIO2_AS_RF_SWITCH: true

bin/config.d/lora-lyra-ws-raspberry-pi-pico-hat.yaml

@@ -2,6 +2,12 @@
 # Enable overlay 'luckfox-lyra-plus-spi0-cs0_rmio13-spidev' with armbian-config
 # Waveshare LoRa HAT for Raspberry Pi Pico
 # https://www.waveshare.com/wiki/Pico-LoRa-SX1262
+Meta:
+  name: Waveshare LoRa HAT for Raspberry Pi Pico
+  support: community
+  compatible:
+    - luckfox-lyra-plus # Armbian
+
 Lora:
   Module: sx1262
   DIO2_AS_RF_SWITCH: true

bin/config.d/lora-lyra-zero-MeshAdv-900M30S.yaml

@@ -0,0 +1,39 @@
+# MeshAdv-Pi E22-900M30S
+# https://github.com/chrismyers2000/MeshAdv-Pi-Hat
+Meta:
+  name: MeshAdv-Pi E22-900M30S
+  support: community
+  compatible:
+    - luckfox-lyra-zero-w # Armbian
+
+Lora:
+  Module: sx1262
+  CS: # GPIO0_C2 (physical 40)
+    pin: 18
+    gpiochip: 0
+    line: 18
+  IRQ: # GPIO1_D1 (physical 36)
+    pin: 57
+    gpiochip: 1
+    line: 25
+  Busy: # GPIO0_C1 (physical 38)
+    pin: 17
+    gpiochip: 0
+    line: 17
+  Reset: # GPIO0_B6 (physical 12)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  TXen: # GPIO1_C2 (physical 33)
+    pin: 50
+    gpiochip: 1
+    line: 18
+  RXen: # GPIO1_D2 (physical 32)
+    pin: 58
+    gpiochip: 1
+    line: 26
+  DIO3_TCXO_VOLTAGE: true
+  # Only for E22-900M33S:
+  # Limit the output power to 8 dBm
+  # SX126X_MAX_POWER: 8
+  spidev: spidev0.0

bin/config.d/lora-lyra-zero-MeshAdv-Mini-900M22S.yaml

@@ -0,0 +1,33 @@
+# MeshAdv Mini E22-900M22S
+# https://github.com/chrismyers2000/MeshAdv-Mini
+Meta:
+  name: MeshAdv Mini E22-900M22S
+  support: community
+  compatible:
+    - luckfox-lyra-zero-w # Armbian
+
+Lora:
+  Module: sx1262 # Ebyte E22-900M22S
+  CS: # GPIO0_B2_d (phys 24, RPi CE0)
+    pin: 10
+    gpiochip: 0
+    line: 10
+  IRQ: # GPIO1_D1_d (phys 36, RPi GPIO16)
+    pin: 57
+    gpiochip: 1
+    line: 25
+  Busy: # GPIO0_C1_d (phys 38, RPi GPIO20)
+    pin: 17
+    gpiochip: 0
+    line: 17
+  Reset: # GPIO0_B4_d (phys 18, RPi GPIO24)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  RXen: # GPIO1_D2_d (phys 32, RPi GPIO12)
+    pin: 58
+    gpiochip: 1
+    line: 26
+  DIO2_AS_RF_SWITCH: true
+  DIO3_TCXO_VOLTAGE: true
+  spidev: spidev0.0

bin/config.d/lora-lyra-zero-RAK6421-13300-slot1.yaml

@@ -0,0 +1,38 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 1
+  support: community # Promote when tested
+  compatible:
+    - luckfox-lyra-zero-w # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_A5 (IO6)
+    pin: 5
+    gpiochip: 0
+    line: 5
+  Reset: # GPIO1_D1 (IO4)
+    pin: 57
+    gpiochip: 1
+    line: 25
+  Busy: # GPIO0_B4 (IO5)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  # Ant_sw: # GPIO1_C2 (IO3)
+  #   pin: 50
+  #   gpiochip: 1
+  #   line: 18
+  Enable_Pins:
+    - pin: 58 # GPIO1_D2
+      gpiochip: 1
+      line: 26
+    - pin: 50 # GPIO1_C2
+      gpiochip: 1
+      line: 18
+  DIO3_TCXO_VOLTAGE: true
+  DIO2_AS_RF_SWITCH: true
+  spidev: spidev0.0
+  # CS: # GPIO0_B2
+  #   pin: 10
+  #   gpiochip: 0
+  #   line: 10

bin/config.d/lora-lyra-zero-RAK6421-13300-slot2.yaml

@@ -0,0 +1,36 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 2
+  support: community # Promote when tested
+  compatible:
+    - luckfox-lyra-zero-w # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_B6 (IO6)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  Reset: # GPIO0_B4 (IO4)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  Busy: # GPIO1_C0 (IO5)
+    pin: 48
+    gpiochip: 1
+    line: 16
+  # Ant_sw: # GPIO0_B5 (IO3)
+  #   pin: 13
+  #   gpiochip: 0
+  #   line: 13
+  Enable_Pins:
+    - pin: 51 # GPIO1_C3
+      gpiochip: 1
+      line: 19
+    - pin: 13 # GPIO0_B5
+      gpiochip: 0
+      line: 13
+  spidev: spidev0.1
+  # CS: # GPIO0_B1
+  #   pin: 9
+  #   gpiochip: 0
+  #   line: 9

bin/config.d/lora-lyra-zero-RAK6421-13302-slot1.yaml

@@ -0,0 +1,39 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 1
+  support: community # Promote when tested
+  compatible:
+    - luckfox-lyra-zero-w # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_A5 (IO6)
+    pin: 5
+    gpiochip: 0
+    line: 5
+  Reset: # GPIO1_D1 (IO4)
+    pin: 57
+    gpiochip: 1
+    line: 25
+  Busy: # GPIO0_B4 (IO5)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  # Ant_sw: # GPIO1_C2 (IO3)
+  #   pin: 50
+  #   gpiochip: 1
+  #   line: 18
+  Enable_Pins:
+    - pin: 58 # GPIO1_D2
+      gpiochip: 1
+      line: 26
+    - pin: 50 # GPIO1_C2
+      gpiochip: 1
+      line: 18
+  DIO3_TCXO_VOLTAGE: true
+  DIO2_AS_RF_SWITCH: true
+  spidev: spidev0.0
+  # CS: # GPIO0_B2
+  #   pin: 10
+  #   gpiochip: 0
+  #   line: 10
+  TX_GAIN_LORA: [9, 9, 10, 11, 9, 8, 9, 10, 10, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12, 10, 9, 8]

bin/config.d/lora-lyra-zero-RAK6421-13302-slot2.yaml

@@ -0,0 +1,37 @@
+Meta:
+  name: RAK6421 + RAK13300 Slot 2
+  support: community # Promote when tested
+  compatible:
+    - luckfox-lyra-zero-w # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_B6 (IO6)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  Reset: # GPIO0_B4 (IO4)
+    pin: 12
+    gpiochip: 0
+    line: 12
+  Busy: # GPIO1_C0 (IO5)
+    pin: 48
+    gpiochip: 1
+    line: 16
+  # Ant_sw: # GPIO0_B5 (IO3)
+  #   pin: 13
+  #   gpiochip: 0
+  #   line: 13
+  Enable_Pins:
+    - pin: 51 # GPIO1_C3
+      gpiochip: 1
+      line: 19
+    - pin: 13 # GPIO0_B5
+      gpiochip: 0
+      line: 13
+  spidev: spidev0.1
+  # CS: # GPIO0_B1
+  #   pin: 9
+  #   gpiochip: 0
+  #   line: 9
+  TX_GAIN_LORA: [9, 9, 10, 11, 9, 8, 9, 10, 10, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12, 10, 9, 8]

bin/config.d/lora-lyra-zero-waveshare-sxxx.yaml

@@ -0,0 +1,30 @@
+Meta:
+  name: Waveshare SX1262
+  support: deprecated
+  compatible:
+    - luckfox-lyra-zero-w # Armbian
+
+Lora:
+  Module: sx1262  # Waveshare SX126X XXXM
+  DIO2_AS_RF_SWITCH: true
+  CS: # GPIO0_C2 (physical 40)
+    pin: 18
+    gpiochip: 0
+    line: 18
+  IRQ: # GPIO1_D1 (physical 36)
+    pin: 57
+    gpiochip: 1
+    line: 25
+  Busy: # GPIO0_C1 (physical 38)
+    pin: 17
+    gpiochip: 0
+    line: 17
+  Reset: # GPIO0_B6 (physical 12)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  SX126X_ANT_SW: # GPIO1_B3 (physical 31)
+    pin: 43
+    gpiochip: 1
+    line: 11
+  spidev: spidev0.0

bin/config.d/lora-meshstick-1262.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: Lora Meshstick SX1262
+  support: official
+  compatible:
+    - usb
+
 Lora:
   Module: sx1262
   CS: 0

bin/config.d/lora-ok3506-MeshAdv-900M30S.yaml

@@ -0,0 +1,41 @@
+# !! WARNING: Hats on the OK3506 board are installed "backwards" (facing outwards)
+
+# MeshAdv-Pi E22-900M30S
+# https://github.com/chrismyers2000/MeshAdv-Pi-Hat
+Meta:
+  name: MeshAdv-Pi E22-900M30S
+  support: community
+  compatible:
+    - forlinx-ok3506-s12 # Armbian
+
+Lora:
+  Module: sx1262
+  CS: # GPIO0_B0 (physical 40)
+    pin: 8
+    gpiochip: 0
+    line: 8
+  IRQ: # GPIO3_B0 (physical 36)
+    pin: 104
+    gpiochip: 3
+    line: 8
+  Busy: # GPIO0_B1 (physical 38)
+    pin: 9
+    gpiochip: 0
+    line: 9
+  Reset: # GPIO0_B6 (physical 12)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  TXen: # GPIO0_A3 (physical 33)
+    pin: 3
+    gpiochip: 0
+    line: 3
+  RXen: # GPIO0_A2 (physical 32)
+    pin: 2
+    gpiochip: 0
+    line: 2
+  DIO3_TCXO_VOLTAGE: true
+  # Only for E22-900M33S:
+  # Limit the output power to 8 dBm
+  # SX126X_MAX_POWER: 8
+  spidev: spidev0.0

bin/config.d/lora-ok3506-MeshAdv-Mini-900M22S.yaml

@@ -0,0 +1,35 @@
+# !! WARNING: Hats on the OK3506 board are installed "backwards" (facing outwards)
+
+# MeshAdv Mini E22-900M22S
+# https://github.com/chrismyers2000/MeshAdv-Mini
+Meta:
+  name: MeshAdv Mini E22-900M22S
+  support: community
+  compatible:
+    - forlinx-ok3506-s12 # Armbian
+
+Lora:
+  Module: sx1262 # Ebyte E22-900M22S
+  CS: # GPIO0_C3 (physical 24, SPI0_CSN0)
+    pin: 19
+    gpiochip: 0
+    line: 19
+  IRQ: # GPIO3_B0 (physical 36)
+    pin: 104
+    gpiochip: 3
+    line: 8
+  Busy: # GPIO0_B1 (physical 38)
+    pin: 9
+    gpiochip: 0
+    line: 9
+  Reset: # GPIO3_A6 (physical 18)
+    pin: 102
+    gpiochip: 3
+    line: 6
+  RXen: # GPIO0_A2 (physical 32)
+    pin: 2
+    gpiochip: 0
+    line: 2
+  DIO2_AS_RF_SWITCH: true
+  DIO3_TCXO_VOLTAGE: true
+  spidev: spidev0.0

bin/config.d/lora-ok3506-RAK6421-13300-slot1.yaml

@@ -0,0 +1,40 @@
+# !! WARNING: Hats on the OK3506 board are installed "backwards" (facing outwards)
+
+Meta:
+  name: RAK6421 + RAK13300 Slot 1
+  support: community # Promote when tested
+  compatible:
+    - forlinx-ok3506-s12 # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO3_B5 (IO6, physical 15)
+    pin: 109
+    gpiochip: 3
+    line: 13
+  Reset: # GPIO3_B0 (IO4, physical 36)
+    pin: 104
+    gpiochip: 3
+    line: 8
+  Busy: # GPIO3_A6 (IO5, physical 18)
+    pin: 102
+    gpiochip: 3
+    line: 6
+  # Ant_sw: # GPIO0_A3 (IO3, physical 33)
+  #   pin: 3
+  #   gpiochip: 0
+  #   line: 3
+  Enable_Pins:
+    - pin: 2 # GPIO0_A2 (physical 32)
+      gpiochip: 0
+      line: 2
+    - pin: 3 # GPIO0_A3 (physical 33)
+      gpiochip: 0
+      line: 3
+  DIO3_TCXO_VOLTAGE: true
+  DIO2_AS_RF_SWITCH: true
+  spidev: spidev0.0
+  # CS: # GPIO0_C3 (SPI0_CSN0, physical 24)
+  #   pin: 19
+  #   gpiochip: 0
+  #   line: 19

bin/config.d/lora-ok3506-RAK6421-13300-slot2.yaml

@@ -0,0 +1,38 @@
+# !! WARNING: Hats on the OK3506 board are installed "backwards" (facing outwards)
+
+Meta:
+  name: RAK6421 + RAK13300 Slot 2
+  support: community # Promote when tested
+  compatible:
+    - forlinx-ok3506-s12 # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_B6 (IO6, physical 12)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  Reset: # GPIO3_A6 (IO4, physical 18)
+    pin: 102
+    gpiochip: 3
+    line: 6
+  Busy: # GPIO0_B2 (IO5, physical 35)
+    pin: 10
+    gpiochip: 0
+    line: 10
+  # Ant_sw: # GPIO3_A7 (IO3, physical 16)
+  #   pin: 103
+  #   gpiochip: 3
+  #   line: 7
+  Enable_Pins:
+    - pin: 106 # GPIO3_B2 (physical 37)
+      gpiochip: 3
+      line: 10
+    - pin: 103 # GPIO3_A7 (physical 16)
+      gpiochip: 3
+      line: 7
+  spidev: spidev0.1
+  # CS: # GPIO0_B7 (SPI0_CSN1, physical 26)
+  #   pin: 15
+  #   gpiochip: 0
+  #   line: 15

bin/config.d/lora-ok3506-RAK6421-13302-slot1.yaml

@@ -0,0 +1,41 @@
+# !! WARNING: Hats on the OK3506 board are installed "backwards" (facing outwards)
+
+Meta:
+  name: RAK6421 + RAK13302 Slot 1
+  support: community # Promote when tested
+  compatible:
+    - forlinx-ok3506-s12 # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO3_B5 (IO6, physical 15)
+    pin: 109
+    gpiochip: 3
+    line: 13
+  Reset: # GPIO3_B0 (IO4, physical 36)
+    pin: 104
+    gpiochip: 3
+    line: 8
+  Busy: # GPIO3_A6 (IO5, physical 18)
+    pin: 102
+    gpiochip: 3
+    line: 6
+  # Ant_sw: # GPIO0_A3 (IO3, physical 33)
+  #   pin: 3
+  #   gpiochip: 0
+  #   line: 3
+  Enable_Pins:
+    - pin: 2 # GPIO0_A2 (physical 32)
+      gpiochip: 0
+      line: 2
+    - pin: 3 # GPIO0_A3 (physical 33)
+      gpiochip: 0
+      line: 3
+  DIO3_TCXO_VOLTAGE: true
+  DIO2_AS_RF_SWITCH: true
+  spidev: spidev0.0
+  # CS: # GPIO0_C3 (SPI0_CSN0, physical 24)
+  #   pin: 19
+  #   gpiochip: 0
+  #   line: 19
+  TX_GAIN_LORA: [9, 9, 10, 11, 9, 8, 9, 10, 10, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12, 10, 9, 8]

bin/config.d/lora-ok3506-RAK6421-13302-slot2.yaml

@@ -0,0 +1,39 @@
+# !! WARNING: Hats on the OK3506 board are installed "backwards" (facing outwards)
+
+Meta:
+  name: RAK6421 + RAK13302 Slot 2
+  support: community # Promote when tested
+  compatible:
+    - forlinx-ok3506-s12 # Armbian
+
+Lora:
+  Module: sx1262
+  IRQ: # GPIO0_B6 (IO6, physical 12)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  Reset: # GPIO3_A6 (IO4, physical 18)
+    pin: 102
+    gpiochip: 3
+    line: 6
+  Busy: # GPIO0_B2 (IO5, physical 35)
+    pin: 10
+    gpiochip: 0
+    line: 10
+  # Ant_sw: # GPIO3_A7 (IO3, physical 16)
+  #   pin: 103
+  #   gpiochip: 3
+  #   line: 7
+  Enable_Pins:
+    - pin: 106 # GPIO3_B2 (physical 37)
+      gpiochip: 3
+      line: 10
+    - pin: 103 # GPIO3_A7 (physical 16)
+      gpiochip: 3
+      line: 7
+  spidev: spidev0.1
+  # CS: # GPIO0_B7 (SPI0_CSN1, physical 26)
+  #   pin: 15
+  #   gpiochip: 0
+  #   line: 15
+  TX_GAIN_LORA: [9, 9, 10, 11, 9, 8, 9, 10, 10, 10, 11, 12, 12, 12, 12, 12, 12, 12, 12, 10, 9, 8]

bin/config.d/lora-ok3506-waveshare-sxxx.yaml

@@ -0,0 +1,32 @@
+# !! WARNING: Hats on the OK3506 board are installed "backwards" (facing outwards)
+
+Meta:
+  name: Waveshare SX1262
+  support: deprecated
+  compatible:
+    - forlinx-ok3506-s12 # Armbian
+
+Lora:
+  Module: sx1262  # Waveshare SX126X XXXM
+  DIO2_AS_RF_SWITCH: true
+  CS: # GPIO0_B0 (physical 40)
+    pin: 8
+    gpiochip: 0
+    line: 8
+  IRQ: # GPIO3_B0 (physical 36)
+    pin: 104
+    gpiochip: 3
+    line: 8
+  Busy: # GPIO0_B1 (physical 38)
+    pin: 9
+    gpiochip: 0
+    line: 9
+  Reset: # GPIO0_B6 (physical 12)
+    pin: 14
+    gpiochip: 0
+    line: 14
+  SX126X_ANT_SW: # GPIO3_B3 (physical 31)
+    pin: 107
+    gpiochip: 3
+    line: 11
+  spidev: spidev0.0

bin/config.d/lora-piggystick-lr1121.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: Lora Meshstick SX1262
+  support: community
+  compatible:
+    - usb
+
 Lora:
   Module: lr1121
   CS: 0

bin/config.d/lora-pinedio-usb-sx1262.yaml

@@ -1,5 +1,11 @@
+Meta:
+  name: Pinedio USB SX1262
+  support: deprecated
+  compatible:
+    - usb
+
 Lora:
   Module: sx1262
   CS: 0 
   IRQ: 10
-  spidev: ch341
+  spidev: ch341

bin/config.d/lora-raxda-rock2f-starter-edition-hat.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: raxda-rock2f-starter-edition-hat
+  support: community
+  compatible:
+    - rock-2f # Armbian
+
 Lora:
 
 ### Raxda Rock 2F running Armbian Linux 6.1.99-vendor-rk35xx

bin/config.d/lora-starter-edition-sx1262-i2c.yaml

@@ -1,5 +1,11 @@
 # https://www.waveshare.com/core1262-868m.htm
 # https://github.com/markbirss/lora-starter-edition-sx1262-i2c
+Meta:
+  name: lora-starter-edition-sx1262-i2c
+  support: community
+  compatible:
+    - raspberry-pi
+
 Lora:
   Module: sx1262  # Starter Edition SX1262 I2C Raspberry Pi HAT
   DIO2_AS_RF_SWITCH: true

bin/config.d/lora-usb-meshstick-1262.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: meshstick-1262
+  support: official
+  compatible:
+    - usb
+
 Lora:
   Module: sx1262
   CS: 0

bin/config.d/lora-usb-meshtoad-e22.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: meshtoad-e22
+  support: official
+  compatible:
+    - usb
+
 Lora:
   Module: sx1262
   CS: 0

bin/config.d/lora-usb-umesh-1262-30dbm.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: umesh-1262-30dbm
+  support: community
+  compatible:
+    - clockwork-uconsole
+
 Lora:
   Module: sx1262
   CS: 0

bin/config.d/lora-usb-umesh-1268-30dbm.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: umesh-1268-30dbm
+  support: community
+  compatible:
+    - clockwork-uconsole
+
 Lora:
   Module: sx1268
   CS: 0

bin/config.d/lora-waveshare-sxxx.yaml

@@ -1,3 +1,9 @@
+Meta:
+  name: Waveshare SX1262
+  support: deprecated
+  compatible:
+    - raspberry-pi
+
 Lora:
   Module: sx1262  # Waveshare SX126X XXXM
   DIO2_AS_RF_SWITCH: true

bin/config.d/lora-ws-raspberry-pi-pico-to-rpi-adapter.yaml

@@ -1,5 +1,12 @@
 # https://www.waveshare.com/pico-lora-sx1262-868m.htm
 # https://github.com/markbirss/lora-ws-raspberry-pi-pico-to-rpi-adapter
+
+Meta:
+  name: ws-raspberry-pico-to-rpi-adapter
+  support: community
+  compatible:
+    - raspberry-pi
+
 Lora:
   Module: sx1262  # Waveshare Raspberry Pi Pico to Raspberry Pi HAT Adapter
   DIO2_AS_RF_SWITCH: true

bin/config.d/lora-ws-raspberry-pico-to-orangepi-03.yaml

@@ -15,6 +15,12 @@
 #   5     CS          24
 #   26    DIO1/IRQ    26
 
+Meta:
+  name: ws-raspberry-pico-to-orangepi-03
+  support: community
+  compatible:
+    - orange-pi-zero-3 # Armbian
+
 Lora:
   Module: sx1262  # Waveshare Raspberry Pico Lora module
   DIO2_AS_RF_SWITCH: true

bin/generate_ci_matrix.py

@@ -43,7 +43,7 @@ for pio_env in pio_envs:
   env = {
     "ci": {"board": pio_env, "platform": env_platform},
     "board_level": cfg.get(f"env:{pio_env}", "board_level", default=None),
-    "board_check": bool(cfg.get(f"env:{pio_env}", "board_check", default=False)),
+    "board_check": cfg.get(f"env:{pio_env}", "board_check", default="false").strip().lower() == "true",
   }
   all_envs.append(env)
 

bin/generate_release_notes.py

@@ -1,25 +1,31 @@
 #!/usr/bin/env python3
-"""
-Generate release notes from merged PRs on develop and master branches.
-Categorizes PRs into Enhancements and Bug Fixes/Maintenance sections.
-"""
+"""Generate release notes from the actual release commit range."""
 
-import subprocess
-import re
+import argparse
 import json
+import re
+import subprocess
 import sys
-from datetime import datetime
 
 
-def get_last_release_tag():
-    """Get the most recent release tag."""
+def get_last_release_tag(compare_ref, exclude_tag=None):
+    """Get the most recent version tag merged into compare_ref."""
     result = subprocess.run(
-        ["git", "describe", "--tags", "--abbrev=0"],
+        ["git", "tag", "--merged", compare_ref, "--sort=-version:refname", "v*"],
         capture_output=True,
         text=True,
         check=True,
     )
-    return result.stdout.strip()
+
+    for line in result.stdout.splitlines():
+        candidate = line.strip()
+        if not candidate:
+            continue
+        if exclude_tag and candidate == exclude_tag:
+            continue
+        return candidate
+
+    raise subprocess.CalledProcessError(result.returncode, result.args, output=result.stdout, stderr=result.stderr)
 
 
 def get_tag_date(tag):
@@ -33,18 +39,18 @@ def get_tag_date(tag):
     return result.stdout.strip()
 
 
-def get_merged_prs_since_tag(tag, branch):
-    """Get all merged PRs since the given tag on the specified branch."""
-    # Get commits since tag on the branch - look for PR numbers in parentheses
+def get_merged_prs_in_range(tag, compare_ref):
+    """Get all merged PRs in the git range between tag and compare_ref."""
     result = subprocess.run(
         [
             "git",
             "log",
-            f"{tag}..origin/{branch}",
+            f"{tag}..{compare_ref}",
             "--oneline",
         ],
         capture_output=True,
         text=True,
+        check=True,
     )
 
     prs = []
@@ -65,6 +71,25 @@ def get_merged_prs_since_tag(tag, branch):
     return prs
 
 
+def parse_args():
+    """Parse CLI arguments."""
+    parser = argparse.ArgumentParser(
+        description="Generate release notes from the actual release commit range."
+    )
+    parser.add_argument("new_version", help="Version that will be tagged for this release")
+    parser.add_argument(
+        "--base-tag",
+        dest="base_tag",
+        help="Existing version tag to diff from. Defaults to the latest version tag merged into the compare ref.",
+    )
+    parser.add_argument(
+        "--compare-ref",
+        default="HEAD",
+        help="Git ref to diff to. Defaults to HEAD.",
+    )
+    return parser.parse_args()
+
+
 def get_pr_details(pr_number):
     """Get PR details from GitHub API via gh CLI."""
     try:
@@ -268,28 +293,28 @@ def get_new_contributors(pr_details_list, tag, repo="meshtastic/firmware"):
 
 
 def main():
-    if len(sys.argv) < 2:
-        print("Usage: generate_release_notes.py <new_version>", file=sys.stderr)
-        sys.exit(1)
-
-    new_version = sys.argv[1]
+    args = parse_args()
+    new_version = args.new_version
+    compare_ref = args.compare_ref
+    current_tag = f"v{new_version}"
 
     # Get last release tag
     try:
-        last_tag = get_last_release_tag()
+        last_tag = args.base_tag or get_last_release_tag(compare_ref, exclude_tag=current_tag)
     except subprocess.CalledProcessError:
         print("Error: Could not find last release tag", file=sys.stderr)
         sys.exit(1)
 
-    # Collect PRs from both branches
-    all_pr_numbers = set()
+    print(
+        f"Resolved release note range: {last_tag}..{compare_ref}",
+        file=sys.stderr,
+    )
 
-    for branch in ["develop", "master"]:
-        try:
-            prs = get_merged_prs_since_tag(last_tag, branch)
-            all_pr_numbers.update(prs)
-        except Exception as e:
-            print(f"Warning: Could not get PRs from {branch}: {e}", file=sys.stderr)
+    try:
+        all_pr_numbers = set(get_merged_prs_in_range(last_tag, compare_ref))
+    except subprocess.CalledProcessError as e:
+        print(f"Error: Could not get PRs for range {last_tag}..{compare_ref}: {e}", file=sys.stderr)
+        sys.exit(1)
 
     # Get details for all PRs
     enhancements = []

bin/org.meshtastic.meshtasticd.metainfo.xml

@@ -87,6 +87,12 @@
   </screenshots>
 
   <releases>
+    <release version="2.7.23" date="2026-04-14">
+      <url type="details">https://github.com/meshtastic/firmware/releases?q=tag%3Av2.7.23</url>
+    </release>
+    <release version="2.7.22" date="2026-04-06">
+      <url type="details">https://github.com/meshtastic/firmware/releases?q=tag%3Av2.7.22</url>
+    </release>
     <release version="2.7.21" date="2026-03-11">
       <url type="details">https://github.com/meshtastic/firmware/releases?q=tag%3Av2.7.21</url>
     </release>

boards/heltec_mesh_node_t096.json

@@ -0,0 +1,54 @@
+{
+  "build": {
+    "arduino": {
+      "ldscript": "nrf52840_s140_v6.ld"
+    },
+    "core": "nRF5",
+    "cpu": "cortex-m4",
+    "extra_flags": "-DNRF52840_XXAA",
+    "f_cpu": "64000000L",
+    "hwids": [
+      ["0x239A", "0x4405"],
+      ["0x239A", "0x0029"],
+      ["0x239A", "0x002A"],
+      ["0x2886", "0x1667"]
+    ],
+    "usb_product": "HT-n5262G",
+    "mcu": "nrf52840",
+    "variant": "heltec_mesh_node_t096",
+    "variants_dir": "variants",
+    "bsp": {
+      "name": "adafruit"
+    },
+    "softdevice": {
+      "sd_flags": "-DS140",
+      "sd_name": "s140",
+      "sd_version": "6.1.1",
+      "sd_fwid": "0x00B6"
+    },
+    "bootloader": {
+      "settings_addr": "0xFF000"
+    }
+  },
+  "connectivity": ["bluetooth"],
+  "debug": {
+    "jlink_device": "nRF52840_xxAA",
+    "onboard_tools": ["jlink"],
+    "svd_path": "nrf52840.svd",
+    "openocd_target": "nrf52840-mdk-rs"
+  },
+  "frameworks": ["arduino"],
+  "name": "Heltec nrf (Adafruit BSP)",
+  "upload": {
+    "maximum_ram_size": 248832,
+    "maximum_size": 815104,
+    "speed": 115200,
+    "protocol": "nrfutil",
+    "protocols": ["jlink", "nrfjprog", "nrfutil", "stlink"],
+    "use_1200bps_touch": true,
+    "require_upload_port": true,
+    "wait_for_upload_port": true
+  },
+  "url": "https://heltec.org/",
+  "vendor": "Heltec"
+}

boards/t5-epaper-s3.json

@@ -0,0 +1,38 @@
+{
+  "build": {
+    "arduino": {
+      "ldscript": "esp32s3_out.ld",
+      "memory_type": "qio_opi",
+      "partitions": "default_16MB.csv"
+    },
+    "core": "esp32",
+    "extra_flags": [
+      "-DBOARD_HAS_PSRAM",
+      "-DARDUINO_RUNNING_CORE=1",
+      "-DARDUINO_EVENT_RUNNING_CORE=0",
+      "-DARDUINO_USB_CDC_ON_BOOT=1",
+      "-DARDUINO_USB_MODE=1"
+    ],
+    "f_cpu": "240000000L",
+    "f_flash": "80000000L",
+    "flash_mode": "qio",
+    "hwids": [["0x303A", "0x1001"]],
+    "mcu": "esp32s3",
+    "variant": "esp32s3"
+  },
+  "connectivity": ["wifi", "bluetooth", "lora"],
+  "debug": {
+    "openocd_target": "esp32s3.cfg"
+  },
+  "frameworks": ["arduino", "espidf"],
+  "name": "LilyGo T5-ePaper-S3",
+  "upload": {
+    "flash_size": "16MB",
+    "maximum_ram_size": 327680,
+    "maximum_size": 16777216,
+    "require_upload_port": true,
+    "speed": 921600
+  },
+  "url": "https://lilygo.cc/products/t5-e-paper-s3-pro",
+  "vendor": "LILYGO"
+}

boards/ttgo-tbeam.json

@@ -0,0 +1,29 @@
+{
+  "build": {
+    "arduino": {
+      "ldscript": "esp32_out.ld"
+    },
+    "core": "esp32",
+    "extra_flags": "-DARDUINO_T_Beam",
+    "f_cpu": "240000000L",
+    "f_flash": "40000000L",
+    "flash_mode": "dio",
+    "mcu": "esp32",
+    "variant": "tbeam"
+  },
+  "connectivity": ["wifi", "bluetooth", "can", "ethernet"],
+  "debug": {
+    "openocd_board": "esp-wroom-32.cfg"
+  },
+  "frameworks": ["arduino", "espidf"],
+  "name": "TTGO T-Beam (PSRAM Disabled)",
+  "upload": {
+    "flash_size": "4MB",
+    "maximum_ram_size": 1310720,
+    "maximum_size": 4194304,
+    "require_upload_port": true,
+    "speed": 460800
+  },
+  "url": "https://github.com/LilyGO/TTGO-T-Beam",
+  "vendor": "TTGO"
+}

debian/changelog

@@ -1,3 +1,15 @@
+meshtasticd (2.7.23.0) unstable; urgency=medium
+
+  * Version 2.7.23
+
+ -- GitHub Actions <github-actions[bot]@users.noreply.github.com>  Tue, 14 Apr 2026 12:29:48 +0000
+
+meshtasticd (2.7.22.0) unstable; urgency=medium
+
+  * Version 2.7.22
+
+ -- GitHub Actions <github-actions[bot]@users.noreply.github.com>  Mon, 06 Apr 2026 11:34:12 +0000
+
 meshtasticd (2.7.21.0) unstable; urgency=medium
 
   * Version 2.7.21

debian/ci_pack_sdeb.sh

@@ -27,5 +27,10 @@ rm -rf debian/changelog
 dch --create --distribution "$SERIES" --package "$package" --newversion "$PKG_VERSION~$SERIES" \
 	"GitHub Actions Automatic packaging for $PKG_VERSION~$SERIES"
 
-# Build the source deb
-debuild -S -nc -k"$GPG_KEY_ID"
+if [[ -n $GPG_KEY_ID ]]; then
+	# Build and sign the source deb
+	debuild -S -nc -k"$GPG_KEY_ID"
+else
+	# Build the source deb without signing (forks)
+	debuild -S -nc
+fi

mcp-server/.gitignore

@@ -0,0 +1,29 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+
+# Test harness artifacts
+tests/report.html
+tests/junit.xml
+tests/reportlog.jsonl
+tests/fwlog.jsonl
+# Subprocess-output tee from pio/esptool/nrfutil/picotool (live flash
+# progress for the TUI; also a post-run diagnostic for plain CLI runs).
+tests/flash.log
+tests/tool_coverage.json
+tests/.coverage
+htmlcov/
+# Persistent run counter for meshtastic-mcp-test-tui header.
+tests/.tui-runs
+# Cross-run history (TUI duration sparkline).
+tests/.history/
+# Reproducer bundles (TUI `x` export on failed tests).
+tests/reproducers/
+# UI-tier camera captures + per-test transcripts. Regenerated every run;
+# left on disk for human review between runs.
+tests/ui_captures/

mcp-server/README.md

@@ -0,0 +1,354 @@
+# Meshtastic MCP Server
+
+An [MCP](https://modelcontextprotocol.io) server for working with the Meshtastic firmware repo and connected devices. Lets Claude Code / Claude Desktop:
+
+- Discover USB-connected Meshtastic devices
+- Enumerate PlatformIO board variants (166+) with Meshtastic metadata
+- Build, clean, flash, erase-and-flash (factory), and OTA-update firmware
+- Read serial logs via `pio device monitor` (with board-specific exception decoders)
+- Trigger 1200bps touch-reset for bootloader entry (nRF52, ESP32-S3, RP2040)
+- Query and administer a running node via the [`meshtastic` Python API](https://github.com/meshtastic/python): owner name, config (LocalConfig + ModuleConfig), channels, messaging, reboot/shutdown/factory-reset
+- Call `esptool`, `nrfutil`, `picotool` directly when PlatformIO doesn't cover the operation
+
+## Design principle
+
+**PlatformIO first.** Its `pio run -t upload` knows the correct protocol, offsets, and post-build chain for every variant in `variants/`. Direct vendor-tool wrappers (`esptool_*`, `nrfutil_*`, `picotool_*`) exist as escape hatches for operations pio doesn't cover (blank-chip erase, DFU `.zip` packages, BOOTSEL-mode inspection).
+
+## Prerequisites
+
+- Python ≥ 3.11
+- [PlatformIO Core](https://platformio.org/install/cli) — `pio` on `$PATH` or at `~/.platformio/penv/bin/pio`
+- The Meshtastic firmware repo checked out somewhere (set via `MESHTASTIC_FIRMWARE_ROOT`)
+- Optional: `esptool`, `nrfutil`, `picotool` on `$PATH` (or under the firmware venv at `.venv/bin/`) if you want to use the direct-tool wrappers
+
+## Install
+
+```bash
+cd <firmware-repo>/mcp-server
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+Verify:
+
+```bash
+MESHTASTIC_FIRMWARE_ROOT=<firmware-repo> .venv/bin/python -m meshtastic_mcp
+```
+
+The server blocks on stdin (that's correct — it speaks MCP over stdio). Ctrl-C to exit.
+
+## Register with Claude Code
+
+Edit `~/.claude/settings.json` (global) or `<firmware-repo>/.claude/settings.local.json` (project-only):
+
+```json
+{
+  "mcpServers": {
+    "meshtastic": {
+      "command": "<firmware-repo>/mcp-server/.venv/bin/python",
+      "args": ["-m", "meshtastic_mcp"],
+      "env": {
+        "MESHTASTIC_FIRMWARE_ROOT": "<firmware-repo>"
+      }
+    }
+  }
+}
+```
+
+Replace `<firmware-repo>` with the absolute path, e.g. `/Users/you/GitHub/firmware`. Restart Claude Code after editing.
+
+## Register with Claude Desktop
+
+Same `mcpServers` block, but in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
+
+## Tools (43)
+
+### Discovery & metadata
+
+| Tool           | What it does                                                                               |
+| -------------- | ------------------------------------------------------------------------------------------ |
+| `list_devices` | USB/serial port listing, flags likely-Meshtastic candidates                                |
+| `list_boards`  | PlatformIO envs with `custom_meshtastic_*` metadata; filters by arch/supported/query/level |
+| `get_board`    | Full env dict incl. raw pio config                                                         |
+
+### Build & flash
+
+| Tool              | What it does                                                         |
+| ----------------- | -------------------------------------------------------------------- |
+| `build`           | `pio run -e <env>` (+ mtjson target)                                 |
+| `clean`           | `pio run -e <env> -t clean`                                          |
+| `pio_flash`       | `pio run -e <env> -t upload --upload-port <port>` — any architecture |
+| `erase_and_flash` | ESP32 full factory flash via `bin/device-install.sh`                 |
+| `update_flash`    | ESP32 OTA app-partition update via `bin/device-update.sh`            |
+| `touch_1200bps`   | 1200-baud open/close to trigger USB CDC bootloader entry             |
+
+### Serial log sessions
+
+Backed by long-running `pio device monitor` subprocesses with a 10k-line ring buffer per session and board-specific filters (`esp32_exception_decoder` auto-selected when you pass `env=`).
+
+| Tool           | What it does                                                       |
+| -------------- | ------------------------------------------------------------------ |
+| `serial_open`  | Start a monitor session; returns `session_id`                      |
+| `serial_read`  | Cursor-based pull; reports `dropped` if lines aged out of the ring |
+| `serial_list`  | All active sessions                                                |
+| `serial_close` | Terminate a session                                                |
+
+### Device reads
+
+| Tool          | What it does                                                                |
+| ------------- | --------------------------------------------------------------------------- |
+| `device_info` | my_node_num, long/short name, firmware version, region, channel, node count |
+| `list_nodes`  | Full node database with position, SNR, RSSI, last_heard, battery            |
+
+_The tool tables below document 38 currently registered MCP server tools._
+
+### Device writes
+
+| Tool                | What it does                                                               |
+| ------------------- | -------------------------------------------------------------------------- |
+| `set_owner`         | Long name + optional short name (≤4 chars)                                 |
+| `get_config`        | One section or all (LocalConfig + ModuleConfig)                            |
+| `set_config`        | Dot-path field write: `lora.region`=`"US"`, `device.role`=`"ROUTER"`, etc. |
+| `get_channel_url`   | Primary-only or include_all=admin URL                                      |
+| `set_channel_url`   | Import channels from a Meshtastic URL                                      |
+| `set_debug_log_api` | Enable or disable debug logging for the Meshtastic Python API client       |
+| `send_text`         | Broadcast or direct text message                                           |
+| `reboot`            | `localNode.reboot(secs)` — requires `confirm=True`                         |
+| `shutdown`          | `localNode.shutdown(secs)` — requires `confirm=True`                       |
+| `factory_reset`     | `localNode.factoryReset(full?)` — requires `confirm=True`                  |
+
+### Direct hardware tools (escape hatches)
+
+| Tool                  | What it does                                              |
+| --------------------- | --------------------------------------------------------- |
+| `esptool_chip_info`   | Read chip, MAC, crystal, flash size                       |
+| `esptool_erase_flash` | Full-chip erase (destructive)                             |
+| `esptool_raw`         | Pass-through; confirm=True required for write/erase/merge |
+| `nrfutil_dfu`         | DFU-flash a `.zip` package                                |
+| `nrfutil_raw`         | Pass-through                                              |
+| `picotool_info`       | Read Pico BOOTSEL-mode info                               |
+| `picotool_load`       | Load a UF2                                                |
+| `picotool_raw`        | Pass-through                                              |
+
+### USB power control (uhubctl)
+
+| Tool            | What it does                                                |
+| --------------- | ----------------------------------------------------------- |
+| `uhubctl_list`  | Enumerate USB hubs + attached-device VID/PID (read-only)    |
+| `uhubctl_power` | Drive a hub port `on` or `off`; `off` requires confirm=True |
+| `uhubctl_cycle` | Off → wait `delay_s` → on; confirm=True required            |
+
+Target a port by explicit `(location, port)` (raw uhubctl syntax like
+`location="1-1.3", port=2`) or by `role` (`"nrf52"`, `"esp32s3"`). Role
+lookup checks `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` +
+`MESHTASTIC_UHUBCTL_PORT_<ROLE>` env vars first, then auto-detects via VID
+against `uhubctl`'s output.
+
+Requires [`uhubctl`](https://github.com/mvp/uhubctl) on PATH:
+
+```bash
+brew install uhubctl        # macOS
+apt install uhubctl         # Debian/Ubuntu
+```
+
+Modern macOS + PPPS-capable hubs generally work without root. On Linux
+without udev rules, or on old macOS with driver quirks, you may need
+`sudo`. If uhubctl returns a permission error the MCP tool raises a
+clear `UhubctlError` pointing at the
+[udev-rules / sudo fallback](https://github.com/mvp/uhubctl#linux-usb-permissions)
+rather than auto-`sudo`'ing mid-run.
+
+## Safety
+
+- **All destructive flash/admin tools require `confirm=True`** as a tool-level gate, on top of any permission prompt from Claude.
+- **Serial port is exclusive.** If a `serial_*` session is active on a port, `device_info`/admin tools on the same port will fail fast with a pointer at the active `session_id`. Close the session first.
+- **Flash confirmation by architecture**: `erase_and_flash` / `update_flash` error if the env's architecture isn't ESP32 — use `pio_flash` for nRF52/RP2040/STM32.
+
+## Environment variables
+
+| Var                        | Default                                                     | Purpose                                                             |
+| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
+| `MESHTASTIC_FIRMWARE_ROOT` | walks up from cwd for `platformio.ini`                      | Pin the firmware repo                                               |
+| `MESHTASTIC_PIO_BIN`       | `~/.platformio/penv/bin/pio` → `$PATH` `pio` → `platformio` | Override `pio` location                                             |
+| `MESHTASTIC_ESPTOOL_BIN`   | `<firmware>/.venv/bin/esptool` → `$PATH`                    | Override esptool                                                    |
+| `MESHTASTIC_NRFUTIL_BIN`   | `$PATH`                                                     | Override nrfutil                                                    |
+| `MESHTASTIC_PICOTOOL_BIN`  | `$PATH`                                                     | Override picotool                                                   |
+| `MESHTASTIC_MCP_SEED`      | `mcp-<user>-<host>`                                         | PSK seed for test-harness session (CI override)                     |
+| `MESHTASTIC_MCP_FLASH_LOG` | `<mcp-server>/tests/flash.log`                              | Tee target for pio/esptool/nrfutil subprocess output (TUI tails it) |
+
+## Hardware Test Suite
+
+`mcp-server/tests/` holds a pytest-based integration suite that exercises
+real USB-connected Meshtastic devices against the MCP server surface. Separate
+from the native C++ unit tests in the firmware repo's top-level `test/`
+directory — this one validates the device-facing behavior end-to-end.
+
+### Invocation
+
+```bash
+./mcp-server/run-tests.sh                               # full suite (auto-detect + auto-bake-if-needed)
+./mcp-server/run-tests.sh --force-bake                  # reflash devices before testing
+./mcp-server/run-tests.sh --assume-baked                # skip the bake step (caller vouches for state)
+./mcp-server/run-tests.sh tests/mesh                    # one tier
+./mcp-server/run-tests.sh tests/mesh/test_traceroute.py # one file
+./mcp-server/run-tests.sh -k telemetry                  # pytest name filter
+```
+
+The wrapper auto-detects connected devices (VID `0x239A` → `nrf52` → env
+`rak4631`; `0x303A` or `0x10C4` → `esp32s3` → env `heltec-v3`), exports
+`MESHTASTIC_MCP_ENV_<ROLE>` env vars, and invokes pytest. Overrides via
+per-role env vars: `MESHTASTIC_MCP_ENV_NRF52=heltec-mesh-node-t114 ./run-tests.sh`.
+
+No hardware connected? The wrapper narrows to `tests/unit/` only and says so
+in the pre-flight header.
+
+### Tiers (run in this order)
+
+- **`bake`** (`tests/test_00_bake.py`) — flashes both hub roles with the
+  session's test profile. Has a skip-if-already-baked check (region + channel
+  match); `--force-bake` overrides.
+- **`unit`** — pure Python, no hardware. boards / PIO wrapper /
+  userPrefs-parse / testing-profile fixtures.
+- **`mesh`** — 2-device mesh: formation, broadcast delivery, direct+ACK,
+  traceroute, bidirectional. Parametrized over both directions. Includes
+  `test_peer_offline_recovery` which uses uhubctl to power-cycle one peer
+  mid-conversation and verifies the mesh recovers (skips without uhubctl).
+- **`telemetry`** — periodic telemetry broadcast + on-demand request/reply
+  (`TELEMETRY_APP` with `wantResponse=True`).
+- **`monitor`** — boot log has no panic markers within 60 s of reboot.
+- **`recovery`** — `uhubctl` power-cycle round-trip: verifies the hub port
+  can be toggled off/on, the device re-enumerates with the same
+  `my_node_num`, and NVS-resident config (region, channel, modem preset)
+  survives a hard reset. Requires `uhubctl` on PATH; skips cleanly otherwise.
+- **`ui`** — input-broker-driven screen navigation (`AdminMessage.send_input_event`
+  injection → `Screen::handleInputEvent` → frame transition). Parametrized
+  on the screen-bearing role (heltec-v3 OLED). Captures images via USB
+  webcam + OCRs them for HTML-report evidence. Requires `pip install -e '.[ui]'`
+  and `MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=<index>`; tier is auto-deselected
+  if `cv2` isn't importable.
+- **`fleet`** — PSK-seed isolation: two labs with different seeds never
+  overlap.
+- **`admin`** — owner persistence across reboot, channel URL round-trip,
+  `lora.hop_limit` persistence.
+- **`provisioning`** — region/channel baking, userPrefs survive
+  `factory_reset(full=False)`.
+
+#### UI tier setup
+
+The `tests/ui/` tier drives the on-device OLED via the firmware's existing
+`AdminMessage.send_input_event` RPC (no firmware changes required) and
+verifies transitions via a macro-gated log line + camera + OCR. Summary:
+
+1. Install extras: `pip install -e 'mcp-server/.[ui]'` — pulls in
+   `opencv-python-headless`, `numpy`, `easyocr`, `Pillow`. First easyocr
+   run downloads ~100 MB of models to `~/.EasyOCR/`; an autouse session
+   fixture pre-warms the reader so per-test OCR is <100 ms after that.
+2. Point a USB webcam at the heltec-v3 OLED. Discover its index:
+   ```bash
+   .venv/bin/python -c "import cv2; [print(i, cv2.VideoCapture(i).read()[0]) for i in range(5)]"
+   ```
+3. Export the per-role device env var:
+   ```bash
+   export MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=0
+   ```
+4. Run:
+   ```bash
+   ./run-tests.sh tests/ui -v
+   ```
+   Captures land under `tests/ui_captures/<session_seed>/<test_id>/`, one
+   PNG + `.ocr.txt` per `frame_capture()` call, with a per-test
+   `transcript.md` stepping through event → frame → OCR. The HTML report
+   embeds the full image strip inline (pass or fail).
+
+On macOS, `cv2.VideoCapture(0)` triggers the TCC Camera permission prompt
+on first use. Pre-grant Terminal (or your IDE's terminal) before running.
+The `OpenCVBackend` fails fast on 10 consecutive black frames so a silent
+permission denial surfaces as a clear error, not an empty PNG strip.
+
+No camera? Set `MESHTASTIC_UI_CAMERA_BACKEND=null` (or leave the device var
+unset). Tests still exercise the event-injection path and log assertions;
+captures just become 1×1 black PNGs.
+
+### Artifacts (regenerated every run, under `tests/`)
+
+- `report.html` — self-contained pytest-html report. Each test gets a
+  **Meshtastic debug** section attached on failure with a 200-line firmware
+  log tail + device-state dump. Open this first on failures.
+- `junit.xml` — CI-parseable.
+- `reportlog.jsonl` — `pytest-reportlog` event stream; consumed by the TUI.
+- `fwlog.jsonl` — firmware log mirror (`meshtastic.log.line` pubsub → JSONL).
+- `flash.log` — tee of all pio / esptool / nrfutil / picotool subprocess
+  output during the run (driven by `MESHTASTIC_MCP_FLASH_LOG`).
+
+### Live TUI
+
+```bash
+.venv/bin/meshtastic-mcp-test-tui
+.venv/bin/meshtastic-mcp-test-tui tests/mesh    # pytest args pass through
+```
+
+Textual-based wrapper over `run-tests.sh` with a live test tree, tier
+counters, pytest output pane, firmware-log pane, and a device-status strip.
+Key bindings: `r` re-run focused, `f` filter, `d` failure detail, `g` open
+`report.html`, `x` export reproducer bundle, `l` cycle fw-log filter, `q`
+quit (SIGINT → SIGTERM → SIGKILL escalation).
+
+Set `MESHTASTIC_UI_TUI_CAMERA=1` to mount a bottom-of-screen **UI camera**
+panel. Left side: the latest capture PNG rendered as Unicode half-blocks
+(via `rich-pixels`, works in any terminal — no kitty/sixel required).
+Right side: live transcript tail ("step 3 — frame 4/8 name=nodelist_nodes
+— OCR: Nodes 2/2") so you can see every event-injection and its result
+as each UI test runs. Requires the `[ui]` extras for image rendering; the
+transcript alone works without them.
+
+### Slash commands
+
+Three AI-assisted workflows are wired up for Claude Code operators
+(`.claude/commands/`) and Copilot operators (`.github/prompts/`):
+`/test` (run + interpret), `/diagnose` (read-only health report), `/repro`
+(flake triage, N-times re-run with log diff).
+
+### House rules (for human + agent contributors)
+
+- Session-scoped fixtures in `tests/conftest.py` snapshot + restore
+  `userPrefs.jsonc`; **never edit `userPrefs.jsonc` from inside a test**.
+  Use the `test_profile` / `no_region_profile` fixtures for ephemeral
+  overrides.
+- `SerialInterface` holds an **exclusive port lock**; sequence calls
+  open → mutate → close, then next device. No parallel calls to the
+  same port.
+- Directed PKI-encrypted sends need **bilateral NodeInfo warmup** —
+  both sides must hold the other's current pubkey. See
+  `tests/mesh/_receive.py::nudge_nodeinfo_port` and the three directed-
+  send tests (`test_direct_with_ack`, `test_traceroute`,
+  `test_telemetry_request_reply`) for the canonical pattern.
+
+## Layout
+
+```text
+mcp-server/
+├── pyproject.toml
+├── README.md
+└── src/meshtastic_mcp/
+    ├── __main__.py         # entry: python -m meshtastic_mcp
+    ├── server.py           # FastMCP app + @app.tool() registrations (thin)
+    ├── config.py           # firmware_root, pio_bin, esptool_bin, etc.
+    ├── pio.py              # subprocess wrapper (timeouts, JSON, tail_lines)
+    ├── devices.py          # list_devices (findPorts + comports)
+    ├── boards.py           # list_boards / get_board (pio project config parse + cache)
+    ├── flash.py            # build, clean, flash, erase_and_flash, update_flash, touch_1200bps
+    ├── serial_session.py   # SerialSession + reader thread + ring buffer
+    ├── registry.py         # session registry + per-port locks
+    ├── connection.py       # connect(port) ctx mgr — SerialInterface + port lock
+    ├── info.py             # device_info, list_nodes
+    ├── admin.py            # set_owner, get/set_config, channels, send_text, reboot/shutdown/factory_reset
+    └── hw_tools.py         # esptool / nrfutil / picotool wrappers
+```
+
+## Troubleshooting
+
+- **"Could not locate Meshtastic firmware root"** — set `MESHTASTIC_FIRMWARE_ROOT`.
+- **"Could not find `pio`"** — install PlatformIO or set `MESHTASTIC_PIO_BIN`.
+- **"Port is held by serial session ..."** — call `serial_close(session_id)` or `serial_list` to find it.
+- **`factory.bin` not found after build** — the env may not be ESP32; only ESP32 envs produce a `.factory.bin`.
+- **`touch_1200bps` reported `new_port: null`** — the device may not have 1200bps-reset stdio, or the bootloader re-uses the same port name. Check `list_devices` manually.