Merge branch 'pioarduino' into crowpanel-p4

Merge branch 'develop' into pioarduino
dependency swap - INA3221Sensor (#10379 )
2026-10-04 03:18:10 +10:00 · 2026-05-07 16:40:44 +02:00 · 2026-05-05 09:10:28 -04:00 · 2026-05-05 06:52:07 -05:00 · 2026-05-04 18:10:59 -05:00 · 2026-05-04 16:19:48 -05:00
204 changed files with 4707 additions and 1031 deletions
@@ -8,7 +8,7 @@
  "features": {
    "ghcr.io/devcontainers/features/python:1": {
      "installTools": true,
-      "version": "3.14"
+      "version": "3.13"
    }
  },
  "customizations": {
@@ -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

@@ -369,7 +370,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 +389,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 +575,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
@@ -4,19 +4,19 @@ cli:
 plugins:
  sources:
    - id: trunk
-      ref: v1.7.6
+      ref: v1.8.0
      uri: https://github.com/trunk-io/plugins
 lint:
  enabled:
-    - checkov@3.2.524
-    - renovate@43.141.0
+    - checkov@3.2.526
+    - renovate@43.150.0
    - prettier@3.8.3
    - trufflehog@3.95.2
    - 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
@@ -36,7 +36,7 @@ lint:
        - bin/**
 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)

@@ -121,19 +122,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
@@ -38,4 +38,4 @@ cp bin/device-install.* $OUTDIR/
 cp bin/device-update.* $OUTDIR/

 echo "Copying manifest"
-cp $BUILDDIR/$basename.mt.json $OUTDIR/$basename.mt.json || true
+cp $BUILDDIR/$basename.mt.json $OUTDIR/$basename.mt.json
@@ -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/
@@ -293,9 +293,12 @@ if ("HAS_TFT", 1) in env.get("CPPDEFINES", []):
 board_arch = infer_architecture(env.BoardConfig())
 should_skip_manifest = board_arch is None

-# For host/native envs, avoid depending on 'buildprog' (some targets don't define it)
-mtjson_deps = [] if should_skip_manifest else ["buildprog"]
-if not should_skip_manifest and platform.name == "espressif32":
+# Most platforms can generate the manifest as part of the default 'buildprog' target.
+# Typically this passes success/failure properly.
+mtjson_deps = ["buildprog"]
+if platform.name == "espressif32":
+    # On ESP32, we need to explicitly depend upon the binary to prevent fake-success upon failure.
+    mtjson_deps = ["$BUILD_DIR/${PROGNAME}.bin"]
    # Build littlefs image as part of mtjson target
    # Equivalent to `pio run -t buildfs`
    target_lfs = env.DataToBin(
@@ -309,7 +312,8 @@ if should_skip_manifest:

    env.AddCustomTarget(
        name="mtjson",
-        dependencies=mtjson_deps,
+        # For host/native envs, avoid depending on 'buildprog' (some targets don't define it)
+        dependencies=[],
        actions=[skip_manifest],
        title="Meshtastic Manifest (skipped)",
        description="mtjson generation is skipped for native environments",
@@ -7,7 +7,7 @@
    "extra_flags": [
      "-D CDEBYTE_EORA_S3",
      "-D ARDUINO_USB_CDC_ON_BOOT=1",
-      "-D ARDUINO_USB_MODE=0",
+      "-D ARDUINO_USB_MODE=1",
      "-D ARDUINO_RUNNING_CORE=1",
      "-D ARDUINO_EVENT_RUNNING_CORE=1",
      "-D BOARD_HAS_PSRAM"
@@ -6,7 +6,7 @@
    "core": "esp32",
    "extra_flags": [
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1",
      "-DBOARD_HAS_PSRAM"
@@ -0,0 +1,32 @@
+{
+  "build": {
+    "core": "esp32",
+    "extra_flags": ["-DBOARD_HAS_PSRAM"],
+    "f_cpu": "360000000L",
+    "f_flash": "80000000L",
+    "f_psram": "200000000L",
+    "flash_mode": "qio",
+    "hwids": [["0x1A86", "0x7522"]],
+    "mcu": "esp32p4",
+    "chip_variant": "esp32p4",
+    "variant": "esp32p4"
+  },
+  "arduino": {
+    "partitions": "default_16MB.csv"
+  },
+  "connectivity": ["bluetooth", "openthread"],
+  "debug": {
+    "openocd_target": "esp32p4.cfg"
+  },
+  "frameworks": ["arduino", "espidf"],
+  "name": "CrowPanel Advanced ESP32-P4 HMI AI Display",
+  "upload": {
+    "flash_size": "16MB",
+    "maximum_ram_size": 512000,
+    "maximum_size": 16777216,
+    "require_upload_port": true,
+    "speed": 1500000
+  },
+  "url": "https://www.elecrow.com/crowpanel-advanced-5inch-esp32-p4-hmi-ai-display-800x480-ips-touch-screen-with-wifi-6.html",
+  "vendor": "Elecrow"
+}
@@ -8,7 +8,7 @@
    "extra_flags": [
      "-DBOARD_HAS_PSRAM",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -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"
+}
@@ -9,7 +9,7 @@
    "extra_flags": [
      "-DBOARD_HAS_PSRAM",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -9,7 +9,7 @@
    "extra_flags": [
      "-DBOARD_HAS_PSRAM",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -9,7 +9,7 @@
    "extra_flags": [
      "-DBOARD_HAS_PSRAM",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -8,7 +8,7 @@
    "extra_flags": [
      "-DHELTEC_WIRELESS_TRACKER",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -7,7 +7,7 @@
    "core": "esp32",
    "extra_flags": [
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -8,7 +8,7 @@
    "extra_flags": [
      "-DBOARD_HAS_PSRAM",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=0"
    ],
@@ -9,7 +9,7 @@
      "-DBOARD_HAS_PSRAM",
      "-DLILYGO_TBEAM_1W",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -8,7 +8,7 @@
    "extra_flags": [
      "-DBOARD_HAS_PSRAM",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -8,7 +8,7 @@
      "-DBOARD_HAS_PSRAM",
      "-DLILYGO_TBEAM_S3_CORE",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -7,7 +7,7 @@
    "extra_flags": [
      "-DLILYGO_T3S3_V1",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1",
      "-DBOARD_HAS_PSRAM"
@@ -10,7 +10,7 @@
      "-DBOARD_HAS_PSRAM",
      "-DUNPHONE_SPIN=9",
      "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
      "-DARDUINO_RUNNING_CORE=1",
      "-DARDUINO_EVENT_RUNNING_CORE=1"
    ],
@@ -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
@@ -0,0 +1,7 @@
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     0x9000,  0x5000,
+otadata,  data, ota,     0xe000,  0x2000,
+app0,     app,  ota_0,   0x10000, 0x640000,
+app1,     app,  ota_1,   0x650000,0x640000,
+spiffs,   data, spiffs,  0xc90000,0x360000,
+coredump, data, coredump,0xFF0000,0x10000,
@@ -0,0 +1,7 @@
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     0x9000,  0x5000,
+otadata,  data, ota,     0xe000,  0x2000,
+app0,     app,  ota_0,   0x10000, 0x330000,
+app1,     app,  ota_1,   0x340000,0x330000,
+spiffs,   data, spiffs,  0x670000,0x180000,
+coredump, data, coredump,0x7F0000,0x10000,
@@ -70,17 +70,6 @@ def esp32_create_combined_bin(source, target, env):

 env.AddPostAction("$BUILD_DIR/${PROGNAME}.bin", esp32_create_combined_bin)

-esp32_kind = env.GetProjectOption("custom_esp32_kind")
-if esp32_kind == "esp32":
-    # Free up some IRAM by removing auxiliary SPI flash chip drivers.
-    # Wrapped stub symbols are defined in src/platform/esp32/iram-quirk.c.
-    env.Append(
-        LINKFLAGS=[
-            "-Wl,--wrap=esp_flash_chip_gd",
-            "-Wl,--wrap=esp_flash_chip_issi",
-            "-Wl,--wrap=esp_flash_chip_winbond",
-        ]
-    )
-else:
-    # For newer ESP32 targets, using newlib nano works better.
-    env.Append(LINKFLAGS=["--specs=nano.specs", "-u", "_printf_float"])
+# Enable Newlib Nano formatting to save space
+# ...but allow printf float support (compromise)
+env.Append(LINKFLAGS=["--specs=nano.specs", "-u", "_printf_float"])
@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# trunk-ignore-all(ruff/F821)
+# trunk-ignore-all(flake8/F821): For SConstruct imports
+
+# force linker response file instead of command line arguments
+
+Import("env")
+
+
+def wrap_with_tempfile(command_key):
+    command = env.get(command_key)
+    if not command or not isinstance(command, str):
+        return
+    if "TEMPFILE(" in command:
+        return
+    env.Replace(**{command_key: "${TEMPFILE('%s')}" % command})
+
+
+# Force SCons to spill long commands into response files on this target.
+env.Replace(MAXLINELENGTH=8192)
+
+for key in ("LINKCOM", "CXXLINKCOM", "SHLINKCOM", "SHCXXLINKCOM"):
+    wrap_with_tempfile(key)
@@ -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

@@ -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
@@ -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():
@@ -141,6 +153,8 @@ def flash(
    that pio performs will pick up the injected values.
    """
    _require_confirm(confirm, "flash")
+    _reject_native_env(env, "flash")
+    connection.reject_if_tcp(port, "flash")
    with userprefs.temporary_overrides(userprefs_overrides) as effective:
        result = pio.run(
            ["run", "-e", env, "-t", "upload", "--upload-port", port],
@@ -200,6 +214,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 +272,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 +407,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:
@@ -71,6 +71,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
@@ -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
@@ -2,7 +2,7 @@
 ; https://docs.platformio.org/page/projectconf.html

 [platformio]
-default_envs = tbeam
+default_envs = heltec-v3

 extra_configs =
 	variants/*/*.ini
@@ -120,12 +120,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]
@@ -170,8 +170,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
@@ -14,4 +14,28 @@ const uint8_t FROMNUM_UUID_16[16u] = {0x53, 0x44, 0xe3, 0x47, 0x75, 0xaa, 0x70,
 const uint8_t LEGACY_LOGRADIO_UUID_16[16u] = {0xe2, 0xf2, 0x1e, 0xbe, 0xc5, 0x15, 0xcf, 0xaa,
                                              0x6b, 0x43, 0xfa, 0x78, 0x38, 0xd2, 0x6f, 0x6c};
 const uint8_t LOGRADIO_UUID_16[16u] = {0x47, 0x95, 0xDF, 0x8C, 0xDE, 0xE9, 0x44, 0x99,
-                                       0x23, 0x44, 0xE6, 0x06, 0x49, 0x6E, 0x3D, 0x5A};
+                                       0x23, 0x44, 0xE6, 0x06, 0x49, 0x6E, 0x3D, 0x5A};
+
+void BluetoothApi::setup() {}
+void BluetoothApi::shutdown() {}
+void BluetoothApi::deinit() {}
+void BluetoothApi::clearBonds() {}
+bool BluetoothApi::isActive()
+{
+    return false;
+}
+bool BluetoothApi::isConnected()
+{
+    return false;
+}
+void BluetoothApi::sendLog(const uint8_t *logMessage, size_t length)
+{
+    (void)logMessage;
+    (void)length;
+}
+
+void updateBatteryLevel(uint8_t level) __attribute__((weak));
+void updateBatteryLevel(uint8_t level)
+{
+    (void)level;
+}
@@ -24,9 +24,14 @@ void updateBatteryLevel(uint8_t level);
 class BluetoothApi
 {
  public:
+    virtual ~BluetoothApi() = default;
+
    virtual void setup();
    virtual void shutdown();
+    virtual void deinit();
    virtual void clearBonds();
+    virtual bool isActive();
    virtual bool isConnected();
    virtual int getRssi() = 0;
+    virtual void sendLog(const uint8_t *logMessage, size_t length);
 };
@@ -151,9 +151,8 @@ extern "C" void logLegacy(const char *level, const char *fmt, ...);
 #include <RAK13800_W5100S.h>
 #endif // HAS_ETHERNET

-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET

 #if HAS_WIFI
@@ -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
 }

