Add support for Wi-Fi HaLow on Seeed XIAO ESP32-S3

Add max_session_seconds to LockdownAuth for session management
Clamp direct position packets to channel precision (fixes #8640 ) (#10383 )
2026-05-16 09:48:17 -05:00 · 2026-05-15 15:14:29 -05:00 · 2026-05-14 20:51:44 -05:00 · 2026-05-13 19:36:15 -05:00 · 2026-05-13 14:33:15 -05:00 · 2026-05-13 13:50:17 -05:00
397 changed files with 33457 additions and 2983 deletions
@@ -49,11 +49,17 @@ Call the meshtastic MCP tool bundle and format a structured health report for on
   - 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**:
+7. **Recorder slice (cheap, always available).** The mcp-server runs an autouse log recorder that's been collecting from every connected device. Pull two short slices to surface anything weird that's already happened:
+   - `mcp__meshtastic__logs_window(start="-2m", level="WARN|ERROR|CRIT", max_lines=20)` — recent firmware errors. If empty, say "no recent errors"; don't manufacture concern.
+   - `mcp__meshtastic__telemetry_timeline(window="1h", field="free_heap", max_points=60)` — heap trend. If `slope_per_min < -50`, flag it and recommend `/leakhunt window=6h` for a deeper read; otherwise just note the current free heap.
+   - If `recorder_status` shows `running:false` or `files.telemetry.last_ts` is null, note "recorder has no telemetry yet — enable `set_debug_log_api(True)` to populate" and skip this step gracefully.
+
+8. **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`.
+   - Heap slope strongly negative → "run `/leakhunt window=6h` for a full timeline + classification."

 ## What NOT to do

@@ -0,0 +1,103 @@
+---
+description: Hunt for memory leaks (and other slow degradations) by reading the persistent recorder's heap timeline + log slice over a window
+argument-hint: [window=1h] [field=free_heap] [variant=local]
+---
+
+<!-- markdownlint-disable MD029 -->
+
+# `/leakhunt` — read the recorder, classify a memory leak
+
+Use the always-on recorder (`mcp-server/.mtlog/`) to read a heap timeline plus the matching log slice and produce a one-page verdict: **steady / slow leak / fragmentation / OOM-imminent**. No firmware changes, no special build flags — the LocalStats telemetry packet that the firmware already broadcasts every ~60 s carries `heap_free_bytes` and `heap_total_bytes`.
+
+## Two signal paths — pick the right one
+
+| Path                  | Build flag       | Cadence        | Per-thread attribution | Cost                      |
+| --------------------- | ---------------- | -------------- | ---------------------- | ------------------------- |
+| LocalStats packet     | (default)        | ~60 s          | No                     | Free — always on          |
+| `[heap N]` log prefix | `-DDEBUG_HEAP=1` | every log line | Yes (Thread X leaked)  | Bigger flash + log volume |
+
+Both feed the same `telemetry_timeline(field="free_heap")` query — when DEBUG_HEAP is on, the recorder synthesizes telemetry rows from log prefixes (tagged `source: debug_heap`), so a single timeline call gets whichever signal is available. **For a slow leak diagnosis, the default path is plenty** (60 s cadence over 6 h = 360 points; linear regression over that nails sub-100-byte/min slopes). **DEBUG_HEAP is for attribution** — when the slope is real and you need to know which thread is leaking.
+
+## What to do
+
+1. **Parse `$ARGUMENTS`**: optional `window` (default `1h`, accepts `30m`/`6h`/`-3d`/etc.), optional `field` (default `free_heap`; alternates: `total_heap`, `battery_level`, anything in the LocalStats variant), optional `variant` (default `local`; alternates: `device`, `environment`, `power`, `airQuality`, `health`).
+
+2. **Verify the recorder is alive** — call `mcp__meshtastic__recorder_status`. Check:
+   - `running == True`
+   - `files.telemetry.lines > 0` (at least one telemetry packet recorded — if zero, the device hasn't broadcast LocalStats yet OR `set_debug_log_api` has never been on; tell the operator to run `mcp__meshtastic__set_debug_log_api(enabled=True)` and wait one device-update interval)
+   - `files.telemetry.last_ts` within the last 5 minutes (if older, the device is silent — log that, not "leak detected")
+
+3. **Detect whether DEBUG_HEAP is active** — `mcp__meshtastic__logs_window(start="-2m", grep=r"\\[heap \\d+\\]", max_lines=3)`. If any line matches, the firmware has the prefix → DEBUG_HEAP is on, expect higher-cadence data and `heap_event` rows. If zero matches over the last 2 minutes, you're on the LocalStats-only path.
+
+4. **Pull the timeline** — `mcp__meshtastic__telemetry_timeline(window=$window, variant=$variant, field=$field, max_points=200)`. Read:
+   - `samples` — how many raw points contributed
+   - `min`, `max` — total swing
+   - `slope_per_min` — units per minute (linear regression over the whole window)
+
+5. **Pull the log context for the same window** — `mcp__meshtastic__logs_window(start="-${window}", grep="Heap status|leaked heap|freed heap|out of memory|Alloc an err|panic|abort", max_lines=200)`. These are the strings the firmware emits when something memory-related happens (`DEBUG_HEAP` builds emit `"Heap status:"` and `"leaked heap"` lines; production builds emit `"Alloc an err"` on failure and `"out of memory"` on OOM).
+
+6. **Pull marker events** so we know if the operator labeled phases — `mcp__meshtastic__events_window(start="-${window}", kind="mark|connection_lost|connection_established")`. If a `connection_lost` overlaps a sharp drop, that's not a leak; that's a reboot.
+
+6a. **(DEBUG_HEAP only) Per-thread attribution** — `mcp__meshtastic__logs_window(start="-${window}", grep="leaked heap", max_lines=200)`. Each row has a structured `heap_event` field with `{kind, thread, before, after, delta}`. Aggregate by thread: sum the `delta` over the window per thread name. The thread with the largest cumulative negative delta is your suspect. Note the count too — a thread with 50× small leaks is different from 1× big leak.
+
+7. **Classify** based on what the data says, NOT on what you wish it said. Use these rules in order:
+   - **Insufficient data** (< 5 samples): say so. Suggest a longer window or longer wait. Stop.
+   - **Reboot mid-window**: if any `connection_lost` event is present AND `free_heap` jumped UP at that timestamp, the device rebooted. Note it; pre-reboot trend may be a leak but you only have part of the curve.
+   - **OOM-imminent**: any `Alloc an err=` or `out of memory` line in the log slice. This trumps everything; flag urgently.
+   - **Slow leak**: `slope_per_min < -50` AND `max - min > 1000` AND no reboot. The heap is monotonically (or near-monotonically) declining. Estimate time-to-zero: `min / -slope_per_min` minutes. Surface it.
+   - **Fragmentation suspect**: `slope_per_min` close to zero (|x| < 50) BUT min trends down across the window AND the log slice shows `Alloc an err` warnings WITHOUT total OOM. Means free total is OK but largest contiguous block is shrinking. Recommend a `DEBUG_HEAP` build to confirm.
+   - **Steady**: |slope_per_min| < 50, no error lines. Heap is fine.
+   - **Recovery curve**: slope is POSITIVE — heap recovered. Either a workload completed or GC fired. Note it; not a leak.
+
+8. **Report**:
+
+   ```text
+   /leakhunt window=6h field=free_heap variant=local
+   ────────────────────────────────────────────────────
+   recorder        : running, telem last_ts 8s ago
+   build           : DEBUG_HEAP=ON (per-line prefix detected)
+   samples         : 14,200 over 6h (cadence ~1.5s, log-line synth)
+   free_heap       : min 92,344 / max 124,008 / range 31,664
+   slope           : -82 bytes/min (negative — heap declining)
+   reboots         : none in window
+   OOM events      : none
+   error lines     : 3× "Alloc an err=ESP_ERR_NO_MEM" at +4h12m, +5h08m, +5h44m
+   thread leaks    : (DEBUG_HEAP) MeshPacket -3,124 B over 18 events
+                                  Router       -1,408 B over 4 events
+                                  others       -240 B
+   verdict         : SLOW LEAK — primary suspect MeshPacket thread
+   est. time-to-OOM: ~1,127 min (~18.8 h) at current slope
+   evidence        : (3 log line citations with uptimes)
+   ```
+
+   Then: **what to do next.**
+   - SLOW LEAK, **DEBUG_HEAP off** → recommend rebuilding with the flag and re-running this skill. Concrete one-liner the operator can copy:
+     ```text
+     mcp__meshtastic__build(env="<env>", build_flags={"DEBUG_HEAP": 1})
+     mcp__meshtastic__pio_flash(env="<env>", port="<port>", confirm=True)
+     ```
+     After flash, set debug_log_api back on and wait one window; re-run `/leakhunt`.
+   - SLOW LEAK, **DEBUG_HEAP on** → cite the top-leaking thread name from step 6a. Point at the corresponding source file (`grep -rn "ThreadName(\"<name>\")" src/`); the operator decides what to fix.
+   - FRAGMENTATION SUSPECT → propose pre-allocating any per-packet buffers; or rebuilding with `CONFIG_HEAP_TASK_TRACKING=y` on ESP32 to see who's holding the largest blocks.
+   - OOM-IMMINENT → flag for immediate attention; don't wait for the next telemetry interval.
+   - STEADY → say so; stop. Don't invent problems.
+
+## What NOT to do
+
+- Don't assume a leak from a single dip. LocalStats fires every ~60 s and the firmware naturally allocates+frees on each broadcast cycle; one packet sees the trough. Look at the slope, not the deltas.
+- Don't recommend code changes. This skill diagnoses; the operator decides what to fix.
+- Don't enable `set_debug_log_api` automatically — if it's off, telemetry isn't reaching pubsub anyway, and the recorder will be empty. Tell the operator to flip it on and wait, then re-run.
+- Don't run heavy workloads to "trigger the leak." The recorder is passive; we read what's there.
+
+## Companion: `mark_event` for stress runs
+
+If the operator wants to test under stimulus (e.g. blast 50 broadcasts and see what the heap does), they can frame the experiment with markers:
+
+```text
+mark_event("burst-start")
+… run the workload …
+mark_event("burst-end")
+/leakhunt window=15m
+```
+
+The markers land in both `events.jsonl` and `logs.jsonl`, so the report can show "free_heap dipped 8 KB during the burst window, recovered to baseline within 2 LocalStats cycles" → not a leak.
@@ -3,6 +3,8 @@ description: Re-run a specific test N times in isolation to triage flakes, diff
 argument-hint: <test-node-id> [count=5]
 ---

+<!-- markdownlint-disable MD029 -->
+
 # `/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."
@@ -40,6 +42,8 @@ Re-run a single pytest node ID N times in isolation, track pass rate, and surfac

   Surface the top 3 differences as a "passes when / fails when" table. Don't dump full logs — pull specific lines with uptime timestamps.

+5a. **Archive recorder slices per attempt** (no extra device interaction; the recorder runs autouse). Right after each attempt finishes, capture its `(start_ts, end_ts)` and call `mcp__meshtastic__recorder_export(start=<start>, end=<end>, dest_dir="mcp-server/tests/repro_artifacts/<safe-test-id>/attempt_<n>/")`. This drops a `logs.jsonl`, `telemetry.jsonl`, `packets.jsonl`, and `events.jsonl` snapshot scoped to the attempt window. Use these for cross-attempt diffs in step 5: `jq '.line' logs.jsonl` is faster than re-running the test, and the telemetry slice lets you compare heap behavior across attempts.
+
 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.
@@ -8,17 +8,21 @@
  "features": {
    "ghcr.io/devcontainers/features/python:1": {
      "installTools": true,
-      "version": "3.14"
+      "version": "3.13"
    }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.cpptools",
-        "platformio.platformio-ide",
+        "Jason2866.esp-decoder",
+        "pioarduino.pioarduino-ide",
        "Trunk.io"
      ],
-      "unwantedRecommendations": ["ms-azuretools.vscode-docker"],
+      "unwantedRecommendations": [
+        "ms-azuretools.vscode-docker",
+        "platformio.platformio-ide"
+      ],
      "settings": {
        "extensions.ignoreRecommendations": true
      }
@@ -13,6 +13,7 @@ Meshtastic is an open-source LoRa mesh networking project for long-range, low-po
 - **RP2040/RP2350** - Raspberry Pi Pico variants
 - **STM32WL** - STM32 with integrated LoRa
 - **Linux/Portduino** - Native Linux builds (Raspberry Pi, etc.)
+- **macOS native** - Headless `meshtasticd` on Apple Silicon / x86_64; see `variants/native/portduino/platformio.ini` for Homebrew prereqs + CH341 LoRa setup

 ### Supported Radio Chips

@@ -134,6 +135,99 @@ On top of authorization, any remote admin message that **mutates** state (not a
 - **Channel 0 PSK change** → every peer must re-learn the channel hash; cached NodeInfo becomes temporarily unreachable until the next broadcast.
 - **`security.private_key` blanked via admin** → regenerates both halves (unless in Ham mode) and propagates the new public key via NodeInfo.

+## NodeDB Layout (v25)
+
+`DEVICESTATE_CUR_VER = 25`, `DEVICESTATE_MIN_VER = 24`. The on-device NodeDB was split in v25 into a slim header table plus four optional satellite stores. Older v24 saves auto-migrate at boot. Old training-data instincts (`node->user.long_name`, `node->position.latitude_i`, `node->is_favorite`, `node->device_metrics.battery_level`) are wrong now — the fields aren't there. Read this section before touching anything that walks `nodeDB->meshNodes`.
+
+### Slim `NodeInfoLite`
+
+`UserLite` is flattened onto `NodeInfoLite` (no nested sub-message); `position` and `device_metrics` are removed entirely (tags reserved). MAC address is dropped. Long names are capped at 25 chars (`max_size:25` in `deviceonly.options`); `hw_model` and `role` are `int_size:8`. Encoded size dropped from ~166 B → ~105 B per node.
+
+Booleans are bit-packed into `NodeInfoLite.bitfield`. **Do not read or write the bits directly** — use the inline helpers in `src/mesh/NodeDB.h`:
+
+```cpp
+nodeInfoLiteHasUser(n)                  // bit 5 — user fields populated
+nodeInfoLiteIsFavorite(n)               // bit 3
+nodeInfoLiteIsIgnored(n)                // bit 4
+nodeInfoLiteIsMuted(n)                  // bit 1
+nodeInfoLiteIsLicensed(n)               // bit 6 — Ham mode peer
+nodeInfoLiteIsKeyManuallyVerified(n)    // bit 0
+nodeInfoLiteHasIsUnmessagable(n)        // bit 8 — "is_unmessagable was sent"
+nodeInfoLiteIsUnmessagable(n)           // bit 7
+// via_mqtt is bit 2 (mask exposed; predicate uses the mask directly)
+
+nodeInfoLiteSetBit(n, NODEINFO_BITFIELD_IS_FAVORITE_MASK, true);  // setter
+```
+
+### Satellite stores
+
+Four `std::unordered_map<NodeNum, …>` members on `NodeDB`, each gated by its own build flag:
+
+| Map               | Value type                      | Build flag                         |
+| ----------------- | ------------------------------- | ---------------------------------- |
+| `nodePositions`   | `meshtastic_PositionLite`       | `MESHTASTIC_EXCLUDE_POSITIONDB`    |
+| `nodeTelemetry`   | `meshtastic_DeviceMetrics`      | `MESHTASTIC_EXCLUDE_TELEMETRYDB`   |
+| `nodeEnvironment` | `meshtastic_EnvironmentMetrics` | `MESHTASTIC_EXCLUDE_ENVIRONMENTDB` |
+| `nodeStatus`      | `meshtastic_StatusMessage`      | `MESHTASTIC_EXCLUDE_STATUSDB`      |
+
+Defaults are ON (i.e., maps **excluded**) for STM32WL only — see `src/mesh/mesh-pb-constants.h`. On every other arch all four maps are present. When excluded, the map member is absent and the corresponding accessors return `false`.
+
+All four maps are guarded by **`mutable concurrency::Lock satelliteMutex`** — concurrent access from receive threads, the phone API state machine, and the renderer is the rule, not the exception.
+
+### Accessor convention
+
+**Never hand out pointers into the maps.** Use the copy-out accessors on `NodeDB`:
+
+```cpp
+bool copyNodePosition(NodeNum, meshtastic_PositionLite &out)       const;
+bool copyNodeTelemetry(NodeNum, meshtastic_DeviceMetrics &out)     const;
+bool copyNodeEnvironment(NodeNum, meshtastic_EnvironmentMetrics &out) const;
+bool copyNodeStatus(NodeNum, meshtastic_StatusMessage &out)        const;
+```
+
+Each takes the lock, copies the value if present, returns `false` if the entry is absent or the DB is excluded. Pass-by-out-param is deliberate — pointer-style accessors would invite UAF and lock-leak bugs across the renderer. The "has any X" convenience predicates (`hasValidPosition` etc.) are implemented in terms of these.
+
+Writers go through `setNodeStatus`, `updatePosition`, `updateTelemetry` (which dispatches on `which_variant` for device vs environment metrics) — these own the lock and the eviction hooks.
+
+### Eviction
+
+Every code path that drops a node from the header table must also evict the satellites. The single chokepoint is `eraseNodeSatellites(NodeNum)`; it's already called from `getOrCreateMeshNode`'s oldest-boring eviction, `removeNodeByNum`, both branches of `resetNodes`, `cleanupMeshDB`, `addFromContact`'s ignored-branch, and `AdminModule`'s `set_ignored_node`. Add new eviction sites here, not by calling `.erase()` directly.
+
+### Sync flow: thin NodeInfo + post-COMPLETE_ID replay (no opt-in)
+
+There is no capability flag and no special "gradient" nonce. The **default** sync flow is:
+
+1. Config / module-config / channel / metadata segments (same as before).
+2. `STATE_SEND_OWN_NODEINFO` — **our own** NodeInfo, still bundled with our position and device_metrics (because the replay snapshot excludes our own NodeNum). Emitted via `ConvertToNodeInfo(lite)`.
+3. `STATE_SEND_OTHER_NODEINFOS` — every other peer's NodeInfo, **always thin** (no `position`, no `device_metrics`). Emitted via `ConvertToNodeInfoThin(lite)`.
+4. `STATE_SEND_FILEMANIFEST` → `STATE_SEND_COMPLETE_ID` — the phone sees `config_complete_id` and treats sync as done.
+5. `STATE_SEND_PACKETS` — live mesh packets, with a trailing replay drain interleaved. The replay drain walks four cached satellite stores in order (positions → telemetry → environment → status) and emits each cached entry as an ordinary `MeshPacket` on the matching portnum (`POSITION_APP`, `TELEMETRY_APP` device + environment variants, `NODE_STATUS_APP`). These are indistinguishable on the wire from live mesh traffic, so clients need no special handling — any code that already updates UI on `POSITION_APP` etc. works.
+
+`PhoneAPI::sendConfigComplete()` arms `replayPhase = REPLAY_PHASE_POSITIONS` for default/full sync and `SPECIAL_NONCE_ONLY_NODES`, while `SPECIAL_NONCE_ONLY_CONFIG` skips replay. The drain runs inside `STATE_SEND_PACKETS` via `popReplayPacket()`, lower priority than live traffic. When all four phases drain, `replayPhase` flips back to `REPLAY_PHASE_IDLE` and the snapshot vectors get `shrink_to_fit`ed.
+
+STM32WL and any other build with all four `MESHTASTIC_EXCLUDE_*DB` flags set produces zero replay packets — `popReplayPacket` advances through each phase in microseconds without emitting anything.
+
+Special nonces that still mean something:
+
+- `SPECIAL_NONCE_ONLY_CONFIG` (69420) — skip node sync entirely, just config.
+- `SPECIAL_NONCE_ONLY_NODES` (69421) — skip config segments, jump straight to `STATE_SEND_OWN_NODEINFO`. Still gets the post-COMPLETE_ID replay drain.
+
+There are no other reserved nonces; everything else is a fresh random `want_config_id` from the client.
+
+### v24 → v25 migration
+
+The legacy migration code lives in **`src/mesh/NodeDBLegacyMigration.cpp`**, not in `NodeDB.cpp`. It owns the `meshtastic_NodeDatabase_Legacy` callback and `NodeDB::migrateLegacyNodeDatabase()`. The legacy proto descriptor is `protobufs/meshtastic/deviceonly_legacy.proto` (only included by the migration TU). The boot path peeks the file's leading version tag, runs the migration if `version < 25`, then re-saves in v25 layout. The legacy descriptor is scheduled for removal once `DEVICESTATE_MIN_VER` is bumped.
+
+### Read-site rules of thumb
+
+- Never `node->position.X` / `node->device_metrics.X` — those fields no longer exist. Pull from the satellite map via `copyNodePosition` / `copyNodeTelemetry`.
+- Never `node->user.long_name` — `long_name`, `short_name`, `public_key`, `hw_model`, `role`, `macaddr` (gone), `is_licensed`, `is_unmessagable` are flat on `NodeInfoLite`.
+- Never `node->is_favorite` / `node->is_ignored` / `node->via_mqtt` / `node->is_key_manually_verified` — use the bitfield helpers.
+- Never assume `nodeDB->getMeshNode(num)->position.time` — call `copyNodePosition` and check the return.
+- Don't lock `satelliteMutex` yourself in renderer code; the copy-out accessors already do.
+
+Unit tests for the conversion layer live in `test/test_type_conversions/test_main.cpp` (Unity) — bitfield round-trips, `long_name` truncation, thin-vs-full conversions. Add cases there when extending the schema.
+
 ## Project Structure

 ```
@@ -195,6 +289,8 @@ firmware/
 - 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.)
+- **Keep code comments minimal — one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior.
+- **Use `Throttle` for time-based rate limiting, not raw `millis()` math.** `src/mesh/Throttle.h` provides `Throttle::isWithinTimespanMs(lastMs, intervalMs)` (returns true while inside the cooldown) and `Throttle::execute(&lastMs, intervalMs, func)` (function-pointer form that updates the timestamp on fire). Use these for any "did N ms pass since X" check — raw `millis() > lastMs + N` is rollover-unsafe (breaks after ~49.7 days) and inconsistent with the rest of the codebase. The helpers compute `now - lastMs` with unsigned subtraction, which wraps correctly.

 ### Naming Conventions

@@ -369,7 +465,7 @@ To reduce avoidable agent mistakes, assume these tools are available (or install
 - **Required CLI basics**: `bash`, `git`, `find`, `grep`, `sed`, `awk`, `xargs`
 - **Strongly recommended**: `rg` (ripgrep) for fast file/text search, `jq` for JSON processing
 - **Build/test tools**: `python3`, `pip`, virtualenv (`python3 -m venv`), `platformio` (`pio`)
- **Containerized native testing**: `docker` (especially important on macOS / non-Linux hosts)
+- **Containerized native testing**: `docker` (fallback for non-Linux hosts; macOS can also build natively via `pio run -e native-macos`)

 Fallback expectations for agents:

@@ -388,6 +484,7 @@ Build commands:
 pio run -e tbeam              # Build specific target
 pio run -e tbeam -t upload    # Build and upload
 pio run -e native             # Build native/Linux version
+pio run -e native-macos       # Build headless macOS meshtasticd (Homebrew prereqs in variants/native/portduino/platformio.ini)
 ```

 ### Build Manifest
@@ -573,6 +670,8 @@ Grouped by purpose. Full argument shapes in `mcp-server/README.md`; a few high-v

 `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`.

+**TCP / native-host nodes.** Setting `MESHTASTIC_MCP_TCP_HOST=<host[:port]>` makes `list_devices` surface a `meshtasticd` daemon (e.g. the `native-macos` build) as a synthetic `tcp://host:port` entry, and `connect()` routes through `meshtastic.tcp_interface.TCPInterface` instead of `SerialInterface`. Every read/write/admin tool that flows through `connect()` works against the daemon transparently. USB-only tools (`pio_flash`, `erase_and_flash`, `update_flash`, `touch_1200bps`, `serial_open`, `esptool_*`, `nrfutil_*`, `picotool_*`) raise a clear `ConnectionError` when handed a `tcp://` port; `pio_flash` against a `native*` env raises a `FlashError` (no upload step — use `build` and run the binary directly). The pytest harness still assumes USB-attached devices per role; TCP-aware fixtures are deferred. See `mcp-server/README.md` § "TCP / native-host nodes".
+
 ### 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.
@@ -32,10 +32,15 @@ jobs:
        shell: bash
        working-directory: meshtasticd
        run: |
+          # Build-tools (notably platformio) come from the Meshtastic project
+          # on the OpenSUSE Build Service:
+          # https://build.opensuse.org/project/show/network:Meshtastic:build-tools
+          echo 'deb http://download.opensuse.org/repositories/network:/Meshtastic:/build-tools/xUbuntu_24.04/ /' \
+            | sudo tee /etc/apt/sources.list.d/network:Meshtastic:build-tools.list
+          curl -fsSL https://download.opensuse.org/repositories/network:Meshtastic:build-tools/xUbuntu_24.04/Release.key \
+            | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/network_Meshtastic_build-tools.gpg >/dev/null
          sudo apt-get update -y --fix-missing
-          sudo apt-get install -y software-properties-common build-essential devscripts equivs
-          sudo add-apt-repository ppa:meshtastic/build-tools -y
-          sudo apt-get update -y --fix-missing
+          sudo apt-get install -y build-essential devscripts equivs
          sudo mk-build-deps --install --remove --tool='apt-get -o Debug::pkgProblemResolver=yes --no-install-recommends --yes' debian/control

      - name: Import GPG key
@@ -0,0 +1,51 @@
+name: Build MacOS Binary
+
+on:
+  workflow_call:
+    inputs:
+      macos_ver:
+        required: false
+        default: "26" # ARM64
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build-MacOS:
+    runs-on: macos-${{ inputs.macos_ver }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Install deps
+        shell: bash
+        run: |
+          brew update
+          brew install platformio yaml-cpp libuv openssl@3 libusb argp-standalone pkg-config ulfius
+
+      - name: Get release version string
+        run: |
+          echo "long=$(./bin/buildinfo.py long)" >> $GITHUB_OUTPUT
+        id: version
+
+      - name: Build for MacOS
+        run: |
+          platformio run -e native-macos
+        env:
+          PKG_VERSION: ${{ steps.version.outputs.long }}
+        # Errors in this step should not fail the entire workflow while MacOS support is in development.
+        continue-on-error: true
+
+      - name: List output files
+        run: ls -lah .pio/build/native-macos/
+
+      - name: Store binaries as an artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: firmware-macos-${{ inputs.macos_ver }}-${{ steps.version.outputs.long }}
+          overwrite: true
+          path: |
+            .pio/build/native-macos/meshtasticd
@@ -73,7 +73,9 @@ jobs:
      - name: Sanitize platform string
        id: sanitize_platform
        # Replace slashes with underscores
-        run: echo "cleaned_platform=${{ inputs.platform }}" | sed 's/\//_/g' >> $GITHUB_OUTPUT
+        env:
+          plat: ${{ inputs.platform }}
+        run: echo "cleaned_platform=${plat}" | sed 's/\//_/g' >> $GITHUB_OUTPUT

      - name: Docker login
        if: ${{ inputs.push }}
@@ -43,6 +43,15 @@ jobs:
      push: true
    secrets: inherit

+  docker-debian-riscv64:
+    uses: ./.github/workflows/docker_build.yml
+    with:
+      distro: debian
+      platform: linux/riscv64
+      runs-on: ubuntu-24.04-arm
+      push: true
+    secrets: inherit
+
  docker-alpine-amd64:
    uses: ./.github/workflows/docker_build.yml
    with:
@@ -70,16 +79,27 @@ jobs:
      push: true
    secrets: inherit

+  docker-alpine-riscv64:
+    uses: ./.github/workflows/docker_build.yml
+    with:
+      distro: alpine
+      platform: linux/riscv64
+      runs-on: ubuntu-24.04-arm
+      push: true
+    secrets: inherit
+
  docker-manifest:
    needs:
      # Debian
      - docker-debian-amd64
      - docker-debian-arm64
      - docker-debian-armv7
+      - docker-debian-riscv64
      # Alpine
      - docker-alpine-amd64
      - docker-alpine-arm64
      - docker-alpine-armv7
+      - docker-alpine-riscv64
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout code
@@ -162,6 +182,7 @@ jobs:
            meshtastic/meshtasticd@${{ needs.docker-debian-amd64.outputs.digest }}
            meshtastic/meshtasticd@${{ needs.docker-debian-arm64.outputs.digest }}
            meshtastic/meshtasticd@${{ needs.docker-debian-armv7.outputs.digest }}
+            meshtastic/meshtasticd@${{ needs.docker-debian-riscv64.outputs.digest }}

      - name: Docker meta (Alpine)
        id: meta_alpine
@@ -182,3 +203,4 @@ jobs:
            meshtastic/meshtasticd@${{ needs.docker-alpine-amd64.outputs.digest }}
            meshtastic/meshtasticd@${{ needs.docker-alpine-arm64.outputs.digest }}
            meshtastic/meshtasticd@${{ needs.docker-alpine-armv7.outputs.digest }}
+            meshtastic/meshtasticd@${{ needs.docker-alpine-riscv64.outputs.digest }}
@@ -116,6 +116,20 @@ jobs:
      build_location: local
    secrets: inherit

+  MacOS:
+    strategy:
+      fail-fast: false
+      matrix:
+        macos_ver:
+          - "26" # ARM64
+          # - '26-intel' # x86_64
+          - "15" # ARM64
+          # - '15-intel' # x86_64
+    uses: ./.github/workflows/build_macos_bin.yml
+    with:
+      macos_ver: ${{ matrix.macos_ver }}
+    # secrets: inherit
+
  package-pio-deps-native-tft:
    if: ${{ github.repository == 'meshtastic/firmware' && github.event_name == 'workflow_dispatch' }}
    uses: ./.github/workflows/package_pio_deps.yml
@@ -286,6 +300,7 @@ jobs:
      - gather-artifacts
      - build-debian-src
      - package-pio-deps-native-tft
+      # - MacOS
    steps:
      - name: Checkout
        uses: actions/checkout@v6
@@ -56,3 +56,16 @@ CMakeLists.txt
 .python3
 .claude/scheduled_tasks.lock
 userPrefs.jsonc.mcp-session-bak
+
+# Fake-NodeDB fixture pipeline (bin/regen-fake-nodedbs.sh)
+# JSONL seeds are committed (test/fixtures/nodedb/seed_v25_*.jsonl);
+# compiled .proto outputs are ephemeral build artifacts.
+build/fixtures/
+bin/_generated/
+
+# Build artifacts: anything compiling .o/.a outside .pio/ is accidental.
+# Explicit exceptions for vendored binaries (Morse Micro mm-iot-esp32 SDK).
+*.o
+*.a
+!lib/MorseWlan/lib/**/*.a
+!lib/MorseWlan/src/*.mbin.o
@@ -4,19 +4,19 @@ cli:
 plugins:
  sources:
    - id: trunk
-      ref: v1.7.6
+      ref: v1.9.0
      uri: https://github.com/trunk-io/plugins
 lint:
  enabled:
-    - checkov@3.2.524
-    - renovate@43.139.6
+    - checkov@3.2.528
+    - renovate@43.150.0
    - prettier@3.8.3
-    - trufflehog@3.95.2
+    - trufflehog@3.95.3
    - yamllint@1.38.0
    - bandit@1.9.4
    - trivy@0.70.0
    - taplo@0.10.0
-    - ruff@0.15.11
+    - ruff@0.15.12
    - isort@8.0.1
    - markdownlint@0.48.0
    - oxipng@10.1.1
@@ -34,9 +34,16 @@ lint:
    - linters: [ALL]
      paths:
        - bin/**
+    # Fake-NodeDB fixture JSONL files contain deterministic synthetic
+    # public_key_hex (64-char hex) values that gitleaks misidentifies as
+    # generic-api-key. These are not secrets — they're test fixtures
+    # produced by bin/gen-fake-nodedb-seed.py with a fixed RNG seed.
+    - linters: [gitleaks]
+      paths:
+        - test/fixtures/nodedb/seed_v25_*.jsonl
 runtimes:
  enabled:
-    - python@3.10.8
+    - python@3.14.4
    - go@1.21.0
    - node@22.16.0
 actions:
@@ -1,10 +1,10 @@
 {
-    // See http://go.microsoft.com/fwlink/?LinkId=827846
-    // for the documentation about the extensions.json format
    "recommendations": [
-        "platformio.platformio-ide"
+        "Jason2866.esp-decoder",
+        "pioarduino.pioarduino-ide"
    ],
    "unwantedRecommendations": [
-        "ms-vscode.cpptools-extension-pack"
+        "ms-vscode.cpptools-extension-pack",
+        "platformio.platformio-ide"
    ]
 }
@@ -10,17 +10,18 @@ This file (`AGENTS.md`) is a short pointer + quick reference for agents that don

 ## 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]`                                      |
+| Action                           | Command                                                                                                       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Build a firmware variant         | `pio run -e <env>` (e.g. `pio run -e rak4631`, `pio run -e heltec-v3`)                                        |
+| Build native macOS host binary   | `pio run -e native-macos` (Homebrew prereqs + CH341 LoRa setup in `variants/native/portduino/platformio.ini`) |
+| 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)

@@ -65,6 +66,8 @@ Key rotation to never trigger casually: only the **full** factory reset (`factor
 - **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.
+- **Keep code comments minimal — one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior.
+- **Use `Throttle` for time-based rate limiting, not raw `millis()` math.** `src/mesh/Throttle.h` provides `Throttle::isWithinTimespanMs(lastMs, intervalMs)` (returns true while inside the cooldown) and `Throttle::execute(&lastMs, intervalMs, func)` (function-pointer form that updates the timestamp on fire). Use these for any "did N ms pass since X" check — raw `millis() > lastMs + N` is rollover-unsafe (breaks after ~49.7 days) and inconsistent with the rest of the codebase. The helpers compute `now - lastMs` with unsigned subtraction, which wraps correctly.

 ## Typical agent workflows

@@ -121,19 +124,21 @@ Sequence these; don't parallelize on the same port.
 - **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.
+- **macOS: `LIBUSB_ERROR_BUSY` on a CH341 LoRa adapter?** A third-party WCH `CH34xVCPDriver` is claiming interface 0. Find the bundle ID with `ioreg -p IOUSB -l -w 0 | grep -B2 -A30 0x5512`, then `sudo kmutil unload -b <bundleID>`. Apple's bundled CH34x kext targets the CH340 UART (PID 0x7523), not the SPI bridge — it's never the culprit.

 ## 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`.                                                                   |
+| 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_MCP_TCP_HOST`            | `host` or `host:port` of a `meshtasticd` daemon (e.g. the `native-macos` build). Surfaces it in `list_devices` as `tcp://host:port` so `connect()`-based tools target it transparently. Default port 4403. |
+| `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`.                                                                                                                               |
@@ -3,15 +3,17 @@
 # trunk-ignore-all(hadolint/DL3008): Do not pin apt package versions
 # trunk-ignore-all(hadolint/DL3013): Do not pin pip package versions

-FROM python:3.14-slim-trixie AS builder
+FROM debian:trixie AS builder
 ARG PIO_ENV=native
 ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=Etc/UTC

 # Install Dependencies
 ENV PIP_ROOT_USER_ACTION=ignore
+ENV PIP_BREAK_SYSTEM_PACKAGES=1
 RUN apt-get update && apt-get install --no-install-recommends -y \
        curl wget g++ zip git ca-certificates pkg-config \
+        python3-pip python3-grpc-tools \
        libgpiod-dev libyaml-cpp-dev libbluetooth-dev libi2c-dev libuv1-dev \
        libusb-1.0-0-dev libulfius-dev liborcania-dev libssl-dev \
        libx11-dev libinput-dev libxkbcommon-x11-dev libsqlite3-dev libsdl2-dev \
@@ -3,12 +3,19 @@
 # trunk-ignore-all(hadolint/DL3018): Do not pin apk package versions
 # trunk-ignore-all(hadolint/DL3013): Do not pin pip package versions

-FROM python:3.14-alpine3.22 AS builder
+# Ensure the Alpine version is updated in both stages of the container!
+FROM alpine:3.23 AS builder
 ARG PIO_ENV=native
-ENV PIP_ROOT_USER_ACTION=ignore

+# Enable Alpine community repository (for 'py3-grpcio-tools')
+RUN echo "https://dl-cdn.alpinelinux.org/alpine/v$(cut -d. -f1,2 /etc/alpine-release)/community" >> /etc/apk/repositories
+
+# Install Dependencies
+ENV PIP_ROOT_USER_ACTION=ignore
+ENV PIP_BREAK_SYSTEM_PACKAGES=1
 RUN apk --no-cache add \
        bash g++ libstdc++-dev linux-headers zip git ca-certificates libbsd-dev \
+        py3-pip py3-grpcio-tools \
        libgpiod-dev yaml-cpp-dev bluez-dev \
        libusb-dev i2c-tools-dev libuv-dev openssl-dev pkgconf argp-standalone \
        libx11-dev libinput-dev libxkbcommon-dev sqlite-dev sdl2-dev \
@@ -60,4 +67,4 @@ EXPOSE 4403

 CMD [ "sh",  "-cx", "meshtasticd --fsdir=/var/lib/meshtasticd" ]

-HEALTHCHECK NONE
+HEALTHCHECK NONE
@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Post-process protoc-generated Python files to live under a local namespace.
+
+Called by bin/regen-py-protos.sh. Walks the generated *_pb2.py files in the
+target directory and rewrites every `meshtastic` reference (imports, dotted
+attribute access) to use the new namespace (e.g., `meshtastic_v25`).
+
+Why: the .proto files declare `package meshtastic;`, so protoc emits
+`from meshtastic import mesh_pb2 as ...` lines. That would shadow the PyPI
+`meshtastic` package which other parts of the mcp-server depend on. Renaming
+to a local namespace keeps both available.
+
+Usage:
+    _rewrite_proto_namespace.py <generated_dir> <new_namespace>
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+
+def rewrite(dir_path: pathlib.Path, new_ns: str) -> int:
+    # Standard protoc import forms:
+    #   from meshtastic.X_pb2 import ...     (rare, for direct symbol pulls)
+    #   from meshtastic import X_pb2 as ...  (common, the cross-file ref)
+    #   import meshtastic.X_pb2              (also possible)
+    pattern_dotted_from = re.compile(r"^from meshtastic\.", re.MULTILINE)
+    pattern_bare_from = re.compile(r"^from meshtastic import ", re.MULTILINE)
+    pattern_dotted_import = re.compile(r"^import meshtastic\.", re.MULTILINE)
+
+    count = 0
+    for p in dir_path.glob("*.py"):
+        text = p.read_text(encoding="utf-8")
+        new = pattern_dotted_from.sub(f"from {new_ns}.", text)
+        new = pattern_bare_from.sub(f"from {new_ns} import ", new)
+        new = pattern_dotted_import.sub(f"import {new_ns}.", new)
+        # NOTE: we deliberately leave `meshtastic/X.proto` source-filename
+        # references inside descriptor strings alone. The descriptor pool is
+        # keyed by source filename (independent of Python package layout), so
+        # those don't collide with the PyPI package's descriptors.
+        if new != text:
+            p.write_text(new, encoding="utf-8")
+            count += 1
+    return count
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print("usage: _rewrite_proto_namespace.py <generated_dir> <new_namespace>", file=sys.stderr)
+        return 2
+    dir_path = pathlib.Path(argv[0])
+    new_ns = argv[1]
+    if not dir_path.is_dir():
+        print(f"directory not found: {dir_path}", file=sys.stderr)
+        return 2
+    n = rewrite(dir_path, new_ns)
+    print(f"rewrote {n} file(s) in {dir_path} → namespace {new_ns}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
@@ -31,5 +31,6 @@ basename=meshtasticd-$1-$VERSION
 pio pkg install --environment "$PIO_ENV" || platformioFailed
 pio run --environment "$PIO_ENV" || platformioFailed

-cp "$BUILDDIR/meshtasticd" "$OUTDIR/meshtasticd_linux_$(uname -m)"
+os_name=$(uname -s | tr '[:upper:]' '[:lower:]')
+cp "$BUILDDIR/meshtasticd" "$OUTDIR/meshtasticd_${os_name}_$(uname -m)"
 cp bin/native-install.* $OUTDIR/
@@ -0,0 +1,18 @@
+# Station G3 motherboard with a Raspberry Pi Zero 2W as the MCU daughterboard.
+# Verify spidev / I2C device paths for your OS — they may differ.
+Meta:
+  name: Station G3
+  support: community
+  compatible:
+    - raspberry-pi
+
+Lora:
+  Module: sx1262
+  IRQ: 22                       # BCM pin — wiki spec
+  Reset: 16                     # BCM pin — wiki spec
+  Busy: 24                      # BCM pin — wiki spec
+  # CS: 8                       # BCM 8 = SPI0 CE0 (default); uncomment only to override
+  DIO2_AS_RF_SWITCH: true
+  DIO3_TCXO_VOLTAGE: true
+  spidev: spidev0.0
+  # SX126X_MAX_POWER: 19        # matches Station G2 firmware cap; raise carefully per PA jumper mode
@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+"""Deterministic seed-data generator for the fake NodeDB fixture pipeline.
+
+Writes a JSONL file describing N fake-but-realistic Meshtastic peers.
+The output is hand-editable and committed; a sibling compile step
+(bin/seed-json-to-proto.py) turns it into a binary `meshtastic_NodeDatabase`
+v25 protobuf with fresh "now-relative" timestamps.
+
+Determinism contract:
+  Same --seed -> byte-identical JSONL output, regardless of wall clock.
+  All timestamps are stored as `*_offset_sec` (seconds before "now"); the
+  compile step resolves them to absolute epochs at compile time.
+
+Structural fields covered:
+  * NodeInfoLite header: num, long_name, short_name, hw_model, role,
+    public_key, snr, channel, hops_away, next_hop, bitfield flags
+  * PositionLite: lat/long Gaussian around --centroid, altitude, source
+  * DeviceMetrics: battery/voltage/util/uptime
+  * EnvironmentMetrics: temp/humidity/pressure/iaq
+  * StatusMessage: error_code (usually zero)
+
+Active-board allow-list:
+  hw_model values are restricted to the intersection of
+    (a) variants with `custom_meshtastic_support_level = 1` in
+        variants/*/*/platformio.ini, AND
+    (b) values present in the `HardwareModel` enum in mesh.proto.
+  See HW_MODEL_WEIGHTS below. Deprecated boards (legacy TLORA / Heltec V1-2 /
+  classic TBEAM / TBEAM_V0P7 / Nano G1 / etc.) and fuzzer-only sentinels
+  (PORTDUINO, ANDROID_SIM, DIY_V1, ...) are excluded.
+
+Active-role allow-list:
+  Excludes ROUTER_CLIENT (deprecated v2.3.15) and REPEATER (deprecated v2.7.11).
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import math
+import pathlib
+import random
+import sys
+
+# --------------------------------------------------------------------------
+# Active-board allow-list (intersection of tier-1 variants + HardwareModel enum).
+# Refresh by running:
+#   for f in $(find variants -name 'platformio.ini' | xargs grep -lE 'custom_meshtastic_support_level = 1'); do
+#       grep custom_meshtastic_hw_model_slug $f | awk -F= '{print $2}' | tr -d ' ';
+#   done | sort -u | comm -12 - <(python3 -c "from meshtastic.protobuf.mesh_pb2 import HardwareModel; print('\\n'.join(HardwareModel.keys()))" | sort)
+# --------------------------------------------------------------------------
+HW_MODEL_WEIGHTS: dict[str, float] = {
+    "HELTEC_V3": 14.0,
+    "T_DECK": 9.0,
+    "HELTEC_V4": 8.0,
+    "RAK4631": 8.0,
+    "HELTEC_MESH_POCKET": 6.0,
+    "TRACKER_T1000_E": 5.0,
+    "HELTEC_MESH_NODE_T114": 5.0,
+    "T_DECK_PRO": 5.0,
+    "LILYGO_TBEAM_S3_CORE": 4.0,
+    "HELTEC_WIRELESS_PAPER": 4.0,
+    "HELTEC_WSL_V3": 3.0,
+    "T_ECHO": 3.0,
+    "HELTEC_WIRELESS_TRACKER": 3.0,
+    "HELTEC_WIRELESS_TRACKER_V2": 2.0,
+    "HELTEC_VISION_MASTER_E290": 2.0,
+    "HELTEC_MESH_SOLAR": 2.0,
+    "SEEED_WIO_TRACKER_L1": 2.0,
+    "T_LORA_PAGER": 1.5,
+    "HELTEC_VISION_MASTER_E213": 1.5,
+    "T_ECHO_PLUS": 1.0,
+    "MUZI_BASE": 1.0,
+    "WISMESH_TAP_V2": 1.0,
+    "THINKNODE_M2": 1.0,
+    "THINKNODE_M5": 1.0,
+    "TLORA_T3_S3": 1.0,
+    # Long tail (uniform low weight across remaining tier-1 boards):
+    "HELTEC_V4_R8": 0.3,
+    "HELTEC_VISION_MASTER_T190": 0.3,
+    "HELTEC_HT62": 0.3,
+    "HELTEC_MESH_NODE_T096": 0.3,
+    "M5STACK_C6L": 0.3,
+    "MINI_EPAPER_S3": 0.3,
+    "MUZI_R1_NEO": 0.3,
+    "NOMADSTAR_METEOR_PRO": 0.3,
+    "RAK3312": 0.3,
+    "RAK3401": 0.3,
+    "SEEED_SOLAR_NODE": 0.3,
+    "SEEED_WIO_TRACKER_L1_EINK": 0.3,
+    "SENSECAP_INDICATOR": 0.3,
+    "TBEAM_1_WATT": 0.3,
+    "THINKNODE_M1": 0.3,
+    "THINKNODE_M3": 0.3,
+    "THINKNODE_M6": 0.3,
+    "T_ECHO_LITE": 0.3,
+    "WISMESH_TAG": 0.3,
+    "WISMESH_TAP": 0.3,
+    "XIAO_NRF52_KIT": 0.3,
+    "CROWPANEL": 0.3,
+}
+
+# Non-deprecated roles only.
+ROLE_WEIGHTS: dict[str, float] = {
+    "CLIENT": 75.0,
+    "CLIENT_MUTE": 5.0,
+    "ROUTER": 7.0,
+    "TRACKER": 3.0,
+    "SENSOR": 2.0,
+    "CLIENT_HIDDEN": 2.0,
+    "ROUTER_LATE": 2.0,
+    "CLIENT_BASE": 2.0,
+    "TAK": 1.0,
+    "TAK_TRACKER": 0.5,
+    "LOST_AND_FOUND": 0.5,
+}
+
+# Name pools — 60 firsts × 60 lasts = 3600 combinations.
+FIRSTS = [
+    "Quick", "Brave", "Silent", "Wild", "Lone", "Bright", "Red", "Blue",
+    "Green", "Black", "White", "Iron", "Steel", "Copper", "Silver", "Gold",
+    "Stone", "River", "Forest", "Mountain", "Canyon", "Desert", "Storm", "Sky",
+    "Solar", "Lunar", "Dawn", "Dusk", "Misty", "Frosty", "Sunny", "Shady",
+    "Happy", "Sleepy", "Drowsy", "Sneaky", "Sharp", "Smooth", "Rough", "Loud",
+    "Soft", "Slow", "Fast", "Tall", "Short", "Old", "New", "Tiny",
+    "Giant", "Hidden", "Lost", "Found", "Wandering", "Roving", "Drifting", "Floating",
+    "Burning", "Frozen", "Whispering", "Howling",
+]
+LASTS = [
+    "Phoenix", "Lion", "Bear", "Wolf", "Hawk", "Eagle", "Fox", "Lynx",
+    "Cougar", "Coyote", "Raven", "Owl", "Crow", "Falcon", "Heron", "Crane",
+    "Otter", "Badger", "Bison", "Elk", "Moose", "Stag", "Doe", "Hare",
+    "Marmot", "Mole", "Beaver", "Squirrel", "Mustang", "Bronco", "Pony", "Colt",
+    "Cobra", "Viper", "Mamba", "Adder", "Gecko", "Iguana", "Tortoise", "Turtle",
+    "Salmon", "Trout", "Bass", "Pike", "Shark", "Whale", "Dolphin", "Seal",
+    "Cactus", "Yucca", "Sage", "Juniper", "Pine", "Cedar", "Aspen", "Oak",
+    "Bluff", "Mesa", "Arroyo", "Ridge",
+]
+
+# Brief callsign pool for licensed-looking suffixes.
+CALLSIGN_PREFIXES = ["KX", "WD", "N5", "KE", "AB", "W5", "K1", "KQ", "AE", "NM"]
+
+# Only emojis that fit in 4 UTF-8 bytes (no variation selectors). short_name's
+# nanopb max_size:5 (incl. NUL) limits content to 4 bytes. ❄️ / ☀️ would be
+# 6 bytes due to U+FE0F variation selector — explicitly excluded.
+EMOJI_SHORTNAMES = ["🦊", "🐺", "🦅", "🐢", "🌵", "🔥", "🌙",
+                    "🌊", "🗻", "🌲", "🦌", "🐝", "🦂", "🦉",
+                    "🦇", "🦋"]
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+NUM_RESERVED = 4         # firmware reserves 0..3 (per NodeDB constants)
+NUM_MAX_EXCLUSIVE = 0x80000000  # restrict to positive int32 range for readability
+
+
+def _weighted_choice(rng: random.Random, weights: dict[str, float]) -> str:
+    """Deterministic weighted pick. Uses sorted keys so dict order is fixed."""
+    keys = sorted(weights.keys())
+    totals = [weights[k] for k in keys]
+    return rng.choices(keys, weights=totals, k=1)[0]
+
+
+def _gen_long_name(rng: random.Random, is_licensed: bool) -> str:
+    base = f"{rng.choice(FIRSTS)} {rng.choice(LASTS)}"
+    if is_licensed:
+        prefix = rng.choice(CALLSIGN_PREFIXES)
+        # Two trailing alpha chars after the digit; keep within 25 - len(base) - 1
+        suffix = f" {prefix}{rng.randint(0,9)}{rng.choice('ABCDEFGHIJKLMNOPQRSTUVWXYZ')}{rng.choice('ABCDEFGHIJKLMNOPQRSTUVWXYZ')}"
+        # nanopb max_size:25 means C string fits 24 bytes + NUL.
+        if len(base) + len(suffix) <= 24:
+            base = base + suffix
+    # Hard cap to 24 chars (nanopb max_size:25 minus NUL).
+    return base[:24]
+
+
+def _gen_short_name(rng: random.Random, long_name: str) -> str:
+    # 10% emoji-only short_name
+    if rng.random() < 0.10:
+        return rng.choice(EMOJI_SHORTNAMES)
+    first_char = long_name[0].upper() if long_name else "X"
+    alphanums = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+    return first_char + "".join(rng.choices(alphanums, k=3))
+
+
+def _gen_hops_away(rng: random.Random) -> int:
+    # Geometric-ish: 0→55%, 1→25%, 2→12%, 3→5%, 4→2%, 5+→1%
+    r = rng.random()
+    if r < 0.55:
+        return 0
+    if r < 0.80:
+        return 1
+    if r < 0.92:
+        return 2
+    if r < 0.97:
+        return 3
+    if r < 0.99:
+        return 4
+    return rng.randint(5, 7)
+
+
+def _gen_position(
+    rng: random.Random,
+    centroid_lat: float,
+    centroid_lon: float,
+    spread_km: float,
+    last_heard_offset_sec: int,
+) -> dict:
+    # 1 deg ≈ 111 km at the equator; we use this as a flat approximation.
+    lat = centroid_lat + rng.gauss(0.0, spread_km / 111.0)
+    lon = centroid_lon + rng.gauss(0.0, spread_km / 111.0)
+    altitude = max(0, round(rng.gauss(1376.0, 250.0)))  # T or C valley floor + relief
+    # Position was reported up to 300s before last_heard.
+    time_offset_sec = last_heard_offset_sec + rng.randint(0, 300)
+    return {
+        "latitude": round(lat, 6),
+        "longitude": round(lon, 6),
+        "altitude": altitude,
+        "time_offset_sec": time_offset_sec,
+        "location_source": "LOC_INTERNAL",
+    }
+
+
+def _gen_telemetry(rng: random.Random) -> dict:
+    # 5% plugged-in (battery_level == 101); rest uniform [10..100].
+    if rng.random() < 0.05:
+        battery_level = 101
+        voltage = 4.20
+    else:
+        battery_level = rng.randint(10, 100)
+        voltage = round(3.3 + (battery_level / 100.0) * 0.9, 3)
+    # Beta distributions for low/right-skewed metrics; randomly draw via gammavariate.
+    def _beta(a: float, b: float) -> float:
+        x = rng.gammavariate(a, 1.0)
+        y = rng.gammavariate(b, 1.0)
+        return x / (x + y)
+    channel_utilization = round(_beta(2.0, 15.0) * 100.0, 2)
+    air_util_tx = round(_beta(1.5, 20.0) * 10.0, 3)
+    uptime_seconds = int(rng.expovariate(1.0 / 86400.0))
+    return {
+        "battery_level": battery_level,
+        "voltage": voltage,
+        "channel_utilization": channel_utilization,
+        "air_util_tx": air_util_tx,
+        "uptime_seconds": uptime_seconds,
+    }
+
+
+def _gen_environment(rng: random.Random) -> dict:
+    return {
+        "temperature": round(rng.gauss(22.0, 8.0), 2),
+        "relative_humidity": round(min(100.0, max(0.0, rng.gauss(55.0, 20.0))), 2),
+        "barometric_pressure": round(rng.gauss(1013.0, 8.0), 2),
+        "iaq": int(min(500, max(0, round(rng.gauss(50.0, 30.0))))),
+    }
+
+
+def _gen_status(rng: random.Random) -> dict:
+    # `StatusMessage` (mesh.proto:1445) has a single free-form `string status`.
+    # Most peers report a healthy short status; occasional alert string.
+    healthy = ["OK", "online", "active", "running", "ready", "nominal"]
+    alert = ["low-batt", "no-gps", "weak-signal", "rebooted", "offline-soon"]
+    if rng.random() < 0.92:
+        return {"status": rng.choice(healthy)}
+    return {"status": rng.choice(alert)}
+
+
+def _gen_node(
+    rng: random.Random,
+    num: int,
+    centroid_lat: float,
+    centroid_lon: float,
+    spread_km: float,
+    coverage: dict[str, float],
+    last_heard_mean_sec: int,
+    last_heard_max_sec: int,
+) -> dict:
+    is_licensed = rng.random() < 0.05
+    long_name = _gen_long_name(rng, is_licensed)
+    short_name = _gen_short_name(rng, long_name)
+    hw_model = _weighted_choice(rng, HW_MODEL_WEIGHTS)
+    role = _weighted_choice(rng, ROLE_WEIGHTS)
+    has_public_key = rng.random() < 0.92
+    public_key_hex = (
+        "".join(f"{rng.randint(0,255):02x}" for _ in range(32)) if has_public_key else ""
+    )
+    snr = round(max(-20.0, min(12.0, rng.gauss(6.0, 4.0))), 2)
+    channel = 0 if rng.random() < 0.90 else rng.randint(1, 7)
+    hops_away = _gen_hops_away(rng)
+    next_hop = rng.randint(0, 255) if hops_away > 0 else 0
+    last_heard_offset_sec = int(min(rng.expovariate(1.0 / last_heard_mean_sec), last_heard_max_sec))
+
+    bitfield = {
+        "has_user": True,
+        "is_favorite": rng.random() < 0.08,
+        "is_muted": rng.random() < 0.03,
+        "via_mqtt": rng.random() < 0.12,
+        "is_ignored": rng.random() < 0.01,
+        "is_licensed": is_licensed,
+        "has_is_unmessagable": True,
+        "is_unmessagable": rng.random() < 0.02,
+        "is_key_manually_verified": rng.random() < 0.04,
+    }
+
+    node: dict = {
+        "num": f"0x{num:08x}",
+        "long_name": long_name,
+        "short_name": short_name,
+        "hw_model": hw_model,
+        "role": role,
+        "public_key_hex": public_key_hex,
+        "snr": snr,
+        "channel": channel,
+        "hops_away": hops_away,
+        "next_hop": next_hop,
+        "last_heard_offset_sec": last_heard_offset_sec,
+        "bitfield": bitfield,
+        "position": (
+            _gen_position(rng, centroid_lat, centroid_lon, spread_km, last_heard_offset_sec)
+            if rng.random() < coverage["position"]
+            else None
+        ),
+        "telemetry": _gen_telemetry(rng) if rng.random() < coverage["telemetry"] else None,
+        "environment": _gen_environment(rng) if rng.random() < coverage["environment"] else None,
+        "status": _gen_status(rng) if rng.random() < coverage["status"] else None,
+    }
+    return node
+
+
+def _parse_my_node_num(s: str | None) -> int | None:
+    if s is None:
+        return None
+    s = s.strip()
+    if s.startswith("0x") or s.startswith("0X"):
+        return int(s, 16)
+    return int(s)
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(
+        description="Deterministic JSONL seed for the fake NodeDB fixture.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    p.add_argument("--count", type=int, required=True, help="Number of fake nodes to emit.")
+    p.add_argument("--seed", type=int, required=True, help="Deterministic seed.")
+    p.add_argument("--out", required=True, help="Output JSONL path.")
+    p.add_argument(
+        "--centroid",
+        default="33.1284,-107.2528",
+        help="LAT,LON centroid (default: Truth or Consequences, NM).",
+    )
+    p.add_argument("--spread-km", type=float, default=60.0, help="Gaussian std-dev in km.")
+    p.add_argument("--position-coverage", type=float, default=0.85)
+    p.add_argument("--telemetry-coverage", type=float, default=0.70)
+    p.add_argument("--environment-coverage", type=float, default=0.25)
+    p.add_argument("--status-coverage", type=float, default=0.40)
+    p.add_argument("--my-node-num", default=None, help="Exclude this NodeNum from generated set (hex or dec).")
+    p.add_argument("--last-heard-mean-sec", type=int, default=3600)
+    p.add_argument("--last-heard-max-sec", type=int, default=7 * 86400)
+    args = p.parse_args(argv)
+
+    if args.count <= 0:
+        print("--count must be positive", file=sys.stderr)
+        return 2
+
+    try:
+        centroid_lat, centroid_lon = (float(s) for s in args.centroid.split(","))
+    except ValueError:
+        print(f"--centroid must be LAT,LON; got {args.centroid!r}", file=sys.stderr)
+        return 2
+
+    my_node_num = _parse_my_node_num(args.my_node_num)
+
+    rng = random.Random(args.seed)
+
+    # 1) Generate a unique deterministic set of NodeNums.
+    nums: set[int] = set()
+    while len(nums) < args.count:
+        n = rng.randrange(NUM_RESERVED, NUM_MAX_EXCLUSIVE)
+        if my_node_num is not None and n == my_node_num:
+            continue
+        nums.add(n)
+    ordered_nums = sorted(nums)  # sort to fix output order independent of set hash
+
+    # 2) Per-node generation (in num order, single RNG continues).
+    coverage = {
+        "position": args.position_coverage,
+        "telemetry": args.telemetry_coverage,
+        "environment": args.environment_coverage,
+        "status": args.status_coverage,
+    }
+    nodes = [
+        _gen_node(
+            rng,
+            n,
+            centroid_lat,
+            centroid_lon,
+            args.spread_km,
+            coverage,
+            args.last_heard_mean_sec,
+            args.last_heard_max_sec,
+        )
+        for n in ordered_nums
+    ]
+
+    # 3) Write JSONL.
+    out_path = pathlib.Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    # `generated_at_iso` is informational; it does NOT affect determinism because
+    # we derive it from the seed, not from wall clock. (Same seed -> same string.)
+    generated_at = _dt.datetime.fromtimestamp(args.seed, tz=_dt.timezone.utc).isoformat().replace("+00:00", "Z")
+    meta = {
+        "_meta": {
+            "version": 25,
+            "seed": args.seed,
+            "count": args.count,
+            "centroid": [centroid_lat, centroid_lon],
+            "spread_km": args.spread_km,
+            "generated_at_iso": generated_at,
+            "my_node_num_excluded": (None if my_node_num is None else f"0x{my_node_num:08x}"),
+            "coverage": coverage,
+            "last_heard_mean_sec": args.last_heard_mean_sec,
+            "last_heard_max_sec": args.last_heard_max_sec,
+        }
+    }
+    with out_path.open("w", encoding="utf-8") as f:
+        # `ensure_ascii=False` so emoji short_names survive. `sort_keys=True` for
+        # determinism (insertion order varies by Python version otherwise).
+        f.write(json.dumps(meta, ensure_ascii=False, sort_keys=True) + "\n")
+        for node in nodes:
+            f.write(json.dumps(node, ensure_ascii=False, sort_keys=True) + "\n")
+
+    print(f"wrote {args.count} nodes to {out_path} ({out_path.stat().st_size} bytes)", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
@@ -87,6 +87,9 @@
  </screenshots>

  <releases>
+    <release version="2.7.24" date="2026-05-08">
+      <url type="details">https://github.com/meshtastic/firmware/releases?q=tag%3Av2.7.24</url>
+    </release>
    <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>
@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Regenerate the fake-NodeDB fixtures: produces 250 / 500 / 1000 / 2000-node
+# JSONL seed files + their compiled v25 protobufs.
+#
+# Layout:
+#   test/fixtures/nodedb/seed_v25_<N>.jsonl   — COMMITTED, hand-editable.
+#   build/fixtures/nodedb/nodes_v25_<N>.proto — .gitignored, build artifact.
+#                                               Drop into /prefs/nodes.proto.
+#
+# Daily use:  ./bin/regen-fake-nodedbs.sh
+#   - Recompiles protos from committed seeds (fresh wall-clock timestamps).
+# Intentional seed bump:  REGEN_SEEDS=yes ./bin/regen-fake-nodedbs.sh
+#   - Overwrites the committed JSONL files with freshly-seeded data.
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# 1) Make sure the Python protobuf bindings exist (in-tree generation; .gitignored).
+if [[ ! -d bin/_generated/meshtastic ]]; then
+    echo "regenerating Python protobuf bindings (one-time)..."
+    ./bin/regen-py-protos.sh
+fi
+
+# 2) Pick a Python interpreter that has the meshtastic deps installed.
+#    Prefer the mcp-server venv (most likely to be set up by the operator).
+PY="python3"
+for cand in mcp-server/.venv/bin/python3 .venv/bin/python3; do
+    if [[ -x "$cand" ]]; then
+        PY="$cand"
+        break
+    fi
+done
+
+# 3) Pinned seeds per size — bump only when you intentionally want different
+#    structural data committed. Parallel arrays so the script works on
+#    macOS bash 3.2 (no `declare -A`).
+SIZES=(250 500 1000 2000)
+SEEDS=(20260511 20260512 20260513 20260514)
+
+REGEN_SEEDS="${REGEN_SEEDS:-no}"
+
+mkdir -p build/fixtures/nodedb test/fixtures/nodedb
+
+for i in 0 1 2 3; do
+    n="${SIZES[$i]}"
+    seed="${SEEDS[$i]}"
+    jsonl=$(printf "test/fixtures/nodedb/seed_v25_%04d.jsonl" "$n")
+    proto=$(printf "build/fixtures/nodedb/nodes_v25_%04d.proto" "$n")
+
+    if [[ "$REGEN_SEEDS" == "yes" || ! -f "$jsonl" ]]; then
+        $PY bin/gen-fake-nodedb-seed.py \
+            --count "$n" \
+            --seed "$seed" \
+            --out "$jsonl" \
+            --centroid 33.1284,-107.2528 \
+            --spread-km 60 \
+            --position-coverage 0.85 \
+            --telemetry-coverage 0.70 \
+            --environment-coverage 0.25 \
+            --status-coverage 0.40
+        echo "  seed:   $jsonl ($(wc -c < "$jsonl") bytes)"
+    fi
+
+    $PY bin/seed-json-to-proto.py --in "$jsonl" --out "$proto"
+    echo "  proto:  $proto ($(wc -c < "$proto") bytes)"
+done
+
+echo ""
+echo "Done. To load on Portduino native:"
+echo "  cp build/fixtures/nodedb/nodes_v25_1000.proto ~/.portduino/default/prefs/nodes.proto"
+echo ""
+echo "To push to a hardware device:"
+echo "  Use the mcp-server tool: push_fake_nodedb(size=1000, target=\"hardware\", port=\"/dev/cu.usbmodemXXXX\", confirm=True)"
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Regenerate Python protobuf bindings from the in-tree `protobufs/` submodule
+# into `bin/_generated/`. Called by bin/regen-fake-nodedbs.sh; also useful as
+# a standalone refresh after any change to a .proto file.
+#
+# Output is .gitignored — bindings are a build artifact.
+#
+# Namespace rewrite:
+# The .proto files declare `package meshtastic;`, which makes protoc emit
+# imports like `from meshtastic import mesh_pb2`. That conflicts with the
+# PyPI `meshtastic` package (which the mcp-server relies on for its
+# SerialInterface/BLEInterface transport). We post-process the generated
+# files to live under `meshtastic_v25` instead — both the directory layout
+# and all internal imports — so they coexist cleanly with the PyPI package.
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+if ! command -v protoc >/dev/null 2>&1; then
+    echo "ERROR: protoc not found in PATH." >&2
+    echo "  macOS: brew install protobuf" >&2
+    echo "  Ubuntu/Debian: apt install protobuf-compiler" >&2
+    exit 1
+fi
+
+OUT=bin/_generated
+LOCAL_NS=meshtastic_v25
+
+rm -rf "$OUT"
+mkdir -p "$OUT"
+
+# 1) Generate from the in-tree protos. nanopb.proto first so its descriptor
+#    is available for the [(nanopb).*] options on other messages.
+protoc \
+    --proto_path=protobufs \
+    --python_out="$OUT" \
+    protobufs/nanopb.proto \
+    protobufs/meshtastic/*.proto
+
+# 2) Move the generated `meshtastic/` directory to `meshtastic_v25/`.
+mv "$OUT/meshtastic" "$OUT/$LOCAL_NS"
+
+# 3) Rewrite internal imports: any reference to `meshtastic.X_pb2` or
+#    `from meshtastic import X_pb2` becomes `meshtastic_v25.*`.
+python3 bin/_rewrite_proto_namespace.py "$OUT/$LOCAL_NS" "$LOCAL_NS"
+
+# 4) Make the package importable.
+touch "$OUT/__init__.py"
+touch "$OUT/$LOCAL_NS/__init__.py"
+
+echo "regenerated Python protobuf bindings -> $OUT/$LOCAL_NS/ (namespace: $LOCAL_NS)" >&2
@@ -0,0 +1,342 @@
+#!/usr/bin/env python3
+"""Compile a committed seed JSONL into a binary meshtastic_NodeDatabase v25 proto.
+
+The input is produced by `bin/gen-fake-nodedb-seed.py`. Timestamps in the JSONL
+are stored as `*_offset_sec` (seconds before "now"); this script resolves them
+to absolute epochs using `--now-epoch` (default: current wall clock).
+
+Output is a raw `pb_encode`-compatible binary that can be dropped at
+`/prefs/nodes.proto` on the device (Portduino prefs dir or hardware via
+XModem) and loaded by `NodeDB::loadFromDisk` at boot.
+
+Wire format reference:
+  protobufs/meshtastic/deviceonly.proto  (NodeDatabase, NodeInfoLite, sat entries)
+  src/mesh/NodeDB.h:467-484              (bitfield bit positions)
+  src/mesh/NodeDB.cpp:1523-1524          (pb_decode entry point)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+import time
+from typing import Any
+
+# Prefer the in-tree generated Python protobuf bindings (bin/_generated/meshtastic_v25/)
+# because the firmware branch's protos (v25 NodeDatabase satellite arrays, slim
+# NodeInfoLite) are typically newer than what the PyPI `meshtastic` package
+# ships. Run `bin/regen-py-protos.sh` to (re)generate.
+#
+# Namespace note: the local bindings live under `meshtastic_v25` (NOT `meshtastic`)
+# to avoid shadowing the PyPI `meshtastic` package — bin/regen-py-protos.sh
+# post-processes the protoc output to rename the package.
+_HERE = pathlib.Path(__file__).resolve().parent
+_LOCAL_PROTO_DIR = _HERE / "_generated"
+if _LOCAL_PROTO_DIR.is_dir():
+    sys.path.insert(0, str(_LOCAL_PROTO_DIR))
+
+try:
+    from meshtastic_v25.deviceonly_pb2 import (  # type: ignore[import-not-found]
+        NodeDatabase,
+        NodeInfoLite,
+        NodePositionEntry,
+        NodeTelemetryEntry,
+        NodeEnvironmentEntry,
+        NodeStatusEntry,
+        PositionLite,
+    )
+    from meshtastic_v25.mesh_pb2 import HardwareModel, Position, StatusMessage  # type: ignore[import-not-found]
+    from meshtastic_v25.config_pb2 import Config  # type: ignore[import-not-found]
+    from meshtastic_v25.telemetry_pb2 import DeviceMetrics, EnvironmentMetrics  # type: ignore[import-not-found]
+except ImportError as local_err:
+    # Fall back to the PyPI package if in-tree bindings haven't been generated.
+    # Will fail the v25 assertion below if the PyPI package predates the
+    # satellite-DB schema, but at least gives a clear "run regen-py-protos.sh"
+    # error message instead of an opaque ImportError.
+    try:
+        from meshtastic.protobuf.deviceonly_pb2 import (
+            NodeDatabase,
+            NodeInfoLite,
+            NodePositionEntry,
+            NodeTelemetryEntry,
+            NodeEnvironmentEntry,
+            NodeStatusEntry,
+            PositionLite,
+        )
+        from meshtastic.protobuf.mesh_pb2 import HardwareModel, Position, StatusMessage
+        from meshtastic.protobuf.config_pb2 import Config
+        from meshtastic.protobuf.telemetry_pb2 import DeviceMetrics, EnvironmentMetrics
+    except ImportError as pypi_err:
+        print(
+            "ERROR: could not import meshtastic protobuf bindings.\n"
+            "  In-tree generation: run `bin/regen-py-protos.sh` (requires protoc).\n"
+            "  PyPI fallback: `pip install meshtastic` (may lag firmware branch).\n"
+            f"  local error (meshtastic_v25): {local_err}\n"
+            f"  pypi error  (meshtastic.protobuf): {pypi_err}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+# Fail loudly if bindings predate v25 (no satellite arrays).
+assert (
+    hasattr(NodeDatabase, "DESCRIPTOR")
+    and "positions" in NodeDatabase.DESCRIPTOR.fields_by_name
+), (
+    "Loaded meshtastic bindings are older than v25 (NodeDatabase.positions missing). "
+    "Run `bin/regen-py-protos.sh` against the in-tree protobufs/ submodule."
+)
+
+# ---------------------------------------------------------------------------
+# Bitfield bit positions (mirror src/mesh/NodeDB.h:467-484).
+# ---------------------------------------------------------------------------
+BIT_IS_KEY_MANUALLY_VERIFIED = 0
+BIT_IS_MUTED = 1
+BIT_VIA_MQTT = 2
+BIT_IS_FAVORITE = 3
+BIT_IS_IGNORED = 4
+BIT_HAS_USER = 5
+BIT_IS_LICENSED = 6
+BIT_IS_UNMESSAGABLE = 7
+BIT_HAS_IS_UNMESSAGABLE = 8
+
+BITFIELD_LAYOUT = (
+    # JSON key            bit position
+    ("is_key_manually_verified", BIT_IS_KEY_MANUALLY_VERIFIED),
+    ("is_muted", BIT_IS_MUTED),
+    ("via_mqtt", BIT_VIA_MQTT),
+    ("is_favorite", BIT_IS_FAVORITE),
+    ("is_ignored", BIT_IS_IGNORED),
+    ("has_user", BIT_HAS_USER),
+    ("is_licensed", BIT_IS_LICENSED),
+    ("is_unmessagable", BIT_IS_UNMESSAGABLE),
+    ("has_is_unmessagable", BIT_HAS_IS_UNMESSAGABLE),
+)
+
+
+def _pack_bitfield(bf: dict[str, bool]) -> int:
+    out = 0
+    for key, shift in BITFIELD_LAYOUT:
+        if bf.get(key, False):
+            out |= (1 << shift)
+    return out
+
+
+def _validate_node(node: dict[str, Any]) -> None:
+    """Friendly errors so hand-editors get clear feedback."""
+    if "num" not in node or not isinstance(node["num"], str):
+        raise ValueError(f"node missing/invalid 'num' (must be hex string): {node!r}")
+    if "long_name" not in node:
+        raise ValueError(f"node {node['num']}: missing 'long_name'")
+    if len(node["long_name"]) > 24:
+        raise ValueError(
+            f"node {node['num']}: long_name {node['long_name']!r} is "
+            f"{len(node['long_name'])} chars; max 24 (nanopb max_size:25 minus NUL)"
+        )
+    if "short_name" in node:
+        # short_name max_size:5 (incl. NUL) → 4 bytes of content.
+        # Char count is irrelevant — emojis with variation selectors (e.g. ❄️ = 6 B)
+        # would slip past a `len(str) > 4` check. Always measure bytes.
+        b = node["short_name"].encode("utf-8")
+        if len(b) > 4:
+            raise ValueError(
+                f"node {node['num']}: short_name {node['short_name']!r} is "
+                f"{len(b)} bytes UTF-8; max 4 (nanopb max_size:5 minus NUL)"
+            )
+    pk = node.get("public_key_hex", "")
+    if pk and len(pk) != 64:
+        raise ValueError(
+            f"node {node['num']}: public_key_hex must be 64 hex chars or empty; "
+            f"got {len(pk)} chars"
+        )
+    if pk:
+        try:
+            bytes.fromhex(pk)
+        except ValueError as e:
+            raise ValueError(f"node {node['num']}: public_key_hex is not valid hex: {e}")
+
+
+def _resolve_time(
+    node: dict[str, Any],
+    field_absolute: str,
+    field_offset: str,
+    now_epoch: int,
+) -> int:
+    """If `field_absolute` is set, use it; else compute `now_epoch - offset`."""
+    if field_absolute in node and node[field_absolute] is not None:
+        return int(node[field_absolute])
+    offset = node.get(field_offset, 0)
+    return max(0, int(now_epoch) - int(offset))
+
+
+def _build_node_info_lite(node: dict[str, Any], now_epoch: int) -> NodeInfoLite:
+    _validate_node(node)
+    info = NodeInfoLite()
+    info.num = int(node["num"], 16) if isinstance(node["num"], str) else int(node["num"])
+    info.long_name = node.get("long_name", "")
+    info.short_name = node.get("short_name", "")
+    # Enum lookups will raise ValueError on unknown names — that's exactly what we want.
+    info.hw_model = HardwareModel.Value(node.get("hw_model", "UNSET"))
+    info.role = Config.DeviceConfig.Role.Value(node.get("role", "CLIENT"))
+    pk_hex = node.get("public_key_hex", "")
+    if pk_hex:
+        info.public_key = bytes.fromhex(pk_hex)
+    info.snr = float(node.get("snr", 0.0))
+    info.channel = int(node.get("channel", 0))
+    if "hops_away" in node:
+        # `optional uint32 hops_away = 9;` — in Python protobuf, assigning the
+        # field implicitly sets HasField("hops_away") to True. No has_hops_away
+        # setter exists (unlike the C++ nanopb-generated header).
+        info.hops_away = int(node["hops_away"])
+    info.next_hop = int(node.get("next_hop", 0))
+    info.last_heard = _resolve_time(node, "last_heard", "last_heard_offset_sec", now_epoch)
+    info.bitfield = _pack_bitfield(node.get("bitfield", {}))
+    return info
+
+
+def _build_position_entry(num: int, pos: dict[str, Any], now_epoch: int) -> NodePositionEntry:
+    entry = NodePositionEntry()
+    entry.num = num
+    pl = PositionLite()
+    # Firmware stores lat/long as int32 in 1e-7 degrees.
+    pl.latitude_i = int(round(float(pos["latitude"]) * 1e7))
+    pl.longitude_i = int(round(float(pos["longitude"]) * 1e7))
+    pl.altitude = int(pos.get("altitude", 0))
+    pl.time = _resolve_time(pos, "time", "time_offset_sec", now_epoch)
+    pl.location_source = Position.LocSource.Value(pos.get("location_source", "LOC_UNSET"))
+    entry.position.CopyFrom(pl)
+    return entry
+
+
+def _build_telemetry_entry(num: int, tel: dict[str, Any]) -> NodeTelemetryEntry:
+    entry = NodeTelemetryEntry()
+    entry.num = num
+    dm = DeviceMetrics()
+    if "battery_level" in tel:
+        dm.battery_level = int(tel["battery_level"])
+    if "voltage" in tel:
+        dm.voltage = float(tel["voltage"])
+    if "channel_utilization" in tel:
+        dm.channel_utilization = float(tel["channel_utilization"])
+    if "air_util_tx" in tel:
+        dm.air_util_tx = float(tel["air_util_tx"])
+    if "uptime_seconds" in tel:
+        dm.uptime_seconds = int(tel["uptime_seconds"])
+    entry.device_metrics.CopyFrom(dm)
+    return entry
+
+
+def _build_environment_entry(num: int, env: dict[str, Any]) -> NodeEnvironmentEntry:
+    entry = NodeEnvironmentEntry()
+    entry.num = num
+    em = EnvironmentMetrics()
+    if "temperature" in env:
+        em.temperature = float(env["temperature"])
+    if "relative_humidity" in env:
+        em.relative_humidity = float(env["relative_humidity"])
+    if "barometric_pressure" in env:
+        em.barometric_pressure = float(env["barometric_pressure"])
+    if "iaq" in env:
+        em.iaq = int(env["iaq"])
+    entry.environment_metrics.CopyFrom(em)
+    return entry
+
+
+def _build_status_entry(num: int, status: dict[str, Any]) -> NodeStatusEntry:
+    # `StatusMessage` (mesh.proto:1445) has a single `string status` field.
+    entry = NodeStatusEntry()
+    entry.num = num
+    sm = StatusMessage()
+    if "status" in status:
+        sm.status = str(status["status"])
+    entry.status.CopyFrom(sm)
+    return entry
+
+
+def compile_jsonl_to_proto(jsonl_path: pathlib.Path, now_epoch: int) -> bytes:
+    """Read a seed JSONL and return the encoded NodeDatabase bytes."""
+    lines = jsonl_path.read_text(encoding="utf-8").splitlines()
+    if not lines:
+        raise ValueError(f"{jsonl_path} is empty")
+    meta_line = lines[0]
+    meta_obj = json.loads(meta_line)
+    meta = meta_obj.get("_meta", {})
+    version = meta.get("version")
+    if version != 25:
+        raise ValueError(
+            f"{jsonl_path}: meta version is {version!r}; this compiler "
+            f"requires version=25. Regenerate the seed with the matching tooling."
+        )
+
+    db = NodeDatabase()
+    db.version = 25
+
+    for ln, raw in enumerate(lines[1:], start=2):
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            node = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"{jsonl_path}:{ln} JSON parse error: {e}")
+
+        num = int(node["num"], 16) if isinstance(node["num"], str) else int(node["num"])
+
+        # Header
+        info = _build_node_info_lite(node, now_epoch)
+        db.nodes.append(info)
+
+        # Satellites (nullable)
+        if node.get("position"):
+            db.positions.append(_build_position_entry(num, node["position"], now_epoch))
+        if node.get("telemetry"):
+            db.telemetry.append(_build_telemetry_entry(num, node["telemetry"]))
+        if node.get("environment"):
+            db.environment.append(_build_environment_entry(num, node["environment"]))
+        if node.get("status"):
+            db.status.append(_build_status_entry(num, node["status"]))
+
+    return db.SerializeToString()
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(
+        description="Compile a seed JSONL into a binary v25 NodeDatabase proto.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    p.add_argument("--in", dest="in_path", required=True, help="Input seed JSONL.")
+    p.add_argument("--out", required=True, help="Output binary .proto path.")
+    p.add_argument(
+        "--now-epoch",
+        type=int,
+        default=None,
+        help="Pin 'now' to this Unix epoch (for byte-identical CI). Default: time.time().",
+    )
+    args = p.parse_args(argv)
+
+    in_path = pathlib.Path(args.in_path)
+    if not in_path.is_file():
+        print(f"input not found: {in_path}", file=sys.stderr)
+        return 2
+
+    now_epoch = args.now_epoch if args.now_epoch is not None else int(time.time())
+
+    try:
+        encoded = compile_jsonl_to_proto(in_path, now_epoch)
+    except ValueError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 3
+
+    out_path = pathlib.Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_bytes(encoded)
+    print(
+        f"compiled {in_path} -> {out_path} ({len(encoded)} bytes, now_epoch={now_epoch})",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,118 @@
+#!/bin/bash
+
+# Script to show commits in develop that are not in master
+# with their associated PR info and commit hashes
+# 
+# Usage:
+#   ./show-unmerged-prs.sh            # Show all unmerged commits
+#   ./show-unmerged-prs.sh --bugfix   # Show only bugfix-labeled PRs
+
+set -e
+
+REPO="firmware"
+OWNER="meshtastic"
+BASE_BRANCH="master"
+HEAD_BRANCH="develop"
+LIMIT=100
+FILTER_LABEL=""
+
+# Parse arguments
+for arg in "$@"; do
+    case $arg in
+        --bugfix)
+            FILTER_LABEL="bugfix"
+            shift
+            ;;
+        --feature)
+            FILTER_LABEL="feature"
+            shift
+            ;;
+        --help)
+            echo "Usage: $0 [OPTIONS]"
+            echo "Options:"
+            echo "  --bugfix     Show only PRs labeled with 'bugfix'"
+            echo "  --feature    Show only PRs labeled with 'feature'"
+            echo "  --help       Show this help message"
+            exit 0
+            ;;
+    esac
+done
+
+if [ -n "$FILTER_LABEL" ]; then
+    echo "Fetching commits in $HEAD_BRANCH that are not in $BASE_BRANCH (filtered by label: $FILTER_LABEL)..."
+else
+    echo "Fetching commits in $HEAD_BRANCH that are not in $BASE_BRANCH..."
+fi
+echo ""
+
+# Check if gh CLI is available
+if ! command -v gh &> /dev/null; then
+    echo "ERROR: GitHub CLI (gh) not found. Please install it first."
+    echo "Visit: https://cli.github.com/"
+    exit 1
+fi
+
+# Get commits in develop that are not in master
+# For each commit, try to find associated PR
+git fetch origin develop master 2>/dev/null || true
+
+# Use git to get the list of commits
+commits=$(git log --pretty=format:"%H|%s" origin/master..origin/develop | head -n $LIMIT)
+
+count=0
+displayed=0
+echo "Commits in $HEAD_BRANCH not in $BASE_BRANCH:"
+echo "=============================================="
+echo ""
+
+while IFS='|' read -r hash subject; do
+    ((count++))
+    
+    # Try to find the PR for this commit
+    # Extract PR number, title, description, and labels
+    pr_response=$(gh api -X GET "/repos/$OWNER/$REPO/commits/$hash/pulls" \
+        -H "Accept: application/vnd.github.v3+json" 2>/dev/null | \
+        jq -r '.[0] | "\(.number)|\(.title)|\(.body // "No description")|\(.labels | map(.name) | join(","))"' 2>/dev/null || echo "||||")
+    
+    if [ -z "$pr_response" ] || [ "$pr_response" = "||||" ]; then
+        # If no PR found, skip if filter is active, otherwise show the commit
+        if [ -z "$FILTER_LABEL" ]; then
+            ((displayed++))
+            echo "[$displayed] Commit: $hash"
+            echo "    Subject: $subject"
+            echo "    PR: Not found in GitHub"
+            echo ""
+        fi
+    else
+        IFS='|' read -r pr_num pr_title pr_desc pr_labels <<< "$pr_response"
+        
+        # Check if filter matches
+        if [ -n "$FILTER_LABEL" ]; then
+            # Only show if the label is in the labels list
+            if ! echo "$pr_labels" | grep -q "$FILTER_LABEL"; then
+                continue
+            fi
+        fi
+        
+        ((displayed++))
+        echo "[$displayed] PR #$pr_num - $pr_title"
+        echo "    Commit: $hash"
+        if [ -n "$pr_desc" ] && [ "$pr_desc" != "No description" ]; then
+            # Truncate description to 200 chars
+            desc_short="${pr_desc:0:200}"
+            [ ${#pr_desc} -gt 200 ] && desc_short+="..."
+            echo "    Description: $desc_short"
+        fi
+        if [ -n "$pr_labels" ] && [ "$pr_labels" != "" ]; then
+            echo "    Labels: $pr_labels"
+        fi
+        echo ""
+    fi
+done <<< "$commits"
+
+echo ""
+if [ -n "$FILTER_LABEL" ]; then
+    echo "Done. Showing $displayed PRs with label '$FILTER_LABEL' from $displayed commits checked."
+else
+    echo "Done. Showing $displayed commits from $HEAD_BRANCH not in $BASE_BRANCH."
+fi
@@ -0,0 +1,42 @@
+{
+  "build": {
+    "arduino": {
+      "ldscript": "esp32s3_out.ld",
+      "memory_type": "qio_opi"
+    },
+    "core": "esp32",
+    "extra_flags": [
+      "-D BOARD_HAS_PSRAM",
+      "-D ARDUINO_USB_CDC_ON_BOOT=0",
+      "-D ARDUINO_USB_MODE=0",
+      "-D ARDUINO_RUNNING_CORE=1",
+      "-D ARDUINO_EVENT_RUNNING_CORE=0"
+    ],
+    "f_cpu": "240000000L",
+    "f_flash": "80000000L",
+    "flash_mode": "qio",
+    "psram_type": "qio_opi",
+    "hwids": [["0x303A", "0x1001"]],
+    "mcu": "esp32s3",
+    "variant": "ELECROW-ThinkNode-M7"
+  },
+  "connectivity": ["wifi", "bluetooth", "lora"],
+  "debug": {
+    "default_tool": "esp-builtin",
+    "onboard_tools": ["esp-builtin"],
+    "openocd_target": "esp32s3.cfg"
+  },
+  "frameworks": ["arduino", "espidf"],
+  "name": "ELECROW ThinkNode M7",
+  "upload": {
+    "flash_size": "8MB",
+    "maximum_ram_size": 524288,
+    "maximum_size": 8388608,
+    "use_1200bps_touch": true,
+    "wait_for_upload_port": true,
+    "require_upload_port": true,
+    "speed": 921600
+  },
+  "url": "https://www.elecrow.com",
+  "vendor": "ELECROW"
+}
@@ -0,0 +1,43 @@
+{
+  "build": {
+    "arduino": {
+      "ldscript": "esp32s3_out.ld",
+      "partitions": "default_16MB.csv",
+      "memory_type": "qio_opi"
+    },
+    "core": "esp32",
+    "extra_flags": [
+      "-DBOARD_HAS_PSRAM",
+      "-DARDUINO_USB_CDC_ON_BOOT=1",
+      "-DARDUINO_USB_MODE=1",
+      "-DARDUINO_RUNNING_CORE=1",
+      "-DARDUINO_EVENT_RUNNING_CORE=1"
+    ],
+    "f_cpu": "240000000L",
+    "f_flash": "80000000L",
+    "flash_mode": "qio",
+    "psram_type": "opi",
+    "hwids": [["0x303A", "0x1001"]],
+    "mcu": "esp32s3",
+    "variant": "heltec_v4_r8"
+  },
+  "connectivity": ["wifi", "bluetooth", "lora"],
+  "debug": {
+    "default_tool": "esp-builtin",
+    "onboard_tools": ["esp-builtin"],
+    "openocd_target": "esp32s3.cfg"
+  },
+  "frameworks": ["arduino", "espidf"],
+  "name": "heltec_wifi_lora_32 v4 r8 (16 MB FLASH, 8 MB PSRAM)",
+  "upload": {
+    "flash_size": "16MB",
+    "maximum_ram_size": 327680,
+    "maximum_size": 16777216,
+    "use_1200bps_touch": true,
+    "wait_for_upload_port": true,
+    "require_upload_port": true,
+    "speed": 921600
+  },
+  "url": "https://heltec.org/",
+  "vendor": "heltec"
+}
@@ -0,0 +1,41 @@
+{
+  "build": {
+    "arduino": {
+      "ldscript": "esp32s3_out.ld",
+      "memory_type": "qio_opi"
+    },
+    "core": "esp32",
+    "extra_flags": [
+      "-DBOARD_HAS_PSRAM",
+      "-DARDUINO_USB_CDC_ON_BOOT=1",
+      "-DARDUINO_USB_MODE=1",
+      "-DARDUINO_RUNNING_CORE=1",
+      "-DARDUINO_EVENT_RUNNING_CORE=0"
+    ],
+    "f_cpu": "240000000L",
+    "f_flash": "80000000L",
+    "flash_mode": "qio",
+    "hwids": [["0x303A", "0x1001"]],
+    "mcu": "esp32s3",
+    "variant": "station-g3"
+  },
+  "connectivity": ["wifi", "bluetooth", "lora"],
+  "debug": {
+    "default_tool": "esp-builtin",
+    "onboard_tools": ["esp-builtin"],
+    "openocd_target": "esp32s3.cfg"
+  },
+  "frameworks": ["arduino", "espidf"],
+  "name": "BQ Station G3",
+  "upload": {
+    "flash_size": "16MB",
+    "maximum_ram_size": 327680,
+    "maximum_size": 16777216,
+    "use_1200bps_touch": true,
+    "wait_for_upload_port": true,
+    "require_upload_port": true,
+    "speed": 921600
+  },
+  "url": "",
+  "vendor": "BQ Consulting"
+}
@@ -1,3 +1,9 @@
+meshtasticd (2.7.24.0) unstable; urgency=medium
+
+  * Version 2.7.24
+
+ -- GitHub Actions <github-actions[bot]@users.noreply.github.com>  Fri, 08 May 2026 10:44:12 +0000
+
 meshtasticd (2.7.23.0) unstable; urgency=medium

  * Version 2.7.23
@@ -1,4 +1,5 @@
 #!/usr/bin/bash
+set -e
 export DEBEMAIL="jbennett@incomsystems.biz"
 export PLATFORMIO_LIBDEPS_DIR=pio/libdeps
 export PLATFORMIO_PACKAGES_DIR=pio/packages
@@ -82,5 +82,18 @@ if esp32_kind == "esp32":
        ]
    )
 else:
-    # For newer ESP32 targets, using newlib nano works better.
-    env.Append(LINKFLAGS=["--specs=nano.specs", "-u", "_printf_float"])
+    # For newer ESP32 targets, using newlib nano works better. Skip on
+    # variants that explicitly opt out — the IDF 5.1 framework override the
+    # HaLow variant uses already includes nano.specs, so re-adding it triggers
+    # a duplicate spec definition error at link time.
+    cppdefines = env.get("CPPDEFINES", [])
+    if not any(
+        (isinstance(d, str) and d == "MESHTASTIC_SKIP_NANO_SPECS")
+        or (
+            isinstance(d, (list, tuple))
+            and len(d) > 0
+            and d[0] == "MESHTASTIC_SKIP_NANO_SPECS"
+        )
+        for d in cppdefines
+    ):
+        env.Append(LINKFLAGS=["--specs=nano.specs", "-u", "_printf_float"])
@@ -0,0 +1,28 @@
+"""
+PlatformIO doesn't natively link .o files vendored inside a library directory.
+The Morse Micro SDK ships the chip firmware (mm6108.mbin.o) and per-region BCF
+(bcf_mf08651_us.mbin.o) as pre-built object files containing data sections.
+This script appends them to LINKFLAGS so they land in the final ELF.
+
+US region only for now — when we add EU/JP/KR variants, gate the BCF here on a
+build flag and pick the matching .o file.
+"""
+
+import os
+
+Import("env", "projenv")
+
+LIB_DIR = os.path.join(env.subst("$PROJECT_DIR"), "lib", "MorseWlan")
+
+mbin_objects = [
+    os.path.join(LIB_DIR, "src", "mm6108.mbin.o"),
+    os.path.join(LIB_DIR, "src", "bcf_mf08651_us.mbin.o"),
+]
+
+# Only add objects that actually exist; missing ones surface as link errors,
+# not silent corruption.
+for obj in mbin_objects:
+    if not os.path.isfile(obj):
+        print("warning: mm-iot-esp32 blob missing: %s" % obj)
+
+env.Append(LINKFLAGS=mbin_objects)
@@ -0,0 +1,77 @@
+/*
+ * Copyright 2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @defgroup MBIN Morse BINary Loader API
+ *
+ * This file defines the structure of the @c MBIN file.
+ *
+ * @{
+ */
+
+#pragma once
+
+#ifndef PACKED
+/** Macro for the compiler packed attribute */
+#define PACKED __attribute__((packed))
+#endif
+
+/** Enumeration of TLV field types */
+enum mbin_tlv_types {
+    FIELD_TYPE_FW_TLV_BCF_ADDR = 0x0001,
+    FIELD_TYPE_MAGIC = 0x8000,
+    FIELD_TYPE_FW_SEGMENT = 0x8001,
+    FIELD_TYPE_FW_SEGMENT_DEFLATED = 0x8002,
+    FIELD_TYPE_BCF_BOARD_CONFIG = 0x8100,
+    FIELD_TYPE_BCF_REGDOM = 0x8101,
+    FIELD_TYPE_BCF_BOARD_DESC = 0x8102,
+    FIELD_TYPE_BCF_BUILD_VER = 0x8103,
+    FIELD_TYPE_SW_SEGMENT = 0x8201,
+    FIELD_TYPE_SW_SEGMENT_DEFLATED = 0x8202,
+    FIELD_TYPE_EOF = 0x8f00,
+    FIELD_TYPE_EOF_WITH_SIGNATURE = 0x8f01,
+};
+
+/** TLV header data structure. */
+struct PACKED mbin_tlv_hdr {
+    /** Type (see mbin_tlv_types). */
+    uint16_t type;
+    /** Length of payload (excludes header). */
+    uint16_t len;
+};
+
+/** Data header in a FIELD_TYPE_XX_SEGMENT field. */
+struct PACKED mbin_segment_hdr {
+    /** Destination base address at which the data should be loaded. */
+    uint32_t base_address;
+};
+
+/** Data header in a FIELD_TYPE_XX_SEGMENT_DEFLATED field. */
+struct PACKED mbin_deflated_segment_hdr {
+    /** Destination base address at which the data should be loaded. */
+    uint32_t base_address;
+    /** Size of deflated data, infer size of compressed data from TLV length */
+    uint16_t chunk_size;
+    /** ZLib header */
+    uint8_t zlib_header[2];
+};
+
+/** Data header in a @c FIELD_TYPE_BCF_REGDOM field. */
+struct PACKED mbin_regdom_hdr {
+    /** Country code that this @c regdom applies to. */
+    uint8_t country_code[2];
+    /** Reserved */
+    uint16_t reserved;
+};
+
+/** Expected value of the magic field for a SW image @c MMSW. */
+#define MBIN_SW_MAGIC_NUMBER (0x57534d4d)
+/** Expected value of the magic field for a firmware image @c MMFW. */
+#define MBIN_FW_MAGIC_NUMBER (0x57464d4d)
+/** Expected value of the magic field for a BCF @c MMBC. */
+#define MBIN_BCF_MAGIC_NUMBER (0x43424d4d)
+
+/** @} */
@@ -0,0 +1,124 @@
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * This file should be included from the application mbedtls_config.h file to ensure that
+ * the mbedTLS features necessary for morselib functionality are enabled.
+ *
+ * It is recommended to include this file at the _end_ of the application mbedtls_config.h file
+ * to avoid redefinition of macros.
+ */
+
+/* Cipher modes */
+#ifndef MBEDTLS_CIPHER_MODE_CBC
+#define MBEDTLS_CIPHER_MODE_CBC
+#endif
+
+#ifndef MBEDTLS_CIPHER_MODE_CTR
+#define MBEDTLS_CIPHER_MODE_CTR
+#endif
+
+/* EC curves */
+#ifndef MBEDTLS_ECP_DP_SECP256R1_ENABLED
+#define MBEDTLS_ECP_DP_SECP256R1_ENABLED
+#endif
+
+#ifndef MBEDTLS_ECP_DP_SECP384R1_ENABLED
+#define MBEDTLS_ECP_DP_SECP384R1_ENABLED
+#endif
+
+#ifndef MBEDTLS_ECP_DP_SECP521R1_ENABLED
+#define MBEDTLS_ECP_DP_SECP521R1_ENABLED
+#endif
+
+/* Features */
+#ifndef MBEDTLS_AES_C
+#define MBEDTLS_AES_C
+#endif
+
+#ifndef MBEDTLS_ASN1_PARSE_C
+#define MBEDTLS_ASN1_PARSE_C
+#endif
+
+#ifndef MBEDTLS_ASN1_WRITE_C
+#define MBEDTLS_ASN1_WRITE_C
+#endif
+
+#ifndef MBEDTLS_BIGNUM_C
+#define MBEDTLS_BIGNUM_C
+#endif
+
+#ifndef MBEDTLS_CIPHER_C
+#define MBEDTLS_CIPHER_C
+#endif
+
+#ifndef MBEDTLS_CMAC_C
+#define MBEDTLS_CMAC_C
+#endif
+
+#ifndef MBEDTLS_CTR_DRBG_C
+#define MBEDTLS_CTR_DRBG_C
+#endif
+
+#ifndef MBEDTLS_ECDH_C
+#define MBEDTLS_ECDH_C
+#endif
+
+#ifndef MBEDTLS_ECP_C
+#define MBEDTLS_ECP_C
+#endif
+
+#ifndef MBEDTLS_ENTROPY_C
+#define MBEDTLS_ENTROPY_C
+#endif
+
+#ifndef MBEDTLS_MD_C
+#define MBEDTLS_MD_C
+#endif
+
+#ifndef MBEDTLS_NIST_KW_C
+#define MBEDTLS_NIST_KW_C
+#endif
+
+#ifndef MBEDTLS_OID_C
+#define MBEDTLS_OID_C
+#endif
+
+#ifndef MBEDTLS_PK_C
+#define MBEDTLS_PK_C
+#endif
+
+#ifndef MBEDTLS_PK_PARSE_C
+#define MBEDTLS_PK_PARSE_C
+#endif
+
+#ifndef MBEDTLS_PK_WRITE_C
+#define MBEDTLS_PK_WRITE_C
+#endif
+
+#ifndef MBEDTLS_PKCS5_C
+#define MBEDTLS_PKCS5_C
+#endif
+
+#ifndef MBEDTLS_SHA1_C
+#define MBEDTLS_SHA1_C
+#endif
+
+#ifndef MBEDTLS_SHA224_C
+#define MBEDTLS_SHA224_C
+#endif
+
+#ifndef MBEDTLS_SHA256_C
+#define MBEDTLS_SHA256_C
+#endif
+
+#ifndef MBEDTLS_SHA384_C
+#define MBEDTLS_SHA384_C
+#endif
+
+#ifndef MBEDTLS_SHA512_C
+#define MBEDTLS_SHA512_C
+#endif
@@ -0,0 +1,331 @@
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @defgroup MMHAL Morse Micro Hardware Abstraction Layer (mmhal) API
+ *
+ * This API provides abstraction from the underlying hardware/BSP.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include "mmhal_flash.h"
+#include "mmhal_wlan.h"
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <time.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Initialization before RTOS scheduler starts. */
+void mmhal_early_init(void);
+
+/** Initialization after RTOS scheduler started. */
+void mmhal_init(void);
+
+/** Enumeration of ISR states (i.e., whether in ISR or not). */
+enum mmhal_isr_state {
+    MMHAL_NOT_IN_ISR,        /**< The function was not executed from ISR context. */
+    MMHAL_IN_ISR,            /**< The function was executed from ISR context. */
+    MMHAL_ISR_STATE_UNKNOWN, /**< The HAL does not support checking ISR state. */
+};
+
+/**
+ * Enumeration for different LED's on the board.
+ *
+ * @note Some of these LED's may not be available on all boards and some of these values
+ *       may refer to the same LED.
+ */
+enum mmhal_led_id { LED_RED, LED_GREEN, LED_BLUE, LED_WHITE };
+
+/** Enumeration of MCU sleep state. */
+enum mmhal_sleep_state {
+    MMHAL_SLEEP_DISABLED, /**< Disable MCU sleep. */
+    MMHAL_SLEEP_SHALLOW,  /**< MCU to enter shallow sleep. */
+    MMHAL_SLEEP_DEEP,     /**< MCU can enter deep sleep. */
+};
+
+/** A value of 0 turns OFF an LED */
+#define LED_OFF 0
+
+/**
+ * A value of 255 turns an LED ON fully.
+ *
+ * Some boards support varying an LED's brightness. For these boards a value between 1 and 255
+ * will result in proportionately varying levels of brightness. LED's that do not have a
+ * brightness control feature will just turn ON fully for any non zero value.
+ */
+#define LED_ON 255
+
+/**
+ * Get the current ISR state  (i.e., whether in ISR or not).
+ *
+ * @returns the current ISR state, or @c MMHAL_ISR_STATE_UNKNOWN if the HAL does not support
+ *          checking ISR state.
+ */
+enum mmhal_isr_state mmhal_get_isr_state(void);
+
+/**
+ * Write to the debug log.
+ *
+ * It is assumed the caller will have mechanisms in place to prevent concurrent access.
+ *
+ * @param data  Buffer containing data to write.
+ * @param len   Length of data in buffer.
+ */
+void mmhal_log_write(const uint8_t *data, size_t len);
+
+/**
+ * Flush the debug log before returning.
+ *
+ * @warning Implementations of this function must support being invoked with interrupts disabled.
+ */
+void mmhal_log_flush(void);
+
+/**
+ * Generate a random 32 bit integer within the given range.
+ *
+ * @param min   Minimum value (inclusive).
+ * @param max   Maximum value (inclusive).
+ *
+ * @returns a randomly generated integer (min <= i <= max).
+ */
+uint32_t mmhal_random_u32(uint32_t min, uint32_t max);
+
+/** Reset the microcontroller. */
+void mmhal_reset(void);
+
+/**
+ * Set the specified LED to the requested level. Do nothing if the requested LED does not exist.
+ *
+ * @param led   The LED to set, if the platform supports it. See @ref mmhal_led_id
+ * @param level The level to set it to. 0 means OFF and non-zero means ON. If the platform supports
+ *              brightness levels then 255 is full. Defines @ref LED_ON and @ref LED_OFF are
+ *              provided for ease of use.
+ */
+void mmhal_set_led(uint8_t led, uint8_t level);
+
+/**
+ * Set the error LED to the requested state.
+ *
+ * @note This function is called by the bootloader and so needs to do all the initialization
+ *       required to set the LED's as the bootloader does not use the regular BSP initialization
+ *       located in main.c for configuring @c GPIO's and setting clock gates as required.
+ *
+ * @param state Set to true if the LED needs to be turned on,
+ *              or false if the led needs to be turned off.
+ */
+void mmhal_set_error_led(bool state);
+
+/**
+ * Enumeration for buttons on the board.
+ *
+ * @note The support for each button is platform dependent.
+ */
+enum mmhal_button_id { BUTTON_ID_USER0 };
+
+/**
+ * Enumeration for button states
+ */
+enum mmhal_button_state { BUTTON_RELEASED, BUTTON_PRESSED };
+
+/** Button state callback function prototype. */
+typedef void (*mmhal_button_state_cb_t)(enum mmhal_button_id button_id, enum mmhal_button_state button_state);
+
+/**
+ * Registers a callback handler for button state changes.
+ *
+ * @note The callback will be executed in an Interrupt Service Routine context
+ *
+ * @param button_id The button whose state should be reported to the callback
+ * @param button_state_cb The function to call on button state change, or NULL to disable.
+ * @returns True if the callback is registered successfully, False if not supported
+ */
+bool mmhal_set_button_callback(enum mmhal_button_id button_id, mmhal_button_state_cb_t button_state_cb);
+
+/**
+ * Returns the registered callback handler for button state changes.
+ *
+ * @param button_id The button whose callback should be returned
+ * @returns The registered callback or NULL if no callback registered
+ */
+mmhal_button_state_cb_t mmhal_get_button_callback(enum mmhal_button_id button_id);
+
+/**
+ * Reads the state of the specified button.
+ *
+ * @param button_id The button state to read
+ * @returns The current button state, or BUTTON_RELEASED if not supported
+ */
+enum mmhal_button_state mmhal_get_button(enum mmhal_button_id button_id);
+
+/**
+ * Reads information that can be used to identify the hardware platform, such as
+ * hardware ID and version number, in the form of a user readable string.
+ *
+ * This function attempts to detect the correct hardware and version.
+ * The actual means of detecting the correct hardware and version will vary from
+ * implementation to implementation and may use means such as identification
+ * information stored in EEPROM or devices detected on GPIO, SPI or I2C interfaces.
+ * Returns false if the hardware could not be identified correctly.
+ *
+ * @param version_buffer The pre-allocated buffer to return the hardware ID and version in.
+ * @param version_buffer_length The length of the pre-allocated buffer.
+ * @returns              True if the hardware was correctly identified and returned.
+ */
+bool mmhal_get_hardware_version(char *version_buffer, size_t version_buffer_length);
+
+/**
+ * Macro to simplify debug pin mask/value definition.
+ *
+ * @param _pin_num  The pin number to set in the mask. Must be 0-31 (inclusive).
+ *
+ * Example:
+ *
+ *     mmhal_set_debug_pins(MMHAL_DEBUG_PIN(0), MMHAL_DEBUG_PIN(0));
+ */
+#define MMHAL_DEBUG_PIN(_pin_num) (1ul << (_pin_num))
+
+/** Bit mask with all debug pins selected. */
+#define MMHAL_ALL_DEBUG_PINS (UINT32_MAX)
+
+/**
+ * Set the value one or more debug pins.
+ *
+ * Each platform can define up to 32 GPIOs for application use. If a GPIO is not supported
+ * by a platform then attempts to set it will be silently ignored. These GPIOs are intended
+ * for debug/test purposes.
+ *
+ * @param mask      Mask of GPIOs to modify. Each bit in this mask that is set will result in
+ *                  the corresponding GPIO being being set to the corresponding value given in
+ *                  @p values.
+ * @param values    Bit field, where each bit corresponds to a GPIO, specifying the direction
+ *                  to drive each GPIO with 1 meaning drive high and 0 meaning drive low.
+ *                  Only GPIOs with the corresponding bit set in @p mask will be modified.
+ *
+ * @sa MM_DEBUG_PIN_MASK
+ */
+void mmhal_set_debug_pins(uint32_t mask, uint32_t values);
+
+/**
+ * Returns the time of day as set in the RTC.
+ * Time is in UTC.
+ *
+ * @return    Epoch time (seconds since 1 Jan 1970) or 0 on failure.
+ */
+time_t mmhal_get_time();
+
+/**
+ * Sets the RTC to the specified time in UTC.
+ *
+ * @note While Unix epoch time supports years from 1970, most Real Time Clock
+ *       chips support years from 2000 only as they store the year as years
+ *       from 2000. So do not attempt to set any years below 2000 as this could cause
+ *       the year to wrap around to an unreasonably high value. Definitely do not do:
+ * @code
+ * mmhal_set_time(0);
+ * @endcode
+ *
+ * @param epoch Time in Unix epoch time (seconds since 1 Jan 1970).
+ */
+void mmhal_set_time(time_t epoch);
+
+/**
+ * Function to prepare MCU to enter sleep.
+ * This will halt the timer that generates the RTOS tick.
+ *
+ * @param expected_idle_time_ms Expected time to sleep in milliseconds.
+ *
+ * @returns the type of sleep permitted by the current system state.
+ */
+enum mmhal_sleep_state mmhal_sleep_prepare(uint32_t expected_idle_time_ms);
+
+/**
+ * Function to enter MCU sleep.
+ *
+ * @param sleep_state             Sleep state to enter into.
+ * @param expected_idle_time_ms   Expected time to sleep in milliseconds.
+ *
+ * @returns Elapsed sleep time in milliseconds.
+ */
+uint32_t mmhal_sleep(enum mmhal_sleep_state sleep_state, uint32_t expected_idle_time_ms);
+
+/**
+ * Function to abort the MCU sleep state.
+ *
+ * @note This must only be invoked after @ref mmhal_sleep_prepare()
+ *       and before @ref mmhal_sleep().
+ *
+ * @param sleep_state         Sleep state to abort.
+ */
+void mmhal_sleep_abort(enum mmhal_sleep_state sleep_state);
+
+/**
+ * Function to cleanup on exit from the MCU sleep state.
+ */
+void mmhal_sleep_cleanup(void);
+
+/** Enumeration of veto_id ranges for use with @ref mmhal_set_deep_sleep_veto() and
+ *  @ref mmhal_clear_deep_sleep_veto(). */
+enum mmhal_veto_id {
+    /** Start of deep sleep veto ID range that is available for application use. */
+    MMHAL_VETO_ID_APP_MIN = 0,
+    /** End of deep sleep veto ID range that is available for application use. */
+    MMHAL_VETO_ID_APP_MAX = 7,
+    /** Start of deep sleep veto ID range that is available for HAL use. */
+    MMHAL_VETO_ID_HAL_MIN = 8,
+    /** End of deep sleep veto ID range that is available for HAL use. */
+    MMHAL_VETO_ID_HAL_MAX = 15,
+    /** Start of deep sleep veto ID range that is allocated for morselib use. Note that this
+     *  must not be changed as it is built into morselib. */
+    MMHAL_VETO_ID_MORSELIB_MIN = 16,
+    /** End of deep sleep veto ID range that is allocated for morselib use. Note that this must not
+     *  be changed as it is built into morselib. */
+    MMHAL_VETO_ID_MORSELIB_MAX = 19,
+    /** Deep sleep veto ID for data-link subsystem. */
+    MMHAL_VETO_ID_DATALINK = 20,
+    /** Deep sleep veto ID allocated to @ref MMCONFIG. */
+    MMHAL_VETO_ID_MMCONFIG = 21,
+    /** Start of deep sleep veto ID range reserved for future use. */
+    MMHAL_VETO_ID_RESERVED_MIN = 22,
+    /** End of deep sleep veto ID range reserved for future use. */
+    MMHAL_VETO_ID_RESERVED_MAX = 31,
+};
+
+/**
+ * Sets a deep sleep veto that will prevent the device from entering deep sleep. The device
+ * will not enter deep sleep until there are no vetoes remaining. This veto can be cleared
+ * by a call to @ref mmhal_clear_deep_sleep_veto() with the same veto_id.
+ *
+ * Up to 32 vetoes are supported (ID numbers 0-31). Each veto should be used exclusively by
+ * a given aspect of the system (e.g., to prevent deep sleep when a DMA transfer is in progress,
+ * or to prevent deep sleep when there is log data buffered for transmit, etc.).
+ *
+ * @param veto_id   The veto identifier. Valid values are 0-31, and these are split up into ranges
+ *                  for use by different subsystems -- see @ref mmhal_veto_id.
+ */
+void mmhal_set_deep_sleep_veto(uint8_t veto_id);
+
+/**
+ * Clears a deep sleep veto that was preventing the device from entering deep sleep (see
+ * @ref mmhal_set_deep_sleep_veto()). If the given veto was not already set then this has
+ * no effect.
+ *
+ * @param veto_id   The veto identifier. Valid values are 0-31, and these are split up into ranges
+ *                  for use by different subsystems -- see @ref mmhal_veto_id.
+ */
+void mmhal_clear_deep_sleep_veto(uint8_t veto_id);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,145 @@
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @ingroup MMHAL Morse Micro Flash Hardware Abstraction Layer (mmhal_flash) API
+ *
+ * This API provides abstraction from the underlying flash hardware/.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * This is the value erased flash bytes are set to. This shall be @c 0xFF as this is the
+ * value that hardware flash erases to.
+ */
+#define MMHAL_FLASH_ERASE_VALUE 0xFF
+
+/** LittleFS configuration structure. Include @c lfs.h for definition. */
+struct lfs_config;
+
+/**
+ * Flash partition configuration structure
+ *
+ * This should be initialized using @c MMHAL_FLASH_PARTITION_CONFIG_DEFAULT.
+ * For example:
+ *
+ * @code{.c}
+ * struct mmhal_flash_partition_config partition = MMHAL_FLASH_PARTITION_CONFIG_DEFAULT;
+ * @endcode
+ */
+struct mmhal_flash_partition_config {
+    /** The start address of the partition, this may be a physical address
+     *  or a relative address depending on implementation
+     */
+    uint32_t partition_start;
+
+    /** The size of the partition */
+    uint32_t partition_size;
+
+    /**
+     * If true, then the partition is not memory mapped and cannot be directly accessed
+     * at the physical @c partition_start address
+     */
+    bool not_memory_mapped;
+};
+
+/** Initial values for @ref mmhal_flash_partition_config. */
+#define MMHAL_FLASH_PARTITION_CONFIG_DEFAULT                                                                                     \
+    {                                                                                                                            \
+        0, 0, false                                                                                                              \
+    }
+
+/**
+ * Get MMCONFIG flash partition configuration.
+ *
+ * MMCONFIG initialization is done by @c mmconfig_init() in @c mmconfig.c.
+ * which in turn calls this function to fetch the partition configuration for config store
+ * from the HAL layer. If config store is not supported by the platform then we just
+ * return NULL. This function returns a static pointer to
+ * @c struct @c mmhal_flash_partition_config.
+ *
+ * @return A static pointer to the partition config for MMCONFIG, or NULL if not supported.
+ */
+const struct mmhal_flash_partition_config *mmhal_get_mmconfig_partition(void);
+
+/**
+ * Erases a block of Flash pointed to by the block_address.
+ *
+ * The block address may be anywhere within the block to erase. The entire block gets erased.
+ * Once erased all bytes in the block shall be @c MMHAL_FLASH_ERASE_VALUE (@c 0xFF).
+ *
+ * @param block_address The address of the block of Flash to erase.
+ * @return              0 on success, negative number on failure
+ */
+int mmhal_flash_erase(uint32_t block_address);
+
+/**
+ * Returns the size of the Flash block at the specified address.
+ *
+ * @param block_address The address of the Flash block.
+ * @return              The size of the Flash block in bytes.
+ *                      Returns 0 if an invalid address is specified.
+ */
+uint32_t mmhal_flash_getblocksize(uint32_t block_address);
+
+/**
+ * Read a block of data from the specified Flash address into the buffer.
+ *
+ * @param read_address  The address in Flash to read from.
+ * @param buf           The buffer to read into.
+ * @param size          The number of bytes to read.
+ * @return              0 on success, or a negative number on failure.
+ */
+int mmhal_flash_read(uint32_t read_address, uint8_t *buf, size_t size);
+
+/**
+ * Write a block of data to the specified Flash address.
+ *
+ * There is no alignment or minimum size requirement.  This function will
+ * take care of aligning the data and merging with existing Flash contents.
+ * The Flash block is not erased, it is up to the application to determine
+ * if the block needs to be erased before programming.
+ *
+ * @param write_address The address in Flash to write to.
+ * @param data          A pointer to the block of data to write.
+ * @param size          The number of bytes to write.
+ * @return              0 on success, or a negative number on failure.
+ */
+int mmhal_flash_write(uint32_t write_address, const uint8_t *data, size_t size);
+
+/**
+ * Get LittleFS configuration.
+ *
+ * LittleFS initialization is done by @c littlefs_init() in @c mmosal_shim_fileio.c.
+ * which in turn calls this function to fetch the hardware configuration for LittleFS
+ * from the HAL layer. The LittleFS configuration will vary from platform to platform.
+ * If LittleFS is not supported by the platform then we just return NULL. This function
+ * returns a static pointer to @c struct @c lfs_config which is defined in @c lfs.h.
+ *
+ * See @c mmhal_littlefs.c for the full HAL layer implementation for your platform.
+ * See @c mmosal_shim_fileio.c for the @c libc shims for LittleFS.
+ * See @c README.md in the @c src/littlefs folder for detailed information on LittleFS.
+ *
+ * @return A static pointer to the LittleFS config structure, or NULL if not supported.
+ */
+const struct lfs_config *mmhal_get_littlefs_config(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @ingroup MMHAL
+ * @defgroup MMHAL_UART Morse Micro Abstraction Layer API for UART
+ *
+ * This provides an abstraction layer for a UART. This is used by MM-IoT-SDK example
+ * applications.
+ *
+ * This is a very simple API and leaves UART configuration to the HAL.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include "mmhal.h"
+#include "mmosal.h"
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Function type for UART RX callback.
+ *
+ * @note The UART HAL must not invoke this function from interrupt context. However, the
+ *       implementation should not block for long periods of time or received data may be lost.
+ *
+ * @param data      The received data.
+ * @param length    Length of the received data.
+ * @param arg       Opaque argument (as passed in to @ref mmhal_uart_init()).
+ */
+typedef void (*mmhal_uart_rx_cb_t)(const uint8_t *data, size_t length, void *arg);
+
+/**
+ * Initialize the UART HAL and perform any setup necessary.
+ *
+ * @param rx_cb     Optional callback to be invoked on receive (may be NULL).
+ *                  This callback may be invoked from interrupt context so should return
+ *                  quickly.
+ * @param rx_cb_arg Optional opaque argument to be passed to the RX callback. May be NULL.
+ */
+void mmhal_uart_init(mmhal_uart_rx_cb_t rx_cb, void *rx_cb_arg);
+
+/**
+ * Deinitialize the UART HAL, and disable the UART.
+ */
+void mmhal_uart_deinit(void);
+
+/**
+ * Transmit data on the UART. This will block until all data is buffered for transmit (but may
+ * return before transmission has completed).
+ *
+ * @param data      Data to transmit.
+ * @param length    Length of @p data.
+ */
+void mmhal_uart_tx(const uint8_t *data, size_t length);
+
+/** Enumeration of deep sleep modes for the UART HAL. */
+enum mmhal_uart_deep_sleep_mode {
+    /** Deep sleep mode is disabled. */
+    MMHAL_UART_DEEP_SLEEP_DISABLED,
+    /** Enable deep sleep until activity occurs on data-link transport. */
+    MMHAL_UART_DEEP_SLEEP_ONE_SHOT,
+};
+
+/**
+ * Set the deep sleep mode for the UART. See @ref mmhal_uart_deep_sleep_mode for possible deep
+ * sleep modes. Note that a given platform may not support all modes.
+ *
+ * @param mode      The deep sleep mode to set.
+ *
+ * @returns true if the mode was set successfully; false on failure (e.g., unsupported mode).
+ */
+bool mmhal_uart_set_deep_sleep_mode(enum mmhal_uart_deep_sleep_mode mode);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,640 @@
+/*
+ * Copyright 2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @ingroup MMHAL
+ * @defgroup MMHAL_WLAN WLAN HAL
+ *
+ * API for communicating with the WLAN transceiver.
+ *
+ * There are different interfaces supported for communicating with the transceiver:
+ *
+ * * @ref MMHAL_WLAN_SDIO
+ * * @ref MMHAL_WLAN_SPI
+ *
+ * @warning These functions shall not be called directly by the end application they are for use
+ *          by Morselib.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include "mmpkt.h"
+#include "mmwlan.h"
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <time.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Function prototype for interrupt handler callbacks.
+ */
+typedef void (*mmhal_irq_handler_t)(void);
+
+/**
+ * Initialize the WLAN HAL.
+ *
+ * Things to do here may include:
+ * * Enable SPI peripheral
+ * * Configure GPIOs
+ * * Enable power to the Morse Micro transceiver
+ *
+ * @note If enabling power for the Morse Micro transceiver in this function you may need to add a
+ *       blocking delay to allow the power rail to stabilize. This is hardware specific so is not
+ *       accounted for in the calling function.
+ */
+void mmhal_wlan_init(void);
+
+/**
+ * Deinitialize the WLAN HAL.
+ *
+ * Things to do here may include:
+ * * Disable SPI peripheral
+ * * Disable GPIOs
+ * * Disable power to the Morse Micro transceiver
+ */
+void mmhal_wlan_deinit(void);
+
+/**
+ * Get MAC address override.
+ *
+ * This function allows the HAL to override the MAC address to be used by the device. The
+ * MAC address override should be written to @p mac_addr. If no override is required then
+ * @p mac_addr should be left untouched.
+ *
+ * @param[out] mac_addr Location where the MAC address will be stored. This will be initialized
+ *                      to zero the first time this function is invoked, and to the previously
+ *                      configured MAC address on subsequent invocations.
+ */
+void mmhal_read_mac_addr(uint8_t *mac_addr);
+
+/**
+ * Assert the WLAN wake pin.
+ */
+void mmhal_wlan_wake_assert(void);
+
+/**
+ * Deassert the WLAN wake pin.
+ */
+void mmhal_wlan_wake_deassert(void);
+
+/**
+ * Tests whether the busy pin is currently asserted.
+ *
+ * @note This is whether it is logically asserted and does not necessarily
+ *       represent the level of the GPIO pin.
+ *
+ * @returns @c true if asserted, else @c false.
+ */
+bool mmhal_wlan_busy_is_asserted(void);
+
+/**
+ * Register a handler for busy interrupts.
+ *
+ * @param handler   The handler to register.
+ */
+void mmhal_wlan_register_busy_irq_handler(mmhal_irq_handler_t handler);
+
+/**
+ * Sets whether the busy interrupt is enabled.
+ *
+ * @warning The interrupt handler function must be configured using
+ *          mmhal_wlan_register_busy_irq_handler() before enabling the interrupt.
+ *
+ * @param enabled   @c true to enable or @c false to disable.
+ */
+void mmhal_wlan_set_busy_irq_enabled(bool enabled);
+
+/**
+ * Read-only buffer data structure.
+ *
+ * The design of this data structure allows the buffer to exist either in statically or
+ * dynamically allocated memory.
+ *
+ * For statically allocated memory, the field @c free_cb may be set to @c NULL and @c free_arg
+ * ignored. For example:
+ *
+ * @code{.c}
+ * const uint8_t some_data[] = { 0x00, 0x01, 0x02 };
+ *
+ * void put_some_data_into_buf(struct mmhal_robuf *robuf)
+ * {
+ *     robuf->buf = some_data;
+ *     robuf->len = sizeof(some_data);
+ *     robuf->free_cb = NULL;
+ * }
+ * @endcode
+ *
+ * For dynamically allocated memory, the field @c free_cb is set to the appropriate function to
+ * free the buffer and @c free_arg is an opaque argument to the free function. This approach might
+ * be used, for example, when reading into a temporary buffer from storage that is not memory
+ * mapped. For example:
+ *
+ * @code{.c}
+ * #define SOME_DATA_MAXLEN (64)
+ *
+ * void put_some_data_into_buf(struct mmhal_robuf *robuf)
+ * {
+ *     uint8_t *buf = malloc(SOME_DATA_MAXLEN);
+ *     robuf->buf = buf;
+ *     if (robuf->buf == NULL)
+ *         return;
+ *
+ *     // HERE: copy data into buf and set robuf->len as appropriate
+ *
+ *     robuf->free_cb = free;
+ *     robuf->free_arg = buf;
+ * }
+ * @endcode
+ *
+ */
+struct mmhal_robuf {
+    /** Pointer to the start of the read-only buffer. May be NULL only if @c len is zero. */
+    const uint8_t *buf;
+    /** Length of the buffer contents. */
+    uint32_t len;
+    /**
+     * Optional callback to be invoked by the consumer to release the buffer when it is
+     * no longer required. If not required, set to @c NULL.
+     *
+     * @note The values of @c buf and @c len in this structure may be modified before
+     *       @c free_cb() is invoked. However, the value of @c free_arg will be passed
+     *       to @c free_cb().
+     */
+    void (*free_cb)(void *arg);
+    /** Optional argument to @c free_cb. Ignored if @c free_cb is @c NULL. */
+    void *free_arg;
+};
+
+/** Minimum length of data to be returned by @ref mmhal_wlan_read_bcf_file() and
+ *  @ref mmhal_wlan_read_fw_file(). */
+#define MMHAL_WLAN_FW_BCF_MIN_READ_LENGTH (4)
+
+/**
+ * Retrieves the content of the Morse Micro Board Configuration File and places it into the given
+ * buffer.
+ *
+ * @param offset        Offset from which to start reading the bcf
+ * @param requested_len Length of data we would like to read. The length of the data returned
+ *                      by this function may be less than @p requested_len, but must be at
+ *                      least @ref MMHAL_WLAN_FW_BCF_MIN_READ_LENGTH.
+ * @param robuf         Read-only buffer data structure to be filled out by this function.
+ *
+ * @note On error, this function should set @c robuf->buf to @c NULL.
+ * @note The caller must zero @p robuf before invoking the function.
+ * @note The BCF must be in mbin format.
+ *
+ * @warning The caller is responsible for checking @c robuf->free_cb and calling when the buffer is
+ * no longer required. Ignored if @c robuf->free_cb is @c NULL.
+ */
+void mmhal_wlan_read_bcf_file(uint32_t offset, uint32_t requested_len, struct mmhal_robuf *robuf);
+
+/**
+ * Retrieves the content of the Morse Micro Chip Firmware and places it into the given buffer.
+ *
+ * @param offset        Offset from which to start reading the bcf
+ * @param requested_len Length of data we would like to read. The length of the data returned
+ *                      by this function may be less than @p requested_len, but must be at
+ *                      least @ref MMHAL_WLAN_FW_BCF_MIN_READ_LENGTH.
+ * @param robuf         Read-only buffer data structure to be filled out by this function.
+ *
+ * @note On error, this function should set @c robuf->buf to @c NULL.
+ * @note The caller must zero @p robuf before invoking the function.
+ * @note The firmware must be in mbin format.
+ *
+ * @warning The caller is responsible for checking @c robuf->free_cb and calling when the buffer
+ * is no longer required. Ignored if @c robuf->free_cb is @c NULL.
+ */
+void mmhal_wlan_read_fw_file(uint32_t offset, uint32_t requested_len, struct mmhal_robuf *robuf);
+
+/**
+ * @defgroup MMHAL_WLAN_SPI WLAN HAL API for SPI interface
+ *
+ * API for communicating with the WLAN transceiver over an SPI interface.
+ *
+ * @note These functions should only be implemented if using a SPI interface. They are not
+ *       required when using the @ref MMHAL_WLAN_SDIO.
+ *
+ * @warning These functions shall not be called directly by the end application they are for use
+ *          by Morselib.
+ *
+ * @{
+ */
+
+/**
+ * Assert the WLAN SPI chip select pin.
+ */
+void mmhal_wlan_spi_cs_assert(void);
+
+/**
+ * Deassert the WLAN SPI chip select pin.
+ */
+void mmhal_wlan_spi_cs_deassert(void);
+
+/**
+ * Simultaneously read and write on the SPI bus.
+ *
+ * @param data   Data to be written.
+ *
+ * @return the value that was read.
+ */
+uint8_t mmhal_wlan_spi_rw(uint8_t data);
+
+/**
+ * Receive multiple octets of data from SPI bus.
+ *
+ * @param buf       The buffer to receive into.
+ * @param len       The number of octets to receive.
+ */
+void mmhal_wlan_spi_read_buf(uint8_t *buf, unsigned len);
+
+/**
+ * Transmit multiple octets of data to SPI bus.
+ *
+ * @param buf       The buffer to transmit from.
+ * @param len       The number of octets to transmit.
+ *
+ * @note Blocks until transfer complete.
+ */
+void mmhal_wlan_spi_write_buf(const uint8_t *buf, unsigned len);
+
+/**
+ * Hard reset the chip by asserting and then releasing the reset pin.
+ *
+ * @warning This function must return with the chip in a fully booted state. i.e only return once
+ *          the reset_n line has been high for at least the boot time specified in the data sheet.
+ *          Failure to do so may lead to undefined behavior.
+ */
+void mmhal_wlan_hard_reset(void);
+
+/**
+ * Invoked by the driver to check whether the external crystal initialization sequence is required.
+ *
+ * Implementation of this function is optional if the external crystal initialization sequence
+ * is not required. If this function is not implemented then the external crystal initialization
+ * sequence will be disabled. Refer to the data sheet for your module to check if this initialization
+ * is required.
+ *
+ * @returns true if the external crystal initialization sequence is required else false.
+ */
+bool mmhal_wlan_ext_xtal_init_is_required(void);
+
+/**
+ * Issue the training sequence required to put the transceiver into SPI mode.
+ */
+void mmhal_wlan_send_training_seq(void);
+
+/**
+ * Register a handler for SPI interrupts.
+ *
+ * @param handler   The handler to register.
+ */
+void mmhal_wlan_register_spi_irq_handler(mmhal_irq_handler_t handler);
+
+/**
+ * Sets whether the SPI interrupt is enabled.
+ *
+ * @warning The interrupt handler function must be configured using
+ *          @ref mmhal_wlan_register_spi_irq_handler() before enabling the interrupt.
+ *
+ * @param enabled   @c true to enable or @c false to disable.
+ */
+void mmhal_wlan_set_spi_irq_enabled(bool enabled);
+
+/**
+ * Tests whether the SPI interrupt pin is currently asserted.
+ *
+ * @note This is whether it is logically asserted and does not necessarily
+ *       represent the level of the GPIO pin.
+ *
+ * @returns @c true if asserted, else @c false.
+ */
+bool mmhal_wlan_spi_irq_is_asserted(void);
+
+/**
+ * Clear the SPI IRQ.
+ *
+ * @deprecated Do not invoke this function because it is deprecated and will be removed from the
+ *             mmhal API in a future release. This function need not be implemented as a weak
+ *             stub is used in morselib.
+ */
+void mmhal_wlan_clear_spi_irq(void);
+
+/** @} */
+
+/**
+ * @defgroup MMHAL_WLAN_PKT WLAN HAL API for packet memory allocation
+ *
+ * API for allocating and freeing packet memory.
+ *
+ * @warning These functions shall not be called directly by the end application they are for use
+ *          by Morselib.
+ *
+ * @{
+ */
+
+/**
+ * Flow control callback that can be invoked by the transmit packet memory manager to pause
+ * and resume the data path in response to resource availability.
+ *
+ * @param state Current flow control state.
+ */
+typedef void (*mmhal_wlan_pktmem_tx_flow_control_cb_t)(enum mmwlan_tx_flow_control_state state);
+
+/** Initialization arguments passed to @ref mmhal_wlan_pktmem_init().  */
+struct mmhal_wlan_pktmem_init_args {
+    /** Flow control callback that can be used by the transmit packet memory manager. */
+    mmhal_wlan_pktmem_tx_flow_control_cb_t tx_flow_control_cb;
+};
+
+/**
+ * Invoked by the driver to initialize the packet memory in the HAL.
+ *
+ * @param args  Initialization arguments.
+ */
+void mmhal_wlan_pktmem_init(struct mmhal_wlan_pktmem_init_args *args);
+
+/**
+ * Invoked by the driver to deinitialize the packet memory in the HAL.
+ *
+ * This can free reserved memory and check for memory leaks.
+ */
+void mmhal_wlan_pktmem_deinit(void);
+
+/**
+ * Enumeration of packet classes used by @ref mmhal_wlan_alloc_mmpkt_for_tx().
+ * These definitions must match the corresponding values in @c mmdrv_pkt_class.
+ */
+enum mmhal_wlan_pkt_class {
+    MMHAL_WLAN_PKT_DATA_TID0,  /**< Data TID0 */
+    MMHAL_WLAN_PKT_DATA_TID1,  /**< Data TID1 */
+    MMHAL_WLAN_PKT_DATA_TID2,  /**< Data TID2 */
+    MMHAL_WLAN_PKT_DATA_TID3,  /**< Data TID3 */
+    MMHAL_WLAN_PKT_DATA_TID4,  /**< Data TID4 */
+    MMHAL_WLAN_PKT_DATA_TID5,  /**< Data TID5 */
+    MMHAL_WLAN_PKT_DATA_TID6,  /**< Data TID6 */
+    MMHAL_WLAN_PKT_DATA_TID7,  /**< Data TID7 */
+    MMHAL_WLAN_PKT_MANAGEMENT, /**< 802.11 Management and other important frames */
+    MMHAL_WLAN_PKT_COMMAND,    /**< Commands from driver to chip */
+};
+
+/**
+ * Allocates an mmpkt for transmission.
+ *
+ * When the pool of mmpkt buffers available for TX is exhausted, the HAL should pause the TX
+ * path using the flow control callback that was registered when @ref mmhal_wlan_pktmem_init()
+ * was invoked. Similarly, when the buffers become available again (and assuming the TX path is
+ * not otherwise blocked) the driver should unpause the TX path.
+ *
+ * @param pkt_class         The class of packet (to allow for prioritization).
+ * @param space_at_start    Amount of space to allocate at start of mmpkt (for prepend).
+ * @param space_at_end      Amount of space to allocate at end of mmpkt (for append).
+ * @param metadata_length   Amount of space to allocate for metadata (used internally by the
+ *                          Morse driver).
+ *
+ * @returns a pointer to the allocated packet on success or @c NULL on allocation failure.
+ */
+struct mmpkt *mmhal_wlan_alloc_mmpkt_for_tx(uint8_t pkt_class, uint32_t space_at_start, uint32_t space_at_end,
+                                            uint32_t metadata_length);
+
+/**
+ * Allocates an mmpkt for reception.
+ *
+ * @param capacity          Amount of space to allocate for data.
+ * @param metadata_length   Amount of space to allocate for metadata (used internally by the
+ *                          Morse driver).
+ *
+ * @returns a pointer to the allocated packet on success or @c NULL on allocation failure.
+ */
+struct mmpkt *mmhal_wlan_alloc_mmpkt_for_rx(uint32_t capacity, uint32_t metadata_length);
+
+/** @} */
+
+/**
+ * @defgroup MMHAL_WLAN_SDIO WLAN HAL API for SDIO interface
+ *
+ * API for communicating with the WLAN transceiver over an SDIO interface
+ *
+ * @warning These functions shall not be called directly by the end application they are for use
+ *          by Morselib.
+ *
+ * @{
+ */
+
+/** Enumeration of error codes that may be returned from @c mmhal_wlan_sdio_XXX() functions. */
+enum mmhal_sdio_error_codes {
+    /** Invalid argument given (e.g., incorrect buffer alignment). */
+    MMHAL_SDIO_INVALID_ARGUMENT = -1,
+    /** Local hardware error (e.g., issue with SDIO controller). */
+    MMHAL_SDIO_HW_ERROR = -2,
+    /** Timeout executing SDIO command. */
+    MMHAL_SDIO_CMD_TIMEOUT = -3,
+    /** CRC error executing SDIO command. */
+    MMHAL_SDIO_CMD_CRC_ERROR = -4,
+    /** Timeout transferring data. */
+    MMHAL_SDIO_DATA_TIMEOUT = -5,
+    /** CRC error transferring data. */
+    MMHAL_SDIO_DATA_CRC_ERROR = -6,
+    /** Underflow filling SDIO controller FIFO. */
+    MMHAL_SDIO_DATA_UNDERFLOW = -7,
+    /** Overflow reading from SDIO controller FIFO. */
+    MMHAL_SDIO_DATA_OVERRUN = -8,
+    /** Another error not covered by the above error codes. */
+    MMHAL_SDIO_OTHER_ERROR = -9,
+};
+
+/**
+ * Perform transport specific startup.
+ *
+ * @returns 0 on success, an error code from @ref mmhal_sdio_error_codes on failure.
+ */
+int mmhal_wlan_sdio_startup(void);
+
+/**
+ * Execute an SDIO command without data.
+ *
+ * @param[in]  cmd_idx  The Command Index.
+ * @param[in]  arg      Command argument. This corresponds to the 32 bits of the command between
+ *                      the Command Index field and the CRC7 field.
+ * @param[out] rsp      The contents of the command response between the Command Index field
+ *                      and the CRC7 field. May be @c NULL if the response is not required.
+ *                      The returned value is undefined if the return code is not zero.
+ *
+ * @returns 0 on success, an error code from @ref mmhal_sdio_error_codes on failure.
+ */
+int mmhal_wlan_sdio_cmd(uint8_t cmd_idx, uint32_t arg, uint32_t *rsp);
+
+/**
+ * Arguments structure for @ref mmhal_wlan_sdio_cmd53_write().
+ */
+struct mmhal_wlan_sdio_cmd53_write_args {
+    /** The SDIO argument. This corresponds to the 32 bits of the command between
+     * the Command Index field and the CRC7 field. */
+    uint32_t sdio_arg;
+    /** Pointer to the data buffer. 32 bit word aligned. */
+    const uint8_t *data;
+    /** Transfer length measured in blocks if block_size is non-zero otherwise in bytes.
+     *  If transfer_length is measured in bytes, it will be a multiple of 4. */
+    uint16_t transfer_length;
+    /**
+     * If non-zero this indicates that the data should be transferred in block mode with
+     * the given block size. If zero then the data should be transferred in byte mode and
+     * @c transfer_length is guaranteed to not exceed the block size of the function.
+     */
+    uint16_t block_size;
+};
+
+/**
+ * Execute an SDIO CMD53 write.
+ *
+ * @param args  The write arguments.
+ *
+ * @returns 0 on success, an error code from @ref mmhal_sdio_error_codes on failure.
+ */
+int mmhal_wlan_sdio_cmd53_write(const struct mmhal_wlan_sdio_cmd53_write_args *args);
+
+/**
+ * Arguments structure for @ref mmhal_wlan_sdio_cmd53_read().
+ */
+struct mmhal_wlan_sdio_cmd53_read_args {
+    /** The SDIO argument. This corresponds to the 32 bits of the command between
+     * the Command Index field and the CRC7 field. */
+    uint32_t sdio_arg;
+    /** Pointer to the data buffer to receive the data. 32 bit word aligned. */
+    uint8_t *data;
+    /** Transfer length measured in blocks if block_size is non-zero otherwise in bytes.
+     *  If transfer_length is measured in bytes, it will be a multiple of 4. */
+    uint16_t transfer_length;
+    /**
+     * If non-zero this indicates that the data should be transferred in block mode with
+     * the given block size. If zero then the data should be transferred in byte mode and
+     * @c transfer_length is guaranteed to not exceed the block size of the function.
+     */
+    uint16_t block_size;
+};
+
+/**
+ * Execute an SDIO CMD53 read.
+ *
+ * @param args  The read arguments.
+ *
+ * @returns 0 on success, an error code from @ref mmhal_sdio_error_codes on failure.
+ */
+int mmhal_wlan_sdio_cmd53_read(const struct mmhal_wlan_sdio_cmd53_read_args *args);
+
+/**
+ * @defgroup MMHAL_WLAN_SDIO_UTILS SDIO Utilities
+ *
+ * Useful macros and inline utilities function for use by SDIO and SPI HALs.
+ *
+ * @{
+ */
+
+/*
+ * SDIO argument definition, per SDIO Specification Version 4.10, Part E1, Section 5.3.
+ */
+
+/** SDIO CMD52/CMD53 R/W flag. */
+enum mmhal_sdio_rw {
+    MMHAL_SDIO_READ = 0,            /**< Read operation */
+    MMHAL_SDIO_WRITE = (1ul << 31), /**< Write operation */
+};
+
+/** SDIO CMD52/CMD53 function number. */
+enum mmhal_sdio_function {
+    MMHAL_SDIO_FUNCTION_0 = 0,           /** Function 0 */
+    MMHAL_SDIO_FUNCTION_1 = (1ul << 28), /** Function 1 */
+    MMHAL_SDIO_FUNCTION_2 = (2ul << 28), /** Function 2 */
+};
+
+/** SDIO CMD53 block mode*/
+enum mmhal_sdio_mode {
+    MMHAL_SDIO_MODE_BYTE = 0,            /** Byte mode */
+    MMHAL_SDIO_MODE_BLOCK = (1ul << 27), /** Block mode */
+};
+
+/** SDIO CMD53 OP code */
+enum mmhal_sdio_opcode {
+    /** Operate on a single, fixed address. */
+    MMHAL_SDIO_OPCODE_FIXED_ADDR = 0,
+    /** Increment address by 1 after each byte. */
+    MMHAL_SDIO_OPCODE_INC_ADDR = (1ul << 26),
+};
+
+/** CMD52/53 Register Address (17 bit) offset. */
+#define MMHAL_SDIO_ADDRESS_OFFSET (9)
+/** CMD52/53 Register Address maximum value. */
+#define MMHAL_SDIO_ADDRESS_MAX ((1ul << 18) - 1)
+
+/** CMD53 Byte/block count offset (9 bit). */
+#define MMHAL_SDIO_COUNT_OFFSET (0)
+/**CMD53 Byte/block count maximum value. */
+#define MMHAL_SDIO_COUNT_MAX ((1ul << 10) - 1)
+
+/** CMD52 Data (8 bit) offset */
+#define MMHAL_SDIO_CMD52_DATA_OFFSET (0)
+
+/**
+ * Construct an SDIO CMD52 argument based on the given arguments.
+ *
+ * @param rw            Flag indication direction (read or write).
+ * @param fn            The applicable function.
+ * @param address       The address to read/write. Must be <= @c MMHAL_SDIO_ADDRESS_MAX.
+ * @param write_data    The data to write if this is a write operation. Should be set to zero
+ *                      for a read operation.
+ *
+ * @return the SDIO CMD52 argument generated based on the given arguments.
+ */
+static inline uint32_t mmhal_make_cmd52_arg(enum mmhal_sdio_rw rw, enum mmhal_sdio_function fn, uint32_t address,
+                                            uint8_t write_data)
+{
+    uint32_t arg;
+
+    arg = rw | fn;
+    arg |= (address << MMHAL_SDIO_ADDRESS_OFFSET);
+    arg |= (write_data << MMHAL_SDIO_CMD52_DATA_OFFSET);
+    return arg;
+}
+
+/**
+ * Construct an SDIO CMD53 argument based on the given arguments.
+ *
+ * @param rw            Flag indication direction (read or write).
+ * @param fn            The applicable function.
+ * @param mode          Selects between byte and block mode.
+ * @param address        The address to read/write. Must be <= @c MMHAL_SDIO_ADDRESS_MAX.
+ * @param count         The count of bytes/blocks (depending on @p mode) to transfer. Must
+ *                      be <= @c MMHAL_SDIO_COUNT_MAX.
+ *
+ * @note OP Code 1 (incrementing address) is assumed. See also @ref MMHAL_SDIO_OPCODE_INC_ADDR.
+ *
+ * @return the SDIO CMD53 argument generated based on the given arguments.
+ */
+static inline uint32_t mmhal_make_cmd53_arg(enum mmhal_sdio_rw rw, enum mmhal_sdio_function fn, enum mmhal_sdio_mode mode,
+                                            uint32_t address, uint16_t count)
+{
+    uint32_t arg;
+
+    arg = rw | fn | MMHAL_SDIO_OPCODE_INC_ADDR | mode;
+    arg |= (address << MMHAL_SDIO_ADDRESS_OFFSET);
+    arg |= (count << MMHAL_SDIO_COUNT_OFFSET);
+    return arg;
+}
+
+/** @} */
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,383 @@
+/*
+ * Copyright 2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @defgroup MMIPAL Morse Micro IP Stack Abstraction Layer (MMIPAL) API
+ *
+ * This API provides a layer of abstraction from the underlying IP stack for common operations
+ * such as configuring the link and getting link status.
+ *
+ * @{
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdbool.h>
+#include <stdint.h>
+
+/** Maximum length of an IP address string, including null-terminator. */
+#ifndef MMIPAL_IPADDR_STR_MAXLEN
+#define MMIPAL_IPADDR_STR_MAXLEN (48)
+#endif
+
+/** Maximum number of IPv6 addresses supported. */
+#ifndef MMIPAL_MAX_IPV6_ADDRESSES
+#define MMIPAL_MAX_IPV6_ADDRESSES (3)
+#endif
+
+/** Enumeration of status codes returned by MMIPAL functions. */
+enum mmipal_status {
+    /** Completed successfully. */
+    MMIPAL_SUCCESS,
+    /** One or more arguments were invalid. */
+    MMIPAL_INVALID_ARGUMENT,
+    /** The operation could not complete because the link is not up. */
+    MMIPAL_NO_LINK,
+    /** Failed due to memory allocation failure. */
+    MMIPAL_NO_MEM,
+    /** This functionality is not supported (e.g., due to build configuration). */
+    MMIPAL_NOT_SUPPORTED,
+};
+
+/** Enumeration of link states. */
+enum mmipal_link_state {
+    /** Link is down. */
+    MMIPAL_LINK_DOWN,
+    /** Link is up. */
+    MMIPAL_LINK_UP,
+};
+
+/** Enumeration of IP address allocation modes. */
+enum mmipal_addr_mode {
+    /** Disabled. */
+    MMIPAL_DISABLED,
+    /** Static IP address. */
+    MMIPAL_STATIC,
+    /** IP address allocated via DHCP. @c LWIP_DHCP must be set to 1 if using LWIP. */
+    MMIPAL_DHCP,
+    /** IP address allocated via AutoIP. @c LWIP_DHCP must be set to 1 if using LWIP. */
+    MMIPAL_AUTOIP,
+    /** DHCP offloaded to chip. */
+    MMIPAL_DHCP_OFFLOAD,
+};
+
+/** IP address string type. */
+typedef char mmipal_ip_addr_t[MMIPAL_IPADDR_STR_MAXLEN];
+
+/**
+ * IPv4 configuration structure.
+ *
+ * This should be initialized using @c MMIPAL_IP_CONFIG_DEFAULT.
+ * For example:
+ *
+ * @code{.c}
+ * struct mmipal_ip_config config = MMIPAL_IP_CONFIG_DEAFULT;
+ * @endcode
+ */
+struct mmipal_ip_config {
+    /** IP address allocation mode. */
+    enum mmipal_addr_mode mode;
+    /** local IP address */
+    mmipal_ip_addr_t ip_addr;
+    /** Netmask address */
+    mmipal_ip_addr_t netmask;
+    /** Gateway address */
+    mmipal_ip_addr_t gateway_addr;
+};
+
+/** Initializer for @ref mmipal_ip_config. */
+#define MMIPAL_IP_CONFIG_DEFAULT                                                                                                 \
+    {                                                                                                                            \
+        MMIPAL_DHCP, "", "", "",                                                                                                 \
+    }
+
+/** Enumeration of IPv6 address allocation modes. */
+enum mmipal_ip6_addr_mode {
+    /** Disabled. */
+    MMIPAL_IP6_DISABLED,
+    /** Static IPv6 addresses. */
+    MMIPAL_IP6_STATIC,
+    /** IPv6 address allocated via autoconfiguration.
+     *  @c LWIP_IPV6_AUTOCONFIG must be set to 1 if using LWIP. */
+    MMIPAL_IP6_AUTOCONFIG,
+    /** IPv6 address allocated via stateless DHCPv6.
+     * @c LWIP_IPV6_DHCP6_STATELESS must be set to 1 if using LWIP. */
+    MMIPAL_IP6_DHCP6_STATELESS,
+};
+
+/**
+ * IPv6 configuration structure.
+ *
+ * This should be initialized using @c MMIPAL_IP6_CONFIG_DEFAULT.
+ * For example:
+ *
+ * @code{.c}
+ * struct mmipal_ip6_config config = MMIPAL_IP6_CONFIG_DEFAULT;
+ * @endcode
+ */
+struct mmipal_ip6_config {
+    /** IPv6 addresses allocation mode. */
+    enum mmipal_ip6_addr_mode ip6_mode;
+    /** Array of IPv6 addresses. */
+    mmipal_ip_addr_t ip6_addr[MMIPAL_MAX_IPV6_ADDRESSES];
+};
+
+/** Initializer for @ref mmipal_ip6_config. */
+#define MMIPAL_IP6_CONFIG_DEFAULT                                                                                                \
+    {                                                                                                                            \
+        MMIPAL_IP6_AUTOCONFIG                                                                                                    \
+    }
+
+/**
+ * Initialize arguments structure.
+ *
+ * This should be initialized using @c MMIPAL_INIT_ARGS_DEFAULT.
+ * For example:
+ *
+ * @code{.c}
+ * struct mmipal_init_args args = MMIPAL_INIT_ARGS_DEFAULT;
+ * @endcode
+ */
+struct mmipal_init_args {
+    /** IP address allocation mode to use. */
+    enum mmipal_addr_mode mode;
+    /** IP address to use (if @c mode is @c MMIPAL_STATIC). */
+    mmipal_ip_addr_t ip_addr;
+    /** Netmask to use (if @c mode is @c MMIPAL_STATIC). */
+    mmipal_ip_addr_t netmask;
+    /** Gateway IP address to use (if @c mode is @c MMIPAL_STATIC). */
+    mmipal_ip_addr_t gateway_addr;
+
+    /** IPv6 address allocation mode to use. */
+    enum mmipal_ip6_addr_mode ip6_mode;
+    /** IPv6 address to use (if @c ip6_mode is @c MMIPAL_IP6_STATIC). */
+    mmipal_ip_addr_t ip6_addr;
+    /** Flag requesting ARP response offload feature */
+    bool offload_arp_response;
+    /** ARP refresh offload interval in seconds */
+    uint32_t offload_arp_refresh_s;
+};
+
+/**
+ * Default values for @ref mmipal_init_args. This should be used when initializing the
+ * @ref mmipal_init_args structure.
+ */
+#define MMIPAL_INIT_ARGS_DEFAULT                                                                                                 \
+    {                                                                                                                            \
+        MMIPAL_DHCP, {0}, {0}, {0}, MMIPAL_IP6_DISABLED, {0}, false, 0                                                           \
+    }
+
+/**
+ * Initialize the IP stack and enable the MMWLAN interface.
+ *
+ * This will implicitly initialize and boot MMWLAN, and will block until this has completed.
+ *
+ * @note This function will boot the Morse Micro transceiver using @ref mmwlan_boot() in order
+ *       to read the MAC address. It is the responsibility of the caller to shut down the
+ *       transceiver using @ref mmwlan_shutdown() as required.
+ *
+ * @warning @ref mmwlan_init() must be called before invoking this function.
+ *
+ * @param  args Initialization arguments.
+ *
+ * @return      @c MMIPAL_SUCCESS on success. otherwise a vendor specific error code.
+ */
+enum mmipal_status mmipal_init(const struct mmipal_init_args *args);
+
+/**
+ * Structure representing the current status of the link.
+ */
+struct mmipal_link_status {
+    /** State of the link (up/down). */
+    enum mmipal_link_state link_state;
+    /** Current IP address. */
+    mmipal_ip_addr_t ip_addr;
+    /** Current netmask. */
+    mmipal_ip_addr_t netmask;
+    /** Current gateway IP address. */
+    mmipal_ip_addr_t gateway;
+};
+
+/**
+ * Prototype for callback function invoked on link status changes.
+ *
+ * @param link_status The current link status.
+ */
+typedef void (*mmipal_link_status_cb_fn_t)(const struct mmipal_link_status *link_status);
+
+/**
+ * Sets the callback function to be invoked on link status changes.
+ *
+ * This will be used when DHCP is enabled.
+ *
+ * @note This is for IPv4 only. To get IPv6 status use @c mmipal_get_ip6_config.
+ * @note If an opaque argument is required then use @ref mmipal_set_ext_link_status_callback()
+ *       instead.
+ *
+ * @param fn Function pointer to the callback function.
+ */
+void mmipal_set_link_status_callback(mmipal_link_status_cb_fn_t fn);
+
+/**
+ * Prototype for callback function invoked on link status changes.
+ *
+ * This is similar to @ref mmipal_link_status_cb_fn_t but with the addition of the @p arg
+ * parameter.
+ *
+ * @param link_status The current link status.
+ * @param arg         Opaque argument that was provided when the callback was registered.
+ */
+typedef void (*mmipal_ext_link_status_cb_fn_t)(const struct mmipal_link_status *link_status, void *arg);
+
+/**
+ * Sets the extended link status callback function to be invoked on link status changes.
+ * This is similar to @ref mmipal_set_link_status_callback() with the exception that
+ * an opaque argument may also be specified.
+ *
+ * This will be used when DHCP is enabled.
+ *
+ * @note This is for IPv4 only. To get IPv6 status use @c mmipal_get_ip6_config.
+ *
+ * @param fn  Function pointer to the callback function.
+ * @param arg Opaque argument to be passed to the callback.
+ */
+void mmipal_set_ext_link_status_callback(mmipal_ext_link_status_cb_fn_t fn, void *arg);
+
+/**
+ * Get the total number of transmitted and received packets on the MMWLAN interface
+ *
+ * @note If using LWIP, this function requires LWIP_STATS to be defined in your application,
+ *       otherwise packet counters will always return as 0.
+ *
+ * @param tx_packets Pointer to location to store total tx packets
+ * @param rx_packets Pointer to location to store total rx packets
+ */
+void mmipal_get_link_packet_counts(uint32_t *tx_packets, uint32_t *rx_packets);
+
+/**
+ * Set the QoS Traffic ID to use when transmitting.
+ *
+ * @param tid The QoS TID to use (0 - @ref MMWLAN_MAX_QOS_TID).
+ */
+void mmipal_set_tx_qos_tid(uint8_t tid);
+
+/**
+ * Gets the local address for the MMWLAN interface that is appropriate for a given
+ * destination address.
+ *
+ * The following table shows how the returned @c local_addr is selected:
+ *
+ * | @p dest_addr | @c local_addr returned    |
+ * |--------------|---------------------------|
+ * | type is IPv4 | IPv4 address              |
+ * | type is IPv6 | An IPv6 source address selected from interface's IPv6 addresses or ERR_CONN |
+ *
+ * (X = don't care)
+ *
+ * If the given parameters would result in a @p local_addr type of IPv4 and IPv4 is not enabled,
+ * or IPv6 and IPv6 is not enabled, then @c MMIPAL_INVALID_ARGUMENT will be returned.
+ *
+ * @param[out] local_addr Output local address for the MMWLAN interface, as noted above.
+ * @param[in]  dest_addr  Destination address.
+ *
+ * @return                @c MMIPAL_SUCESS if @p local_addr successfully set. otherwise an
+ *                        appropriate error code.
+ */
+enum mmipal_status mmipal_get_local_addr(mmipal_ip_addr_t local_addr, const mmipal_ip_addr_t dest_addr);
+
+/**
+ * Get the IP configurations.
+ *
+ * This can be used to get the local IP configurations.
+ *
+ * @param config Pointer to the IP configurations.
+ *
+ * @returns @c MMIPAL_SUCCESS on success, @c MMIPAL_NOT_SUPPORTED if IPv4 is not supported.
+ */
+enum mmipal_status mmipal_get_ip_config(struct mmipal_ip_config *config);
+
+/**
+ * Set the IP configurations.
+ *
+ * This can be used to set the local IP configurations.
+ *
+ * @param config Pointer to the IP configurations.
+ *
+ * @returns @c MMIPAL_SUCCESS on success, @c MMIPAL_NOT_SUPPORTED if IPv4 is not supported.
+ */
+enum mmipal_status mmipal_set_ip_config(const struct mmipal_ip_config *config);
+
+/**
+ * Gets the current IPv4 broadcast address.
+ *
+ * @param[out] broadcast_addr Buffer to receive the broadcast address as a string.
+ *
+ * @returns @c MMIPAL_SUCCESS on success, @c MMIPAL_NOT_SUPPORTED if IPv4 is not supported.
+ */
+enum mmipal_status mmipal_get_ip_broadcast_addr(mmipal_ip_addr_t broadcast_addr);
+
+/**
+ * Get the IP configurations.
+ *
+ * This can be used to get the local IP configurations.
+ *
+ * @param config Pointer to the IP configurations.
+ *
+ * @returns @c MMIPAL_SUCCESS on success, @c MMIPAL_NOT_SUPPORTED if IPv6 is not supported..
+ */
+enum mmipal_status mmipal_get_ip6_config(struct mmipal_ip6_config *config);
+
+/**
+ * Set the IPv6 configurations.
+ *
+ * This can be used to set the local IPv6 configurations.
+ *
+ * @param config Pointer to the IPv6 configurations.
+ *
+ * @returns @c MMIPAL_SUCCESS on success, @c MMIPAL_NOT_SUPPORTED if IPv6 is not supported.
+ */
+enum mmipal_status mmipal_set_ip6_config(const struct mmipal_ip6_config *config);
+
+/**
+ * Get current IPv4 link state.
+ *
+ * @returns the current IPv4 link state (up or down).
+ */
+enum mmipal_link_state mmipal_get_link_state(void);
+
+/**
+ * Set the DNS server at the given index.
+ *
+ * @warning Depending on IP stack implementation, this setting may be overridden by DHCP.
+ *
+ * @param[in]  index Index of the DNS server to set.
+ * @param[out] addr  Address of the DNS server to set.
+ *
+ * @returns @c MMIPAL_SUCCESS on success, @c MMIPAL_INVALID_ARGUMENT if an invalid index or IP
+ *          address was given.
+ */
+enum mmipal_status mmipal_set_dns_server(uint8_t index, const mmipal_ip_addr_t addr);
+
+/**
+ * Get the DNS server at the given index.
+ *
+ * @param[in]  index Index of the DNS server to set.
+ * @param[out] addr  IP address buffer to receive the IP address of the DNS server at the given
+ *                   index. Will be set to empty string if no server at the given index.
+ *
+ * @returns @c MMIPAL_SUCCESS on success.
+ */
+enum mmipal_status mmipal_get_dns_server(uint8_t index, mmipal_ip_addr_t addr);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,64 @@
+/*
+ * Morse logging API
+ *
+ * Copyright 2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+
+/**
+ * Macro for printing a @c uint64_t as two separate @c uint32_t values. This is to allow printing of
+ * these values even when the @c printf implementation doesn't support it.
+ */
+#define MM_X64_VAL(value) ((uint32_t)(value >> 32)), ((uint32_t)value)
+
+/** Macro for format specifier to print @ref MM_X64_VAL */
+#define MM_X64_FMT "%08lx%08lx"
+
+/**
+ * Macro for printing a MAC address. This saves writing it out by hand.
+ *
+ * Must be used in conjunction with @ref MM_MAC_ADDR_FMT. For example:
+ *
+ * @code
+ * uint8_t mac_addr[] = { 0, 1, 2, 3, 4, 5 };
+ * printf("MAC address: " MM_MAC_ADDR_FMT "\n", MM_MAC_ADDR_VAL(mac_addr));
+ * @endcode
+ */
+#define MM_MAC_ADDR_VAL(value) ((value)[0]), ((value)[1]), ((value)[2]), ((value)[3]), ((value)[4]), ((value)[5])
+
+/** Macro for format specifier to print @ref MM_MAC_ADDR_VAL */
+#define MM_MAC_ADDR_FMT "%02x:%02x:%02x:%02x:%02x:%02x"
+
+/**
+ * Initialize Morse logging API.
+ *
+ * This should be invoked after OS initialization since it will create a mutex for
+ * logging.
+ */
+void mm_logging_init(void);
+
+/**
+ * Dumps a binary buffer in hex.
+ *
+ * @param level         A single character indicating log level.
+ * @param function      Name of function this was invoked from.
+ * @param line_number   Line number this was invoked from.
+ * @param title         Title of the buffer.
+ * @param buf           The buffer to dump.
+ * @param len           Length of the buffer.
+ */
+void mm_hexdump(char level, const char *function, unsigned line_number, const char *title, const uint8_t *buf, size_t len);
+
+#ifdef __cplusplus
+}
+#endif
@@ -0,0 +1,515 @@
+/*
+ * Copyright 2022-2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @defgroup MMPKT Morse Micro Packet Buffer (mmpkt) API
+ *
+ * This API provides support for buffers tailored towards packets.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "mmosal.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Round @p x up to the next multiple of @p m (where @p m is a power of 2).
+ *
+ * @warning @p m must be a power of 2.
+ */
+#ifndef MM_FAST_ROUND_UP
+#define MM_FAST_ROUND_UP(x, m) ((((x)-1) | ((m)-1)) + 1)
+#endif
+
+struct mmdrv_cmd_metadata;
+struct mmdrv_tx_metadata;
+struct mmdrv_rx_metadata;
+struct mmpkt_ops;
+
+/**
+ * Union of pointer types for mmpkt metadata.
+ *
+ * The metadata is accessed through one of these pointers, depending on which context the packet
+ * is being used in.
+ */
+union mmpkt_metadata_ptr {
+    /** Opaque pointer for contexts which are unaware of the specific metadata structure. */
+    void *opaque;
+    /** Metadata for a packet which is being transmitted. */
+    struct mmdrv_tx_metadata *tx;
+    /** Metadata for a packet which is being received. */
+    struct mmdrv_rx_metadata *rx;
+    /** Control block for a command response sent to the host. */
+    struct mmdrv_cmd_metadata *cmd;
+};
+
+/**
+ * Core mmpkt data structure.
+ *
+ * @note The contents of this data structure should never need to be accessed directly. Rather
+ *       the various functions provided as part of this API should be used.
+ *
+ * @code
+ *      +----------------------------------------------------------+--------------+
+ *      | RESERVED |              Data            |    RESERVED    |   METADATA   |
+ *      +----------------------------------------------------------+--------------+
+ *      ^          ^                              ^                ^
+ *      |          |                              |                |
+ *      |          |<-----------data_len--------->|                |
+ *      |     start_offset                                         |
+ *      |                                                          |
+ *      |<-----------------------buf_len-------------------------->|
+ *     buf
+ * @endcode
+ */
+struct mmpkt {
+    /** The buffer where data is stored. */
+    uint8_t *buf;
+    /** Length of the buffer. */
+    uint32_t buf_len;
+    /** Offset where actual data starts in the buffer. */
+    uint32_t start_offset;
+    /** Length of actual data in the buffer. */
+    uint32_t data_len;
+    /** Packet metadata used by driver (context dependent). */
+    union mmpkt_metadata_ptr metadata;
+    /** Reference to operations data structure for this mmpkt. */
+    const struct mmpkt_ops *ops;
+    /** Pointer that can be used to construct linked lists. */
+    struct mmpkt *volatile next;
+};
+
+/** Operations data structure for mmpkt. */
+struct mmpkt_ops {
+    /** Free the given mmpkt. */
+    void (*free_mmpkt)(void *mmpkt);
+};
+
+/**
+ * Opened view of an mmpkt.
+ *
+ * In this implementation, this structure does not actually exist. We only use it as a pointer type
+ * which is incompatible with @ref mmpkt, to distinguish between functions which operate on opened
+ * packet views versus functions which can operate on unopened packets.
+ *
+ * In other implementations of this API, packets must be "opened" (mapped into memory) before their
+ * contents can be accessed. Thus the distinction between opened and unopened packets is important
+ * for those implementations.
+ */
+struct mmpktview;
+
+/**
+ * Initialize an mmpkt header with the given values.
+ *
+ * @param mmpkt                 mmpkt to initialize.
+ * @param buf                   Pointer to buffer.
+ * @param buf_len               Length of @p buf.
+ * @param data_start_offset     Initial value for @c start_offset.
+ * @param ops                   Operations data structure.
+ */
+static inline void mmpkt_init(struct mmpkt *mmpkt, uint8_t *buf, uint32_t buf_len, uint32_t data_start_offset,
+                              const struct mmpkt_ops *ops)
+{
+    memset(mmpkt, 0, sizeof(*mmpkt));
+    mmpkt->buf = buf;
+    mmpkt->buf_len = buf_len;
+    mmpkt->start_offset = data_start_offset;
+    mmpkt->ops = ops;
+}
+
+/**
+ * Initialize an mmpkt in a single buffer using the given values.
+ *
+ * @param buf                   Pointer to buffer.
+ * @param buf_len               Length of @p buf.
+ * @param space_at_start        Amount of space to reserve at start of buffer.
+ * @param space_at_end          Amount of space to reserve at end of buffer.
+ * @param metadata_size         Size of metadata (0 for no metadata).
+ *
+ * @param ops                   Operations data structure.
+ *
+ * @note @p buf_len must be large enough to contain the @c mmkpt header, the data buffer
+ *          (rounded up to the nearest 4 bytes) and metadata (rounded up to the nearest 4 bytes).
+ *
+ * @returns a pointer to the initialized @c mmpkt (will be the same address as @p buf) or @c NULL
+ *          on error (@p buf length too short).
+ */
+static inline struct mmpkt *mmpkt_init_buf(uint8_t *buf, uint32_t buf_len, uint32_t space_at_start, uint32_t space_at_end,
+                                           uint32_t metadata_size, const struct mmpkt_ops *ops)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)buf;
+
+    uint8_t *data_start;
+    uint32_t header_size = MM_FAST_ROUND_UP(sizeof(*mmpkt), 4);
+    uint32_t data_len = MM_FAST_ROUND_UP(space_at_start + space_at_end, 4);
+    metadata_size = MM_FAST_ROUND_UP(metadata_size, 4);
+
+    if (header_size + data_len + metadata_size > buf_len) {
+        return NULL;
+    }
+
+    data_start = ((uint8_t *)mmpkt) + header_size;
+
+    mmpkt_init(mmpkt, data_start, data_len, space_at_start, ops);
+
+    if (metadata_size != 0) {
+        mmpkt->metadata.opaque = data_start + data_len;
+        memset(mmpkt->metadata.opaque, 0, metadata_size);
+    }
+
+    return mmpkt;
+}
+
+/**
+ * Allocate a new mmpkt on the heap (using @ref mmosal_malloc()).
+ *
+ * @param space_at_start    Amount of space to reserve at start of buffer.
+ * @param space_at_end      Amount of space to reserve at end of buffer.
+ * @param metadata_size     Size of metadata (0 for no metadata).
+ *
+ * @note @c start_offset will be set to @p space_at_start, and @c buf_len will be the sum
+ *       of @p space_at_start and @p space_at_end (rounded up to a multiple of 4).
+ *
+ * @returns newly allocated mmpkt on success or @c NULL on failure.
+ */
+struct mmpkt *mmpkt_alloc_on_heap(uint32_t space_at_start, uint32_t space_at_end, uint32_t metadata_size);
+
+/**
+ * Release a reference to the given mmpkt. If this was the last reference (@c addition_ref_cnt
+ * was 0) then the mmpkt will be freed using the appropriate op callback.
+ *
+ * @param mmpkt     The mmpkt to release reference to. May be @c NULL.
+ */
+void mmpkt_release(struct mmpkt *mmpkt);
+
+/**
+ * Open a view of the given mmpkt.
+ *
+ * Packets must be opened before the contents of their buffer can be accessed. Most of the
+ * functions below expect to be passed an opened view of a packet to operate on.
+ *
+ * The view must be closed by calling @ref mmpkt_close() before the packet is released by
+ * @ref mmpkt_release().
+ *
+ * @param mmpkt  The mmpkt to be opened.
+ *
+ * @returns a pointer representing the opened view.
+ */
+static inline struct mmpktview *mmpkt_open(struct mmpkt *mmpkt)
+{
+    return (struct mmpktview *)mmpkt;
+}
+
+/**
+ * Close the given view.
+ *
+ * @param[in,out] view  Pointer to a variable holding the view to be closed.
+ *                      This will be modified to indicate it is no longer valid.
+ */
+static inline void mmpkt_close(struct mmpktview **view)
+{
+    (void)(view);
+}
+
+/**
+ * Get the underlying mmpkt from an opened view.
+ *
+ * @param view  View of an mmpkt.
+ *
+ * @returns the underlying mmpkt.
+ */
+static inline struct mmpkt *mmpkt_from_view(struct mmpktview *view)
+{
+    return (struct mmpkt *)view;
+}
+
+/**
+ * Gets a pointer to the start of the data in the mmpkt.
+ *
+ * @param view      The opened mmpkt to operate on.
+ *
+ * @returns a pointer to the start of the data in the mmpkt.
+ */
+static inline uint8_t *mmpkt_get_data_start(struct mmpktview *view)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    return mmpkt->buf + mmpkt->start_offset;
+}
+
+/**
+ * Gets a pointer to the end of the data in the mmpkt.
+ *
+ * @param view      The opened mmpkt to operate on.
+ *
+ * @returns a pointer to the end of the data in the mmpkt.
+ */
+static inline uint8_t *mmpkt_get_data_end(struct mmpktview *view)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    return mmpkt->buf + mmpkt->start_offset + mmpkt->data_len;
+}
+
+/**
+ * Peek the length of the data currently from an unopened mmpkt.
+ *
+ * @param mmpkt      The unopened mmpkt to operate on.
+ *
+ * @returns the length of the data currently in the mmpkt (note that this is different from the
+ *          length of the available buffer space).
+ */
+static inline uint32_t mmpkt_peek_data_length(struct mmpkt *mmpkt)
+{
+    return mmpkt->data_len;
+}
+
+/**
+ * Gets the length of the data currently in the mmpkt.
+ *
+ * @param view      The opened mmpkt to operate on.
+ *
+ * @returns the length of the data currently in the mmpkt (note that this is different from the
+ *          length of the available buffer space).
+ */
+static inline uint32_t mmpkt_get_data_length(struct mmpktview *view)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    return mmpkt->data_len;
+}
+
+/**
+ * Returns the amount of space available for prepending to the data in the buffer.
+ *
+ * @param view      The opened mmpkt to operate on.
+ *
+ * @returns the available space in bytes.
+ */
+static inline uint32_t mmpkt_available_space_at_start(struct mmpktview *view)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    return mmpkt->start_offset;
+}
+
+/**
+ * Returns the amount of space available for appending to the data in the buffer.
+ *
+ * @param view      The opened mmpkt to operate on.
+ *
+ * @returns the available space in bytes.
+ */
+static inline uint32_t mmpkt_available_space_at_end(struct mmpktview *view)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    return mmpkt->buf_len - (mmpkt->start_offset + mmpkt->data_len);
+}
+
+/**
+ * Reserves space immediately before the data currently in the given mmpkt and returns
+ * a pointer to this space.
+ *
+ * For a function that also copies data in, see @ref mmpkt_prepend_data().
+ *
+ * @warning @p len must be less than or equal to @ref mmpkt_available_space_at_start().
+ *
+ * @param view      The opened mmpkt to operate on.
+ * @param len       Length of data to be prepended.
+ *
+ * @returns a pointer to the place in the buffer where the data should be put.
+ */
+static inline uint8_t *mmpkt_prepend(struct mmpktview *view, uint32_t len)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    MMOSAL_ASSERT(len <= mmpkt_available_space_at_start(view));
+    mmpkt->start_offset -= len;
+    mmpkt->data_len += len;
+    return mmpkt->buf + mmpkt->start_offset;
+}
+
+/**
+ * Prepends the given data to the data already in the mmpkt.
+ *
+ * @warning @p len must be less than or equal to @ref mmpkt_available_space_at_start().
+ *
+ * @warning The memory area pointed to by data must not overlap with the mmpkt data.
+ *
+ * @param view      The opened mmpkt to operate on.
+ * @param data      The data to be prepended.
+ * @param len       Length of data to be prepended.
+ */
+static inline void mmpkt_prepend_data(struct mmpktview *view, const uint8_t *data, uint32_t len)
+{
+    uint8_t *dest = mmpkt_prepend(view, len);
+    memcpy(dest, data, len);
+}
+
+/**
+ * Reserves space immediately after the data currently in the given mmpkt and returns
+ * a pointer to this space.
+ *
+ * For a function that also copies data in, see @ref mmpkt_append_data().
+ *
+ * @warning @p len must be less than or equal to @ref mmpkt_available_space_at_end().
+ *
+ * @param view      The opened mmpkt to operate on.
+ * @param len       Length of data to be append.
+ *
+ * @returns a pointer to the place in the buffer where the data should be put.
+ */
+static inline uint8_t *mmpkt_append(struct mmpktview *view, uint32_t len)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    uint8_t *ret = mmpkt_get_data_end(view);
+    MMOSAL_ASSERT(len <= mmpkt_available_space_at_end(view));
+    mmpkt->data_len += len;
+    return ret;
+}
+
+/**
+ * Appends the given data to the data already in the mmpkt.
+ *
+ * @warning @p len must be less than or equal to @ref mmpkt_available_space_at_start().
+ *
+ * @param view      The opened mmpkt to operate on.
+ * @param data      The data to be prepended.
+ * @param len       Length of data to be prepended.
+ */
+static inline void mmpkt_append_data(struct mmpktview *view, const uint8_t *data, uint32_t len)
+{
+    uint8_t *dest = mmpkt_append(view, len);
+    memcpy(dest, data, len);
+}
+
+/**
+ * Retrieve a reference to the metadata associated with the given mmpkt.
+ *
+ * @param mmpkt     The mmpkt to operate on.
+ *
+ * @returns a reference to the mmpkt metadata.
+ */
+static inline union mmpkt_metadata_ptr mmpkt_get_metadata(struct mmpkt *mmpkt)
+{
+    return mmpkt->metadata;
+}
+
+/**
+ * Remove data from the start of the mmpkt.
+ *
+ * @param view      The opened mmpkt to operate on.
+ * @param len       Length of data to remove.
+ *
+ * @returns a pointer to the removed data or NULL if the mmpkt data length was less than @p len.
+ */
+static inline uint8_t *mmpkt_remove_from_start(struct mmpktview *view, uint32_t len)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    uint8_t *ret;
+
+    if (mmpkt_get_data_length(view) < len) {
+        return NULL;
+    }
+
+    ret = mmpkt_get_data_start(view);
+
+    mmpkt->start_offset += len;
+    mmpkt->data_len -= len;
+
+    return ret;
+}
+
+/**
+ * Remove data from the end of the mmpkt.
+ *
+ * @param view      The opened mmpkt to operate on.
+ * @param len       Length of data to remove.
+ *
+ * @returns a pointer to the removed data or NULL if the mmpkt data length was less than @p len.
+ */
+static inline uint8_t *mmpkt_remove_from_end(struct mmpktview *view, uint32_t len)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    uint8_t *ret;
+
+    if (mmpkt_get_data_length(view) < len) {
+        return NULL;
+    }
+
+    ret = mmpkt_get_data_end(view) - len;
+
+    mmpkt->data_len -= len;
+
+    return ret;
+}
+
+/**
+ * Truncate the mmpkt data to the given length.
+ *
+ * @param mmpkt     mmpkt to operate on.
+ * @param len       New data length. (Must be less than or equal to the data length
+ *                  of the mmpkt).
+ */
+static inline void mmpkt_truncate(struct mmpkt *mmpkt, uint32_t len)
+{
+    MMOSAL_ASSERT(len <= mmpkt->data_len);
+    mmpkt->data_len = len;
+}
+
+/**
+ * Get the `next` pointer embedded in the mmpkt.
+ *
+ * Used by the mmpkt_list structure for making linked lists of mmpkts.
+ *
+ * @param mmpkt     The mmpkt to operate on.
+ *
+ * @returns pointer to the next mmpkt in the chain (may be NULL).
+ */
+static inline struct mmpkt *mmpkt_get_next(struct mmpkt *mmpkt)
+{
+    return mmpkt->next;
+}
+
+/**
+ * Set the `next` pointer embedded in the mmpkt.
+ *
+ * Used by the mmpkt_list structure for making linked lists of mmpkts.
+ *
+ * @param mmpkt     The mmpkt to operate on.
+ * @param next      The next mmpkt in the chain.
+ */
+static inline void mmpkt_set_next(struct mmpkt *mmpkt, struct mmpkt *next)
+{
+    mmpkt->next = next;
+}
+
+/**
+ * Check whether the given pointer is pointing inside the mmpkt's buffer.
+ *
+ * @note This checks against the full buffer, which includes any unused regions at the beginning and
+ * end of the buffer which do not contain valid packet data.
+ *
+ * @param view      The opened mmpkt to operate on.
+ * @param ptr       The pointer to check.
+ *
+ * @returns true if the pointer points into the buffer.
+ */
+static inline bool mmpkt_contains_ptr(struct mmpktview *view, const void *ptr)
+{
+    struct mmpkt *mmpkt = (struct mmpkt *)view;
+    return ((const uint8_t *)ptr >= &mmpkt->buf[0] && (const uint8_t *)ptr < &mmpkt->buf[mmpkt->buf_len]);
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,172 @@
+/*
+ * Copyright 2022-2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @ingroup MMPKT
+ *
+ * @{
+ */
+
+#pragma once
+
+#include <stddef.h>
+
+#include "mmpkt.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Structure that can be used as the head of a linked list of mmpkts that counts its length. */
+struct mmpkt_list {
+    /** First mmpkt in the list. */
+    struct mmpkt *volatile head;
+    /** Last mmpkt in the list. */
+    struct mmpkt *volatile tail;
+    /** Length of the list. */
+    volatile uint32_t len;
+};
+
+/** Static initializer for @ref mmpkt_list. */
+#define MMPKT_LIST_INIT                                                                                                          \
+    {                                                                                                                            \
+        NULL, NULL, 0                                                                                                            \
+    }
+
+/**
+ * Initialization function for @ref mmpkt_list, for cases where @c MMPKT_LIST_INIT
+ * cannot be used.
+ *
+ * @param list The mmpkt_list to init.
+ */
+static inline void mmpkt_list_init(struct mmpkt_list *list)
+{
+    list->head = NULL;
+    list->tail = NULL;
+    list->len = 0;
+}
+
+/**
+ * Add an mmpkt to the start of an mmpkt list.
+ *
+ * @param list  The list to prepend to.
+ * @param mmpkt The mmpkt to prepend.
+ */
+void mmpkt_list_prepend(struct mmpkt_list *list, struct mmpkt *mmpkt);
+
+/**
+ * Add an mmpkt to the end of an mmpkt list.
+ *
+ * @param list  The list to append to.
+ * @param mmpkt The mmpkt to append.
+ */
+void mmpkt_list_append(struct mmpkt_list *list, struct mmpkt *mmpkt);
+
+/**
+ * Remove an mmpkt from an mmpkt list.
+ *
+ * @param list  The list to remove from.
+ * @param mmpkt The mmpkt to remove.
+ */
+void mmpkt_list_remove(struct mmpkt_list *list, struct mmpkt *mmpkt);
+
+/**
+ * Remove the mmpkt at the head of the list and return it.
+ *
+ * @param list The list to dequeue from.
+ *
+ * @returns the dequeued mmpkt, or @c NULL if the list is empty.
+ */
+struct mmpkt *mmpkt_list_dequeue(struct mmpkt_list *list);
+
+/**
+ * Remove the mmpkt at the tail of the list and return it.
+ *
+ * @param list The list to dequeue from.
+ *
+ * @returns the dequeued mmpkt, or @c NULL if the list is empty.
+ */
+struct mmpkt *mmpkt_list_dequeue_tail(struct mmpkt_list *list);
+
+/**
+ * Remove all mmpkts from the list and return as a linked list.
+ *
+ * @param list The list to dequeue from.
+ *
+ * @returns the dequeued mmpkts, or @c NULL if the list is empty.
+ */
+static inline struct mmpkt *mmpkt_list_dequeue_all(struct mmpkt_list *list)
+{
+    struct mmpkt *head = list->head;
+    list->head = NULL;
+    list->tail = NULL;
+    list->len = 0;
+    return head;
+}
+
+/**
+ * Checks whether the given mmpkt list is empty.
+ *
+ * @param list The list to check.
+ *
+ * @returns @c true if the list is empty, else @c false.
+ */
+static inline bool mmpkt_list_is_empty(struct mmpkt_list *list)
+{
+    return (list->head == NULL);
+}
+
+/**
+ * Returns the head of the mmpkt list.
+ *
+ * @param list The list to peek into.
+ *
+ * @returns the mmpkt at the head of the list.
+ */
+static inline struct mmpkt *mmpkt_list_peek(struct mmpkt_list *list)
+{
+    return list->head;
+}
+
+/**
+ * Returns the tail of the mmpkt list.
+ *
+ * @param list The list to peek into.
+ *
+ * @returns the mmpkt at the tail of the list.
+ */
+static inline struct mmpkt *mmpkt_list_peek_tail(struct mmpkt_list *list)
+{
+    return list->tail;
+}
+
+/**
+ * Free all the packets in the given list and reset the list to empty state.
+ *
+ * @param list The list to clear.
+ */
+void mmpkt_list_clear(struct mmpkt_list *list);
+
+/**
+ * Safely walk the mmpkt list.
+ *
+ * @warning This macro cannot be used following an if statement with no parentheses if there
+ *          is an else clause. For example, do not do:
+ *          `if (x) MMPKT_LIST_WALK(a,b,c) else foo();` -- instead:
+ *          `if (x) { MMPKT_LIST_WALK(a,b,c) } else foo();`
+ */
+#define MMPKT_LIST_WALK(_lst, _wlk, _nxt)                                                                                        \
+    if ((_lst)->head != NULL) /* NOLINT(readability/braces) */                                                                   \
+        for (_wlk = (_lst)->head, _nxt = mmpkt_get_next(_wlk); _wlk != NULL;                                                     \
+             _wlk = _nxt, _nxt = _wlk ? mmpkt_get_next(_wlk) : NULL)
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
@@ -0,0 +1,302 @@
+/*
+ *
+ * Copyright 2022-2023 Morse Micro
+ */
+/**
+ * @ingroup MMWLAN_REGDB
+ * @defgroup MMWLAN_REGDB_TEMPLATE Template S1G regulatory database
+ *
+ * \{
+ *
+ * @section MMWLAN_REGDB_TEMPLATE_DISCLAIMER Disclaimer
+ *
+ * While every effort has been made to maintain accuracy of this database, no guarantee is
+ * given as to the accuracy of the information contained herein.
+ *
+ * @section MMWLAN_REGDB_TEMPLATE_COUNTRIES Country code list
+ *
+ * | Country Code | Country |
+ * | ------------ | ------- |
+ * | AU | Australia |
+ * | EU | EU |
+ * | IN | India |
+ * | JP | Japan |
+ * | KR | South Korea |
+ * | NZ | New Zealand |
+ * | SG | Singapore |
+ * | US | USA |
+ */
+
+#include "mmwlan.h"
+
+/** List of valid S1G channels for Australia. */
+static const struct mmwlan_s1g_channel s1g_channels_AU[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  915500000, 10000, false, 68, 22, 27,  1,  30, 0, 0, 0 },
+    {  916500000, 10000, false, 68, 22, 29,  1,  30, 0, 0, 0 },
+    {  917500000, 10000, false, 68, 22, 31,  1,  30, 0, 0, 0 },
+    {  918500000, 10000, false, 68, 22, 33,  1,  30, 0, 0, 0 },
+    {  919500000, 10000, false, 68, 22, 35,  1,  30, 0, 0, 0 },
+    {  920500000, 10000, false, 68, 22, 37,  1,  30, 0, 0, 0 },
+    {  921500000, 10000, false, 68, 22, 39,  1,  30, 0, 0, 0 },
+    {  922500000, 10000, false, 68, 22, 41,  1,  30, 0, 0, 0 },
+    {  923500000, 10000, false, 68, 22, 43,  1,  30, 0, 0, 0 },
+    {  924500000, 10000, false, 68, 22, 45,  1,  30, 0, 0, 0 },
+    {  925500000, 10000, false, 68, 22, 47,  1,  30, 0, 0, 0 },
+    {  926500000, 10000, false, 68, 22, 49,  1,  30, 0, 0, 0 },
+    {  927500000, 10000, false, 68, 22, 51,  1,  30, 0, 0, 0 },
+    {  917000000, 10000, false, 69, 23, 30,  2,  30, 0, 0, 0 },
+    {  919000000, 10000, false, 69, 23, 34,  2,  30, 0, 0, 0 },
+    {  921000000, 10000, false, 69, 23, 38,  2,  30, 0, 0, 0 },
+    {  923000000, 10000, false, 69, 23, 42,  2,  30, 0, 0, 0 },
+    {  925000000, 10000, false, 69, 23, 46,  2,  30, 0, 0, 0 },
+    {  927000000, 10000, false, 69, 23, 50,  2,  30, 0, 0, 0 },
+    {  918000000, 10000, false, 70, 24, 32,  4,  30, 0, 0, 0 },
+    {  922000000, 10000, false, 70, 24, 40,  4,  30, 0, 0, 0 },
+    {  926000000, 10000, false, 70, 24, 48,  4,  30, 0, 0, 0 },
+    {  924000000, 10000, false, 71, 25, 44,  8,  30, 0, 0, 0 },
+};
+
+/** Channel list structure for Australia. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_AU = {
+    .country_code = "AU",
+    .num_channels = (sizeof(s1g_channels_AU)/sizeof(s1g_channels_AU[0])),
+    .channels = s1g_channels_AU,
+};
+
+/** List of valid S1G channels for EU. */
+static const struct mmwlan_s1g_channel s1g_channels_EU[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  863500000,   280, false, 66,  6,  1,  1,  16, 0, 0, 0 },
+    {  864500000,   280, false, 66,  6,  3,  1,  16, 0, 0, 0 },
+    {  865500000,   280, false, 66,  6,  5,  1,  16, 0, 0, 0 },
+    {  866500000,   280, false, 66,  6,  7,  1,  16, 0, 0, 0 },
+    {  867500000,   280, false, 66,  6,  9,  1,  16, 0, 0, 0 },
+};
+
+/** Channel list structure for EU. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_EU = {
+    .country_code = "EU",
+    .num_channels = (sizeof(s1g_channels_EU)/sizeof(s1g_channels_EU[0])),
+    .channels = s1g_channels_EU,
+};
+
+/** List of valid S1G channels for India. */
+static const struct mmwlan_s1g_channel s1g_channels_IN[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  865500000,   280, false, 66,  6,  5,  1,  16, 0, 0, 0 },
+    {  866500000,   280, false, 66,  6,  7,  1,  16, 0, 0, 0 },
+    {  867500000,   280, false, 66,  6,  9,  1,  16, 0, 0, 0 },
+};
+
+/** Channel list structure for India. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_IN = {
+    .country_code = "IN",
+    .num_channels = (sizeof(s1g_channels_IN)/sizeof(s1g_channels_IN[0])),
+    .channels = s1g_channels_IN,
+};
+
+/** List of valid S1G channels for Japan. */
+static const struct mmwlan_s1g_channel s1g_channels_JP[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  921000000,  1000, true, 73,  8,  9,  1,  16, 2000, 2000, 100000 },
+    {  923000000,  1000, true, 73,  8, 13,  1,  16, 2000, 2000, 100000 },
+    {  924000000,  1000, true, 73,  8, 15,  1,  16, 2000, 2000, 100000 },
+    {  925000000,  1000, true, 73,  8, 17,  1,  16, 2000, 2000, 100000 },
+    {  926000000,  1000, true, 73,  8, 19,  1,  16, 2000, 2000, 100000 },
+    {  927000000,  1000, true, 73,  8, 21,  1,  16, 2000, 2000, 100000 },
+    {  923500000,  1000, true, 64,  9,  2,  2,  16, 2000, 2000, 100000 },
+    {  924500000,  1000, true, 64, 10,  4,  2,  16, 2000, 2000, 100000 },
+    {  925500000,  1000, true, 64,  9,  6,  2,  16, 2000, 2000, 100000 },
+    {  926500000,  1000, true, 64, 10,  8,  2,  16, 2000, 2000, 100000 },
+    {  924500000,  1000, true, 65, 11, 36,  4,  16, 2000, 2000, 100000 },
+    {  925500000,  1000, true, 65, 12, 38,  4,  16, 2000, 2000, 100000 },
+};
+
+/** Channel list structure for Japan. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_JP = {
+    .country_code = "JP",
+    .num_channels = (sizeof(s1g_channels_JP)/sizeof(s1g_channels_JP[0])),
+    .channels = s1g_channels_JP,
+};
+
+/** List of valid S1G channels for South Korea. */
+static const struct mmwlan_s1g_channel s1g_channels_KR[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  918000000, 10000, false, 74, 14,  1,  1,   4, 50000, 0, 4000000 },
+    {  919000000, 10000, false, 74, 14,  3,  1,   4, 50000, 0, 4000000 },
+    {  920000000, 10000, false, 74, 14,  5,  1,   4, 50000, 0, 4000000 },
+    {  921000000, 10000, false, 74, 14,  7,  1,   4, 50000, 0, 4000000 },
+    {  922000000, 10000, false, 74, 14,  9,  1,  10, 50000, 0, 4000000 },
+    {  923000000, 10000, false, 74, 14, 11,  1,  10, 50000, 0, 4000000 },
+    {  918500000, 10000, false, 75, 15,  2,  2,   4, 50000, 0, 4000000 },
+    {  920500000, 10000, false, 75, 15,  6,  2,   4, 50000, 0, 4000000 },
+    {  922500000, 10000, false, 75, 15, 10,  2,  10, 50000, 0, 4000000 },
+    {  921500000, 10000, false, 76, 16,  8,  4,   4, 50000, 0, 4000000 },
+    {  926500000, 10000, false, 74, 14, 18,  1,  17, 264, 0, 220000 }, /* Warning: regulatory requirements may not be met */
+    {  927500000, 10000, false, 74, 14, 20,  1,  17, 264, 0, 220000 }, /* Warning: regulatory requirements may not be met */
+    {  928500000, 10000, false, 74, 14, 22,  1,  17, 264, 0, 220000 }, /* Warning: regulatory requirements may not be met */
+    {  929500000, 10000, false, 74, 14, 24,  1,  17, 264, 0, 220000 }, /* Warning: regulatory requirements may not be met */
+    {  927000000, 10000, false, 75, 15, 19,  2,  20, 264, 0, 220000 }, /* Warning: regulatory requirements may not be met */
+    {  929000000, 10000, false, 75, 15, 23,  2,  20, 264, 0, 220000 }, /* Warning: regulatory requirements may not be met */
+};
+
+/** Channel list structure for South Korea. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_KR = {
+    .country_code = "KR",
+    .num_channels = (sizeof(s1g_channels_KR)/sizeof(s1g_channels_KR[0])),
+    .channels = s1g_channels_KR,
+};
+
+/** List of valid S1G channels for New Zealand. */
+static const struct mmwlan_s1g_channel s1g_channels_NZ[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  915500000, 10000, false, 68, 26, 27,  1,  30, 0, 0, 0 },
+    {  916500000, 10000, false, 68, 26, 29,  1,  30, 0, 0, 0 },
+    {  917500000, 10000, false, 68, 26, 31,  1,  30, 0, 0, 0 },
+    {  918500000, 10000, false, 68, 26, 33,  1,  30, 0, 0, 0 },
+    {  919500000, 10000, false, 68, 26, 35,  1,  30, 0, 0, 0 },
+    {  920500000, 10000, false, 68, 26, 37,  1,  36, 0, 0, 0 },
+    {  921500000, 10000, false, 68, 26, 39,  1,  36, 0, 0, 0 },
+    {  922500000, 10000, false, 68, 26, 41,  1,  36, 0, 0, 0 },
+    {  923500000, 10000, false, 68, 26, 43,  1,  36, 0, 0, 0 },
+    {  924500000, 10000, false, 68, 26, 45,  1,  36, 0, 0, 0 },
+    {  925500000, 10000, false, 68, 26, 47,  1,  36, 0, 0, 0 },
+    {  926500000, 10000, false, 68, 26, 49,  1,  36, 0, 0, 0 },
+    {  927500000, 10000, false, 68, 26, 51,  1,  36, 0, 0, 0 },
+    {  917000000, 10000, false, 69, 27, 30,  2,  30, 0, 0, 0 },
+    {  919000000, 10000, false, 69, 27, 34,  2,  30, 0, 0, 0 },
+    {  921000000, 10000, false, 69, 27, 38,  2,  36, 0, 0, 0 },
+    {  923000000, 10000, false, 69, 27, 42,  2,  36, 0, 0, 0 },
+    {  925000000, 10000, false, 69, 27, 46,  2,  36, 0, 0, 0 },
+    {  927000000, 10000, false, 69, 27, 50,  2,  36, 0, 0, 0 },
+    {  918000000, 10000, false, 70, 28, 32,  4,  30, 0, 0, 0 },
+    {  922000000, 10000, false, 70, 28, 40,  4,  36, 0, 0, 0 },
+    {  926000000, 10000, false, 70, 28, 48,  4,  36, 0, 0, 0 },
+    {  924000000, 10000, false, 71, 29, 44,  8,  36, 0, 0, 0 },
+};
+
+/** Channel list structure for New Zealand. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_NZ = {
+    .country_code = "NZ",
+    .num_channels = (sizeof(s1g_channels_NZ)/sizeof(s1g_channels_NZ[0])),
+    .channels = s1g_channels_NZ,
+};
+
+/** List of valid S1G channels for Singapore. */
+static const struct mmwlan_s1g_channel s1g_channels_SG[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  866500000,   277, false, 66, 17,  7,  1,  29, 100000, 0, 1000000 },
+    {  867500000,   277, false, 66, 17,  9,  1,  29, 100000, 0, 1000000 },
+    {  868500000,   277, false, 66, 17, 11,  1,  29, 100000, 0, 1000000 },
+    {  868000000,   277, false, 67, 19, 10,  2,  29, 100000, 0, 1000000 },
+    {  920500000, 10000, false, 68, 18, 37,  1,  22, 0, 0, 0 },
+    {  921500000, 10000, false, 68, 18, 39,  1,  22, 0, 0, 0 },
+    {  922500000, 10000, false, 68, 18, 41,  1,  22, 0, 0, 0 },
+    {  923500000, 10000, false, 68, 18, 43,  1,  22, 0, 0, 0 },
+    {  924500000, 10000, false, 68, 18, 45,  1,  22, 0, 0, 0 },
+    {  921000000, 10000, false, 69, 20, 38,  2,  22, 0, 0, 0 },
+    {  923000000, 10000, false, 69, 20, 42,  2,  22, 0, 0, 0 },
+    {  922000000, 10000, false, 70, 21, 40,  4,  22, 0, 0, 0 },
+};
+
+/** Channel list structure for Singapore. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_SG = {
+    .country_code = "SG",
+    .num_channels = (sizeof(s1g_channels_SG)/sizeof(s1g_channels_SG[0])),
+    .channels = s1g_channels_SG,
+};
+
+/** List of valid S1G channels for USA. */
+static const struct mmwlan_s1g_channel s1g_channels_US[] = {
+    /* Ctr Freq (Hz), Duty Cycle (%/100), Omit Control Response, Global Op Class, S1G Op Class, S1G Chan #, Op BW, Max Tx EIRP (dBm), Min Packet Spacing Window (microsec), airtime_min (microsec), airtime_max (microsec) */
+    {  902500000, 10000, false, 68,  1,  1,  1,  36, 0, 0, 0 }, /* Warning: regulatory requirements may not be met */
+    {  903500000, 10000, false, 68,  1,  3,  1,  36, 0, 0, 0 },
+    {  904500000, 10000, false, 68,  1,  5,  1,  36, 0, 0, 0 },
+    {  905500000, 10000, false, 68,  1,  7,  1,  36, 0, 0, 0 },
+    {  906500000, 10000, false, 68,  1,  9,  1,  36, 0, 0, 0 },
+    {  907500000, 10000, false, 68,  1, 11,  1,  36, 0, 0, 0 },
+    {  908500000, 10000, false, 68,  1, 13,  1,  36, 0, 0, 0 },
+    {  909500000, 10000, false, 68,  1, 15,  1,  36, 0, 0, 0 },
+    {  910500000, 10000, false, 68,  1, 17,  1,  36, 0, 0, 0 },
+    {  911500000, 10000, false, 68,  1, 19,  1,  36, 0, 0, 0 },
+    {  912500000, 10000, false, 68,  1, 21,  1,  36, 0, 0, 0 },
+    {  913500000, 10000, false, 68,  1, 23,  1,  36, 0, 0, 0 },
+    {  914500000, 10000, false, 68,  1, 25,  1,  36, 0, 0, 0 },
+    {  915500000, 10000, false, 68,  1, 27,  1,  36, 0, 0, 0 },
+    {  916500000, 10000, false, 68,  1, 29,  1,  36, 0, 0, 0 },
+    {  917500000, 10000, false, 68,  1, 31,  1,  36, 0, 0, 0 },
+    {  918500000, 10000, false, 68,  1, 33,  1,  36, 0, 0, 0 },
+    {  919500000, 10000, false, 68,  1, 35,  1,  36, 0, 0, 0 },
+    {  920500000, 10000, false, 68,  1, 37,  1,  36, 0, 0, 0 },
+    {  921500000, 10000, false, 68,  1, 39,  1,  36, 0, 0, 0 },
+    {  922500000, 10000, false, 68,  1, 41,  1,  36, 0, 0, 0 },
+    {  923500000, 10000, false, 68,  1, 43,  1,  36, 0, 0, 0 },
+    {  924500000, 10000, false, 68,  1, 45,  1,  36, 0, 0, 0 },
+    {  925500000, 10000, false, 68,  1, 47,  1,  36, 0, 0, 0 },
+    {  926500000, 10000, false, 68,  1, 49,  1,  36, 0, 0, 0 },
+    {  927500000, 10000, false, 68,  1, 51,  1,  36, 0, 0, 0 },
+    {  903000000, 10000, false, 69,  2,  2,  2,  36, 0, 0, 0 }, /* Warning: regulatory requirements may not be met */
+    {  905000000, 10000, false, 69,  2,  6,  2,  36, 0, 0, 0 },
+    {  907000000, 10000, false, 69,  2, 10,  2,  36, 0, 0, 0 },
+    {  909000000, 10000, false, 69,  2, 14,  2,  36, 0, 0, 0 },
+    {  911000000, 10000, false, 69,  2, 18,  2,  36, 0, 0, 0 },
+    {  913000000, 10000, false, 69,  2, 22,  2,  36, 0, 0, 0 },
+    {  915000000, 10000, false, 69,  2, 26,  2,  36, 0, 0, 0 },
+    {  917000000, 10000, false, 69,  2, 30,  2,  36, 0, 0, 0 },
+    {  919000000, 10000, false, 69,  2, 34,  2,  36, 0, 0, 0 },
+    {  921000000, 10000, false, 69,  2, 38,  2,  36, 0, 0, 0 },
+    {  923000000, 10000, false, 69,  2, 42,  2,  36, 0, 0, 0 },
+    {  925000000, 10000, false, 69,  2, 46,  2,  36, 0, 0, 0 },
+    {  927000000, 10000, false, 69,  2, 50,  2,  36, 0, 0, 0 },
+    {  906000000, 10000, false, 70,  3,  8,  4,  36, 0, 0, 0 },
+    {  910000000, 10000, false, 70,  3, 16,  4,  36, 0, 0, 0 },
+    {  914000000, 10000, false, 70,  3, 24,  4,  36, 0, 0, 0 },
+    {  918000000, 10000, false, 70,  3, 32,  4,  36, 0, 0, 0 },
+    {  922000000, 10000, false, 70,  3, 40,  4,  36, 0, 0, 0 },
+    {  926000000, 10000, false, 70,  3, 48,  4,  36, 0, 0, 0 },
+    {  908000000, 10000, false, 71,  4, 12,  8,  36, 0, 0, 0 },
+    {  916000000, 10000, false, 71,  4, 28,  8,  36, 0, 0, 0 },
+    {  924000000, 10000, false, 71,  4, 44,  8,  36, 0, 0, 0 },
+};
+
+/** Channel list structure for USA. */
+static const struct mmwlan_s1g_channel_list s1g_channel_list_US = {
+    .country_code = "US",
+    .num_channels = (sizeof(s1g_channels_US)/sizeof(s1g_channels_US[0])),
+    .channels = s1g_channels_US,
+};
+
+/** Array of all channel list structs used for the regulatory database. */
+
+static const struct mmwlan_s1g_channel_list *regulatory_db_domains[] = {
+    &s1g_channel_list_AU,
+    &s1g_channel_list_EU,
+    &s1g_channel_list_IN,
+    &s1g_channel_list_JP,
+    &s1g_channel_list_KR,
+    &s1g_channel_list_NZ,
+    &s1g_channel_list_SG,
+    &s1g_channel_list_US,
+};
+
+/** Regulatory database. */
+static const struct mmwlan_regulatory_db regulatory_db = {
+    .num_domains = (sizeof(regulatory_db_domains)/sizeof(regulatory_db_domains[0])),
+    .domains = regulatory_db_domains,
+};
+
+/**
+ * Get a pointer to regulatory_db. This function isn't strictly necessary, since regulatory_db
+ * can be accessed directly, but will prevent the compiler from generated warnings about
+ * regulatory_db being unused.
+ *
+ * @return Reference to the regulatory database
+ */
+static inline const struct mmwlan_regulatory_db *get_regulatory_db(void)
+{
+    return &regulatory_db;
+}
+
+
+/** \} */
@@ -0,0 +1,14 @@
+{
+  "name": "MorseWlan",
+  "version": "0.1.0",
+  "description": "Morse Micro mm-iot-esp32 SDK vendored for Meshtastic HaLow transport. Static morselib (Apache-2.0) + open-source shims.",
+  "frameworks": ["arduino", "espidf"],
+  "platforms": ["espressif32"],
+  "build": {
+    "srcDir": "src",
+    "srcFilter": ["+<*.c>"],
+    "includeDir": "include",
+    "libArchive": false,
+    "extraScript": "extra_script.py"
+  }
+}
@@ -0,0 +1,148 @@
+/*
+ * Copyright 2022-2024 Morse Micro
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+/*
+ * ----
+ * Endianness operations
+ * ----
+ */
+
+#ifdef __big_endian__
+#define __BYTE_ORDER __BIG_ENDIAN
+#else
+#define __BYTE_ORDER __LITTLE_ENDIAN
+#endif
+
+#define bswap_16(x) __builtin_bswap16(x)
+#define bswap_32(x) __builtin_bswap32(x)
+
+#define INET_ADDRSTRLEN 16
+#define INET6_ADDRSTRLEN 46
+
+/* Protocol families.  */
+#define PF_INET 2   /* IP protocol family. */
+#define PF_INET6 10 /* IP version 6. */
+
+/* Address families. */
+#define AF_INET PF_INET
+#define AF_INET6 PF_INET6
+
+/*
+ * ----
+ * Type definitions
+ * ----
+ */
+typedef signed char __s8;
+typedef unsigned char __u8;
+typedef signed short __s16;
+typedef unsigned short __u16;
+typedef signed int __s32;
+typedef unsigned int __u32;
+
+struct in_addr {
+    __u32 s_addr;
+};
+
+struct in6_addr {
+    union {
+        __u32 u32_addr[4];
+        __u8 u8_addr[16];
+    } un;
+#define s6_addr un.u8_addr
+};
+
+/* Stub function declaration for inet_ntop which is called from write_ipv4_info
+ * function in robust_av.c. Since they are not used we will create a dummy
+ * function declarion here.
+ */
+const char *inet_ntop(int __af, const void *__cp, char *__buf, int __len);
+
+/* Rename crypto functions to match symbol name mangling in morselib for avoidance of namespace
+ * collisions. */
+#define aes_decrypt mmint_aes_decrypt
+#define aes_decrypt_deinit mmint_aes_decrypt_deinit
+#define aes_decrypt_init mmint_aes_decrypt_init
+#define crypto_bignum_add mmint_crypto_bignum_add
+#define crypto_bignum_addmod mmint_crypto_bignum_addmod
+#define crypto_bignum_cmp mmint_crypto_bignum_cmp
+#define crypto_bignum_deinit mmint_crypto_bignum_deinit
+#define crypto_bignum_div mmint_crypto_bignum_div
+#define crypto_bignum_exptmod mmint_crypto_bignum_exptmod
+#define crypto_bignum_init mmint_crypto_bignum_init
+#define crypto_bignum_init_set mmint_crypto_bignum_init_set
+#define crypto_bignum_init_uint mmint_crypto_bignum_init_uint
+#define crypto_bignum_inverse mmint_crypto_bignum_inverse
+#define crypto_bignum_is_odd mmint_crypto_bignum_is_odd
+#define crypto_bignum_is_one mmint_crypto_bignum_is_one
+#define crypto_bignum_is_zero mmint_crypto_bignum_is_zero
+#define crypto_bignum_legendre mmint_crypto_bignum_legendre
+#define crypto_bignum_mod mmint_crypto_bignum_mod
+#define crypto_bignum_mulmod mmint_crypto_bignum_mulmod
+#define crypto_bignum_rand mmint_crypto_bignum_rand
+#define crypto_bignum_rshift mmint_crypto_bignum_rshift
+#define crypto_bignum_sqrmod mmint_crypto_bignum_sqrmod
+#define crypto_bignum_sub mmint_crypto_bignum_sub
+#define crypto_bignum_to_bin mmint_crypto_bignum_to_bin
+#define crypto_ec_deinit mmint_crypto_ec_deinit
+#define crypto_ec_get_a mmint_crypto_ec_get_a
+#define crypto_ec_get_b mmint_crypto_ec_get_b
+#define crypto_ec_get_generator mmint_crypto_ec_get_generator
+#define crypto_ec_get_order mmint_crypto_ec_get_order
+#define crypto_ec_get_prime mmint_crypto_ec_get_prime
+#define crypto_ec_init mmint_crypto_ec_init
+#define crypto_ec_order_len mmint_crypto_ec_order_len
+#define crypto_ec_point_add mmint_crypto_ec_point_add
+#define crypto_ec_point_cmp mmint_crypto_ec_point_cmp
+#define crypto_ec_point_x mmint_crypto_ec_point_x
+#define crypto_ec_point_compute_y_sqr mmint_crypto_ec_point_compute_y_sqr
+#define crypto_ec_point_deinit mmint_crypto_ec_point_deinit
+#define crypto_ec_point_from_bin mmint_crypto_ec_point_from_bin
+#define crypto_ec_point_init mmint_crypto_ec_point_init
+#define crypto_ec_point_invert mmint_crypto_ec_point_invert
+#define crypto_ec_point_is_at_infinity mmint_crypto_ec_point_is_at_infinity
+#define crypto_ec_point_is_on_curve mmint_crypto_ec_point_is_on_curve
+#define crypto_ec_point_mul mmint_crypto_ec_point_mul
+#define crypto_ec_point_to_bin mmint_crypto_ec_point_to_bin
+#define crypto_ec_prime_len mmint_crypto_ec_prime_len
+#define crypto_ec_prime_len_bits mmint_crypto_ec_prime_len_bits
+#define crypto_ecdh_deinit mmint_crypto_ecdh_deinit
+#define crypto_ecdh_get_pubkey mmint_crypto_ecdh_get_pubkey
+#define crypto_ecdh_init mmint_crypto_ecdh_init
+#define crypto_ecdh_init2 mmint_crypto_ecdh_init2
+#define crypto_ecdh_set_peerkey mmint_crypto_ecdh_set_peerkey
+#define crypto_ecdh_prime_len mmint_crypto_ecdh_prime_len
+#define crypto_get_random mmint_crypto_get_random
+#define crypto_unload mmint_crypto_unload
+#define hmac_md5 mmint_hmac_md5
+#define hmac_sha1 mmint_hmac_sha1
+#define hmac_sha1_vector mmint_hmac_sha1_vector
+#define hmac_sha256 mmint_hmac_sha256
+#define hmac_sha256_vector mmint_hmac_sha256_vector
+#define hmac_sha384 mmint_hmac_sha384
+#define hmac_sha384_vector mmint_hmac_sha384_vector
+#define hmac_sha512 mmint_hmac_sha512
+#define hmac_sha512_vector mmint_hmac_sha512_vector
+#define omac1_aes_vector mmint_omac1_aes_vector
+#define omac1_aes_128 mmint_omac1_aes_128
+#define pbkdf2_sha1 mmint_pbkdf2_sha1
+#define sha1_prf mmint_sha1_prf
+#define sha1_vector mmint_sha1_vector
+#define sha256_prf mmint_sha256_prf
+#define sha256_prf_bits mmint_sha256_prf_bits
+#define sha256_vector mmint_sha256_vector
+#define sha384_prf mmint_sha384_prf
+#define sha384_vector mmint_sha384_vector
+#define sha512_prf mmint_sha512_prf
+#define sha512_vector mmint_sha512_vector
+
+#define wpabuf_alloc mmint_wpabuf_alloc
+#define wpabuf_alloc_copy mmint_wpabuf_alloc_copy
+#define wpabuf_clear_free mmint_wpabuf_clear_free
+#define wpabuf_put mmint_wpabuf_put
@@ -0,0 +1,27 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Stubs for LWIP netif callback API that Arduino-ESP32's prebuilt LWIP omits
+ * (CONFIG_LWIP_NETIF_STATUS_CALLBACK / _LINK_CALLBACK are disabled in its
+ * sdkconfig, so the real functions are absent from the static library).
+ *
+ * mmipal calls these once during init to register a single callback for
+ * link-up / IP-configured events. With these stubs, the callback never fires —
+ * mmwlan_register_link_state_cb (driven by the radio firmware) remains the
+ * authoritative source of link state, so this only costs us LWIP-level
+ * notifications (e.g. "DHCP got an address"). HaLowInterface polls
+ * mmipal_get_ip_config when it needs to know.
+ */
+#include "lwip/netif.h"
+
+void __attribute__((weak)) netif_set_link_callback(struct netif *netif, netif_status_callback_fn link_callback)
+{
+    (void)netif;
+    (void)link_callback;
+}
+
+void __attribute__((weak)) netif_set_status_callback(struct netif *netif, netif_status_callback_fn status_callback)
+{
+    (void)netif;
+    (void)status_callback;
+}
+#endif
@@ -0,0 +1,216 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ */
+
+#include "mmbuf.h"
+#include "mmosal.h"
+#include "mmutils.h"
+
+static const struct mmbuf_ops mmbuf_heap_ops = {.free_mmbuf = mmosal_free};
+
+struct mmbuf *mmbuf_alloc_on_heap(uint32_t space_at_start, uint32_t space_at_end)
+{
+    struct mmbuf *mmbuf;
+    uint8_t *buf;
+    uint32_t alloc_len = MM_FAST_ROUND_UP(sizeof(*mmbuf), 4) + MM_FAST_ROUND_UP(space_at_start + space_at_end, 4);
+    mmbuf = (struct mmbuf *)mmosal_malloc(alloc_len);
+    if (mmbuf == NULL) {
+        return NULL;
+    }
+
+    /* We zero the buffer as a defensive measure to reduce the likelihood of unintentionally
+     * leaking information. */
+    memset((uint8_t *)mmbuf, 0, alloc_len);
+
+    buf = ((uint8_t *)mmbuf) + MM_FAST_ROUND_UP(sizeof(*mmbuf), 4);
+
+    mmbuf_init(mmbuf, buf, MM_FAST_ROUND_UP(space_at_start + space_at_end, 4), space_at_start, &mmbuf_heap_ops);
+
+    return mmbuf;
+}
+
+struct mmbuf *mmbuf_make_copy_on_heap(struct mmbuf *original)
+{
+    struct mmbuf *mmbuf;
+    uint8_t *buf;
+    uint32_t alloc_len = MM_FAST_ROUND_UP(sizeof(*original), 4) + original->buf_len;
+    mmbuf = (struct mmbuf *)mmosal_malloc(alloc_len);
+    if (mmbuf == NULL) {
+        return NULL;
+    }
+
+    buf = ((uint8_t *)mmbuf) + MM_FAST_ROUND_UP(sizeof(*mmbuf), 4);
+    mmbuf_init(mmbuf, buf, original->buf_len, original->start_offset, &mmbuf_heap_ops);
+    mmbuf->data_len = original->data_len;
+
+    if (original->data_len) {
+        memcpy(mmbuf_get_data_start(mmbuf), mmbuf_get_data_start(original), mmbuf_get_data_length(original));
+    }
+
+    return mmbuf;
+}
+
+void mmbuf_release(struct mmbuf *mmbuf)
+{
+    if (mmbuf == NULL) {
+        return;
+    }
+
+    MMOSAL_ASSERT(mmbuf->ops != NULL && mmbuf->ops->free_mmbuf != NULL);
+    mmbuf->ops->free_mmbuf(mmbuf);
+}
+
+#ifdef MMBUF_SANITY
+static void mmbuf_list_sanity_check(struct mmbuf_list *list)
+{
+    unsigned cnt = 0;
+    struct mmbuf *walk;
+    struct mmbuf *prev = NULL;
+
+    for (walk = list->head; walk != NULL; walk = walk->next) {
+        cnt++;
+        prev = walk;
+    }
+
+    MMOSAL_ASSERT(cnt == list->len);
+    MMOSAL_ASSERT(prev == list->tail);
+}
+#endif
+
+void mmbuf_list_prepend(struct mmbuf_list *list, struct mmbuf *mmbuf)
+{
+    mmbuf->next = list->head;
+    list->head = mmbuf;
+    list->len++;
+
+    if (list->tail == NULL) {
+        list->tail = list->head;
+    }
+
+#ifdef MMBUF_SANITY
+    mmbuf_list_sanity_check(list);
+#endif
+}
+
+void mmbuf_list_append(struct mmbuf_list *list, struct mmbuf *mmbuf)
+{
+    mmbuf->next = NULL;
+    if (list->head == NULL) {
+        list->head = mmbuf;
+        list->tail = mmbuf;
+    } else {
+        list->tail->next = mmbuf;
+        list->tail = mmbuf;
+    }
+    list->len++;
+
+#ifdef MMBUF_SANITY
+    mmbuf_list_sanity_check(list);
+#endif
+}
+
+static struct mmbuf *mmbuf_find_prev(struct mmbuf_list *list, struct mmbuf *mmbuf)
+{
+    struct mmbuf *walk, *next;
+    for (walk = list->head, next = walk->next; next != NULL; walk = next, next = walk->next) {
+        if (next == mmbuf) {
+            return walk;
+        }
+    }
+    return NULL;
+}
+
+bool mmbuf_list_remove(struct mmbuf_list *list, struct mmbuf *mmbuf)
+{
+    struct mmbuf *prev = NULL;
+
+    if (list->head == NULL) {
+        return false;
+    }
+
+    if (list->head == mmbuf) {
+        list->head = mmbuf->next;
+    } else {
+        prev = mmbuf_find_prev(list, mmbuf);
+        if (prev == NULL) {
+            return false;
+        }
+        prev->next = mmbuf->next;
+    }
+
+    if (list->tail == mmbuf) {
+        list->tail = prev;
+    }
+
+    list->len--;
+    mmbuf->next = NULL;
+
+#ifdef MMBUF_SANITY
+    mmbuf_list_sanity_check(list);
+#endif
+
+    return true;
+}
+
+struct mmbuf *mmbuf_list_dequeue(struct mmbuf_list *list)
+{
+    if (list->head == NULL) {
+        return NULL;
+    } else {
+        struct mmbuf *mmbuf = list->head;
+        list->head = mmbuf->next;
+        list->len--;
+
+        if (list->tail == mmbuf) {
+            list->tail = NULL;
+        }
+
+#ifdef MMBUF_SANITY
+        mmbuf_list_sanity_check(list);
+#endif
+        if (mmbuf != NULL) {
+            mmbuf->next = NULL;
+        }
+        return mmbuf;
+    }
+}
+
+struct mmbuf *mmbuf_list_dequeue_tail(struct mmbuf_list *list)
+{
+    if (list->tail == NULL) {
+        return NULL;
+    }
+
+    struct mmbuf *mmbuf = list->tail;
+    mmbuf_list_remove(list, mmbuf);
+
+    return mmbuf;
+}
+
+void mmbuf_list_clear(struct mmbuf_list *list)
+{
+    struct mmbuf *walk;
+    struct mmbuf *next;
+
+#ifdef MMBUF_SANITY
+    mmbuf_list_sanity_check(list);
+#endif
+
+    if (list->head == NULL) {
+        return;
+    }
+
+    for (walk = list->head, next = walk->next; walk != NULL; walk = next, next = walk ? walk->next : NULL) {
+        mmbuf_release(walk);
+    }
+
+    list->len = 0;
+    list->head = NULL;
+    list->tail = NULL;
+}
+
+#endif /* USE_MM_IOT_ESP32 */
@@ -0,0 +1,457 @@
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @defgroup MMBUF Morse Micro Buffer (mmbuf) API
+ *
+ * This API provides support for buffers tailored towards packet-like data that has
+ * headers and trailers that are applied at subsequent layers.
+ *
+ * It is designed to support various backends for memory allocation. The default
+ * is allocation on the heap, but other methods could be used due to the flexible API.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "mmosal.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct mmbuf_ops;
+
+/**
+ * Core mmbuf data structure.
+ *
+ * @note The contents of this data structure should never need to be accessed directly. Rather
+ *       the various functions provided as part of this API should be used.
+ *
+ * @code
+ *      +----------------------------------------------------------+
+ *      | RESERVED |              Data            |    RESERVED    |
+ *      +----------------------------------------------------------+
+ *      ^          ^                              ^                ^
+ *      |          |                              |                |
+ *      |          |<-----------data_len--------->|                |
+ *      |     start_offset                                         |
+ *      |                                                          |
+ *      |<-----------------------buf_len-------------------------->|
+ *     buf
+ * @endcode
+ */
+struct mmbuf {
+    /** The buffer where data is stored. */
+    uint8_t *buf;
+    /** Length of the buffer. */
+    uint32_t buf_len;
+    /** Offset where actual data starts in the buffer. */
+    uint32_t start_offset;
+    /** Length of actual data in the buffer. */
+    uint32_t data_len;
+    /** Reference to operations data structure for this mmbuf. */
+    const struct mmbuf_ops *ops;
+    /** Pointer that can be used to construct linked lists. */
+    struct mmbuf *volatile next;
+};
+
+/** Operations data structure for mmbuf. */
+struct mmbuf_ops {
+    /** Free the given mmbuf. */
+    void (*free_mmbuf)(void *mmbuf);
+};
+
+/**
+ * Initialize an mmbuf header with the given values.
+ *
+ * @param mmbuf                 mmbuf to initialize.
+ * @param buf                   Pointer to buffer.
+ * @param buf_len               Length of @p buf.
+ * @param data_start_offset     Initial value for @c start_offset.
+ * @param ops                   Operations data structure.
+ */
+static inline void mmbuf_init(struct mmbuf *mmbuf, uint8_t *buf, uint32_t buf_len, uint32_t data_start_offset,
+                              const struct mmbuf_ops *ops)
+{
+    memset(mmbuf, 0, sizeof(*mmbuf));
+    mmbuf->buf = buf;
+    mmbuf->buf_len = buf_len;
+    mmbuf->start_offset = data_start_offset;
+    mmbuf->ops = ops;
+}
+
+/**
+ * Allocate a new mmbuf on the heap (using @ref mmosal_malloc()).
+ *
+ * @param space_at_start    Amount of space to reserve at start of buffer.
+ * @param space_at_end      Amount of space to reserve at end of buffer.
+ *
+ * @note @c start_offset will be set to @p space_at_start, and @c buf_len will be the sum
+ *       of @p space_at_start and @p space_at_end (rounded up to a multiple of 4).
+ *
+ * @returns newly allocated mmbuf on success or @c NULL on failure.
+ */
+struct mmbuf *mmbuf_alloc_on_heap(uint32_t space_at_start, uint32_t space_at_end);
+
+/**
+ * Make a copy of the given mmbuf. Note that regardless of the backend that allocated
+ * @p original, the newly allocated mmbuf will be allocated on the heap using
+ * @ref mmbuf_alloc_on_heap().
+ *
+ * @param original          mmbuf to copy.
+ *
+ * @returns newly allocated mmbuf on success or @c NULL on failure.
+ */
+struct mmbuf *mmbuf_make_copy_on_heap(struct mmbuf *original);
+
+/**
+ * Release a reference to the given mmbuf. If this was the last reference (@c addition_ref_cnt
+ * was 0) then the mmbuf will be freed using the appropriate op callback.
+ *
+ * @param mmbuf     The mmbuf to release reference to. May be @c NULL.
+ */
+void mmbuf_release(struct mmbuf *mmbuf);
+
+/**
+ * Gets a pointer to the start of the data in the mmbuf.
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ *
+ * @returns a pointer to the start of the data in the mmbuf.
+ */
+static inline uint8_t *mmbuf_get_data_start(struct mmbuf *mmbuf)
+{
+    return mmbuf->buf + mmbuf->start_offset;
+}
+
+/**
+ * Gets a pointer to the end of the data in the mmbuf.
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ *
+ * @returns a pointer to the end of the data in the mmbuf.
+ */
+static inline uint8_t *mmbuf_get_data_end(struct mmbuf *mmbuf)
+{
+    return mmbuf->buf + mmbuf->start_offset + mmbuf->data_len;
+}
+
+/**
+ * Gets the length of the data currently in the mmbuf.
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ *
+ * @returns the length of the data currently in the mmbuf (note that this is different from the
+ *          length of the available buffer space).
+ */
+static inline uint32_t mmbuf_get_data_length(struct mmbuf *mmbuf)
+{
+    return mmbuf->data_len;
+}
+
+/**
+ * Returns the amount of space available for prepending to the data in the buffer.
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ *
+ * @returns the available space in bytes.
+ */
+static inline uint32_t mmbuf_available_space_at_start(struct mmbuf *mmbuf)
+{
+    return mmbuf->start_offset;
+}
+
+/**
+ * Returns the amount of space available for appending to the data in the buffer.
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ *
+ * @returns the available space in bytes.
+ */
+static inline uint32_t mmbuf_available_space_at_end(struct mmbuf *mmbuf)
+{
+    return mmbuf->buf_len - (mmbuf->start_offset + mmbuf->data_len);
+}
+
+/**
+ * Reserves space immediately before the data currently in the given mmbuf and returns
+ * a pointer to this space.
+ *
+ * For a function that also copies data in, see @ref mmbuf_prepend_data().
+ *
+ * @warning @p len must be less than or equal to @ref mmbuf_available_space_at_start().
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ * @param len       Length of data to be prepended.
+ *
+ * @returns a pointer to the place in the buffer where the data should be put.
+ */
+static inline uint8_t *mmbuf_prepend(struct mmbuf *mmbuf, uint32_t len)
+{
+    MMOSAL_ASSERT(len <= mmbuf_available_space_at_start(mmbuf));
+    mmbuf->start_offset -= len;
+    mmbuf->data_len += len;
+    return mmbuf->buf + mmbuf->start_offset;
+}
+
+/**
+ * Prepends the given data to the data already in the mmbuf.
+ *
+ * @warning @p len must be less than or equal to @ref mmbuf_available_space_at_start().
+ *
+ * @warning The memory area pointed to by data must not overlap with the mmbuf data.
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ * @param data      The data to be prepended.
+ * @param len       Length of data to be prepended.
+ */
+static inline void mmbuf_prepend_data(struct mmbuf *mmbuf, const uint8_t *data, uint32_t len)
+{
+    uint8_t *dest = mmbuf_prepend(mmbuf, len);
+    memcpy(dest, data, len);
+}
+
+/**
+ * Reserves space immediately after the data currently in the given mmbuf and returns
+ * a pointer to this space.
+ *
+ * For a function that also copies data in, see @ref mmbuf_append_data().
+ *
+ * @warning @p len must be less than or equal to @ref mmbuf_available_space_at_end().
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ * @param len       Length of data to be append.
+ *
+ * @returns a pointer to the place in the buffer where the data should be put.
+ */
+static inline uint8_t *mmbuf_append(struct mmbuf *mmbuf, uint32_t len)
+{
+    uint8_t *ret = mmbuf_get_data_end(mmbuf);
+    MMOSAL_ASSERT(len <= mmbuf_available_space_at_end(mmbuf));
+    mmbuf->data_len += len;
+    return ret;
+}
+
+/**
+ * Appends the given data to the data already in the mmbuf.
+ *
+ * @warning @p len must be less than or equal to @ref mmbuf_available_space_at_start().
+ *
+ * @param mmbuf     The mmbuf to operate on.
+ * @param data      The data to be prepended.
+ * @param len       Length of data to be prepended.
+ */
+static inline void mmbuf_append_data(struct mmbuf *mmbuf, const uint8_t *data, uint32_t len)
+{
+    uint8_t *dest = mmbuf_append(mmbuf, len);
+    memcpy(dest, data, len);
+}
+
+/**
+ * Remove data from the start of the mmbuf.
+ *
+ * @param mmbuf     mmbuf to operate on.
+ * @param len       Length of data to remove.
+ *
+ * @returns a pointer to the removed data or NULL if the mmbuf data length was less than @p len.
+ */
+static inline uint8_t *mmbuf_remove_from_start(struct mmbuf *mmbuf, uint32_t len)
+{
+    uint8_t *ret;
+
+    if (mmbuf_get_data_length(mmbuf) < len) {
+        return NULL;
+    }
+
+    ret = mmbuf_get_data_start(mmbuf);
+
+    mmbuf->start_offset += len;
+    mmbuf->data_len -= len;
+
+    return ret;
+}
+
+/**
+ * Remove data from the end of the mmbuf.
+ *
+ * @param mmbuf     mmbuf to operate on.
+ * @param len       Length of data to remove.
+ *
+ * @returns a pointer to the removed data or NULL if the mmbuf data length was less than @p len.
+ */
+static inline uint8_t *mmbuf_remove_from_end(struct mmbuf *mmbuf, uint32_t len)
+{
+    uint8_t *ret;
+
+    if (mmbuf_get_data_length(mmbuf) < len) {
+        return NULL;
+    }
+
+    ret = mmbuf_get_data_end(mmbuf) - len;
+
+    mmbuf->data_len -= len;
+
+    return ret;
+}
+
+/**
+ * Truncate the mmbuf data to the given length.
+ *
+ * @param mmbuf     mmbuf to operate on.
+ * @param len       New data length. (Must be less than or equal to the data length
+ *                  of the mmbuf).
+ */
+static inline void mmbuf_truncate(struct mmbuf *mmbuf, uint32_t len)
+{
+    MMOSAL_ASSERT(len <= mmbuf->data_len);
+    mmbuf->data_len = len;
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+/** Structure that can be used as the head of a linked list of mmbufs that counts its length. */
+struct mmbuf_list {
+    /** First mmbuf in the list. */
+    struct mmbuf *volatile head;
+    /** Last mmbuf in the list. */
+    struct mmbuf *volatile tail;
+    /** Length of the list. */
+    volatile uint32_t len;
+};
+
+/** Static initializer for @ref mmbuf_list. */
+#define MMBUF_LIST_INIT                                                                                                          \
+    {                                                                                                                            \
+        NULL, NULL, 0                                                                                                            \
+    }
+
+/**
+ * Initialization function for @ref mmbuf_list, for cases where @c MMBUF_LIST_INIT
+ * cannot be used.
+ *
+ * @param list  The mmbuf_list to init.
+ */
+static inline void mmbuf_list_init(struct mmbuf_list *list)
+{
+    list->head = NULL;
+    list->tail = NULL;
+    list->len = 0;
+}
+
+/**
+ * Add an mmbuf to the start of an mmbuf list.
+ *
+ * @param list  The list to prepend to.
+ * @param mmbuf The mmbuf to prepend.
+ */
+void mmbuf_list_prepend(struct mmbuf_list *list, struct mmbuf *mmbuf);
+
+/**
+ * Add an mmbuf to the end of an mmbuf list.
+ *
+ * @param list  The list to append to.
+ * @param mmbuf The mmbuf to append.
+ */
+void mmbuf_list_append(struct mmbuf_list *list, struct mmbuf *mmbuf);
+
+/**
+ * Remove an mmbuf from an mmbuf list.
+ *
+ * @param list  The list to remove from.
+ * @param mmbuf The mmbuf to remove.
+ *
+ * @returns @c true if the given @c mmbuf was present in @c list, else @c fase.
+ */
+bool mmbuf_list_remove(struct mmbuf_list *list, struct mmbuf *mmbuf);
+
+/**
+ * Remove the mmbuf at the head of the list and return it.
+ *
+ * @param list  The list to dequeue from.
+ *
+ * @returns the dequeued mmbuf, or @c NULL if the list is empty.
+ */
+struct mmbuf *mmbuf_list_dequeue(struct mmbuf_list *list);
+
+/**
+ * Remove the mmbuf at the tail of the list and return it.
+ *
+ * @param list  The list to dequeue from.
+ *
+ * @returns the dequeued mmbuf, or @c NULL if the list is empty.
+ */
+struct mmbuf *mmbuf_list_dequeue_tail(struct mmbuf_list *list);
+
+/**
+ * Remove all mmbufs from the list and return as a linked list.
+ *
+ * @param list  The list to dequeue from.
+ *
+ * @returns the dequeued mmbufs, or @c NULL if the list is empty.
+ */
+static inline struct mmbuf *mmbuf_list_dequeue_all(struct mmbuf_list *list)
+{
+    struct mmbuf *head = list->head;
+    list->head = NULL;
+    list->tail = NULL;
+    list->len = 0;
+    return head;
+}
+
+/**
+ * Checks whether the given mmbuf list is empty.
+ *
+ * @param list  The list to check.
+ *
+ * @returns @c true if the list is empty, else @c false.
+ */
+static inline bool mmbuf_list_is_empty(struct mmbuf_list *list)
+{
+    return (list->head == NULL);
+}
+
+/**
+ * Returns the head of the mmbuf list.
+ *
+ * @param list  The list to peek into.
+ *
+ * @returns the mmbuf at the head of the list.
+ */
+static inline struct mmbuf *mmbuf_list_peek(struct mmbuf_list *list)
+{
+    return list->head;
+}
+
+/**
+ * Returns the tail of the mmbuf list.
+ *
+ * @param list  The list to peek into.
+ *
+ * @returns the mmbuf at the tail of the list.
+ */
+static inline struct mmbuf *mmbuf_list_peek_tail(struct mmbuf_list *list)
+{
+    return list->tail;
+}
+
+/**
+ * Free all the packets in the given list and reset the list to empty state.
+ *
+ * @param list  The list to clear.
+ */
+void mmbuf_list_clear(struct mmbuf_list *list);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,50 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mmcrc.h"
+
+/**
+ * Static table used for the table_driven implementation.
+ */
+static const uint16_t crc16_xmodem_lookup_table[256] = {
+    0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7, 0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c, 0xd1ad, 0xe1ce,
+    0xf1ef, 0x1231, 0x0210, 0x3273, 0x2252, 0x52b5, 0x4294, 0x72f7, 0x62d6, 0x9339, 0x8318, 0xb37b, 0xa35a, 0xd3bd, 0xc39c,
+    0xf3ff, 0xe3de, 0x2462, 0x3443, 0x0420, 0x1401, 0x64e6, 0x74c7, 0x44a4, 0x5485, 0xa56a, 0xb54b, 0x8528, 0x9509, 0xe5ee,
+    0xf5cf, 0xc5ac, 0xd58d, 0x3653, 0x2672, 0x1611, 0x0630, 0x76d7, 0x66f6, 0x5695, 0x46b4, 0xb75b, 0xa77a, 0x9719, 0x8738,
+    0xf7df, 0xe7fe, 0xd79d, 0xc7bc, 0x48c4, 0x58e5, 0x6886, 0x78a7, 0x0840, 0x1861, 0x2802, 0x3823, 0xc9cc, 0xd9ed, 0xe98e,
+    0xf9af, 0x8948, 0x9969, 0xa90a, 0xb92b, 0x5af5, 0x4ad4, 0x7ab7, 0x6a96, 0x1a71, 0x0a50, 0x3a33, 0x2a12, 0xdbfd, 0xcbdc,
+    0xfbbf, 0xeb9e, 0x9b79, 0x8b58, 0xbb3b, 0xab1a, 0x6ca6, 0x7c87, 0x4ce4, 0x5cc5, 0x2c22, 0x3c03, 0x0c60, 0x1c41, 0xedae,
+    0xfd8f, 0xcdec, 0xddcd, 0xad2a, 0xbd0b, 0x8d68, 0x9d49, 0x7e97, 0x6eb6, 0x5ed5, 0x4ef4, 0x3e13, 0x2e32, 0x1e51, 0x0e70,
+    0xff9f, 0xefbe, 0xdfdd, 0xcffc, 0xbf1b, 0xaf3a, 0x9f59, 0x8f78, 0x9188, 0x81a9, 0xb1ca, 0xa1eb, 0xd10c, 0xc12d, 0xf14e,
+    0xe16f, 0x1080, 0x00a1, 0x30c2, 0x20e3, 0x5004, 0x4025, 0x7046, 0x6067, 0x83b9, 0x9398, 0xa3fb, 0xb3da, 0xc33d, 0xd31c,
+    0xe37f, 0xf35e, 0x02b1, 0x1290, 0x22f3, 0x32d2, 0x4235, 0x5214, 0x6277, 0x7256, 0xb5ea, 0xa5cb, 0x95a8, 0x8589, 0xf56e,
+    0xe54f, 0xd52c, 0xc50d, 0x34e2, 0x24c3, 0x14a0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405, 0xa7db, 0xb7fa, 0x8799, 0x97b8,
+    0xe75f, 0xf77e, 0xc71d, 0xd73c, 0x26d3, 0x36f2, 0x0691, 0x16b0, 0x6657, 0x7676, 0x4615, 0x5634, 0xd94c, 0xc96d, 0xf90e,
+    0xe92f, 0x99c8, 0x89e9, 0xb98a, 0xa9ab, 0x5844, 0x4865, 0x7806, 0x6827, 0x18c0, 0x08e1, 0x3882, 0x28a3, 0xcb7d, 0xdb5c,
+    0xeb3f, 0xfb1e, 0x8bf9, 0x9bd8, 0xabbb, 0xbb9a, 0x4a75, 0x5a54, 0x6a37, 0x7a16, 0x0af1, 0x1ad0, 0x2ab3, 0x3a92, 0xfd2e,
+    0xed0f, 0xdd6c, 0xcd4d, 0xbdaa, 0xad8b, 0x9de8, 0x8dc9, 0x7c26, 0x6c07, 0x5c64, 0x4c45, 0x3ca2, 0x2c83, 0x1ce0, 0x0cc1,
+    0xef1f, 0xff3e, 0xcf5d, 0xdf7c, 0xaf9b, 0xbfba, 0x8fd9, 0x9ff8, 0x6e17, 0x7e36, 0x4e55, 0x5e74, 0x2e93, 0x3eb2, 0x0ed1,
+    0x1ef0};
+
+/**
+ * @note This implementation(with a few modifications) and corresponding table was generated using
+ *       pycrc v0.9.2 (MIT) using the XMODEM model. https://pycrc.org/. The code generated by pycrc
+ *       is not considered a substantial portion of the software, therefore the licence does not
+ *       cover the generated code, and the author of pycrc will not claim any copyright on the
+ *       generated code (https://pypi.org/project/pycrc/0.9.2/).
+ */
+uint16_t mmcrc_16_xmodem(uint16_t crc, const void *data, size_t data_len)
+{
+    const uint8_t *d = (const uint8_t *)data;
+
+    while (data_len--) {
+        crc = (crc16_xmodem_lookup_table[((crc >> 8) ^ *d++)] ^ (crc << 8));
+    }
+    return crc;
+}
+
+#endif /* USE_MM_IOT_ESP32 */
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @defgroup MMCRC Morse Micro Cyclic Redundancy Check (mmcrc) API
+ *
+ * This API provides support for CRC algorithms used by Morse Micro code.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Compute the CRC-16 for the data buffer using the XMODEM model.
+ *
+ * @param crc       Seed for CRC calc, zero in most cases this is zero (0). If chaining calls
+ *                  then this is the output from the previous invocation.
+ * @param data      Pointer to the start of the data to calculate the crc over.
+ * @param data_len  Length of the data array in bytes.
+ *
+ * @return Returns the CRC value.
+ */
+uint16_t mmcrc_16_xmodem(uint16_t crc, const void *data, size_t data_len);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,100 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mmhal.h"
+#include "mmosal.h"
+#include "mmutils.h"
+#include "mmwlan.h"
+
+#include "driver/gpio.h"
+#include "esp_random.h"
+#include "esp_system.h"
+#include "sdkconfig.h"
+
+void mmhal_init(void)
+{
+    /* We initialise the MM_RESET_N Pin here so that we can hold the MM6108 in reset regardless of
+     * whether the mmhal_wlan_init/deinit function have been called. This allows us to ensure the
+     * chip is in its lowest power state. You may want to revise this depending on your particular
+     * hardware configuration. */
+    gpio_config_t io_conf = {};
+    io_conf.intr_type = GPIO_INTR_DISABLE;
+    io_conf.mode = GPIO_MODE_OUTPUT;
+    io_conf.pin_bit_mask = (1 << CONFIG_MM_RESET_N);
+    io_conf.pull_down_en = 0;
+    io_conf.pull_up_en = 0;
+    gpio_config(&io_conf);
+
+    gpio_set_level(CONFIG_MM_RESET_N, 0);
+
+    /* Initialise the gpio ISR handler service. This allows per-pin GPIO interrupt handlers and is
+     * what is used to register all the wlan related interrupt. */
+    gpio_install_isr_service(0);
+}
+
+void mmhal_log_write(const uint8_t *data, size_t length)
+{
+    while (length--) {
+        putc(*data++, stdout);
+    }
+}
+
+void mmhal_log_flush(void) {}
+
+void mmhal_read_mac_addr(uint8_t *mac_addr)
+{
+    /* We do not override the MAC address here. Therefore the driver will attempt to read it from
+     * the chip and failing that will assign a randomly generated address. */
+    (void)(mac_addr);
+}
+
+uint32_t mmhal_random_u32(uint32_t min, uint32_t max)
+{
+    /* Note: the below implementation does not guarantee a uniform distribution. */
+
+    uint32_t random_value = esp_random();
+
+    if (min == 0 && max == UINT32_MAX) {
+        return random_value;
+    } else {
+        /* Calculate the range and shift required to fit within [min, max] */
+        return (random_value % (max - min + 1)) + min;
+    }
+}
+
+void mmhal_reset(void)
+{
+    esp_restart();
+    while (1) {
+    }
+}
+
+void mmhal_set_deep_sleep_veto(uint8_t veto_id)
+{
+    MM_UNUSED(veto_id);
+}
+
+void mmhal_clear_deep_sleep_veto(uint8_t veto_id)
+{
+    MM_UNUSED(veto_id);
+}
+
+void mmhal_set_led(uint8_t led, uint8_t level)
+{
+    MM_UNUSED(led);
+    MM_UNUSED(level);
+}
+
+bool mmhal_get_hardware_version(char *version_buffer, size_t version_buffer_length)
+{
+    /* Note: You need to identify the correct hardware and or version
+     *       here using whatever means available (GPIO's, version number stored in EEPROM, etc)
+     *       and return the correct string here. */
+    return !mmosal_safer_strcpy(version_buffer, "MM-ESP32S3 V1.0", version_buffer_length);
+}
+
+#endif /* USE_MM_IOT_ESP32 */
@@ -0,0 +1,72 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mmhal_wlan.h"
+#include "mmosal.h"
+
+/*
+ * ---------------------------------------------------------------------------------------------
+ *                                      BCF Retrieval
+ * ---------------------------------------------------------------------------------------------
+ */
+
+/*
+ * The following implementation reads the BCF File from the config store.
+ */
+
+void mmhal_wlan_read_bcf_file(uint32_t offset, uint32_t requested_len, struct mmhal_robuf *robuf)
+{
+    /** Points to the start of the BCF binary image. Defined as part of the Makefile */
+    extern uint8_t bcf_binary_start;
+    /** Points to the end of the BCF binary image. Defined as part of the Makefile */
+    extern uint8_t bcf_binary_end;
+
+    size_t bcf_len = &bcf_binary_end - &bcf_binary_start;
+
+    /* Initialise robuf */
+    robuf->buf = NULL;
+    robuf->len = 0;
+    robuf->free_arg = NULL;
+    robuf->free_cb = NULL;
+
+    /* Sanity check */
+    if (bcf_len < offset) {
+        printf("Detected an attempt to start reading off the end of the bcf file.\n");
+        return;
+    }
+
+    robuf->buf = (uint8_t *)&bcf_binary_start + offset;
+    robuf->len = bcf_len - offset;
+    robuf->len = (robuf->len < requested_len) ? robuf->len : requested_len;
+}
+
+/*
+ * ---------------------------------------------------------------------------------------------
+ *                                    Firmware Retrieval
+ * ---------------------------------------------------------------------------------------------
+ */
+/** Points to the start of the firmware binary image. Defined as part of the Makefile */
+extern uint8_t firmware_binary_start;
+/** Points to the end of the firmware binary image. Defined as part of the Makefile */
+extern uint8_t firmware_binary_end;
+
+void mmhal_wlan_read_fw_file(uint32_t offset, uint32_t requested_len, struct mmhal_robuf *robuf)
+{
+    uint32_t firmware_len = &firmware_binary_end - &firmware_binary_start;
+    if (offset > firmware_len) {
+        printf("Detected an attempt to start read off the end of the firmware file.\n");
+        robuf->buf = NULL;
+        return;
+    }
+
+    robuf->buf = (&firmware_binary_start + offset);
+    firmware_len -= offset;
+
+    robuf->len = (firmware_len < requested_len) ? firmware_len : requested_len;
+}
+
+#endif /* USE_MM_IOT_ESP32 */
@@ -0,0 +1,726 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mmipal.h"
+#include "mmnetif.h"
+#include "mmosal.h"
+#include "mmutils.h"
+#include "mmwlan.h"
+
+#include "lwip/api.h"
+#include "lwip/autoip.h"
+#include "lwip/def.h"
+#include "lwip/dhcp.h"
+#include "lwip/dhcp6.h"
+#include "lwip/dns.h"
+#include "lwip/etharp.h"
+#include "lwip/ethip6.h"
+#include "lwip/igmp.h"
+#include "lwip/inet.h"
+#include "lwip/ip4_frag.h"
+#include "lwip/ip6_frag.h"
+#include "lwip/ip_addr.h"
+#include "lwip/mem.h"
+#include "lwip/sockets.h"
+#include "lwip/stats.h"
+#include "lwip/tcp.h"
+#include "lwip/tcpip.h"
+#include "lwip/udp.h"
+
+static struct mmipal_data {
+    struct netif lwip_mmnetif;
+    /** This stores the IPv4 link state for the IP stack. I.e., do we have an IP address or not. */
+    enum mmipal_link_state ip_link_state;
+    /** Flag requesting ARP response offload feature */
+    bool offload_arp_response;
+    /** ARP refresh offload interval in seconds */
+    uint32_t offload_arp_refresh_s;
+    bool dhcp_offload_init_complete;
+    /** The link status callback function that has been registered. */
+    mmipal_link_status_cb_fn_t link_status_callback;
+    /** The extended link status callback function that has been registered. */
+    mmipal_ext_link_status_cb_fn_t ext_link_status_callback;
+    /** Argument for the extended link status callback function that has been registered. */
+    void *ext_link_status_callback_arg;
+#if LWIP_IPV4
+    enum mmipal_addr_mode ip4_mode;
+#endif
+#if LWIP_IPV6
+    enum mmipal_ip6_addr_mode ip6_mode;
+#endif
+} mmipal_data = {};
+
+/** Getter function to retrieve the global mmipal data structure.*/
+static inline struct mmipal_data *mmipal_get_data(void)
+{
+    return &mmipal_data;
+}
+
+static void netif_status_callback(struct netif *netif);
+
+#if LWIP_IPV4
+
+/**
+ * DHCP Lease update callback, invoked when we get a new DHCP lease.
+ *
+ * @param lease_info The new DHCP lease.
+ */
+static void mmipal_dhcp_lease_updated(const struct mmwlan_dhcp_lease_info *lease_info, void *arg)
+{
+    struct mmipal_data *data = mmipal_get_data();
+
+    ip4_addr_t ip_addr, netmask, gateway;
+    ip_addr_t dns_addr = ip_addr_any;
+
+    MM_UNUSED(arg);
+
+    data->dhcp_offload_init_complete = true;
+
+    ip4_addr_set_u32(&ip_addr, lease_info->ip4_addr);
+    ip4_addr_set_u32(&netmask, lease_info->mask4_addr);
+    ip4_addr_set_u32(&gateway, lease_info->gw4_addr);
+    ip4_addr_set_u32(ip_2_ip4(&dns_addr), lease_info->dns4_addr);
+
+    LOCK_TCPIP_CORE();
+    netif_set_addr(&data->lwip_mmnetif, &ip_addr, &netmask, &gateway);
+    dns_setserver(0, &dns_addr);
+    UNLOCK_TCPIP_CORE();
+
+    netif_status_callback(&data->lwip_mmnetif);
+}
+
+enum mmipal_status mmipal_get_ip_config(struct mmipal_ip_config *config)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    char *result;
+
+    config->mode = data->ip4_mode;
+
+    result = ipaddr_ntoa_r(&data->lwip_mmnetif.ip_addr, config->ip_addr, sizeof(config->ip_addr));
+    LWIP_ASSERT("IP buf too short", result != NULL);
+
+    result = ipaddr_ntoa_r(&data->lwip_mmnetif.netmask, config->netmask, sizeof(config->netmask));
+    LWIP_ASSERT("IP buf too short", result != NULL);
+
+    result = ipaddr_ntoa_r(&data->lwip_mmnetif.gw, config->gateway_addr, sizeof(config->gateway_addr));
+    LWIP_ASSERT("IP buf too short", result != NULL);
+
+    return MMIPAL_SUCCESS;
+}
+
+enum mmipal_status mmipal_set_ip_config(const struct mmipal_ip_config *config)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    int result;
+    ip_addr_t ip_addr = ip_addr_any;
+    ip_addr_t netmask = ip_addr_any;
+    ip_addr_t gateway = ip_addr_any;
+    struct netif *netif = &data->lwip_mmnetif;
+
+    if (config->mode != MMIPAL_DHCP_OFFLOAD && data->ip4_mode == MMIPAL_DHCP_OFFLOAD) {
+        printf("Once enabled DHCP offload mode cannot be disabled\n");
+        return MMIPAL_NOT_SUPPORTED;
+    }
+
+    switch (config->mode) {
+    case MMIPAL_DISABLED:
+        printf("%s mode not supported\n", "DISABLED");
+        return MMIPAL_INVALID_ARGUMENT;
+
+    case MMIPAL_AUTOIP:
+        printf("%s mode not supported\n", "AutoIP");
+        return MMIPAL_INVALID_ARGUMENT;
+
+    case MMIPAL_DHCP_OFFLOAD:
+        /* Currently we only support enabling DHCP offload when initialising */
+        printf("%s mode not supported\n", "DHCP_OFFLOAD");
+        return MMIPAL_INVALID_ARGUMENT;
+
+    case MMIPAL_STATIC:
+        result = ipaddr_aton(config->ip_addr, &ip_addr);
+        if (!result) {
+            return MMIPAL_INVALID_ARGUMENT;
+        }
+        result = ipaddr_aton(config->netmask, &netmask);
+        if (!result) {
+            return MMIPAL_INVALID_ARGUMENT;
+        }
+        result = ipaddr_aton(config->gateway_addr, &gateway);
+        if (!result) {
+            return MMIPAL_INVALID_ARGUMENT;
+        }
+        break;
+
+    case MMIPAL_DHCP:
+        break;
+    }
+
+    LOCK_TCPIP_CORE();
+
+    if (config->mode != MMIPAL_DHCP && data->ip4_mode == MMIPAL_DHCP) {
+        /* Stop DHCP if it was started earlier before setting static IP */
+        dhcp_stop(netif);
+    }
+
+    data->ip4_mode = config->mode;
+
+    netif_set_addr(netif, ip_2_ip4(&ip_addr), ip_2_ip4(&netmask), ip_2_ip4(&gateway));
+    if (data->ip4_mode == MMIPAL_DHCP) {
+        result = dhcp_start(netif);
+        LWIP_ASSERT("DHCP start error", result == ERR_OK);
+    }
+
+    UNLOCK_TCPIP_CORE();
+    return MMIPAL_SUCCESS;
+}
+
+enum mmipal_status mmipal_get_ip_broadcast_addr(mmipal_ip_addr_t broadcast_addr)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    char *result;
+
+    uint32_t ip_addr = ip_addr_get_ip4_u32(&data->lwip_mmnetif.ip_addr);
+    uint32_t netmask = ip_addr_get_ip4_u32(&data->lwip_mmnetif.netmask);
+    uint32_t broadcast_u32 = (ip_addr & netmask) | (0xffffffff & ~netmask);
+    ip_addr_t broadcast_ip_addr;
+    ip_addr_t *_broadcast_ip_addr = &broadcast_ip_addr;
+    ip_addr_set_ip4_u32(_broadcast_ip_addr, broadcast_u32);
+
+    result = ipaddr_ntoa_r(&broadcast_ip_addr, broadcast_addr, MMIPAL_IPADDR_STR_MAXLEN);
+    LWIP_ASSERT("IP buf too short", result != NULL);
+
+    return MMIPAL_SUCCESS;
+}
+
+#else
+enum mmipal_status mmipal_get_ip_config(struct mmipal_ip_config *config)
+{
+    MM_UNUSED(config);
+    LWIP_ASSERT("IPv4 not enabled", false);
+    return MMIPAL_NOT_SUPPORTED;
+}
+
+enum mmipal_status mmipal_set_ip_config(const struct mmipal_ip_config *config)
+{
+    MM_UNUSED(config);
+    LWIP_ASSERT("IPv4 not enabled", false);
+    return MMIPAL_NOT_SUPPORTED;
+}
+
+enum mmipal_status mmipal_get_ip_broadcast_addr(mmipal_ip_addr_t broadcast_addr)
+{
+    MM_UNUSED(broadcast_addr);
+    LWIP_ASSERT("IPv4 not enabled", false);
+    return MMIPAL_NOT_SUPPORTED;
+}
+
+#endif
+
+#if LWIP_IPV6
+
+enum mmipal_status mmipal_get_ip6_config(struct mmipal_ip6_config *config)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    unsigned ii;
+    struct netif *netif = &data->lwip_mmnetif;
+
+    if (config == NULL) {
+        return MMIPAL_INVALID_ARGUMENT;
+    }
+    config->ip6_mode = data->ip6_mode;
+    for (ii = 0; ii < LWIP_IPV6_NUM_ADDRESSES; ii++) {
+        char *result;
+        const ip_addr_t *addr = &ip6_addr_any;
+
+        if (ip6_addr_isvalid(netif_ip6_addr_state(netif, ii))) {
+            addr = &data->lwip_mmnetif.ip6_addr[ii];
+        }
+
+        result = ipaddr_ntoa_r(addr, config->ip6_addr[ii], sizeof(config->ip6_addr[ii]));
+        LWIP_ASSERT("IP buf too short", result != NULL);
+    }
+    return MMIPAL_SUCCESS;
+}
+
+enum mmipal_status mmipal_set_ip6_config(const struct mmipal_ip6_config *config)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    struct netif *netif = &data->lwip_mmnetif;
+    err_t result;
+    unsigned ii;
+    ip_addr_t ip6_addr[LWIP_IPV6_NUM_ADDRESSES];
+
+    for (ii = 0; ii < LWIP_IPV6_NUM_ADDRESSES; ii++) {
+        int result = ipaddr_aton(config->ip6_addr[ii], &ip6_addr[ii]);
+        if (!result) {
+            return MMIPAL_INVALID_ARGUMENT;
+        }
+    }
+
+    LOCK_TCPIP_CORE();
+
+    if (config->ip6_mode == MMIPAL_IP6_STATIC) {
+        if (data->ip6_mode != MMIPAL_IP6_STATIC) {
+#if LWIP_IPV6_DHCP6
+            dhcp6_disable(netif);
+#endif
+            netif_set_ip6_autoconfig_enabled(netif, 0);
+            data->ip6_mode = MMIPAL_IP6_STATIC;
+        }
+
+        if (!ip6_addr_islinklocal(ip_2_ip6(&(ip6_addr[0])))) {
+            printf("First address must be linklocal address (address start with fe80)\n");
+        }
+
+        for (ii = 0; ii < LWIP_IPV6_NUM_ADDRESSES; ii++) {
+            if (ip_addr_isany_val(ip6_addr[ii])) {
+                netif_ip6_addr_set(netif, ii, IP6_ADDR_ANY6);
+                netif_ip6_addr_set_state(netif, ii, IP6_ADDR_INVALID);
+            } else {
+                netif_ip6_addr_set(netif, ii, ip_2_ip6(&(ip6_addr[ii])));
+                netif_ip6_addr_set_state(netif, ii, IP6_ADDR_TENTATIVE);
+                netif_ip6_addr_set_valid_life(netif, ii, IP6_ADDR_LIFE_STATIC);
+            }
+        }
+    } else {
+        if (data->ip6_mode == MMIPAL_IP6_STATIC) {
+            for (ii = 0; ii < LWIP_IPV6_NUM_ADDRESSES; ii++) {
+                netif_ip6_addr_set(netif, ii, IP6_ADDR_ANY6);
+                netif_ip6_addr_set_state(netif, ii, IP6_ADDR_INVALID);
+            }
+        }
+        netif_set_ip6_autoconfig_enabled(netif, 1);
+        netif_create_ip6_linklocal_address(netif, 1);
+        data->ip6_mode = MMIPAL_IP6_AUTOCONFIG;
+    }
+
+    if (config->ip6_mode == MMIPAL_IP6_DHCP6_STATELESS)
+#if LWIP_IPV6_DHCP6
+    {
+        result = dhcp6_enable_stateless(netif);
+        LWIP_ASSERT("Stateless DHCP6 start error", result == ERR_OK);
+        data->ip6_mode = MMIPAL_IP6_DHCP6_STATELESS;
+    } else {
+        dhcp6_disable(netif);
+    }
+#else
+    {
+        printf("LWIP_IPV6_DHCP6 is not enabled\n");
+    }
+#endif
+
+    UNLOCK_TCPIP_CORE();
+    return MMIPAL_SUCCESS;
+}
+
+#else
+enum mmipal_status mmipal_get_ip6_config(struct mmipal_ip6_config *config)
+{
+    MM_UNUSED(config);
+    LWIP_ASSERT("IPv6 not enabled", false);
+    return MMIPAL_NOT_SUPPORTED;
+}
+
+enum mmipal_status mmipal_set_ip6_config(const struct mmipal_ip6_config *config)
+{
+    MM_UNUSED(config);
+    LWIP_ASSERT("IPv6 not enabled", false);
+    return MMIPAL_NOT_SUPPORTED;
+}
+
+#endif
+
+static bool mmipal_link_status_check(struct netif *netif)
+{
+    bool ip4_addr_check = true;
+
+#if LWIP_IPV4
+    ip4_addr_check = !ip_addr_isany(&(netif->ip_addr));
+#endif
+
+    return ip4_addr_check && netif_is_link_up(netif);
+}
+
+/** Handler for @c netif status callbacks from LWIP. */
+static void netif_status_callback(struct netif *netif)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    enum mmipal_link_state new_link_state = MMIPAL_LINK_DOWN;
+
+#if LWIP_IPV4
+    if (data->ip4_mode == MMIPAL_DHCP_OFFLOAD) {
+        /* Initialize DHCP offload on link up */
+        if (mmwlan_enable_dhcp_offload(mmipal_dhcp_lease_updated, NULL) != MMWLAN_SUCCESS) {
+            printf("Failed to enable DHCP offload!\n");
+        }
+
+        if (!data->dhcp_offload_init_complete) {
+            /* This just prevents a spurious 'Link Up' message on very first call */
+            return;
+        }
+    }
+#endif
+
+    if (mmipal_link_status_check(netif)) {
+        new_link_state = MMIPAL_LINK_UP;
+    }
+
+    if (data->ip_link_state != new_link_state) {
+        data->ip_link_state = new_link_state;
+
+        if (data->link_status_callback || data->ext_link_status_callback) {
+            struct mmipal_link_status link_status;
+            memset(&link_status, 0, sizeof(link_status));
+            link_status.link_state = data->ip_link_state;
+
+#if LWIP_IPV4
+            char *result = ipaddr_ntoa_r(&netif->ip_addr, link_status.ip_addr, sizeof(link_status.ip_addr));
+            LWIP_ASSERT("IP buf too short", result != NULL);
+
+            result = ipaddr_ntoa_r(&netif->netmask, link_status.netmask, sizeof(link_status.netmask));
+            LWIP_ASSERT("IP buf too short", result != NULL);
+
+            result = ipaddr_ntoa_r(&netif->gw, link_status.gateway, sizeof(link_status.gateway));
+            LWIP_ASSERT("IP buf too short", result != NULL);
+
+            if (data->ip_link_state == MMIPAL_LINK_UP) {
+                /* Check if ARP response offload feature is enabled */
+                if (data->offload_arp_response) {
+                    mmwlan_enable_arp_response_offload(ip4_addr_get_u32(netif_ip4_addr(netif)));
+                }
+
+                /* Check if ARP refresh offload feature is enabled */
+                if (data->offload_arp_refresh_s > 0) {
+                    mmwlan_enable_arp_refresh_offload(data->offload_arp_refresh_s, ip4_addr_get_u32(netif_ip4_gw(netif)), true);
+                }
+            }
+#endif
+            if (data->link_status_callback) {
+                data->link_status_callback(&link_status);
+            }
+            if (data->ext_link_status_callback) {
+                data->ext_link_status_callback(&link_status, data->ext_link_status_callback_arg);
+            }
+        }
+    }
+}
+
+void mmipal_set_link_status_callback(mmipal_link_status_cb_fn_t fn)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    data->link_status_callback = fn;
+}
+
+void mmipal_set_ext_link_status_callback(mmipal_ext_link_status_cb_fn_t fn, void *arg)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    data->ext_link_status_callback = fn;
+    data->ext_link_status_callback_arg = arg;
+}
+
+static volatile bool tcpip_init_done = false;
+
+struct lwip_init_args {
+    enum mmipal_addr_mode mode;
+    enum mmipal_ip6_addr_mode ip6_mode;
+    ip_addr_t ip_addr;
+    ip_addr_t netmask;
+    ip_addr_t gateway_addr;
+    ip_addr_t ip6_addr;
+};
+
+static void tcpip_init_done_handler(void *arg)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    struct netif *netif = &data->lwip_mmnetif;
+    struct lwip_init_args *args = (struct lwip_init_args *)arg;
+
+    netif_add_noaddr(netif, NULL, mmnetif_init, tcpip_input);
+    netif_set_default(netif);
+    netif_set_up(netif);
+
+#if LWIP_IPV4
+    err_t result;
+    data->ip4_mode = args->mode;
+    if (args->mode == MMIPAL_DHCP) {
+        result = dhcp_start(netif);
+        LWIP_ASSERT("DHCP start error", result == ERR_OK);
+    } else if (args->mode == MMIPAL_STATIC) {
+        netif_set_addr(netif, ip_2_ip4(&(args->ip_addr)), ip_2_ip4(&(args->netmask)), ip_2_ip4(&(args->gateway_addr)));
+    }
+#endif
+
+    netif_set_link_callback(netif, netif_status_callback);
+    netif_set_status_callback(netif, netif_status_callback);
+
+#if LWIP_IPV6
+    err_t result6;
+    data->ip6_mode = args->ip6_mode;
+    if (args->ip6_mode == MMIPAL_IP6_STATIC) {
+        netif_ip6_addr_set(netif, 0, ip_2_ip6(&(args->ip6_addr)));
+        netif_ip6_addr_set_state(netif, 0, IP6_ADDR_TENTATIVE);
+    } else if (data->ip6_mode == MMIPAL_IP6_AUTOCONFIG) {
+        netif_set_ip6_autoconfig_enabled(netif, 1);
+        netif_create_ip6_linklocal_address(netif, 1);
+    } else if (data->ip6_mode == MMIPAL_IP6_DHCP6_STATELESS)
+#if LWIP_IPV6_DHCP6
+    {
+        result6 = dhcp6_enable_stateless(netif);
+        LWIP_ASSERT("Stateless DHCP6 start error", result6 == ERR_OK);
+    }
+#else
+    {
+        printf("LWIP_IPV6_DHCP6 is not enabled\n");
+    }
+#endif
+#endif
+
+    mmosal_free(args);
+
+    tcpip_init_done = true;
+}
+
+enum mmipal_status mmipal_init(const struct mmipal_init_args *args)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    enum mmipal_status status = MMIPAL_INVALID_ARGUMENT;
+    int result;
+
+    struct lwip_init_args *lwip_args = (struct lwip_init_args *)mmosal_malloc(sizeof(*lwip_args));
+    if (lwip_args == NULL) {
+        printf("malloc failure\n");
+        return MMIPAL_NO_MEM;
+    }
+
+    memset(lwip_args, 0, sizeof(*lwip_args));
+    lwip_args->mode = args->mode;
+    lwip_args->ip6_mode = args->ip6_mode;
+
+    data->link_status_callback = NULL;
+
+    data->offload_arp_response = args->offload_arp_response;
+    data->offload_arp_refresh_s = args->offload_arp_refresh_s;
+
+    /* Validate arguments */
+#if LWIP_IPV4
+    switch (args->mode) {
+    case MMIPAL_DISABLED:
+        printf("%s mode not supported\n", "DISABLED");
+        goto exit;
+
+    case MMIPAL_DHCP_OFFLOAD:
+    case MMIPAL_STATIC:
+        result = ipaddr_aton(args->ip_addr, &lwip_args->ip_addr);
+        if (!result) {
+            goto exit;
+        }
+        result = ipaddr_aton(args->netmask, &lwip_args->netmask);
+        if (!result) {
+            goto exit;
+        }
+        result = ipaddr_aton(args->gateway_addr, &lwip_args->gateway_addr);
+        if (!result) {
+            goto exit;
+        }
+
+        if (ip_addr_isany_val(lwip_args->ip_addr)) {
+            printf("IP address not specified\n");
+            goto exit;
+        }
+        break;
+
+    case MMIPAL_DHCP:
+        if (LWIP_DHCP == 0) {
+            printf("DHCP not compiled in\n");
+            goto exit;
+        }
+        break;
+
+    case MMIPAL_AUTOIP:
+        printf("%s mode not supported\n", "AutoIP");
+        break;
+    }
+#endif
+
+#if LWIP_IPV6
+    switch (args->ip6_mode) {
+    case MMIPAL_IP6_DISABLED:
+        break;
+
+    case MMIPAL_IP6_STATIC:
+        result = ipaddr_aton(args->ip6_addr, &lwip_args->ip6_addr);
+        if (!result) {
+            goto exit;
+        }
+
+        if (ip_addr_isany_val(lwip_args->ip6_addr)) {
+            printf("IP address not specified\n");
+            goto exit;
+        }
+        break;
+
+    case MMIPAL_IP6_AUTOCONFIG:
+        if (LWIP_IPV6_AUTOCONFIG == 0) {
+            printf("AUTOCONFIG not compiled in\n");
+            goto exit;
+        }
+        break;
+
+    case MMIPAL_IP6_DHCP6_STATELESS:
+        if (LWIP_IPV6_DHCP6_STATELESS == 0) {
+            printf("DHCP6_STATELESS not compiled in\n");
+            goto exit;
+        }
+        break;
+    }
+#endif
+
+    tcpip_init(tcpip_init_done_handler, lwip_args);
+
+    /* Block until initialisation is complete */
+    while (!tcpip_init_done) {
+        mmosal_task_sleep(10);
+    }
+
+    return MMIPAL_SUCCESS;
+
+exit:
+    mmosal_free(lwip_args);
+    return status;
+}
+
+void mmipal_get_link_packet_counts(uint32_t *tx_packets, uint32_t *rx_packets)
+{
+#if LWIP_STATS
+    *tx_packets = lwip_stats.link.xmit;
+    *rx_packets = lwip_stats.link.recv;
+#else
+    *tx_packets = 0;
+    *rx_packets = 0;
+#endif
+}
+
+void mmipal_set_tx_qos_tid(uint8_t tid)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    bool ok = tcpip_init_done;
+    MMOSAL_ASSERT(ok);
+    mmnetif_set_tx_qos_tid(&data->lwip_mmnetif, tid);
+}
+
+enum mmipal_link_state mmipal_get_link_state(void)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    return data->ip_link_state;
+}
+
+static enum mmipal_status mmipal_get_local_addr_(ip_addr_t *local_addr, const ip_addr_t *dest_addr)
+{
+    struct mmipal_data *data = mmipal_get_data();
+    struct netif *netif = &data->lwip_mmnetif;
+#if LWIP_IPV6
+    if (IP_IS_V6(dest_addr)) {
+        const ip_addr_t *src_addr = ip6_select_source_address(netif, ip_2_ip6(dest_addr));
+        if (src_addr == NULL) {
+            return MMIPAL_NO_LINK;
+        }
+        ip_addr_copy(*local_addr, *src_addr);
+        return MMIPAL_SUCCESS;
+    } else {
+        MM_UNUSED(dest_addr);
+    }
+#endif
+
+#if LWIP_IPV4
+    if (IP_IS_V4(dest_addr)) {
+        ip_addr_copy(*local_addr, netif->ip_addr);
+        return MMIPAL_SUCCESS;
+    } else {
+        MM_UNUSED(dest_addr);
+    }
+#endif
+
+#if !LWIP_IPV4 && !LWIP_IPV6
+    MM_UNUSED(local_addr);
+    MM_UNUSED(dest_addr);
+#endif
+
+    return MMIPAL_INVALID_ARGUMENT;
+}
+
+enum mmipal_status mmipal_get_local_addr(mmipal_ip_addr_t local_addr, const mmipal_ip_addr_t dest_addr)
+{
+    ip_addr_t lwip_dest_addr;
+    ip_addr_t lwip_local_addr;
+    int ok;
+    enum mmipal_status status;
+
+    if (dest_addr == NULL) {
+        return MMIPAL_INVALID_ARGUMENT;
+    }
+
+    ok = ipaddr_aton(dest_addr, &lwip_dest_addr);
+    if (!ok) {
+        return MMIPAL_INVALID_ARGUMENT;
+    }
+
+    status = mmipal_get_local_addr_(&lwip_local_addr, &lwip_dest_addr);
+    if (status != 0) {
+        return status;
+    }
+
+    if (ipaddr_ntoa_r(&lwip_local_addr, local_addr, MMIPAL_IPADDR_STR_MAXLEN) == NULL) {
+        return MMIPAL_NO_MEM;
+    } else {
+        return MMIPAL_SUCCESS;
+    }
+}
+
+enum mmipal_status mmipal_set_dns_server(uint8_t index, const mmipal_ip_addr_t addr)
+{
+    ip_addr_t dns_addr;
+    int ok;
+
+    if (index >= DNS_MAX_SERVERS) {
+        return MMIPAL_INVALID_ARGUMENT;
+    }
+
+    ok = ipaddr_aton(addr, &dns_addr);
+    if (!ok) {
+        return MMIPAL_INVALID_ARGUMENT;
+    }
+
+    dns_setserver(index, &dns_addr);
+    return MMIPAL_SUCCESS;
+}
+
+enum mmipal_status mmipal_get_dns_server(uint8_t index, mmipal_ip_addr_t addr)
+{
+    const ip_addr_t *dns_addr;
+
+    if (index >= DNS_MAX_SERVERS) {
+        return MMIPAL_INVALID_ARGUMENT;
+    }
+
+    dns_addr = dns_getserver(index);
+
+#if LWIP_IPV4
+    /* dns_getserver() returns ip_addr_any if no address configured. */
+    if (!memcmp(dns_addr, &ip_addr_any, sizeof(*dns_addr))) {
+        addr[0] = '\0';
+        return MMIPAL_SUCCESS;
+    }
+#endif
+
+    if (ipaddr_ntoa_r(dns_addr, addr, MMIPAL_IPADDR_STR_MAXLEN) == NULL) {
+        return MMIPAL_NO_MEM;
+    } else {
+        return MMIPAL_SUCCESS;
+    }
+}
+
+#endif
@@ -0,0 +1,218 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "mmnetif.h"
+#include "mmosal.h"
+#include "mmwlan.h"
+
+#include "lwip/etharp.h"
+#include "lwip/ethip6.h"
+#include "lwip/tcpip.h"
+#if LWIP_SNMP
+#include "lwip/snmp.h"
+#endif
+
+struct netif_state {
+    volatile uint8_t tx_qos_tid;
+};
+
+static struct netif_state *get_netif_state(struct netif *netif)
+{
+    MMOSAL_ASSERT(netif->state != NULL);
+    return (struct netif_state *)netif->state;
+}
+
+/** pbuf wrapper around an mmpkt. */
+struct mmpkt_pbuf_wrapper {
+    struct pbuf_custom p;
+    struct mmpkt *pkt;
+    struct mmpktview *pktview;
+};
+
+LWIP_MEMPOOL_DECLARE(RX_POOL, MMPKTMEM_RX_POOL_N_BLOCKS, sizeof(struct mmpkt_pbuf_wrapper), "mmpkt_rx");
+
+static void mmpkt_pbuf_wrapper_free(struct pbuf *p)
+{
+    struct mmpkt_pbuf_wrapper *pbuf = (struct mmpkt_pbuf_wrapper *)p;
+    if (p == NULL) {
+        return;
+    }
+    mmpkt_close(&pbuf->pktview);
+    mmpkt_release(pbuf->pkt);
+    LWIP_MEMPOOL_FREE(RX_POOL, pbuf);
+}
+
+static void mmnetif_rx(struct mmpkt *rxpkt, void *arg)
+{
+    struct netif *netif = (struct netif *)arg;
+    LWIP_ASSERT("arg NULL", netif != NULL);
+
+    LWIP_DEBUGF(NETIF_DEBUG, ("mmnetif: packet received\n"));
+
+    struct mmpkt_pbuf_wrapper *pbuf = (struct mmpkt_pbuf_wrapper *)LWIP_MEMPOOL_ALLOC(RX_POOL);
+    if (pbuf != NULL) {
+        struct pbuf *p;
+
+        pbuf->p.custom_free_function = mmpkt_pbuf_wrapper_free;
+        pbuf->pkt = rxpkt;
+        pbuf->pktview = mmpkt_open(pbuf->pkt);
+
+        p = pbuf_alloced_custom(PBUF_RAW, mmpkt_get_data_length(pbuf->pktview), PBUF_REF, &pbuf->p,
+                                mmpkt_get_data_start(pbuf->pktview), mmpkt_get_data_length(pbuf->pktview));
+        int ret = tcpip_input(p, netif);
+        if (ret == ERR_OK) {
+            LINK_STATS_INC(link.recv);
+        } else {
+            LWIP_DEBUGF(NETIF_DEBUG, ("mmnetif: input error\n"));
+            pbuf_free(p);
+            LINK_STATS_INC(link.memerr);
+            LINK_STATS_INC(link.drop);
+        }
+    } else {
+        LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_SERIOUS, ("mmnetif: alloc error\n"));
+        LINK_STATS_INC(link.memerr);
+        mmpkt_release(rxpkt);
+    }
+}
+
+static void mmnetif_link_state(enum mmwlan_link_state link_state, void *arg)
+{
+    struct netif *netif = (struct netif *)arg;
+    LWIP_ASSERT("arg NULL", netif != NULL);
+
+    LOCK_TCPIP_CORE();
+    if (link_state == MMWLAN_LINK_DOWN) {
+        LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_ALL, ("mmnetif: link down\n"));
+        /* Note: we cast netif_set_link_down to tcpip_callback_fn since the tcpip_callback_fn
+         * has a "void *" parameter and netif_set_link_down has "struct netif *". */
+        err_t err = tcpip_callback_with_block((tcpip_callback_fn)netif_set_link_down, netif, 0);
+        LWIP_ASSERT("sched callback failed", err == ERR_OK);
+    } else {
+        LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_ALL, ("mmnetif: link up\n"));
+        /* Note: we cast netif_set_link_down to tcpip_callback_fn since the tcpip_callback_fn
+         * has a "void *" parameter and netif_set_link_down has "struct netif *". */
+        err_t err = tcpip_callback_with_block((tcpip_callback_fn)netif_set_link_up, netif, 0);
+        LWIP_ASSERT("sched callback failed", err == ERR_OK);
+    }
+    UNLOCK_TCPIP_CORE();
+}
+
+static err_t mmnetif_tx(struct netif *netif, struct pbuf *p)
+{
+    struct mmpkt *pkt;
+    struct mmpktview *pktview;
+    enum mmwlan_status status;
+    struct pbuf *walk;
+    struct mmwlan_tx_metadata metadata = {
+        .tid = get_netif_state(netif)->tx_qos_tid,
+    };
+
+    status = mmwlan_tx_wait_until_ready(1000);
+    if (status != MMWLAN_SUCCESS) {
+        LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_SERIOUS, ("mmnetif: transmit blocked\n"));
+        LINK_STATS_INC(link.drop);
+        return ERR_BUF;
+    }
+
+    pkt = mmwlan_alloc_mmpkt_for_tx(p->tot_len, metadata.tid);
+    if (pkt == NULL) {
+        LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_SERIOUS, ("mmnetif: allocation failure\n"));
+        LINK_STATS_INC(link.memerr);
+        return ERR_MEM;
+    }
+    pktview = mmpkt_open(pkt);
+    for (walk = p; walk != NULL; walk = walk->next) {
+        mmpkt_append_data(pktview, (const uint8_t *)walk->payload, walk->len);
+    }
+    mmpkt_close(&pktview);
+
+    status = mmwlan_tx_pkt(pkt, &metadata);
+    if (status != MMWLAN_SUCCESS) {
+        LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_SERIOUS, ("mmnetif: error sending packet\n"));
+        LINK_STATS_INC(link.drop);
+        return ERR_BUF;
+    }
+
+    LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_ALL, ("mmnetif: packet sent\n"));
+    LINK_STATS_INC(link.xmit);
+    return ERR_OK;
+}
+
+err_t mmnetif_init(struct netif *netif)
+{
+    static bool initialised = false;
+    if (initialised) {
+        return ERR_IF;
+    }
+
+    LWIP_MEMPOOL_INIT(RX_POOL);
+
+    LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_ALL, ("mmnetif: initialising mmnetif\n"));
+
+#if LWIP_SNMP
+    NETIF_INIT_SNMP(netif, snmp_ifType_ethernet_csmacd, 1000000UL);
+#endif
+
+    enum mmwlan_status status;
+
+    /* Boot the transceiver so that we can read the MAC address. */
+    struct mmwlan_boot_args boot_args = MMWLAN_BOOT_ARGS_INIT;
+    status = mmwlan_boot(&boot_args);
+    if (status != MMWLAN_SUCCESS) {
+        LWIP_DEBUGF(NETIF_DEBUG | LWIP_DBG_LEVEL_SEVERE, ("mmwlan_boot failed with code %d\n", status));
+    }
+    MMOSAL_ASSERT(status == MMWLAN_SUCCESS);
+
+    /* Set MAC hardware address */
+    netif->hwaddr_len = MMWLAN_MAC_ADDR_LEN;
+    status = mmwlan_get_mac_addr(netif->hwaddr);
+    MMOSAL_ASSERT(status == MMWLAN_SUCCESS);
+
+    netif->mtu = 1500;
+#if LWIP_IPV4 && !LWIP_IPV6
+    netif->flags |= NETIF_FLAG_BROADCAST | NETIF_FLAG_ETHARP | NETIF_FLAG_IGMP;
+#else
+    netif->flags |= NETIF_FLAG_BROADCAST | NETIF_FLAG_ETHARP | NETIF_FLAG_IGMP | NETIF_FLAG_MLD6;
+#endif
+
+    netif->state = NULL;
+    netif->name[0] = 'M';
+    netif->name[1] = 'M';
+
+#if LWIP_IPV4
+    netif->output = etharp_output;
+#endif
+#if LWIP_IPV6
+    netif->output_ip6 = ethip6_output;
+#endif
+    netif->linkoutput = mmnetif_tx;
+
+    struct netif_state *state = (struct netif_state *)mmosal_malloc(sizeof(*state));
+    MMOSAL_ASSERT(state != NULL);
+    state->tx_qos_tid = MMWLAN_TX_DEFAULT_QOS_TID;
+    netif->state = state;
+
+    status = mmwlan_register_rx_pkt_cb(mmnetif_rx, netif);
+    MMOSAL_ASSERT(status == MMWLAN_SUCCESS);
+    status = mmwlan_register_link_state_cb(mmnetif_link_state, netif);
+    MMOSAL_ASSERT(status == MMWLAN_SUCCESS);
+
+    printf("Morse LwIP interface initialised. MAC address %02x:%02x:%02x:%02x:%02x:%02x\n", netif->hwaddr[0], netif->hwaddr[1],
+           netif->hwaddr[2], netif->hwaddr[3], netif->hwaddr[4], netif->hwaddr[5]);
+
+    initialised = true;
+
+    return ERR_OK;
+}
+
+void mmnetif_set_tx_qos_tid(struct netif *netif, uint8_t tid)
+{
+    MMOSAL_ASSERT(tid <= MMWLAN_MAX_QOS_TID);
+    get_netif_state(netif)->tx_qos_tid = tid;
+}
+
+#endif
@@ -0,0 +1,29 @@
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "lwip/err.h"
+#include "lwip/netif.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Initializer for the Morse Micro network interface */
+err_t mmnetif_init(struct netif *netif);
+
+/**
+ * Configure the QoS TID for the @c netif. QoS data will be sent using this TID.
+ *
+ * @param netif The @c netif to configure.
+ * @param tid   The TID value to set.
+ */
+void mmnetif_set_tx_qos_tid(struct netif *netif, uint8_t tid);
+
+#ifdef __cplusplus
+}
+#endif
@@ -0,0 +1,563 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "esp_debug_helpers.h"
+#include "esp_private/startup_internal.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/queue.h"
+#include "freertos/semphr.h"
+#include "freertos/task.h"
+#include "freertos/timers.h"
+#include "rom/ets_sys.h"
+
+#include "mmhal.h"
+#include "mmosal.h"
+
+/* --------------------------------------------------------------------------------------------- */
+
+/** Maximum number of failure records to store (must be a power of 2). */
+#define MAX_FAILURE_RECORDS 4
+
+/** Fast implementation of _x % _m where _m is a power of 2. */
+#define FAST_MOD(_x, _m) ((_x) & ((_m)-1))
+
+/** Duration to delay before resetting the device on assert. */
+#define DELAY_BEFORE_RESET_MS 1000
+
+/** Data structure for assertion information to be preserved. */
+struct mmosal_preserved_failure_info {
+    /** Magic number, to check if the info is valid. */
+    uint32_t magic;
+
+    /** Number of failures recorded. */
+    uint32_t failure_count;
+
+    /** Number of most recently displayed failure. */
+    uint32_t displayed_failure_count;
+
+    /** Preserved information from the most recent failure(s). */
+    struct mmosal_failure_info info[MAX_FAILURE_RECORDS];
+};
+
+/** Magic number to put in @c mmosal_assert_info.magic to indicate that the assertion info
+ *  is valid. */
+#define ASSERT_INFO_MAGIC (0xabcd1234)
+
+/* Persistent assertion info. Linker script should put this into memory that is not
+ * zeroed on boot. Be careful to update linker script if renaming. */
+struct mmosal_preserved_failure_info preserved_failure_info __attribute__((section(".noinit")));
+
+void mmosal_log_failure_info(const struct mmosal_failure_info *info)
+{
+    uint32_t record_num;
+
+    if (preserved_failure_info.magic != ASSERT_INFO_MAGIC) {
+        preserved_failure_info.failure_count = 0;
+        preserved_failure_info.displayed_failure_count = 0;
+    }
+
+    preserved_failure_info.magic = ASSERT_INFO_MAGIC;
+    record_num = FAST_MOD(preserved_failure_info.failure_count, MAX_FAILURE_RECORDS);
+    preserved_failure_info.failure_count++;
+    memcpy(&preserved_failure_info.info[record_num], info, sizeof(*info));
+}
+
+static void mmosal_dump_failure_info(void)
+{
+    unsigned first_failure_num = preserved_failure_info.displayed_failure_count;
+    unsigned new_failure_count = preserved_failure_info.failure_count - preserved_failure_info.displayed_failure_count;
+    unsigned failure_offset;
+
+    if (new_failure_count >= MAX_FAILURE_RECORDS) {
+        first_failure_num = FAST_MOD(preserved_failure_info.failure_count, MAX_FAILURE_RECORDS);
+        new_failure_count = MAX_FAILURE_RECORDS;
+    }
+
+    for (failure_offset = 0; failure_offset < new_failure_count; failure_offset++) {
+        unsigned ii;
+        unsigned idx = FAST_MOD(first_failure_num + failure_offset, MAX_FAILURE_RECORDS);
+        struct mmosal_failure_info *info = &preserved_failure_info.info[idx];
+
+        ets_printf("Failure %u logged at pc 0x%08lx, lr 0x%08lx, line %ld in %08lx\n", first_failure_num + failure_offset,
+                   info->pc, info->lr, info->line, info->fileid);
+
+        for (ii = 0; ii < sizeof(info->platform_info) / sizeof(info->platform_info[0]); ii++) {
+            ets_printf("    0x%08lx\n", info->platform_info[ii]);
+        }
+    }
+
+    preserved_failure_info.displayed_failure_count = preserved_failure_info.failure_count;
+}
+
+void mmosal_impl_assert(void)
+{
+    ets_printf("MMOSAL Assert, CPU %d (current core) backtrace", xPortGetCoreID());
+    (void)esp_backtrace_print(100);
+#ifdef HALT_ON_ASSERT
+    if (preserved_failure_info.magic == ASSERT_INFO_MAGIC) {
+        mmosal_dump_failure_info();
+    }
+    mmosal_disable_interrupts();
+    mmhal_log_flush();
+    MMPORT_BREAKPOINT();
+#else
+    mmosal_task_sleep(DELAY_BEFORE_RESET_MS);
+    mmhal_reset();
+#endif
+    while (1) {
+    }
+}
+
+/* Function to be called as part of the secondary initialization. See [System
+ * Initialization](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/startup.html#system-initialization)
+ * for more information. */
+ESP_SYSTEM_INIT_FN(mmosal_dump_failure_info, BIT(0), 999)
+{
+    if (preserved_failure_info.magic == ASSERT_INFO_MAGIC) {
+        mmosal_dump_failure_info();
+    }
+    return ESP_OK;
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+void *mmosal_malloc_(size_t size)
+{
+    return pvPortMalloc(size);
+}
+
+#ifdef MMOSAL_TRACK_ALLOCATIONS
+void *mmosal_malloc_dbg(size_t size, const char *name, unsigned line_number)
+{
+    return pvPortMalloc_dbg(size, name, line_number);
+}
+#else
+void *mmosal_malloc_dbg(size_t size, const char *name, unsigned line_number)
+{
+    (void)name;
+    (void)line_number;
+    return pvPortMalloc(size);
+}
+#endif
+
+void mmosal_free(void *p)
+{
+    vPortFree(p);
+}
+
+void *mmosal_realloc(void *ptr, size_t size)
+{
+    return realloc(ptr, size);
+}
+
+void *mmosal_calloc(size_t nitems, size_t size)
+{
+    void *ptr = pvPortMalloc(nitems * size);
+    if (ptr == NULL) {
+        return NULL;
+    }
+
+    memset(ptr, 0, nitems * size);
+    return ptr;
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+struct mmosal_task_arg {
+    mmosal_task_fn_t task_fn;
+    void *task_fn_arg;
+};
+
+void mmosal_task_main(void *arg)
+{
+    struct mmosal_task_arg task_arg = *(struct mmosal_task_arg *)arg;
+    mmosal_free(arg);
+    task_arg.task_fn(task_arg.task_fn_arg);
+    mmosal_task_delete(NULL);
+}
+
+struct mmosal_task *mmosal_task_create(mmosal_task_fn_t task_fn, void *argument, enum mmosal_task_priority priority,
+                                       unsigned stack_size_u32, const char *name)
+{
+    TaskHandle_t handle;
+    UBaseType_t freertos_priority = tskIDLE_PRIORITY + priority;
+
+    struct mmosal_task_arg *task_arg = (struct mmosal_task_arg *)mmosal_malloc(sizeof(*task_arg));
+    if (task_arg == NULL) {
+        return NULL;
+    }
+    task_arg->task_fn = task_fn;
+    task_arg->task_fn_arg = argument;
+
+    BaseType_t result = xTaskCreate(mmosal_task_main, name, stack_size_u32 * 4, task_arg, freertos_priority, &handle);
+    if (result == pdFAIL) {
+        mmosal_free(task_arg);
+        return NULL;
+    }
+
+    return (struct mmosal_task *)handle;
+}
+
+void mmosal_task_delete(struct mmosal_task *task)
+{
+    vTaskDelete((TaskHandle_t)task);
+}
+
+/*
+ * Warning: this function should not be used since eTaskGetState() is not a reliable
+ * means of testing whether a task has completed.
+ *
+ * This function will be removed in future.
+ */
+void mmosal_task_join(struct mmosal_task *task)
+{
+    while (eTaskGetState((TaskHandle_t)task) != eDeleted) {
+        mmosal_task_sleep(10);
+    }
+}
+
+struct mmosal_task *mmosal_task_get_active(void)
+{
+    return (struct mmosal_task *)xTaskGetCurrentTaskHandle();
+}
+
+void mmosal_task_yield(void)
+{
+    taskYIELD();
+}
+
+void mmosal_task_sleep(uint32_t duration_ms)
+{
+    vTaskDelay(duration_ms / portTICK_PERIOD_MS);
+}
+
+static portMUX_TYPE task_spinlock = portMUX_INITIALIZER_UNLOCKED;
+
+void mmosal_task_enter_critical(void)
+{
+    taskENTER_CRITICAL(&task_spinlock);
+}
+
+void mmosal_task_exit_critical(void)
+{
+    taskEXIT_CRITICAL(&task_spinlock);
+}
+
+void mmosal_disable_interrupts(void)
+{
+    taskDISABLE_INTERRUPTS();
+}
+
+void mmosal_enable_interrupts(void)
+{
+    taskENABLE_INTERRUPTS();
+}
+
+const char *mmosal_task_name(void)
+{
+    TaskHandle_t t = xTaskGetCurrentTaskHandle();
+    return pcTaskGetName(t);
+}
+
+bool mmosal_task_wait_for_notification(uint32_t timeout_ms)
+{
+    TickType_t wait = portMAX_DELAY;
+    if (timeout_ms < UINT32_MAX) {
+        wait = pdMS_TO_TICKS(timeout_ms);
+    }
+    uint32_t ret = ulTaskNotifyTake(pdTRUE, /* Act as binary semaphore */
+                                    wait);
+    return (ret != 0);
+}
+
+void mmosal_task_notify(struct mmosal_task *task)
+{
+    xTaskNotifyGive((TaskHandle_t)task);
+}
+
+void mmosal_task_notify_from_isr(struct mmosal_task *task)
+{
+    BaseType_t higher_priority_task_woken = pdFALSE;
+    vTaskNotifyGiveFromISR((TaskHandle_t)task, &higher_priority_task_woken);
+    portYIELD_FROM_ISR(higher_priority_task_woken);
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+struct mmosal_mutex *mmosal_mutex_create(const char *name)
+{
+    struct mmosal_mutex *mutex = (struct mmosal_mutex *)xSemaphoreCreateMutex();
+#if (configUSE_TRACE_FACILITY == 1) && defined(ENABLE_TRACEALYZER) && ENABLE_TRACEALYZER
+    if (name != NULL) {
+        vTraceSetMutexName(mutex, name);
+    }
+#else
+    (void)name;
+#endif
+    return mutex;
+}
+
+void mmosal_mutex_delete(struct mmosal_mutex *mutex)
+{
+    if (mutex != NULL) {
+        vQueueDelete((SemaphoreHandle_t)mutex);
+    }
+}
+
+bool mmosal_mutex_get(struct mmosal_mutex *mutex, uint32_t timeout_ms)
+{
+    uint32_t timeout_ticks = portMAX_DELAY;
+    if (timeout_ms != UINT32_MAX) {
+        timeout_ticks = timeout_ms / portTICK_PERIOD_MS;
+    }
+    return (xSemaphoreTake((SemaphoreHandle_t)mutex, timeout_ticks) == pdPASS);
+}
+
+bool mmosal_mutex_release(struct mmosal_mutex *mutex)
+{
+    return (xSemaphoreGive((SemaphoreHandle_t)mutex) == pdPASS);
+}
+
+bool mmosal_mutex_is_held_by_active_task(struct mmosal_mutex *mutex)
+{
+    return xSemaphoreGetMutexHolder((SemaphoreHandle_t)mutex) == xTaskGetCurrentTaskHandle();
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+struct mmosal_sem *mmosal_sem_create(unsigned max_count, unsigned initial_count, const char *name)
+{
+    struct mmosal_sem *sem = (struct mmosal_sem *)xSemaphoreCreateCounting(max_count, initial_count);
+#if (configUSE_TRACE_FACILITY == 1) && defined(ENABLE_TRACEALYZER) && ENABLE_TRACEALYZER
+    if (name != NULL) {
+        vTraceSetSemaphoreName(sem, name);
+    }
+#else
+    (void)name;
+#endif
+    return sem;
+}
+
+void mmosal_sem_delete(struct mmosal_sem *sem)
+{
+    vQueueDelete((SemaphoreHandle_t)sem);
+}
+
+bool mmosal_sem_give(struct mmosal_sem *sem)
+{
+    return xSemaphoreGive((SemaphoreHandle_t)sem);
+}
+
+bool mmosal_sem_give_from_isr(struct mmosal_sem *sem)
+{
+    BaseType_t task_woken = false;
+    BaseType_t ret = xSemaphoreGiveFromISR((SemaphoreHandle_t)sem, &task_woken);
+    if (ret == pdPASS) {
+        portYIELD_FROM_ISR(task_woken);
+        return true;
+    } else {
+        return false;
+    }
+}
+
+bool mmosal_sem_wait(struct mmosal_sem *sem, uint32_t timeout_ms)
+{
+    uint32_t timeout_ticks = portMAX_DELAY;
+    if (timeout_ms != UINT32_MAX) {
+        timeout_ticks = timeout_ms / portTICK_PERIOD_MS;
+    }
+    return (xSemaphoreTake((SemaphoreHandle_t)sem, timeout_ticks) == pdPASS);
+}
+
+uint32_t mmosal_sem_get_count(struct mmosal_sem *sem)
+{
+    return uxSemaphoreGetCount((SemaphoreHandle_t)sem);
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+struct mmosal_semb *mmosal_semb_create(const char *name)
+{
+    struct mmosal_semb *semb = (struct mmosal_semb *)xSemaphoreCreateBinary();
+#if (configUSE_TRACE_FACILITY == 1) && defined(ENABLE_TRACEALYZER) && ENABLE_TRACEALYZER
+    if (name != NULL) {
+        vTraceSetSemaphoreName(semb, name);
+    }
+#else
+    (void)name;
+#endif
+    return semb;
+}
+
+void mmosal_semb_delete(struct mmosal_semb *semb)
+{
+    vQueueDelete((SemaphoreHandle_t)semb);
+}
+
+bool mmosal_semb_give(struct mmosal_semb *semb)
+{
+    return (xSemaphoreGive((SemaphoreHandle_t)semb) == pdPASS);
+}
+
+bool mmosal_semb_give_from_isr(struct mmosal_semb *semb)
+{
+    BaseType_t task_woken = pdFALSE;
+    BaseType_t ret = xSemaphoreGiveFromISR((SemaphoreHandle_t)semb, &task_woken);
+    if (ret == pdPASS) {
+        portYIELD_FROM_ISR(task_woken);
+        return true;
+    } else {
+        return false;
+    }
+}
+
+bool mmosal_semb_wait(struct mmosal_semb *semb, uint32_t timeout_ms)
+{
+    uint32_t timeout_ticks = portMAX_DELAY;
+    if (timeout_ms != UINT32_MAX) {
+        timeout_ticks = timeout_ms / portTICK_PERIOD_MS;
+    }
+    return (xSemaphoreTake((SemaphoreHandle_t)semb, timeout_ticks) == pdPASS);
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+struct mmosal_queue *mmosal_queue_create(size_t num_items, size_t item_size, const char *name)
+{
+    struct mmosal_queue *queue = (struct mmosal_queue *)xQueueCreate(num_items, item_size);
+#if (configUSE_TRACE_FACILITY == 1) && defined(ENABLE_TRACEALYZER) && ENABLE_TRACEALYZER
+    if (name != NULL) {
+        vTraceSetQueueName(queue, name);
+    }
+#else
+    (void)name;
+#endif
+    return queue;
+}
+
+void mmosal_queue_delete(struct mmosal_queue *queue)
+{
+    vQueueDelete((SemaphoreHandle_t)queue);
+}
+
+bool mmosal_queue_pop(struct mmosal_queue *queue, void *item, uint32_t timeout_ms)
+{
+    uint32_t timeout_ticks = portMAX_DELAY;
+    if (timeout_ms != UINT32_MAX) {
+        timeout_ticks = timeout_ms / portTICK_PERIOD_MS;
+    }
+    return (xQueueReceive((SemaphoreHandle_t)queue, item, timeout_ticks) == pdPASS);
+}
+
+bool mmosal_queue_push(struct mmosal_queue *queue, const void *item, uint32_t timeout_ms)
+{
+    uint32_t timeout_ticks = portMAX_DELAY;
+    if (timeout_ms != UINT32_MAX) {
+        timeout_ticks = timeout_ms / portTICK_PERIOD_MS;
+    }
+    return (xQueueSendToBack((SemaphoreHandle_t)queue, item, timeout_ticks) == pdPASS);
+}
+
+bool mmosal_queue_pop_from_isr(struct mmosal_queue *queue, void *item)
+{
+    BaseType_t task_woken = pdFALSE;
+    if (xQueueReceiveFromISR((SemaphoreHandle_t)queue, item, &task_woken) == pdTRUE) {
+        portYIELD_FROM_ISR(task_woken);
+        return true;
+    } else {
+        return false;
+    }
+}
+
+bool mmosal_queue_push_from_isr(struct mmosal_queue *queue, const void *item)
+{
+    BaseType_t task_woken = pdFALSE;
+    if (xQueueSendToBackFromISR((SemaphoreHandle_t)queue, item, &task_woken) == pdTRUE) {
+        portYIELD_FROM_ISR(task_woken);
+        return true;
+    } else {
+        return false;
+    }
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+uint32_t mmosal_get_time_ms(void)
+{
+    return xTaskGetTickCount() * portTICK_PERIOD_MS;
+}
+
+uint32_t mmosal_get_time_ticks(void)
+{
+    return xTaskGetTickCount();
+}
+
+uint32_t mmosal_ticks_per_second(void)
+{
+    return portTICK_PERIOD_MS * 1000;
+}
+
+/* --------------------------------------------------------------------------------------------- */
+
+struct mmosal_timer *mmosal_timer_create(const char *name, uint32_t timer_period, bool auto_reload, void *arg,
+                                         timer_callback_t callback)
+{
+    /*
+     * The software timer callback functions execute in the context of a task that is
+     * created automatically when the FreeRTOS scheduler is started. Therefore, it is essential that
+     * software timer callback functions never call FreeRTOS API functions that will result in the
+     * calling task entering the Blocked state. It is ok to call functions such as xQueueReceive(), but
+     * only if the function’s xTicksToWait parameter (which specifies the function’s block time) is set
+     * to 0. It is not ok to call functions such as vTaskDelay(), as calling vTaskDelay() will always
+     * place the calling task into the Blocked state.
+     */
+    return (struct mmosal_timer *)xTimerCreate(name, pdMS_TO_TICKS(timer_period), (UBaseType_t)auto_reload, arg,
+                                               (TimerCallbackFunction_t)callback);
+}
+
+void mmosal_timer_delete(struct mmosal_timer *timer)
+{
+    if (timer != NULL) {
+        BaseType_t ret = xTimerDelete((TimerHandle_t)timer, 0);
+        configASSERT(ret == pdPASS);
+    }
+}
+
+bool mmosal_timer_start(struct mmosal_timer *timer)
+{
+    BaseType_t ret = xTimerStart((TimerHandle_t)timer, 0);
+
+    return (ret == pdPASS);
+}
+
+bool mmosal_timer_stop(struct mmosal_timer *timer)
+{
+    BaseType_t ret = xTimerStop((TimerHandle_t)timer, 0);
+
+    return (ret == pdPASS);
+}
+
+bool mmosal_timer_change_period(struct mmosal_timer *timer, uint32_t new_period)
+{
+    BaseType_t ret = xTimerChangePeriod((TimerHandle_t)timer, pdMS_TO_TICKS(new_period), 0);
+
+    return (ret == pdPASS);
+}
+
+void *mmosal_timer_get_arg(struct mmosal_timer *timer)
+{
+    return pvTimerGetTimerID((TimerHandle_t)timer);
+}
+
+bool mmosal_is_timer_active(struct mmosal_timer *timer)
+{
+    BaseType_t ret = xTimerIsTimerActive((TimerHandle_t)timer);
+
+    return (ret != pdFALSE);
+}
+
+#endif /* USE_MM_IOT_ESP32 */
@@ -0,0 +1,245 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdatomic.h>
+#include <stdint.h>
+
+#include "mmhal.h"
+#include "mmosal.h"
+#include "mmpkt.h"
+#include "mmpkt_list.h"
+#include "mmutils.h"
+
+/* MMPKTMEM_TX_POOL_N_BLOCKS and MMPKTMEM_RX_POOL_N_BLOCKS provide an upper bound on the number
+ * of packets we will allocate in the transmit and receive directions respectively. */
+
+#ifndef MMPKTMEM_TX_POOL_N_BLOCKS
+#error MMPKTMEM_TX_POOL_N_BLOCKS not defined
+#endif
+
+#ifndef MMPKTMEM_RX_POOL_N_BLOCKS
+#error MMPKTMEM_RX_POOL_N_BLOCKS not defined
+#endif
+
+/* Packet pool for data/management frames configuration. */
+#define TX_DATA_POOL_UNPAUSE_THRESHOLD (MMPKTMEM_TX_POOL_N_BLOCKS - 2)
+#define TX_DATA_POOL_PAUSE_THRESHOLD (MMPKTMEM_TX_POOL_N_BLOCKS - 1)
+
+/* Packet pool for commands configuration. */
+#define TX_COMMAND_POOL_BLOCK_SIZE (256)
+#define TX_COMMAND_POOL_N_BLOCKS (2)
+
+#ifndef MMPKT_LOG
+#define MMPKT_LOG(...) printf(__VA_ARGS__)
+#endif
+
+struct pktmem_data {
+    /** Count of allocated tx packets (excluding command pool -- see below). */
+    volatile atomic_int_least32_t tx_data_pool_allocated;
+    /** Boolean tracking whether the data path is currently paused. */
+    volatile atomic_uint_fast8_t tx_data_pool_tx_paused;
+    /** Count of allocated rx packets. */
+    volatile atomic_int_least32_t rx_pool_allocated;
+
+    /** Command pool free (unallocated) packet list. */
+    struct mmpkt_list tx_command_pool_free_list;
+    /** Statically allocated memory for the command pool. */
+    uint8_t tx_command_pool[TX_COMMAND_POOL_BLOCK_SIZE * TX_COMMAND_POOL_N_BLOCKS];
+
+    /** Flow control callback function pointer. */
+    mmhal_wlan_pktmem_tx_flow_control_cb_t tx_flow_control_cb;
+};
+
+static struct pktmem_data pktmem;
+
+void mmhal_wlan_pktmem_init(struct mmhal_wlan_pktmem_init_args *args)
+{
+    unsigned ii;
+
+    memset(&pktmem, 0, sizeof(pktmem));
+
+    pktmem.tx_flow_control_cb = args->tx_flow_control_cb;
+
+    /* Initialize the free (unallocated) packet list of the transmit command pool. */
+    for (ii = 0; ii < TX_COMMAND_POOL_N_BLOCKS; ii++) {
+        size_t offset = TX_COMMAND_POOL_BLOCK_SIZE * ii;
+        mmpkt_list_append(&pktmem.tx_command_pool_free_list, (struct mmpkt *)(pktmem.tx_command_pool + offset));
+    }
+}
+
+void mmhal_wlan_pktmem_deinit(void)
+{
+    size_t ii;
+
+    /* If there is still memory allocated, allow some time for other threads to clean up. */
+    for (ii = 0; ii < 100; ii++) {
+        if ((pktmem.tx_command_pool_free_list.len | pktmem.tx_data_pool_allocated | pktmem.tx_data_pool_allocated) == 0) {
+            break;
+        }
+        mmosal_task_sleep(10);
+    }
+
+    /* Check for memory leaks. */
+    if (pktmem.tx_data_pool_allocated != 0) {
+        MMPKT_LOG("Potential memory leak: %d %s pool allocations at deinit\n", (int)pktmem.tx_data_pool_allocated, "data");
+    }
+
+    if (pktmem.tx_command_pool_free_list.len != TX_COMMAND_POOL_N_BLOCKS) {
+        MMPKT_LOG("Potential memory leak: %d %s pool allocations at deinit\n",
+                  TX_COMMAND_POOL_N_BLOCKS - (int)pktmem.tx_command_pool_free_list.len, "command");
+    }
+}
+
+/*
+ * --------------------------------------------------------------------------------------
+ *     Command pool
+ * --------------------------------------------------------------------------------------
+ */
+
+static void tx_command_reserved_free(void *mmpkt)
+{
+    struct mmpkt *pkt = (struct mmpkt *)mmpkt;
+    MMOSAL_TASK_ENTER_CRITICAL();
+    mmpkt_list_append(&pktmem.tx_command_pool_free_list, pkt);
+    MMOSAL_TASK_EXIT_CRITICAL();
+}
+
+static const struct mmpkt_ops tx_command_pool_ops = {
+    .free_mmpkt = tx_command_reserved_free,
+};
+
+static struct mmpkt *alloc_pkt_from_list(struct mmpkt_list *list, uint32_t pktbufsize, uint32_t space_at_start,
+                                         uint32_t space_at_end, uint32_t metadata_length)
+{
+    struct mmpkt *mmpkt_buf;
+    struct mmpkt *mmpkt;
+
+    MMOSAL_TASK_ENTER_CRITICAL();
+    mmpkt_buf = mmpkt_list_dequeue(list);
+    MMOSAL_TASK_EXIT_CRITICAL();
+
+    if (mmpkt_buf == NULL) {
+        return NULL;
+    }
+
+    mmpkt = mmpkt_init_buf((uint8_t *)mmpkt_buf, pktbufsize, space_at_start, space_at_end, metadata_length, &tx_command_pool_ops);
+    if (mmpkt == NULL) {
+        /* Command was too big for the reserved buffer. Return the reserved buffer. */
+        tx_command_reserved_free(mmpkt_buf);
+    }
+
+    return mmpkt;
+}
+
+static struct mmpkt *command_pool_alloc(uint32_t space_at_start, uint32_t space_at_end, uint32_t metadata_length)
+{
+    return alloc_pkt_from_list(&pktmem.tx_command_pool_free_list, TX_COMMAND_POOL_BLOCK_SIZE, space_at_start, space_at_end,
+                               metadata_length);
+}
+
+/*
+ * --------------------------------------------------------------------------------------
+ *     Data pool
+ * --------------------------------------------------------------------------------------
+ */
+
+static void tx_data_pool_pkt_free(void *mmpkt)
+{
+    atomic_int_least32_t old_value = atomic_fetch_sub(&pktmem.tx_data_pool_allocated, 1);
+    MMOSAL_ASSERT(old_value > 0);
+    mmosal_free(mmpkt);
+
+    if (pktmem.tx_data_pool_allocated < TX_DATA_POOL_UNPAUSE_THRESHOLD) {
+        atomic_uint_fast8_t old_tx_paused = atomic_exchange(&pktmem.tx_data_pool_tx_paused, 0);
+        if (old_tx_paused) {
+            pktmem.tx_flow_control_cb(MMWLAN_TX_READY);
+        }
+    }
+}
+
+static const struct mmpkt_ops tx_data_pool_pkt_ops = {
+    .free_mmpkt = tx_data_pool_pkt_free,
+};
+
+struct mmpkt *mmhal_wlan_alloc_mmpkt_for_tx(uint8_t pkt_class, uint32_t space_at_start, uint32_t space_at_end,
+                                            uint32_t metadata_length)
+{
+    atomic_int_least32_t old_value;
+    struct mmpkt *mmpkt;
+
+    /* For command packets, try allocating from the command pool first. If that fails then
+     * we proceed to allocate from the data pool. */
+    if (pkt_class == MMHAL_WLAN_PKT_COMMAND) {
+        mmpkt = command_pool_alloc(space_at_start, space_at_end, metadata_length);
+        if (mmpkt != NULL) {
+            return mmpkt;
+        }
+    }
+
+    old_value = atomic_fetch_add(&pktmem.tx_data_pool_allocated, 1);
+
+    if (old_value >= MMPKTMEM_TX_POOL_N_BLOCKS) {
+        /* Maximum allocations reached. Do not attempt to increase further. */
+        atomic_fetch_sub(&pktmem.tx_data_pool_allocated, 1);
+        return NULL;
+    }
+
+    mmpkt = mmpkt_alloc_on_heap(space_at_start, space_at_end, metadata_length);
+    if (mmpkt == NULL) {
+        atomic_fetch_sub(&pktmem.tx_data_pool_allocated, 1);
+        return NULL;
+    }
+
+    mmpkt->ops = &tx_data_pool_pkt_ops;
+
+    if (pktmem.tx_data_pool_allocated > TX_DATA_POOL_PAUSE_THRESHOLD) {
+        atomic_uint_fast8_t old_tx_paused = atomic_exchange(&pktmem.tx_data_pool_tx_paused, 1);
+        if (!old_tx_paused) {
+            pktmem.tx_flow_control_cb(MMWLAN_TX_PAUSED);
+        }
+    }
+
+    return mmpkt;
+}
+
+static void rx_pkt_free(void *mmpkt)
+{
+    if (mmpkt != NULL) {
+        atomic_fetch_sub(&pktmem.rx_pool_allocated, 1);
+        mmosal_free(mmpkt);
+    }
+}
+
+static const struct mmpkt_ops mmpkt_rx_ops = {.free_mmpkt = rx_pkt_free};
+
+struct mmpkt *mmhal_wlan_alloc_mmpkt_for_rx(uint32_t capacity, uint32_t metadata_length)
+{
+    atomic_int_least32_t old_value;
+    struct mmpkt *mmpkt;
+
+    old_value = atomic_fetch_add(&pktmem.rx_pool_allocated, 1);
+
+    if (old_value >= MMPKTMEM_RX_POOL_N_BLOCKS) {
+        /* Maximum allocations reached. Do not attempt to increase further. */
+        atomic_fetch_sub(&pktmem.rx_pool_allocated, 1);
+        return NULL;
+    }
+
+    /* For now we do not put an explicit limit on the of packets buffers on the RX path. */
+    mmpkt = mmpkt_alloc_on_heap(0, capacity, metadata_length);
+    if (mmpkt == NULL) {
+        atomic_fetch_sub(&pktmem.rx_pool_allocated, 1);
+        return NULL;
+    }
+
+    /* Override packet ops to use a custom free function that also decrements the
+     * allocation count. */
+    mmpkt->ops = &mmpkt_rx_ops;
+    return mmpkt;
+}
+
+#endif
@@ -0,0 +1,12 @@
+/*
+ * Copyright 2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#define MMPORT_BREAKPOINT() while (1)
+#define MMPORT_GET_LR() (__builtin_return_address(0))
+#define MMPORT_GET_PC(_a) ((_a) = 0) // TODO
+#define MMPORT_MEM_SYNC() __sync_synchronize()
@@ -0,0 +1,301 @@
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @defgroup MMUTILS Morse Micro Utilities
+ *
+ * Utility macros and functions to improve quality of life.
+ *
+ * @{
+ */
+
+#pragma once
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Get the minimum of 2 values.
+ *
+ * Note that this macro is not ideal and should be used with caution. Caveats include:
+ * * The two parameters may be evaluated more than once, so should be constant values that
+ *   do not have side effects. For example, do NOT do `MM_MIN(a++, b)`.
+ * * There are no explicit constraints on types, so be careful of comparing different integer
+ *   types, etc.
+ *
+ * @param _x    The first value to compare.
+ * @param _y    The second value to compare.
+ *
+ * @returns the minimum of @p _x and @p _y.
+ */
+#define MM_MIN(_x, _y) (((_x) < (_y)) ? (_x) : (_y))
+
+/**
+ * Get the maximum of 2 values.
+ *
+ * Note that this macro is not ideal and should be used with caution. Caveats include:
+ * * The two parameters may be evaluated more than once, so should be constant values that
+ *   do not have side effects. For example, do NOT do `MM_MAX(a++, b)`.
+ * * There are no explicit constraints on types, so be careful of comparing different integer
+ *   types, etc.
+ *
+ * @param _x    The first value to compare.
+ * @param _y    The second value to compare.
+ *
+ * @returns the maximum of @p _x and @p _y.
+ */
+#define MM_MAX(_x, _y) (((_x) > (_y)) ? (_x) : (_y))
+
+/**
+ * Round @p x up to the next multiple of @p m (where @p m is a power of 2).
+ *
+ * @warning @p m must be a power of 2.
+ */
+#ifndef MM_FAST_ROUND_UP
+#define MM_FAST_ROUND_UP(x, m) ((((x)-1) | ((m)-1)) + 1)
+#endif
+
+/** Casts the given expression to void to avoid "unused" warnings from the compiler. */
+#define MM_UNUSED(_x) (void)(_x)
+
+/** Tells the compiler to pack the structure. */
+#ifndef MM_PACKED
+#define MM_PACKED __attribute__((packed))
+#endif
+
+/** Used to declare a weak symbol.  */
+#ifndef MM_WEAK
+#define MM_WEAK __attribute__((weak))
+#endif
+
+#ifndef MM_STATIC_ASSERT
+/**
+ * Assertion check that is evaluated at compile time.
+ *
+ * The constant expression, @p _expression, is evaluted at compile time. If zero then
+ * it triggers a compilation error and @p _message is displayed. If non-zero, no code
+ * is emitted.
+ *
+ * @param _expression   Constant expression to evaluate. If zero then a compilation error
+ *                      is triggered.
+ * @param _message      Message to display on error.
+ */
+#define MM_STATIC_ASSERT(_expression, _message) _Static_assert((_expression), _message)
+#endif
+
+/**
+ * Return the number of elements in the given array.
+ *
+ * @param _a    The array to get the element count for. Note that this must be an _array_
+ *              and not a pointer. Beware that array-type function arguments are
+ *              actually treated as pointers by the compiler. Must not be NULL.
+ *
+ * @returns the count of elements in the given array.
+ */
+#define MM_ARRAY_COUNT(_a) (sizeof(_a) / sizeof((_a)[0]))
+
+/**
+ * Convert the least significant 4 bits of the given argument to a character representing their
+ * hexadecimal value.
+ *
+ * For example, for input 0xde this will return 'E', for 0x01 it will return '1'.
+ *
+ * @param nibble    The input nibble (upper 4 bits will be discarded).
+ *
+ * @return The character that represents the hexadecimal value of the lower 4 bits of @p nibble.
+ *         Values greater than 0x09 will be represented with upper case characters.
+ */
+static inline char mm_nibble_to_hex_char(uint8_t nibble)
+{
+    nibble &= 0x0f;
+    if (nibble < 0x0a) {
+        return '0' + nibble;
+    } else {
+        return 'A' + nibble - 0x0a;
+    }
+}
+
+/**
+ * @defgroup MMUTILS_WLAN WLAN Utilities
+ *
+ * Utility macros and functions relating to WLAN.
+ *
+ * @{
+ */
+
+/** Enumeration of Authentication Key Management (AKM) Suite OUIs as BE32 integers. */
+enum mm_akm_suite_oui {
+    /** Open (no security) */
+    MM_AKM_SUITE_NONE = 0,
+    /** Pre-shared key (WFA OUI) */
+    MM_AKM_SUITE_PSK = 0x506f9a02,
+    /** Simultaneous Authentication of Equals (SAE) */
+    MM_AKM_SUITE_SAE = 0x000fac08,
+    /** OWE */
+    MM_AKM_SUITE_OWE = 0x000fac12,
+    /** Another suite not in this enum */
+    MM_AKM_SUITE_OTHER = 1,
+};
+
+/** Enumeration of Cipher Suite OUIs as BE32 integers. */
+enum mm_cipher_suite_oui {
+    /** Open (no security) */
+    MM_CIPHER_SUITE_AES_CCM = 0x000fac04,
+    /** Another cipher suite not in this enum */
+    MM_CIPHER_SUITE_OTHER = 1,
+};
+
+/** Maximum number of pairwise cipher suites our parser will process. */
+#ifndef MM_RSN_INFORMATION_MAX_PAIRWISE_CIPHER_SUITES
+#define MM_RSN_INFORMATION_MAX_PAIRWISE_CIPHER_SUITES (2)
+#endif
+
+/** Maximum number of AKM suites our parser will process. */
+#ifndef MM_RSN_INFORMATION_MAX_AKM_SUITES
+#define MM_RSN_INFORMATION_MAX_AKM_SUITES (2)
+#endif
+
+/** Tag number of the RSN information element, in which we can find security details of the AP. */
+#define MM_RSN_INFORMATION_IE_TYPE (48)
+/** Tag number of the Vendor Specific information element. */
+#define MM_VENDOR_SPECIFIC_IE_TYPE (221)
+
+/** Explicitly defined errno values to obviate the need to include errno.h. MM prefix to
+ *  avoid namespace collision in case errno.h gets included. */
+enum mm_errno {
+    MM_ENOMEM = 12,
+    MM_EFAULT = 14,
+    MM_ENODEV = 19,
+    MM_EINVAL = 22,
+    MM_ETIMEDOUT = 110,
+};
+
+/**
+ * Data structure to represent information extracted from an RSN information element.
+ *
+ * All integers in host order.
+ */
+struct mm_rsn_information {
+    /** The group cipher suite OUI. */
+    uint32_t group_cipher_suite;
+    /** Pairwise cipher suite OUIs. Count given by @c num_pairwise_cipher_suites. */
+    uint32_t pairwise_cipher_suites[MM_RSN_INFORMATION_MAX_PAIRWISE_CIPHER_SUITES];
+    /** AKM suite OUIs. Count given by @c num_akm_suites. */
+    uint32_t akm_suites[MM_RSN_INFORMATION_MAX_AKM_SUITES];
+    /** Number of pairwise cipher suites in @c pairwise_cipher_suites. */
+    uint16_t num_pairwise_cipher_suites;
+    /** Number of AKM suites in @c akm_suites. */
+    uint16_t num_akm_suites;
+    /** Version number of the RSN IE. */
+    uint16_t version;
+    /** RSN Capabilities field of the RSN IE (in host order). */
+    uint16_t rsn_capabilities;
+};
+
+/**
+ * Get the name of the given AKM Suite as a string.
+ *
+ * @param akm_suite_oui     The OUI of the AKM suite as a big endian integer.
+ *
+ * @returns the string representation.
+ */
+const char *mm_akm_suite_to_string(uint32_t akm_suite_oui);
+
+/**
+ * Search a list of Information Elements (IEs) from the given starting offset and find the first
+ * instance of matching the given type.
+ *
+ * @warning A @p search_offset that is not aligned to the start of an IE header will result in
+ *          undefined behaviour.
+ *
+ * @param ies           Buffer containing the information elements.
+ * @param ies_len       Length of @p ies
+ * @param search_offset Offset to start searching from. This **must** point to a IE header.
+ * @param ie_type       The type of the IE to look for.
+ *
+ * @return If the information element is found, the offset of the start of the IE within @p ies; if
+ *         no match is found then -1; if the IE is found but is malformed then -2.
+ */
+int mm_find_ie_from_offset(const uint8_t *ies, uint32_t ies_len, uint32_t search_offset, uint8_t ie_type);
+
+/**
+ * Search a list of Information Elements (IEs) and find the first instance of matching the
+ * given type.
+ *
+ * @param ies       Buffer containing the information elements.
+ * @param ies_len   Length of @p ies
+ * @param ie_type   The type of the IE to look for.
+ *
+ * @return If the information element is found, the offset of the start of the IE within @p ies;
+ *         if no match is found then -1; if the IE is found but is malformed then -2.
+ */
+static inline int mm_find_ie(const uint8_t *ies, uint32_t ies_len, uint8_t ie_type)
+{
+    return mm_find_ie_from_offset(ies, ies_len, 0, ie_type);
+}
+
+/**
+ * Search through the given list of Information Elements (IEs) from the given starting offset to
+ * find the first Vendor Specific IE that matches the given id.
+ *
+ * @warning A @p search_offset that is not aligned to the start of an IE header will result in
+ *          undefined behaviour.
+ *
+ * @param[in] ies           Buffer containing the information elements.
+ * @param[in] ies_len       Length of @p ies
+ * @param[in] search_offset Offset to start searching from. This **must** point to a IE header.
+ * @param[in] id            Buffer containing the IE ID, usually OUI+TYPE.
+ * @param[in] id_len        Length of the ID.
+ *
+ * @return If the information element is found, the offset of the start of the IE within @p ies; if
+ *         no match is found then -1; if the IE is found but is malformed then -2.
+ */
+int mm_find_vendor_specific_ie_from_offset(const uint8_t *ies, uint32_t ies_len, uint32_t search_offset, const uint8_t *id,
+                                           size_t id_len);
+
+/**
+ * Search through the given list of Information Elements (IEs) to find the first Vendor Specific IE
+ * that matches the given id.
+ *
+ * @param[in] ies       Buffer containing the information elements.
+ * @param[in] ies_len   Length of @p ies
+ * @param[in] id        Buffer containing the IE ID, usually OUI+TYPE.
+ * @param[in] id_len    Length of the ID.
+ *
+ * @return If the information element is found, the offset of the start of the IE within @p ies; if
+ *         no match is found then -1; if the IE is found but is malformed then -2.
+ */
+static inline int mm_find_vendor_specific_ie(const uint8_t *ies, uint32_t ies_len, const uint8_t *id, size_t id_len)
+{
+    return mm_find_vendor_specific_ie_from_offset(ies, ies_len, 0, id, id_len);
+}
+
+/**
+ * Search through the given list of information elements to find the RSN IE then parse it
+ * to extract relevant information into an instance of @ref mm_rsn_information.
+ *
+ * @param[in] ies       Buffer containing the information elements.
+ * @param[in] ies_len   Length of @p ies
+ * @param[out] output   Pointer to an instance of @ref mm_rsn_information to receive output.
+ *
+ * @returns -2 on parse error, -1 if the RSN IE was not found, 0 if the RSN IE was found.
+ */
+int mm_parse_rsn_information(const uint8_t *ies, uint32_t ies_len, struct mm_rsn_information *output);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
@@ -0,0 +1,163 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2024 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+
+#include "mmutils.h"
+
+const char *mm_akm_suite_to_string(uint32_t akm_suite_oui)
+{
+    switch (akm_suite_oui) {
+    case MM_AKM_SUITE_NONE:
+        return "None";
+
+    case MM_AKM_SUITE_PSK:
+        return "PSK";
+
+    case MM_AKM_SUITE_SAE:
+        return "SAE";
+
+    case MM_AKM_SUITE_OWE:
+        return "OWE";
+
+    default:
+        return "Other";
+    }
+}
+
+int mm_find_ie_from_offset(const uint8_t *ies, uint32_t ies_len, uint32_t search_offset, uint8_t ie_type)
+{
+    while ((search_offset + 2) <= ies_len) {
+        uint8_t type = ies[search_offset];
+        uint8_t length = ies[search_offset + 1];
+
+        if (type == ie_type) {
+            if ((search_offset + 2 + length) > ies_len) {
+                return -2;
+            }
+            return search_offset;
+        }
+
+        search_offset += 2 + length;
+    }
+
+    return -1;
+}
+
+int mm_find_vendor_specific_ie_from_offset(const uint8_t *ies, uint32_t ies_len, uint32_t search_offset, const uint8_t *id,
+                                           size_t id_len)
+{
+    int offset = 0;
+
+    while ((search_offset + id_len) <= ies_len) {
+        offset = mm_find_ie_from_offset(ies, ies_len, search_offset, MM_VENDOR_SPECIFIC_IE_TYPE);
+        if (offset < 0) {
+            return offset;
+        }
+
+        uint8_t ie_type = ies[offset];
+        uint8_t ie_length = ies[offset + 1];
+        const uint8_t *ie_data = ies + (offset + 2);
+
+        if (ie_type == MM_VENDOR_SPECIFIC_IE_TYPE && id_len <= ie_length && (memcmp(id, ie_data, id_len) == 0)) {
+            if (((uint32_t)offset + 2 + ie_length) > ies_len) {
+                return -2;
+            }
+            return offset;
+        }
+
+        search_offset = 2 + ie_length + (uint32_t)offset;
+    }
+
+    return -1;
+}
+
+int mm_parse_rsn_information(const uint8_t *ies, uint32_t ies_len, struct mm_rsn_information *output)
+{
+    uint8_t length;
+    uint16_t num_pairwise_cipher_suites;
+    uint16_t num_akm_suites;
+    uint16_t ii;
+
+    int offset = mm_find_ie(ies, ies_len, MM_RSN_INFORMATION_IE_TYPE);
+
+    memset(output, 0, sizeof(*output));
+
+    if (offset < 0) {
+        return offset;
+    }
+
+    /* Note that we rely on mm_find_ie() to validate that the IE does not extend past the end
+     * of the given buffer. */
+
+    length = ies[offset + 1];
+    offset += 2;
+
+    if (length < 8) {
+        printf("*WRN* RSN IE too short\n");
+        return -2;
+    }
+
+    /* Skip version field */
+    output->version = ies[offset] | ies[offset + 1] << 8;
+    offset += 2;
+    length -= 2;
+
+    output->group_cipher_suite = ies[offset] << 24 | ies[offset + 1] << 16 | ies[offset + 2] << 8 | ies[offset + 3];
+    offset += 4;
+    length -= 4;
+
+    num_pairwise_cipher_suites = ies[offset] | ies[offset + 1] << 8;
+    offset += 2;
+    length -= 2;
+
+    output->num_pairwise_cipher_suites = num_pairwise_cipher_suites;
+    if (num_pairwise_cipher_suites > MM_RSN_INFORMATION_MAX_PAIRWISE_CIPHER_SUITES) {
+        output->num_pairwise_cipher_suites = MM_RSN_INFORMATION_MAX_PAIRWISE_CIPHER_SUITES;
+    }
+
+    if (length < 4 * num_pairwise_cipher_suites + 2) {
+        printf("*WRN* RSN IE too short\n");
+        return -2;
+    }
+
+    for (ii = 0; ii < num_pairwise_cipher_suites; ii++) {
+        if (ii < output->num_pairwise_cipher_suites) {
+            output->pairwise_cipher_suites[ii] =
+                ies[offset] << 24 | ies[offset + 1] << 16 | ies[offset + 2] << 8 | ies[offset + 3];
+        }
+        offset += 4;
+        length -= 4;
+    }
+
+    num_akm_suites = ies[offset] | ies[offset + 1] << 8;
+    offset += 2;
+    length -= 2;
+
+    output->num_akm_suites = num_akm_suites;
+    if (num_akm_suites > MM_RSN_INFORMATION_MAX_AKM_SUITES) {
+        output->num_akm_suites = MM_RSN_INFORMATION_MAX_AKM_SUITES;
+    }
+
+    if (length < 4 * num_akm_suites + 2) {
+        printf("*WRN* RSN IE too short\n");
+        return -2;
+    }
+
+    for (ii = 0; ii < num_akm_suites; ii++) {
+        if (ii < output->num_akm_suites) {
+            output->akm_suites[ii] = ies[offset] << 24 | ies[offset + 1] << 16 | ies[offset + 2] << 8 | ies[offset + 3];
+        }
+        offset += 4;
+        length -= 4;
+    }
+
+    output->rsn_capabilities = ies[offset] | ies[offset + 1] << 8;
+    return 0;
+}
+
+#endif /* USE_MM_IOT_ESP32 */
@@ -0,0 +1,267 @@
+#ifdef USE_MM_IOT_ESP32
+/*
+ * Copyright 2021-2023 Morse Micro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "mmhal.h"
+#include "mmosal.h"
+
+#include "driver/gpio.h"
+#include "driver/spi_common.h"
+#include "driver/spi_master.h"
+#include "esp_random.h"
+#include "esp_system.h"
+
+/** 10x8bit training seq */
+#define BYTE_TRAIN 16
+
+/** SPI hw interrupt handler. Must be set before enabling irq */
+static mmhal_irq_handler_t spi_irq_handler = NULL;
+
+/** busy interrupt handler. Must be set before enabling irq */
+static mmhal_irq_handler_t busy_irq_handler = NULL;
+
+static spi_device_handle_t spi_handle;
+
+static void wlan_hal_gpio_init(void)
+{
+    gpio_config_t io_conf = {};
+    io_conf.intr_type = GPIO_INTR_DISABLE;
+    io_conf.mode = GPIO_MODE_OUTPUT;
+    io_conf.pin_bit_mask = ((1ull << CONFIG_MM_WAKE) | (1ull << CONFIG_MM_SPI_CS));
+    io_conf.pull_down_en = 0;
+    io_conf.pull_up_en = 0;
+    gpio_config(&io_conf);
+
+    gpio_set_level(CONFIG_MM_WAKE, 0);
+    gpio_set_level(CONFIG_MM_SPI_CS, 0);
+
+    io_conf.intr_type = GPIO_INTR_DISABLE;
+    io_conf.mode = GPIO_MODE_INPUT;
+    io_conf.pin_bit_mask = (1ull << CONFIG_MM_BUSY);
+    io_conf.pull_down_en = 1;
+    gpio_config(&io_conf);
+
+    io_conf.intr_type = GPIO_INTR_DISABLE;
+    io_conf.mode = GPIO_MODE_INPUT;
+    io_conf.pin_bit_mask = (1ull << CONFIG_MM_SPI_IRQ);
+    io_conf.pull_down_en = 0;
+    gpio_config(&io_conf);
+}
+
+static void wlan_hal_spi_init(void)
+{
+    esp_err_t ret;
+
+    spi_bus_config_t buscfg = {
+        .miso_io_num = CONFIG_MM_SPI_MISO,
+        .mosi_io_num = CONFIG_MM_SPI_MOSI,
+        .sclk_io_num = CONFIG_MM_SPI_SCK,
+        .quadwp_io_num = -1,
+        .quadhd_io_num = -1,
+        /* max_transfer_sz defaults to 4092 if 0 when DMA enabled, or to SOC_SPI_MAXIMUM_BUFFER_SIZE
+         * if DMA is disabled. */
+        .max_transfer_sz = 0,
+        .flags = SPICOMMON_BUSFLAG_MASTER,
+    };
+    ret = spi_bus_initialize(SPI2_HOST, &buscfg, SPI_DMA_CH_AUTO);
+    if (ret != ESP_OK) {
+        printf("spi_bus_initialize failed\n");
+    }
+
+    /* Selected the highest available SPI clock speed that is still below the MM6108's maximum of
+     * 50MHz */
+    spi_device_interface_config_t dev_cfg = {
+        .clock_speed_hz = SPI_MASTER_FREQ_40M,
+        .mode = 0,
+        .spics_io_num = -1,
+        .queue_size = 1,
+    };
+    ret = spi_bus_add_device(SPI2_HOST, &dev_cfg, &spi_handle);
+    if (ret != ESP_OK) {
+        printf("spi_bus_add_device failed\n");
+    }
+
+    /* The actual clock frequency may not be the one that was set as it is re-calculated by the
+     * driver to the nearest hardware-compatible number. Importantly it is the "nearest", so it could be above
+     * the value set. */
+    int actual_freq_khz = 0;
+    spi_device_get_actual_freq(spi_handle, &actual_freq_khz);
+    printf("Actual SPI CLK %dkHz\n", actual_freq_khz);
+}
+
+static void wlan_hal_spi_deinit(void)
+{
+    esp_err_t ret = spi_bus_remove_device(spi_handle);
+    if (ret != ESP_OK) {
+        printf("spi_bus_remove_device failed\n");
+    }
+
+    ret = spi_bus_free(SPI2_HOST);
+    if (ret != ESP_OK) {
+        printf("spi_bus_initialize failed\n");
+    }
+}
+
+/**
+ * Minium transfer length in bytes before interrupt based transactions are used. This is because
+ * there is some setup time associated with using the interrupt based method when compared to the
+ * polling method. In the cases where the difference in setup time exceeds the transaction duration
+ * it is more efficient to uses the polling method instead of the interrupt based one. The below
+ * equation was used to calculate this.
+ *
+ * (DMA_TRANSACTION_DURATION - POLL_TRANSACTION_DURATION) / (8/SPI_FREQ)
+ *
+ * The typical duration for the ESP32 can be found in the [transaction
+ * duration](https://docs.espressif.com/projects/esp-idf/en/v5.1.1/esp32s3/api-reference/peripherals/spi_master.html#transaction-duration)
+ * section of the docs.
+ */
+#define INTERRUPT_TRANSFER_MIN_LENGTH 75
+
+static void spi_master_rw(const uint8_t *w_data, uint8_t *r_data, size_t len)
+{
+    spi_transaction_t trans_desc = {
+        .rx_buffer = r_data,
+        .tx_buffer = w_data,
+        .length = (len * 8),
+        .flags = 0,
+    };
+
+    esp_err_t err;
+    if (len < INTERRUPT_TRANSFER_MIN_LENGTH) {
+        err = spi_device_polling_transmit(spi_handle, &trans_desc);
+    } else {
+        err = spi_device_transmit(spi_handle, &trans_desc);
+    }
+
+    if (err != ESP_OK) {
+        printf("SPI rw error = %x\n", err);
+    }
+}
+
+void mmhal_wlan_hard_reset(void)
+{
+    gpio_set_level(CONFIG_MM_RESET_N, 0);
+    mmosal_task_sleep(5);
+    gpio_set_level(CONFIG_MM_RESET_N, 1);
+    mmosal_task_sleep(20);
+}
+
+void mmhal_wlan_spi_cs_assert(void)
+{
+    gpio_set_level(CONFIG_MM_SPI_CS, 0);
+}
+
+void mmhal_wlan_spi_cs_deassert(void)
+{
+    gpio_set_level(CONFIG_MM_SPI_CS, 1);
+}
+
+uint8_t mmhal_wlan_spi_rw(uint8_t data)
+{
+    uint8_t readval;
+    spi_master_rw(&data, &readval, 1);
+    return readval;
+}
+
+void mmhal_wlan_spi_read_buf(uint8_t *buf, unsigned len)
+{
+    spi_master_rw(NULL, buf, len);
+}
+
+void mmhal_wlan_spi_write_buf(const uint8_t *buf, unsigned len)
+{
+    spi_master_rw(buf, NULL, len);
+}
+
+void mmhal_wlan_send_training_seq(void)
+{
+    mmhal_wlan_spi_cs_deassert();
+    /* Send >74 clock pulses to card to stabilize CLK.
+     * This method of stacking up the TX data is described in RM0090 rev 19 Figure 253.
+     * It results is a reduction in the time between bytes of ~85% (316ns -> 48ns).
+     * Could not get this to work for the other transactions however.
+     */
+    uint8_t buf[BYTE_TRAIN] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};
+    spi_master_rw(buf, NULL, BYTE_TRAIN);
+}
+
+void mmhal_wlan_register_spi_irq_handler(mmhal_irq_handler_t handler)
+{
+    spi_irq_handler = handler;
+    gpio_isr_handler_add(CONFIG_MM_SPI_IRQ, (gpio_isr_t)spi_irq_handler, NULL);
+}
+
+bool mmhal_wlan_spi_irq_is_asserted(void)
+{
+    return !gpio_get_level(CONFIG_MM_SPI_IRQ);
+}
+
+void mmhal_wlan_set_spi_irq_enabled(bool enabled)
+{
+    if (enabled) {
+        gpio_set_intr_type(CONFIG_MM_SPI_IRQ, GPIO_INTR_LOW_LEVEL);
+    } else {
+        gpio_set_intr_type(CONFIG_MM_SPI_IRQ, GPIO_INTR_DISABLE);
+    }
+}
+
+void mmhal_wlan_init(void)
+{
+    wlan_hal_gpio_init();
+    wlan_hal_spi_init();
+    /* Raise the RESET_N line to enable the WLAN transceiver. */
+    gpio_set_level(CONFIG_MM_RESET_N, 1);
+}
+
+void mmhal_wlan_deinit(void)
+{
+    /* Lower the RESET_N line to disable the WLAN transceiver. This will put the transceiver in its
+     * lowest power state. */
+    gpio_set_level(CONFIG_MM_RESET_N, 0);
+
+    wlan_hal_spi_deinit();
+
+    /* Clean up any ISR handlers that have been added. These will be added again if the WLAN
+     * interface is brought back up. */
+    gpio_isr_handler_remove(CONFIG_MM_SPI_IRQ);
+    gpio_isr_handler_remove(CONFIG_MM_BUSY);
+}
+
+void mmhal_wlan_wake_assert(void)
+{
+    gpio_set_level(CONFIG_MM_WAKE, 1);
+}
+
+void mmhal_wlan_wake_deassert(void)
+{
+    gpio_set_level(CONFIG_MM_WAKE, 0);
+}
+
+bool mmhal_wlan_busy_is_asserted(void)
+{
+    return gpio_get_level(CONFIG_MM_BUSY);
+}
+
+void mmhal_wlan_register_busy_irq_handler(mmhal_irq_handler_t handler)
+{
+    busy_irq_handler = handler;
+    gpio_isr_handler_add(CONFIG_MM_BUSY, (gpio_isr_t)busy_irq_handler, NULL);
+}
+
+void mmhal_wlan_set_busy_irq_enabled(bool enabled)
+{
+    if (enabled) {
+        gpio_set_intr_type(CONFIG_MM_BUSY, GPIO_INTR_POSEDGE);
+    } else {
+        gpio_set_intr_type(CONFIG_MM_BUSY, GPIO_INTR_DISABLE);
+    }
+}
+
+#endif /* USE_MM_IOT_ESP32 */
@@ -7,6 +7,12 @@ __pycache__/
 dist/
 build/

+# Persistent device-log capture (recorder + Datadog cursor).
+# Cross-session JSONL streams written by the autouse Recorder singleton
+# (see src/meshtastic_mcp/recorder/). Lives outside tests/ so the pytest
+# fixture truncate doesn't touch it.
+.mtlog/
+
 # Test harness artifacts
 tests/report.html
 tests/junit.xml
@@ -166,15 +166,73 @@ rather than auto-`sudo`'ing mid-run.

 ## 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) |
+| 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)                                              |
+| `MESHTASTIC_MCP_TCP_HOST`  | unset                                                       | `host` or `host:port` of a `meshtasticd` daemon to surface as a TCP device (see "TCP / native-host nodes" below) |
+
+## TCP / native-host nodes
+
+The `native-macos` and `native` PlatformIO envs build a headless `meshtasticd`
+binary that runs on the host (Apple Silicon / Intel macOS, or Linux Portduino).
+The daemon exposes the meshtastic TCP API on port `4403` rather than a USB
+serial endpoint — point the MCP server at it via `MESHTASTIC_MCP_TCP_HOST`:
+
+```bash
+# 1. Build + run a daemon on this host (see variants/native/portduino/platformio.ini
+#    for full Homebrew prereqs and CH341 LoRa-adapter setup).
+pio run -e native-macos
+~/.meshtasticd/meshtasticd
+
+# 2. Point the MCP server at it.
+export MESHTASTIC_MCP_TCP_HOST=localhost     # or host:port, default port 4403
+```
+
+**First-run gotcha — MAC address.** `meshtasticd` derives its MAC from the
+USB adapter's serial-number / product strings. Many cheap CH341 dongles
+(MeshStick included — VID 0x1A86 / PID 0x5512) ship with `iSerialNumber=0`
+and `iProduct=0`, so the daemon aborts on boot with `*** Blank MAC Address
+not allowed!`. Set the MAC explicitly in `config.yaml`:
+
+```yaml
+# Under General:
+MACAddress: 02:CA:FE:BA:BE:01
+```
+
+Use a locally-administered address (first byte's second-LSB set, e.g.
+`02:*` / `06:*` / `0A:*` / `0E:*`) to avoid colliding with a real OUI.
+
+There is also a `--hwid AA:BB:CC:DD:EE:FF` CLI flag visible in
+`meshtasticd --help`, but it is **currently broken** in
+`MAC_from_string()` (`src/platform/portduino/PortduinoGlue.cpp`): the
+function strips colons from its parameter but then reads bytes from the
+global `portduino_config.mac_address`, so `--hwid` is silently overridden
+when `MACAddress:` is also set, and crashes the daemon (uncaught
+`std::invalid_argument: stoi: no conversion`) when it isn't. Use the YAML
+form until that's fixed upstream.
+
+`list_devices` will surface the daemon as `tcp://localhost:4403` with
+`likely_meshtastic=True`, so `device_info`, `list_nodes`, `get_config`,
+`set_config`, `set_owner`, `send_text`, `userprefs_*`, and the admin RPCs
+auto-select it when no `port` is passed. Pass `port="tcp://other-host:9999"`
+explicitly to target a different daemon.
+
+**Tools that don't apply to a TCP/native node** (no USB hardware to operate
+on) raise a clear `ConnectionError` rather than failing mysteriously:
+`pio_flash`, `erase_and_flash`, `update_flash`, `touch_1200bps`,
+`serial_open` (use info/admin tools directly), and the vendor escape hatches
+`esptool_*`, `nrfutil_*`, `picotool_*`. `pio_flash` against a `native*` env
+similarly raises — there's no upload step; use `build` and run the binary
+directly.
+
+The pytest harness in `tests/` still assumes USB-attached devices per role —
+TCP-aware fixtures are not part of this surface yet.

 ## Hardware Test Suite

@@ -0,0 +1,217 @@
+{
+  "title": "Meshtastic Firmware — Recorder Stream",
+  "description": "Live view of `.mtlog/` streams shipped by `mtlog_to_datadog.py`. Heap, packet volume, log levels, errors. One row per port.",
+  "widgets": [
+    {
+      "definition": {
+        "title": "Free heap (bytes)",
+        "type": "timeseries",
+        "show_legend": true,
+        "requests": [
+          {
+            "queries": [
+              {
+                "name": "free_heap",
+                "data_source": "metrics",
+                "query": "avg:mesh.local.heap_free_bytes{service:meshtastic-firmware} by {port}"
+              }
+            ],
+            "response_format": "timeseries",
+            "display_type": "line"
+          }
+        ],
+        "yaxis": { "label": "bytes" }
+      }
+    },
+    {
+      "definition": {
+        "title": "Heap slope (bytes/min) — last 1h",
+        "type": "query_value",
+        "precision": 0,
+        "requests": [
+          {
+            "queries": [
+              {
+                "name": "slope",
+                "data_source": "metrics",
+                "query": "derivative(avg:mesh.local.heap_free_bytes{service:meshtastic-firmware})",
+                "aggregator": "avg"
+              }
+            ],
+            "response_format": "scalar"
+          }
+        ],
+        "conditional_formats": [
+          { "comparator": "<", "value": -100, "palette": "white_on_red" },
+          { "comparator": "<", "value": 0, "palette": "white_on_yellow" },
+          { "comparator": ">=", "value": 0, "palette": "white_on_green" }
+        ]
+      }
+    },
+    {
+      "definition": {
+        "title": "Total heap (bytes)",
+        "type": "timeseries",
+        "requests": [
+          {
+            "queries": [
+              {
+                "name": "total_heap",
+                "data_source": "metrics",
+                "query": "avg:mesh.local.heap_total_bytes{service:meshtastic-firmware} by {port}"
+              }
+            ],
+            "response_format": "timeseries",
+            "display_type": "line"
+          }
+        ]
+      }
+    },
+    {
+      "definition": {
+        "title": "Battery level (%)",
+        "type": "timeseries",
+        "requests": [
+          {
+            "queries": [
+              {
+                "name": "battery",
+                "data_source": "metrics",
+                "query": "avg:mesh.device.battery_level{service:meshtastic-firmware} by {port}"
+              }
+            ],
+            "response_format": "timeseries",
+            "display_type": "line"
+          }
+        ],
+        "yaxis": { "min": "0", "max": "105" }
+      }
+    },
+    {
+      "definition": {
+        "title": "Air utilization (TX %)",
+        "type": "timeseries",
+        "requests": [
+          {
+            "queries": [
+              {
+                "name": "airutil",
+                "data_source": "metrics",
+                "query": "avg:mesh.device.air_util_tx{service:meshtastic-firmware} by {port}"
+              }
+            ],
+            "response_format": "timeseries",
+            "display_type": "line"
+          }
+        ]
+      }
+    },
+    {
+      "definition": {
+        "title": "Channel utilization (%)",
+        "type": "timeseries",
+        "requests": [
+          {
+            "queries": [
+              {
+                "name": "chutil",
+                "data_source": "metrics",
+                "query": "avg:mesh.device.channel_utilization{service:meshtastic-firmware} by {port}"
+              }
+            ],
+            "response_format": "timeseries",
+            "display_type": "line"
+          }
+        ]
+      }
+    },
+    {
+      "definition": {
+        "title": "Log volume by level",
+        "type": "timeseries",
+        "show_legend": true,
+        "requests": [
+          {
+            "response_format": "timeseries",
+            "display_type": "bars",
+            "queries": [
+              {
+                "name": "log_count",
+                "data_source": "logs",
+                "indexes": ["*"],
+                "compute": { "aggregation": "count" },
+                "search": { "query": "service:meshtastic-firmware" },
+                "group_by": [
+                  {
+                    "facet": "@level",
+                    "limit": 10,
+                    "sort": { "order": "desc", "aggregation": "count" }
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "definition": {
+        "title": "Recent ERROR / CRIT firmware logs",
+        "type": "list_stream",
+        "requests": [
+          {
+            "response_format": "event_list",
+            "query": {
+              "data_source": "logs_stream",
+              "query_string": "service:meshtastic-firmware (status:error OR @level:ERROR OR @level:CRIT)",
+              "indexes": [],
+              "sort": { "column": "timestamp", "order": "desc" }
+            },
+            "columns": [
+              { "field": "timestamp", "width": "auto" },
+              { "field": "host", "width": "auto" },
+              { "field": "@port", "width": "auto" },
+              { "field": "@level", "width": "auto" },
+              { "field": "@thread", "width": "auto" },
+              { "field": "message", "width": "stretch" }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "definition": {
+        "title": "Recorder marker events",
+        "type": "list_stream",
+        "requests": [
+          {
+            "response_format": "event_list",
+            "query": {
+              "data_source": "logs_stream",
+              "query_string": "service:meshtastic-firmware @level:MARK",
+              "indexes": [],
+              "sort": { "column": "timestamp", "order": "desc" }
+            },
+            "columns": [
+              { "field": "timestamp", "width": "auto" },
+              { "field": "host", "width": "auto" },
+              { "field": "message", "width": "stretch" }
+            ]
+          }
+        ]
+      }
+    }
+  ],
+  "template_variables": [
+    {
+      "name": "port",
+      "prefix": "port",
+      "available_values": [],
+      "default": "*"
+    },
+    { "name": "host", "prefix": "host", "available_values": [], "default": "*" }
+  ],
+  "layout_type": "ordered",
+  "notify_list": [],
+  "reflow_type": "auto"
+}
@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+"""Forward selected recorder JSONL streams to Datadog.
+
+Reads `.mtlog/logs.jsonl` and `.mtlog/telemetry.jsonl`, ships logs to the
+Logs Intake API and telemetry numerics to the Metrics v2 series API.
+Resumes from `.mtlog/.dd-cursor.json` so a daemon restart doesn't
+duplicate rows already shipped from the current live files.
+
+This forwarder does not currently backfill rotated `.jsonl.gz` archives.
+If the recorder rotates before this process drains the live file, or the
+forwarder is down across a rotation, those older rows are skipped.
+
+Usage:
+    DD_API_KEY=... ./scripts/mtlog_to_datadog.py --tail
+    ./scripts/mtlog_to_datadog.py --once          # catch up + exit
+    ./scripts/mtlog_to_datadog.py --since 3600   # backfill last hour from start
+
+Default `DD_SITE` is `us5.datadoghq.com` — the team's Datadog instance.
+Override via `DD_SITE=...` env var or `--site` flag for one-offs.
+
+The forwarder is a separate process by design — a Datadog outage or
+auth failure must not backpressure the recorder. We exit non-zero on
+fatal config errors (missing API key) and keep retrying on transient
+network/HTTP errors.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import socket
+import sys
+import time
+from pathlib import Path
+from typing import Any, Iterator
+
+try:
+    import requests
+except ImportError:
+    print(
+        "requests is required. Install it in the mcp-server venv: "
+        "uv pip install requests",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+
+_DEFAULT_LOG_DIR = Path(__file__).resolve().parents[1] / ".mtlog"
+_LOG_INTAKE_TPL = "https://http-intake.logs.{site}/api/v2/logs"
+_METRICS_TPL = "https://api.{site}/api/v2/series"
+_LOG_BATCH = 50
+_METRICS_BATCH = 100
+_MAX_RETRIES = 5
+_RETRY_BASE_S = 1.5
+
+
+# --- streaming JSONL with byte-position cursor -------------------------
+
+
+class _StreamReader:
+    """Reads a single rotating JSONL with cursor-based resume.
+
+    This tails only the live `.jsonl` file. The recorder rotates files
+    (live `.jsonl` → `.YYYYMMDD-HHMMSS-uuuuuu-NNNNN.jsonl.gz`), which means
+    the live file shrinks abruptly. We detect that via inode change OR live
+    size < cursor position, and reset the live-file cursor to 0.
+    """
+
+    def __init__(self, path: Path, cursor: dict[str, Any]):
+        self.path = path
+        self.cursor = cursor
+
+    def _state(self) -> tuple[int, int]:
+        """Return (inode, size) for the live file. (0, 0) if missing."""
+        try:
+            st = self.path.stat()
+            return (st.st_ino, st.st_size)
+        except FileNotFoundError:
+            return (0, 0)
+
+    def iter_new_records(self) -> Iterator[dict[str, Any]]:
+        ino, size = self._state()
+        last_ino = self.cursor.get("ino")
+        last_pos = int(self.cursor.get("pos") or 0)
+        if ino == 0:
+            return
+        if last_ino is not None and last_ino != ino:
+            # Rotation happened. Start over.
+            last_pos = 0
+        if last_pos > size:
+            # Live file truncated/shrunk under us — recorder rotated.
+            last_pos = 0
+        try:
+            with self.path.open("r", encoding="utf-8") as fh:
+                fh.seek(last_pos)
+                for line in fh:
+                    line = line.rstrip("\n")
+                    if not line:
+                        continue
+                    try:
+                        yield json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    last_pos = fh.tell()
+        except FileNotFoundError:
+            return
+        self.cursor["ino"] = ino
+        self.cursor["pos"] = last_pos
+
+
+def _load_cursor(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _save_cursor(path: Path, data: dict[str, Any]) -> None:
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, separators=(",", ":")))
+    tmp.replace(path)
+
+
+# --- Datadog clients ---------------------------------------------------
+
+
+class _DDSession:
+    """Pool one HTTPS session, share retry logic."""
+
+    def __init__(self, api_key: str, site: str, hostname: str) -> None:
+        self.api_key = api_key
+        self.site = site
+        self.hostname = hostname
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "DD-API-KEY": api_key,
+                "Content-Type": "application/json",
+            }
+        )
+
+    def _post(self, url: str, payload: Any) -> bool:
+        for attempt in range(_MAX_RETRIES):
+            try:
+                resp = self.session.post(url, json=payload, timeout=30)
+            except requests.RequestException as e:
+                _wait_retry(attempt, f"network error: {e}")
+                continue
+            if 200 <= resp.status_code < 300:
+                return True
+            if resp.status_code in (408, 429, 500, 502, 503, 504):
+                _wait_retry(
+                    attempt,
+                    f"HTTP {resp.status_code} retrying",
+                )
+                continue
+            print(
+                f"datadog refused: {resp.status_code} {resp.text[:200]}",
+                file=sys.stderr,
+            )
+            return False
+        return False
+
+    def send_logs(self, records: list[dict[str, Any]]) -> int:
+        if not records:
+            return 0
+        url = _LOG_INTAKE_TPL.format(site=self.site)
+        sent = 0
+        for i in range(0, len(records), _LOG_BATCH):
+            batch = records[i : i + _LOG_BATCH]
+            if self._post(url, batch):
+                sent += len(batch)
+        return sent
+
+    def send_metrics(self, series: list[dict[str, Any]]) -> int:
+        if not series:
+            return 0
+        url = _METRICS_TPL.format(site=self.site)
+        sent = 0
+        for i in range(0, len(series), _METRICS_BATCH):
+            batch = series[i : i + _METRICS_BATCH]
+            if self._post(url, {"series": batch}):
+                sent += len(batch)
+        return sent
+
+
+def _wait_retry(attempt: int, reason: str) -> None:
+    wait = _RETRY_BASE_S * (2**attempt)
+    print(
+        f"  retry {attempt + 1}/{_MAX_RETRIES} in {wait:.1f}s ({reason})",
+        file=sys.stderr,
+    )
+    time.sleep(wait)
+
+
+# --- record → datadog payload ------------------------------------------
+
+
+def _log_record_to_dd(rec: dict[str, Any], host: str) -> dict[str, Any]:
+    line = rec.get("line") or ""
+    tags = [
+        f"role:{rec.get('role')}",
+        f"port:{rec.get('port')}",
+    ]
+    level = rec.get("level")
+    if level:
+        tags.append(f"level:{level}")
+    tag = rec.get("tag")
+    if tag:
+        tags.append(f"thread:{tag}")
+    return {
+        "ddsource": "meshtastic-firmware",
+        "service": "meshtastic-firmware",
+        "hostname": host,
+        "message": line,
+        "ddtags": ",".join(t for t in tags if t and "None" not in t),
+        "timestamp": int((rec.get("ts") or time.time()) * 1000),
+        "level": level,
+    }
+
+
+def _telemetry_record_to_metrics(
+    rec: dict[str, Any], host: str
+) -> list[dict[str, Any]]:
+    fields = rec.get("fields") or {}
+    if not isinstance(fields, dict):
+        return []
+    variant = rec.get("variant") or "unknown"
+    ts = int(rec.get("ts") or time.time())
+    out: list[dict[str, Any]] = []
+    tags = []
+    if rec.get("port"):
+        tags.append(f"port:{rec['port']}")
+    if rec.get("role"):
+        tags.append(f"role:{rec['role']}")
+    if rec.get("from_node"):
+        tags.append(f"from_node:{rec['from_node']}")
+    tags.append(f"variant:{variant}")
+    for field, value in fields.items():
+        if not isinstance(value, (int, float)) or isinstance(value, bool):
+            continue
+        metric = f"mesh.{variant}.{_metric_safe(field)}"
+        out.append(
+            {
+                "metric": metric,
+                "type": 3,  # GAUGE
+                "points": [{"timestamp": ts, "value": float(value)}],
+                "tags": tags,
+                "resources": [{"type": "host", "name": host}],
+            }
+        )
+    return out
+
+
+def _metric_safe(name: str) -> str:
+    # Lowercase, replace non-alnum with underscore for safe metric names.
+    return "".join(c.lower() if c.isalnum() else "_" for c in name)
+
+
+# --- main loop ---------------------------------------------------------
+
+
+def run(
+    log_dir: Path,
+    *,
+    once: bool,
+    since_seconds: float | None,
+    poll_interval: float,
+    dd: _DDSession,
+) -> int:
+    cursor_path = log_dir / ".dd-cursor.json"
+    cursors = _load_cursor(cursor_path)
+
+    # `--since` overrides cursor: rewind to (now-since) timestamp.
+    # We can't seek by timestamp directly (cursor is byte position), so
+    # we just reset cursors to 0 and let the time filter in iter_new
+    # drop older records.
+    cutoff_ts: float | None = None
+    if since_seconds is not None:
+        cursors = {}
+        cutoff_ts = time.time() - since_seconds
+
+    sent_total = {"logs": 0, "telemetry": 0}
+
+    while True:
+        # logs.jsonl → DD logs
+        log_cursor = cursors.setdefault("logs", {})
+        log_batch: list[dict[str, Any]] = []
+        for rec in _StreamReader(log_dir / "logs.jsonl", log_cursor).iter_new_records():
+            if cutoff_ts and (rec.get("ts") or 0) < cutoff_ts:
+                continue
+            log_batch.append(_log_record_to_dd(rec, dd.hostname))
+        if log_batch:
+            n = dd.send_logs(log_batch)
+            sent_total["logs"] += n
+            print(f"logs: sent {n}/{len(log_batch)}")
+
+        # telemetry.jsonl → DD metrics
+        telem_cursor = cursors.setdefault("telemetry", {})
+        metric_series: list[dict[str, Any]] = []
+        for rec in _StreamReader(
+            log_dir / "telemetry.jsonl", telem_cursor
+        ).iter_new_records():
+            if cutoff_ts and (rec.get("ts") or 0) < cutoff_ts:
+                continue
+            metric_series.extend(_telemetry_record_to_metrics(rec, dd.hostname))
+        if metric_series:
+            n = dd.send_metrics(metric_series)
+            sent_total["telemetry"] += n
+            print(f"telemetry: sent {n}/{len(metric_series)} metric points")
+
+        _save_cursor(cursor_path, cursors)
+
+        if once:
+            print(f"done. logs={sent_total['logs']} metrics={sent_total['telemetry']}")
+            return 0
+        time.sleep(poll_interval)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--log-dir",
+        default=str(_DEFAULT_LOG_DIR),
+        help="Path to .mtlog/ (default: mcp-server/.mtlog)",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--once", action="store_true", help="Catch up then exit")
+    mode.add_argument(
+        "--tail",
+        action="store_true",
+        help="Daemon: poll forever (default)",
+    )
+    parser.add_argument(
+        "--since",
+        type=float,
+        default=None,
+        help="Backfill last N seconds. Resets cursor.",
+    )
+    parser.add_argument(
+        "--poll-interval",
+        type=float,
+        default=5.0,
+        help="Seconds between tail polls (default 5)",
+    )
+    parser.add_argument(
+        "--site",
+        default=os.environ.get("DD_SITE", "us5.datadoghq.com"),
+        help=(
+            "Datadog site. Default is the team's instance (us5.datadoghq.com). "
+            "Override via DD_SITE env var or this flag."
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default=socket.gethostname(),
+        help="Hostname tag (default: socket.gethostname())",
+    )
+    args = parser.parse_args(argv)
+
+    api_key = os.environ.get("DD_API_KEY")
+    if not api_key:
+        print("DD_API_KEY env var required.", file=sys.stderr)
+        return 2
+
+    log_dir = Path(args.log_dir)
+    if not log_dir.exists():
+        print(
+            f"log dir {log_dir} does not exist — start the mcp-server first.",
+            file=sys.stderr,
+        )
+        return 2
+
+    dd = _DDSession(api_key=api_key, site=args.site, hostname=args.host)
+    once = args.once and not args.tail
+    return run(
+        log_dir,
+        once=once,
+        since_seconds=args.since,
+        poll_interval=args.poll_interval,
+        dd=dd,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -1,4 +1,4 @@
-"""Context manager for meshtastic.SerialInterface connections.
+"""Context manager for meshtastic interface connections (serial + TCP).

 Every info/admin tool goes through `connect(port)` so we have a single place
 that:
@@ -6,8 +6,16 @@ that:
  - fails fast if a serial_session is already holding the port,
  - guarantees `.close()` is called, even on exception.

-The `SerialInterface` blocks on construction waiting for the node database;
-that's fine for v1 since every tool is a short-lived request.
+Two transports:
+  - Serial: USB-attached firmware on `/dev/cu.*` / `/dev/ttyUSB*` / `COM*`.
+  - TCP: a `meshtasticd` daemon (e.g. the native macOS / Linux Portduino
+    headless build) addressed as `tcp://host[:port]` (default port 4403).
+    Surfaced by `devices.list_devices()` when `MESHTASTIC_MCP_TCP_HOST` is
+    set, so `resolve_port(None)` auto-selects it like a USB candidate.
+
+Both `SerialInterface` and `TCPInterface` block on construction waiting for
+the node database; that's fine for v1 since every tool is a short-lived
+request.
 """

 from __future__ import annotations
@@ -17,20 +25,107 @@ from typing import Iterator

 from . import devices, registry

+DEFAULT_TCP_PORT = 4403
+TCP_SCHEME = "tcp://"
+TCP_HOST_ENV = "MESHTASTIC_MCP_TCP_HOST"
+

 class ConnectionError(RuntimeError):
    pass


+def is_tcp_port(port: str | None) -> bool:
+    return bool(port) and port.startswith(TCP_SCHEME)
+
+
+def parse_tcp_port(port: str) -> tuple[str, int]:
+    """Parse `tcp://host[:port]` → (host, port). Defaults to 4403.
+
+    Validates host shape (non-empty, no path separators) and port range
+    (1..65535). Raises `ConnectionError` on malformed input — never lets
+    a raw `ValueError` bubble up to a tool surface.
+    """
+    if not port.startswith(TCP_SCHEME):
+        raise ConnectionError(
+            f"Invalid TCP endpoint {port!r}: expected '{TCP_SCHEME}host[:port]'."
+        )
+    rest = port[len(TCP_SCHEME) :]
+    if ":" in rest:
+        host, port_str = rest.rsplit(":", 1)
+        try:
+            tcp_port = int(port_str)
+        except ValueError as e:
+            raise ConnectionError(
+                f"Invalid TCP endpoint {port!r}: port {port_str!r} is not an integer."
+            ) from e
+    else:
+        host, tcp_port = rest, DEFAULT_TCP_PORT
+    if not host:
+        raise ConnectionError(f"Invalid TCP endpoint {port!r}: empty host.")
+    if any(c in host for c in ("/", "\\")):
+        raise ConnectionError(
+            f"Invalid TCP endpoint {port!r}: host {host!r} contains a path "
+            "separator. TCP hostnames cannot contain '/' or '\\' — did you "
+            "pass a serial port path or a Windows drive path by mistake?"
+        )
+    if not (1 <= tcp_port <= 65535):
+        raise ConnectionError(
+            f"Invalid TCP endpoint {port!r}: port {tcp_port} out of range "
+            "(must be 1..65535)."
+        )
+    return host, tcp_port
+
+
+def normalize_tcp_endpoint(endpoint: str) -> str:
+    r"""Normalize `host`, `host:port`, or `tcp://host[:port]` → canonical
+    `tcp://host:port` form. One place that owns the lock-key shape.
+
+    Defers all validation to `parse_tcp_port`, so path-like inputs
+    (`/dev/cu.foo`, `C:\Windows\…`), empty hosts, non-integer ports,
+    and out-of-range ports raise `ConnectionError` here too.
+    """
+    if endpoint.startswith(TCP_SCHEME):
+        canonical = endpoint
+    elif ":" in endpoint:
+        canonical = f"{TCP_SCHEME}{endpoint}"
+    else:
+        canonical = f"{TCP_SCHEME}{endpoint}:{DEFAULT_TCP_PORT}"
+    host, port = parse_tcp_port(canonical)
+    return f"{TCP_SCHEME}{host}:{port}"
+
+
+def reject_if_tcp(port: str | None, tool_name: str) -> None:
+    """Raise if `port` is a TCP endpoint — for tools that need real USB
+    hardware (flash, bootloader, vendor escape hatches, serial monitor).
+
+    Only checks the explicit arg; auto-selection via env var is the caller's
+    responsibility to handle if it matters.
+    """
+    if is_tcp_port(port):
+        raise ConnectionError(
+            f"{tool_name} is not applicable to TCP/native nodes ({port}). "
+            "This tool requires USB-attached hardware."
+        )
+
+
 def resolve_port(port: str | None) -> str:
-    """Pick a port: explicit > sole likely_meshtastic candidate > error."""
+    """Pick a port: explicit > sole likely_meshtastic candidate > error.
+
+    A `tcp://` string passes through (after canonicalization). When `port`
+    is None and no USB candidates are present, `MESHTASTIC_MCP_TCP_HOST`
+    is consulted via `devices.list_devices()`.
+    """
    if port:
+        if is_tcp_port(port):
+            return normalize_tcp_endpoint(port)
        return port
    candidates = [d for d in devices.list_devices() if d["likely_meshtastic"]]
    if not candidates:
        raise ConnectionError(
-            "No Meshtastic devices detected. Plug one in or pass `port` explicitly. "
-            "Run `list_devices` with include_unknown=True to see all serial ports."
+            "No Meshtastic devices detected. Plug one in, set "
+            f"{TCP_HOST_ENV}=<host[:port]> for a meshtasticd daemon, "
+            "or pass `port` explicitly. Run `list_devices` with "
+            "include_unknown=True to see all serial ports."
        )
    if len(candidates) > 1:
        ports = ", ".join(c["port"] for c in candidates)
@@ -43,17 +138,62 @@ def resolve_port(port: str | None) -> str:

@contextmanager
 def connect(port: str | None = None, timeout_s: float = 8.0) -> Iterator:
-    """Open a `meshtastic.SerialInterface` and always close it.
+    """Open a meshtastic interface (serial or TCP) and always close it.

-    Raises `ConnectionError` immediately if another serial session holds the
-    port (a `pio device monitor` in `serial_sessions/`, for instance).
+    For serial: raises `ConnectionError` immediately if another serial
+    session holds the port (a `pio device monitor` in `serial_sessions/`).
+    For TCP: no exclusive-access requirement, so the serial-session check
+    is skipped — but the `port_lock` still serializes parallel `connect()`
+    calls to the same daemon endpoint.
+
+    `timeout_s` is plumbed through to both `SerialInterface(timeout=...)`
+    and `TCPInterface(timeout=...)`. The meshtastic library uses the value
+    as the reply-wait deadline for `localNode.waitForConfig()` during
+    construction and for any subsequent admin RPC. `int()`-converted at
+    the boundary because the upstream API expects whole seconds.
    """
+    resolved = resolve_port(port)
+    timeout = int(timeout_s)
+
+    if is_tcp_port(resolved):
+        from meshtastic.tcp_interface import (
+            TCPInterface,  # type: ignore[import-untyped]
+        )
+
+        host, tcp_port = parse_tcp_port(resolved)
+        lock = registry.port_lock(resolved)
+        if not lock.acquire(blocking=False):
+            raise ConnectionError(
+                f"TCP endpoint {resolved} is busy — another device operation "
+                "is in flight. Retry shortly."
+            )
+
+        iface = None
+        try:
+            iface = TCPInterface(
+                hostname=host,
+                portNumber=tcp_port,
+                connectNow=True,
+                noProto=False,
+                timeout=timeout,
+            )
+            yield iface
+        finally:
+            if iface is not None:
+                try:
+                    iface.close()
+                except Exception:
+                    pass
+            try:
+                lock.release()
+            except RuntimeError:
+                pass
+        return
+
    from meshtastic.serial_interface import (
        SerialInterface,  # type: ignore[import-untyped]
    )

-    resolved = resolve_port(port)
-
    active = registry.active_session_for_port(resolved)
    if active is not None:
        raise ConnectionError(
@@ -70,7 +210,12 @@ def connect(port: str | None = None, timeout_s: float = 8.0) -> Iterator:

    iface = None
    try:
-        iface = SerialInterface(devPath=resolved, connectNow=True, noProto=False)
+        iface = SerialInterface(
+            devPath=resolved,
+            connectNow=True,
+            noProto=False,
+            timeout=timeout,
+        )
        yield iface
    finally:
        if iface is not None:
@@ -1,13 +1,18 @@
-"""USB/serial device discovery.
+"""USB/serial + TCP device discovery.

 Combines the canonical `meshtastic.util.findPorts()` allowlist/blocklist with
 the richer metadata (`serial.tools.list_ports.comports()`) so callers see
 VID/PID, descriptions, and manufacturer strings alongside the "is this likely
 a Meshtastic device" signal.
+
+If `MESHTASTIC_MCP_TCP_HOST=<host[:port]>` is set, a synthetic entry for the
+`meshtasticd` daemon at that endpoint is prepended to the result, so
+`resolve_port(None)` auto-selects it like a USB candidate.
 """

 from __future__ import annotations

+import os
 from typing import Any

 from serial.tools import list_ports
@@ -19,6 +24,45 @@ def _to_hex(value: int | None) -> str | None:
    return f"0x{value:04x}"


+def _tcp_endpoint_from_env() -> dict[str, Any] | None:
+    """Synthesize a TCP device entry from MESHTASTIC_MCP_TCP_HOST, if set.
+
+    If the env var is malformed (non-integer port, path-like host, etc.),
+    return an entry with `likely_meshtastic=False` and the parser error in
+    the description, rather than raising — `list_devices` is the diagnostic
+    tool a user reaches for when their env var isn't working, so it must
+    not crash on misconfiguration.
+    """
+    host = os.environ.get("MESHTASTIC_MCP_TCP_HOST")
+    if not host:
+        return None
+    # Lazy import to avoid a circular dependency (connection imports devices).
+    from . import connection
+
+    try:
+        port = connection.normalize_tcp_endpoint(host)
+        description = "meshtasticd (TCP)"
+        likely = True
+    except connection.ConnectionError as e:
+        # Surface the raw env-var value plus the parser's reason so the
+        # user can see exactly what they set and why it was rejected.
+        # Don't double the scheme if the user already prefixed `tcp://`.
+        port = host if host.startswith(connection.TCP_SCHEME) else f"tcp://{host}"
+        description = f"meshtasticd (TCP) — invalid MESHTASTIC_MCP_TCP_HOST: {e}"
+        likely = False
+    return {
+        "port": port,
+        "vid": None,
+        "pid": None,
+        "description": description,
+        "manufacturer": None,
+        "product": None,
+        "serial_number": None,
+        "likely_meshtastic": likely,
+        "blacklisted": False,
+    }
+
+
 def list_devices(include_unknown: bool = False) -> list[dict[str, Any]]:
    """Return enriched info for serial ports, flagging Meshtastic candidates.

@@ -70,6 +114,22 @@ def list_devices(include_unknown: bool = False) -> list[dict[str, Any]]:
            }
        )

-    # Stable ordering: likely_meshtastic first, then by port path
-    results.sort(key=lambda r: (not r["likely_meshtastic"], r["port"]))
+    # Append the TCP endpoint (if env var set) and sort everything together.
+    tcp_entry = _tcp_endpoint_from_env()
+    if tcp_entry is not None:
+        results.append(tcp_entry)
+
+    # Stable ordering: likely_meshtastic first; within rank, TCP wins over
+    # USB (explicit env-var configuration takes precedence over USB
+    # enumeration); then by port path. A misconfigured TCP entry has
+    # likely_meshtastic=False and lands among the other ignored entries —
+    # it does NOT pre-empt real USB devices at the top of the list.
+    results.sort(
+        key=lambda r: (
+            not r["likely_meshtastic"],
+            not r["port"].startswith("tcp://"),
+            r["port"],
+        )
+    )
+
    return results
@@ -0,0 +1,382 @@
+"""Fake NodeDB fixture push — Portduino file copy + hardware XModem upload.
+
+The fixture pipeline is two-stage:
+  1. `bin/gen-fake-nodedb-seed.py` produces a deterministic JSONL describing N
+     fake-but-realistic peers. Committed under `test/fixtures/nodedb/`.
+  2. `bin/seed-json-to-proto.py` compiles JSONL → binary v25 NodeDatabase
+     protobuf with fresh wall-clock timestamps.
+
+This module exposes `push_fake_nodedb(...)`, the MCP tool that:
+  - target="portduino": compiles the JSONL into the device's prefs dir on
+    the local filesystem (`~/.portduino/<config>/prefs/nodes.proto`).
+  - target="hardware":  compiles to a temp file, then streams it over the
+    XModem protocol (via the meshtastic SerialInterface/BLEInterface +
+    `meshtastic.xmodempacket` pubsub topic) to `/prefs/nodes.proto` on the
+    device. Triggers a reboot so the firmware loads the new state on next
+    boot.
+
+XModem wire details (mirrors firmware impl at src/xmodem.cpp:115-260):
+  * 128-byte chunks; final chunk padded to 128 B with 0x1A (SUB) bytes.
+  * CRC16-CCITT (poly 0x1021, init 0x0000).
+  * SOH/seq=0 carries the destination filename in `buffer.bytes`. ACK if
+    `FSCom.open(filename, FILE_O_WRITE)` succeeds; NAK otherwise.
+  * SOH/seq≥1 carries a 128-byte chunk. ACK = advance; NAK = retransmit.
+  * EOT after the last chunk flushes + closes the file on-device.
+
+Hardware push requires `confirm=True` (mirrors factory_reset / erase_and_flash
+in the .github/copilot-instructions.md "never do these without asking" list).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import pathlib
+import queue
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from typing import Any, Literal
+
+from .connection import connect, is_tcp_port
+
+# Resolve repo root so the tool works regardless of mcp-server cwd.
+_REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+_SEED_DIR = _REPO_ROOT / "test" / "fixtures" / "nodedb"
+_COMPILE_SCRIPT = _REPO_ROOT / "bin" / "seed-json-to-proto.py"
+
+_DEFAULT_NODES_FILENAME = "/prefs/nodes.proto"
+_XMODEM_CHUNK = 128
+_XMODEM_SUB = 0x1A
+_ACK_TIMEOUT_INIT_S = 5.0
+_ACK_TIMEOUT_CHUNK_S = 2.0
+_MAX_CHUNK_RETRIES = 5
+
+_VALID_SIZES = (250, 500, 1000, 2000)
+
+
+class FixtureError(RuntimeError):
+    """Raised for any fixture-push failure (compile, transport, ack timeout, …)."""
+
+
+# ---------------------------------------------------------------------------
+# CRC16-CCITT (poly 0x1021, init 0x0000). Matches the firmware's `crc16_ccitt`.
+# Hand-rolled to avoid the optional `crcmod` dep.
+# ---------------------------------------------------------------------------
+def _crc16_ccitt(data: bytes, *, init: int = 0x0000) -> int:
+    crc = init
+    for b in data:
+        crc ^= b << 8
+        for _ in range(8):
+            if crc & 0x8000:
+                crc = ((crc << 1) ^ 0x1021) & 0xFFFF
+            else:
+                crc = (crc << 1) & 0xFFFF
+    return crc
+
+
+# ---------------------------------------------------------------------------
+# Compile step — shells out to bin/seed-json-to-proto.py so the MCP module
+# doesn't have to duplicate the proto-encoding logic.
+# ---------------------------------------------------------------------------
+def _compile_proto(jsonl_path: pathlib.Path, out_path: pathlib.Path) -> None:
+    if not _COMPILE_SCRIPT.is_file():
+        raise FixtureError(f"compile script missing at {_COMPILE_SCRIPT}")
+    cmd = [
+        sys.executable,
+        str(_COMPILE_SCRIPT),
+        "--in",
+        str(jsonl_path),
+        "--out",
+        str(out_path),
+    ]
+    try:
+        subprocess.run(cmd, check=True, capture_output=True, text=True)
+    except subprocess.CalledProcessError as exc:
+        raise FixtureError(
+            f"seed-json-to-proto.py failed (exit {exc.returncode}):\n"
+            f"  stdout: {exc.stdout}\n  stderr: {exc.stderr}"
+        ) from exc
+
+
+def _resolve_seed_jsonl(size: int, custom: str | None) -> pathlib.Path:
+    if custom is not None:
+        p = pathlib.Path(custom).expanduser().resolve()
+        if not p.is_file():
+            raise FixtureError(f"custom_seed_jsonl not found: {p}")
+        return p
+    p = _SEED_DIR / f"seed_v25_{size:04d}.jsonl"
+    if not p.is_file():
+        raise FixtureError(
+            f"missing committed seed at {p}. "
+            f"Run `./bin/regen-fake-nodedbs.sh` to generate it."
+        )
+    return p
+
+
+# ---------------------------------------------------------------------------
+# Portduino push — file copy into ~/.portduino/<config>/prefs/
+# ---------------------------------------------------------------------------
+def _portduino_prefs_dir(config_name: str) -> pathlib.Path:
+    home = pathlib.Path.home()
+    return home / ".portduino" / config_name / "prefs"
+
+
+def _push_portduino(
+    size: int,
+    jsonl: pathlib.Path,
+    portduino_config: str,
+    backup_existing: bool,
+) -> dict[str, Any]:
+    prefs = _portduino_prefs_dir(portduino_config)
+    prefs.mkdir(parents=True, exist_ok=True)
+    target = prefs / "nodes.proto"
+    backed_up_to: str | None = None
+    if backup_existing and target.is_file():
+        ts = int(time.time())
+        backup = prefs / f"nodes.proto.bak.{ts}"
+        shutil.move(str(target), str(backup))
+        backed_up_to = str(backup)
+    _compile_proto(jsonl, target)
+    raw = target.read_bytes()
+    return {
+        "transport": "portduino",
+        "path": str(target),
+        "bytes": len(raw),
+        "sha256": hashlib.sha256(raw).hexdigest(),
+        "jsonl_source": str(jsonl),
+        "backed_up_to": backed_up_to,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Hardware push — XModem over BLE/serial via the meshtastic Python interface.
+# ---------------------------------------------------------------------------
+@dataclasses.dataclass
+class _AckEvent:
+    control: int
+    seq: int
+
+
+def _wait_for_response(q: "queue.Queue[_AckEvent]", timeout_s: float) -> _AckEvent:
+    try:
+        return q.get(timeout=timeout_s)
+    except queue.Empty as exc:
+        raise FixtureError(
+            f"XModem response timeout after {timeout_s:.1f}s — device not responding"
+        ) from exc
+
+
+def _push_hardware(
+    size: int,
+    jsonl: pathlib.Path,
+    port: str | None,
+    reboot_after: bool,
+) -> dict[str, Any]:
+    # Lazy imports so the module loads even when the meshtastic deps aren't
+    # available (e.g. CI in a Python env without the package installed).
+    try:
+        from meshtastic.protobuf import mesh_pb2, xmodem_pb2
+        from pubsub import pub
+    except ImportError as exc:  # pragma: no cover — dep missing
+        raise FixtureError(
+            f"hardware push requires the meshtastic + pypubsub packages: {exc}"
+        ) from exc
+
+    if is_tcp_port(port):
+        raise FixtureError(
+            "hardware push over TCP/portduino is not supported — use "
+            "target='portduino' to drop the fixture directly into the prefs dir."
+        )
+
+    # Compile the fixture to a temp file with fresh timestamps.
+    with tempfile.NamedTemporaryFile(suffix=".proto", delete=False) as tf:
+        proto_path = pathlib.Path(tf.name)
+    try:
+        _compile_proto(jsonl, proto_path)
+        payload = proto_path.read_bytes()
+    finally:
+        proto_path.unlink(missing_ok=True)
+
+    sha256 = hashlib.sha256(payload).hexdigest()
+    total_bytes = len(payload)
+
+    # Subscribe to XModem responses BEFORE we open the interface, so we don't
+    # race the first ACK that arrives during the SOH/seq=0 handshake.
+    #
+    # NB: the signature MUST declare every kwarg pypubsub will see for this
+    # topic, or pubsub locks the topic spec to a smaller set (whichever
+    # subscribe arrives first) and then *rejects* the meshtastic library's
+    # publish call with `SenderUnknownMsgDataError: unknown ... interface`.
+    # The meshtastic lib publishes both `packet=` and `interface=`
+    # (mesh_interface.py:1389-1395), so both must appear here.
+    response_q: "queue.Queue[_AckEvent]" = queue.Queue()
+
+    def _on_xmodem(packet: Any = None, interface: Any = None, **_kw: Any) -> None:
+        if packet is None:
+            return
+        response_q.put(_AckEvent(control=int(packet.control), seq=int(packet.seq)))
+
+    pub.subscribe(_on_xmodem, "meshtastic.xmodempacket")
+
+    chunks_sent = 0
+    retried = 0
+    rebooted = False
+
+    XMC = xmodem_pb2.XModem.Control
+    try:
+        with connect(port=port) as iface:
+            # 1) Send the filename (SOH, seq=0).
+            init_pkt = xmodem_pb2.XModem(
+                control=XMC.Value("SOH"),
+                seq=0,
+                buffer=_DEFAULT_NODES_FILENAME.encode("utf-8"),
+            )
+            iface._sendToRadio(mesh_pb2.ToRadio(xmodemPacket=init_pkt))
+            ack = _wait_for_response(response_q, _ACK_TIMEOUT_INIT_S)
+            if ack.control != XMC.Value("ACK"):
+                raise FixtureError(
+                    f"device refused filename {_DEFAULT_NODES_FILENAME!r} "
+                    f"(got control={ack.control}, expected ACK). "
+                    f"Filesystem full or permissions issue?"
+                )
+
+            # 2) Stream the payload in 128 B chunks.
+            for offset in range(0, total_bytes, _XMODEM_CHUNK):
+                chunk = payload[offset : offset + _XMODEM_CHUNK]
+                if len(chunk) < _XMODEM_CHUNK:
+                    # Pad final chunk to 128 B with SUB. The trailing 0x1A bytes
+                    # become part of the file on-device, but nanopb ignores
+                    # bytes past the end of the top-level message.
+                    chunk = chunk + bytes([_XMODEM_SUB] * (_XMODEM_CHUNK - len(chunk)))
+                seq = ((offset // _XMODEM_CHUNK) + 1) % 256
+                # Retry loop on NAK / timeout.
+                attempts = 0
+                while True:
+                    pkt = xmodem_pb2.XModem(
+                        control=XMC.Value("SOH"),
+                        seq=seq,
+                        buffer=chunk,
+                        crc16=_crc16_ccitt(chunk),
+                    )
+                    iface._sendToRadio(mesh_pb2.ToRadio(xmodemPacket=pkt))
+                    ack = _wait_for_response(response_q, _ACK_TIMEOUT_CHUNK_S)
+                    if ack.control == XMC.Value("ACK"):
+                        chunks_sent += 1
+                        break
+                    if ack.control == XMC.Value("NAK"):
+                        attempts += 1
+                        retried += 1
+                        if attempts >= _MAX_CHUNK_RETRIES:
+                            # Abort: send CAN so the firmware removes the half-
+                            # written file via FSCom.remove(filename).
+                            iface._sendToRadio(
+                                mesh_pb2.ToRadio(
+                                    xmodemPacket=xmodem_pb2.XModem(
+                                        control=XMC.Value("CAN")
+                                    )
+                                )
+                            )
+                            raise FixtureError(
+                                f"chunk seq={seq} NAK'd {attempts} times; "
+                                f"aborted transfer (file removed on-device)."
+                            )
+                        continue  # retry the same chunk
+                    raise FixtureError(
+                        f"unexpected XModem control={ack.control} on seq={seq}"
+                    )
+
+            # 3) Tell the device we're done.
+            iface._sendToRadio(
+                mesh_pb2.ToRadio(
+                    xmodemPacket=xmodem_pb2.XModem(control=XMC.Value("EOT"))
+                )
+            )
+            ack = _wait_for_response(response_q, _ACK_TIMEOUT_CHUNK_S)
+            if ack.control != XMC.Value("ACK"):
+                raise FixtureError(f"EOT not ACKed (got control={ack.control})")
+
+            # 4) Reboot so loadFromDisk picks up the new file.
+            if reboot_after:
+                iface.localNode.reboot(secs=1)
+                rebooted = True
+    finally:
+        try:
+            pub.unsubscribe(_on_xmodem, "meshtastic.xmodempacket")
+        except Exception:
+            pass
+
+    return {
+        "transport": "hardware",
+        "port": port,
+        "filename_on_device": _DEFAULT_NODES_FILENAME,
+        "bytes": total_bytes,
+        "chunks_sent": chunks_sent,
+        "retried": retried,
+        "sha256": sha256,
+        "jsonl_source": str(jsonl),
+        "rebooted": rebooted,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Public entry point — registered as an MCP tool in server.py.
+# ---------------------------------------------------------------------------
+def push_fake_nodedb(
+    size: int,
+    target: Literal["portduino", "hardware"] = "portduino",
+    *,
+    port: str | None = None,
+    portduino_config: str = "default",
+    backup_existing: bool = True,
+    confirm: bool = False,
+    reboot_after: bool = True,
+    custom_seed_jsonl: str | None = None,
+) -> dict[str, Any]:
+    """Compile a fresh-timestamp NodeDatabase fixture and push it to a device.
+
+    Args:
+      size: 250, 500, 1000, or 2000 — selects which committed seed JSONL to use.
+      target: "portduino" (file copy to ~/.portduino/<config>/prefs/) or
+              "hardware" (XModem upload to /prefs/nodes.proto + reboot).
+      port: required for target="hardware". Serial path (e.g. /dev/cu.usbmodemXXXX)
+            or BLE identifier. TCP endpoints are rejected — use target="portduino"
+            instead.
+      portduino_config: which Portduino instance dir under ~/.portduino/. Default "default".
+      backup_existing: portduino only. Move nodes.proto -> nodes.proto.bak.<ts>
+                        if present, so you can roll back.
+      confirm: required True for target="hardware" (writes flash + reboots).
+      reboot_after: hardware only. If True, send a 1-second reboot after the
+                    final ACK so loadFromDisk picks up the new file at next boot.
+      custom_seed_jsonl: override the committed JSONL. Use to push a hand-edited
+                         test scenario.
+
+    Returns:
+        dict with transport, bytes, sha256, etc. — depends on target.
+
+    """
+    if size not in _VALID_SIZES:
+        raise FixtureError(
+            f"size must be one of {_VALID_SIZES}; got {size!r}. "
+            f"Add a new committed seed if you need a different cardinality."
+        )
+
+    jsonl = _resolve_seed_jsonl(size, custom_seed_jsonl)
+
+    if target == "portduino":
+        return _push_portduino(size, jsonl, portduino_config, backup_existing)
+
+    if target == "hardware":
+        if not confirm:
+            raise FixtureError(
+                "hardware push writes flash and triggers a reboot — pass confirm=True."
+            )
+        if not port:
+            raise FixtureError(
+                "target='hardware' requires a port (e.g. /dev/cu.usbmodemXXXX)."
+            )
+        return _push_hardware(size, jsonl, port, reboot_after)
+
+    raise FixtureError(f"unknown target {target!r}; expected 'portduino' or 'hardware'")
@@ -17,7 +17,7 @@ from typing import Any

 import serial

-from . import boards, config, devices, pio, userprefs
+from . import boards, config, connection, devices, pio, userprefs

 # Meshtastic variants use both `esp32s3` and `esp32-s3` style names across
 # variants/*/platformio.ini (no consistency enforced). Accept both spellings.
@@ -46,6 +46,18 @@ def _require_confirm(confirm: bool, operation: str) -> None:
        )


+def _reject_native_env(env: str, operation: str) -> None:
+    """`native*` envs build a host executable, not firmware — there's no
+    upload step. The user wants `build` (or just runs the binary directly).
+    """
+    if env.startswith("native"):
+        raise FlashError(
+            f"{operation} is not applicable for env {env!r}: native envs "
+            "produce a host executable, not flashable firmware. Use `build` "
+            "instead, then run the resulting binary directly."
+        )
+
+
 def _artifacts_for(env: str) -> list[Path]:
    build_dir = config.firmware_root() / ".pio" / "build" / env
    if not build_dir.is_dir():
@@ -96,18 +108,33 @@ def build(
    env: str,
    with_manifest: bool = True,
    userprefs_overrides: dict[str, Any] | None = None,
+    build_flags: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
    """Run `pio run -e <env>` and return artifact paths.

    `userprefs_overrides` (optional): dict of `USERPREFS_<KEY>: value` to inject
    into userPrefs.jsonc for this build only. File is restored byte-for-byte
    on exit. Use `userprefs_set()` for persistent changes.
+
+    `build_flags` (optional): dict of `-D<NAME>=<VALUE>` macros to set for
+    this build only via `PLATFORMIO_BUILD_FLAGS`. Common useful flag:
+    `{"DEBUG_HEAP": 1}` enables per-thread leak detection + `[heap N]`
+    prefix on every log line. Combines with the recorder so heap shows
+    up at log cadence (much higher resolution than the ~60 s LocalStats
+    packet) — see `recorder/parsers.py:_HEAP_PREFIX_RE`. Bool values
+    expand to bare `-D<NAME>` (presence-only flags).
    """
    args = ["run", "-e", env]
    if with_manifest:
        args.extend(["-t", "mtjson"])
+    extra_env = _build_flags_env(build_flags) if build_flags else None
    with userprefs.temporary_overrides(userprefs_overrides) as effective:
-        result = pio.run(args, timeout=pio.TIMEOUT_BUILD, check=False)
+        result = pio.run(
+            args,
+            timeout=pio.TIMEOUT_BUILD,
+            check=False,
+            extra_env=extra_env,
+        )
    return {
        "exit_code": result.returncode,
        "artifacts": [str(p) for p in _artifacts_for(env)],
@@ -115,9 +142,27 @@ def build(
        "stderr_tail": pio.tail_lines(result.stderr, 200),
        "duration_s": round(result.duration_s, 2),
        "userprefs": _userprefs_summary(effective),
+        "build_flags": dict(build_flags) if build_flags else None,
    }


+def _build_flags_env(build_flags: dict[str, Any]) -> dict[str, str]:
+    """Translate `{"DEBUG_HEAP": 1, "FOO": "bar"}` → `{"PLATFORMIO_BUILD_FLAGS":
+    "-DDEBUG_HEAP=1 -DFOO=bar"}`. Bool True → bare `-D<NAME>`; False/None drop
+    the flag entirely. Other types stringify."""
+    parts: list[str] = []
+    for key, value in build_flags.items():
+        if value is False or value is None:
+            continue
+        if value is True:
+            parts.append(f"-D{key}")
+        else:
+            parts.append(f"-D{key}={value}")
+    if not parts:
+        return {}
+    return {"PLATFORMIO_BUILD_FLAGS": " ".join(parts)}
+
+
 def clean(env: str) -> dict[str, Any]:
    """Run `pio run -e <env> -t clean`."""
    result = pio.run(["run", "-e", env, "-t", "clean"], timeout=120, check=False)
@@ -134,18 +179,29 @@ def flash(
    port: str,
    confirm: bool = False,
    userprefs_overrides: dict[str, Any] | None = None,
+    build_flags: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
    """`pio run -e <env> -t upload --upload-port <port>`. All architectures.

    `userprefs_overrides` (optional): see `build()` — the rebuild-before-upload
    that pio performs will pick up the injected values.
+
+    `build_flags` (optional): same shape as `build()` — `PLATFORMIO_BUILD_FLAGS`
+    is exported for the rebuild-before-upload, so the uploaded firmware
+    actually carries the flags. Without this propagation, `pio run -t upload`
+    would relink without the env var and silently drop them. Common use:
+    `build_flags={"DEBUG_HEAP": 1}` for the leak-hunt path.
    """
    _require_confirm(confirm, "flash")
+    _reject_native_env(env, "flash")
+    connection.reject_if_tcp(port, "flash")
+    extra_env = _build_flags_env(build_flags) if build_flags else None
    with userprefs.temporary_overrides(userprefs_overrides) as effective:
        result = pio.run(
            ["run", "-e", env, "-t", "upload", "--upload-port", port],
            timeout=pio.TIMEOUT_UPLOAD,
            check=False,
+            extra_env=extra_env,
        )
    return {
        "exit_code": result.returncode,
@@ -153,6 +209,7 @@ def flash(
        "stderr_tail": pio.tail_lines(result.stderr, 200),
        "duration_s": round(result.duration_s, 2),
        "userprefs": _userprefs_summary(effective),
+        "build_flags": dict(build_flags) if build_flags else None,
    }


@@ -200,6 +257,7 @@ def erase_and_flash(
    in that case) since a cached factory.bin would not reflect the new prefs.
    """
    _require_confirm(confirm, "erase_and_flash")
+    connection.reject_if_tcp(port, "erase_and_flash")
    _check_esp32_env(env)

    if userprefs_overrides and skip_build:
@@ -257,6 +315,7 @@ def update_flash(
    overrides are provided we always force a rebuild.
    """
    _require_confirm(confirm, "update_flash")
+    connection.reject_if_tcp(port, "update_flash")
    _check_esp32_env(env)

    if userprefs_overrides and skip_build:
@@ -391,6 +450,7 @@ def touch_1200bps(

    Returns `{ok, former_port, new_port, new_port_vid_pid, attempts}`.
    """
+    connection.reject_if_tcp(port, "touch_1200bps")
    before_list = devices.list_devices(include_unknown=True)
    before_ports = {d["port"] for d in before_list}

@@ -16,7 +16,7 @@ import subprocess
 from pathlib import Path
 from typing import Any, Sequence

-from . import config, pio
+from . import config, connection, pio

 _TIMEOUT_SHORT = 30
 _TIMEOUT_LONG = 600
@@ -102,6 +102,7 @@ def _parse_esptool_chip_info(stdout: str) -> dict[str, Any]:


 def esptool_chip_info(port: str) -> dict[str, Any]:
+    connection.reject_if_tcp(port, "esptool_chip_info")
    binary = config.esptool_bin()
    # `chip_id` prints chip + mac + crystal + features. `flash_id` adds flash.
    combined = _run(binary, ["--port", port, "flash_id"], timeout=_TIMEOUT_SHORT)
@@ -116,6 +117,7 @@ def esptool_chip_info(port: str) -> dict[str, Any]:
 def esptool_erase_flash(port: str, confirm: bool = False) -> dict[str, Any]:
    """Full-chip erase. Leaves the device unbootable until reflashed."""
    _require_confirm(confirm, "esptool_erase_flash")
+    connection.reject_if_tcp(port, "esptool_erase_flash")
    binary = config.esptool_bin()
    # esptool v5 uses `erase-flash`, older uses `erase_flash`. Try the new name
    # first; if it fails with unknown command, retry old.
@@ -134,6 +136,7 @@ def esptool_raw(
    """Raw esptool passthrough. Destructive subcommands require confirm=True."""
    if not args:
        raise ToolError("args must not be empty")
+    connection.reject_if_tcp(port, "esptool_raw")
    # Find the first non-flag arg (the subcommand).
    subcommand = next((a for a in args if not a.startswith("-")), None)
    if subcommand and subcommand.replace("-", "_") in {
@@ -156,6 +159,7 @@ NRFUTIL_DESTRUCTIVE = {"dfu", "settings"}

 def nrfutil_dfu(port: str, package_path: str, confirm: bool = False) -> dict[str, Any]:
    _require_confirm(confirm, "nrfutil_dfu")
+    connection.reject_if_tcp(port, "nrfutil_dfu")
    pkg = Path(package_path).expanduser()
    if not pkg.is_file():
        raise ToolError(f"Package not found: {pkg}")
@@ -213,6 +217,7 @@ def _parse_picotool_info(stdout: str) -> dict[str, Any]:
 def picotool_info(port: str | None = None) -> dict[str, Any]:
    """Read device info from a Pico in BOOTSEL mode. `port` is informational
    only — picotool auto-detects."""
+    connection.reject_if_tcp(port, "picotool_info")
    binary = config.picotool_bin()
    res = _run(binary, ["info", "-a"], timeout=_TIMEOUT_SHORT)
    if res["exit_code"] != 0:
@@ -0,0 +1,410 @@
+"""Read-side queries over the recorder's JSONL streams.
+
+Pure functions over `mcp-server/.mtlog/`. Streaming JSONL reader: never
+loads a whole file. Time-bound queries short-circuit as soon as `ts`
+exceeds the requested end. The recorder writes monotonically, so a
+forward scan is cheap; we don't need an index.
+
+All time arguments accept:
+  - epoch seconds (int/float)
+  - relative strings: "-15m", "-2h", "-3d", "now"
+  - ISO-ish absolute strings: "2026-05-07T14:30:00" (naive timestamps are
+    treated as UTC)
+
+Tools that return data ALWAYS cap their output (max_lines / max_points
+/ max), and report whether more matched than was returned.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import re
+import statistics
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+from .recorder.recorder import get_recorder
+
+_REL_RE = re.compile(r"^\s*-\s*(\d+(?:\.\d+)?)\s*([smhd])\s*$")
+_REGEX_PREVIEW_MAX = 100
+_REGEX_PREVIEW_TRUNCATE = 97
+
+
+def _parse_time(value: Any, *, now: float | None = None) -> float:
+    """Coerce to epoch seconds. Defaults `now` to `time.time()`."""
+    if value is None:
+        return time.time()
+    if isinstance(value, (int, float)):
+        return float(value)
+    if not isinstance(value, str):
+        raise ValueError(f"invalid time: {value!r}")
+    s = value.strip().lower()
+    if s in ("", "now"):
+        return time.time() if now is None else now
+    m = _REL_RE.match(s)
+    if m:
+        n = float(m.group(1))
+        unit = m.group(2)
+        secs = n * {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
+        base = time.time() if now is None else now
+        return base - secs
+    # Try ISO 8601. Accept naive (assume UTC) and Z-suffixed.
+    try:
+        if s.endswith("z"):
+            s = s[:-1] + "+00:00"
+        dt = datetime.fromisoformat(s)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    except ValueError as e:
+        raise ValueError(f"unparseable time: {value!r}") from e
+
+
+def _iter_jsonl(path: Path, *, since: float, until: float) -> Iterator[dict[str, Any]]:
+    """Stream records in chronological order: rotated archives first
+    (oldest → newest by lex sort, which is chronological for our
+    `YYYYMMDD-HHMMSS-uuuuuu-NNNNN` archive naming), then the live file
+    last. The "keep last N" pop-front logic in the window queries
+    relies on records arriving in time order across files.
+    """
+    files: list[Path] = []
+    # Gzipped archives are named "<stem>.YYYYMMDD-HHMMSS-uuuuuu-NNNNN.jsonl.gz".
+    for archive in sorted(path.parent.glob(f"{path.stem}.*.jsonl.gz")):
+        files.append(archive)
+    if path.exists():
+        files.append(path)
+    for f in files:
+        opener = gzip.open if f.suffix == ".gz" else open
+        try:
+            with opener(f, "rt", encoding="utf-8") as fh:  # type: ignore[arg-type]
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        rec = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    ts = rec.get("ts")
+                    if not isinstance(ts, (int, float)):
+                        continue
+                    if ts < since:
+                        continue
+                    if ts > until:
+                        # Records are append-monotonic within a file, so
+                        # the rest of this file is also past `until`.
+                        # Archives can still overlap each other, so only
+                        # short-circuit this file, not the whole scan.
+                        break
+                    yield rec
+        except (FileNotFoundError, OSError):
+            continue
+
+
+# -- queries ------------------------------------------------------------
+
+
+def logs_window(
+    start: Any = "-15m",
+    end: Any = "now",
+    *,
+    grep: str | None = None,
+    level: str | None = None,
+    tag: str | None = None,
+    port: str | None = None,
+    max_lines: int = 200,
+) -> dict[str, Any]:
+    """Recent firmware log lines, filtered.
+
+    `level` accepts a single level name or pipe-separated set
+    ("WARN|ERROR|CRIT"). `grep` is a regex (Python re) over the raw
+    `line` field. Returns the last `max_lines` matches.
+    """
+    s = _parse_time(start)
+    e = _parse_time(end)
+    levels = _split_set(level)
+    if grep:
+        try:
+            grep_re = re.compile(grep)
+        except re.error as exc:
+            preview = (
+                grep
+                if len(grep) <= _REGEX_PREVIEW_MAX
+                else f"{grep[:_REGEX_PREVIEW_TRUNCATE]}..."
+            )
+            raise ValueError(f"invalid grep regex {preview!r}: {exc}") from exc
+    else:
+        grep_re = None
+
+    base = get_recorder().base_dir
+    matched = 0
+    out: list[dict[str, Any]] = []
+    for rec in _iter_jsonl(base / "logs.jsonl", since=s, until=e):
+        if levels and rec.get("level") not in levels:
+            continue
+        if tag and rec.get("tag") != tag:
+            continue
+        if port and rec.get("port") != port:
+            continue
+        if grep_re and not grep_re.search(rec.get("line") or ""):
+            continue
+        matched += 1
+        out.append(rec)
+        if len(out) > max_lines:
+            out.pop(0)  # keep the most recent N
+    return {
+        "lines": out,
+        "total_matched": matched,
+        "dropped": max(0, matched - max_lines),
+        "window": {"start": s, "end": e},
+    }
+
+
+def telemetry_timeline(
+    window: Any = "1h",
+    *,
+    variant: str = "local",
+    field: str = "free_heap",
+    port: str | None = None,
+    max_points: int = 200,
+) -> dict[str, Any]:
+    """Timeseries of one telemetry field, downsampled.
+
+    `field` matches both the protobuf snake_case name (`free_heap`,
+    `heap_free_bytes`, `battery_level`) and camelCase (`freeHeap`).
+    Server-side bucket-mean downsamples to ≤ `max_points`. Returns
+    `slope_per_min` (linear regression slope, units/min) so a leak
+    detector can read one number.
+    """
+    end = time.time()
+    if isinstance(window, (int, float)):
+        # Numeric `window` is a duration in seconds — "last N seconds".
+        # Without this branch, `_parse_time(-N)` would treat -N as an
+        # absolute epoch timestamp (i.e., Jan 1 1970 minus N seconds),
+        # producing a wildly negative `start` and matching nothing.
+        start = end - float(window)
+    elif isinstance(window, str) and not window.startswith("-"):
+        # Bare string like "1h" is sugar for "-1h".
+        start = _parse_time(f"-{window}", now=end)
+    else:
+        start = _parse_time(window, now=end)
+
+    base = get_recorder().base_dir
+    raw: list[tuple[float, float]] = []
+    field_aliases = _field_aliases(field)
+    for rec in _iter_jsonl(base / "telemetry.jsonl", since=start, until=end):
+        if rec.get("variant") != variant:
+            continue
+        if port and rec.get("port") != port:
+            continue
+        fields = rec.get("fields") or {}
+        value: Any = None
+        for alias in field_aliases:
+            if alias in fields:
+                value = fields[alias]
+                break
+        if not isinstance(value, (int, float)):
+            continue
+        raw.append((float(rec["ts"]), float(value)))
+
+    if not raw:
+        return {
+            "points": [],
+            "samples": 0,
+            "min": None,
+            "max": None,
+            "slope_per_min": None,
+            "window": {"start": start, "end": end, "variant": variant, "field": field},
+        }
+
+    points = _downsample(raw, max_points=max_points)
+    values = [v for _, v in raw]
+    return {
+        "points": [{"ts": ts, "value": v} for ts, v in points],
+        "samples": len(raw),
+        "min": min(values),
+        "max": max(values),
+        "slope_per_min": _slope_per_min(raw),
+        "window": {"start": start, "end": end, "variant": variant, "field": field},
+    }
+
+
+def packets_window(
+    start: Any = "-5m",
+    end: Any = "now",
+    *,
+    portnum: str | None = None,
+    from_node: str | None = None,
+    to_node: str | None = None,
+    max: int = 200,
+) -> dict[str, Any]:
+    s = _parse_time(start)
+    e = _parse_time(end)
+    portnums = _split_set(portnum)
+    base = get_recorder().base_dir
+    matched = 0
+    out: list[dict[str, Any]] = []
+    for rec in _iter_jsonl(base / "packets.jsonl", since=s, until=e):
+        if portnums and rec.get("portnum") not in portnums:
+            continue
+        if from_node and str(rec.get("from_node")) != str(from_node):
+            continue
+        if to_node and str(rec.get("to_node")) != str(to_node):
+            continue
+        matched += 1
+        out.append(rec)
+        if len(out) > max:
+            out.pop(0)
+    return {
+        "packets": out,
+        "total_matched": matched,
+        "dropped": matched - max if matched > max else 0,
+        "window": {"start": s, "end": e},
+    }
+
+
+def events_window(
+    start: Any = "-1h",
+    end: Any = "now",
+    *,
+    kind: str | None = None,
+    max: int = 200,
+) -> dict[str, Any]:
+    s = _parse_time(start)
+    e = _parse_time(end)
+    kinds = _split_set(kind)
+    base = get_recorder().base_dir
+    matched = 0
+    out: list[dict[str, Any]] = []
+    for rec in _iter_jsonl(base / "events.jsonl", since=s, until=e):
+        if kinds and rec.get("kind") not in kinds:
+            continue
+        matched += 1
+        out.append(rec)
+        if len(out) > max:
+            out.pop(0)
+    return {
+        "events": out,
+        "total_matched": matched,
+        "dropped": matched - max if matched > max else 0,
+        "window": {"start": s, "end": e},
+    }
+
+
+def export(
+    start: Any,
+    end: Any,
+    dest_dir: str,
+    *,
+    streams: list[str] | None = None,
+) -> dict[str, Any]:
+    """Bundle a slice of each requested stream into `dest_dir`.
+
+    For a notebook, a bug report, or a Datadog backfill. Output files
+    are uncompressed JSONL (callers gzip themselves if they want to).
+    """
+    s = _parse_time(start)
+    e = _parse_time(end)
+    selected = streams or ["logs", "telemetry", "packets", "events"]
+    dest = Path(dest_dir)
+    dest.mkdir(parents=True, exist_ok=True)
+
+    base = get_recorder().base_dir
+    paths: dict[str, str] = {}
+    for stream in selected:
+        src = base / f"{stream}.jsonl"
+        if not src.exists() and not list(base.glob(f"{stream}.*.jsonl.gz")):
+            continue
+        out_path = dest / f"{stream}.jsonl"
+        n = 0
+        with out_path.open("w", encoding="utf-8") as fh:
+            for rec in _iter_jsonl(src, since=s, until=e):
+                fh.write(json.dumps(rec, separators=(",", ":")) + "\n")
+                n += 1
+        paths[stream] = str(out_path)
+        paths[f"{stream}_count"] = str(n)
+    return {"dest_dir": str(dest), "paths": paths, "window": {"start": s, "end": e}}
+
+
+# -- helpers ------------------------------------------------------------
+
+
+def _split_set(value: str | None) -> set[str] | None:
+    if not value:
+        return None
+    return {v.strip() for v in value.split("|") if v.strip()}
+
+
+def _field_aliases(field: str) -> list[str]:
+    """Accept snake_case OR camelCase, plus a few legacy aliases."""
+    snake = field
+    camel = _snake_to_camel(field)
+    aliases = {snake, camel}
+    # Old protobuf fields (pre-LocalStats) used different names
+    legacy = {
+        "free_heap": ["free_heap", "freeHeap", "heap_free_bytes", "heapFreeBytes"],
+        "heap_free_bytes": [
+            "heap_free_bytes",
+            "heapFreeBytes",
+            "free_heap",
+            "freeHeap",
+        ],
+        "total_heap": ["total_heap", "totalHeap", "heap_total_bytes", "heapTotalBytes"],
+        "heap_total_bytes": [
+            "heap_total_bytes",
+            "heapTotalBytes",
+            "total_heap",
+            "totalHeap",
+        ],
+    }
+    if field in legacy:
+        aliases.update(legacy[field])
+    return list(aliases)
+
+
+def _snake_to_camel(name: str) -> str:
+    parts = name.split("_")
+    return parts[0] + "".join(p.title() for p in parts[1:])
+
+
+def _downsample(
+    points: list[tuple[float, float]], *, max_points: int
+) -> list[tuple[float, float]]:
+    if len(points) <= max_points:
+        return points
+    # Even-bucket mean. Preserves shape better than nth-sample picking.
+    n = len(points)
+    bucket = n / max_points
+    out: list[tuple[float, float]] = []
+    i = 0
+    for k in range(max_points):
+        end = int((k + 1) * bucket)
+        end = min(end, n)
+        if end <= i:
+            continue
+        chunk = points[i:end]
+        ts = chunk[len(chunk) // 2][0]
+        val = statistics.fmean(v for _, v in chunk)
+        out.append((ts, val))
+        i = end
+    return out
+
+
+def _slope_per_min(points: list[tuple[float, float]]) -> float | None:
+    """Least-squares slope (units per minute). None if too few points."""
+    if len(points) < 2:
+        return None
+    xs = [t for t, _ in points]
+    ys = [v for _, v in points]
+    n = len(xs)
+    mean_x = sum(xs) / n
+    mean_y = sum(ys) / n
+    num = sum((xs[i] - mean_x) * (ys[i] - mean_y) for i in range(n))
+    den = sum((x - mean_x) ** 2 for x in xs)
+    if den == 0:
+        return None
+    slope_per_sec = num / den
+    return slope_per_sec * 60.0
@@ -92,6 +92,7 @@ def _run_capturing(
    cwd: Path | None = None,
    timeout: float | None = None,
    tee_header: str | None = None,
+    extra_env: dict[str, str] | None = None,
 ) -> tuple[int, str, str, float]:
    """Run a subprocess, capture stdout+stderr, optionally tee to the flash log.

@@ -99,6 +100,9 @@ def _run_capturing(
    `subprocess.TimeoutExpired` on timeout (callers map this to their own
    domain-specific error).

+    `extra_env` merges into the subprocess environment (parent env stays
+    intact). Used for `PLATFORMIO_BUILD_FLAGS=-DDEBUG_HEAP=1` and similar.
+
    Fast path: `subprocess.run(capture_output=True)` when no flash log is
    configured (unchanged behavior).

@@ -110,6 +114,9 @@ def _run_capturing(
    """
    log_path = _flash_log_path()
    t0 = time.monotonic()
+    env = None
+    if extra_env:
+        env = {**os.environ, **extra_env}

    if log_path is None:
        # Fast path — unchanged.
@@ -119,6 +126,7 @@ def _run_capturing(
            capture_output=True,
            text=True,
            timeout=timeout,
+            env=env,
        )
        return (
            proc.returncode,
@@ -145,6 +153,7 @@ def _run_capturing(
        stderr=subprocess.PIPE,
        text=True,
        bufsize=1,  # line-buffered
+        env=env,
    )
    stdout_chunks: list[str] = []
    stderr_chunks: list[str] = []
@@ -232,12 +241,17 @@ def run(
    cwd: Path | None = None,
    timeout: float | None = TIMEOUT_DEFAULT,
    check: bool = True,
+    extra_env: dict[str, str] | None = None,
 ) -> PioResult:
    """Invoke `pio <args>` and return captured output.

    `cwd` defaults to the firmware root. `check=True` raises `PioError` on
    non-zero exit; set `check=False` to inspect `returncode` manually.

+    `extra_env` merges into the subprocess environment — used for
+    `PLATFORMIO_BUILD_FLAGS=-DDEBUG_HEAP=1` and similar build-time
+    toggles that can't be expressed as command-line args.
+
    If `MESHTASTIC_MCP_FLASH_LOG` is set, output is also tee'd to that file
    line-by-line as it arrives (for live flash progress in the TUI).
    """
@@ -250,6 +264,7 @@ def run(
            cwd=work_dir,
            timeout=timeout,
            tee_header=f"pio {' '.join(args)}",
+            extra_env=extra_env,
        )
    except subprocess.TimeoutExpired as exc:
        raise PioTimeout(f"pio {' '.join(args)} timed out after {timeout}s") from exc
@@ -0,0 +1,19 @@
+"""Persistent device-log capture.
+
+Singleton `Recorder` subscribes once to the meshtastic pubsub fan-out
+(`meshtastic.log.line`, `meshtastic.receive.*`, `meshtastic.connection.*`)
+and appends to four JSONL files under `mcp-server/.mtlog/`. Pubsub is
+process-global so a single subscription captures every active interface
+(serial / TCP / BLE) without any per-connection bookkeeping.
+
+The recorder is opt-in-by-import: importing this package is a no-op; call
+`get_recorder().start()` (which `server.py` does at FastMCP app init) to
+begin writing. `pause()` / `resume()` exist for the rare case the user
+wants a clean stretch of file (e.g. capturing a known-good baseline).
+"""
+
+from __future__ import annotations
+
+from .recorder import Recorder, get_recorder
+
+__all__ = ["Recorder", "get_recorder"]
@@ -0,0 +1,309 @@
+"""Best-effort parsers for log lines and telemetry packets.
+
+Two flavors of log line cross our pubsub subscription:
+  1. Text-mode path (debug_log_api disabled): the meshtastic Python lib
+     accumulates bytes between protobuf frames and emits the full
+     firmware-formatted line, e.g.
+         "INFO  | 12:34:56 12345 [Main] Booting"
+     — level, HH:MM:SS, uptime seconds, thread bracket, then message.
+  2. LogRecord protobuf path (debug_log_api enabled): the lib calls
+     `_handleLogLine(record.message)` with ONLY the message body. The
+     level/source/time fields on the LogRecord are dropped before
+     pubsub fan-out. We get e.g. just "Booting".
+
+Both arrive on `meshtastic.log.line`. The parser tries to recover a
+level + thread when the prefix is present and falls back to level=None
+otherwise. Consumers who want level filtering on protobuf-mode hosts
+should grep the raw `line` field instead.
+
+Telemetry: `meshtastic.receive.telemetry` packets carry one of several
+metric variants in `packet["decoded"]["telemetry"]`. We flatten the
+chosen variant into a {field: value} dict so callers don't have to
+know the protobuf shape.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# Match: LEVEL | HH:MM:SS UPTIME [Thread] message
+# HH:MM:SS may be ??:??:?? when RTC isn't valid. The level alternation
+# below is the canonical list — DebugConfiguration.h's MESHTASTIC_LOG_LEVEL_*
+# macros must stay in sync with these strings.
+_LINE_RE = re.compile(
+    r"""
+    ^
+    (?P<level>DEBUG|INFO\ |WARN\ |ERROR|CRIT\ |TRACE|HEAP\ )
+    \s*\|\s*
+    (?P<clock>(?:\d{2}:\d{2}:\d{2})|(?:\?{2}:\?{2}:\?{2}))
+    \s+
+    (?P<uptime>\d+)
+    \s+
+    (?:\[(?P<thread>[^\]]+)\]\s+)?
+    (?P<msg>.*)
+    $
+    """,
+    re.VERBOSE,
+)
+
+# DEBUG_HEAP build prepends `[heap N] ` to every message body, AFTER the
+# thread bracket. See src/RedirectablePrint.cpp:175.
+_HEAP_PREFIX_RE = re.compile(r"^\[heap\s+(?P<heap>\d+)\]\s+(?P<rest>.*)$")
+
+# OSThread leak/free detection. See src/concurrency/OSThread.cpp:89-91.
+# Format: "------ Thread NAME leaked heap A -> B (delta) ------"
+#         "++++++ Thread NAME freed heap A -> B (delta) ++++++"
+_THREAD_HEAP_RE = re.compile(
+    r"""
+    ^[\-+]+\s*
+    Thread\s+(?P<thread>\S+)\s+
+    (?P<kind>leaked|freed)\s+heap\s+
+    (?P<before>-?\d+)\s*->\s*(?P<after>-?\d+)\s+
+    \((?P<delta>-?\d+)\)
+    """,
+    re.VERBOSE,
+)
+
+# Power.cpp:908 periodic heap status (DEBUG_HEAP only).
+# Format: "Heap status: FREE/TOTAL bytes free (DELTA), running R/N threads"
+_HEAP_STATUS_RE = re.compile(
+    r"""
+    Heap\s+status:\s+
+    (?P<free>\d+)\s*/\s*(?P<total>\d+)\s+bytes\s+free
+    (?:\s+\((?P<delta>-?\d+)\))?
+    """,
+    re.VERBOSE,
+)
+
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+_HEAP_BRACKET_RE = re.compile(r"^heap\s+(?P<heap>\d+)$")
+
+
+def parse_log_line(line: str) -> dict[str, Any]:
+    """Best-effort decompose a raw firmware log line.
+
+    Returns a dict with at least `line` (the original, unmodified — ANSI
+    codes preserved for fidelity). Adds `level`, `tag`, `clock`,
+    `uptime_s`, and `msg` when the full prefix is present.
+
+    Handles two firmware quirks:
+      - LogRecord.message can carry ANSI color escapes from RedirectablePrint
+        (the BLE/StreamAPI path inherited the colored body in some builds).
+        We strip ANSI before regex matching so the prefix survives.
+      - DEBUG_HEAP injects `[heap N]` after the thread bracket. When NO
+        thread name is set, the heap takes the thread bracket position —
+        looks like `[heap 12345] msg`. We detect that shape and move it
+        out of `tag` and into `heap_free`.
+
+    DEBUG_HEAP-build extras (when `[heap N]` is injected): `heap_free`
+    (bytes), and when a `Thread X leaked|freed heap` line is recognized,
+    `heap_event` = {kind, thread, before, after, delta}.
+
+    Never raises.
+    """
+    out: dict[str, Any] = {"line": line}
+    if not line:
+        return out
+
+    # Strip ANSI escapes BEFORE any regex matching. The original `line`
+    # stays in `out["line"]` for fidelity / future grep.
+    clean = _ANSI_RE.sub("", line)
+
+    m = _LINE_RE.match(clean)
+    msg: str | None = None
+    if m:
+        level = m.group("level").rstrip()
+        out["level"] = level
+        out["clock"] = m.group("clock")
+        try:
+            out["uptime_s"] = int(m.group("uptime"))
+        except (TypeError, ValueError):
+            out["uptime_s"] = None
+        thread = m.group("thread")
+        if thread:
+            # If "thread" is actually the heap prefix taking the bracket
+            # position (DEBUG_HEAP build, no thread set), capture heap
+            # and leave tag unset.
+            hb = _HEAP_BRACKET_RE.match(thread.strip())
+            if hb:
+                try:
+                    out["heap_free"] = int(hb.group("heap"))
+                except (TypeError, ValueError):
+                    pass
+            else:
+                out["tag"] = thread
+        msg = m.group("msg")
+        out["msg"] = msg
+    else:
+        # No prefix — bare LogRecord.message body. Inspect the whole
+        # line for DEBUG_HEAP-style content; the heap-prefix and
+        # thread-leak patterns can survive on either path.
+        msg = clean
+
+    # DEBUG_HEAP per-line heap prefix: `[heap 92344] message`.
+    # Sits AFTER the thread bracket and BEFORE the message body, but
+    # for bare LogRecord lines it's at the start. Match it at the
+    # head of `msg`.
+    if msg:
+        hp = _HEAP_PREFIX_RE.match(msg)
+        if hp:
+            try:
+                out["heap_free"] = int(hp.group("heap"))
+            except (TypeError, ValueError):
+                pass
+            else:
+                # Strip the prefix from `msg` so a grep on the message
+                # body doesn't have to know about it.
+                out["msg"] = hp.group("rest")
+                msg = hp.group("rest")
+
+        # Thread-level leak/free detection.
+        thr = _THREAD_HEAP_RE.search(msg)
+        if thr:
+            try:
+                out["heap_event"] = {
+                    "kind": thr.group("kind"),
+                    "thread": thr.group("thread"),
+                    "before": int(thr.group("before")),
+                    "after": int(thr.group("after")),
+                    "delta": int(thr.group("delta")),
+                }
+            except (TypeError, ValueError):
+                pass
+
+        # Power.cpp periodic "Heap status: F/T bytes free (D), running ..."
+        hs = _HEAP_STATUS_RE.search(msg)
+        if hs:
+            try:
+                out["heap_free"] = int(hs.group("free"))
+                out["heap_total"] = int(hs.group("total"))
+                if hs.group("delta") is not None:
+                    out["heap_delta"] = int(hs.group("delta"))
+            except (TypeError, ValueError):
+                pass
+
+    return out
+
+
+# -- Telemetry ----------------------------------------------------------
+
+# Order matters: meshtastic-python decoded packets use the protobuf
+# `oneof variant` field name (snake_case) as the dict key.
+_TELEMETRY_VARIANTS = (
+    ("device_metrics", "device"),
+    ("local_stats", "local"),
+    ("environment_metrics", "environment"),
+    ("power_metrics", "power"),
+    ("air_quality_metrics", "airQuality"),
+    ("health_metrics", "health"),
+    ("host_metrics", "host"),
+)
+
+
+def extract_telemetry(packet: dict[str, Any]) -> dict[str, Any] | None:
+    """Pull the telemetry variant + flat fields out of a `meshtastic.receive.telemetry`
+    packet. Returns None when the shape isn't what we expect — so the
+    caller can fall back to a generic packets.jsonl row.
+    """
+    if not isinstance(packet, dict):
+        return None
+    decoded = packet.get("decoded")
+    if not isinstance(decoded, dict):
+        return None
+    telem = decoded.get("telemetry")
+    if not isinstance(telem, dict):
+        return None
+    # The Python lib produces dict-of-camelCase keys via MessageToDict.
+    # Try both camelCase and snake_case to be robust to lib version drift.
+    for snake, label in _TELEMETRY_VARIANTS:
+        camel = _snake_to_camel(snake)
+        for key in (snake, camel):
+            value = telem.get(key)
+            if isinstance(value, dict):
+                return {
+                    "variant": label,
+                    "fields": {k: _scalarize(v) for k, v in value.items()},
+                    "time": telem.get("time"),
+                }
+    return None
+
+
+def _snake_to_camel(name: str) -> str:
+    parts = name.split("_")
+    return parts[0] + "".join(p.title() for p in parts[1:])
+
+
+def _scalarize(value: Any) -> Any:
+    """Keep telemetry fields JSON-friendly. Lists/dicts pass through
+    untouched; bytes -> hex string; protobuf enums occasionally arrive
+    as ints (fine) or strings (also fine)."""
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return bytes(value).hex()
+    return value
+
+
+# -- Generic packet summary ---------------------------------------------
+
+
+def summarize_packet(
+    packet: dict[str, Any], *, payload_hex_len: int = 64
+) -> dict[str, Any]:
+    """Reduce a packet dict to a stable, queryable summary. Drops the
+    full payload bytes — the recorder records summaries, not pcaps.
+    """
+    if not isinstance(packet, dict):
+        return {"raw_type": type(packet).__name__}
+    decoded = packet.get("decoded") if isinstance(packet.get("decoded"), dict) else {}
+    portnum = decoded.get("portnum") if isinstance(decoded, dict) else None
+    payload = decoded.get("payload") if isinstance(decoded, dict) else None
+    payload_hex = None
+    payload_size = None
+    if isinstance(payload, (bytes, bytearray, memoryview)):
+        b = bytes(payload)
+        payload_size = len(b)
+        payload_hex = b[:payload_hex_len].hex() if b else ""
+    elif isinstance(payload, str):
+        # Some decoded payloads (text messages) come as decoded strings.
+        payload_size = len(payload)
+        payload_hex = None  # not bytes
+    return {
+        "from_node": packet.get("fromId") or packet.get("from"),
+        "to_node": packet.get("toId") or packet.get("to"),
+        "portnum": portnum,
+        "hop_limit": packet.get("hopLimit"),
+        "want_ack": packet.get("wantAck"),
+        "rx_rssi": packet.get("rxRssi"),
+        "rx_snr": packet.get("rxSnr"),
+        "channel": packet.get("channel"),
+        "id": packet.get("id"),
+        "payload_size": payload_size,
+        "payload_hex_prefix": payload_hex,
+    }
+
+
+# -- Interface identification ------------------------------------------
+
+
+def interface_label(interface: Any) -> dict[str, Any]:
+    """Stable identifier for the meshtastic interface that emitted an event.
+
+    Used as the `port`/`role` tag on every recorded row. SerialInterface
+    has `devPath`; TCPInterface has `hostname`+`portNumber`; BLEInterface
+    has `address`. Falls back to the class name when none of those exist.
+    """
+    if interface is None:
+        return {"port": None, "role": None}
+    dev_path = getattr(interface, "devPath", None)
+    if dev_path:
+        return {"port": str(dev_path), "role": "serial"}
+    hostname = getattr(interface, "hostname", None)
+    if hostname:
+        port_num = getattr(interface, "portNumber", None)
+        endpoint = f"tcp://{hostname}:{port_num}" if port_num else f"tcp://{hostname}"
+        return {"port": endpoint, "role": "tcp"}
+    address = getattr(interface, "address", None)
+    if address:
+        return {"port": str(address), "role": "ble"}
+    return {"port": type(interface).__name__, "role": None}
@@ -0,0 +1,467 @@
+"""Process-global recorder singleton.
+
+Subscribes once to the meshtastic pubsub fan-out and writes four append-only
+JSONL streams under `mcp-server/.mtlog/`. The pubsub fan-out is
+process-global — a single subscription captures every active interface
+without per-connection bookkeeping.
+
+Files:
+  logs.jsonl      — every `meshtastic.log.line` event (best-effort prefix
+                    parsed for level/tag/uptime; raw `line` always preserved)
+  telemetry.jsonl — `meshtastic.receive.telemetry` packets, flattened by
+                    variant (device / local / environment / power / etc.)
+  packets.jsonl   — every other `meshtastic.receive.*` packet, summarized
+                    (portnum, hops, RSSI/SNR, payload size + 64-byte hex)
+  events.jsonl    — connection lifecycle, node-DB updates, and manual
+                    `mark_event` rows. Lower volume; useful for aligning
+                    timelines.
+
+Pause/resume: `pause()` flips a flag; subscriptions stay registered. The
+write methods short-circuit when paused, so we don't lose ordering when
+resumed (we just have a gap). No queueing.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from . import parsers
+from .rotating import _RotatingJsonl
+
+_DEFAULT_DIR = Path(__file__).resolve().parents[3] / ".mtlog"
+log = logging.getLogger(__name__)
+
+
+class Recorder:
+    """Singleton write-side of the persistent log capture system."""
+
+    def __init__(self, base_dir: Path | None = None) -> None:
+        self.base_dir = Path(base_dir) if base_dir else _DEFAULT_DIR
+        self._lock = threading.RLock()
+        self._started = False
+        self._paused = False
+        self._pause_reason: str | None = None
+        self._started_at: float | None = None
+        self._handlers: list[tuple[str, Any]] = []
+        self._files: dict[str, _RotatingJsonl] = {}
+
+    # -- lifecycle ----------------------------------------------------
+
+    def start(self) -> None:
+        """Idempotent. Safe to call from FastMCP app startup."""
+        with self._lock:
+            if self._started:
+                return
+            self.base_dir.mkdir(parents=True, exist_ok=True)
+            self._files = {
+                "logs": _RotatingJsonl(self.base_dir / "logs.jsonl"),
+                "telemetry": _RotatingJsonl(self.base_dir / "telemetry.jsonl"),
+                "packets": _RotatingJsonl(self.base_dir / "packets.jsonl"),
+                "events": _RotatingJsonl(self.base_dir / "events.jsonl"),
+            }
+            self._wire_pubsub()
+            self._started = True
+            self._started_at = time.time()
+        # Write the recorder_start marker after the initialization block.
+        # `_write_event()` re-checks recorder state via `_files_snapshot()`,
+        # so keeping this out of the setup block avoids nested lifecycle work.
+        self._write_event(kind="recorder_start", label="recorder_started")
+
+    def stop(self) -> None:
+        with self._lock:
+            if not self._started:
+                return
+            self._unwire_pubsub()
+            for f in self._files.values():
+                f.close()
+            self._files = {}
+            self._started = False
+
+    def pause(self, reason: str | None = None) -> None:
+        # Write the pause marker BEFORE flipping the flag — `_write_event`
+        # short-circuits when paused, so the order matters for this event
+        # to actually land in events.jsonl.
+        self._write_event(
+            kind="recorder_pause",
+            label="paused",
+            note=reason,
+        )
+        with self._lock:
+            self._paused = True
+            self._pause_reason = reason
+
+    def resume(self) -> None:
+        # Mirror of `pause()`: clear the flag first, then write the marker
+        # so it isn't suppressed by the still-paused short-circuit.
+        with self._lock:
+            self._paused = False
+            self._pause_reason = None
+        self._write_event(kind="recorder_resume", label="resumed")
+
+    # -- pubsub wiring ------------------------------------------------
+
+    def _wire_pubsub(self) -> None:
+        from pubsub import pub  # type: ignore[import-untyped]
+
+        # Subscribers — one per topic. Each pubsub publisher sends
+        # keyword args matching its handler's signature; pubsub
+        # introspects the function signature to route args.
+        bindings = [
+            ("meshtastic.log.line", self._on_log_line),
+            ("meshtastic.serial.line", self._on_serial_line),
+            ("meshtastic.receive", self._on_receive),
+            ("meshtastic.receive.telemetry", self._on_telemetry),
+            ("meshtastic.connection.established", self._on_connection_established),
+            ("meshtastic.connection.lost", self._on_connection_lost),
+            ("meshtastic.node.updated", self._on_node_updated),
+        ]
+        for topic, handler in bindings:
+            try:
+                pub.subscribe(handler, topic)
+                self._handlers.append((topic, handler))
+            except Exception as exc:
+                # If pubsub refuses one binding (signature mismatch on
+                # an old lib version), log it and keep the rest.
+                log.warning("Recorder failed to subscribe to %s: %s", topic, exc)
+
+    def _unwire_pubsub(self) -> None:
+        from pubsub import pub  # type: ignore[import-untyped]
+
+        for topic, handler in self._handlers:
+            try:
+                pub.unsubscribe(handler, topic)
+            except Exception:
+                pass
+        self._handlers.clear()
+
+    # -- handlers -----------------------------------------------------
+    #
+    # Pubsub callbacks must never raise. Every handler is wrapped in a
+    # try/except that swallows so a bug here can't take down the
+    # SerialInterface receive thread.
+    #
+    # Threading: handlers fire on whatever thread the meshtastic library
+    # dispatches from (varies by interface), while `stop()` clears
+    # `self._files` under `self._lock`. We snapshot `_files` under the
+    # lock at the top of each handler so a concurrent stop can't
+    # KeyError us mid-write. The actual file write goes through
+    # `_RotatingJsonl` which has its own lock.
+
+    def _files_snapshot(self) -> dict[str, _RotatingJsonl] | None:
+        """Atomic-ish view of `self._files`. Returns None when the recorder
+        is paused or stopped, so handlers can early-exit cleanly without
+        racing `stop()`'s clear."""
+        with self._lock:
+            if not self._started or self._paused:
+                return None
+            return dict(self._files)
+
+    def _on_log_line(self, line: str, interface: Any = None) -> None:
+        files = self._files_snapshot()
+        if files is None:
+            return
+        try:
+            tags = parsers.interface_label(interface)
+            parsed = parsers.parse_log_line(str(line))
+            ts = time.time()
+            record: dict[str, Any] = {
+                "ts": ts,
+                "port": tags["port"],
+                "role": tags["role"],
+                "level": parsed.get("level"),
+                "tag": parsed.get("tag"),
+                "uptime_s": parsed.get("uptime_s"),
+                "line": parsed["line"],
+            }
+            # DEBUG_HEAP enrichments (only present when the firmware
+            # was built with -DDEBUG_HEAP=1). Surface as first-class
+            # fields so logs_window can grep/filter on them and so
+            # heap_free synthesizes a telemetry point below.
+            if "heap_free" in parsed:
+                record["heap_free"] = parsed["heap_free"]
+            if "heap_total" in parsed:
+                record["heap_total"] = parsed["heap_total"]
+            if "heap_delta" in parsed:
+                record["heap_delta"] = parsed["heap_delta"]
+            heap_event = parsed.get("heap_event")
+            if heap_event:
+                record["heap_event"] = heap_event
+            files["logs"].write(record)
+
+            # If the line carried a heap snapshot, also write it as a
+            # synthesized LocalStats-shaped row so telemetry_timeline
+            # picks it up at log cadence (much higher resolution than
+            # the ~60 s LocalStats packet). Tagged source=debug_heap so
+            # consumers can filter if mixing scales is unwanted.
+            heap_free = parsed.get("heap_free")
+            if isinstance(heap_free, int):
+                fields: dict[str, Any] = {"heap_free_bytes": heap_free}
+                heap_total = parsed.get("heap_total")
+                if isinstance(heap_total, int):
+                    fields["heap_total_bytes"] = heap_total
+                files["telemetry"].write(
+                    {
+                        "ts": ts,
+                        "port": tags["port"],
+                        "role": tags["role"],
+                        "from_node": None,
+                        "variant": "local",
+                        "fields": fields,
+                        "source": "debug_heap",
+                    }
+                )
+        except Exception:
+            pass
+
+    def _on_serial_line(self, line: str, port: str | None = None) -> None:
+        """Text-mode passive tap. Fired from `serial_session._drain` when a
+        `pio device monitor` subprocess is running.
+
+        Same parse + heap-synthesis path as `_on_log_line`, but receives
+        the raw text-formatted line (full level/clock/uptime/thread/`[heap N]`/
+        body). On DEBUG_HEAP builds in text mode this gives us per-log-line
+        heap data — far higher cadence than LocalStats, and works without
+        protobuf API mode (no SerialInterface required).
+        """
+        files = self._files_snapshot()
+        if files is None:
+            return
+        try:
+            parsed = parsers.parse_log_line(str(line))
+            ts = time.time()
+            record: dict[str, Any] = {
+                "ts": ts,
+                "port": port,
+                "role": "serial_session",
+                "level": parsed.get("level"),
+                "tag": parsed.get("tag"),
+                "uptime_s": parsed.get("uptime_s"),
+                "line": parsed["line"],
+            }
+            if "heap_free" in parsed:
+                record["heap_free"] = parsed["heap_free"]
+            if "heap_total" in parsed:
+                record["heap_total"] = parsed["heap_total"]
+            if "heap_delta" in parsed:
+                record["heap_delta"] = parsed["heap_delta"]
+            heap_event = parsed.get("heap_event")
+            if heap_event:
+                record["heap_event"] = heap_event
+            files["logs"].write(record)
+
+            # Synthesize a heap_free telemetry sample whenever the line
+            # carries one — same logic as _on_log_line, tagged source so
+            # consumers can distinguish text-mode tap from protobuf path.
+            heap_free = parsed.get("heap_free")
+            if isinstance(heap_free, int):
+                fields: dict[str, Any] = {"heap_free_bytes": heap_free}
+                heap_total = parsed.get("heap_total")
+                if isinstance(heap_total, int):
+                    fields["heap_total_bytes"] = heap_total
+                files["telemetry"].write(
+                    {
+                        "ts": ts,
+                        "port": port,
+                        "role": "serial_session",
+                        "from_node": None,
+                        "variant": "local",
+                        "fields": fields,
+                        "source": "debug_heap_serial",
+                    }
+                )
+        except Exception:
+            pass
+
+    def _on_telemetry(self, packet: dict[str, Any], interface: Any = None) -> None:
+        files = self._files_snapshot()
+        if files is None:
+            return
+        try:
+            tags = parsers.interface_label(interface)
+            extracted = parsers.extract_telemetry(packet)
+            if extracted is None:
+                # Couldn't extract a known variant — fall through to the
+                # generic `_on_receive` path, which will still fire for
+                # this packet via the parent topic.
+                return
+            record = {
+                "ts": time.time(),
+                "port": tags["port"],
+                "role": tags["role"],
+                "from_node": packet.get("fromId") or packet.get("from"),
+                "variant": extracted["variant"],
+                "fields": extracted["fields"],
+                "device_time": extracted.get("time"),
+            }
+            files["telemetry"].write(record)
+        except Exception:
+            pass
+
+    def _on_receive(self, packet: dict[str, Any], interface: Any = None) -> None:
+        # Generic-receive fires for EVERY packet. Telemetry packets get
+        # recorded twice (here and in _on_telemetry) — that's intentional:
+        # packets.jsonl is the universal record, telemetry.jsonl is the
+        # structured timeseries view.
+        files = self._files_snapshot()
+        if files is None:
+            return
+        try:
+            tags = parsers.interface_label(interface)
+            summary = parsers.summarize_packet(packet)
+            record = {
+                "ts": time.time(),
+                "port": tags["port"],
+                "role": tags["role"],
+                **summary,
+            }
+            files["packets"].write(record)
+        except Exception:
+            pass
+
+    def _on_connection_established(self, interface: Any = None) -> None:
+        self._write_event(
+            kind="connection_established",
+            interface=interface,
+        )
+
+    def _on_connection_lost(self, interface: Any = None) -> None:
+        self._write_event(
+            kind="connection_lost",
+            interface=interface,
+        )
+
+    def _on_node_updated(
+        self, node: dict[str, Any] | None = None, interface: Any = None
+    ) -> None:
+        # Lower-volume than packets but informative — node ID, hops away,
+        # last heard. Skip the user dict if absent.
+        try:
+            user = (node or {}).get("user") if isinstance(node, dict) else None
+            self._write_event(
+                kind="node_updated",
+                interface=interface,
+                data={
+                    "num": (node or {}).get("num"),
+                    "id": (user or {}).get("id"),
+                    "short": (user or {}).get("shortName"),
+                    "long": (user or {}).get("longName"),
+                    "hops_away": (node or {}).get("hopsAway"),
+                    "snr": (node or {}).get("snr"),
+                    "last_heard": (node or {}).get("lastHeard"),
+                },
+            )
+        except Exception:
+            pass
+
+    # -- public write helpers -----------------------------------------
+
+    def mark_event(
+        self,
+        label: str,
+        note: str | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """User-facing marker. Writes to events.jsonl AND emits a
+        synthetic logs.jsonl row tagged level=MARK so timelines align.
+        """
+        ts = self._write_event(kind="mark", label=label, note=note, data=data)
+        # Mirror into logs so a single logs_window grep finds it.
+        files = self._files_snapshot()
+        if files is not None:
+            try:
+                files["logs"].write(
+                    {
+                        "ts": ts,
+                        "port": None,
+                        "role": "marker",
+                        "level": "MARK",
+                        "tag": "mark_event",
+                        "line": f"[mark] {label}" + (f" — {note}" if note else ""),
+                    }
+                )
+            except Exception:
+                pass
+        return {"ts": ts, "label": label}
+
+    def _write_event(
+        self,
+        *,
+        kind: str,
+        label: str | None = None,
+        note: str | None = None,
+        interface: Any = None,
+        data: dict[str, Any] | None = None,
+    ) -> float:
+        ts = time.time()
+        # Lifecycle markers (recorder_start, recorder_pause, recorder_resume)
+        # arrive at choreographed moments — `pause()` writes BEFORE flipping
+        # the flag and `resume()` writes AFTER clearing it, so those calls
+        # see _paused=False here. Other event kinds short-circuit when
+        # paused via the snapshot guard below.
+        files = self._files_snapshot()
+        if files is None:
+            return ts
+        try:
+            tags = parsers.interface_label(interface)
+            files["events"].write(
+                {
+                    "ts": ts,
+                    "kind": kind,
+                    "label": label,
+                    "note": note,
+                    "port": tags["port"],
+                    "role": tags["role"],
+                    "data": data,
+                }
+            )
+        except Exception:
+            pass
+        return ts
+
+    # -- introspection ------------------------------------------------
+
+    def status(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "running": self._started,
+                "paused": self._paused,
+                "pause_reason": self._pause_reason,
+                "started_at": self._started_at,
+                "base_dir": str(self.base_dir),
+                "files": {name: f.status() for name, f in self._files.items()},
+            }
+
+    def force_rotate_all(self) -> dict[str, Any]:
+        """Test/admin hook: rotate every stream right now."""
+        with self._lock:
+            files = list(self._files.values())
+        for f in files:
+            f.force_rotate()
+        # `status()` re-acquires `self._lock`; release before calling it.
+        return self.status()
+
+
+# -- module-level singleton accessor ------------------------------------
+
+_INSTANCE_LOCK = threading.Lock()
+_INSTANCE: Recorder | None = None
+
+
+def get_recorder() -> Recorder:
+    """Return the process-global Recorder. Created on first call.
+
+    Honors `MESHTASTIC_MCP_LOG_DIR` env var for the base directory
+    (used by tests to redirect to a tmpdir).
+    """
+    global _INSTANCE
+    with _INSTANCE_LOCK:
+        if _INSTANCE is None:
+            override = os.environ.get("MESHTASTIC_MCP_LOG_DIR")
+            base = Path(override) if override else None
+            _INSTANCE = Recorder(base_dir=base)
+        return _INSTANCE
@@ -0,0 +1,163 @@
+"""Append-only JSONL writer with size-capped rotation.
+
+A `_RotatingJsonl` owns one live `.jsonl` file. Writes are line-delimited
+JSON objects (one row per call). When the live file exceeds `max_bytes`,
+it is closed, gzipped to `<name>.YYYYMMDD-HHMMSS-uuuuuu-NNNNN.jsonl.gz`,
+and the live file resets to empty. Old archives past `keep_archives` are
+unlinked oldest-first.
+
+Size check is amortized — `os.fstat` runs every `check_every` writes,
+not per-write, so the hot path stays at one `fh.write` + one `fh.flush`.
+
+Threading: every public method acquires `self._lock`. The recorder runs
+several pubsub handlers on whatever thread the meshtastic library
+dispatches from (varies by interface), and queries from MCP tool calls
+arrive on the FastMCP request thread, so this lock is not optional.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import shutil
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+class _RotatingJsonl:
+    """Append-only JSONL with size rotation. Thread-safe."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        max_bytes: int = 100 * 1024 * 1024,
+        keep_archives: int = 5,
+        check_every: int = 1000,
+    ) -> None:
+        self.path = path
+        self.max_bytes = max_bytes
+        self.keep_archives = keep_archives
+        self.check_every = check_every
+        self._lock = threading.Lock()
+        self._fh: Any = None
+        self._writes_since_check = 0
+        self._rotations = 0
+        self._lines_written = 0
+        self._last_ts: float | None = None
+        self._open()
+
+    # -- lifecycle ----------------------------------------------------
+
+    def _open(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._fh = self.path.open("a", encoding="utf-8")
+
+    def close(self) -> None:
+        with self._lock:
+            if self._fh is not None:
+                try:
+                    self._fh.close()
+                finally:
+                    self._fh = None
+
+    # -- write --------------------------------------------------------
+
+    def write(self, record: dict[str, Any]) -> None:
+        """Append one JSON object as a line. Triggers rotation if oversized."""
+        line = json.dumps(record, separators=(",", ":"), default=str) + "\n"
+        with self._lock:
+            if self._fh is None:
+                return
+            try:
+                self._fh.write(line)
+                self._fh.flush()
+            except Exception:
+                # Best-effort: a failed write must not crash the pubsub
+                # handler. Caller has no way to react anyway.
+                return
+            self._lines_written += 1
+            ts = record.get("ts")
+            if isinstance(ts, (int, float)):
+                self._last_ts = float(ts)
+            self._writes_since_check += 1
+            if self._writes_since_check >= self.check_every:
+                self._writes_since_check = 0
+                self._maybe_rotate()
+
+    # -- rotation -----------------------------------------------------
+
+    def _maybe_rotate(self) -> None:
+        # Caller holds self._lock.
+        try:
+            size = os.fstat(self._fh.fileno()).st_size
+        except OSError:
+            return
+        if size < self.max_bytes:
+            return
+        self._rotate_locked()
+
+    def _rotate_locked(self) -> None:
+        # Close, gzip-rename, reopen empty, prune oldest archives.
+        try:
+            self._fh.close()
+        except Exception:
+            pass
+        self._fh = None
+        # Microsecond-resolution timestamp + per-instance counter so back-
+        # to-back rotations (small max_bytes, repeated `force_rotate()`,
+        # or chatty test loops) get unique archive filenames. The lex
+        # sort order of `YYYYMMDD-HHMMSS-uuuuuu-NNNNN` is chronological,
+        # which `_prune_archives()` and `log_query._iter_jsonl()` both
+        # rely on.
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+        archive = self.path.with_suffix(f".{stamp}-{self._rotations:05d}.jsonl.gz")
+        try:
+            with self.path.open("rb") as src, gzip.open(archive, "wb") as dst:
+                shutil.copyfileobj(src, dst, length=1024 * 1024)
+            self.path.unlink()
+        except Exception:
+            # Rotation is best-effort. If gzip fails, leave the file
+            # in place and re-open it; we'll try again next check.
+            pass
+        self._open()
+        self._rotations += 1
+        self._prune_archives()
+
+    def _prune_archives(self) -> None:
+        # Match siblings of self.path.name with `.jsonl.gz` suffix.
+        prefix = self.path.stem  # "logs" for "logs.jsonl"
+        # Archive filenames are already lexicographically chronological.
+        # Prune by name, not mtime, so copied/restored files don't reorder.
+        archives = sorted(self.path.parent.glob(f"{prefix}.*.jsonl.gz"))
+        excess = len(archives) - self.keep_archives
+        for old in archives[: max(0, excess)]:
+            try:
+                old.unlink()
+            except OSError:
+                pass
+
+    def force_rotate(self) -> None:
+        """Test/admin hook: rotate immediately regardless of size."""
+        with self._lock:
+            if self._fh is not None:
+                self._rotate_locked()
+
+    # -- introspection ------------------------------------------------
+
+    def status(self) -> dict[str, Any]:
+        with self._lock:
+            try:
+                size = os.fstat(self._fh.fileno()).st_size if self._fh else 0
+            except OSError:
+                size = 0
+            return {
+                "path": str(self.path),
+                "size": size,
+                "lines": self._lines_written,
+                "last_ts": self._last_ts,
+                "rotations": self._rotations,
+            }
@@ -46,7 +46,23 @@ class SerialSession:


 def _drain(session: SerialSession) -> None:
-    """Reader thread: line-by-line pull stdout into buffer."""
+    """Reader thread: line-by-line pull stdout into buffer.
+
+    Each line is also published to the `meshtastic.serial.line` pubsub
+    topic so the persistent recorder can capture it without holding its
+    own port. This is the text-mode tap path: when no SerialInterface is
+    open, the firmware emits full formatted lines (level + clock + uptime
+    + thread + `[heap N]` prefix on DEBUG_HEAP builds + body), and we
+    fan them out to whoever is listening. Pubsub is best-effort —
+    publish failures must never block the reader.
+    """
+    # Lazy import: pubsub isn't required just to import this module
+    # (e.g., during static analysis), and we want a clean test surface.
+    try:
+        from pubsub import pub  # type: ignore[import-untyped]
+    except Exception:  # pragma: no cover - defensive
+        pub = None
+
    assert session.proc.stdout is not None
    try:
        for line in session.proc.stdout:
@@ -54,6 +70,16 @@ def _drain(session: SerialSession) -> None:
            with session.lock:
                session.buffer.append(line_stripped)
                session.total_lines += 1
+            if pub is not None:
+                try:
+                    pub.sendMessage(
+                        "meshtastic.serial.line",
+                        line=line_stripped,
+                        port=session.port,
+                    )
+                except Exception:
+                    # A subscriber raising must not break the reader.
+                    pass
    except Exception:  # pragma: no cover - defensive
        pass
    finally:
@@ -71,6 +97,10 @@ def open_session(
    If `env` is supplied, pio resolves baud and filters from platformio.ini.
    Otherwise uses the supplied `baud` and `filters` (default `['direct']`).
    """
+    # Lazy import to avoid circular: registry imports serial_session.
+    from . import connection
+
+    connection.reject_if_tcp(port, "serial_open")
    args = ["device", "monitor", "--port", port, "--no-reconnect"]
    effective_filters: list[str]
    effective_baud: int = baud
@@ -6,6 +6,7 @@ etc.). Business logic does not live here.

 from __future__ import annotations

+import logging
 from typing import Any

 from mcp.server.fastmcp import FastMCP
@@ -14,17 +15,38 @@ from . import (
    admin,
    boards,
    devices,
+    fixtures,
    flash,
    hw_tools,
    info,
+    log_query,
    registry,
    serial_session,
 )
 from . import userprefs as userprefs_mod
+from .recorder import get_recorder
+
+log = logging.getLogger(__name__)

 app = FastMCP("meshtastic-mcp")


+def _start_recorder() -> None:
+    # Persistent device-log capture. Starts on first import — pubsub fan-out
+    # is process-global, so subscribing here captures every active interface
+    # (whether opened by an MCP tool, a pytest fixture, or a serial_session).
+    # Files land in mcp-server/.mtlog/ (gitignored). See recorder/recorder.py
+    # for the full design. Recorder startup is best-effort: an unwritable
+    # log dir or pubsub mismatch should not take the MCP server down.
+    try:
+        get_recorder().start()
+    except Exception as exc:
+        log.warning("Failed to start persistent recorder: %s", exc)
+
+
+_start_recorder()
+
+
 # ---------- Discovery & metadata ------------------------------------------


@@ -75,6 +97,7 @@ def build(
    env: str,
    with_manifest: bool = True,
    userprefs: dict[str, Any] | None = None,
+    build_flags: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
    """Build firmware for one env via `pio run -e <env>`.

@@ -86,8 +109,21 @@ def build(
    build via userPrefs.jsonc injection. The file is restored after the build
    completes. Use `userprefs_manifest` to discover available keys. Use
    `userprefs_set` for persistent changes.
+
+    `build_flags` (optional): dict of `-D<NAME>=<VALUE>` macros for this build
+    only, injected via `PLATFORMIO_BUILD_FLAGS`. Common pattern:
+    `build_flags={"DEBUG_HEAP": 1}` enables per-thread leak detection + a
+    `[heap N]` prefix on every log line. The recorder picks the prefix up
+    automatically and synthesizes a high-resolution heap timeline that
+    `telemetry_timeline(field="free_heap")` can read alongside the normal
+    ~60 s LocalStats packets. Pair with `/leakhunt` for classification.
    """
-    return flash.build(env, with_manifest=with_manifest, userprefs_overrides=userprefs)
+    return flash.build(
+        env,
+        with_manifest=with_manifest,
+        userprefs_overrides=userprefs,
+        build_flags=build_flags,
+    )


@app.tool()
@@ -105,6 +141,7 @@ def pio_flash(
    port: str,
    confirm: bool = False,
    userprefs: dict[str, Any] | None = None,
+    build_flags: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
    """Flash firmware via `pio run -e <env> -t upload --upload-port <port>`.

@@ -114,8 +151,19 @@ def pio_flash(

    `userprefs` (optional): dict of `USERPREFS_<KEY>: value` baked into this
    build via userPrefs.jsonc injection; restored after upload.
+
+    `build_flags` (optional): dict of `-D<NAME>=<VALUE>` macros for the
+    rebuild-before-upload, e.g. `{"DEBUG_HEAP": 1}`. Required for the flags
+    to actually land in the uploaded firmware — without it, the implicit
+    rebuild relinks without the env var and silently drops them.
    """
-    return flash.flash(env, port, confirm=confirm, userprefs_overrides=userprefs)
+    return flash.flash(
+        env,
+        port,
+        confirm=confirm,
+        userprefs_overrides=userprefs,
+        build_flags=build_flags,
+    )


@app.tool()
@@ -734,3 +782,227 @@ def picotool_load(uf2_path: str, confirm: bool = False) -> dict[str, Any]:
 def picotool_raw(args: list[str], confirm: bool = False) -> dict[str, Any]:
    """Pass-through to `picotool`. load/reboot/save/erase require confirm=True."""
    return hw_tools.picotool_raw(args, confirm=confirm)
+
+
+# ---------- Persistent device-log capture (recorder) ----------------------
+#
+# The recorder is autouse — it starts at server import and continuously
+# writes every meshtastic pubsub event to JSONL files under .mtlog/. These
+# tools are query-only over those files, plus a few lifecycle controls.
+
+
+@app.tool()
+def logs_window(
+    start: str = "-15m",
+    end: str = "now",
+    grep: str | None = None,
+    level: str | None = None,
+    tag: str | None = None,
+    port: str | None = None,
+    max_lines: int = 200,
+) -> dict[str, Any]:
+    """Recent firmware log lines from the persistent recorder.
+
+    Filters by time window, regex over the line, level (single or
+    pipe-separated set like "WARN|ERROR|CRIT"), thread-name tag, and
+    interface port. Returns up to max_lines most-recent matches.
+
+    Time strings: "-15m", "-2h", "-3d", "now", or ISO 8601.
+
+    Note: lines arriving via the LogRecord protobuf path (when
+    set_debug_log_api(True) is on) come without level prefix — the
+    meshtastic Python lib drops record.level before fan-out. For those,
+    `level` filter won't match; use `grep` instead.
+    """
+    return log_query.logs_window(
+        start=start,
+        end=end,
+        grep=grep,
+        level=level,
+        tag=tag,
+        port=port,
+        max_lines=max_lines,
+    )
+
+
+@app.tool()
+def telemetry_timeline(
+    window: str = "1h",
+    variant: str = "local",
+    field: str = "free_heap",
+    port: str | None = None,
+    max_points: int = 200,
+) -> dict[str, Any]:
+    """Time series of one telemetry field, downsampled to <= max_points.
+
+    `variant` ∈ device, local, environment, power, airQuality, health, host.
+    `field` accepts snake_case or camelCase; common aliases (free_heap ↔
+    heap_free_bytes) are normalized.
+
+    Returns slope_per_min (linear-regression slope, units/minute) so a
+    leak detector can read one number — negative slope on free_heap over
+    a long window indicates a real leak.
+
+    LocalStats variant ("local") cadence is ~60 s (whatever the device's
+    `device_update_interval` is set to), so a 1 h window gives ~60 raw
+    points. Bucket-mean downsampling preserves shape.
+    """
+    return log_query.telemetry_timeline(
+        window=window,
+        variant=variant,
+        field=field,
+        port=port,
+        max_points=max_points,
+    )
+
+
+@app.tool()
+def packets_window(
+    start: str = "-5m",
+    end: str = "now",
+    portnum: str | None = None,
+    from_node: str | None = None,
+    to_node: str | None = None,
+    max: int = 200,
+) -> dict[str, Any]:
+    """Recent mesh packets recorded by the recorder.
+
+    Each row is a summary (portnum, from/to, hop_limit, RSSI/SNR, payload
+    size + first 64 bytes hex) — full payload bytes are not stored.
+    `portnum` accepts a pipe-separated set like "TEXT_MESSAGE_APP|POSITION_APP".
+    """
+    return log_query.packets_window(
+        start=start,
+        end=end,
+        portnum=portnum,
+        from_node=from_node,
+        to_node=to_node,
+        max=max,
+    )
+
+
+@app.tool()
+def events_window(
+    start: str = "-1h",
+    end: str = "now",
+    kind: str | None = None,
+    max: int = 200,
+) -> dict[str, Any]:
+    """Return recorder events: connection lifecycle, node updates, and `mark_event` markers.
+
+    `kind` ∈ recorder_start, recorder_pause, recorder_resume,
+    connection_established, connection_lost, node_updated, mark.
+    Pipe-separated sets ("connection_lost|connection_established") work.
+    """
+    return log_query.events_window(start=start, end=end, kind=kind, max=max)
+
+
+@app.tool()
+def mark_event(
+    label: str,
+    note: str | None = None,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Drop a named marker into events.jsonl AND logs.jsonl.
+
+    Useful for aligning a timeline around a known stimulus: call before
+    and after a stress workload, then query telemetry_timeline /
+    logs_window with the markers' timestamps as bounds.
+
+    The marker also lands in logs.jsonl with level=MARK so a single
+    grep over logs picks it up.
+    """
+    return get_recorder().mark_event(label=label, note=note, data=data)
+
+
+@app.tool()
+def recorder_status() -> dict[str, Any]:
+    """Return recorder runtime info: running, paused, file sizes, last_ts per stream.
+
+    Use this to sanity-check that capture is working before you trust a
+    `logs_window` / `telemetry_timeline` result.
+    """
+    return get_recorder().status()
+
+
+@app.tool()
+def recorder_pause(reason: str | None = None) -> dict[str, Any]:
+    """Pause writes to all four streams. Pubsub subscriptions stay active —
+    we just drop events on the floor while paused. Resume with `recorder_resume`.
+
+    Use when capturing a known-good baseline that you don't want to
+    pollute with pre-test noise. Default state is recording; this is
+    rarely needed.
+    """
+    get_recorder().pause(reason=reason)
+    return {"ok": True, "paused": True, "reason": reason}
+
+
+@app.tool()
+def recorder_resume() -> dict[str, Any]:
+    """Resume writes after `recorder_pause`. No-op if already running."""
+    get_recorder().resume()
+    return {"ok": True, "paused": False}
+
+
+@app.tool()
+def recorder_export(
+    start: str,
+    end: str,
+    dest_dir: str,
+    streams: list[str] | None = None,
+) -> dict[str, Any]:
+    """Bundle a slice of the recorder's streams into `dest_dir`.
+
+    Writes one uncompressed JSONL per requested stream (logs / telemetry /
+    packets / events). Useful for: attaching to a bug report, feeding a
+    notebook, or backfilling Datadog after the fact.
+    """
+    return log_query.export(
+        start=start,
+        end=end,
+        dest_dir=dest_dir,
+        streams=streams,
+    )
+
+
+# ---------- Fixture / test-data push --------------------------------------
+
+
+@app.tool()
+def push_fake_nodedb(
+    size: int,
+    target: str = "portduino",
+    port: str | None = None,
+    portduino_config: str = "default",
+    backup_existing: bool = True,
+    confirm: bool = False,
+    reboot_after: bool = True,
+    custom_seed_jsonl: str | None = None,
+) -> dict[str, Any]:
+    """Push a fake-NodeDB v25 fixture (250/500/1000/2000 nodes) onto a device.
+
+    Two transports:
+      target="portduino" — file copy to ~/.portduino/<portduino_config>/prefs/nodes.proto.
+                            Fast, no device connection needed.
+      target="hardware"  — XModem upload over serial/BLE to /prefs/nodes.proto.
+                            Requires `port` + `confirm=True`. Triggers a reboot
+                            so loadFromDisk picks up the new file at next boot.
+
+    Compiles a fresh-timestamp proto from the committed JSONL seed under
+    test/fixtures/nodedb/seed_v25_<N>.jsonl each invocation, so the loaded
+    NodeDB always looks "recent" to the connecting phone. Structural data
+    (names, IDs, positions, telemetries) is deterministic per the seed.
+
+    Override the JSONL via `custom_seed_jsonl` to push a hand-edited scenario.
+    """
+    return fixtures.push_fake_nodedb(
+        size=size,
+        target=target,  # type: ignore[arg-type]
+        port=port,
+        portduino_config=portduino_config,
+        backup_existing=backup_existing,
+        confirm=confirm,
+        reboot_after=reboot_after,
+        custom_seed_jsonl=custom_seed_jsonl,
+    )
@@ -0,0 +1,88 @@
+"""Unit tests for the `build_flags` injection on `flash.build()`.
+
+We don't actually run pio here — too slow, requires hardware-aware envs.
+We test the translation layer (`_build_flags_env`) and that the env vars
+are threaded through pio.run correctly via mock.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from meshtastic_mcp import flash, pio
+
+
+class TestBuildFlagsEnv:
+    def test_simple_value(self) -> None:
+        out = flash._build_flags_env({"DEBUG_HEAP": 1})
+        assert out == {"PLATFORMIO_BUILD_FLAGS": "-DDEBUG_HEAP=1"}
+
+    def test_string_value(self) -> None:
+        out = flash._build_flags_env({"FOO": "bar"})
+        assert out == {"PLATFORMIO_BUILD_FLAGS": "-DFOO=bar"}
+
+    def test_bool_true_is_bare_flag(self) -> None:
+        out = flash._build_flags_env({"DEBUG_HEAP": True})
+        assert out == {"PLATFORMIO_BUILD_FLAGS": "-DDEBUG_HEAP"}
+
+    def test_bool_false_dropped(self) -> None:
+        out = flash._build_flags_env({"DEBUG_HEAP": False, "OTHER": 1})
+        assert out == {"PLATFORMIO_BUILD_FLAGS": "-DOTHER=1"}
+
+    def test_none_dropped(self) -> None:
+        out = flash._build_flags_env({"DEBUG_HEAP": None})
+        assert out == {}
+
+    def test_multiple_combined(self) -> None:
+        out = flash._build_flags_env({"DEBUG_HEAP": 1, "FOO": "x", "BAR": True})
+        # Order isn't guaranteed in dict iteration, so check membership.
+        flags = out["PLATFORMIO_BUILD_FLAGS"].split()
+        assert set(flags) == {"-DDEBUG_HEAP=1", "-DFOO=x", "-DBAR"}
+
+
+class TestBuildPropagatesFlags:
+    def test_extra_env_passed_to_pio_run(self) -> None:
+        # Mock pio.run so we don't actually invoke pio. Capture extra_env.
+        captured = {}
+
+        class _StubResult:
+            returncode = 0
+            stdout = ""
+            stderr = ""
+            duration_s = 0.1
+
+        def _stub(args, **kwargs):
+            captured["args"] = args
+            captured["kwargs"] = kwargs
+            return _StubResult()
+
+        with patch.object(pio, "run", side_effect=_stub):
+            with patch.object(flash, "_artifacts_for", return_value=[]):
+                out = flash.build(
+                    "fake-env",
+                    with_manifest=False,
+                    build_flags={"DEBUG_HEAP": 1},
+                )
+        assert captured["args"] == ["run", "-e", "fake-env"]
+        assert captured["kwargs"]["extra_env"] == {
+            "PLATFORMIO_BUILD_FLAGS": "-DDEBUG_HEAP=1"
+        }
+        assert out["build_flags"] == {"DEBUG_HEAP": 1}
+
+    def test_no_flags_means_no_extra_env(self) -> None:
+        captured = {}
+
+        class _StubResult:
+            returncode = 0
+            stdout = ""
+            stderr = ""
+            duration_s = 0.1
+
+        def _stub(args, **kwargs):
+            captured["kwargs"] = kwargs
+            return _StubResult()
+
+        with patch.object(pio, "run", side_effect=_stub):
+            with patch.object(flash, "_artifacts_for", return_value=[]):
+                flash.build("fake-env", with_manifest=False)
+        assert captured["kwargs"]["extra_env"] is None
@@ -0,0 +1,383 @@
+"""TCP transport plumbing in connection.py + devices.py.
+
+Pure-Python tests — no real device or daemon required. Mocks `TCPInterface`
+when exercising `connect()`.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from meshtastic_mcp import connection, devices
+
+# ---------- helpers --------------------------------------------------------
+
+
+class TestIsTcpPort:
+    def test_tcp_scheme(self) -> None:
+        assert connection.is_tcp_port("tcp://localhost") is True
+        assert connection.is_tcp_port("tcp://localhost:4403") is True
+        assert connection.is_tcp_port("tcp://192.168.1.50:9999") is True
+
+    def test_serial_paths(self) -> None:
+        assert connection.is_tcp_port("/dev/cu.usbmodem1234") is False
+        assert connection.is_tcp_port("/dev/ttyUSB0") is False
+        assert connection.is_tcp_port("COM3") is False
+
+    def test_empty_or_none(self) -> None:
+        assert connection.is_tcp_port(None) is False
+        assert connection.is_tcp_port("") is False
+
+
+class TestParseTcpPort:
+    def test_default_port(self) -> None:
+        assert connection.parse_tcp_port("tcp://localhost") == ("localhost", 4403)
+
+    def test_explicit_port(self) -> None:
+        assert connection.parse_tcp_port("tcp://localhost:9999") == (
+            "localhost",
+            9999,
+        )
+
+    def test_ip_with_port(self) -> None:
+        assert connection.parse_tcp_port("tcp://192.168.1.50:4403") == (
+            "192.168.1.50",
+            4403,
+        )
+
+
+class TestNormalizeTcpEndpoint:
+    def test_bare_host(self) -> None:
+        assert connection.normalize_tcp_endpoint("localhost") == "tcp://localhost:4403"
+
+    def test_host_port(self) -> None:
+        assert (
+            connection.normalize_tcp_endpoint("localhost:5000")
+            == "tcp://localhost:5000"
+        )
+
+    def test_full_url(self) -> None:
+        assert (
+            connection.normalize_tcp_endpoint("tcp://1.2.3.4") == "tcp://1.2.3.4:4403"
+        )
+        assert (
+            connection.normalize_tcp_endpoint("tcp://1.2.3.4:9999")
+            == "tcp://1.2.3.4:9999"
+        )
+
+    def test_idempotent(self) -> None:
+        once = connection.normalize_tcp_endpoint("localhost:4403")
+        twice = connection.normalize_tcp_endpoint(once)
+        assert once == twice == "tcp://localhost:4403"
+
+    def test_path_like_endpoint_rejected(self) -> None:
+        # Serial port paths and Windows drive paths are common config typos
+        # (someone passes a serial path to MESHTASTIC_MCP_TCP_HOST). Reject
+        # rather than producing a nonsense `tcp:///dev/cu.foo:4403` URL.
+        with pytest.raises(connection.ConnectionError, match="path separator"):
+            connection.normalize_tcp_endpoint("/dev/cu.foo")
+        with pytest.raises(connection.ConnectionError):
+            connection.normalize_tcp_endpoint("tcp:///dev/cu.foo:4403")
+        with pytest.raises(connection.ConnectionError):
+            connection.normalize_tcp_endpoint(r"C:\Windows\System32")
+
+    def test_non_integer_port_rejected(self) -> None:
+        with pytest.raises(connection.ConnectionError, match="not an integer"):
+            connection.normalize_tcp_endpoint("tcp://host:notaport")
+        with pytest.raises(connection.ConnectionError, match="not an integer"):
+            connection.normalize_tcp_endpoint("host:notaport")
+
+    def test_empty_host_rejected(self) -> None:
+        with pytest.raises(connection.ConnectionError, match="empty host"):
+            connection.normalize_tcp_endpoint("tcp://:4403")
+
+    def test_port_out_of_range_rejected(self) -> None:
+        with pytest.raises(connection.ConnectionError, match="out of range"):
+            connection.normalize_tcp_endpoint("tcp://host:0")
+        with pytest.raises(connection.ConnectionError, match="out of range"):
+            connection.normalize_tcp_endpoint("tcp://host:65536")
+        with pytest.raises(connection.ConnectionError, match="out of range"):
+            connection.normalize_tcp_endpoint("host:99999")
+
+
+class TestParseTcpPortValidation:
+    def test_missing_scheme_rejected(self) -> None:
+        # parse_tcp_port is a low-level helper that requires the scheme.
+        # Misuse should fail loudly rather than silently mis-parsing.
+        with pytest.raises(connection.ConnectionError, match="expected"):
+            connection.parse_tcp_port("localhost:4403")
+
+    def test_negative_port_rejected(self) -> None:
+        with pytest.raises(connection.ConnectionError, match="out of range"):
+            connection.parse_tcp_port("tcp://host:-1")
+
+
+# ---------- reject_if_tcp --------------------------------------------------
+
+
+class TestRejectIfTcp:
+    def test_rejects_tcp(self) -> None:
+        with pytest.raises(connection.ConnectionError, match="not applicable"):
+            connection.reject_if_tcp("tcp://localhost", "esptool_chip_info")
+
+    def test_passes_through_serial(self) -> None:
+        connection.reject_if_tcp("/dev/cu.usbmodem1", "esptool_chip_info")  # no raise
+
+    def test_passes_through_none(self) -> None:
+        # None means "auto-detect"; not the explicit-arg case we guard.
+        connection.reject_if_tcp(None, "esptool_chip_info")  # no raise
+
+
+# ---------- resolve_port ---------------------------------------------------
+
+
+class TestResolvePort:
+    def test_explicit_serial_passthrough(self) -> None:
+        assert connection.resolve_port("/dev/cu.usbmodem999") == "/dev/cu.usbmodem999"
+
+    def test_explicit_tcp_normalized(self) -> None:
+        assert connection.resolve_port("tcp://localhost") == "tcp://localhost:4403"
+
+    def test_no_port_no_devices_errors(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("MESHTASTIC_MCP_TCP_HOST", raising=False)
+        with patch.object(devices, "list_devices", return_value=[]):
+            with pytest.raises(
+                connection.ConnectionError, match="No Meshtastic devices"
+            ):
+                connection.resolve_port(None)
+
+    def test_no_port_one_candidate_selected(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("MESHTASTIC_MCP_TCP_HOST", raising=False)
+        fake = [{"port": "/dev/cu.usbmodem1", "likely_meshtastic": True}]
+        with patch.object(devices, "list_devices", return_value=fake):
+            assert connection.resolve_port(None) == "/dev/cu.usbmodem1"
+
+    def test_no_port_multiple_candidates_errors(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("MESHTASTIC_MCP_TCP_HOST", raising=False)
+        fake = [
+            {"port": "/dev/cu.usbmodem1", "likely_meshtastic": True},
+            {"port": "/dev/cu.usbmodem2", "likely_meshtastic": True},
+        ]
+        with patch.object(devices, "list_devices", return_value=fake):
+            with pytest.raises(connection.ConnectionError, match="Multiple"):
+                connection.resolve_port(None)
+
+    def test_env_var_surfaces_tcp_via_devices(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "localhost")
+        # Don't patch list_devices — let the real env-var path run, but stub
+        # the USB enumeration to keep the test hermetic.
+        with patch("meshtastic_mcp.devices.list_ports.comports", return_value=[]):
+            assert connection.resolve_port(None) == "tcp://localhost:4403"
+
+
+# ---------- devices.list_devices TCP entry --------------------------------
+
+
+class TestDevicesTcpEntry:
+    def test_no_env_var_no_tcp_entry(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("MESHTASTIC_MCP_TCP_HOST", raising=False)
+        with patch("meshtastic_mcp.devices.list_ports.comports", return_value=[]):
+            ds = devices.list_devices()
+        assert all(not d["port"].startswith("tcp://") for d in ds)
+
+    def test_env_var_adds_tcp_entry(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "myhost:9999")
+        with patch("meshtastic_mcp.devices.list_ports.comports", return_value=[]):
+            ds = devices.list_devices()
+        tcp = [d for d in ds if d["port"].startswith("tcp://")]
+        assert len(tcp) == 1
+        assert tcp[0]["port"] == "tcp://myhost:9999"
+        assert tcp[0]["likely_meshtastic"] is True
+        assert tcp[0]["description"] == "meshtasticd (TCP)"
+
+    def test_tcp_entry_first_in_results(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "localhost")
+        with patch("meshtastic_mcp.devices.list_ports.comports", return_value=[]):
+            ds = devices.list_devices()
+        assert ds, "expected at least the TCP entry"
+        assert ds[0]["port"].startswith("tcp://")
+
+    def test_invalid_env_var_does_not_break_list_devices(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # `list_devices` is the diagnostic tool reached for when an env var
+        # isn't working — it must not throw on misconfiguration.
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "host:notaport")
+        with patch("meshtastic_mcp.devices.list_ports.comports", return_value=[]):
+            ds = devices.list_devices(include_unknown=True)
+        tcp = [d for d in ds if "TCP" in (d["description"] or "")]
+        assert len(tcp) == 1
+        assert tcp[0]["likely_meshtastic"] is False
+        assert "invalid MESHTASTIC_MCP_TCP_HOST" in tcp[0]["description"]
+        assert "not an integer" in tcp[0]["description"]
+
+    def test_invalid_env_var_excluded_from_resolve_port_autodetect(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # `likely_meshtastic=False` keeps the bad TCP entry out of the
+        # auto-select path — `resolve_port(None)` should still report
+        # "no Meshtastic devices" rather than picking a broken endpoint.
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "host:notaport")
+        with patch("meshtastic_mcp.devices.list_ports.comports", return_value=[]):
+            with pytest.raises(connection.ConnectionError, match="No Meshtastic"):
+                connection.resolve_port(None)
+
+    def test_invalid_env_var_does_not_double_tcp_scheme(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # If a user mistakenly sets `MESHTASTIC_MCP_TCP_HOST=tcp://host:bad`,
+        # the diagnostic entry must surface the raw value as-is rather than
+        # producing `tcp://tcp://host:bad`.
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "tcp://host:notaport")
+        with patch("meshtastic_mcp.devices.list_ports.comports", return_value=[]):
+            ds = devices.list_devices(include_unknown=True)
+        tcp = [d for d in ds if "TCP" in (d["description"] or "")]
+        assert len(tcp) == 1
+        assert tcp[0]["port"] == "tcp://host:notaport"
+        assert "tcp://tcp://" not in tcp[0]["port"]
+
+    def test_invalid_env_var_does_not_pre_empt_real_usb_devices(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Sort ordering: a misconfigured TCP env var must NOT take position 0
+        # ahead of real USB candidates. Position 0 is reserved for the highest
+        # rank (likely_meshtastic=True), with TCP-before-USB as a tiebreaker
+        # within rank.
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "host:notaport")
+
+        # Stub a USB Meshtastic candidate (Espressif VID, port present in
+        # findPorts).
+        class FakeInfo:
+            def __init__(self, device: str, vid: int, pid: int) -> None:
+                self.device = device
+                self.vid = vid
+                self.pid = pid
+                self.description = "Heltec V3"
+                self.manufacturer = "Espressif"
+                self.product = "USB JTAG/serial"
+                self.serial_number = "abc"
+
+        fake_port = FakeInfo("/dev/cu.usbmodem4201", 0x303A, 0x1001)
+        with patch(
+            "meshtastic_mcp.devices.list_ports.comports", return_value=[fake_port]
+        ), patch(
+            "meshtastic.util.findPorts",
+            return_value=["/dev/cu.usbmodem4201"],
+        ):
+            ds = devices.list_devices(include_unknown=True)
+
+        assert ds, "expected at least the USB + TCP entries"
+        # Real USB candidate must be at position 0 — it's likely_meshtastic.
+        assert ds[0]["port"] == "/dev/cu.usbmodem4201"
+        assert ds[0]["likely_meshtastic"] is True
+        # The malformed TCP entry exists but lands among the unlikely entries.
+        tcp = [d for d in ds if "TCP" in (d["description"] or "")]
+        assert len(tcp) == 1
+        assert tcp[0]["likely_meshtastic"] is False
+        assert ds.index(tcp[0]) > 0
+
+    def test_likely_tcp_entry_wins_tiebreak_over_usb(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Conversely, a *valid* TCP env var should sort ahead of USB
+        # candidates of equal likely_meshtastic rank — explicit env-var
+        # configuration is a precedence signal.
+        monkeypatch.setenv("MESHTASTIC_MCP_TCP_HOST", "localhost:4403")
+
+        class FakeInfo:
+            def __init__(self, device: str, vid: int, pid: int) -> None:
+                self.device = device
+                self.vid = vid
+                self.pid = pid
+                self.description = "Heltec V3"
+                self.manufacturer = "Espressif"
+                self.product = "USB JTAG/serial"
+                self.serial_number = "abc"
+
+        fake_port = FakeInfo("/dev/cu.usbmodem4201", 0x303A, 0x1001)
+        with patch(
+            "meshtastic_mcp.devices.list_ports.comports", return_value=[fake_port]
+        ), patch(
+            "meshtastic.util.findPorts",
+            return_value=["/dev/cu.usbmodem4201"],
+        ):
+            ds = devices.list_devices()
+
+        assert ds[0]["port"] == "tcp://localhost:4403"
+        assert ds[0]["likely_meshtastic"] is True
+
+
+# ---------- connect() routing ---------------------------------------------
+
+
+class TestConnectRoutesTcp:
+    def test_connect_uses_tcp_interface_for_tcp_port(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Verify the TCP branch instantiates `TCPInterface(hostname, portNumber)`
+        and never touches `SerialInterface`."""
+        # Make sure the env var doesn't leak in and confuse resolve_port.
+        monkeypatch.delenv("MESHTASTIC_MCP_TCP_HOST", raising=False)
+
+        with patch("meshtastic.tcp_interface.TCPInterface") as mock_tcp, patch(
+            "meshtastic.serial_interface.SerialInterface"
+        ) as mock_serial:
+            mock_tcp.return_value.close.return_value = None
+            with connection.connect(port="tcp://example.com:1234", timeout_s=12.0):
+                pass
+
+        mock_tcp.assert_called_once_with(
+            hostname="example.com",
+            portNumber=1234,
+            connectNow=True,
+            noProto=False,
+            timeout=12,
+        )
+        mock_serial.assert_not_called()
+
+    def test_connect_plumbs_timeout_to_serial_interface(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Verify the serial branch also propagates `timeout_s` so callers
+        passing a custom timeout to `device_info` / `list_nodes` / etc. don't
+        silently get the library default."""
+        monkeypatch.delenv("MESHTASTIC_MCP_TCP_HOST", raising=False)
+
+        with patch("meshtastic.serial_interface.SerialInterface") as mock_serial, patch(
+            "meshtastic.tcp_interface.TCPInterface"
+        ) as mock_tcp:
+            mock_serial.return_value.close.return_value = None
+            with connection.connect(port="/dev/cu.fake", timeout_s=20.0):
+                pass
+
+        mock_serial.assert_called_once_with(
+            devPath="/dev/cu.fake",
+            connectNow=True,
+            noProto=False,
+            timeout=20,
+        )
+        mock_tcp.assert_not_called()
+
+    def test_connect_releases_lock_on_tcp_failure(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("MESHTASTIC_MCP_TCP_HOST", raising=False)
+        with patch("meshtastic.tcp_interface.TCPInterface") as mock_tcp:
+            mock_tcp.side_effect = RuntimeError("boom")
+            with pytest.raises(RuntimeError, match="boom"):
+                with connection.connect(port="tcp://locktest:4403"):
+                    pass
+
+        # Lock should be released — a second connect attempt must not fail
+        # with "busy".
+        with patch("meshtastic.tcp_interface.TCPInterface") as mock_tcp:
+            mock_tcp.return_value.close.return_value = None
+            with connection.connect(port="tcp://locktest:4403"):
+                pass
@@ -0,0 +1,364 @@
+"""Tests for the fake-NodeDB fixture pipeline (bin/gen-fake-nodedb-seed.py
+ bin/seed-json-to-proto.py + mcp-server fixtures.push_fake_nodedb).
+
+Lives under tests/unit/ because none of these touch real hardware — they
+shell out to the bin/ scripts and decode the resulting protobufs in-process.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+import subprocess
+import sys
+import time
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+SEED_GEN = REPO_ROOT / "bin" / "gen-fake-nodedb-seed.py"
+COMPILE = REPO_ROOT / "bin" / "seed-json-to-proto.py"
+FIXTURES_DIR = REPO_ROOT / "test" / "fixtures" / "nodedb"
+
+# Ensure the locally-generated Python protobuf bindings are importable.
+# These live under `meshtastic_v25` (not `meshtastic`) so they don't shadow
+# the PyPI `meshtastic` package that the rest of the mcp-server depends on.
+_BINDINGS_DIR = REPO_ROOT / "bin" / "_generated"
+if _BINDINGS_DIR.is_dir() and str(_BINDINGS_DIR) not in sys.path:
+    sys.path.insert(0, str(_BINDINGS_DIR))
+
+try:
+    from meshtastic_v25.deviceonly_pb2 import (
+        NodeDatabase,  # type: ignore[import-not-found]
+    )
+except ImportError:
+    NodeDatabase = None  # type: ignore[assignment]
+
+
+def _require_v25_bindings() -> None:
+    if NodeDatabase is None:
+        pytest.skip(
+            "v25 Python protobuf bindings missing; run `./bin/regen-py-protos.sh`."
+        )
+    if "positions" not in NodeDatabase.DESCRIPTOR.fields_by_name:
+        pytest.skip(
+            "Loaded NodeDatabase predates v25 — run `./bin/regen-py-protos.sh`."
+        )
+
+
+def _run(cmd: list[str]) -> None:
+    subprocess.check_call(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+
+
+# ---------------------------------------------------------------------------
+# Seed generator: deterministic for given --seed (no wall-clock dependence).
+# ---------------------------------------------------------------------------
+def test_seed_generator_is_deterministic(tmp_path: pathlib.Path) -> None:
+    a = tmp_path / "a.jsonl"
+    b = tmp_path / "b.jsonl"
+    _run(
+        [
+            sys.executable,
+            str(SEED_GEN),
+            "--count",
+            "100",
+            "--seed",
+            "42",
+            "--out",
+            str(a),
+        ]
+    )
+    # Sleep so any sneaky wall-clock leak in the generator would surface as
+    # a byte diff between the two runs.
+    time.sleep(0.8)
+    _run(
+        [
+            sys.executable,
+            str(SEED_GEN),
+            "--count",
+            "100",
+            "--seed",
+            "42",
+            "--out",
+            str(b),
+        ]
+    )
+    assert a.read_bytes() == b.read_bytes()
+
+
+def test_seed_generator_meta_line(tmp_path: pathlib.Path) -> None:
+    out = tmp_path / "seed.jsonl"
+    _run(
+        [
+            sys.executable,
+            str(SEED_GEN),
+            "--count",
+            "50",
+            "--seed",
+            "1",
+            "--out",
+            str(out),
+        ]
+    )
+    lines = out.read_text(encoding="utf-8").splitlines()
+    assert len(lines) == 51  # 1 meta + 50 nodes
+    meta = json.loads(lines[0])
+    assert "_meta" in meta
+    assert meta["_meta"]["version"] == 25
+    assert meta["_meta"]["count"] == 50
+    assert meta["_meta"]["seed"] == 1
+
+
+def test_seed_only_uses_active_hardware_and_roles(tmp_path: pathlib.Path) -> None:
+    """Confirm no deprecated roles + no off-list HW models leak through."""
+    out = tmp_path / "seed.jsonl"
+    _run(
+        [
+            sys.executable,
+            str(SEED_GEN),
+            "--count",
+            "500",
+            "--seed",
+            "7",
+            "--out",
+            str(out),
+        ]
+    )
+    forbidden_roles = {"ROUTER_CLIENT", "REPEATER"}
+    forbidden_hw = {
+        "TLORA_V1",
+        "TLORA_V2",
+        "TLORA_V1_1P3",
+        "TLORA_V2_1_1P6",
+        "TLORA_V2_1_1P8",
+        "HELTEC_V1",
+        "HELTEC_V2_0",
+        "HELTEC_V2_1",
+        "TBEAM",
+        "TBEAM_V0P7",
+        "NANO_G1",
+        "NANO_G1_EXPLORER",
+        "NANO_G2_ULTRA",
+        "STATION_G1",
+        "STATION_G2",
+        "PORTDUINO",
+        "ANDROID_SIM",
+        "DIY_V1",
+        "LORA_RELAY_V1",
+        "NRF52840_PCA10059",
+        "NRF52_UNKNOWN",
+        "DR_DEV",
+        "GENIEBLOCKS",
+        "M5STACK",
+        "RP2040_LORA",
+        "PPR",
+    }
+    for raw in out.read_text(encoding="utf-8").splitlines()[1:]:
+        node = json.loads(raw)
+        assert node["role"] not in forbidden_roles, f"deprecated role: {node['role']}"
+        assert (
+            node["hw_model"] not in forbidden_hw
+        ), f"non-tier-1 HW: {node['hw_model']}"
+
+
+# ---------------------------------------------------------------------------
+# Compile step + committed seeds.
+# ---------------------------------------------------------------------------
+@pytest.mark.parametrize("size", [250, 500, 1000, 2000])
+def test_committed_seed_compiles_and_decodes(size: int, tmp_path: pathlib.Path) -> None:
+    _require_v25_bindings()
+    proto = tmp_path / "out.proto"
+    jsonl = FIXTURES_DIR / f"seed_v25_{size:04d}.jsonl"
+    if not jsonl.is_file():
+        pytest.skip(f"{jsonl} not present — run ./bin/regen-fake-nodedbs.sh")
+    _run([sys.executable, str(COMPILE), "--in", str(jsonl), "--out", str(proto)])
+
+    db = NodeDatabase()
+    db.ParseFromString(proto.read_bytes())
+    assert db.version == 25
+    assert len(db.nodes) == size
+    nums = {n.num for n in db.nodes}
+    assert len(nums) == size, "node numbers must be unique"
+    assert all(n.long_name and n.short_name for n in db.nodes)
+    assert all(len(n.long_name) <= 24 for n in db.nodes)  # max_size:25 - NUL
+
+    # Coverage sanity (±10pp tolerance for binomial fluctuation).
+    def in_range(actual: int, expected_ratio: float, tol_pp: float = 0.10) -> bool:
+        lo = max(0, int((expected_ratio - tol_pp) * size))
+        hi = min(size, int((expected_ratio + tol_pp) * size))
+        return lo <= actual <= hi
+
+    assert in_range(len(db.positions), 0.85)
+    assert in_range(len(db.telemetry), 0.70)
+    assert in_range(len(db.environment), 0.25)
+    assert in_range(len(db.status), 0.40)
+
+
+def test_compile_freshens_timestamps(tmp_path: pathlib.Path) -> None:
+    """Same JSONL compiled twice → identical structure, different timestamps."""
+    _require_v25_bindings()
+    jsonl = FIXTURES_DIR / "seed_v25_0250.jsonl"
+    if not jsonl.is_file():
+        pytest.skip("250-node seed not present — run ./bin/regen-fake-nodedbs.sh")
+    a = tmp_path / "a.proto"
+    b = tmp_path / "b.proto"
+    _run([sys.executable, str(COMPILE), "--in", str(jsonl), "--out", str(a)])
+    time.sleep(1.2)
+    _run([sys.executable, str(COMPILE), "--in", str(jsonl), "--out", str(b)])
+
+    da = NodeDatabase()
+    db_ = NodeDatabase()
+    da.ParseFromString(a.read_bytes())
+    db_.ParseFromString(b.read_bytes())
+
+    # Zero out timestamp fields and confirm everything else is byte-identical.
+    for d in (da, db_):
+        for n in d.nodes:
+            n.last_heard = 0
+        for p in d.positions:
+            p.position.time = 0
+    assert da.SerializeToString() == db_.SerializeToString()
+
+    # Re-load fresh copies to confirm timestamps actually moved.
+    aa = NodeDatabase()
+    bb = NodeDatabase()
+    aa.ParseFromString(a.read_bytes())
+    bb.ParseFromString(b.read_bytes())
+    aa_max = max(n.last_heard for n in aa.nodes if n.last_heard)
+    bb_max = max(n.last_heard for n in bb.nodes if n.last_heard)
+    assert bb_max >= aa_max
+    assert bb_max - aa_max < 5  # within a few seconds
+
+
+def test_compile_pinned_now_epoch_is_byte_identical(tmp_path: pathlib.Path) -> None:
+    """With --now-epoch pinned, two compiles produce identical bytes."""
+    _require_v25_bindings()
+    jsonl = FIXTURES_DIR / "seed_v25_0250.jsonl"
+    if not jsonl.is_file():
+        pytest.skip("250-node seed not present")
+    a = tmp_path / "a.proto"
+    b = tmp_path / "b.proto"
+    for o in (a, b):
+        _run(
+            [
+                sys.executable,
+                str(COMPILE),
+                "--in",
+                str(jsonl),
+                "--now-epoch",
+                "1700000000",
+                "--out",
+                str(o),
+            ]
+        )
+    assert a.read_bytes() == b.read_bytes()
+
+
+def test_compile_timestamps_are_recent(tmp_path: pathlib.Path) -> None:
+    _require_v25_bindings()
+    jsonl = FIXTURES_DIR / "seed_v25_0250.jsonl"
+    if not jsonl.is_file():
+        pytest.skip("250-node seed not present")
+    out = tmp_path / "out.proto"
+    _run([sys.executable, str(COMPILE), "--in", str(jsonl), "--out", str(out)])
+    db = NodeDatabase()
+    db.ParseFromString(out.read_bytes())
+    now = int(time.time())
+    # No timestamp older than 7 days, none in the future.
+    for n in db.nodes:
+        if n.last_heard:
+            assert now - 7 * 86400 <= n.last_heard <= now
+    # At least half should be within the last hour
+    # (matches expovariate(mean=3600s)).
+    recent = sum(1 for n in db.nodes if n.last_heard and n.last_heard >= now - 3600)
+    assert recent >= 0.4 * len(db.nodes)
+
+
+def test_compile_hand_edit_round_trip(tmp_path: pathlib.Path) -> None:
+    """Edit one JSONL line, recompile, confirm edit appears in the proto."""
+    _require_v25_bindings()
+    src = FIXTURES_DIR / "seed_v25_0250.jsonl"
+    if not src.is_file():
+        pytest.skip("250-node seed not present")
+    dst = tmp_path / "edited.jsonl"
+    lines = src.read_text(encoding="utf-8").splitlines()
+
+    # Find a node that already has telemetry so the index relationship is
+    # easy to assert on the other side.
+    edit_idx = None
+    for i, raw in enumerate(lines[1:], start=1):
+        node = json.loads(raw)
+        if node.get("telemetry") is not None:
+            edit_idx = i
+            break
+    assert edit_idx is not None, "expected at least one node with telemetry"
+
+    node = json.loads(lines[edit_idx])
+    target_num = int(node["num"], 16)
+    node["long_name"] = "Hand Edited Node"
+    node["telemetry"] = {
+        "battery_level": 42,
+        "voltage": 3.71,
+        "channel_utilization": 0.0,
+        "air_util_tx": 0.0,
+        "uptime_seconds": 1,
+    }
+    lines[edit_idx] = json.dumps(node, ensure_ascii=False, sort_keys=True)
+    dst.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    out = tmp_path / "out.proto"
+    _run([sys.executable, str(COMPILE), "--in", str(dst), "--out", str(out)])
+    db = NodeDatabase()
+    db.ParseFromString(out.read_bytes())
+    edited = next((n for n in db.nodes if n.num == target_num), None)
+    assert edited is not None
+    assert edited.long_name == "Hand Edited Node"
+    tel = next((t for t in db.telemetry if t.num == target_num), None)
+    assert tel is not None
+    assert tel.device_metrics.battery_level == 42
+
+
+# ---------------------------------------------------------------------------
+# Misc smoke checks on the module surface.
+# ---------------------------------------------------------------------------
+def test_crc16_ccitt_matches_known_vectors() -> None:
+    """Sanity-check the hand-rolled CRC16-CCITT matches well-known vectors.
+
+    Test vectors from the XModem-CRC spec (init=0, poly=0x1021):
+      crc16("123456789") = 0x31C3
+      crc16("")          = 0x0000
+    """
+    from meshtastic_mcp.fixtures import _crc16_ccitt
+
+    assert _crc16_ccitt(b"") == 0x0000
+    assert _crc16_ccitt(b"123456789") == 0x31C3
+
+
+def test_push_fake_nodedb_rejects_invalid_size() -> None:
+    from meshtastic_mcp.fixtures import FixtureError, push_fake_nodedb
+
+    with pytest.raises(FixtureError, match="size must be one of"):
+        push_fake_nodedb(size=999, target="portduino")  # type: ignore[arg-type]
+
+
+def test_push_fake_nodedb_hardware_requires_confirm() -> None:
+    from meshtastic_mcp.fixtures import FixtureError, push_fake_nodedb
+
+    with pytest.raises(FixtureError, match="confirm=True"):
+        push_fake_nodedb(size=250, target="hardware", port="/dev/cu.fake")
+
+
+def test_push_fake_nodedb_hardware_requires_port() -> None:
+    from meshtastic_mcp.fixtures import FixtureError, push_fake_nodedb
+
+    with pytest.raises(FixtureError, match="requires a port"):
+        push_fake_nodedb(size=250, target="hardware", confirm=True)
+
+
+def test_push_fake_nodedb_hardware_rejects_tcp_port() -> None:
+    from meshtastic_mcp.fixtures import FixtureError, push_fake_nodedb
+
+    with pytest.raises(FixtureError, match="not supported"):
+        push_fake_nodedb(
+            size=250, target="hardware", confirm=True, port="tcp://localhost:4403"
+        )
@@ -0,0 +1,548 @@
+"""Unit tests for the persistent device-log recorder.
+
+Hardware-free: drives the Recorder through its `_on_*` handlers with
+synthetic packet/line dicts, then queries via log_query. Validates
+prefix parsing, telemetry variant dispatch, marker round-trip, time
+window filtering, downsampling, slope estimation, and gzip rotation
+ archive pruning.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import logging
+import os
+import time
+from pathlib import Path
+
+import pubsub
+import pytest
+from meshtastic_mcp import log_query
+from meshtastic_mcp.recorder.parsers import (
+    extract_telemetry,
+    interface_label,
+    parse_log_line,
+    summarize_packet,
+)
+from meshtastic_mcp.recorder.recorder import Recorder
+from meshtastic_mcp.recorder.rotating import _RotatingJsonl
+
+# -- isolation: every test gets a fresh Recorder + tmp dir -----------
+
+
+@pytest.fixture
+def recorder(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Recorder:
+    # Redirect both the Recorder and the module-level singleton lookup
+    # to the same tmp dir so log_query queries the same files we write.
+    monkeypatch.setenv("MESHTASTIC_MCP_LOG_DIR", str(tmp_path))
+    monkeypatch.setattr(
+        "meshtastic_mcp.recorder.recorder._INSTANCE", None, raising=False
+    )
+    r = Recorder(base_dir=tmp_path)
+    r.start()
+    monkeypatch.setattr("meshtastic_mcp.recorder.recorder._INSTANCE", r, raising=False)
+    yield r
+    r.stop()
+
+
+class _FakeIface:
+    devPath = "/dev/cu.fake"
+
+
+# -- parsers ---------------------------------------------------------
+
+
+class TestParseLogLine:
+    def test_full_prefix(self) -> None:
+        out = parse_log_line("INFO  | 12:34:56 12345 [Main] Booting")
+        assert out["level"] == "INFO"
+        assert out["tag"] == "Main"
+        assert out["uptime_s"] == 12345
+        assert out["msg"] == "Booting"
+        assert out["clock"] == "12:34:56"
+
+    def test_invalid_clock(self) -> None:
+        out = parse_log_line("WARN  | ??:??:?? 7 [SerialConsole] Boot")
+        assert out["level"] == "WARN"
+        assert out["clock"] == "??:??:??"
+        assert out["uptime_s"] == 7
+
+    def test_no_thread_bracket(self) -> None:
+        out = parse_log_line("DEBUG | 00:00:00 0 raw message body")
+        assert out["level"] == "DEBUG"
+        assert out.get("tag") is None
+        assert out["msg"] == "raw message body"
+
+    def test_bare_message(self) -> None:
+        # LogRecord.message path — no level prefix at all.
+        out = parse_log_line("just a bare message")
+        assert "level" not in out or out.get("level") is None
+        assert out["line"] == "just a bare message"
+
+    def test_empty(self) -> None:
+        assert parse_log_line("") == {"line": ""}
+
+    def test_debug_heap_prefix_extracted(self) -> None:
+        out = parse_log_line("INFO  | 12:34:56 12345 [Main] [heap 92344] Booting")
+        assert out["level"] == "INFO"
+        assert out["tag"] == "Main"
+        assert out["heap_free"] == 92344
+        assert out["msg"] == "Booting"
+
+    def test_debug_heap_prefix_on_bare_line(self) -> None:
+        # LogRecord.message path: no level prefix but still has [heap N].
+        out = parse_log_line("[heap 12345] some message")
+        assert out["heap_free"] == 12345
+        assert out["msg"] == "some message"
+
+    def test_thread_leak_event(self) -> None:
+        out = parse_log_line(
+            "HEAP  | 00:00:01 100 [Power] [heap 90000] "
+            "------ Thread MeshPacket leaked heap 92344 -> 90000 (-2344) ------"
+        )
+        assert out["level"] == "HEAP"
+        assert out["heap_free"] == 90000
+        ev = out["heap_event"]
+        assert ev["kind"] == "leaked"
+        assert ev["thread"] == "MeshPacket"
+        assert ev["before"] == 92344
+        assert ev["after"] == 90000
+        assert ev["delta"] == -2344
+
+    def test_thread_freed_event(self) -> None:
+        out = parse_log_line(
+            "++++++ Thread Router freed heap 1000 -> 1500 (500) ++++++"
+        )
+        ev = out["heap_event"]
+        assert ev["kind"] == "freed"
+        assert ev["thread"] == "Router"
+        assert ev["delta"] == 500
+
+    def test_heap_status_periodic(self) -> None:
+        out = parse_log_line(
+            "HEAP  | 00:00:30 30 [Power] "
+            "Heap status: 92344/200000 bytes free (-128), running 8/12 threads"
+        )
+        assert out["heap_free"] == 92344
+        assert out["heap_total"] == 200000
+        assert out["heap_delta"] == -128
+
+
+class TestRecorderDebugHeapSynthesis:
+    def test_log_with_heap_writes_telemetry(self, recorder: "Recorder") -> None:
+        # When a log line carries [heap N], the recorder should also
+        # emit a synthesized telemetry row tagged source=debug_heap.
+        recorder._on_log_line(
+            "INFO  | 00:00:00 1 [Main] [heap 88888] hello",
+            _FakeIface(),
+        )
+        telem = (recorder.base_dir / "telemetry.jsonl").read_text().splitlines()
+        synth = [json.loads(r) for r in telem if '"source":"debug_heap"' in r]
+        assert len(synth) == 1
+        assert synth[0]["fields"]["heap_free_bytes"] == 88888
+        assert synth[0]["variant"] == "local"
+
+    def test_heap_status_writes_total_too(self, recorder: "Recorder") -> None:
+        recorder._on_log_line(
+            "HEAP  | 00:00:30 30 [Power] "
+            "Heap status: 50000/200000 bytes free (-100), running 8/12 threads",
+            _FakeIface(),
+        )
+        telem = (recorder.base_dir / "telemetry.jsonl").read_text().splitlines()
+        synth = [json.loads(r) for r in telem if '"source":"debug_heap"' in r]
+        assert synth[-1]["fields"]["heap_free_bytes"] == 50000
+        assert synth[-1]["fields"]["heap_total_bytes"] == 200000
+
+    def test_no_heap_no_synthesis(self, recorder: "Recorder") -> None:
+        # Plain log line (no [heap N], no Heap status) — telemetry.jsonl
+        # should NOT gain a synth row.
+        before = (recorder.base_dir / "telemetry.jsonl").read_text().count("\n")
+        recorder._on_log_line("INFO  | 00:00:00 1 [Main] just a message", _FakeIface())
+        after = (recorder.base_dir / "telemetry.jsonl").read_text().count("\n")
+        assert after == before
+
+    def test_thread_leak_event_persists_on_log_row(self, recorder: "Recorder") -> None:
+        recorder._on_log_line(
+            "HEAP  | 00:00:01 100 [Power] [heap 90000] "
+            "------ Thread MeshPacket leaked heap 92344 -> 90000 (-2344) ------",
+            _FakeIface(),
+        )
+        rows = [
+            json.loads(r)
+            for r in (recorder.base_dir / "logs.jsonl").read_text().splitlines()
+            if r
+        ]
+        evt_rows = [r for r in rows if r.get("heap_event")]
+        assert len(evt_rows) == 1
+        assert evt_rows[0]["heap_event"]["thread"] == "MeshPacket"
+        assert evt_rows[0]["heap_event"]["delta"] == -2344
+
+
+class TestSerialTap:
+    def test_serial_line_records_log_and_synthesizes_heap(
+        self, recorder: "Recorder"
+    ) -> None:
+        recorder._on_serial_line(
+            "INFO  | 00:00:00 5 [Main] [heap 88888] tap-line",
+            port="/dev/cu.tap",
+        )
+        logs = (recorder.base_dir / "logs.jsonl").read_text().splitlines()
+        telem = (recorder.base_dir / "telemetry.jsonl").read_text().splitlines()
+        log_rows = [json.loads(r) for r in logs if r]
+        # Find the row from this call (port=/dev/cu.tap, role=serial_session)
+        tap_rows = [r for r in log_rows if r.get("port") == "/dev/cu.tap"]
+        assert len(tap_rows) == 1
+        assert tap_rows[0]["role"] == "serial_session"
+        assert tap_rows[0]["level"] == "INFO"
+        assert tap_rows[0]["tag"] == "Main"
+        assert tap_rows[0]["heap_free"] == 88888
+        synth = [json.loads(r) for r in telem if '"source":"debug_heap_serial"' in r]
+        assert len(synth) == 1
+        assert synth[0]["fields"]["heap_free_bytes"] == 88888
+        assert synth[0]["role"] == "serial_session"
+
+    def test_serial_line_thread_leak_event(self, recorder: "Recorder") -> None:
+        recorder._on_serial_line(
+            "HEAP  | 00:00:30 30 [Power] [heap 53484] "
+            "------ Thread Router leaked heap 53612 -> 53484 (-128) ------",
+            port="/dev/cu.tap",
+        )
+        rows = [
+            json.loads(r)
+            for r in (recorder.base_dir / "logs.jsonl").read_text().splitlines()
+            if r
+        ]
+        evt = [r for r in rows if r.get("heap_event")]
+        assert len(evt) == 1
+        assert evt[0]["heap_event"]["thread"] == "Router"
+        assert evt[0]["heap_event"]["delta"] == -128
+        # Heap also synthesized.
+        telem = (recorder.base_dir / "telemetry.jsonl").read_text()
+        assert '"source":"debug_heap_serial"' in telem
+
+    def test_serial_line_pause(self, recorder: "Recorder") -> None:
+        recorder.pause("baseline")
+        recorder._on_serial_line(
+            "INFO  | 00:00:00 1 [t] [heap 1000] dropped",
+            port="/dev/cu.tap",
+        )
+        # Only the pause event row should exist; no tap row.
+        logs = (recorder.base_dir / "logs.jsonl").read_text()
+        assert "dropped" not in logs
+
+    def test_serial_line_handler_swallows_exceptions(
+        self, recorder: "Recorder"
+    ) -> None:
+        # Hostile input — should not raise.
+        recorder._on_serial_line(None, port="/dev/cu.tap")  # type: ignore[arg-type]
+        recorder._on_serial_line(b"\x00\x01\x02\x03", port="/dev/cu.tap")  # type: ignore[arg-type]
+        # Survived.
+
+
+class TestExtractTelemetry:
+    def test_local_stats_camel(self) -> None:
+        pkt = {
+            "decoded": {
+                "telemetry": {
+                    "localStats": {"heap_total_bytes": 1000, "heap_free_bytes": 600}
+                }
+            }
+        }
+        out = extract_telemetry(pkt)
+        assert out is not None
+        assert out["variant"] == "local"
+        assert out["fields"]["heap_free_bytes"] == 600
+
+    def test_device_metrics_snake(self) -> None:
+        pkt = {
+            "decoded": {
+                "telemetry": {"device_metrics": {"battery_level": 88, "voltage": 4.1}}
+            }
+        }
+        out = extract_telemetry(pkt)
+        assert out is not None
+        assert out["variant"] == "device"
+        assert out["fields"]["battery_level"] == 88
+
+    def test_unknown_variant_returns_none(self) -> None:
+        assert extract_telemetry({"decoded": {"telemetry": {"weird": {}}}}) is None
+        assert extract_telemetry({}) is None
+        assert extract_telemetry({"decoded": "not-a-dict"}) is None
+
+
+class TestSummarizePacket:
+    def test_text_with_payload(self) -> None:
+        pkt = {
+            "fromId": "!abc",
+            "toId": "!def",
+            "decoded": {"portnum": "TEXT_MESSAGE_APP", "payload": b"hello"},
+            "hopLimit": 3,
+        }
+        out = summarize_packet(pkt)
+        assert out["from_node"] == "!abc"
+        assert out["portnum"] == "TEXT_MESSAGE_APP"
+        assert out["payload_size"] == 5
+        assert out["payload_hex_prefix"] == "68656c6c6f"
+
+    def test_no_decoded(self) -> None:
+        out = summarize_packet({"fromId": "!abc"})
+        assert out["from_node"] == "!abc"
+        assert out["portnum"] is None
+
+
+class TestInterfaceLabel:
+    def test_serial(self) -> None:
+        assert interface_label(_FakeIface()) == {
+            "port": "/dev/cu.fake",
+            "role": "serial",
+        }
+
+    def test_tcp(self) -> None:
+        class T:
+            hostname = "node.lan"
+            portNumber = 4403
+
+        assert interface_label(T()) == {"port": "tcp://node.lan:4403", "role": "tcp"}
+
+    def test_unknown(self) -> None:
+        assert interface_label(object()) == {"port": "object", "role": None}
+
+    def test_none(self) -> None:
+        assert interface_label(None) == {"port": None, "role": None}
+
+
+# -- recorder write side ---------------------------------------------
+
+
+class TestRecorderWrites:
+    def test_log_line_is_recorded(self, recorder: Recorder) -> None:
+        recorder._on_log_line("INFO  | 12:34:56 99 [T] hi", _FakeIface())
+        path = recorder.base_dir / "logs.jsonl"
+        rows = [json.loads(line) for line in path.read_text().splitlines() if line]
+        # First row is recorder_start_event mirror? No — that's events.jsonl only.
+        assert any(r.get("level") == "INFO" and r.get("tag") == "T" for r in rows)
+
+    def test_telemetry_recorded_and_packet_double(self, recorder: Recorder) -> None:
+        # _on_telemetry alone — only telemetry.jsonl
+        recorder._on_telemetry(
+            {
+                "fromId": "!abc",
+                "decoded": {"telemetry": {"localStats": {"heap_free_bytes": 600}}},
+            },
+            _FakeIface(),
+        )
+        telem_rows = (recorder.base_dir / "telemetry.jsonl").read_text().splitlines()
+        assert any('"variant":"local"' in r for r in telem_rows)
+
+    def test_packets_summary(self, recorder: Recorder) -> None:
+        recorder._on_receive(
+            {
+                "fromId": "!abc",
+                "toId": "!def",
+                "decoded": {"portnum": "TEXT_MESSAGE_APP", "payload": b"hi"},
+            },
+            _FakeIface(),
+        )
+        rows = (recorder.base_dir / "packets.jsonl").read_text().splitlines()
+        assert any('"portnum":"TEXT_MESSAGE_APP"' in r for r in rows)
+
+    def test_mark_event_round_trip(self, recorder: Recorder) -> None:
+        out = recorder.mark_event("checkpoint", note="midpoint")
+        assert "ts" in out
+        events = (recorder.base_dir / "events.jsonl").read_text().splitlines()
+        logs = (recorder.base_dir / "logs.jsonl").read_text().splitlines()
+        assert any('"label":"checkpoint"' in r and '"kind":"mark"' in r for r in events)
+        assert any('"level":"MARK"' in r and "checkpoint" in r for r in logs)
+
+    def test_pause_drops_writes(self, recorder: Recorder) -> None:
+        before = len((recorder.base_dir / "logs.jsonl").read_text().splitlines())
+        recorder.pause(reason="baseline")
+        recorder._on_log_line("INFO  | 00:00:00 1 [t] swallowed", _FakeIface())
+        after = len((recorder.base_dir / "logs.jsonl").read_text().splitlines())
+        assert after == before
+        recorder.resume()
+        recorder._on_log_line("INFO  | 00:00:00 2 [t] kept", _FakeIface())
+        post_resume = (recorder.base_dir / "logs.jsonl").read_text()
+        assert "kept" in post_resume
+
+    def test_pubsub_handler_swallows_exceptions(self, recorder: Recorder) -> None:
+        # If the writer dies, the pubsub callback must NOT raise — that
+        # would crash the meshtastic receive thread.
+        bad_packet = object()  # not a dict
+        recorder._on_receive(bad_packet, _FakeIface())  # type: ignore[arg-type]
+        recorder._on_telemetry(bad_packet, _FakeIface())  # type: ignore[arg-type]
+        recorder._on_log_line(None, _FakeIface())  # type: ignore[arg-type]
+        # No assertion needed — survival is the test.
+
+
+# -- log_query read side ---------------------------------------------
+
+
+class TestLogQuery:
+    def test_logs_window_grep_and_level(self, recorder: Recorder) -> None:
+        recorder._on_log_line("INFO  | 12:00:00 1 [A] alpha", _FakeIface())
+        recorder._on_log_line("WARN  | 12:00:01 2 [B] bravo failed", _FakeIface())
+        recorder._on_log_line("ERROR | 12:00:02 3 [C] charlie failed", _FakeIface())
+
+        out = log_query.logs_window(start="-1m", level="WARN|ERROR", max_lines=10)
+        assert out["total_matched"] == 2
+        levels = {r["level"] for r in out["lines"]}
+        assert levels == {"WARN", "ERROR"}
+
+        out2 = log_query.logs_window(start="-1m", grep=r"failed$", max_lines=10)
+        assert out2["total_matched"] == 2
+
+    def test_logs_window_invalid_regex(self, recorder: Recorder) -> None:
+        recorder._on_log_line("INFO  | 12:00:00 1 [A] alpha", _FakeIface())
+        with pytest.raises(ValueError, match="invalid grep regex"):
+            log_query.logs_window(start="-1m", grep="(")
+
+    def test_telemetry_timeline_slope_and_downsample(self, recorder: Recorder) -> None:
+        # Synthesize a downward leak: 100 points, free_heap drops 1 byte/sample.
+        base_ts = time.time() - 60
+        for i in range(100):
+            recorder._files["telemetry"].write(
+                {
+                    "ts": base_ts + i * 0.5,
+                    "port": "/dev/cu.fake",
+                    "role": "serial",
+                    "from_node": "!abc",
+                    "variant": "local",
+                    "fields": {"heap_free_bytes": 10000 - i},
+                }
+            )
+
+        out = log_query.telemetry_timeline(
+            window="2m", variant="local", field="free_heap", max_points=10
+        )
+        assert out["samples"] == 100
+        assert len(out["points"]) <= 10
+        # Negative slope (heap dropping). Magnitude: 1 byte every 0.5s = 120/min.
+        assert out["slope_per_min"] is not None
+        assert out["slope_per_min"] < -100
+
+    def test_export_bundles_slice(self, recorder: Recorder, tmp_path: Path) -> None:
+        recorder._on_log_line("INFO  | 00:00:00 1 [t] one", _FakeIface())
+        recorder._on_log_line("INFO  | 00:00:00 2 [t] two", _FakeIface())
+        dest = tmp_path / "bundle"
+        out = log_query.export(start="-1m", end="now", dest_dir=str(dest))
+        assert (dest / "logs.jsonl").exists()
+        assert "logs" in out["paths"]
+
+
+# -- time parser -----------------------------------------------------
+
+
+class TestParseTime:
+    def test_relative(self) -> None:
+        now = 1_000_000.0
+        assert log_query._parse_time("-15m", now=now) == now - 900
+        assert log_query._parse_time("-2h", now=now) == now - 7200
+        assert log_query._parse_time("-1d", now=now) == now - 86400
+
+    def test_now_and_epoch(self) -> None:
+        now = 1_000_000.0
+        assert log_query._parse_time("now", now=now) == now
+        assert log_query._parse_time(now) == now
+
+    def test_iso(self) -> None:
+        ts = log_query._parse_time("2026-01-01T00:00:00Z")
+        assert isinstance(ts, float) and ts > 1_700_000_000
+
+    def test_naive_iso_assumes_utc(self) -> None:
+        assert log_query._parse_time("2026-01-01T00:00:00") == log_query._parse_time(
+            "2026-01-01T00:00:00Z"
+        )
+
+    def test_invalid(self) -> None:
+        with pytest.raises(ValueError):
+            log_query._parse_time("not a time")
+
+
+# -- rotation --------------------------------------------------------
+
+
+class TestRotation:
+    def test_size_cap_rotates_and_gzips(self, tmp_path: Path) -> None:
+        path = tmp_path / "rot.jsonl"
+        r = _RotatingJsonl(path, max_bytes=512, keep_archives=5, check_every=1)
+        for i in range(100):
+            r.write({"ts": float(i), "i": i, "pad": "x" * 40})
+        r.close()
+        archives = sorted(tmp_path.glob("rot.*.jsonl.gz"))
+        assert archives, "expected at least one rotation"
+        # Archive content is valid gzip + valid JSONL
+        with gzip.open(archives[0], "rt") as fh:
+            first = json.loads(fh.readline())
+            assert "ts" in first
+
+    def test_archive_pruning(self, tmp_path: Path) -> None:
+        path = tmp_path / "rot.jsonl"
+        r = _RotatingJsonl(path, max_bytes=200, keep_archives=2, check_every=1)
+        # Force several rotations.
+        for _ in range(8):
+            for i in range(20):
+                r.write({"ts": float(i), "pad": "x" * 30})
+            r.force_rotate()
+        r.close()
+        archives = sorted(tmp_path.glob("rot.*.jsonl.gz"))
+        assert len(archives) <= 2, f"expected ≤2 kept archives, got {len(archives)}"
+
+    def test_archive_pruning_uses_filename_order(self, tmp_path: Path) -> None:
+        path = tmp_path / "rot.jsonl"
+        r = _RotatingJsonl(path, keep_archives=2)
+        old = tmp_path / "rot.20260101-000000-000000-00000.jsonl.gz"
+        mid = tmp_path / "rot.20260101-000001-000000-00000.jsonl.gz"
+        new = tmp_path / "rot.20260101-000002-000000-00000.jsonl.gz"
+        for archive in (old, mid, new):
+            with gzip.open(archive, "wt", encoding="utf-8") as fh:
+                fh.write('{"ts":1}\n')
+        # Deliberately scramble mtimes so lexicographic filename order is
+        # the only stable chronological signal.
+        os.utime(old, (300, 300))
+        os.utime(mid, (100, 100))
+        os.utime(new, (200, 200))
+
+        r._prune_archives()
+        r.close()
+
+        archives = sorted(p.name for p in tmp_path.glob("rot.*.jsonl.gz"))
+        assert archives == [mid.name, new.name]
+
+    def test_force_rotate_when_below_threshold(self, tmp_path: Path) -> None:
+        path = tmp_path / "rot.jsonl"
+        r = _RotatingJsonl(path, max_bytes=10_000_000, check_every=999_999)
+        r.write({"ts": 1.0, "msg": "tiny"})
+        r.force_rotate()
+        r.write({"ts": 2.0, "msg": "after-rotate"})
+        r.close()
+        archives = sorted(tmp_path.glob("rot.*.jsonl.gz"))
+        assert len(archives) == 1
+        assert path.exists()
+        assert "after-rotate" in path.read_text()
+
+
+class TestRecorderLocks:
+    def test_force_rotate_all_returns_status(self, recorder: Recorder) -> None:
+        out = recorder.force_rotate_all()
+        assert out["running"] is True
+        assert out["files"]
+
+    def test_wire_pubsub_logs_subscription_failure(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        class FailingPubSubMock:
+            def subscribe(self, callback: object, topic: str) -> None:
+                raise RuntimeError("boom")
+
+        monkeypatch.setattr(pubsub, "pub", FailingPubSubMock())
+        recorder = Recorder(base_dir=tmp_path)
+        with caplog.at_level(logging.WARNING):
+            recorder._wire_pubsub()
+        assert (
+            "Recorder failed to subscribe to meshtastic.log.line: boom" in caplog.text
+        )
@@ -29,6 +29,7 @@ build_flags = -Wno-missing-field-initializers
 	-DUSE_THREAD_NAMES
 	-DTINYGPS_OPTION_NO_CUSTOM_FIELDS
 	-DPB_ENABLE_MALLOC=1
+	-DPB_VALIDATE_UTF8=1
 	-DRADIOLIB_EXCLUDE_CC1101=1
 	-DRADIOLIB_EXCLUDE_NRF24=1
 	-DRADIOLIB_EXCLUDE_RF69=1
@@ -48,6 +49,7 @@ build_flags = -Wno-missing-field-initializers
 	-DRADIOLIB_EXCLUDE_PAGER=1
 	-DRADIOLIB_EXCLUDE_FSK4=1
 	-DRADIOLIB_EXCLUDE_APRS=1
+	-DRADIOLIB_EXCLUDE_ADSB=1
 	-DRADIOLIB_EXCLUDE_LORAWAN=1
 	-DMESHTASTIC_EXCLUDE_DROPZONE=1
 	-DMESHTASTIC_EXCLUDE_REPLYBOT=1
@@ -66,7 +68,7 @@ monitor_speed = 115200
 monitor_filters = direct
 lib_deps =
 	# renovate: datasource=git-refs depName=meshtastic-esp8266-oled-ssd1306 packageName=https://github.com/meshtastic/esp8266-oled-ssd1306 gitBranch=master
-	https://github.com/meshtastic/esp8266-oled-ssd1306/archive/21e484f409cde18d44012caef84c244eb5ca28f3.zip
+	https://github.com/meshtastic/esp8266-oled-ssd1306/archive/6bfd1f135e1ebe37afd6050bb4b9964cea3fcfda.zip
 	# renovate: datasource=git-refs depName=meshtastic-OneButton packageName=https://github.com/meshtastic/OneButton gitBranch=master
 	https://github.com/meshtastic/OneButton/archive/fa352d668c53f290cfa480a5f79ad422cd828c70.zip
 	# renovate: datasource=git-refs depName=meshtastic-arduino-fsm packageName=https://github.com/meshtastic/arduino-fsm gitBranch=master
@@ -119,12 +121,12 @@ lib_deps =
 [radiolib_base]
 lib_deps =
 	# renovate: datasource=github-tags depName=RadioLib packageName=jgromes/RadioLib
-	https://github.com/jgromes/RadioLib/archive/refs/tags/7.6.0.zip
+	https://github.com/jgromes/RadioLib/archive/afe72ae46a343e15e3cac7f26ac585c7f98bffe5.zip

 [device-ui_base]
 lib_deps =
 	# renovate: datasource=git-refs depName=meshtastic/device-ui packageName=https://github.com/meshtastic/device-ui gitBranch=master
-	https://github.com/meshtastic/device-ui/archive/56e1da4e7d30abcd746a2092a30e422f8cf5fc2b.zip
+	https://github.com/meshtastic/device-ui/archive/4bf593a82100b911ff816dddf7158ffdee2114cd.zip

 ; Common libs for environmental measurements in telemetry module
 [environmental_base]
@@ -136,7 +138,7 @@ lib_deps =
 	# renovate: datasource=github-tags depName=Adafruit GFX packageName=adafruit/Adafruit-GFX-Library
 	https://github.com/adafruit/Adafruit-GFX-Library/archive/refs/tags/1.12.6.zip
 	# renovate: datasource=github-tags depName=NeoPixel packageName=adafruit/Adafruit_NeoPixel
-	https://github.com/adafruit/Adafruit_NeoPixel/archive/refs/tags/1.15.4.zip
+	https://github.com/adafruit/Adafruit_NeoPixel/archive/1.15.5.zip
 	# renovate: datasource=github-tags depName=Adafruit SSD1306 packageName=adafruit/Adafruit_SSD1306
 	https://github.com/adafruit/Adafruit_SSD1306/archive/refs/tags/2.5.16.zip
 	# renovate: datasource=github-tags depName=Adafruit BMP280 packageName=adafruit/Adafruit_BMP280_Library
@@ -169,8 +171,8 @@ lib_deps =
 	https://github.com/EmotiBit/EmotiBit_MLX90632/archive/refs/tags/v1.0.8.zip
 	# renovate: datasource=github-tags depName=Adafruit MLX90614 packageName=adafruit/Adafruit_MLX90614
 	https://github.com/adafruit/Adafruit-MLX90614-Library/archive/refs/tags/2.1.6.zip
-	# renovate: datasource=git-refs depName=INA3221 packageName=https://github.com/sgtwilko/INA3221 gitBranch=FixOverflow
-	https://github.com/sgtwilko/INA3221/archive/bb03d7e9bfcc74fc798838a54f4f99738f29fc6a.zip
+	# renovate: datasource=github-tags depName=INA3221_RT packageName=RobTillaart/INA3221_RT
+	https://github.com/RobTillaart/INA3221_RT/archive/refs/tags/0.4.2.zip
 	# renovate: datasource=github-tags depName=QMC5883L Compass packageName=mprograms/QMC5883LCompass
 	https://github.com/mprograms/QMC5883LCompass/archive/refs/tags/v1.2.3.zip
 	# renovate: datasource=github-tags depName=DFRobot_RTU packageName=dfrobot/DFRobot_RTU
@@ -26,6 +26,8 @@ SOFTWARE.*/

 #include "DebugConfiguration.h"

+#include <memory>
+
 #ifdef ARCH_PORTDUINO
 #include "platform/portduino/PortduinoGlue.h"
 #endif
@@ -119,27 +121,22 @@ bool Syslog::vlogf(uint16_t pri, const char *fmt, va_list args)

 bool Syslog::vlogf(uint16_t pri, const char *appName, const char *fmt, va_list args)
 {
-    char *message;
-    size_t initialLen;
-    size_t len;
-    bool result;
+    // First measure the formatted length using a copy of args; passing args directly
+    // to vsnprintf consumes it, and reusing a consumed va_list is undefined behavior.
+    va_list args_measure;
+    va_copy(args_measure, args);
+    int needed = vsnprintf(nullptr, 0, fmt, args_measure);
+    va_end(args_measure);

-    initialLen = strlen(fmt);
+    if (needed < 0)
+        return false; // encoding error

-    message = new char[initialLen + 1];
+    auto message = std::unique_ptr<char[]>(new char[static_cast<size_t>(needed) + 1]);
+    int written = vsnprintf(message.get(), static_cast<size_t>(needed) + 1, fmt, args);
+    if (written < 0)
+        return false;

-    len = vsnprintf(message, initialLen + 1, fmt, args);
-    if (len > initialLen) {
-        delete[] message;
-        message = new char[len + 1];
-
-        vsnprintf(message, len + 1, fmt, args);
-    }
-
-    result = this->_sendLog(pri, appName, message);
-
-    delete[] message;
-    return result;
+    return this->_sendLog(pri, appName, message.get());
 }

 inline bool Syslog::_sendLog(uint16_t pri, const char *appName, const char *message)
@@ -154,7 +151,7 @@ inline bool Syslog::_sendLog(uint16_t pri, const char *appName, const char *mess
    if (!this->_enabled)
        return false;

-    if ((this->_server == NULL && this->_ip == INADDR_NONE) || this->_port == 0)
+    if ((this->_server == NULL && this->_ip == IPAddress(0, 0, 0, 0)) || this->_port == 0)
        return false;

    // Check priority against priMask values.
@@ -13,6 +13,11 @@ extern MemGet memGet;
 #define LED_STATE_ON 1
 #endif

+// WIFI LED
+#ifndef WIFI_STATE_ON
+#define WIFI_STATE_ON 1
+#endif
+
 // -----------------------------------------------------------------------------
 // DEBUG
 // -----------------------------------------------------------------------------
@@ -147,7 +152,9 @@ extern "C" void logLegacy(const char *level, const char *fmt, ...);
 // Default Bluetooth PIN
 #define defaultBLEPin 123456

-#if HAS_ETHERNET && !defined(USE_WS5500)
+#if HAS_ETHERNET && defined(USE_CH390D)
+#include <ESP32_CH390.h>
+#elif HAS_ETHERNET && !defined(USE_WS5500)
 #include <RAK13800_W5100S.h>
 #endif // HAS_ETHERNET

@@ -79,28 +79,46 @@ bool copyFile(const char *from, const char *to)
 bool renameFile(const char *pathFrom, const char *pathTo)
 {
 #ifdef FSCom
-
-#ifdef ARCH_ESP32
-    // take SPI Lock
    spiLock->lock();
-    // rename was fixed for ESP32 IDF LittleFS in April
    bool result = FSCom.rename(pathFrom, pathTo);
    spiLock->unlock();
    return result;
 #else
-    // copyFile does its own locking.
-    if (copyFile(pathFrom, pathTo) && FSCom.remove(pathFrom)) {
-        return true;
-    } else {
-        return false;
-    }
-#endif
-
+    return false;
 #endif
 }

 #include <vector>

+/**
+ * @brief Platform-agnostic filesystem format / wipe.
+ *
+ * On embedded targets (ESP32, NRF52, STM32WL, RP2040) this calls the
+ * native FSCom.format() which erases and reinitialises the LittleFS
+ * partition.
+ *
+ * On Portduino the fs::FS backend has no format() method. We instead
+ * delete /prefs (the only meshtastic data directory written at runtime)
+ * and return. rmDir("/prefs") is already called unconditionally by
+ * factoryReset() so this is a proven primitive on Portduino.
+ * FSBegin() is a no-op (#define FSBegin() true) on Portduino.
+ *
+ * @return true on success, false on failure or if no filesystem is configured.
+ */
+bool fsFormat()
+{
+#ifdef FSCom
+#if defined(ARCH_PORTDUINO)
+    rmDir("/prefs");
+    return FSBegin();
+#else
+    return FSCom.format();
+#endif
+#else
+    return false;
+#endif
+}
+
 /**
 * @brief Get the list of files in a directory.
 *
@@ -123,23 +141,21 @@ std::vector<meshtastic_FileInfo> getFiles(const char *dirname, uint8_t levels)

    File file = root.openNextFile();
    while (file) {
+#ifdef ARCH_ESP32
+        const char *filepath = file.path();
+#else
+        const char *filepath = file.name();
+#endif
        if (file.isDirectory() && !String(file.name()).endsWith(".")) {
            if (levels) {
-#ifdef ARCH_ESP32
-                std::vector<meshtastic_FileInfo> subDirFilenames = getFiles(file.path(), levels - 1);
-#else
-                std::vector<meshtastic_FileInfo> subDirFilenames = getFiles(file.name(), levels - 1);
-#endif
+                std::vector<meshtastic_FileInfo> subDirFilenames = getFiles(filepath, levels - 1);
                filenames.insert(filenames.end(), subDirFilenames.begin(), subDirFilenames.end());
                file.close();
            }
        } else {
            meshtastic_FileInfo fileInfo = {"", static_cast<uint32_t>(file.size())};
-#ifdef ARCH_ESP32
-            strcpy(fileInfo.file_name, file.path());
-#else
-            strcpy(fileInfo.file_name, file.name());
-#endif
+            strncpy(fileInfo.file_name, filepath, sizeof(fileInfo.file_name) - 1);
+            fileInfo.file_name[sizeof(fileInfo.file_name) - 1] = '\0';
            if (!String(fileInfo.file_name).endsWith(".")) {
                filenames.push_back(fileInfo);
            }
@@ -163,98 +179,59 @@ std::vector<meshtastic_FileInfo> getFiles(const char *dirname, uint8_t levels)
 void listDir(const char *dirname, uint8_t levels, bool del)
 {
 #ifdef FSCom
-#if (defined(ARCH_ESP32) || defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
    char buffer[255];
-#endif
    File root = FSCom.open(dirname, FILE_O_READ);
-    if (!root) {
+    if (!root || !root.isDirectory())
        return;
-    }
-    if (!root.isDirectory()) {
-        return;
-    }

    File file = root.openNextFile();
-    while (
-        file &&
-        file.name()[0]) { // This file.name() check is a workaround for a bug in the Adafruit LittleFS nrf52 glue (see issue 4395)
+    while (file && file.name()[0]) { // file.name()[0] check: workaround for Adafruit LittleFS nRF52 bug #4395
+#ifdef ARCH_ESP32
+        const char *filepath = file.path();
+#else
+        const char *filepath = file.name();
+#endif
        if (file.isDirectory() && !String(file.name()).endsWith(".")) {
            if (levels) {
-#ifdef ARCH_ESP32
-                listDir(file.path(), levels - 1, del);
+                listDir(filepath, levels - 1, del);
                if (del) {
-                    LOG_DEBUG("Remove %s", file.path());
-                    strncpy(buffer, file.path(), sizeof(buffer));
+                    LOG_DEBUG("Remove %s", filepath);
+                    strncpy(buffer, filepath, sizeof(buffer) - 1);
+                    buffer[sizeof(buffer) - 1] = '\0';
                    file.close();
                    FSCom.rmdir(buffer);
                } else {
                    file.close();
                }
-#elif (defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
-                listDir(file.name(), levels - 1, del);
-                if (del) {
-                    LOG_DEBUG("Remove %s", file.name());
-                    strncpy(buffer, file.name(), sizeof(buffer));
-                    file.close();
-                    FSCom.rmdir(buffer);
-                } else {
-                    file.close();
-                }
-#else
-                LOG_DEBUG(" %s (directory)", file.name());
-                listDir(file.name(), levels - 1, del);
-                file.close();
-#endif
            }
        } else {
-#ifdef ARCH_ESP32
            if (del) {
-                LOG_DEBUG("Delete %s", file.path());
-                strncpy(buffer, file.path(), sizeof(buffer));
+                LOG_DEBUG("Delete %s", filepath);
+                strncpy(buffer, filepath, sizeof(buffer) - 1);
+                buffer[sizeof(buffer) - 1] = '\0';
                file.close();
                FSCom.remove(buffer);
            } else {
-                LOG_DEBUG(" %s (%i Bytes)", file.path(), file.size());
+                LOG_DEBUG(" %s (%i Bytes)", filepath, file.size());
                file.close();
            }
-#elif (defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
-            if (del) {
-                LOG_DEBUG("Delete %s", file.name());
-                strncpy(buffer, file.name(), sizeof(buffer));
-                file.close();
-                FSCom.remove(buffer);
-            } else {
-                LOG_DEBUG(" %s (%i Bytes)", file.name(), file.size());
-                file.close();
-            }
-#else
-            LOG_DEBUG("   %s (%i Bytes)", file.name(), file.size());
-            file.close();
-#endif
        }
        file = root.openNextFile();
    }
 #ifdef ARCH_ESP32
-    if (del) {
-        LOG_DEBUG("Remove %s", root.path());
-        strncpy(buffer, root.path(), sizeof(buffer));
-        root.close();
-        FSCom.rmdir(buffer);
-    } else {
-        root.close();
-    }
-#elif (defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
-    if (del) {
-        LOG_DEBUG("Remove %s", root.name());
-        strncpy(buffer, root.name(), sizeof(buffer));
-        root.close();
-        FSCom.rmdir(buffer);
-    } else {
-        root.close();
-    }
+    const char *rootpath = root.path();
 #else
-    root.close();
+    const char *rootpath = root.name();
 #endif
+    if (del) {
+        LOG_DEBUG("Remove %s", rootpath);
+        strncpy(buffer, rootpath, sizeof(buffer) - 1);
+        buffer[sizeof(buffer) - 1] = '\0';
+        root.close();
+        FSCom.rmdir(buffer);
+    } else {
+        root.close();
+    }
 #endif
 }

@@ -268,14 +245,7 @@ void listDir(const char *dirname, uint8_t levels, bool del)
 void rmDir(const char *dirname)
 {
 #ifdef FSCom
-
-#if (defined(ARCH_ESP32) || defined(ARCH_RP2040) || defined(ARCH_PORTDUINO))
    listDir(dirname, 10, true);
-#elif defined(ARCH_NRF52)
-    // nRF52 implementation of LittleFS has a recursive delete function
-    FSCom.rmdir_r(dirname);
-#endif
-
 #endif
 }

@@ -52,6 +52,7 @@ void fsInit();
 void fsListFiles();
 bool copyFile(const char *from, const char *to);
 bool renameFile(const char *pathFrom, const char *pathTo);
+bool fsFormat();
 std::vector<meshtastic_FileInfo> getFiles(const char *dirname, uint8_t levels);
 void listDir(const char *dirname, uint8_t levels, bool del = false);
 void rmDir(const char *dirname);
@@ -53,8 +53,7 @@ class GPSStatus : public Status
    int32_t getLatitude() const
    {
        if (config.position.fixed_position) {
-            meshtastic_NodeInfoLite *node = nodeDB->getMeshNode(nodeDB->getNodeNum());
-            return node->position.latitude_i;
+            return localPosition.latitude_i;
        } else {
            return p.latitude_i;
        }
@@ -63,8 +62,7 @@ class GPSStatus : public Status
    int32_t getLongitude() const
    {
        if (config.position.fixed_position) {
-            meshtastic_NodeInfoLite *node = nodeDB->getMeshNode(nodeDB->getNodeNum());
-            return node->position.longitude_i;
+            return localPosition.longitude_i;
        } else {
            return p.longitude_i;
        }
@@ -73,8 +71,7 @@ class GPSStatus : public Status
    int32_t getAltitude() const
    {
        if (config.position.fixed_position) {
-            meshtastic_NodeInfoLite *node = nodeDB->getMeshNode(nodeDB->getNodeNum());
-            return node->position.altitude;
+            return localPosition.altitude;
        } else {
            return p.altitude;
        }
--- a/Show More
+++ b/Show More