@@ -307,7 +277,7 @@ void fsInit()
 */
 void setupSDCard()
 {
-#if defined(HAS_SDCARD) && !defined(SDCARD_USE_SOFT_SPI)
+#if defined(HAS_SDCARD) && !defined(SDCARD_USE_SOFT_SPI) && !defined(HAS_SD_MMC)
    concurrency::LockGuard g(spiLock);
    SDHandler.begin(SPI_SCK, SPI_MISO, SPI_MOSI);
    if (!SD.begin(SDCARD_CS, SDHandler, SD_SPI_FREQUENCY)) {
@@ -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);
@@ -24,6 +24,13 @@
 #include "meshUtils.h"
 #include "power/PowerHAL.h"
 #include "sleep.h"
+#ifdef ARCH_ESP32
+// #include <driver/adc.h>
+#include <esp_adc/adc_cali.h>
+#include <esp_adc/adc_cali_scheme.h>
+#include <esp_adc/adc_oneshot.h>
+#include <esp_err.h>
+#endif

 #if defined(ARCH_PORTDUINO)
 #include "api/WiFiServerAPI.h"
@@ -63,9 +70,8 @@
 #include <WiFi.h>
 #endif

-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET

 #endif
@@ -77,21 +83,86 @@
 #if defined(BATTERY_PIN) && defined(ARCH_ESP32)

 #ifndef BAT_MEASURE_ADC_UNIT // ADC1 is default
-static const adc1_channel_t adc_channel = ADC_CHANNEL;
+static const adc_channel_t adc_channel = ADC_CHANNEL;
 static const adc_unit_t unit = ADC_UNIT_1;
-#else // ADC2
-static const adc2_channel_t adc_channel = ADC_CHANNEL;
+#else  // ADC2
+static const adc_channel_t adc_channel = ADC_CHANNEL;
 static const adc_unit_t unit = ADC_UNIT_2;
-RTC_NOINIT_ATTR uint64_t RTC_reg_b;
-
 #endif // BAT_MEASURE_ADC_UNIT

-esp_adc_cal_characteristics_t *adc_characs = (esp_adc_cal_characteristics_t *)calloc(1, sizeof(esp_adc_cal_characteristics_t));
+static adc_oneshot_unit_handle_t adc_handle = nullptr;
+static adc_cali_handle_t adc_cali_handle = nullptr;
+static bool adc_calibrated = false;
 #ifndef ADC_ATTENUATION
 static const adc_atten_t atten = ADC_ATTEN_DB_12;
 #else
 static const adc_atten_t atten = ADC_ATTENUATION;
 #endif
+#ifdef ADC_BITWIDTH
+static const adc_bitwidth_t adc_width = ADC_BITWIDTH;
+#else
+static const adc_bitwidth_t adc_width = ADC_BITWIDTH_DEFAULT;
+#endif
+
+static int adcBitWidthToBits(adc_bitwidth_t width)
+{
+    switch (width) {
+    case ADC_BITWIDTH_9:
+        return 9;
+    case ADC_BITWIDTH_10:
+        return 10;
+    case ADC_BITWIDTH_11:
+        return 11;
+    case ADC_BITWIDTH_12:
+        return 12;
+#ifdef ADC_BITWIDTH_13
+    case ADC_BITWIDTH_13:
+        return 13;
+#endif
+    default:
+        return 12;
+    }
+}
+
+static bool initAdcCalibration()
+{
+#if ADC_CALI_SCHEME_CURVE_FITTING_SUPPORTED
+    adc_cali_curve_fitting_config_t cali_config = {
+        .unit_id = unit,
+        .atten = atten,
+        .bitwidth = adc_width,
+    };
+    esp_err_t ret = adc_cali_create_scheme_curve_fitting(&cali_config, &adc_cali_handle);
+    if (ret == ESP_OK) {
+        LOG_INFO("ADC calibration: curve fitting enabled");
+        return true;
+    }
+    if (ret != ESP_ERR_NOT_SUPPORTED) {
+        LOG_WARN("ADC calibration: curve fitting failed: %s", esp_err_to_name(ret));
+    }
+#endif
+
+#if ADC_CALI_SCHEME_LINE_FITTING_SUPPORTED
+    adc_cali_line_fitting_config_t cali_config = {
+        .unit_id = unit,
+        .atten = atten,
+        .bitwidth = adc_width,
+        .default_vref = DEFAULT_VREF,
+    };
+    esp_err_t ret = adc_cali_create_scheme_line_fitting(&cali_config, &adc_cali_handle);
+    if (ret == ESP_OK) {
+        LOG_INFO("ADC calibration: line fitting enabled");
+        return true;
+    }
+    if (ret != ESP_ERR_NOT_SUPPORTED) {
+        LOG_WARN("ADC calibration: line fitting failed: %s", esp_err_to_name(ret));
+    }
+#endif
+
+    LOG_INFO("ADC calibration not supported; using approximate scaling");
+    return false;
+}
+
 #endif // BATTERY_PIN && ARCH_ESP32

 #ifdef EXT_PWR_DETECT
@@ -367,8 +438,20 @@ class AnalogBatteryLevel : public HasBatteryLevel
            scaled *= operativeAdcMultiplier;
 #elif defined(ARCH_ESP32) // ADC block for espressif platforms
            raw = espAdcRead();
-            scaled = esp_adc_cal_raw_to_voltage(raw, adc_characs);
-            scaled *= operativeAdcMultiplier;
+            int voltage_mv = 0;
+            if (adc_calibrated && adc_cali_handle) {
+                if (adc_cali_raw_to_voltage(adc_cali_handle, raw, &voltage_mv) != ESP_OK) {
+                    LOG_WARN("ADC calibration read failed; using raw value");
+                    voltage_mv = 0;
+                }
+            }
+            if (voltage_mv == 0) {
+                // Fallback approximate conversion without calibration
+                const int bits = adcBitWidthToBits(adc_width);
+                const float max_code = powf(2.0f, bits) - 1.0f;
+                voltage_mv = (int)((raw / max_code) * DEFAULT_VREF);
+            }
+            scaled = voltage_mv * operativeAdcMultiplier;
 #else                     // block for all other platforms
 #ifdef ARCH_NRF52
            concurrency::LockGuard saadcGuard(concurrency::nrf52SaadcLock);
@@ -410,51 +493,22 @@ class AnalogBatteryLevel : public HasBatteryLevel
        uint32_t raw = 0;
        uint8_t raw_c = 0; // raw reading counter

-#ifndef BAT_MEASURE_ADC_UNIT // ADC1
+        if (!adc_handle) {
+            LOG_ERROR("ADC oneshot handle not initialized");
+            return 0;
+        }
+
        for (int i = 0; i < BATTERY_SENSE_SAMPLES; i++) {
-            int val_ = adc1_get_raw(adc_channel);
-            if (val_ >= 0) { // save only valid readings
-                raw += val_;
+            int val = 0;
+            esp_err_t err = adc_oneshot_read(adc_handle, adc_channel, &val);
+            if (err == ESP_OK) {
+                raw += val;
                raw_c++;
-            }
-            // delayMicroseconds(100);
-        }
-#else                            // ADC2
-#ifdef CONFIG_IDF_TARGET_ESP32S3 // ESP32S3
-        // ADC2 wifi bug workaround not required, breaks compile
-        // On ESP32S3, ADC2 can take turns with Wifi (?)
-
-        int32_t adc_buf;
-        esp_err_t read_result;
-
-        // Multiple samples
-        for (int i = 0; i < BATTERY_SENSE_SAMPLES; i++) {
-            adc_buf = 0;
-            read_result = -1;
-
-            read_result = adc2_get_raw(adc_channel, ADC_WIDTH_BIT_12, &adc_buf);
-            if (read_result == ESP_OK) {
-                raw += adc_buf;
-                raw_c++; // Count valid samples
            } else {
-                LOG_DEBUG("An attempt to sample ADC2 failed");
+                LOG_DEBUG("ADC read failed: %s", esp_err_to_name(err));
            }
        }

-#else  // Other ESP32
-        int32_t adc_buf = 0;
-        for (int i = 0; i < BATTERY_SENSE_SAMPLES; i++) {
-            // ADC2 wifi bug workaround, see
-            // https://github.com/espressif/arduino-esp32/issues/102
-            WRITE_PERI_REG(SENS_SAR_READ_CTRL2_REG, RTC_reg_b);
-            SET_PERI_REG_MASK(SENS_SAR_READ_CTRL2_REG, SENS_SAR2_DATA_INV);
-            adc2_get_raw(adc_channel, ADC_WIDTH_BIT_12, &adc_buf);
-            raw += adc_buf;
-            raw_c++;
-        }
-#endif // BAT_MEASURE_ADC_UNIT
-
-#endif // End BAT_MEASURE_ADC_UNIT
        return (raw / (raw_c < 1 ? 1 : raw_c));
    }
 #endif
@@ -666,42 +720,31 @@ bool Power::analogInit()
 #ifdef ARCH_STM32WL
    analogReadResolution(BATTERY_SENSE_RESOLUTION_BITS);
 #elif defined(ARCH_ESP32) // ESP32 needs special analog stuff
+    adc_oneshot_unit_init_cfg_t init_config = {
+        .unit_id = unit,
+    };

-#ifndef ADC_WIDTH // max resolution by default
-    static const adc_bits_width_t width = ADC_WIDTH_BIT_12;
-#else
-    static const adc_bits_width_t width = ADC_WIDTH;
-#endif
-#ifndef BAT_MEASURE_ADC_UNIT // ADC1
-    adc1_config_width(width);
-    adc1_config_channel_atten(adc_channel, atten);
-#else                        // ADC2
-    adc2_config_channel_atten(adc_channel, atten);
-#ifndef CONFIG_IDF_TARGET_ESP32S3
-    // ADC2 wifi bug workaround
-    // Not required with ESP32S3, breaks compile
-    RTC_reg_b = READ_PERI_REG(SENS_SAR_READ_CTRL2_REG);
-#endif
-#endif
-    // calibrate ADC
-    esp_adc_cal_value_t val_type = esp_adc_cal_characterize(unit, atten, width, DEFAULT_VREF, adc_characs);
-    // show ADC characterization base
-    if (val_type == ESP_ADC_CAL_VAL_EFUSE_TP) {
-        LOG_INFO("ADC config based on Two Point values stored in eFuse");
-    } else if (val_type == ESP_ADC_CAL_VAL_EFUSE_VREF) {
-        LOG_INFO("ADC config based on reference voltage stored in eFuse");
+    if (!adc_handle) {
+        esp_err_t err = adc_oneshot_new_unit(&init_config, &adc_handle);
+        if (err != ESP_OK) {
+            LOG_ERROR("ADC oneshot init failed: %s", esp_err_to_name(err));
+            return false;
+        }
    }
-#ifdef CONFIG_IDF_TARGET_ESP32S3
-    // ESP32S3
-    else if (val_type == ESP_ADC_CAL_VAL_EFUSE_TP_FIT) {
-        LOG_INFO("ADC config based on Two Point values and fitting curve "
-                 "coefficients stored in eFuse");
+
+    adc_oneshot_chan_cfg_t chan_cfg = {
+        .atten = atten,
+        .bitwidth = adc_width,
+    };
+
+    esp_err_t err = adc_oneshot_config_channel(adc_handle, adc_channel, &chan_cfg);
+    if (err != ESP_OK) {
+        LOG_ERROR("ADC channel config failed: %s", esp_err_to_name(err));
+        return false;
    }
-#endif
-    else {
-        LOG_INFO("ADC config based on default reference voltage");
-    }
-#endif // ARCH_ESP32
+
+    adc_calibrated = initAdcCalibration();
+#endif                    // ARCH_ESP32

    // NRF52 ADC init moved to powerHAL_init in nrf52 platform

@@ -781,8 +824,10 @@ void Power::reboot()
    rp2040.reboot();
 #elif defined(ARCH_PORTDUINO)
    deInitApiServer();
+#ifdef __linux__
    if (aLinuxInputImpl)
        aLinuxInputImpl->deInit();
+#endif
    SPI.end();
    Wire.end();
    Serial1.end();
@@ -222,7 +222,7 @@ void RedirectablePrint::log_to_ble(const char *logLevel, const char *format, va_
    if (config.security.debug_log_api_enabled && !pauseBluetoothLogging) {
        bool isBleConnected = false;
 #ifdef ARCH_ESP32
-        isBleConnected = nimbleBluetooth && nimbleBluetooth->isActive() && nimbleBluetooth->isConnected();
+        isBleConnected = bluetoothApi && bluetoothApi->isActive() && bluetoothApi->isConnected();
 #elif defined(ARCH_NRF52)
        isBleConnected = nrf52Bluetooth != nullptr && nrf52Bluetooth->isConnected();
 #endif
@@ -238,7 +238,7 @@ void RedirectablePrint::log_to_ble(const char *logLevel, const char *format, va_
            auto buffer = std::unique_ptr<uint8_t[]>(new uint8_t[meshtastic_LogRecord_size]);
            size_t size = pb_encode_to_bytes(buffer.get(), meshtastic_LogRecord_size, meshtastic_LogRecord_fields, &logRecord);
 #ifdef ARCH_ESP32
-            nimbleBluetooth->sendLog(buffer.get(), size);
+            bluetoothApi->sendLog(buffer.get(), size);
 #elif defined(ARCH_NRF52)
            nrf52Bluetooth->sendLog(buffer.get(), size);
 #endif
@@ -1,8 +1,8 @@
 #pragma once

 #include "../freertosinc.h"
+#include "Print.h"
 #include "mesh/generated/meshtastic/mesh.pb.h"
-#include <Print.h>
 #include <stdarg.h>
 #include <string>

@@ -7,10 +7,6 @@ static File openFile(const char *filename, bool fullAtomic)
 {
    concurrency::LockGuard g(spiLock);
    LOG_DEBUG("Opening %s, fullAtomic=%d", filename, fullAtomic);
-#ifdef ARCH_NRF52
-    FSCom.remove(filename);
-    return FSCom.open(filename, FILE_O_WRITE);
-#endif
    if (!fullAtomic) {
        FSCom.remove(filename); // Nuke the old file to make space (ignore if it !exists)
    }
@@ -67,9 +63,6 @@ bool SafeFile::close()
    f.close();
    spiLock->unlock();

-#ifdef ARCH_NRF52
-    return true;
-#endif
    if (!testReadback())
        return false;

@@ -0,0 +1,762 @@
+#include "configuration.h"
+
+#if defined(CONFIG_IDF_TARGET_ESP32P4) && defined(CONFIG_ESP_HOSTED_ENABLED) && !MESHTASTIC_EXCLUDE_BLUETOOTH
+#include "BluetoothStatus.h"
+#include "PowerFSM.h"
+#include "bluetooth/HostedBluetooth.h"
+#include "concurrency/OSThread.h"
+#include "esp32-hal-hosted.h"
+#include "esp_err.h"
+#include "esp_event.h"
+#include "esp_hosted.h"
+#include "esp_hosted_event.h"
+#include "main.h"
+#include "mesh/PhoneAPI.h"
+#include "mesh/mesh-pb-constants.h"
+#include <BLEAdvertising.h>
+#include <BLEDevice.h>
+#include <BLESecurity.h>
+#include <BLEServer.h>
+#include <BLEUtils.h>
+#include <array>
+#include <atomic>
+#include <climits>
+#include <cstring>
+#include <driver/gpio.h>
+#include <mutex>
+
+#include "host/ble_gap.h"
+#include "host/ble_store.h"
+
+namespace
+{
+/*
+ * Maintainer note: HostedBluetooth intentionally stays close to NimbleBluetooth
+ * but is not a strict drop-in equivalent.
+ *
+ * Intentional differences from NimbleBluetooth include:
+ * - ESP-Hosted transport lifecycle handling (event callbacks + CP reset GPIO control).
+ * - Data-length update behavior (Hosted currently requests ble_gap_set_data_len on connect).
+ * - No Battery Service exposure here.
+ *
+ * If you modify common BLE flow in one class, review and likely mirror in both:
+ * - PhoneAPI queueing/synchronization between BLE callbacks and runOnce().
+ * - Security/pairing config and passkey UX/status updates.
+ * - Mesh GATT characteristics, permissions, and advertising setup.
+ * - Connection parameter tuning and reconnect/disconnect cleanup paths.
+ */
+constexpr uint16_t kPreferredBleMtu = 517;
+constexpr uint16_t kPreferredBleTxOctets = 251;
+constexpr uint16_t kPreferredBleTxTimeUs = (kPreferredBleTxOctets + 14) * 8;
+constexpr size_t kBluetoothToPhoneQueueSize = 3;
+constexpr size_t kBluetoothFromPhoneQueueSize = 3;
+
+BLECharacteristic *fromNumCharacteristic = nullptr;
+BLECharacteristic *logRadioCharacteristic = nullptr;
+BLEServer *bleServer = nullptr;
+
+static bool passkeyShowing = false;
+std::atomic<uint16_t> hostedConnHandle{BLE_HS_CONN_HANDLE_NONE};
+
+void clearPairingDisplay()
+{
+    if (!passkeyShowing) {
+        return;
+    }
+
+    passkeyShowing = false;
+#if HAS_SCREEN
+    if (screen) {
+        screen->endAlert();
+    }
+#endif
+}
+
+class HostedBluetoothPhoneAPI : public PhoneAPI, public concurrency::OSThread
+{
+  public:
+    HostedBluetoothPhoneAPI() : concurrency::OSThread("HostedBluetooth") { api_type = TYPE_BLE; }
+
+    std::mutex fromPhoneMutex;
+    std::atomic<size_t> fromPhoneQueueSize{0};
+    std::array<BLEValue, kBluetoothFromPhoneQueueSize> fromPhoneQueue{};
+
+    std::mutex toPhoneMutex;
+    std::atomic<size_t> toPhoneQueueSize{0};
+    std::array<std::array<uint8_t, meshtastic_FromRadio_size>, kBluetoothToPhoneQueueSize> toPhoneQueue{};
+    std::array<size_t, kBluetoothToPhoneQueueSize> toPhoneQueueByteSizes{};
+    std::atomic<bool> onReadCallbackIsWaitingForData{false};
+
+  protected:
+    int32_t runOnce() override
+    {
+        while (fromPhoneQueueSize > 0 || onReadCallbackIsWaitingForData) {
+            runOnceHandleFromPhoneQueue();
+            runOnceHandleToPhoneQueue();
+        }
+        return INT32_MAX;
+    }
+
+    void onNowHasData(uint32_t fromRadioNum) override
+    {
+        PhoneAPI::onNowHasData(fromRadioNum);
+
+        if (!fromNumCharacteristic || !bleServer || bleServer->getConnectedCount() == 0) {
+            return;
+        }
+
+        uint8_t val[4];
+        put_le32(val, fromRadioNum);
+        fromNumCharacteristic->setValue(val, sizeof(val));
+        fromNumCharacteristic->notify();
+    }
+
+    bool checkIsConnected() override { return bleServer && bleServer->getConnectedCount() > 0; }
+
+  private:
+    void runOnceHandleToPhoneQueue()
+    {
+        if (!onReadCallbackIsWaitingForData) {
+            return;
+        }
+
+        uint8_t fromRadioBytes[meshtastic_FromRadio_size] = {0};
+        size_t numBytes = getFromRadio(fromRadioBytes);
+
+        if (numBytes > 0 && toPhoneQueueSize < kBluetoothToPhoneQueueSize) {
+            std::lock_guard<std::mutex> guard(toPhoneMutex);
+            const size_t storeAtIndex = toPhoneQueueSize.load();
+            memcpy(toPhoneQueue[storeAtIndex].data(), fromRadioBytes, numBytes);
+            toPhoneQueueByteSizes[storeAtIndex] = numBytes;
+            toPhoneQueueSize++;
+        }
+
+        onReadCallbackIsWaitingForData = false;
+    }
+
+    void runOnceHandleFromPhoneQueue()
+    {
+        if (fromPhoneQueueSize == 0) {
+            return;
+        }
+
+        BLEValue val;
+        {
+            std::lock_guard<std::mutex> guard(fromPhoneMutex);
+            val = fromPhoneQueue[0];
+            for (size_t i = 1; i < fromPhoneQueueSize; ++i) {
+                fromPhoneQueue[i - 1] = fromPhoneQueue[i];
+            }
+            fromPhoneQueueSize--;
+        }
+
+        handleToRadio(val.getData(), val.getLength());
+    }
+};
+
+static HostedBluetoothPhoneAPI *bluetoothPhoneAPI = nullptr;
+uint8_t lastToRadio[MAX_TO_FROM_RADIO_SIZE] = {0};
+
+class HostedBluetoothToRadioCallback : public BLECharacteristicCallbacks
+{
+  public:
+    void onWrite(BLECharacteristic *pCharacteristic) override
+    {
+        if (!bluetoothPhoneAPI) {
+            return;
+        }
+
+        BLEValue val;
+        val.setValue(pCharacteristic->getData(), pCharacteristic->getLength());
+
+        if (memcmp(lastToRadio, val.getData(), val.getLength()) == 0) {
+            return;
+        }
+
+        if (bluetoothPhoneAPI->fromPhoneQueueSize >= kBluetoothFromPhoneQueueSize) {
+            LOG_WARN("Hosted BLE onWrite drop: queue full (%u bytes)", val.getLength());
+            return;
+        }
+
+        memcpy(lastToRadio, val.getData(), val.getLength());
+
+        {
+            std::lock_guard<std::mutex> guard(bluetoothPhoneAPI->fromPhoneMutex);
+            bluetoothPhoneAPI->fromPhoneQueue.at(bluetoothPhoneAPI->fromPhoneQueueSize) = val;
+            bluetoothPhoneAPI->fromPhoneQueueSize++;
+        }
+
+        bluetoothPhoneAPI->setIntervalFromNow(0);
+        concurrency::mainDelay.interrupt();
+    }
+};
+
+class HostedBluetoothFromRadioCallback : public BLECharacteristicCallbacks
+{
+  public:
+    void onRead(BLECharacteristic *pCharacteristic) override
+    {
+        if (!bluetoothPhoneAPI) {
+            return;
+        }
+
+        if (bluetoothPhoneAPI->toPhoneQueueSize == 0) {
+            bluetoothPhoneAPI->onReadCallbackIsWaitingForData = true;
+            bluetoothPhoneAPI->setIntervalFromNow(0);
+            concurrency::mainDelay.interrupt();
+
+            int tries = 0;
+            while (bluetoothPhoneAPI->onReadCallbackIsWaitingForData && tries < 4000) {
+                delay(tries < 20 ? 1 : 5);
+                tries++;
+                if (tries == 4000) {
+                    LOG_WARN("BLE onRead: timeout waiting for data after %d tries, giving up and returning 0-size response",
+                             tries);
+                }
+            }
+        }
+
+        uint8_t fromRadioBytes[meshtastic_FromRadio_size] = {0};
+        size_t numBytes = 0;
+
+        {
+            std::lock_guard<std::mutex> guard(bluetoothPhoneAPI->toPhoneMutex);
+            size_t pending = bluetoothPhoneAPI->toPhoneQueueSize.load();
+            if (pending > 0) {
+                numBytes = bluetoothPhoneAPI->toPhoneQueueByteSizes[0];
+                memcpy(fromRadioBytes, bluetoothPhoneAPI->toPhoneQueue[0].data(), numBytes);
+
+                for (size_t i = 1; i < pending; ++i) {
+                    memcpy(bluetoothPhoneAPI->toPhoneQueue[i - 1].data(), bluetoothPhoneAPI->toPhoneQueue[i].data(),
+                           bluetoothPhoneAPI->toPhoneQueueByteSizes[i]);
+                    bluetoothPhoneAPI->toPhoneQueueByteSizes[i - 1] = bluetoothPhoneAPI->toPhoneQueueByteSizes[i];
+                }
+
+                bluetoothPhoneAPI->toPhoneQueueSize--;
+            }
+        }
+
+        pCharacteristic->setValue(fromRadioBytes, numBytes);
+    }
+};
+
+class HostedBluetoothServerCallback : public BLEServerCallbacks
+{
+  public:
+    explicit HostedBluetoothServerCallback(HostedBluetooth *owner) : owner(owner) {}
+
+  private:
+    HostedBluetooth *owner;
+
+    void onConnect(BLEServer *pServer, struct ble_gap_conn_desc *desc) override
+    {
+        BLEAddress peerAddr(desc->peer_id_addr);
+        LOG_INFO("Hosted BLE incoming connection %s", peerAddr.toString().c_str());
+        owner->setConnected(true);
+        hostedConnHandle = desc->conn_handle;
+
+        const int dataLenResult = ble_gap_set_data_len(desc->conn_handle, kPreferredBleTxOctets, kPreferredBleTxTimeUs);
+        if (dataLenResult != 0) {
+            LOG_WARN("Hosted BLE failed to raise data length rc=%d", dataLenResult);
+        }
+
+        pServer->updateConnParams(desc->conn_handle, 6, 12, 0, 200);
+    }
+
+    void onDisconnect(BLEServer *pServer, struct ble_gap_conn_desc *desc) override
+    {
+        (void)pServer;
+        (void)desc;
+        LOG_INFO("Hosted BLE disconnected");
+        owner->setConnected(false);
+        meshtastic::BluetoothStatus newStatus(meshtastic::BluetoothStatus::ConnectionState::DISCONNECTED);
+        bluetoothStatus->updateStatus(&newStatus);
+        clearPairingDisplay();
+        hostedConnHandle = BLE_HS_CONN_HANDLE_NONE;
+        memset(lastToRadio, 0, sizeof(lastToRadio));
+
+        if (bluetoothPhoneAPI) {
+            bluetoothPhoneAPI->close();
+            {
+                std::lock_guard<std::mutex> guard(bluetoothPhoneAPI->fromPhoneMutex);
+                bluetoothPhoneAPI->fromPhoneQueueSize = 0;
+            }
+            {
+                std::lock_guard<std::mutex> guard(bluetoothPhoneAPI->toPhoneMutex);
+                bluetoothPhoneAPI->toPhoneQueueSize = 0;
+            }
+            bluetoothPhoneAPI->onReadCallbackIsWaitingForData = false;
+        }
+
+        owner->startAdvertising();
+    }
+};
+
+class HostedBluetoothSecurityCallback : public BLESecurityCallbacks
+{
+  public:
+    void onPassKeyNotify(uint32_t passkey) override
+    {
+        LOG_INFO("*** Enter passkey %06u on the peer side ***", passkey);
+        powerFSM.trigger(EVENT_BLUETOOTH_PAIR);
+
+        meshtastic::BluetoothStatus newStatus(std::to_string(passkey));
+        bluetoothStatus->updateStatus(&newStatus);
+
+#if HAS_SCREEN
+        if (screen) {
+            screen->startAlert([passkey](OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y) -> void {
+                char btPIN[16] = "888888";
+                snprintf(btPIN, sizeof(btPIN), "%06u", passkey);
+                int x_offset = display->width() / 2;
+                int y_offset = display->height() <= 80 ? 0 : 12;
+                display->setTextAlignment(TEXT_ALIGN_CENTER);
+                display->setFont(FONT_MEDIUM);
+                display->drawString(x_offset + x, y_offset + y, "Bluetooth");
+#if !defined(M5STACK_UNITC6L)
+                display->setFont(FONT_SMALL);
+                y_offset = display->height() == 64 ? y_offset + FONT_HEIGHT_MEDIUM - 4 : y_offset + FONT_HEIGHT_MEDIUM + 5;
+                display->drawString(x_offset + x, y_offset + y, "Enter this code");
+#endif
+                display->setFont(FONT_LARGE);
+                char pin[8];
+                snprintf(pin, sizeof(pin), "%.3s %.3s", btPIN, btPIN + 3);
+                y_offset = display->height() == 64 ? y_offset + FONT_HEIGHT_SMALL - 5 : y_offset + FONT_HEIGHT_SMALL + 5;
+                display->drawString(x_offset + x, y_offset + y, pin);
+
+                display->setFont(FONT_SMALL);
+                char deviceName[64];
+                snprintf(deviceName, sizeof(deviceName), "Name: %s", getDeviceName());
+                y_offset = display->height() == 64 ? y_offset + FONT_HEIGHT_LARGE - 6 : y_offset + FONT_HEIGHT_LARGE + 5;
+                display->drawString(x_offset + x, y_offset + y, deviceName);
+            });
+        }
+#endif
+
+        passkeyShowing = true;
+    }
+
+    void onAuthenticationComplete(ble_gap_conn_desc *desc) override
+    {
+        (void)desc;
+        LOG_INFO("Hosted BLE authentication complete");
+
+        meshtastic::BluetoothStatus newStatus(meshtastic::BluetoothStatus::ConnectionState::CONNECTED);
+        bluetoothStatus->updateStatus(&newStatus);
+        clearPairingDisplay();
+    }
+};
+
+HostedBluetoothToRadioCallback *toRadioCallbacks = nullptr;
+HostedBluetoothFromRadioCallback *fromRadioCallbacks = nullptr;
+HostedBluetoothSecurityCallback *securityCallbacks = nullptr;
+
+gpio_num_t getSlaveResetGpio()
+{
+#if defined(CONFIG_ESP_HOSTED_GPIO_SLAVE_RESET_SLAVE)
+    return static_cast<gpio_num_t>(CONFIG_ESP_HOSTED_GPIO_SLAVE_RESET_SLAVE);
+#elif defined(CONFIG_ESP_HOSTED_SDIO_GPIO_RESET_SLAVE)
+    return static_cast<gpio_num_t>(CONFIG_ESP_HOSTED_SDIO_GPIO_RESET_SLAVE);
+#else
+    return GPIO_NUM_NC;
+#endif
+}
+
+void setSlaveResetLine(bool assertReset)
+{
+    const gpio_num_t gpioNum = getSlaveResetGpio();
+    if (gpioNum == GPIO_NUM_NC || gpioNum < 0) {
+        return;
+    }
+
+    if (gpio_reset_pin(gpioNum) != ESP_OK) {
+        return;
+    }
+    if (gpio_set_direction(gpioNum, GPIO_MODE_OUTPUT) != ESP_OK) {
+        return;
+    }
+
+    const int activeLevel =
+#if defined(CONFIG_ESP_HOSTED_SDIO_RESET_ACTIVE_HIGH)
+        1;
+#else
+        0;
+#endif
+    const int inactiveLevel = activeLevel ? 0 : 1;
+
+    gpio_set_level(gpioNum, assertReset ? activeLevel : inactiveLevel);
+    LOG_DEBUG("[HostedBluetooth] setSlaveResetLine: GPIO[%d] -> %d (assertReset=%d, activeLevel=%d)", gpioNum,
+              assertReset ? activeLevel : inactiveLevel, assertReset, activeLevel);
+}
+
+void hostedEventHandler(void *arg, esp_event_base_t eventBase, int32_t eventId, void *eventData)
+{
+    (void)eventData;
+
+    auto *self = static_cast<HostedBluetooth *>(arg);
+    if (!self || eventBase != ESP_HOSTED_EVENT) {
+        return;
+    }
+
+    switch (eventId) {
+    case ESP_HOSTED_EVENT_TRANSPORT_UP:
+        LOG_INFO("ESP-Hosted transport is up");
+        self->setConnected(true);
+        break;
+    case ESP_HOSTED_EVENT_TRANSPORT_DOWN:
+        LOG_WARN("ESP-Hosted transport is down");
+        [[fallthrough]];
+    case ESP_HOSTED_EVENT_TRANSPORT_FAILURE:
+        if (eventId == ESP_HOSTED_EVENT_TRANSPORT_FAILURE) {
+            LOG_ERROR("ESP-Hosted transport failure");
+        }
+        self->setConnected(false);
+        break;
+    case ESP_HOSTED_EVENT_CP_INIT:
+    case ESP_HOSTED_EVENT_CP_HEARTBEAT:
+    default:
+        break;
+    }
+}
+} // namespace
+
+HostedBluetooth::HostedBluetooth() {}
+
+HostedBluetooth::~HostedBluetooth()
+{
+    deinit();
+}
+
+bool HostedBluetooth::registerCallbacks()
+{
+    if (callbacksRegistered) {
+        return true;
+    }
+
+    // Defensive cleanup in case setup() is called again after an incomplete/early previous init.
+    // esp_event_handler_unregister can safely fail if the handler wasn't present.
+    esp_event_handler_unregister(ESP_HOSTED_EVENT, ESP_EVENT_ANY_ID, hostedEventHandler);
+
+    esp_err_t err = esp_event_handler_register(ESP_HOSTED_EVENT, ESP_EVENT_ANY_ID, hostedEventHandler, this);
+    if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) {
+        LOG_ERROR("Failed to register hosted event handler: %s", esp_err_to_name(err));
+        return false;
+    }
+    if (err == ESP_ERR_INVALID_STATE) {
+        LOG_WARN("Hosted event handler already registered, continuing");
+    }
+
+    callbacksRegistered = true;
+    return true;
+}
+
+void HostedBluetooth::unregisterCallbacks()
+{
+    if (!callbacksRegistered) {
+        return;
+    }
+
+    esp_event_handler_unregister(ESP_HOSTED_EVENT, ESP_EVENT_ANY_ID, hostedEventHandler);
+
+    callbacksRegistered = false;
+}
+
+void HostedBluetooth::setup()
+{
+    if (active) {
+        return;
+    }
+
+    // Ensure co-processor is released from reset before bringing transport back up.
+    setSlaveResetLine(false);
+    LOG_DEBUG("[HostedBluetooth] setup(): Released co-processor from reset");
+
+    if (!registerCallbacks()) {
+        return;
+    }
+
+    active = setupGatt();
+    firstRssiLogged.store(false);
+    if (active) {
+        LOG_INFO("ESP-Hosted Bluetooth ready");
+    } else {
+        LOG_ERROR("Hosted BLE setup failed in hosted mode");
+        deinit();
+    }
+}
+
+void HostedBluetooth::shutdown()
+{
+    deinit();
+}
+
+void HostedBluetooth::deinit()
+{
+    if (!active && !callbacksRegistered) {
+        return;
+    }
+
+    shutdownGatt();
+    if (BLEDevice::getInitialized()) {
+        BLEDevice::deinit(false);
+    } else {
+        hostedDeinitBLE();
+    }
+
+    // Hold co-processor in reset when hosted transport is disabled to reduce idle draw.
+    setSlaveResetLine(true);
+
+    unregisterCallbacks();
+
+    connected.store(false);
+    active = false;
+    rssi.store(0);
+    firstRssiLogged.store(false);
+}
+
+void HostedBluetooth::clearBonds()
+{
+    ble_store_util_delete_all(BLE_STORE_OBJ_TYPE_PEER_SEC, nullptr);
+    ble_store_util_delete_all(BLE_STORE_OBJ_TYPE_CCCD, nullptr);
+}
+
+bool HostedBluetooth::isActive()
+{
+    return active;
+}
+
+bool HostedBluetooth::isConnected()
+{
+    if (!connected.load()) {
+        return false;
+    }
+    return bleServer && bleServer->getConnectedCount() > 0;
+}
+
+int HostedBluetooth::getRssi()
+{
+    if (!bleServer || !isConnected()) {
+        return 0;
+    }
+
+    uint16_t connHandle = hostedConnHandle.load();
+    if (connHandle == BLE_HS_CONN_HANDLE_NONE) {
+        const auto peers = bleServer->getPeerDevices(true);
+        if (!peers.empty()) {
+            connHandle = peers.begin()->first;
+            hostedConnHandle = connHandle;
+        }
+    }
+    if (connHandle == BLE_HS_CONN_HANDLE_NONE) {
+        return 0;
+    }
+
+    int8_t currentRssi = 0;
+    const int rc = ble_gap_conn_rssi(connHandle, &currentRssi);
+    if (rc == 0) {
+        setRssi(currentRssi);
+        return currentRssi;
+    }
+
+    return rssi.load();
+}
+
+void HostedBluetooth::sendLog(const uint8_t *logMessage, size_t length)
+{
+    if (!logRadioCharacteristic || !isConnected() || length > 512) {
+        return;
+    }
+
+    logRadioCharacteristic->setValue(logMessage, length);
+    logRadioCharacteristic->notify();
+}
+
+void HostedBluetooth::setConnected(bool value)
+{
+    connected.store(value);
+}
+
+void HostedBluetooth::setRssi(int value)
+{
+    rssi.store(value);
+    maybeLogFirstRssi(value);
+}
+
+void HostedBluetooth::maybeLogFirstRssi(int value)
+{
+    bool expected = false;
+    if (firstRssiLogged.compare_exchange_strong(expected, true)) {
+        LOG_INFO("ESP-Hosted first RSSI update: %d dBm", value);
+    }
+}
+
+bool HostedBluetooth::setupGatt()
+{
+    memset(lastToRadio, 0, sizeof(lastToRadio));
+    hostedConnHandle = BLE_HS_CONN_HANDLE_NONE;
+
+    if (!BLEDevice::init(getDeviceName())) {
+        LOG_ERROR("Hosted BLE init failed");
+        return false;
+    }
+#ifdef ESP_PWR_LVL_P9
+    BLEDevice::setPower(ESP_PWR_LVL_P9);
+#endif
+
+    BLESecurity *security = new BLESecurity();
+    security->setInitEncryptionKey(ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK);
+    security->setRespEncryptionKey(ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK);
+    if (config.bluetooth.mode != meshtastic_Config_BluetoothConfig_PairingMode_NO_PIN) {
+        security->setCapability(ESP_IO_CAP_OUT);
+        if (config.bluetooth.mode == meshtastic_Config_BluetoothConfig_PairingMode_RANDOM_PIN) {
+            LOG_INFO("Hosted BLE using random passkey");
+            security->setPassKey(false);
+        } else {
+            LOG_INFO("Hosted BLE using fixed passkey");
+            security->setPassKey(true, config.bluetooth.fixed_pin);
+        }
+        // Enable authorization requirements:
+        // - bonding: true (for persistent storage of the keys)
+        // - MITM: true (enables Man-In-The-Middle protection for password prompts)
+        // - secure connection: true (enables secure connection for encryption)
+        security->setAuthenticationMode(true, true, true);
+    } else {
+        security->setCapability(ESP_IO_CAP_NONE);
+        security->setAuthenticationMode(true, false, false);
+    }
+
+    if (!securityCallbacks) {
+        securityCallbacks = new HostedBluetoothSecurityCallback();
+    }
+    BLEDevice::setSecurityCallbacks(securityCallbacks);
+
+    const int mtuResult = BLEDevice::setMTU(kPreferredBleMtu);
+    if (mtuResult == 0) {
+        LOG_INFO("Hosted BLE MTU request set to %u", kPreferredBleMtu);
+    } else {
+        LOG_WARN("Hosted BLE unable to request MTU %u, rc=%d", kPreferredBleMtu, mtuResult);
+    }
+
+    bleServer = BLEDevice::createServer();
+    if (!bleServer) {
+        LOG_ERROR("Hosted BLE createServer failed");
+        return false;
+    }
+
+    const int nameRc = ble_svc_gap_device_name_set(BLEDevice::getDeviceName().c_str());
+    if (nameRc != 0) {
+        LOG_WARN("Hosted BLE device_name_set rc=%d %s", nameRc, BLEUtils::returnCodeToString(nameRc));
+    }
+
+    bleServer->setCallbacks(new HostedBluetoothServerCallback(this));
+
+    BLEService *meshService = bleServer->createService(MESH_SERVICE_UUID);
+    if (!meshService) {
+        LOG_ERROR("Hosted BLE mesh service creation failed");
+        return false;
+    }
+
+    BLECharacteristic *toRadioCharacteristic = nullptr;
+    BLECharacteristic *fromRadioCharacteristic = nullptr;
+    if (config.bluetooth.mode == meshtastic_Config_BluetoothConfig_PairingMode_NO_PIN) {
+        toRadioCharacteristic = meshService->createCharacteristic(TORADIO_UUID, BLECharacteristic::PROPERTY_WRITE);
+        fromRadioCharacteristic = meshService->createCharacteristic(FROMRADIO_UUID, BLECharacteristic::PROPERTY_READ);
+        fromNumCharacteristic = meshService->createCharacteristic(FROMNUM_UUID, BLECharacteristic::PROPERTY_NOTIFY |
+                                                                                    BLECharacteristic::PROPERTY_READ);
+        logRadioCharacteristic = meshService->createCharacteristic(LOGRADIO_UUID, BLECharacteristic::PROPERTY_NOTIFY |
+                                                                                      BLECharacteristic::PROPERTY_READ);
+    } else {
+        toRadioCharacteristic = meshService->createCharacteristic(TORADIO_UUID, BLECharacteristic::PROPERTY_WRITE |
+                                                                                    BLECharacteristic::PROPERTY_WRITE_AUTHEN |
+                                                                                    BLECharacteristic::PROPERTY_WRITE_ENC);
+        fromRadioCharacteristic = meshService->createCharacteristic(FROMRADIO_UUID, BLECharacteristic::PROPERTY_READ |
+                                                                                        BLECharacteristic::PROPERTY_READ_AUTHEN |
+                                                                                        BLECharacteristic::PROPERTY_READ_ENC);
+        fromNumCharacteristic = meshService->createCharacteristic(
+            FROMNUM_UUID, BLECharacteristic::PROPERTY_NOTIFY | BLECharacteristic::PROPERTY_READ |
+                              BLECharacteristic::PROPERTY_READ_AUTHEN | BLECharacteristic::PROPERTY_READ_ENC);
+        logRadioCharacteristic = meshService->createCharacteristic(
+            LOGRADIO_UUID, BLECharacteristic::PROPERTY_NOTIFY | BLECharacteristic::PROPERTY_READ |
+                               BLECharacteristic::PROPERTY_READ_AUTHEN | BLECharacteristic::PROPERTY_READ_ENC);
+    }
+
+    if (!toRadioCharacteristic || !fromRadioCharacteristic || !fromNumCharacteristic || !logRadioCharacteristic) {
+        LOG_ERROR("Hosted BLE characteristic creation failed");
+        return false;
+    }
+
+    if (!bluetoothPhoneAPI) {
+        bluetoothPhoneAPI = new HostedBluetoothPhoneAPI();
+    }
+
+    if (!toRadioCallbacks) {
+        toRadioCallbacks = new HostedBluetoothToRadioCallback();
+    }
+    if (!fromRadioCallbacks) {
+        fromRadioCallbacks = new HostedBluetoothFromRadioCallback();
+    }
+
+    toRadioCharacteristic->setCallbacks(toRadioCallbacks);
+    fromRadioCharacteristic->setCallbacks(fromRadioCallbacks);
+    meshService->start();
+
+    startAdvertising();
+    return true;
+}
+
+void HostedBluetooth::shutdownGatt()
+{
+    if (bluetoothPhoneAPI) {
+        bluetoothPhoneAPI->close();
+        delete bluetoothPhoneAPI;
+        bluetoothPhoneAPI = nullptr;
+    }
+
+    delete toRadioCallbacks;
+    toRadioCallbacks = nullptr;
+
+    delete fromRadioCallbacks;
+    fromRadioCallbacks = nullptr;
+
+    delete securityCallbacks;
+    securityCallbacks = nullptr;
+
+    if (bleServer) {
+        BLEAdvertising *advertising = BLEDevice::getAdvertising();
+        if (advertising) {
+            advertising->stop();
+        }
+    }
+
+    fromNumCharacteristic = nullptr;
+    logRadioCharacteristic = nullptr;
+    bleServer = nullptr;
+    hostedConnHandle = BLE_HS_CONN_HANDLE_NONE;
+}
+
+void HostedBluetooth::startAdvertising()
+{
+    BLEAdvertising *advertising = BLEDevice::getAdvertising();
+    if (!advertising) {
+        LOG_ERROR("Hosted BLE getAdvertising failed");
+        return;
+    }
+
+    advertising->stop();
+    advertising->reset();
+    advertising->addServiceUUID(MESH_SERVICE_UUID);
+
+    BLEAdvertisementData scan;
+    scan.setName(getDeviceName());
+    advertising->setScanResponseData(scan);
+    advertising->setMinPreferred(0x06);
+    advertising->setMaxPreferred(0x12);
+
+    if (!advertising->start(0)) {
+        LOG_ERROR("Hosted BLE failed to start advertising");
+    } else {
+        LOG_INFO("Hosted BLE advertising started");
+    }
+}
+
+#endif
@@ -0,0 +1,43 @@
+#pragma once
+
+#include "BluetoothCommon.h"
+#include <atomic>
+
+/**
+ * Placeholder backend for ESP32-P4 + ESP-Hosted BLE transport.
+ *
+ * This intentionally mirrors the NimbleBluetooth surface used by the firmware,
+ * so the caller side can stay stable while we implement esp-hosted internals.
+ */
+class HostedBluetooth : public BluetoothApi
+{
+  public:
+    HostedBluetooth();
+    ~HostedBluetooth() override;
+
+    void setup() override;
+    void shutdown() override;
+    void deinit() override;
+    void clearBonds() override;
+    bool isActive() override;
+    bool isConnected() override;
+    int getRssi() override;
+    void sendLog(const uint8_t *logMessage, size_t length) override;
+    void startAdvertising();
+
+    void setConnected(bool value);
+    void setRssi(int value);
+
+  private:
+    bool setupGatt();
+    void shutdownGatt();
+    void maybeLogFirstRssi(int value);
+    bool registerCallbacks();
+    void unregisterCallbacks();
+
+    bool active = false;
+    std::atomic<bool> connected{false};
+    std::atomic<int> rssi{0};
+    std::atomic<bool> firstRssiLogged{false};
+    bool callbacksRegistered = false;
+};
@@ -80,7 +80,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.

 // Pre-hop drop handling (compile-time flag).
 #ifndef MESHTASTIC_PREHOP_DROP
-#define MESHTASTIC_PREHOP_DROP 0
+#define MESHTASTIC_PREHOP_DROP 1
 #endif

 /// Convert a preprocessor name into a quoted string
@@ -162,6 +162,9 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #elif defined(HELTEC_MESH_NODE_T096)
 #define NUM_PA_POINTS 22
 #define TX_GAIN_LORA 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 14, 13, 13, 13, 12, 11, 10, 9, 8, 7
+#elif defined(HELTEC_V4_R8)
+#define NUM_PA_POINTS 22
+#define TX_GAIN_LORA 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 13, 12, 12, 11, 11, 10, 9, 8, 7
 #else
 // If a board enables USE_KCT8103L_PA but does not match a known variant and has
 // not already provided a PA curve, fail at compile time to avoid unsafe defaults.
@@ -70,20 +70,25 @@ bool GPSUpdateScheduling::isUpdateDue()
 // Have we been searching for a GPS position for too long?
 bool GPSUpdateScheduling::searchedTooLong()
 {
+    constexpr uint32_t oneMinuteMs = 60UL * 1000UL;
+    constexpr uint32_t maxSearchClampMs = 15UL * oneMinuteMs; // Hard cap: 15 minutes is always too long
+    uint32_t elapsed = elapsedSearchMs();
+
+    // Anything over 15 minutes is too long, regardless of the broadcast interval.
+    // TODO: Make a smarter algorithm that backs off the search dwell time when not getting a lock.
+    if (elapsed > maxSearchClampMs)
+        return true;
+
    uint32_t minimumOrConfiguredSecs =
        Default::getConfiguredOrMinimumValue(config.position.position_broadcast_secs, default_broadcast_interval_secs);
    uint32_t maxSearchMs = Default::getConfiguredOrDefaultMs(minimumOrConfiguredSecs, default_broadcast_interval_secs);
-    // If broadcast interval set to max, no such thing as "too long"
-    if (maxSearchMs == UINT32_MAX)
-        return false;

    // If we've been searching longer than our position broadcast interval: that's too long
-    else if (elapsedSearchMs() > maxSearchMs)
+    if (elapsed > maxSearchMs)
        return true;

    // Otherwise, not too long yet!
-    else
-        return false;
+    return false;
 }

 // Updates the predicted time-to-get-lock, by exponentially smoothing the latest observation
@@ -524,6 +524,11 @@ void Screen::handleSetOn(bool on, FrameCallback einkScreensaver)
            delay(100);
 #endif
 #if !ARCH_PORTDUINO
+#if defined(USE_ST7789) && defined(VTFT_CTRL)
+            // Ensure panel power rail is enabled before sending wake commands.
+            pinMode(VTFT_CTRL, OUTPUT);
+            digitalWrite(VTFT_CTRL, LOW);
+#endif
            dispdev->displayOn();
 #endif

@@ -545,10 +550,6 @@ void Screen::handleSetOn(bool on, FrameCallback einkScreensaver)
            ui->init();
 #endif
 #if defined(USE_ST7789) && defined(VTFT_LEDA)
-#ifdef VTFT_CTRL
-            pinMode(VTFT_CTRL, OUTPUT);
-            digitalWrite(VTFT_CTRL, LOW);
-#endif
            ui->init();
 #ifdef ESP_PLATFORM
            analogWrite(VTFT_LEDA, BRIGHTNESS_DEFAULT);
@@ -589,23 +590,22 @@ void Screen::handleSetOn(bool on, FrameCallback einkScreensaver)
 #endif
 #ifdef USE_ST7789
            SPI1.end();
-#if defined(ARCH_ESP32)
+            // Keep TFT control pins in deterministic states while timed-off.
+            // Floating/default pin states can corrupt panel edge rows on wake.
 #ifdef VTFT_LEDA
-            pinMode(VTFT_LEDA, ANALOG);
+            pinMode(VTFT_LEDA, OUTPUT);
+            digitalWrite(VTFT_LEDA, !TFT_BACKLIGHT_ON);
 #endif
 #ifdef VTFT_CTRL
-            pinMode(VTFT_CTRL, ANALOG);
-#endif
-            pinMode(ST7789_RESET, ANALOG);
-            pinMode(ST7789_RS, ANALOG);
-            pinMode(ST7789_NSS, ANALOG);
-#else
-            nrf_gpio_cfg_default(VTFT_LEDA);
-            nrf_gpio_cfg_default(VTFT_CTRL);
-            nrf_gpio_cfg_default(ST7789_RESET);
-            nrf_gpio_cfg_default(ST7789_RS);
-            nrf_gpio_cfg_default(ST7789_NSS);
+            pinMode(VTFT_CTRL, OUTPUT);
+            digitalWrite(VTFT_CTRL, HIGH);
 #endif
+            pinMode(ST7789_RESET, OUTPUT);
+            digitalWrite(ST7789_RESET, HIGH);
+            pinMode(ST7789_RS, OUTPUT);
+            digitalWrite(ST7789_RS, HIGH);
+            pinMode(ST7789_NSS, OUTPUT);
+            digitalWrite(ST7789_NSS, HIGH);
 #endif
 #ifdef USE_ST7796
            SPI1.end();
@@ -422,7 +422,7 @@ static LGFX *tft = nullptr;

 #elif defined(ST7789_CS)
 #include <LovyanGFX.hpp> // Graphics and font library for ST7735 driver chip
-#ifdef HELTEC_V4_TFT
+#if defined(HELTEC_V4_TFT) || defined(HELTEC_V4_R8_TFT)
 #include "chsc6x.h"
 #include "lgfx/v1/Touch.hpp"
 namespace lgfx
@@ -444,7 +444,11 @@ class TOUCH_CHSC6X : public ITouch
    bool init(void) override
    {
        if (chsc6xTouch == nullptr) {
+#if (TOUCH_I2C_PORT == 1)
            chsc6xTouch = new chsc6x(&Wire1, TOUCH_SDA_PIN, TOUCH_SCL_PIN, TOUCH_INT_PIN, TOUCH_RST_PIN);
+#else
+            chsc6xTouch = new chsc6x(&Wire, TOUCH_SDA_PIN, TOUCH_SCL_PIN, TOUCH_INT_PIN, TOUCH_RST_PIN);
+#endif
        }
        chsc6xTouch->chsc6x_init();
        return true;
@@ -481,7 +485,7 @@ class LGFX : public lgfx::LGFX_Device
 #if HAS_TOUCHSCREEN
 #if defined(T_WATCH_S3) || defined(ELECROW)
    lgfx::Touch_FT5x06 _touch_instance;
-#elif defined(HELTEC_V4_TFT)
+#elif defined(HELTEC_V4_TFT) || defined(HELTEC_V4_R8_TFT)
    lgfx::TOUCH_CHSC6X _touch_instance;
 #else
    lgfx::Touch_GT911 _touch_instance;
@@ -500,7 +504,11 @@ class LGFX : public lgfx::LGFX_Device
            cfg.freq_write = SPI_FREQUENCY; // SPI clock for transmission (up to 80MHz, rounded to the value obtained by dividing
                                            // 80MHz by an integer)
            cfg.freq_read = SPI_READ_FREQUENCY; // SPI clock when receiving
-            cfg.spi_3wire = false;
+#ifdef SPI_3_WIRE
+            cfg.spi_3wire = SPI_3_WIRE;
+#else
+            cfg.spi_3wire = true;                      // Set to true if reception is done on the MOSI pin
+#endif
            cfg.use_lock = true;               // Set to true to use transaction locking
            cfg.dma_channel = SPI_DMA_CH_AUTO; // SPI_DMA_CH_AUTO; // Set DMA channel to use (0=not use DMA / 1=1ch / 2=ch /
                                               // SPI_DMA_CH_AUTO=auto setting)
@@ -550,8 +558,11 @@ class LGFX : public lgfx::LGFX_Device
            cfg.rgb_order = false;                        // Set to true if the panel's red and blue are swapped
            cfg.dlen_16bit =
                false;             // Set to true for panels that transmit data length in 16-bit units with 16-bit parallel or SPI
+#if defined(HAS_SDCARD)
            cfg.bus_shared = true; // If the bus is shared with the SD card, set to true (bus control with drawJpgFile etc.)
-
+#else
+            cfg.bus_shared = false;
+#endif
            // Set the following only when the display is shifted with a driver with a variable number of pixels, such as the
            // ST7735 or ILI9163.
            // cfg.memory_width = TFT_WIDTH;   // Maximum width supported by the driver IC
@@ -53,10 +53,11 @@ void InkHUD::MessageStore::saveToFlash()
        f.write(reinterpret_cast<const uint8_t *>(&m.timestamp), sizeof(m.timestamp));       // Write timestamp. 4 bytes
        f.write(reinterpret_cast<const uint8_t *>(&m.sender), sizeof(m.sender));             // Write sender NodeId. 4 Bytes
        f.write(reinterpret_cast<const uint8_t *>(&m.channelIndex), sizeof(m.channelIndex)); // Write channel index. 1 Byte
-        f.write(reinterpret_cast<const uint8_t *>(m.text.c_str()), min(MAX_MESSAGE_SIZE, m.text.size())); // Write message text
-        f.write('\0');                                                                                    // Append null term
-        LOG_DEBUG("Wrote message %u, length %u, text \"%s\"", static_cast<uint32_t>(i), min(MAX_MESSAGE_SIZE, m.text.size()),
-                  m.text.c_str());
+        f.write(reinterpret_cast<const uint8_t *>(m.text.c_str()),
+                min((size_t)MAX_MESSAGE_SIZE, m.text.size())); // Write message text
+        f.write('\0');                                         // Append null term
+        LOG_DEBUG("Wrote message %u, length %u, text \"%s\"", static_cast<uint32_t>(i),
+                  min((size_t)MAX_MESSAGE_SIZE, m.text.size()), m.text.c_str());
    }

    // Release firmware's SPI lock, because SafeFile::close needs it
@@ -13,6 +13,8 @@

 #ifdef INPUTBROKER_EXPRESSLRSFIVEWAY_TYPE

+// REVISIT esp_adc_cal.h
+// "legacy adc calibration driver is deprecated, please migrate to use esp_adc/adc_cali.h and esp_adc/adc_cali_scheme.h"
 #include <esp_adc_cal.h>
 #include <soc/adc_channel.h>

@@ -390,8 +390,11 @@ void InputBroker::Init()
                seesawRotary = nullptr;
            }
        }
+#ifdef __linux__
+        // Linux evdev keyboard input only — macOS has no <linux/input.h>.
        aLinuxInputImpl = new LinuxInputImpl();
        aLinuxInputImpl->init();
+#endif
    }
 #endif
 #if !MESHTASTIC_EXCLUDE_INPUTBROKER && HAS_TRACKBALL
@@ -1,5 +1,8 @@
 #pragma once
-#if ARCH_PORTDUINO
+// Linux evdev keyboard input. Only compiled on Linux portduino targets;
+// macOS / non-Linux builds have no <linux/input.h> or epoll, and the
+// headless build doesn't need real keyboards anyway.
+#if ARCH_PORTDUINO && defined(__linux__)
 #include "InputBroker.h"
 #include "concurrency/OSThread.h"
 #include <assert.h>
@@ -1,4 +1,5 @@
-#ifdef ARCH_PORTDUINO
+// Linux evdev impl. Same Linux-only gating as LinuxInput.h.
+#if defined(ARCH_PORTDUINO) && defined(__linux__)
 #pragma once
 #include "LinuxInput.h"
 #include "main.h"
@@ -68,7 +68,7 @@ TLoraPagerKeyboard::TLoraPagerKeyboard()
    : TCA8418KeyboardBase(_TCA8418_ROWS, _TCA8418_COLS), modifierFlag(0), last_modifier_time(0), last_key(UINT8_MAX),
      next_key(UINT8_MAX), last_tap(0L), char_idx(0), tap_interval(0)
 {
-#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 0, 0)
+#if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
    ledcAttach(KB_BL_PIN, LEDC_BACKLIGHT_FREQ, LEDC_BACKLIGHT_BIT_WIDTH);
 #else
    ledcSetup(LEDC_BACKLIGHT_CHANNEL, LEDC_BACKLIGHT_FREQ, LEDC_BACKLIGHT_BIT_WIDTH);
@@ -108,7 +108,7 @@ void TLoraPagerKeyboard::setBacklight(bool on)
    uint32_t _brightness = 0;
    if (on)
        _brightness = brightness;
-#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 0, 0)
+#if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
    ledcWrite(KB_BL_PIN, _brightness);
 #else
    ledcWrite(LEDC_BACKLIGHT_CHANNEL, _brightness);
@@ -49,8 +49,7 @@
 #include "mesh/http/WebServer.h"
 #endif
 #if !MESHTASTIC_EXCLUDE_BLUETOOTH
-#include "nimble/NimbleBluetooth.h"
-NimbleBluetooth *nimbleBluetooth = nullptr;
+BluetoothApi *bluetoothApi = nullptr;
 #endif
 #endif

@@ -12,8 +12,8 @@
 #include <SPI.h>
 #include <map>
 #if defined(ARCH_ESP32) && !defined(CONFIG_IDF_TARGET_ESP32S2)
-#include "nimble/NimbleBluetooth.h"
-extern NimbleBluetooth *nimbleBluetooth;
+#include "BluetoothCommon.h"
+extern BluetoothApi *bluetoothApi;
 #endif
 #ifdef ARCH_NRF52
 #include "NRF52Bluetooth.h"
@@ -2,18 +2,21 @@

 #include "meshUtils.h"

+// Convert seconds to ms, clamping at INT32_MAX (~24.86 days)
+static inline uint32_t secondsToMsClamped(uint32_t secs)
+{
+    constexpr uint32_t MAX_MS = static_cast<uint32_t>(INT32_MAX);
+    return (secs > MAX_MS / 1000U) ? MAX_MS : secs * 1000U;
+}
+
 uint32_t Default::getConfiguredOrDefaultMs(uint32_t configuredInterval, uint32_t defaultInterval)
 {
-    if (configuredInterval > 0)
-        return configuredInterval * 1000;
-    return defaultInterval * 1000;
+    return secondsToMsClamped(configuredInterval > 0 ? configuredInterval : defaultInterval);
 }

 uint32_t Default::getConfiguredOrDefaultMs(uint32_t configuredInterval)
 {
-    if (configuredInterval > 0)
-        return configuredInterval * 1000;
-    return default_broadcast_interval_secs * 1000;
+    return secondsToMsClamped(configuredInterval > 0 ? configuredInterval : default_broadcast_interval_secs);
 }

 uint32_t Default::getConfiguredOrDefault(uint32_t configured, uint32_t defaultValue)
@@ -47,7 +50,14 @@ uint32_t Default::getConfiguredOrDefaultMsScaled(uint32_t configured, uint32_t d
                  meshtastic_Config_DeviceConfig_Role_TAK_TRACKER))
        return getConfiguredOrDefaultMs(configured, defaultValue);

-    return getConfiguredOrDefaultMs(configured, defaultValue) * congestionScalingCoefficient(numOnlineNodes);
+    // Saturate at INT32_MAX to match secondsToMsClamped: float→uint32_t when
+    // out of range is UB, and the result is consumed as an int32_t downstream.
+    constexpr uint32_t MAX_MS = static_cast<uint32_t>(INT32_MAX);
+    uint32_t base = getConfiguredOrDefaultMs(configured, defaultValue);
+    float coef = congestionScalingCoefficient(numOnlineNodes);
+    if (static_cast<double>(base) * static_cast<double>(coef) >= static_cast<double>(MAX_MS))
+        return MAX_MS;
+    return base * coef;
 }

 uint32_t Default::getConfiguredOrMinimumValue(uint32_t configured, uint32_t minValue)
@@ -66,4 +76,4 @@ uint8_t Default::getConfiguredOrDefaultHopLimit(uint8_t configured)
 #else
    return (configured >= HOP_MAX) ? HOP_MAX : config.lora.hop_limit;
 #endif
-}
+}
@@ -19,8 +19,12 @@ extern Adafruit_nRFCrypto nRFCrypto;
 #include <Arduino.h>
 #elif defined(ARCH_PORTDUINO)
 #include <random>
-#include <sys/random.h>
 #include <unistd.h>
+#ifdef __linux__
+#include <sys/random.h> // getrandom()
+#else
+#include <stdlib.h> // arc4random_buf() on Darwin/BSD
+#endif
 #endif

 namespace HardwareRNG
@@ -119,10 +123,16 @@ bool fill(uint8_t *buffer, size_t length, bool useRadioEntropy)
    filled = true;
 #elif defined(ARCH_PORTDUINO)
    // Prefer the host OS RNG first when running under Portduino.
+#ifdef __linux__
    ssize_t generated = ::getrandom(buffer, length, 0);
    if (generated == static_cast<ssize_t>(length)) {
        filled = true;
    }
+#else
+    // arc4random_buf is available on Darwin/BSD and cannot fail.
+    ::arc4random_buf(buffer, length);
+    filled = true;
+#endif

    if (!filled) {
        fillWithRandomDevice(buffer, length);
@@ -6,8 +6,11 @@
 #include "configuration.h"
 #include "detect/LoRaRadioType.h"

-// Sentinel marking the end of a modem preset array
-static constexpr meshtastic_Config_LoRaConfig_ModemPreset MODEM_PRESET_END =
+// Sentinel marking the end of a modem preset array. Declared `const` rather
+// than `constexpr` because the cast from 0xFF to the enum is out-of-range and
+// therefore not a valid constant expression on Clang 16+ (Apple Clang on
+// macOS). The value is only ever compared at runtime, so static-init is fine.
+static const meshtastic_Config_LoRaConfig_ModemPreset MODEM_PRESET_END =
    static_cast<meshtastic_Config_LoRaConfig_ModemPreset>(0xFF);

 // Region profile: bundles the preset list with regulatory parameters shared across regions
@@ -688,7 +688,7 @@ void NodeDB::installDefaultConfig(bool preserveKey = false)
    strncpy(config.network.ntp_server, "meshtastic.pool.ntp.org", 32);

 #if (defined(T_DECK) || defined(T_WATCH_S3) || defined(UNPHONE) || defined(PICOMPUTER_S3) || defined(SENSECAP_INDICATOR) ||      \
-     defined(ELECROW_PANEL) || defined(HELTEC_V4_TFT)) &&                                                                        \
+     defined(ELECROW_PANEL) || defined(HELTEC_V4_TFT) || defined(HELTEC_V4_R8_TFT)) &&                                           \
    HAS_TFT
    // switch BT off by default; use TFT programming mode or hotkey to enable
    config.bluetooth.enabled = false;
@@ -1205,11 +1205,11 @@ void NodeDB::loadFromDisk()
    spiLock->unlock();
 #endif
 #ifdef FSCom
-#ifdef FACTORY_INSTALL
+#if defined(FACTORY_INSTALL) && !defined(ARCH_PORTDUINO)
    spiLock->lock();
    if (!FSCom.exists("/prefs/" xstr(BUILD_EPOCH))) {
        LOG_WARN("Factory Install Reset!");
-        FSCom.format();
+        rmDir("/prefs");
        FSCom.mkdir("/prefs");
        File f2 = FSCom.open("/prefs/" xstr(BUILD_EPOCH), FILE_O_WRITE);
        if (f2) {
@@ -1611,12 +1611,10 @@ bool NodeDB::saveToDisk(int saveWhat)

    if (!success) {
        LOG_ERROR("Failed to save to disk, retrying");
-#ifdef ARCH_NRF52 // @geeksville is not ready yet to say we should do this on other platforms.  See bug #4184 discussion
        spiLock->lock();
-        FSCom.format();
+        fsFormat();
        spiLock->unlock();

-#endif
        success = saveToDiskNoRetry(saveWhat);

        RECORD_CRITICALERROR(success ? meshtastic_CriticalErrorCode_FLASH_CORRUPTION_RECOVERABLE
@@ -522,11 +522,6 @@ size_t PhoneAPI::getFromRadio(uint8_t *buf)
            // LOG_INFO("nodeinfo: num=0x%x, lastseen=%u, id=%s, name=%s", nodeInfoForPhone.num, nodeInfoForPhone.last_heard,
            // nodeInfoForPhone.user.id, nodeInfoForPhone.user.long_name);

-            // Occasional progress logging. (readIndex==2 will be true for the first non-us node)
-            if (readIndex == 2 || readIndex % 20 == 0) {
-                LOG_DEBUG("nodeinfo: %d/%d", readIndex, nodeDB->getNumMeshNodes());
-            }
-
            fromRadioScratch.which_payload_variant = meshtastic_FromRadio_node_info_tag;
            fromRadioScratch.node_info = infoToSend;
            prefetchNodeInfos();
@@ -657,9 +652,11 @@ void PhoneAPI::releaseQueueStatusPhonePacket()
 void PhoneAPI::prefetchNodeInfos()
 {
    bool added = false;
+    bool wasEmpty = false;
    // Keep the queue topped up so BLE reads stay responsive even if DB fetches take a moment.
    {
        concurrency::LockGuard guard(&nodeInfoMutex);
+        wasEmpty = nodeInfoQueue.empty();
        while (nodeInfoQueue.size() < kNodePrefetchDepth) {
            auto nextNode = nodeDB->readNextMeshNode(readIndex);
            if (!nextNode)
@@ -673,11 +670,15 @@ void PhoneAPI::prefetchNodeInfos()
            info.via_mqtt = isUs ? false : info.via_mqtt;
            info.is_favorite = info.is_favorite || isUs;
            nodeInfoQueue.push_back(info);
+            // Log progress here (at fetch time) so readIndex is accurate and each value logs only once.
+            if (readIndex == 2 || readIndex % 20 == 0) {
+                LOG_DEBUG("nodeinfo: %d/%d", readIndex, nodeDB->getNumMeshNodes());
+            }
            added = true;
        }
    }

-    if (added)
+    if (added && wasEmpty)
        onNowHasData(0);
 }

@@ -119,7 +119,7 @@ bool RadioLibInterface::canSendImmediately()
        return true;
 }

-bool RadioLibInterface::receiveDetected(uint16_t irq, ulong syncWordHeaderValidFlag, ulong preambleDetectedFlag)
+bool RadioLibInterface::receiveDetected(uint16_t irq, unsigned long syncWordHeaderValidFlag, unsigned long preambleDetectedFlag)
 {
    bool detected = (irq & (syncWordHeaderValidFlag | preambleDetectedFlag));
    // Handle false detections
@@ -220,7 +220,7 @@ class RadioLibInterface : public RadioInterface, protected concurrency::Notified
  protected:
    uint32_t activeReceiveStart = 0;

-    bool receiveDetected(uint16_t irq, ulong syncWordHeaderValidFlag, ulong preambleDetectedFlag);
+    bool receiveDetected(uint16_t irq, unsigned long syncWordHeaderValidFlag, unsigned long preambleDetectedFlag);

    /** Do any hardware setup needed on entry into send configuration for the radio.
     * Subclasses can customize, but must also call this base method */
@@ -3,9 +3,8 @@
 #include "ServerAPI.h"
 #include <WiFi.h>

-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET

 /**
@@ -55,7 +55,7 @@ extern const pb_msgdesc_t meshtastic_ChannelSet_msg;

 /* Maximum encoded size of messages (where known) */
 #define MESHTASTIC_MESHTASTIC_APPONLY_PB_H_MAX_SIZE meshtastic_ChannelSet_size
-#define meshtastic_ChannelSet_size               682
+#define meshtastic_ChannelSet_size               685

 #ifdef __cplusplus
 } /* extern "C" */
@@ -618,6 +618,8 @@ typedef struct _meshtastic_Config_LoRaConfig {
    bool config_ok_to_mqtt;
    /* Set where LORA FEM is enabled, disabled, or not present */
    meshtastic_Config_LoRaConfig_FEM_LNA_Mode fem_lna_mode;
+    /* Don't use radiolib to initialize the radio, instead listen for a serialHal connection */
+    bool serial_hal_only;
 } meshtastic_Config_LoRaConfig;

 typedef struct _meshtastic_Config_BluetoothConfig {
@@ -779,7 +781,7 @@ extern "C" {
 #define meshtastic_Config_NetworkConfig_init_default {0, "", "", "", 0, _meshtastic_Config_NetworkConfig_AddressMode_MIN, false, meshtastic_Config_NetworkConfig_IpV4Config_init_default, "", 0, 0}
 #define meshtastic_Config_NetworkConfig_IpV4Config_init_default {0, 0, 0, 0}
 #define meshtastic_Config_DisplayConfig_init_default {0, _meshtastic_Config_DisplayConfig_DeprecatedGpsCoordinateFormat_MIN, 0, 0, 0, _meshtastic_Config_DisplayConfig_DisplayUnits_MIN, _meshtastic_Config_DisplayConfig_OledType_MIN, _meshtastic_Config_DisplayConfig_DisplayMode_MIN, 0, 0, _meshtastic_Config_DisplayConfig_CompassOrientation_MIN, 0, 0, 0}
-#define meshtastic_Config_LoRaConfig_init_default {0, _meshtastic_Config_LoRaConfig_ModemPreset_MIN, 0, 0, 0, 0, _meshtastic_Config_LoRaConfig_RegionCode_MIN, 0, 0, 0, 0, 0, 0, 0, 0, 0, {0, 0, 0}, 0, 0, _meshtastic_Config_LoRaConfig_FEM_LNA_Mode_MIN}
+#define meshtastic_Config_LoRaConfig_init_default {0, _meshtastic_Config_LoRaConfig_ModemPreset_MIN, 0, 0, 0, 0, _meshtastic_Config_LoRaConfig_RegionCode_MIN, 0, 0, 0, 0, 0, 0, 0, 0, 0, {0, 0, 0}, 0, 0, _meshtastic_Config_LoRaConfig_FEM_LNA_Mode_MIN, 0}
 #define meshtastic_Config_BluetoothConfig_init_default {0, _meshtastic_Config_BluetoothConfig_PairingMode_MIN, 0}
 #define meshtastic_Config_SecurityConfig_init_default {{0, {0}}, {0, {0}}, 0, {{0, {0}}, {0, {0}}, {0, {0}}}, 0, 0, 0, 0}
 #define meshtastic_Config_SessionkeyConfig_init_default {0}
@@ -790,7 +792,7 @@ extern "C" {
 #define meshtastic_Config_NetworkConfig_init_zero {0, "", "", "", 0, _meshtastic_Config_NetworkConfig_AddressMode_MIN, false, meshtastic_Config_NetworkConfig_IpV4Config_init_zero, "", 0, 0}
 #define meshtastic_Config_NetworkConfig_IpV4Config_init_zero {0, 0, 0, 0}
 #define meshtastic_Config_DisplayConfig_init_zero {0, _meshtastic_Config_DisplayConfig_DeprecatedGpsCoordinateFormat_MIN, 0, 0, 0, _meshtastic_Config_DisplayConfig_DisplayUnits_MIN, _meshtastic_Config_DisplayConfig_OledType_MIN, _meshtastic_Config_DisplayConfig_DisplayMode_MIN, 0, 0, _meshtastic_Config_DisplayConfig_CompassOrientation_MIN, 0, 0, 0}
-#define meshtastic_Config_LoRaConfig_init_zero   {0, _meshtastic_Config_LoRaConfig_ModemPreset_MIN, 0, 0, 0, 0, _meshtastic_Config_LoRaConfig_RegionCode_MIN, 0, 0, 0, 0, 0, 0, 0, 0, 0, {0, 0, 0}, 0, 0, _meshtastic_Config_LoRaConfig_FEM_LNA_Mode_MIN}
+#define meshtastic_Config_LoRaConfig_init_zero   {0, _meshtastic_Config_LoRaConfig_ModemPreset_MIN, 0, 0, 0, 0, _meshtastic_Config_LoRaConfig_RegionCode_MIN, 0, 0, 0, 0, 0, 0, 0, 0, 0, {0, 0, 0}, 0, 0, _meshtastic_Config_LoRaConfig_FEM_LNA_Mode_MIN, 0}
 #define meshtastic_Config_BluetoothConfig_init_zero {0, _meshtastic_Config_BluetoothConfig_PairingMode_MIN, 0}
 #define meshtastic_Config_SecurityConfig_init_zero {{0, {0}}, {0, {0}}, 0, {{0, {0}}, {0, {0}}, {0, {0}}}, 0, 0, 0, 0}
 #define meshtastic_Config_SessionkeyConfig_init_zero {0}
@@ -877,6 +879,7 @@ extern "C" {
 #define meshtastic_Config_LoRaConfig_ignore_mqtt_tag 104
 #define meshtastic_Config_LoRaConfig_config_ok_to_mqtt_tag 105
 #define meshtastic_Config_LoRaConfig_fem_lna_mode_tag 106
+#define meshtastic_Config_LoRaConfig_serial_hal_only_tag 107
 #define meshtastic_Config_BluetoothConfig_enabled_tag 1
 #define meshtastic_Config_BluetoothConfig_mode_tag 2
 #define meshtastic_Config_BluetoothConfig_fixed_pin_tag 3
@@ -1029,7 +1032,8 @@ X(a, STATIC,   SINGULAR, BOOL,     pa_fan_disabled,  15) \
 X(a, STATIC,   REPEATED, UINT32,   ignore_incoming, 103) \
 X(a, STATIC,   SINGULAR, BOOL,     ignore_mqtt,     104) \
 X(a, STATIC,   SINGULAR, BOOL,     config_ok_to_mqtt, 105) \
-X(a, STATIC,   SINGULAR, UENUM,    fem_lna_mode,    106)
+X(a, STATIC,   SINGULAR, UENUM,    fem_lna_mode,    106) \
+X(a, STATIC,   SINGULAR, BOOL,     serial_hal_only, 107)
 #define meshtastic_Config_LoRaConfig_CALLBACK NULL
 #define meshtastic_Config_LoRaConfig_DEFAULT NULL

@@ -1086,7 +1090,7 @@ extern const pb_msgdesc_t meshtastic_Config_SessionkeyConfig_msg;
 #define meshtastic_Config_BluetoothConfig_size   10
 #define meshtastic_Config_DeviceConfig_size      100
 #define meshtastic_Config_DisplayConfig_size     36
-#define meshtastic_Config_LoRaConfig_size        88
+#define meshtastic_Config_LoRaConfig_size        91
 #define meshtastic_Config_NetworkConfig_IpV4Config_size 20
 #define meshtastic_Config_NetworkConfig_size     204
 #define meshtastic_Config_PositionConfig_size    62
@@ -361,7 +361,7 @@ extern const pb_msgdesc_t meshtastic_BackupPreferences_msg;
 /* Maximum encoded size of messages (where known) */
 /* meshtastic_NodeDatabase_size depends on runtime parameters */
 #define MESHTASTIC_MESHTASTIC_DEVICEONLY_PB_H_MAX_SIZE meshtastic_BackupPreferences_size
-#define meshtastic_BackupPreferences_size        2429
+#define meshtastic_BackupPreferences_size        2432
 #define meshtastic_ChannelFile_size              718
 #define meshtastic_DeviceState_size              1737
 #define meshtastic_NodeInfoLite_size             196
@@ -205,7 +205,7 @@ extern const pb_msgdesc_t meshtastic_LocalModuleConfig_msg;

 /* Maximum encoded size of messages (where known) */
 #define MESHTASTIC_MESHTASTIC_LOCALONLY_PB_H_MAX_SIZE meshtastic_LocalModuleConfig_size
-#define meshtastic_LocalConfig_size              754
+#define meshtastic_LocalConfig_size              757
 #define meshtastic_LocalModuleConfig_size        820

 #ifdef __cplusplus
@@ -0,0 +1,19 @@
+/* Automatically generated nanopb constant definitions */
+/* Generated by nanopb-0.4.9.1 */
+
+#include "meshtastic/serial_hal.pb.h"
+#if PB_PROTO_HEADER_VERSION != 40
+#error Regenerate this file with the current version of nanopb generator.
+#endif
+
+PB_BIND(meshtastic_SerialHalCommand, meshtastic_SerialHalCommand, 2)
+
+
+PB_BIND(meshtastic_SerialHalResponse, meshtastic_SerialHalResponse, 2)
+
+
+
+
+
+
+
@@ -0,0 +1,135 @@
+/* Automatically generated nanopb header */
+/* Generated by nanopb-0.4.9.1 */
+
+#ifndef PB_MESHTASTIC_MESHTASTIC_SERIAL_HAL_PB_H_INCLUDED
+#define PB_MESHTASTIC_MESHTASTIC_SERIAL_HAL_PB_H_INCLUDED
+#include <pb.h>
+
+#if PB_PROTO_HEADER_VERSION != 40
+#error Regenerate this file with the current version of nanopb generator.
+#endif
+
+/* Enum definitions */
+typedef enum _meshtastic_SerialHalCommand_Type {
+    meshtastic_SerialHalCommand_Type_UNSET = 0,
+    meshtastic_SerialHalCommand_Type_PIN_MODE = 1,
+    meshtastic_SerialHalCommand_Type_DIGITAL_WRITE = 2,
+    meshtastic_SerialHalCommand_Type_DIGITAL_READ = 3,
+    meshtastic_SerialHalCommand_Type_ATTACH_INTERRUPT = 4,
+    meshtastic_SerialHalCommand_Type_DETACH_INTERRUPT = 5,
+    meshtastic_SerialHalCommand_Type_SPI_TRANSFER = 6,
+    meshtastic_SerialHalCommand_Type_NOOP = 7
+} meshtastic_SerialHalCommand_Type;
+
+typedef enum _meshtastic_SerialHalResponse_Result {
+    meshtastic_SerialHalResponse_Result_OK = 0,
+    meshtastic_SerialHalResponse_Result_ERROR = 1,
+    meshtastic_SerialHalResponse_Result_BAD_REQUEST = 2,
+    meshtastic_SerialHalResponse_Result_UNSUPPORTED = 3
+} meshtastic_SerialHalResponse_Result;
+
+/* Struct definitions */
+typedef PB_BYTES_ARRAY_T(512) meshtastic_SerialHalCommand_data_t;
+typedef struct _meshtastic_SerialHalCommand {
+    /* Host-assigned request id. Replies echo this id back in
+ SerialHalResponse.transaction_id. */
+    uint32_t transaction_id;
+    meshtastic_SerialHalCommand_Type type;
+    uint32_t pin;
+    uint32_t value;
+    uint32_t mode;
+    meshtastic_SerialHalCommand_data_t data;
+} meshtastic_SerialHalCommand;
+
+typedef PB_BYTES_ARRAY_T(512) meshtastic_SerialHalResponse_data_t;
+typedef struct _meshtastic_SerialHalResponse {
+    /* Matches the originating SerialHalCommand.transaction_id for normal
+ request/response traffic.
+
+ A value of 0 indicates an unsolicited interrupt notification generated by
+ the device. In that case, the host should interpret value as the GPIO pin
+ that triggered. */
+    uint32_t transaction_id;
+    meshtastic_SerialHalResponse_Result result;
+    /* Used by DIGITAL_READ replies and interrupt notifications. For interrupt
+ notifications (transaction_id == 0), this carries the pin number. */
+    uint32_t value;
+    meshtastic_SerialHalResponse_data_t data;
+    char error[80];
+} meshtastic_SerialHalResponse;
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Helper constants for enums */
+#define _meshtastic_SerialHalCommand_Type_MIN meshtastic_SerialHalCommand_Type_UNSET
+#define _meshtastic_SerialHalCommand_Type_MAX meshtastic_SerialHalCommand_Type_NOOP
+#define _meshtastic_SerialHalCommand_Type_ARRAYSIZE ((meshtastic_SerialHalCommand_Type)(meshtastic_SerialHalCommand_Type_NOOP+1))
+
+#define _meshtastic_SerialHalResponse_Result_MIN meshtastic_SerialHalResponse_Result_OK
+#define _meshtastic_SerialHalResponse_Result_MAX meshtastic_SerialHalResponse_Result_UNSUPPORTED
+#define _meshtastic_SerialHalResponse_Result_ARRAYSIZE ((meshtastic_SerialHalResponse_Result)(meshtastic_SerialHalResponse_Result_UNSUPPORTED+1))
+
+#define meshtastic_SerialHalCommand_type_ENUMTYPE meshtastic_SerialHalCommand_Type
+
+#define meshtastic_SerialHalResponse_result_ENUMTYPE meshtastic_SerialHalResponse_Result
+
+
+/* Initializer values for message structs */
+#define meshtastic_SerialHalCommand_init_default {0, _meshtastic_SerialHalCommand_Type_MIN, 0, 0, 0, {0, {0}}}
+#define meshtastic_SerialHalResponse_init_default {0, _meshtastic_SerialHalResponse_Result_MIN, 0, {0, {0}}, ""}
+#define meshtastic_SerialHalCommand_init_zero    {0, _meshtastic_SerialHalCommand_Type_MIN, 0, 0, 0, {0, {0}}}
+#define meshtastic_SerialHalResponse_init_zero   {0, _meshtastic_SerialHalResponse_Result_MIN, 0, {0, {0}}, ""}
+
+/* Field tags (for use in manual encoding/decoding) */
+#define meshtastic_SerialHalCommand_transaction_id_tag 1
+#define meshtastic_SerialHalCommand_type_tag     2
+#define meshtastic_SerialHalCommand_pin_tag      3
+#define meshtastic_SerialHalCommand_value_tag    4
+#define meshtastic_SerialHalCommand_mode_tag     5
+#define meshtastic_SerialHalCommand_data_tag     6
+#define meshtastic_SerialHalResponse_transaction_id_tag 1
+#define meshtastic_SerialHalResponse_result_tag  2
+#define meshtastic_SerialHalResponse_value_tag   3
+#define meshtastic_SerialHalResponse_data_tag    4
+#define meshtastic_SerialHalResponse_error_tag   5
+
+/* Struct field encoding specification for nanopb */
+#define meshtastic_SerialHalCommand_FIELDLIST(X, a) \
+X(a, STATIC,   SINGULAR, UINT32,   transaction_id,    1) \
+X(a, STATIC,   SINGULAR, UENUM,    type,              2) \
+X(a, STATIC,   SINGULAR, UINT32,   pin,               3) \
+X(a, STATIC,   SINGULAR, UINT32,   value,             4) \
+X(a, STATIC,   SINGULAR, UINT32,   mode,              5) \
+X(a, STATIC,   SINGULAR, BYTES,    data,              6)
+#define meshtastic_SerialHalCommand_CALLBACK NULL
+#define meshtastic_SerialHalCommand_DEFAULT NULL
+
+#define meshtastic_SerialHalResponse_FIELDLIST(X, a) \
+X(a, STATIC,   SINGULAR, UINT32,   transaction_id,    1) \
+X(a, STATIC,   SINGULAR, UENUM,    result,            2) \
+X(a, STATIC,   SINGULAR, UINT32,   value,             3) \
+X(a, STATIC,   SINGULAR, BYTES,    data,              4) \
+X(a, STATIC,   SINGULAR, STRING,   error,             5)
+#define meshtastic_SerialHalResponse_CALLBACK NULL
+#define meshtastic_SerialHalResponse_DEFAULT NULL
+
+extern const pb_msgdesc_t meshtastic_SerialHalCommand_msg;
+extern const pb_msgdesc_t meshtastic_SerialHalResponse_msg;
+
+/* Defines for backwards compatibility with code written before nanopb-0.4.0 */
+#define meshtastic_SerialHalCommand_fields &meshtastic_SerialHalCommand_msg
+#define meshtastic_SerialHalResponse_fields &meshtastic_SerialHalResponse_msg
+
+/* Maximum encoded size of messages (where known) */
+#define MESHTASTIC_MESHTASTIC_SERIAL_HAL_PB_H_MAX_SIZE meshtastic_SerialHalResponse_size
+#define meshtastic_SerialHalCommand_size         541
+#define meshtastic_SerialHalResponse_size        610
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif
@@ -13,9 +13,8 @@
 #include <WebServer.h>
 #include <WiFi.h>

-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET

 #ifdef ARCH_ESP32
@@ -1,22 +1,34 @@
 /*
-Adds a WebServer and WebService callbacks to meshtastic as Linux Version. The WebServer & Webservices
-runs in a real linux thread beside the portdunio threading emulation. It replaces the complete ESP32
-Webserver libs including generation of SSL certifcicates,  because the use ESP specific details in
-the lib that can't be emulated.
+Adds a WebServer and WebService callbacks to meshtastic via the Portduino/native target (Linux and
+macOS). The WebServer & Webservices run in a real host thread beside the Portduino threading
+emulation. It replaces the complete ESP32 Webserver libs including generation of SSL certificates,
+because those libs use ESP-specific details that can't be emulated.

 The WebServices adapt to the two major phoneapi functions "handleAPIv1FromRadio,handleAPIv1ToRadio"
-The WebServer just adds basaic support to deliver WebContent, so it can be used to
-deliver the WebGui definded by the WebClient Project.
+The WebServer just adds basic support to deliver WebContent, so it can be used to
+deliver the WebGui defined by the WebClient Project.

 Steps to get it running:
-1.) Add these Linux Libs to the compile and target machine:
+
+Linux (apt):
+1.) Add these libs to the compile and target machine:

    sudo apt update && \
-        apt -y install openssl libssl-dev libopenssl libsdl2-dev \
+        apt -y install openssl libssl-dev libsdl2-dev \
                     libulfius-dev liborcania-dev

+macOS (Homebrew):
+1.) Install prerequisites via Homebrew:
+
+    brew install ulfius openssl@3
+
+    The PlatformIO env (native-macos) picks up compiler/linker flags via
+    `pkg-config`. In particular, OpenSSL needs `pkg-config --cflags --libs openssl@3`
+    so both the Homebrew include path and linker flags are provided; ulfius and its
+    dependencies (liborcania, libyder) are also resolved via `pkg-config`.
+
 2.) Configure the root directory of the web Content in the config.yaml file.
-    The followinng tags should be included and set at your needs
+    The following tags should be included and set at your needs

    Example entry in the config.yaml
    Webserver:
@@ -34,7 +46,10 @@ Author: Marc Philipp Hammermann
 mail:   marchammermann@googlemail.com

 */
-#ifdef PORTDUINO_LINUX_HARDWARE
+// Mirrors the guard in PiWebServer.h — see comment there. macOS Homebrew
+// provides ulfius + deps; Linux pulls them via apt. Either way, this
+// translation unit only compiles when the headers are present.
+#ifdef ARCH_PORTDUINO
 #if __has_include(<ulfius.h>)
 #include "PiWebServer.h"
 #include "NodeDB.h"
@@ -1,5 +1,9 @@
 #pragma once
-#ifdef PORTDUINO_LINUX_HARDWARE
+// Portduino webserver is built whenever the ulfius headers are reachable,
+// not only on Linux. macOS users can `brew install ulfius` to enable it;
+// without ulfius the entire body is skipped and main.cpp's matching
+// __has_include guard avoids referencing the type.
+#ifdef ARCH_PORTDUINO
 #if __has_include(<ulfius.h>)
 #include "PhoneAPI.h"
 #include "ulfius-cfg.h"
@@ -12,9 +12,8 @@

 #include <AsyncUDP.h>

-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET

 #define UDP_MULTICAST_DEFAUL_PORT 4403 // Default port for UDP multicast is same as TCP api server
@@ -10,9 +10,8 @@
 #include "target_specific.h"
 #include <WiFi.h>

-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET

 #include <WiFiUdp.h>
@@ -9,9 +9,8 @@
 #include <WiFi.h>
 #endif

-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET

 extern bool needReconnect;
@@ -262,7 +262,7 @@ bool AdminModule::handleReceivedProtobuf(const meshtastic_MeshPacket &mp, meshta
        break;
    }
    case meshtastic_AdminMessage_ota_request_tag: {
-#if defined(ARCH_ESP32)
+#if defined(ARCH_ESP32) && !MESHTASTIC_EXCLUDE_WIFI
        LOG_INFO("OTA Requested");

        if (r->ota_request.ota_hash.size != 32) {
@@ -1336,9 +1336,9 @@ void AdminModule::handleGetDeviceConnectionStatus(const meshtastic_MeshPacket &r
    conn.has_bluetooth = true;
    conn.bluetooth.pin = config.bluetooth.fixed_pin;
 #ifdef ARCH_ESP32
-    if (config.bluetooth.enabled && nimbleBluetooth) {
-        conn.bluetooth.is_connected = nimbleBluetooth->isConnected();
-        conn.bluetooth.rssi = nimbleBluetooth->getRssi();
+    if (config.bluetooth.enabled && bluetoothApi) {
+        conn.bluetooth.is_connected = bluetoothApi->isConnected();
+        conn.bluetooth.rssi = bluetoothApi->getRssi();
    }
 #elif defined(ARCH_NRF52)
    if (config.bluetooth.enabled && nrf52Bluetooth) {
@@ -1412,7 +1412,9 @@ void AdminModule::saveChanges(int saveWhat, bool shouldReboot)

 void AdminModule::handleStoreDeviceUIConfig(const meshtastic_DeviceUIConfig &uicfg)
 {
+#if HAS_SCREEN
    nodeDB->saveProto("/prefs/uiconfig.proto", meshtastic_DeviceUIConfig_size, &meshtastic_DeviceUIConfig_msg, &uicfg);
+#endif
 }

 void AdminModule::handleSetHamMode(const meshtastic_HamParameters &p)
@@ -1597,8 +1599,8 @@ void disableBluetooth()
 {
 #if HAS_BLUETOOTH
 #ifdef ARCH_ESP32
-    if (nimbleBluetooth)
-        nimbleBluetooth->deinit();
+    if (bluetoothApi)
+        bluetoothApi->deinit();
 #elif defined(ARCH_NRF52)
    if (nrf52Bluetooth)
        nrf52Bluetooth->shutdown();
@@ -16,10 +16,28 @@ int32_t INA3221Sensor::runOnce()
        return DEFAULT_SENSOR_MINIMUM_WAIT_TIME_BETWEEN_READS;
    }
    if (!status) {
-        ina3221.begin(nodeTelemetrySensorsMap[sensorType].second);
-        ina3221.setShuntRes(100, 100, 100); // 0.1 Ohm shunt resistors
-        status = true;
+        // Re-initialise with the address and Wire bus from the telemetry sensors map.
+        // (Rob Tillaart INA3221_RT takes address + TwoWire*, unlike sgtwilko which took Wire in begin().)
+        ina3221 = INA3221(nodeTelemetrySensorsMap[sensorType].first, nodeTelemetrySensorsMap[sensorType].second);
+        status = ina3221.begin();
+        if (status) {
+            // Default all three channels to a 0.1 Ω shunt resistor.
+            // Override per-variant by defining INA3221_SHUNT_R_CH1/CH2/CH3 (in Ohms) in variant.h.
+#ifndef INA3221_SHUNT_R_CH1
+#define INA3221_SHUNT_R_CH1 0.1f
+#endif
+#ifndef INA3221_SHUNT_R_CH2
+#define INA3221_SHUNT_R_CH2 0.1f
+#endif
+#ifndef INA3221_SHUNT_R_CH3
+#define INA3221_SHUNT_R_CH3 0.1f
+#endif
+            ina3221.setShuntR(0, INA3221_SHUNT_R_CH1);
+            ina3221.setShuntR(1, INA3221_SHUNT_R_CH2);
+            ina3221.setShuntR(2, INA3221_SHUNT_R_CH3);
+        }
    } else {
+        // Already initialised; status stays true and initI2CSensor() returns next poll interval.
        status = true;
    }
    return initI2CSensor();
@@ -27,12 +45,14 @@ int32_t INA3221Sensor::runOnce()

 void INA3221Sensor::setup() {}

-struct _INA3221Measurement INA3221Sensor::getMeasurement(ina3221_ch_t ch)
+struct _INA3221Measurement INA3221Sensor::getMeasurement(uint8_t ch)
 {
    struct _INA3221Measurement measurement;

-    measurement.voltage = ina3221.getVoltage(ch);
-    measurement.current = ina3221.getCurrent(ch);
+    measurement.voltage = ina3221.getBusVoltage(ch); // Volts
+    // getCurrent_mA() is used instead of getCurrent() because Rob Tillaart's getCurrent()
+    // returns Amperes; the telemetry proto and VoltageSensor/CurrentSensor interfaces expect mA.
+    measurement.current = ina3221.getCurrent_mA(ch); // milliAmps

    return measurement;
 }
@@ -43,7 +63,7 @@ struct _INA3221Measurements INA3221Sensor::getMeasurements()

    // INA3221 has 3 channels starting from 0
    for (int i = 0; i < 3; i++) {
-        measurements.measurements[i] = getMeasurement((ina3221_ch_t)i);
+        measurements.measurements[i] = getMeasurement((uint8_t)i);
    }

    return measurements;
@@ -87,24 +107,41 @@ bool INA3221Sensor::getPowerMetrics(meshtastic_Telemetry *measurement)
    measurement->variant.power_metrics.has_ch3_voltage = true;
    measurement->variant.power_metrics.has_ch3_current = true;

-    measurement->variant.power_metrics.ch1_voltage = m.measurements[INA3221_CH1].voltage;
-    measurement->variant.power_metrics.ch1_current = m.measurements[INA3221_CH1].current;
-    measurement->variant.power_metrics.ch2_voltage = m.measurements[INA3221_CH2].voltage;
-    measurement->variant.power_metrics.ch2_current = m.measurements[INA3221_CH2].current;
-    measurement->variant.power_metrics.ch3_voltage = m.measurements[INA3221_CH3].voltage;
-    measurement->variant.power_metrics.ch3_current = m.measurements[INA3221_CH3].current;
+    // INA3221 channel indices are zero-based (0=CH1, 1=CH2, 2=CH3).
+    measurement->variant.power_metrics.ch1_voltage = m.measurements[0].voltage;
+    measurement->variant.power_metrics.ch1_current = m.measurements[0].current;
+    measurement->variant.power_metrics.ch2_voltage = m.measurements[1].voltage;
+    measurement->variant.power_metrics.ch2_current = m.measurements[1].current;
+    measurement->variant.power_metrics.ch3_voltage = m.measurements[2].voltage;
+    measurement->variant.power_metrics.ch3_current = m.measurements[2].current;

    return true;
 }

 uint16_t INA3221Sensor::getBusVoltageMv()
 {
-    return lround(ina3221.getVoltage(BAT_CH) * 1000);
+    return lround(ina3221.getBusVoltage_mV(BAT_CH));
 }

 int16_t INA3221Sensor::getCurrentMa()
 {
-    return lround(ina3221.getCurrent(BAT_CH));
+    return lround(ina3221.getCurrent_mA(BAT_CH));
+}
+
+// Bus voltage register (0x02 + ch*2): bits [15:3] unsigned, 1 LSB = 8 mV (datasheet p.6).
+// Voltage raw units: 1 count = 8 mV, so V_mV = raw * 8.
+int16_t INA3221Sensor::getRawBusVoltage(uint8_t ch)
+{
+    return (int16_t)(ina3221.getRegister(0x02 + ch * 2) >> 3);
+}
+
+// Shunt voltage register (0x01 + ch*2): bits [15:3] signed two's complement, 1 LSB = 40 µV (datasheet p.6).
+// Current raw units are shunt-voltage counts: 1 count = 40 uV, signed.
+// I_mA = (raw * 40 uV) / R_mOhm, because uV / mOhm = mA.
+// Example for 100 mOhm shunt: I_mA = raw * 40 / 100 = raw * 0.4.
+int16_t INA3221Sensor::getRawShuntCurrent(uint8_t ch)
+{
+    return (int16_t)(ina3221.getRegister(0x01 + ch * 2) >> 3);
 }

 #endif
@@ -1,3 +1,9 @@
+// INA3221 channel aliases (zero-based: 0 = CH1, 1 = CH2, 2 = CH3).
+// Defined before configuration.h so variant.h can use them in INA3221_ENV_CH / INA3221_BAT_CH.
+#define INA3221_CH1 0
+#define INA3221_CH2 1
+#define INA3221_CH3 2
+
 #include "configuration.h"

 #if HAS_TELEMETRY && !MESHTASTIC_EXCLUDE_ENVIRONMENTAL_SENSOR && __has_include(<INA3221.h>)
@@ -9,26 +15,29 @@
 #include <INA3221.h>

 #ifndef INA3221_ENV_CH
-#define INA3221_ENV_CH INA3221_CH1
+#define INA3221_ENV_CH INA3221_CH1 // channel to report in environment metrics (default: CH1)
 #endif

 #ifndef INA3221_BAT_CH
-#define INA3221_BAT_CH INA3221_CH1
+#define INA3221_BAT_CH INA3221_CH1 // channel for device_battery_ina_address (default: CH1)
 #endif

 class INA3221Sensor : public TelemetrySensor, VoltageSensor, CurrentSensor
 {
  private:
-    INA3221 ina3221 = INA3221(INA3221_ADDR42_SDA);
+    // Placeholder constructor; re-initialised with correct address and Wire in runOnce().
+    INA3221 ina3221 = INA3221(INA3221_ADDR);

    // channel to report voltage/current for environment metrics
-    static const ina3221_ch_t ENV_CH = INA3221_ENV_CH;
+    static const uint8_t ENV_CH = INA3221_ENV_CH;
+    static_assert(INA3221_ENV_CH >= 0 && INA3221_ENV_CH <= 2, "INA3221_ENV_CH must be 0, 1, or 2");

    // channel to report battery voltage for device_battery_ina_address
-    static const ina3221_ch_t BAT_CH = INA3221_BAT_CH;
+    static const uint8_t BAT_CH = INA3221_BAT_CH;
+    static_assert(INA3221_BAT_CH >= 0 && INA3221_BAT_CH <= 2, "INA3221_BAT_CH must be 0, 1, or 2");

    // get a single measurement for a channel
-    struct _INA3221Measurement getMeasurement(ina3221_ch_t ch);
+    struct _INA3221Measurement getMeasurement(uint8_t ch);

    // get all measurements for all channels
    struct _INA3221Measurements getMeasurements();
@@ -45,6 +54,10 @@ class INA3221Sensor : public TelemetrySensor, VoltageSensor, CurrentSensor
    bool getMetrics(meshtastic_Telemetry *measurement) override;
    virtual uint16_t getBusVoltageMv() override;
    virtual int16_t getCurrentMa() override;
+
+    // Raw register reads (bits [15:3] right-shifted), no conversion applied.
+    int16_t getRawBusVoltage(uint8_t ch);
+    int16_t getRawShuntCurrent(uint8_t ch);
 };

 struct _INA3221Measurement {
@@ -90,8 +90,8 @@ int32_t PaxcounterModule::runOnce()
            configuration.blecounter = 1;
            configuration.blescantime = 0; // infinite
            configuration.wificounter = 1;
-            configuration.wifi_channel_map = WIFI_CHANNEL_ALL;
-            configuration.wifi_channel_switch_interval = 50;
+            // configuration.wifi_channel_map = WIFI_CHANNEL_ALL;
+            // configuration.wifi_channel_switch_interval = 50;
            configuration.wifi_rssi_threshold = Default::getConfiguredOrDefault(moduleConfig.paxcounter.wifi_threshold, -80);
            configuration.ble_rssi_threshold = Default::getConfiguredOrDefault(moduleConfig.paxcounter.ble_threshold, -80);
            libpax_update_config(&configuration);
@@ -19,9 +19,8 @@
 #include "mesh/wifi/WiFiAPClient.h"
 #include <WiFi.h>
 #endif
-#if HAS_ETHERNET && defined(USE_WS5500)
-#include <ETHClass2.h>
-#define ETH ETH2
+#if HAS_ETHERNET && defined(ARCH_ESP32)
+#include <ETH.h>
 #endif // HAS_ETHERNET
 #include "Default.h"
 #if !defined(ARCH_NRF52) || NRF52_USE_JSON
@@ -32,7 +31,7 @@
 #include <assert.h>
 #include <utility>

-#include <IPAddress.h>
+#include "IPAddress.h"
 #if defined(ARCH_PORTDUINO)
 #include <netinet/in.h>
 #elif !defined(ntohl)
@@ -350,6 +349,8 @@ inline bool isConnectedToNetwork()
    return WiFi.isConnected();
 #elif HAS_ETHERNET
    return Ethernet.linkStatus() == LinkON;
+#elif defined(ARCH_PORTDUINO)
+    return true;
 #else
    return false;
 #endif
@@ -1,5 +1,5 @@
 #include "configuration.h"
-#if !MESHTASTIC_EXCLUDE_BLUETOOTH
+#if !MESHTASTIC_EXCLUDE_BLUETOOTH && !defined(CONFIG_IDF_TARGET_ESP32P4)
 #include "BluetoothCommon.h"
 #include "NimbleBluetooth.h"
 #include "PowerFSM.h"
@@ -10,31 +10,28 @@
 #include "mesh/PhoneAPI.h"
 #include "mesh/mesh-pb-constants.h"
 #include "sleep.h"
-#include <NimBLEDevice.h>
+#include <BLE2904.h>
+#include <BLEAdvertising.h>
+#include <BLEDevice.h>
+#include <BLESecurity.h>
+#include <BLEUtils.h>
 #include <atomic>
 #include <mutex>

-#ifdef NIMBLE_TWO
-#include "NimBLEAdvertising.h"
-#include "NimBLEExtAdvertising.h"
 #include "PowerStatus.h"
-#endif

-#if defined(CONFIG_NIMBLE_CPP_IDF)
 #include "host/ble_gap.h"
-#else
-#include "nimble/nimble/host/include/host/ble_gap.h"
-#endif
-
-#if defined(CONFIG_IDF_TARGET_ESP32S3) || defined(CONFIG_IDF_TARGET_ESP32C6)
+#include "host/ble_store.h"

 namespace
 {
+// Maintainer note: this backend intentionally diverges from HostedBluetooth in a few platform-specific areas.
+// If you change shared BLE flow here (PhoneAPI queue/sync, security/pairing, mesh GATT/advertising,
+// connect/disconnect handling), review and update HostedBluetooth.cpp as needed.
 constexpr uint16_t kPreferredBleMtu = 517;
 constexpr uint16_t kPreferredBleTxOctets = 251;
 constexpr uint16_t kPreferredBleTxTimeUs = (kPreferredBleTxOctets + 14) * 8;
 } // namespace
-#endif

 // Debugging options: careful, they slow things down quite a bit!
 // #define DEBUG_NIMBLE_ON_READ_TIMING  // uncomment to time onRead duration
@@ -44,10 +41,10 @@ constexpr uint16_t kPreferredBleTxTimeUs = (kPreferredBleTxOctets + 14) * 8;
 #define NIMBLE_BLUETOOTH_TO_PHONE_QUEUE_SIZE 3
 #define NIMBLE_BLUETOOTH_FROM_PHONE_QUEUE_SIZE 3

-NimBLECharacteristic *fromNumCharacteristic;
-NimBLECharacteristic *BatteryCharacteristic;
-NimBLECharacteristic *logRadioCharacteristic;
-NimBLEServer *bleServer;
+BLECharacteristic *fromNumCharacteristic;
+BLECharacteristic *BatteryCharacteristic;
+BLECharacteristic *logRadioCharacteristic;
+BLEServer *bleServer;

 static bool passkeyShowing;
 static std::atomic<uint16_t> nimbleBluetoothConnHandle{BLE_HS_CONN_HANDLE_NONE}; // BLE_HS_CONN_HANDLE_NONE means "no connection"
@@ -118,7 +115,8 @@ class BluetoothPhoneAPI : public PhoneAPI, public concurrency::OSThread
        - Yes, we have to do some copy operations on pop because of this, but it's worth it to avoid cross-task memory management.

      NOTIFY IS BROKEN:
-        - Adding NIMBLE_PROPERTY::NOTIFY to FromRadioCharacteristic appears to break things. It is NOT backwards compatible.
+        - Adding BLECharacteristic::PROPERTY_NOTIFY to FromRadioCharacteristic appears to break things. It is NOT backwards
+      compatible.

      ZERO-SIZE READS:
        - Returning a zero-size read from onRead breaks some clients during the config phase. So we have to block onRead until we
@@ -139,7 +137,7 @@ class BluetoothPhoneAPI : public PhoneAPI, public concurrency::OSThread
    std::mutex fromPhoneMutex;
    std::atomic<size_t> fromPhoneQueueSize{0};
    // We use array here (and pay the cost of memcpy) to avoid dynamic memory allocations and frees across FreeRTOS tasks.
-    std::array<NimBLEAttValue, NIMBLE_BLUETOOTH_FROM_PHONE_QUEUE_SIZE> fromPhoneQueue{};
+    std::array<BLEValue, NIMBLE_BLUETOOTH_FROM_PHONE_QUEUE_SIZE> fromPhoneQueue{};

    /* Packets to phone (BLE onRead callback) */
    std::mutex toPhoneMutex;
@@ -301,7 +299,7 @@ class BluetoothPhoneAPI : public PhoneAPI, public concurrency::OSThread
            LOG_DEBUG("NimbleBluetooth: handling ToRadio packet, fromPhoneQueueSize=%u", fromPhoneQueueSize.load());

            // Pop the front of fromPhoneQueue, holding the mutex only briefly while we pop.
-            NimBLEAttValue val;
+            BLEValue val;
            { // scope for fromPhoneMutex mutex
                std::lock_guard<std::mutex> guard(fromPhoneMutex);
                val = fromPhoneQueue[0];
@@ -316,7 +314,7 @@ class BluetoothPhoneAPI : public PhoneAPI, public concurrency::OSThread
                    fromPhoneQueueSize--;
            }

-            handleToRadio(val.data(), val.length());
+            handleToRadio(val.getData(), val.getLength());
        }
    }

@@ -328,9 +326,7 @@ class BluetoothPhoneAPI : public PhoneAPI, public concurrency::OSThread
        PhoneAPI::onNowHasData(fromRadioNum);

 #ifdef DEBUG_NIMBLE_NOTIFY
-
        int currentNotifyCount = notifyCount.fetch_add(1);
-
        uint8_t cc = bleServer->getConnectedCount();
        // This logging slows things down when there are lots of packets going to the phone, like initial connection:
        LOG_DEBUG("BLE notify(%d) fromNum: %d connections: %d", currentNotifyCount, fromRadioNum, cc);
@@ -340,13 +336,7 @@ class BluetoothPhoneAPI : public PhoneAPI, public concurrency::OSThread
        put_le32(val, fromRadioNum);

        fromNumCharacteristic->setValue(val, sizeof(val));
-#ifdef NIMBLE_TWO
-        // NOTE: I don't have any NIMBLE_TWO devices, but this line makes me suspicious, and I suspect it needs to just be
-        // notify().
-        fromNumCharacteristic->notify(val, sizeof(val), BLE_HS_CONN_HANDLE_NONE);
-#else
        fromNumCharacteristic->notify();
-#endif
    }

    /// Check the current underlying physical link to see if the client is currently connected
@@ -409,14 +399,9 @@ static BluetoothPhoneAPI *bluetoothPhoneAPI;
 // Last ToRadio value received from the phone
 static uint8_t lastToRadio[MAX_TO_FROM_RADIO_SIZE];

-class NimbleBluetoothToRadioCallback : public NimBLECharacteristicCallbacks
+class NimbleBluetoothToRadioCallback : public BLECharacteristicCallbacks
 {
-#ifdef NIMBLE_TWO
-    virtual void onWrite(NimBLECharacteristic *pCharacteristic, NimBLEConnInfo &connInfo) override
-#else
-    virtual void onWrite(NimBLECharacteristic *pCharacteristic) override
-
-#endif
+    void onWrite(BLECharacteristic *pCharacteristic) override
    {
        // CAUTION: This callback runs in the NimBLE task!!! Don't do anything except communicate with the main task's runOnce.
        // Assumption: onWrite is serialized by NimBLE, so we don't need to lock here against multiple concurrent onWrite calls.
@@ -428,15 +413,17 @@ class NimbleBluetoothToRadioCallback : public NimBLECharacteristicCallbacks
        LOG_DEBUG("BLE onWrite(%d): start millis=%d", currentWriteCount, startMillis);
 #endif

-        auto val = pCharacteristic->getValue();
+        // Create a BLEValue and populate it with the received data
+        BLEValue val;
+        val.setValue(pCharacteristic->getData(), pCharacteristic->getLength());

-        if (memcmp(lastToRadio, val.data(), val.length()) != 0) {
+        if (memcmp(lastToRadio, val.getData(), val.getLength()) != 0) {
            if (bluetoothPhoneAPI->fromPhoneQueueSize < NIMBLE_BLUETOOTH_FROM_PHONE_QUEUE_SIZE) {
                // Note: the comparison above is safe without a mutex because we are the only method that *increases*
                // fromPhoneQueueSize. (It's okay if fromPhoneQueueSize *decreases* in the main task meanwhile.)
-                memcpy(lastToRadio, val.data(), val.length());
+                memcpy(lastToRadio, val.getData(), val.getLength());

-                { // scope for fromPhoneMutex mutex
+                { // scope for fromPhoneMutex mutexv, pCharacteristic->getLen
                    // Append to fromPhoneQueue, protected by fromPhoneMutex. Hold the mutex as briefly as possible.
                    std::lock_guard<std::mutex> guard(bluetoothPhoneAPI->fromPhoneMutex);
                    bluetoothPhoneAPI->fromPhoneQueue.at(bluetoothPhoneAPI->fromPhoneQueueSize) = val;
@@ -450,24 +437,21 @@ class NimbleBluetoothToRadioCallback : public NimBLECharacteristicCallbacks
 #ifdef DEBUG_NIMBLE_ON_WRITE_TIMING
                int finishMillis = millis();
                LOG_DEBUG("BLE onWrite(%d): append to fromPhoneQueue took %u ms. numBytes=%d", currentWriteCount,
-                          finishMillis - startMillis, val.length());
+                          finishMillis - startMillis, val.getLength());
 #endif
            } else {
-                LOG_WARN("BLE onWrite(%d): Drop ToRadio packet, fromPhoneQueue full (%u bytes)", currentWriteCount, val.length());
+                LOG_WARN("BLE onWrite(%d): Drop ToRadio packet, fromPhoneQueue full (%u bytes)", currentWriteCount,
+                         val.getLength());
            }
        } else {
-            LOG_DEBUG("BLE onWrite(%d): Drop duplicate ToRadio packet (%u bytes)", currentWriteCount, val.length());
+            LOG_DEBUG("BLE onWrite(%d): Drop duplicate ToRadio packet (%u bytes)", currentWriteCount, val.getLength());
        }
    }
 };

-class NimbleBluetoothFromRadioCallback : public NimBLECharacteristicCallbacks
+class NimbleBluetoothFromRadioCallback : public BLECharacteristicCallbacks
 {
-#ifdef NIMBLE_TWO
-    virtual void onRead(NimBLECharacteristic *pCharacteristic, NimBLEConnInfo &connInfo) override
-#else
-    virtual void onRead(NimBLECharacteristic *pCharacteristic) override
-#endif
+    void onRead(BLECharacteristic *pCharacteristic) override
    {
        // CAUTION: This callback runs in the NimBLE task!!! Don't do anything except communicate with the main task's runOnce.

@@ -573,34 +557,15 @@ class NimbleBluetoothFromRadioCallback : public NimBLECharacteristicCallbacks
    }
 };

-class NimbleBluetoothServerCallback : public NimBLEServerCallbacks
+class NimbleBluetoothSecurityCallback : public BLESecurityCallbacks
 {
-#ifdef NIMBLE_TWO
-  public:
-    NimbleBluetoothServerCallback(NimbleBluetooth *ble) { this->ble = ble; }
-
-  private:
-    NimbleBluetooth *ble;
-
-    virtual uint32_t onPassKeyDisplay() override
-#else
-    virtual uint32_t onPassKeyRequest() override
-#endif
+    void onPassKeyNotify(uint32_t passkey) override
    {
-        uint32_t passkey = config.bluetooth.fixed_pin;
-
-        if (config.bluetooth.mode == meshtastic_Config_BluetoothConfig_PairingMode_RANDOM_PIN) {
-            LOG_INFO("Use random passkey");
-            // This is the passkey to be entered on peer - we pick a number >100,000 to ensure 6 digits
-            passkey = random(100000, 999999);
-        }
-        LOG_INFO("*** Enter passkey %d on the peer side ***", passkey);
-
+        LOG_INFO("*** Enter passkey %06u on the peer side ***", passkey);
        powerFSM.trigger(EVENT_BLUETOOTH_PAIR);
        meshtastic::BluetoothStatus newStatus(std::to_string(passkey));
        bluetoothStatus->updateStatus(&newStatus);
-
-#if HAS_SCREEN // Todo: migrate this display code back into Screen class, and observe bluetoothStatus
+#if HAS_SCREEN
        if (screen) {
            screen->startAlert([passkey](OLEDDisplay *display, OLEDDisplayUiState *state, int16_t x, int16_t y) -> void {
                char btPIN[16] = "888888";
@@ -630,15 +595,8 @@ class NimbleBluetoothServerCallback : public NimBLEServerCallbacks
        }
 #endif
        passkeyShowing = true;
-
-        return passkey;
    }
-
-#ifdef NIMBLE_TWO
-    virtual void onAuthenticationComplete(NimBLEConnInfo &connInfo) override
-#else
-    virtual void onAuthenticationComplete(ble_gap_conn_desc *desc) override
-#endif
+    void onAuthenticationComplete(ble_gap_conn_desc *desc) override
    {
        LOG_INFO("BLE authentication complete");

@@ -646,58 +604,47 @@ class NimbleBluetoothServerCallback : public NimBLEServerCallbacks
        bluetoothStatus->updateStatus(&newStatus);
        clearPairingDisplay();

-        // Store the connection handle for future use
-#ifdef NIMBLE_TWO
-        nimbleBluetoothConnHandle = connInfo.getConnHandle();
-#else
        nimbleBluetoothConnHandle = desc->conn_handle;
-#endif
    }
+};

-#ifdef NIMBLE_TWO
-    virtual void onConnect(NimBLEServer *pServer, NimBLEConnInfo &connInfo) override
+class NimbleBluetoothServerCallback : public BLEServerCallbacks
+{
+  public:
+    explicit NimbleBluetoothServerCallback(NimbleBluetooth *ble) : ble(ble) {}
+
+  private:
+    NimbleBluetooth *ble;
+
+    void onConnect(BLEServer *pServer, struct ble_gap_conn_desc *desc)
    {
-        LOG_INFO("BLE incoming connection %s", connInfo.getAddress().toString().c_str());
+        BLEAddress peer_addr(desc->peer_id_addr);
+        LOG_INFO("BLE incoming connection %s", peer_addr.toString().c_str());

-        const uint16_t connHandle = connInfo.getConnHandle();
-#if NIMBLE_ENABLE_2M_PHY && (defined(CONFIG_IDF_TARGET_ESP32S3) || defined(CONFIG_IDF_TARGET_ESP32C6))
-        int phyResult =
-            ble_gap_set_prefered_le_phy(connHandle, BLE_GAP_LE_PHY_2M_MASK, BLE_GAP_LE_PHY_2M_MASK, BLE_GAP_LE_PHY_CODED_ANY);
-        if (phyResult == 0) {
-            LOG_INFO("BLE conn %u requested 2M PHY", connHandle);
-        } else {
-            LOG_WARN("Failed to prefer 2M PHY for conn %u, rc=%d", connHandle, phyResult);
-        }
-#endif
+        const uint16_t connHandle = desc->conn_handle;

+        // With Google Pixel 8 Android devices, this causes ESP32 device crash
+        // when phone reconnects. Disable this to make progress on the
+        // Arduino v3 migration while we investigate the Android compatibility
+        // issue.
+#if 0
        int dataLenResult = ble_gap_set_data_len(connHandle, kPreferredBleTxOctets, kPreferredBleTxTimeUs);
        if (dataLenResult == 0) {
            LOG_INFO("BLE conn %u requested data length %u bytes", connHandle, kPreferredBleTxOctets);
        } else {
            LOG_WARN("Failed to raise data length for conn %u, rc=%d", connHandle, dataLenResult);
        }
+#endif

-        LOG_INFO("BLE conn %u initial MTU %u (target %u)", connHandle, connInfo.getMTU(), kPreferredBleMtu);
+        LOG_INFO("BLE conn %u peer MTU %u (target %u)", connHandle, pServer->getPeerMTU(connHandle), kPreferredBleMtu);
        pServer->updateConnParams(connHandle, 6, 12, 0, 200);
    }
-#endif

-#ifdef NIMBLE_TWO
-    virtual void onDisconnect(NimBLEServer *pServer, NimBLEConnInfo &connInfo, int reason) override
+    void onDisconnect(BLEServer *pServer, struct ble_gap_conn_desc *desc)
    {
-        LOG_INFO("BLE disconnect reason: %d", reason);
-#else
-    virtual void onDisconnect(NimBLEServer *pServer, ble_gap_conn_desc *desc) override
-    {
-        LOG_INFO("BLE disconnect");
-#endif
-#ifdef NIMBLE_TWO
+        LOG_INFO("BLE disconnected");
        if (ble->isDeInit)
            return;
-#else
-        if (nimbleBluetooth && nimbleBluetooth->isDeInit)
-            return;
-#endif

        meshtastic::BluetoothStatus newStatus(meshtastic::BluetoothStatus::ConnectionState::DISCONNECTED);
        bluetoothStatus->updateStatus(&newStatus);
@@ -722,43 +669,51 @@ class NimbleBluetoothServerCallback : public NimBLEServerCallbacks
            bluetoothPhoneAPI->writeCount = 0;
        }

-        // Clear the last ToRadio packet buffer to avoid rejecting first packet from new connection
        memset(lastToRadio, 0, sizeof(lastToRadio));

-        nimbleBluetoothConnHandle = BLE_HS_CONN_HANDLE_NONE; // BLE_HS_CONN_HANDLE_NONE means "no connection"
+        nimbleBluetoothConnHandle = BLE_HS_CONN_HANDLE_NONE;

-#ifdef NIMBLE_TWO
-        // Restart Advertising
        ble->startAdvertising();
-#else
-        NimBLEAdvertising *pAdvertising = NimBLEDevice::getAdvertising();
-        if (!pAdvertising->start(0)) {
-            if (pAdvertising->isAdvertising()) {
-                LOG_DEBUG("BLE advertising already running");
-            } else {
-                LOG_ERROR("BLE failed to restart advertising");
-            }
-        }
-#endif
    }
 };

 static NimbleBluetoothToRadioCallback *toRadioCallbacks;
 static NimbleBluetoothFromRadioCallback *fromRadioCallbacks;

+void NimbleBluetooth::startAdvertising()
+{
+    BLEAdvertising *pAdvertising = BLEDevice::getAdvertising();
+    pAdvertising->stop();
+    pAdvertising->reset();
+
+    pAdvertising->addServiceUUID(MESH_SERVICE_UUID);
+    // if (powerStatus->getHasBattery() == 1) {
+    //     pAdvertising->addServiceUUID(BLEUUID((uint16_t)0x180f));
+    // }
+
+    BLEAdvertisementData scan = BLEAdvertisementData();
+    scan.setName(getDeviceName());
+    pAdvertising->setScanResponseData(scan);
+    pAdvertising->setMinPreferred(0x06); // functions that help with iPhone connections issue
+    pAdvertising->setMaxPreferred(0x12);
+
+    if (!pAdvertising->start(0)) {
+        LOG_ERROR("BLE failed to start advertising");
+    } else {
+        LOG_DEBUG("BLE Advertising started");
+    }
+}
+
 void NimbleBluetooth::shutdown()
 {
-    // No measurable power saving for ESP32 during light-sleep(?)
 #ifndef ARCH_ESP32
-    // Shutdown bluetooth for minimum power draw
    LOG_INFO("Disable bluetooth");
-    NimBLEAdvertising *pAdvertising = NimBLEDevice::getAdvertising();
+    BLEAdvertising *pAdvertising = BLEDevice::getAdvertising();
    pAdvertising->reset();
    pAdvertising->stop();
 #endif
 }

-// Proper shutdown for ESP32. Needs reboot to reverse.
 void NimbleBluetooth::deinit()
 {
 #ifdef ARCH_ESP32
@@ -768,21 +723,19 @@ void NimbleBluetooth::deinit()
 #ifdef BLE_LED
    digitalWrite(BLE_LED, LED_STATE_OFF);
 #endif
-#ifndef NIMBLE_TWO
-    NimBLEDevice::deinit();
-#endif
+
+    BLEDevice::deinit(true);
 #endif
 }

-// Has initial setup been completed
 bool NimbleBluetooth::isActive()
 {
-    return bleServer;
+    return bleServer != nullptr;
 }

 bool NimbleBluetooth::isConnected()
 {
-    return bleServer->getConnectedCount() > 0;
+    return bleServer && bleServer->getConnectedCount() > 0;
 }

 int NimbleBluetooth::getRssi()
@@ -795,9 +748,9 @@ int NimbleBluetooth::getRssi()
    uint16_t connHandle = nimbleBluetoothConnHandle.load();

    if (connHandle == BLE_HS_CONN_HANDLE_NONE) {
-        const auto peers = bleServer->getPeerDevices();
+        const auto peers = bleServer->getPeerDevices(true);
        if (!peers.empty()) {
-            connHandle = peers.front();
+            connHandle = peers.begin()->first;
            nimbleBluetoothConnHandle = connHandle;
        }
    }
@@ -825,74 +778,84 @@ void NimbleBluetooth::setup()

    LOG_INFO("Init the NimBLE bluetooth module");

-    NimBLEDevice::init(getDeviceName());
-    NimBLEDevice::setPower(ESP_PWR_LVL_P9);
+    BLEDevice::init(getDeviceName());
+    BLEDevice::setPower(ESP_PWR_LVL_P9);

-#if NIMBLE_ENABLE_2M_PHY && (defined(CONFIG_IDF_TARGET_ESP32S3) || defined(CONFIG_IDF_TARGET_ESP32C6))
-    int mtuResult = NimBLEDevice::setMTU(kPreferredBleMtu);
+    int mtuResult = BLEDevice::setMTU(kPreferredBleMtu);
    if (mtuResult == 0) {
        LOG_INFO("BLE MTU request set to %u", kPreferredBleMtu);
    } else {
        LOG_WARN("Unable to request MTU %u, rc=%d", kPreferredBleMtu, mtuResult);
    }

-    int phyResult = ble_gap_set_prefered_default_le_phy(BLE_GAP_LE_PHY_2M_MASK, BLE_GAP_LE_PHY_2M_MASK);
-    if (phyResult == 0) {
-        LOG_INFO("BLE default PHY preference set to 2M");
-    } else {
-        LOG_WARN("Failed to prefer 2M PHY by default, rc=%d", phyResult);
-    }
-
-    int dataLenResult = ble_gap_write_sugg_def_data_len(kPreferredBleTxOctets, kPreferredBleTxTimeUs);
-    if (dataLenResult == 0) {
-        LOG_INFO("BLE suggested data length set to %u bytes", kPreferredBleTxOctets);
-    } else {
-        LOG_WARN("Failed to raise suggested data length (%u/%u), rc=%d", kPreferredBleTxOctets, kPreferredBleTxTimeUs,
-                 dataLenResult);
-    }
-#endif
-
+    BLESecurity *pSecurity = new BLESecurity();
+    pSecurity->setInitEncryptionKey(ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK);
+    pSecurity->setRespEncryptionKey(ESP_BLE_ENC_KEY_MASK | ESP_BLE_ID_KEY_MASK);
    if (config.bluetooth.mode != meshtastic_Config_BluetoothConfig_PairingMode_NO_PIN) {
-        NimBLEDevice::setSecurityAuth(BLE_SM_PAIR_AUTHREQ_BOND | BLE_SM_PAIR_AUTHREQ_MITM | BLE_SM_PAIR_AUTHREQ_SC);
-        NimBLEDevice::setSecurityInitKey(BLE_SM_PAIR_KEY_DIST_ENC | BLE_SM_PAIR_KEY_DIST_ID);
-        NimBLEDevice::setSecurityRespKey(BLE_SM_PAIR_KEY_DIST_ENC | BLE_SM_PAIR_KEY_DIST_ID);
-        NimBLEDevice::setSecurityIOCap(BLE_HS_IO_DISPLAY_ONLY);
+        // Set IO capability to DisplayOnly for MITM authentication
+        pSecurity->setCapability(ESP_IO_CAP_OUT);
+        // Set the passkey
+        if (config.bluetooth.mode == meshtastic_Config_BluetoothConfig_PairingMode_RANDOM_PIN) {
+            LOG_INFO("Use random passkey");
+            pSecurity->setPassKey(false); // generate a random passkey
+        } else {
+            LOG_INFO("Use fixed passkey");
+            pSecurity->setPassKey(true, config.bluetooth.fixed_pin);
+        }
+        // Enable authorization requirements:
+        // - bonding: true (for persistent storage of the keys)
+        // - MITM: true (enables Man-In-The-Middle protection for password prompts)
+        // - secure connection: true (enables secure connection for encryption)
+        pSecurity->setAuthenticationMode(true, true, true);
+    } else {
+        // No IO capability for no PIN mode
+        pSecurity->setCapability(ESP_IO_CAP_NONE);
+        // No PIN mode: no MITM protection
+        pSecurity->setAuthenticationMode(true, false, false);
    }
-    bleServer = NimBLEDevice::createServer();
-#ifdef NIMBLE_TWO
-    NimbleBluetoothServerCallback *serverCallbacks = new NimbleBluetoothServerCallback(this);
-#else
-    NimbleBluetoothServerCallback *serverCallbacks = new NimbleBluetoothServerCallback();
-#endif
-    bleServer->setCallbacks(serverCallbacks, true);
+    // Set the security callbacks
+    BLEDevice::setSecurityCallbacks(new NimbleBluetoothSecurityCallback());
+    bleServer = BLEDevice::createServer();
+
+    // BLEDevice::createServer calls ble_svc_gap_init, which resets the device
+    // name to default, so set it again.
+    int nameRc = ble_svc_gap_device_name_set(BLEDevice::getDeviceName().c_str());
+    if (nameRc != 0) {
+        LOG_ERROR("ble_svc_gap_device_name_set: rc=%d %s", nameRc, BLEUtils::returnCodeToString(nameRc));
+    }
+
+    bleServer->setCallbacks(new NimbleBluetoothServerCallback(this));
    setupService();
    startAdvertising();
 }

 void NimbleBluetooth::setupService()
 {
-    NimBLEService *bleService = bleServer->createService(MESH_SERVICE_UUID);
-    NimBLECharacteristic *ToRadioCharacteristic;
-    NimBLECharacteristic *FromRadioCharacteristic;
+    BLEService *bleService = bleServer->createService(MESH_SERVICE_UUID);
+    BLECharacteristic *ToRadioCharacteristic;
+    BLECharacteristic *FromRadioCharacteristic;
    // Define the characteristics that the app is looking for
    if (config.bluetooth.mode == meshtastic_Config_BluetoothConfig_PairingMode_NO_PIN) {
-        ToRadioCharacteristic = bleService->createCharacteristic(TORADIO_UUID, NIMBLE_PROPERTY::WRITE);
+        ToRadioCharacteristic = bleService->createCharacteristic(TORADIO_UUID, BLECharacteristic::PROPERTY_WRITE);
        // Allow notifications so phones can stream FromRadio without polling.
-        FromRadioCharacteristic = bleService->createCharacteristic(FROMRADIO_UUID, NIMBLE_PROPERTY::READ);
-        fromNumCharacteristic = bleService->createCharacteristic(FROMNUM_UUID, NIMBLE_PROPERTY::NOTIFY | NIMBLE_PROPERTY::READ);
-        logRadioCharacteristic =
-            bleService->createCharacteristic(LOGRADIO_UUID, NIMBLE_PROPERTY::NOTIFY | NIMBLE_PROPERTY::READ, 512U);
-    } else {
-        ToRadioCharacteristic = bleService->createCharacteristic(
-            TORADIO_UUID, NIMBLE_PROPERTY::WRITE | NIMBLE_PROPERTY::WRITE_AUTHEN | NIMBLE_PROPERTY::WRITE_ENC);
-        FromRadioCharacteristic = bleService->createCharacteristic(
-            FROMRADIO_UUID, NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::READ_AUTHEN | NIMBLE_PROPERTY::READ_ENC);
+        FromRadioCharacteristic = bleService->createCharacteristic(FROMRADIO_UUID, BLECharacteristic::PROPERTY_READ);
        fromNumCharacteristic =
-            bleService->createCharacteristic(FROMNUM_UUID, NIMBLE_PROPERTY::NOTIFY | NIMBLE_PROPERTY::READ |
-                                                               NIMBLE_PROPERTY::READ_AUTHEN | NIMBLE_PROPERTY::READ_ENC);
+            bleService->createCharacteristic(FROMNUM_UUID, BLECharacteristic::PROPERTY_NOTIFY | BLECharacteristic::PROPERTY_READ);
+        logRadioCharacteristic = bleService->createCharacteristic(LOGRADIO_UUID, BLECharacteristic::PROPERTY_NOTIFY |
+                                                                                     BLECharacteristic::PROPERTY_READ);
+    } else {
+        ToRadioCharacteristic = bleService->createCharacteristic(TORADIO_UUID, BLECharacteristic::PROPERTY_WRITE |
+                                                                                   BLECharacteristic::PROPERTY_WRITE_AUTHEN |
+                                                                                   BLECharacteristic::PROPERTY_WRITE_ENC);
+        FromRadioCharacteristic = bleService->createCharacteristic(FROMRADIO_UUID, BLECharacteristic::PROPERTY_READ |
+                                                                                       BLECharacteristic::PROPERTY_READ_AUTHEN |
+                                                                                       BLECharacteristic::PROPERTY_READ_ENC);
+        fromNumCharacteristic = bleService->createCharacteristic(
+            FROMNUM_UUID, BLECharacteristic::PROPERTY_NOTIFY | BLECharacteristic::PROPERTY_READ |
+                              BLECharacteristic::PROPERTY_READ_AUTHEN | BLECharacteristic::PROPERTY_READ_ENC);
        logRadioCharacteristic = bleService->createCharacteristic(
-            LOGRADIO_UUID,
-            NIMBLE_PROPERTY::NOTIFY | NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::READ_AUTHEN | NIMBLE_PROPERTY::READ_ENC, 512U);
+            LOGRADIO_UUID, BLECharacteristic::PROPERTY_NOTIFY | BLECharacteristic::PROPERTY_READ |
+                               BLECharacteristic::PROPERTY_READ_AUTHEN | BLECharacteristic::PROPERTY_READ_ENC);
    }
    bluetoothPhoneAPI = new BluetoothPhoneAPI();

@@ -905,76 +868,31 @@ void NimbleBluetooth::setupService()
    bleService->start();

    // Setup the battery service
-    NimBLEService *batteryService = bleServer->createService(NimBLEUUID((uint16_t)0x180f)); // 0x180F is the Battery Service
-    BatteryCharacteristic = batteryService->createCharacteristic( // 0x2A19 is the Battery Level characteristic)
-        (uint16_t)0x2a19, NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::NOTIFY, 1);
-#ifdef NIMBLE_TWO
-    NimBLE2904 *batteryLevelDescriptor = BatteryCharacteristic->create2904();
-#else
-    NimBLE2904 *batteryLevelDescriptor = (NimBLE2904 *)BatteryCharacteristic->createDescriptor((uint16_t)0x2904);
-#endif
-    batteryLevelDescriptor->setFormat(NimBLE2904::FORMAT_UINT8);
+    BLEService *batteryService = bleServer->createService(BLEUUID((uint16_t)0x180f)); // 0x180F is the Battery Service
+    BLE2904 *batteryLevelDescriptor = new BLE2904();
+    batteryLevelDescriptor->setFormat(BLE2904::FORMAT_UINT8);
    batteryLevelDescriptor->setNamespace(1);
    batteryLevelDescriptor->setUnit(0x27ad);
-
+    BatteryCharacteristic = batteryService->createCharacteristic( // 0x2A19 is the Battery Level characteristic)
+        (uint16_t)0x2a19, BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_NOTIFY);
+    BatteryCharacteristic->addDescriptor(batteryLevelDescriptor);
    batteryService->start();
 }

-void NimbleBluetooth::startAdvertising()
-{
-#ifdef NIMBLE_TWO
-    NimBLEExtAdvertising *pAdvertising = NimBLEDevice::getAdvertising();
-    NimBLEExtAdvertisement legacyAdvertising;
-
-    legacyAdvertising.setLegacyAdvertising(true);
-    legacyAdvertising.setScannable(true);
-    legacyAdvertising.setConnectable(true);
-    legacyAdvertising.setFlags(BLE_HS_ADV_F_DISC_GEN);
-    if (powerStatus->getHasBattery() == 1) {
-        legacyAdvertising.setCompleteServices(NimBLEUUID((uint16_t)0x180f));
-    }
-    legacyAdvertising.setCompleteServices(NimBLEUUID(MESH_SERVICE_UUID));
-    legacyAdvertising.setMinInterval(500);
-    legacyAdvertising.setMaxInterval(1000);
-
-    NimBLEExtAdvertisement legacyScanResponse;
-    legacyScanResponse.setLegacyAdvertising(true);
-    legacyScanResponse.setConnectable(true);
-    legacyScanResponse.setName(getDeviceName());
-
-    if (!pAdvertising->setInstanceData(0, legacyAdvertising)) {
-        LOG_ERROR("BLE failed to set legacyAdvertising");
-    } else if (!pAdvertising->setScanResponseData(0, legacyScanResponse)) {
-        LOG_ERROR("BLE failed to set legacyScanResponse");
-    } else if (!pAdvertising->start(0, 0, 0)) {
-        LOG_ERROR("BLE failed to start legacyAdvertising");
-    }
-#else
-    NimBLEAdvertising *pAdvertising = NimBLEDevice::getAdvertising();
-    pAdvertising->reset();
-    pAdvertising->addServiceUUID(MESH_SERVICE_UUID);
-    pAdvertising->addServiceUUID(NimBLEUUID((uint16_t)0x180f)); // 0x180F is the Battery Service
-    pAdvertising->start(0);
-#endif
-}
-
 /// Given a level between 0-100, update the BLE attribute
 void updateBatteryLevel(uint8_t level)
 {
-    if ((config.bluetooth.enabled == true) && bleServer && nimbleBluetooth->isConnected()) {
+    if ((config.bluetooth.enabled == true) && bleServer && bluetoothApi && bluetoothApi->isConnected()) {
        BatteryCharacteristic->setValue(&level, 1);
-#ifdef NIMBLE_TWO
-        BatteryCharacteristic->notify(&level, 1, BLE_HS_CONN_HANDLE_NONE);
-#else
        BatteryCharacteristic->notify();
-#endif
    }
 }

 void NimbleBluetooth::clearBonds()
 {
    LOG_INFO("Clearing bluetooth bonds!");
-    NimBLEDevice::deleteAllBonds();
+    ble_store_util_delete_all(BLE_STORE_OBJ_TYPE_PEER_SEC, nullptr);
+    ble_store_util_delete_all(BLE_STORE_OBJ_TYPE_CCCD, nullptr);
 }

 void NimbleBluetooth::sendLog(const uint8_t *logMessage, size_t length)
@@ -982,11 +900,26 @@ void NimbleBluetooth::sendLog(const uint8_t *logMessage, size_t length)
    if (!bleServer || !isConnected() || length > 512) {
        return;
    }
-#ifdef NIMBLE_TWO
-    logRadioCharacteristic->notify(logMessage, length, BLE_HS_CONN_HANDLE_NONE);
-#else
-    logRadioCharacteristic->notify(logMessage, length, true);
+    logRadioCharacteristic->setValue(logMessage, length);
+    logRadioCharacteristic->notify();
+}
+
+void clearNVS()
+{
+    ble_store_util_delete_all(BLE_STORE_OBJ_TYPE_PEER_SEC, nullptr);
+    ble_store_util_delete_all(BLE_STORE_OBJ_TYPE_CCCD, nullptr);
+#ifdef ARCH_ESP32
+    ESP.restart();
 #endif
 }

+#else
+
+void updateBatteryLevel(uint8_t level)
+{
+    (void)level;
+}
+
+void clearNVS() {}
+
 #endif
@@ -1,27 +1,24 @@
 #pragma once
 #include "BluetoothCommon.h"

-class NimbleBluetooth : BluetoothApi
+class NimbleBluetooth : public BluetoothApi
 {
  public:
-    void setup();
-    void shutdown();
-    void deinit();
-    void clearBonds();
-    bool isActive();
-    bool isConnected();
-    int getRssi();
-    void sendLog(const uint8_t *logMessage, size_t length);
-#if defined(NIMBLE_TWO)
+    void setup() override;
+    void shutdown() override;
+    void deinit() override;
+    void clearBonds() override;
+    bool isActive() override;
+    bool isConnected() override;
+    int getRssi() override;
+    void sendLog(const uint8_t *logMessage, size_t length) override;
    void startAdvertising();
-#endif
+    virtual ~NimbleBluetooth() {}
+
    bool isDeInit = false;

  private:
    void setupService();
-#if !defined(NIMBLE_TWO)
-    void startAdvertising();
-#endif
 };

 void setBluetoothEnable(bool enable);
@@ -0,0 +1,42 @@
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_attr.h"
+
+#ifdef ESP32_FORCE_IRAM_MEMSET
+
+/*
+ * T-Beam/classic ESP32 boot workaround
+ * ------------------------------------
+ * During early flash operations the ESP32 disables cache, but some IRAM flash
+ * code paths still reach libc memcpy/memset. If those resolve to flash-resident
+ * implementations, startup can panic with cache-disabled access errors.
+ *
+ * We wrap memcpy/memset for the T-Beam environment. Fast path uses the
+ * normal libc routines when cache is enabled; slow path uses IRAM-safe byte
+ * loops when cache is disabled.
+ */
+
+extern void *__real_memcpy(void *dst, const void *src, size_t n);
+
+static inline bool IRAM_ATTR cache_is_enabled(void)
+{
+    return (*(volatile uint32_t *)0x3FF00040u) & (1u << 3);
+}
+
+extern void *IRAM_ATTR __wrap_memcpy(void *dst, const void *src, size_t n)
+{
+    if (cache_is_enabled()) {
+        return __real_memcpy(dst, src, n);
+    }
+
+    uint8_t *d = (uint8_t *)dst;
+    const uint8_t *s = (const uint8_t *)src;
+    while (n--) {
+        *d++ = *s++;
+    }
+    return dst;
+}
+
+#endif
@@ -0,0 +1,42 @@
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "esp_attr.h"
+
+#ifdef ESP32_FORCE_IRAM_MEMSET
+
+/*
+ * T-Beam/classic ESP32 boot workaround
+ * ------------------------------------
+ * During early flash operations the ESP32 disables cache, but some IRAM flash
+ * code paths still reach libc memcpy/memset. If those resolve to flash-resident
+ * implementations, startup can panic with cache-disabled access errors.
+ *
+ * We wrap memcpy/memset for the T-Beam environment. Fast path uses the
+ * normal libc routines when cache is enabled; slow path uses IRAM-safe byte
+ * loops when cache is disabled.
+ */
+
+extern void *__real_memset(void *dst, int c, size_t n);
+
+static inline bool IRAM_ATTR cache_is_enabled(void)
+{
+    return (*(volatile uint32_t *)0x3FF00040u) & (1u << 3);
+}
+
+extern void *IRAM_ATTR __wrap_memset(void *dst, int c, size_t n)
+{
+    if (cache_is_enabled()) {
+        return __real_memset(dst, c, n);
+    }
+
+    uint8_t *ptr = (uint8_t *)dst;
+    const uint8_t fill = (uint8_t)c;
+    while (n--) {
+        *ptr++ = fill;
+    }
+    return dst;
+}
+
+#endif
@@ -0,0 +1,11 @@
+/* Arduino fix: catch esp_event's orphaned .text.handler_execute section and align to 4 bytes */
+SECTIONS
+{
+  .text.handler_execute ALIGN(4) :
+  {
+    KEEP(*(.text.handler_execute))
+    KEEP(*(.text.handler_execute.*))
+    . = ALIGN(4);
+  }
+}
+INSERT AFTER .flash.text;
@@ -4,9 +4,13 @@
 #include "esp_task_wdt.h"
 #include "main.h"

-#if !defined(CONFIG_IDF_TARGET_ESP32S2) && !MESHTASTIC_EXCLUDE_BLUETOOTH
+#if !MESHTASTIC_EXCLUDE_BLUETOOTH
+#if defined(CONFIG_IDF_TARGET_ESP32P4)
+#include "bluetooth/HostedBluetooth.h"
+#elif !defined(CONFIG_IDF_TARGET_ESP32S2)
 #include "nimble/NimbleBluetooth.h"
 #endif
+#endif

 #include <MeshtasticOTA.h>

@@ -40,16 +44,30 @@ void setBluetoothEnable(bool enable)
    if (config.bluetooth.enabled == true)
 #endif
    {
-        if (!nimbleBluetooth) {
-            nimbleBluetooth = new NimbleBluetooth();
+#if defined(CONFIG_IDF_TARGET_ESP32P4)
+        if (!enable) {
+            if (bluetoothApi && bluetoothApi->isActive()) {
+                bluetoothApi->shutdown();
+                powerMon->clearState(meshtastic_PowerMon_State_BT_On);
+            }
+            return;
        }
-        if (enable && !nimbleBluetooth->isActive()) {
+#endif
+
+        if (!bluetoothApi) {
+#if defined(CONFIG_IDF_TARGET_ESP32P4)
+            bluetoothApi = new HostedBluetooth();
+#else
+            bluetoothApi = new NimbleBluetooth();
+#endif
+        }
+        if (enable && !bluetoothApi->isActive()) {
            powerMon->setState(meshtastic_PowerMon_State_BT_On);
-            nimbleBluetooth->setup();
+            bluetoothApi->setup();
        }
        // For ESP32, no way to recover from bluetooth shutdown without reboot
        // BLE advertising automatically stops when MCU enters light-sleep(?)
-        // For deep-sleep, shutdown hardware with nimbleBluetooth->deinit(). Requires reboot to reverse
+        // For deep-sleep, shutdown hardware with bluetoothApi->deinit(). Requires reboot to reverse
    }
 }
 #else
@@ -165,17 +183,30 @@ void esp32Setup()
 // #define APP_WATCHDOG_SECS 45
 #define APP_WATCHDOG_SECS 90

-#ifdef CONFIG_IDF_TARGET_ESP32C6
-    esp_task_wdt_config_t *wdt_config = (esp_task_wdt_config_t *)malloc(sizeof(esp_task_wdt_config_t));
-    wdt_config->timeout_ms = APP_WATCHDOG_SECS * 1000;
-    wdt_config->trigger_panic = true;
-    res = esp_task_wdt_init(wdt_config);
+#if ESP_ARDUINO_VERSION >= ESP_ARDUINO_VERSION_VAL(3, 0, 0)
+    const esp_task_wdt_config_t wdt_config = {
+        .timeout_ms = APP_WATCHDOG_SECS * 1000,
+        .idle_core_mask = (1U << CONFIG_FREERTOS_NUMBER_OF_CORES) - 1U,
+        .trigger_panic = true,
+    };
+    res = esp_task_wdt_init(&wdt_config);
+    if (res == ESP_ERR_INVALID_STATE) {
+        LOG_WARN("Task watchdog already initialized, reconfiguring existing instance");
+        res = esp_task_wdt_reconfigure(&wdt_config);
+    }
    assert(res == ESP_OK);
 #else
    res = esp_task_wdt_init(APP_WATCHDOG_SECS, true);
+    if (res == ESP_ERR_INVALID_STATE) {
+        LOG_WARN("Task watchdog already initialized, reusing existing instance");
+        res = ESP_OK;
+    }
    assert(res == ESP_OK);
 #endif
-    res = esp_task_wdt_add(NULL);
+    res = esp_task_wdt_status(NULL);
+    if (res == ESP_ERR_NOT_FOUND) {
+        res = esp_task_wdt_add(NULL);
+    }
    assert(res == ESP_OK);

 #if HAS_32768HZ
@@ -258,8 +289,10 @@ void cpuDeepSleep(uint32_t msecToWake)
 #endif
    variant_shutdown();

+#if SOC_PM_SUPPORT_RTC_PERIPH_PD
    // We want RTC peripherals to stay on
    esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
+#endif

    esp_sleep_enable_timer_wakeup(msecToWake * 1000ULL); // call expects usecs
    esp_deep_sleep_start();                              // TBD mA sleep current (battery)
@@ -9,13 +9,11 @@
 #include "PortduinoGlue.h"
 #include "SHA256.h"
 #include "api/ServerAPI.h"
-#include "linux/gpio/LinuxGPIOPin.h"
 #include "meshUtils.h"
 #include <ErriezCRC32.h>
 #include <Utility.h>
 #include <assert.h>
-#include <bluetooth/bluetooth.h>
-#include <bluetooth/hci.h>
+#include <cctype>
 #include <filesystem>
 #include <fstream>
 #include <iostream>
@@ -25,10 +23,26 @@
 #include <sys/ioctl.h>
 #include <unistd.h>

+#ifdef PORTDUINO_LINUX_HARDWARE
+#include "linux/gpio/LinuxGPIOPin.h"
+#include <bluetooth/bluetooth.h>
+#include <bluetooth/hci.h>
+#endif
+
 #ifdef PORTDUINO_LINUX_HARDWARE
 #include <cxxabi.h>
 #endif

+#ifdef __APPLE__
+// Used by getMacAddr()'s macOS fallback to read the en0 link-layer address.
+// `getifaddrs()` is the BSD-portable way; `<net/if_dl.h>` provides the
+// `sockaddr_dl` cast and the `LLADDR()` macro that points at the 6-byte MAC.
+#include <cstring> // strcmp, memcpy
+#include <ifaddrs.h>
+#include <net/if.h>
+#include <net/if_dl.h>
+#endif
+
 #include "platform/portduino/USBHal.h"

 portduino_config_struct portduino_config;
@@ -130,9 +144,9 @@ void getMacAddr(uint8_t *dmac)
        }
    } else if (portduino_config.mac_address.length() > 11) {
        MAC_from_string(portduino_config.mac_address, dmac);
-        exit;
+        return;
    } else {
-
+#ifdef PORTDUINO_LINUX_HARDWARE
        struct hci_dev_info di = {0};
        di.dev_id = 0;
        bdaddr_t bdaddr;
@@ -152,6 +166,37 @@ void getMacAddr(uint8_t *dmac)
        dmac[3] = di.bdaddr.b[2];
        dmac[4] = di.bdaddr.b[1];
        dmac[5] = di.bdaddr.b[0];
+#elif defined(__APPLE__)
+        // No BlueZ on macOS, but we can fall back to the host's primary
+        // network interface MAC. `en0` is Wi-Fi on every shipping Mac
+        // (Ethernet, when present, is en1 or higher), which gives the user
+        // the same kind of stable, host-derived identifier that the BlueZ
+        // path provides on Linux. If en0 isn't found or has no MAC, dmac is
+        // left untouched and the caller's "Blank MAC Address not allowed!"
+        // check will still fire — preserving existing behavior for users
+        // who deliberately rely on --hwid or YAML override.
+        struct ifaddrs *ifap = nullptr;
+        if (getifaddrs(&ifap) == 0) {
+            for (struct ifaddrs *p = ifap; p != nullptr; p = p->ifa_next) {
+                if (p->ifa_addr == nullptr || p->ifa_addr->sa_family != AF_LINK) {
+                    continue;
+                }
+                if (strcmp(p->ifa_name, "en0") != 0) {
+                    continue;
+                }
+                auto *sdl = reinterpret_cast<struct sockaddr_dl *>(p->ifa_addr);
+                if (sdl->sdl_alen == 6) {
+                    memcpy(dmac, LLADDR(sdl), 6);
+                    break;
+                }
+            }
+            freeifaddrs(ifap);
+        }
+#else
+        // No platform-specific MAC source; leave dmac at its default. Caller
+        // can override via the --hwid CLI flag or the YAML config.
+        (void)dmac;
+#endif
    }
 }

@@ -486,10 +531,17 @@ void portduinoSetup()
            exit(EXIT_FAILURE);
        }
        char serial[9] = {0};
-        ch341Hal->getSerialString(serial, 8);
+        // Pass the full buffer size (9 = 8 chars + null) to getSerialString,
+        // not 8. The function treats `len` as buffer size and reserves one
+        // slot for the null terminator, so passing 8 produced a 7-char serial
+        // and broke the `strlen(serial) == 8` check below — masked on Linux
+        // by the BlueZ HCI MAC fallback in getMacAddr(), but on macOS (where
+        // the BlueZ path is __linux__-guarded) it left mac_address empty and
+        // meshtasticd refused to start.
+        ch341Hal->getSerialString(serial, sizeof(serial));
        std::cout << "CH341 Serial " << serial << std::endl;
        char product_string[96] = {0};
-        ch341Hal->getProductString(product_string, 95);
+        ch341Hal->getProductString(product_string, sizeof(product_string));
        std::cout << "CH341 Product " << product_string << std::endl;
        if (strlen(serial) == 8 && portduino_config.mac_address.length() < 12) {
            std::cout << "Deriving MAC address from Serial and Product String" << std::endl;
@@ -1041,17 +1093,31 @@ static bool ends_with(std::string_view str, std::string_view suffix)
 bool MAC_from_string(std::string mac_str, uint8_t *dmac)
 {
    mac_str.erase(std::remove(mac_str.begin(), mac_str.end(), ':'), mac_str.end());
-    if (mac_str.length() == 12) {
-        dmac[0] = std::stoi(portduino_config.mac_address.substr(0, 2), nullptr, 16);
-        dmac[1] = std::stoi(portduino_config.mac_address.substr(2, 2), nullptr, 16);
-        dmac[2] = std::stoi(portduino_config.mac_address.substr(4, 2), nullptr, 16);
-        dmac[3] = std::stoi(portduino_config.mac_address.substr(6, 2), nullptr, 16);
-        dmac[4] = std::stoi(portduino_config.mac_address.substr(8, 2), nullptr, 16);
-        dmac[5] = std::stoi(portduino_config.mac_address.substr(10, 2), nullptr, 16);
-        return true;
-    } else {
+    if (mac_str.length() != 12) {
        return false;
    }
+    // Validate every character is a hex digit before parsing. std::stoi
+    // would otherwise skip leading whitespace and silently truncate at the
+    // first non-digit, which is too lenient for a MAC address.
+    for (char c : mac_str) {
+        if (!isxdigit(static_cast<unsigned char>(c))) {
+            return false;
+        }
+    }
+    // Parse into a temporary so dmac is not partially modified if a later
+    // byte fails. At least one caller in getMacAddr() ignores the bool
+    // return, so leaving stale bytes in dmac on failure would silently
+    // produce a wrong MAC.
+    uint8_t tmp[6];
+    try {
+        for (int i = 0; i < 6; i++) {
+            tmp[i] = static_cast<uint8_t>(std::stoi(mac_str.substr(i * 2, 2), nullptr, 16));
+        }
+    } catch (const std::exception &) {
+        return false;
+    }
+    memcpy(dmac, tmp, 6);
+    return true;
 }

 std::string exec(const char *cmd)
--- a/Show More
+++ b/Show More