meshtastic 0.0.179 → 0.0.181

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fa03c5234c1b6d136fca93a0a37a5c9dd6588b116b6f932f457f4e139eee89c
-  data.tar.gz: 54d66239895c5989f8f8ee5423e63d05769bdecd6281d59d914b31561177fabd
+  metadata.gz: 27355386b939c892e3fb2bc5ab98181fa0a02995663fadd66021153f9fbbf219
+  data.tar.gz: 5de937dd2654b8bbb7b8a5859251a63de35cef66f3fd6304bb714f3e6344d0ed
 SHA512:
-  metadata.gz: fd7705cf063ef5448b167dc7d3f1664dea20cc25ff1b1791a72de2e4a656afc11ef5717969b4171f65736448616e05f985a9a5c40dc11196559b9767a2b5b286
-  data.tar.gz: 506c41dfa105d57a5fae6febd3fa9748f30319c1a280f0ebbc5412d1bfd8b9f9330c337aba25033ee06e9fbc10fa4c600a28cecd61baab145422ec02162df238
+  metadata.gz: 718d1b5cf1fe122909636032011da2ebe28271305f01bf2ea44a50b003780299bdc851a2c68029e599982d270439c7062b2b8504494671bfc9775413457caca5
+  data.tar.gz: 5b8435e2d71adcb7a3634b758ca8678a89774b8ba62f3e3868cb2ffca265f7b4369421e417689a551f97443c80b73fe70d0c8044fb53b842ab45374964a821f4

data/Gemfile

@@ -6,13 +6,13 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'bundler', '>=4.0.20'
+gem 'bundler', '>=4.0.21'
 gem 'bundler-audit', '>=0.9.3'
 gem 'executable-hooks', '1.7.1'
 gem 'gem-wrappers', '1.4.0'
 gem 'geocoder', '1.8.6'
 gem 'google-protobuf', '4.36.1'
-gem 'grpc-tools', '1.83.1'
+gem 'grpc-tools', '1.84.0'
 gem 'mqtt', '0.7.0'
 gem 'rake', '13.4.2'
 gem 'rdoc', '7.0.4'

data/documentation/README.md

@@ -28,8 +28,9 @@ Do not open Serial and Bluetooth to the same radio at once. Always `disconnect`
 ## Feature modules
 
 - [Meshtastic::Admin](admin.md)
-- [Meshtastic::Channel](channel.md)
-- [Meshtastic::Config](config.md)
+- [Meshtastic::Admin::Channel](admin-channel.md)
+- [Meshtastic::Admin::Config](admin-config.md)
+- [Meshtastic::Admin::Firmware](admin-firmware.md)
 - [Meshtastic::ModuleConfig](module-config.md)
 - [Meshtastic::Position](position.md)
 - [Meshtastic::Telemetry](telemetry.md)

data/documentation/admin-channel.md

@@ -0,0 +1,64 @@
+# Meshtastic::Admin::Channel
+
+Build, read, write, and share mesh channels using `ADMIN_APP`. The generated protobuf remains `Meshtastic::Channel`. All public methods accept one options Hash.
+
+## Channel operations
+
+- `build_settings(settings:, ...)` copies an optional `ChannelSettings` protobuf or field Hash and overlays explicit settings without mutating the input. Supports **every bundled field**: `channel_num`, raw-byte `psk`, `name`, `id`, `uplink_enabled`, `downlink_enabled`, `module_settings`, `use_aead`. Nested `module_settings` accepts a `Meshtastic::ModuleSettings` or Hash, including `position_precision` and `is_muted`. Explicit `false` clears booleans.
+- `build(channel:, index:, role:, settings:, ...)` copies an optional Channel protobuf, preserving its settings and overlaying supplied values. Defaults to slot zero and protobuf role `:DISABLED`; choose `:PRIMARY` or `:SECONDARY` explicitly when enabling a channel.
+- `get(index:)` requests a **zero-based** slot (default 0). `Admin.get_channel` converts to the protocol's **one-based request**: slot 0 sends `get_channel_request = 1`. Response and set-channel indexes remain zero-based. Never add one yourself.
+- `set(channel:, index:, role:, settings:, ...)` builds/validates a Channel and sends it through Admin. A supplied Channel can be overlaid with explicit settings. Slots must be Integers from 0 through 7; numeric strings and fractional indexes are rejected. Unsupported roles, invalid PSK lengths, and overlong names are rejected before sending.
+- `help` / `authors` show usage and attribution.
+
+Channel names must occupy fewer than 12 UTF-8 bytes. PSKs accept 0, 1, 16, or 32 raw bytes; they are **not** hex/base64 strings. Empty keys disable encryption; one-byte keys are public shorthand keys, not secure random keys. `channel_num` is deprecated in ChannelSettings: configure frequency selection with `Admin::Config.set_lora` instead. AEAD is experimental and peers must agree on its use.
+
+```ruby
+settings = Meshtastic::Admin::Channel.build_settings(
+  name: 'Example', psk: "\x01".b,
+  uplink_enabled: false,
+  module_settings: { position_precision: 13, is_muted: false }
+)
+Meshtastic::Admin::Channel.set(
+  serial_obj: serial_obj, index: 1, role: :SECONDARY, settings: settings
+)
+Meshtastic::Admin::Channel.get(serial_obj: serial_obj, index: 1)
+
+# Explicitly disable a slot.
+Meshtastic::Admin::Channel.set(serial_obj: serial_obj, index: 1, role: :DISABLED)
+```
+
+Admin transport/routing/authentication options pass through (`serial_obj`, `bluetooth_obj`, `tcp_obj`, `mqtt_obj`, `to`, `from`, `session_passkey`, etc.). Here `channel:` means a **Channel protobuf**, not the outgoing mesh transport channel selector; it is removed before delivery. Use the lower-level `Admin.set_channel(channel_settings: protobuf, channel: numeric_index, ...)` when a particular transport channel is necessary.
+
+## Channel URLs
+
+Official clients share a protobuf `Meshtastic::ChannelSet` using unpadded URL-safe Base64 in the fragment of `https://meshtastic.org/e/#...` (legacy `/d/#...` imports are also accepted).
+
+- `export_url(channels:, lora_config:, include_all:)` is offline. Requires exactly one primary, puts it first, sorts secondary channels by slot, and omits disabled slots. `include_all: false` exports only the primary; default includes secondaries. An optional LoRaConfig protobuf/Hash is included without fetching hardware. Up to eight enabled channels are accepted.
+- `import_url(url:)` is offline and returns the decoded ChannelSet, preserving settings and optional LoRaConfig. Accepts padded or unpadded Base64 from HTTPS `meshtastic.org` e/d URLs only, with no userinfo or alternate port. Malformed protobuf/Base64, missing fragments, and zero or more than eight settings are rejected with a generic error that does not echo the secret URL. It does not assign device slots or modify a radio.
+- `apply_url(url:, transport_options...)` explicitly writes imported settings into consecutive slots starting at zero: first PRIMARY, remaining SECONDARY. All channel settings are validated before the first write. Optional LoRa config is written last; absent LoRa config is left unchanged. Returns the individual transport submission results. **Existing higher slots are left untouched**, matching the official Python client's replacement behavior. Add-only/query links are rejected before transmission; for adding channels, import offline, inspect existing slots, and call `set` with explicitly chosen secondary slots.
+
+```ruby
+# channels and lora_config are protobufs already obtained from the node.
+url = Meshtastic::Admin::Channel.export_url(
+  channels: channels, lora_config: lora_config
+)
+channel_set = Meshtastic::Admin::Channel.import_url(url: url)
+
+# Only when replacement of slots from zero is intended:
+Meshtastic::Admin::Channel.apply_url(serial_obj: serial_obj, url: url)
+```
+
+**URLs contain channel keys.** Treat them as credentials: do not log, publish, or send them to third-party QR services. Export does not redact PSKs. A URL carries settings, not original slot indexes/roles: its first entry becomes primary when applied.
+
+## Operational limits
+
+Writes are submissions, not delivery/persistence acknowledgements. No live hardware was exercised. No automatic reply collection, session-key acquisition, readback, edit transaction, rollback, or add-only merge is performed. URL application can partially succeed if transport or firmware fails mid-sequence, and changing LoRa/primary settings can disconnect remote administration. For radio use, manage edit transactions and ACK/readback through Admin as appropriate for the firmware; verify slots and LoRa configuration after writing.
+
+## Protocol evidence
+
+- [Official Admin schema](https://github.com/meshtastic/protobufs/blob/master/meshtastic/admin.proto): `get_channel_request` is index + 1.
+- [Official Channel schema](https://github.com/meshtastic/protobufs/blob/master/meshtastic/channel.proto): roles, settings, PSK/name constraints, deprecated channel_num.
+- [Official app-only schema](https://github.com/meshtastic/protobufs/blob/master/meshtastic/apponly.proto): ChannelSet contains primary-first settings, secondaries, and optional LoRa config.
+- [Official Python node client](https://github.com/meshtastic/python/blob/master/meshtastic/node.py): `_requestChannel`, `getURL`, and `setURL` establish index and sharing/application semantics. Python is reference evidence only; this implementation is Ruby.
+
+Related: [Admin](admin.md), [Config](admin-config.md).

data/documentation/admin-config.md

@@ -0,0 +1,59 @@
+# Meshtastic::Admin::Config
+
+Admin requests and writes for every section in the bundled `Meshtastic::Config` protobuf. Public methods take a single options Hash; `help` describes the options. The generated protobuf remains `Meshtastic::Config`.
+
+## Operations
+
+| Section | Read | Write | Value type |
+| --- | --- | --- | --- |
+| Device | `get_device` | `set_device(device:)` | `Config::DeviceConfig` or field Hash |
+| Position | `get_position` | `set_position(position:)` | `Config::PositionConfig` or field Hash |
+| Power | `get_power` | `set_power(power:)` | `Config::PowerConfig` or field Hash |
+| Network | `get_network` | `set_network(network:)` | `Config::NetworkConfig` or field Hash |
+| Display | `get_display` | `set_display(display:)` | `Config::DisplayConfig` or field Hash |
+| LoRa | `get_lora` | `set_lora(lora:)` | `Config::LoRaConfig` or field Hash |
+| Bluetooth | `get_bluetooth` | `set_bluetooth(bluetooth:)` | `Config::BluetoothConfig` or field Hash |
+| Security | `get_security` | `set_security(security:)` | `Config::SecurityConfig` or field Hash |
+| Session key | `get_sessionkey` | Request-only; writes raise `ArgumentError` | Empty `Config::SessionkeyConfig` placeholder |
+| Device UI | `get_device_ui` | `set_device_ui(device_ui:)` | `Meshtastic::DeviceUIConfig` or field Hash |
+
+- `get(config_type:)` is the raw ConfigType request (default `:DEVICE_CONFIG`). Supported types are `:DEVICE_CONFIG`, `:POSITION_CONFIG`, `:POWER_CONFIG`, `:NETWORK_CONFIG`, `:DISPLAY_CONFIG`, `:LORA_CONFIG`, `:BLUETOOTH_CONFIG`, `:SECURITY_CONFIG`, `:SESSIONKEY_CONFIG`, and `:DEVICEUI_CONFIG`.
+- `set(config:)` accepts a `Meshtastic::Config` with exactly one selected section; an absent/empty config is rejected before transmission. All fields of the section, including nested/repeated fields, are supported by the generated protobuf, not a hand-picked subset.
+- Device UI uses **`get_ui_config_request` / `store_ui_config`**, not the firmware's no-op Config device-UI handling. Generic `set` also routes a `device_ui` section correctly. The raw `get(config_type: :DEVICEUI_CONFIG)` remains a raw enum request; use `get_device_ui` for useful UI data.
+- `SessionkeyConfig` is empty and request-only. The authorization bytes come from **`AdminMessage.session_passkey`**, not the Config payload. Both `set_sessionkey` and generic `set` reject this non-writable section.
+- `help` / `authors` provide usage and attribution.
+
+ModuleConfig is a different protobuf: use `Admin.get_module_config` / `Admin.set_module_config` for MQTT, telemetry, and other module configuration.
+
+## Transport and authorization
+
+Read/write helpers pass through Admin options, including `serial_obj`, `bluetooth_obj`, `tcp_obj`, `mqtt_obj`, `to`, `from`, numeric transport `channel`, `want_ack`, `want_response`, `hop_limit`, and `session_passkey`. Use a supported connected transport. Session authentication and remote-node routing follow [Admin](admin.md).
+
+A return value means transport submission, **not confirmed persistence**. These methods do not wait for a reply, automatically acquire a session key, or read settings back. Obtain the prior configuration, edit it, write, and request it again to confirm; configuration writes replace a whole section rather than patching only non-default fields. Omitting a field in a Hash can reset that setting to its protobuf default. Firmware version and hardware determine which fields are applied, and writes may reboot/disconnect the node.
+
+## Example
+
+```ruby
+Meshtastic::Admin::Config.get_lora(serial_obj: serial_obj)
+
+# Supply the full desired section; prefer editing the returned protobuf.
+Meshtastic::Admin::Config.set_position(
+  serial_obj: serial_obj,
+  position: Meshtastic::Config::PositionConfig.new(position_broadcast_secs: 900)
+)
+
+Meshtastic::Admin::Config.set_device_ui(
+  serial_obj: serial_obj,
+  device_ui: Meshtastic::DeviceUIConfig.new
+)
+```
+
+Ruby protobuf's `display` reader collides with `Object#display`; inspect `config['display']`, not `config.display`. Do not log configuration objects: network/security settings and session passkeys can contain secrets.
+
+## Protocol evidence
+
+- [Official Config schema](https://github.com/meshtastic/protobufs/blob/master/meshtastic/config.proto): all ten variants and request-only SessionkeyConfig.
+- [Official Admin schema](https://github.com/meshtastic/protobufs/blob/master/meshtastic/admin.proto): ConfigType and dedicated UI operations.
+- [Official firmware AdminModule](https://github.com/meshtastic/firmware/blob/master/src/modules/AdminModule.cpp): `handleSetConfig` / config request handling mark device-UI Config operations as no-ops and point to the dedicated handlers.
+
+Related: [Admin](admin.md), [Channel](admin-channel.md).

data/documentation/admin-firmware-nordic.md

@@ -0,0 +1,86 @@
+# Nordic/Adafruit BLE DFU
+
+## Supported path
+
+`Meshtastic::Admin::Firmware::NordicDFU` installs **application-only, unsigned legacy Adafruit CRC16 DFU ZIP packages** over the SDK11 BLE bootloader protocol. It does not invoke Python, nrfutil, unzip, or any other external program. Use the correct board's `firmware-…-ota.zip`, not a UF2, HEX, raw binary, release bundle, or bootloader/SoftDevice upgrade ZIP.
+
+This is a genuinely supported Nordic path, **not Nordic Secure DFU**. Meshtastic's application-side `BLEDfuSecure` advertises FE59 as a buttonless reboot service; that name does not establish that the bootloader implements Secure DFU's protobuf init packets and object/CRC32 transfer protocol. The Adafruit SDK11 bootloader uses legacy service 1530 and its own control-point commands.
+
+Unsupported packages fail before any GATT writes: SoftDevice/bootloader or multi-image updates, Nordic Secure DFU init packets, Adafruit extended hash/signed init packets, encrypted/split/ZIP64 archives, data-descriptor ZIPs, missing or malformed manifest entries, inconsistent directory/local headers, duplicate or unsafe names, oversized entries, CRC32 failures, non-word-aligned binaries, and image CRC16 mismatches. Stored and raw-DEFLATE ZIP entries are supported, bounded in memory; nothing is extracted to disk.
+
+Adafruit's optional `SIGNED_FW` build is a **different legacy init extension**, not Secure DFU: extension identifier 2, image length, SHA-256 and raw P-256 signature R/S. Its bootloader verifies a compiled-in public key. This installer rejects that extension rather than discarding signatures or silently downgrading security. Ordinary CRC16 packages provide corruption detection, **not authenticity**. Obtain the board-specific ZIP from a trusted release source. Device type 0x0052 does not uniquely identify a board; the bootloader checks the package's SoftDevice requirements but host-side board compatibility cannot be inferred from this format.
+
+## Integration API
+
+```ruby
+require 'meshtastic'
+require 'meshtastic/admin/firmware/nordic_dfu'
+
+result = Meshtastic::Admin::Firmware::NordicDFU.install(
+  protocol: :nordic_dfu,
+  package: '/path/to/firmware-board-version-ota.zip',
+  address: 'AA:BB:CC:DD:EE:FF',
+  adapter: 'hci0',
+  timeout: 30
+)
+```
+
+The public signature is `install(opts = {})`. Exactly one source is required:
+
+- `package:` — DFU ZIP filename.
+- `package_bytes:` — raw ZIP String instead of a filename.
+
+Other accepted keys: `protocol:` (optional, must be `:nordic_dfu`), `gatt:` (already-connected adapter), `address:` (required without injection), `adapter:` (default `hci0`), `timeout:` (positive finite per-notification timeout, default 30 seconds). Unknown options are rejected. In particular, no `retries:`, Secure DFU mode, or generic `bytes:`/`firmware:` aliases are silently accepted. The orchestrator should pass the ZIP source using the explicit package keys.
+
+Production construction uses the shared BLE module:
+
+```ruby
+Meshtastic::Admin::Firmware::BLE::BlueZ.new(
+  address: address, adapter: adapter, timeout: timeout,
+  service_uuid: '00001530-1212-efde-1523-785feabcd123'
+).connect
+```
+
+The BLE backend is shared with the unified installer; this module does not implement another BlueZ backend. BlueZ must already know the explicitly selected bootloader address. Discovery, pairing, application-to-bootloader reboot, and post-reboot reconnect belong to the caller/orchestrator.
+
+### Exact injected GATT interface
+
+All methods use Ruby keywords:
+
+- `subscribe(uuid:)` enables and queues notifications before the first write.
+- `write(uuid:, bytes:, response:)` writes a binary String. Control point uses `response: true`; packet characteristic uses `false`.
+- `notification(timeout:)` returns `{ uuid: String, bytes: String }`, or nil on timeout; transport exceptions propagate. The implementation must enforce the supplied timeout.
+- `close` releases the connection. The installer closes after an attempted session, including injected adapters. Package validation failures do not acquire or close an injected adapter.
+
+Control UUID: `00001531-1212-efde-1523-785feabcd123`.
+Packet UUID: `00001532-1212-efde-1523-785feabcd123`.
+The backend resolves these only within the selected device/service and fails if absent; no fallback to unrelated characteristics or Secure DFU.
+
+## Wire sequence and verification
+
+1. Subscribe to control-point notifications.
+2. Write Start DFU `[01 04]` (application), then three little-endian uint32 sizes `[0, 0, image_size]` to the packet characteristic. Require `[10 01 01]` success.
+3. Write Init Start `[02 00]`, stream the **unchanged** `.dat` in at-most-20-byte packets, then Init Complete `[02 01]`. Require `[10 02 01]` success. Legacy init is little-endian device type uint16, revision uint16, application version uint32, SoftDevice count uint16, count uint16 IDs, then CRC16.
+4. Enable packet receipt notifications with `[08 01 00]` (PRN=1); this command has no protocol response. Write Receive Firmware `[03]`.
+5. Stream binary in at-most-20-byte, word-aligned packets. After each non-final packet require `[11 <received uint32 little-endian>]` with the **exact cumulative byte offset**. SDK11 sends no PRN on the final packet: instead require Receive Firmware success `[10 03 01]`, emitted after its final flash operation completes.
+6. Write Validate `[04]`; require `[10 04 01]`, which confirms device-side image CRC16 validation. Only then write Activate and Reset `[05]`. This command has no DFU response; a failed ATT write is not suppressed as presumed reboot success.
+
+The result contains `status: :verified`, `protocol: :nordic_dfu`, image `bytes:`, image `sha256:`, and `reboot_verified: false`. Verified means **bootloader validation acknowledged**, not a confirmed successful reboot or healthy Meshtastic application. The SHA-256 is computed locally for identification, not reported by the bootloader. The caller must reconnect and verify application identity/version separately.
+
+### Retry policy
+
+No automatic wire retries or resume. Legacy packets have no sequence number; retransmitting after an ambiguous write, missing PRN, timeout, wrong opcode, rejection, or disconnect could duplicate bytes or corrupt state. The installer closes and raises; it never sends Activate after a failed validation. The operator may explicitly restart from a newly entered bootloader session after resolving the failure. GATT/ATT link-layer retransmissions remain the Bluetooth stack's responsibility.
+
+## Evidence and testing
+
+The matching spec uses an independently implemented stateful DFU peer which parses every write, checks command order and sizes, accumulates `.dat`/image packets, generates PRNs from received byte counts, and calculates image CRC16 with a separate bitwise algorithm. It includes corruption/rejection/timeout/offset faults and validates ZIP parsing, supported compression, unsafe packages and production-backend construction. No hardware was opened; emulation does not prove device flash behavior or post-reboot health.
+
+Upstream source references inspected:
+
+- [Adafruit SDK11 BLE DFU service](https://github.com/adafruit/Adafruit_nRF52_Bootloader/blob/master/lib/sdk11/components/ble/ble_services/ble_dfu/ble_dfu.c): legacy opcodes and characteristic behavior.
+- [Adafruit SDK11 BLE transport](https://github.com/adafruit/Adafruit_nRF52_Bootloader/blob/master/lib/sdk11/components/libraries/bootloader_dfu/dfu_transport_ble.c): `on_dfu_evt`, `app_data_process`, PRNs only on non-final packets, final receive response after flash completion, init/validate/reset handling.
+- [Adafruit init validation](https://github.com/adafruit/Adafruit_nRF52_Bootloader/blob/master/src/dfu_init.c): device type, SoftDevice matching, CRC16 versus optional `SIGNED_FW` P-256 extension.
+- [Adafruit package generation](https://github.com/adafruit/Adafruit_nRF52_nrfutil/blob/master/nordicsemi/dfu/package.py) and [init encoding](https://github.com/adafruit/Adafruit_nRF52_nrfutil/blob/master/nordicsemi/dfu/init_packet.py): manifest, `.bin`/`.dat`, default legacy v0.5 CRC16 and distinct v0.6/v0.7/v0.8 extensions.
+- [Meshtastic buttonless DFU](https://github.com/meshtastic/firmware/blob/develop/src/platform/nrf52/BLEDfuSecure.cpp): FE59 application service initiates bootloader transition, not the image-transfer implementation.
+- [Meshtastic NRF52 release script](https://github.com/meshtastic/firmware/blob/develop/bin/build-nrf52.sh): release OTA ZIP naming.
+- [Meshtastic OTAFIX bootloader fork](https://github.com/meshtastic/Adafruit_nRF52_Bootloader_OTAFIX): device-specific bootloader deployments can differ; legacy-only support must not be generalized to every NRF52 bootloader.

data/documentation/admin-firmware-serial.md

@@ -0,0 +1,180 @@
+# Native serial ROM firmware installation
+
+`Meshtastic::Admin::Firmware::SerialBootloader` implements Espressif's UART ROM
+protocol in Ruby using the existing `uart`/`termios` dependencies. It does not
+execute esptool, Python, nrfutil, or an uploaded flasher stub.
+
+## Supported targets and boundaries
+
+| `chip:` | Hardware identification | Write format |
+| --- | --- | --- |
+| `:esp32` | ROM magic register `0x40001000 == 0x00f01d83`; security eFuse reads | 16-byte FLASH_BEGIN |
+| `:esp32s3` | GET_SECURITY_INFO chip ID 9 and security flags | 20-byte FLASH_BEGIN, encryption disabled |
+| `:esp32c3` | GET_SECURITY_INFO chip ID 5 and security flags | 20-byte FLASH_BEGIN, encryption disabled |
+
+Support is for **UART ROM download mode**, normally through an external USB/UART
+bridge. Automatic reset requires the conventional DTR-to-BOOT and RTS-to-EN
+circuit. Native USB-Serial-JTAG/USB-OTG reset and re-enumeration are not implemented.
+Other chips, including ESP8266, ESP32-S2, C2, C6, H2 and Nordic nRF52, are rejected.
+No device was physically flashed during development: verification uses an
+independent ROM emulator over a PTY and the real UART opener.
+
+Only a **single, unmerged ESP application `.bin`** is accepted. This is not a
+factory/recovery installer: it does not install a bootloader, partition table,
+filesystem, OTA selection metadata, UF2 image, ZIP package, signed image or merged
+release image. The existing bootloader and partition table must already be valid.
+Trailing padding, signatures and merged images are deliberately rejected.
+
+## Direct API
+
+```ruby
+require 'meshtastic'
+require 'meshtastic/admin/firmware/serial_bootloader'
+
+result = Meshtastic::Admin::Firmware::SerialBootloader.install(
+  protocol: :esp_rom,
+  port: '/dev/ttyUSB0',
+  chip: :esp32s3,
+  firmware: '/path/to/board-matched-application.bin',
+  offset: 0x10000,           # example only: consult this board's partition table
+  flash_size: 4 * 1024 * 1024, # actual physical capacity, not image length
+  reset: :classic,
+  timeout: 120
+)
+```
+
+Supply exactly one of `firmware:` (path) or `bytes:` (binary String). `protocol:`
+is optional on the direct backend and defaults to `:esp_rom`. Unknown options
+raise `ArgumentError` before opening the serial device.
+
+- `port:` is a required dedicated serial device path, **not** `serial_obj:` from
+  an active Meshtastic PhoneAPI connection. Close that connection and stop its
+  reader before installing. Never flash while another process uses this port.
+- `chip:` is required and must match both the image header and the connected ROM.
+- `offset:` is required, at least `0x10000`, and aligned to a 4096-byte flash sector.
+  This check prevents writes into low-address bootloader/partition metadata; it
+  does **not** discover which application partition the board actually boots.
+- `flash_size:` is required, a power of two between 1 and 16 MiB. It is declared
+  by the caller; this backend does not probe JEDEC flash capacity. The complete
+  sector-rounded erase range must fit within it.
+- `reset: :classic` (default) drives DTR/RTS to enter ROM, then pulses EN after
+  verified completion. If the bridge does not support modem-control ioctls, the
+  operation fails rather than assuming a reset occurred.
+- `reset: :none` means the operator has already entered ROM download mode. It
+  suppresses modem-line changes, not the final FLASH_END reboot request. Opening
+  a UART can still affect modem lines on some operating systems/bridges.
+- `timeout:` is a finite positive per-command deadline, default 120 seconds.
+  SYNC has at most three attempts, each capped at one second. The whole transfer
+  can take longer than `timeout:`. Data, erase and reboot commands are not replayed
+  after a timeout or rejection.
+
+**Before flashing:** verify the board model, hardware revision requirements,
+partition address and partition capacity independently. The ESP image chip ID is
+not a board model identifier. This backend does not validate minimum silicon
+revision against eFuses, discover partitions, select an inactive OTA slot, or
+change OTA selection metadata. It cannot guarantee that the next boot selects
+this image. Back up configuration before installing. Sector erase destroys the
+rest of the final sector, even where the image itself ends earlier. Do not use an
+offset/range belonging to NVS, a filesystem, another application or OTA metadata.
+
+## Protocol and verification
+
+Before opening the port, validation checks image magic, segment count and bounds,
+segment word alignment, embedded chip ID, segment XOR checksum, the appended
+SHA-256 digest when present, and exact end-of-image. These are corruption checks,
+not firmware authenticity or signature verification.
+
+The backend then:
+
+1. Opens UART at 115200, 8N1, disables inherited RTS/CTS flow control and HUPCL,
+   and performs the requested reset.
+2. Sends escaped SLIP SYNC and accepts a nonzero ROM response value. A zero value
+   is rejected as a running flasher stub. Extra ROM SYNC responses are drained
+   while waiting for the next matching command response.
+3. Identifies the chip and rejects secure boot, secure download, or any programmed
+   flash-encryption count. Conservatively rejecting even previously used encryption
+   counters avoids silently treating a security-configured device as plain flash.
+4. Sends SPI_ATTACH with default pins and SPI_SET_PARAMS for declared NOR capacity.
+   Custom SPI pin mappings and NAND are unsupported.
+5. Erases the selected range via FLASH_BEGIN, then sends 1024-byte FLASH_DATA
+   blocks with sequence numbers, `0xff` final-block padding and XOR checksum
+   seeded with `0xef`. Every command requires a matching response and successful
+   ROM status. Invalid framing, opcode, length, timeout or error status aborts.
+6. Requests SPI_FLASH_MD5 over the **original unpadded image length** and compares
+   the ROM's 32 ASCII hexadecimal characters with Ruby's MD5 of the exact source.
+   A mismatch prevents FLASH_END and explicit hard reset.
+7. Sends FLASH_END with reboot requested, requires its acknowledgment, and performs
+   the final EN pulse for `:classic`. The UART closes on success or failure.
+
+On success the return hash contains:
+
+```ruby
+{
+  status: :verified,
+  chip: :esp32s3,
+  bytes: image_byte_count,
+  offset: application_offset,
+  md5: rom_verified_hex_md5,
+  sha256: source_hex_sha256,
+  reboot_requested: true,
+  boot_verified: false
+}
+```
+
+`:verified` means **the ROM-reported flash digest matched**. It is not a
+post-reboot health check or a guarantee the booted application is this image.
+Automatic Admin session/readback and post-reboot verification belong in the
+higher-level Firmware orchestrator, after this backend has closed its UART.
+The backend does not return an invented firmware version or treat port reopening
+as proof of application health. On failure it raises `ArgumentError`, `IOError`,
+`EOFError`, `Timeout::Error`, or the underlying filesystem/serial exception. A
+failed transfer may have already erased or partially written the application;
+no rollback is implemented.
+
+## Unsupported commands and Nordic DFU
+
+Implemented ROM commands are SYNC (`0x08`), READ_REG (`0x0a`, ESP32 only),
+GET_SECURITY_INFO (`0x14`, S3/C3), SPI_ATTACH (`0x0d`), SPI_SET_PARAMS (`0x0b`),
+FLASH_BEGIN/DATA/END (`0x02`/`0x03`/`0x04`) and SPI_FLASH_MD5 (`0x13`).
+
+There is no compressed flashing, RAM/stub upload, arbitrary register writing,
+baud-rate change, encrypted write, secure-download controller, raw flash readback,
+full-chip erase, or stub-only `0xd0`/`0xd1`/`0xd2` erase/read protocol. ROM MD5 is
+not interchangeable with the stub's 16-byte binary digest response.
+
+Adafruit's nRF52 serial/CDC DFU is a **different protocol**: its upstream uploader
+uses reliable HCI/SLIP framing with sequence acknowledgments, CRC16 and Nordic
+START/INIT/DATA/STOP records. It is not ESP SLIP command framing, PhoneAPI framing,
+a UF2 copy, or Nordic Secure DFU's object protocol. This backend explicitly does
+not implement it or invoke its Python uploader. A correct future backend needs
+package/init-packet validation, exact bootloader capability matching, acknowledged
+HCI sequencing and honest device validation/activation evidence; transport ACKs
+alone must not be reported as a verified installation.
+
+## Sources and tests
+
+Protocol choices were checked against the official source, not inferred from a
+successful port open:
+
+- [Espressif serial protocol reference](https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/serial-protocol.html)
+- [Espressif command implementation](https://github.com/espressif/esptool/blob/master/esptool/loader.py)
+- [ESP32 target/eFuses](https://github.com/espressif/esptool/blob/master/esptool/targets/esp32.py),
+  [ESP32-S3](https://github.com/espressif/esptool/blob/master/esptool/targets/esp32s3.py),
+  [ESP32-C3](https://github.com/espressif/esptool/blob/master/esptool/targets/esp32c3.py)
+- [Espressif image format parser](https://github.com/espressif/esptool/blob/master/esptool/bin_image.py)
+- [Classic reset sequence](https://github.com/espressif/esptool/blob/v4.8.1/esptool/reset.py)
+- [Adafruit nRF52 bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader)
+- [Adafruit serial DFU transport](https://github.com/adafruit/Adafruit_nRF52_nrfutil/blob/master/nordicsemi/dfu/dfu_transport_serial.py)
+
+Run the hardware-free tests:
+
+```sh
+bundle exec rspec spec/lib/meshtastic/admin/firmware/serial_bootloader_spec.rb
+```
+
+The emulator independently checks wire framing, little-endian command fields,
+sequence numbers, block padding/checksums, chip-specific FLASH_BEGIN layout and
+verification range. Tests cover all three chips, file input, optional image
+digests, classic reset controls, security/chip mismatches, malformed/error replies,
+MD5 mismatch, timeouts, synchronization retry, resource teardown and rejection
+before opening a device. Actual board behavior remains hardware-unverified.

data/documentation/admin-firmware.md

@@ -0,0 +1,126 @@
+# Meshtastic::Admin::Firmware
+
+**PhoneAPI XModem is not a firmware flashing protocol.** The old implementation incorrectly sent padded XModem data after an OTA admin request and could report completion without any device acknowledgement. That path is now rejected, including MQTT's former silent request-only `install`.
+
+## Supported operations
+
+| Operation | What the Ruby implementation actually does |
+| --- | --- |
+| `sha256(firmware: ... \| bytes: ...)` | Returns a raw 32-byte SHA-256 digest. Exactly one nonempty image source is required. |
+| `request_ota(...)` | Sends the real ESP32 `OTAEvent` admin request: raw SHA-256 plus `:OTA_BLE` (default) or `:OTA_WIFI`. This pins the image hash and requests a reboot into an **already installed compatible loader**; it does not upload firmware or prove that the loader started. |
+| `install(protocol: :unified_wifi, host: ..., firmware: ... \| bytes: ...)` | Separate ESP32 unified-loader TCP protocol, normally port 3232. Requires the image hash to have been provisioned using `request_ota`. |
+| `install(protocol: :unified_ble, address: ..., firmware: ... \| bytes: ...)` | ESP32 unified-loader custom GATT protocol, with a native Ruby BlueZ backend and application ACK flow control. Not the old BLE-only firmware-ota protocol. |
+| `install(protocol: :nordic_dfu, address: ..., package: ...)` | Adafruit SDK11 legacy Nordic BLE DFU for application-only legacy ZIP packages. [Exact scope and options](admin-firmware-nordic.md). Not Nordic Secure DFU or UF2. |
+| `install(protocol: :esp_rom, ...)` | Native ESP ROM serial flashing with explicit chip, flash geometry and offset, ROM acknowledgements and flash MD5 verification. [Exact scope and options](admin-firmware-serial.md). |
+| `verify_reboot(...)` or `install(..., verify: {...})` | Fresh application connection, matching configuration handshake and a new request-ID/source-correlated Admin device-metadata reply. Checks exact firmware version and optional node identity. |
+| `enter_dfu(...)` | Sends `enter_dfu_mode_request`; current upstream handles entry on nRF52/RP2040. It neither transfers a DFU package nor copies a UF2 image. |
+| `reboot_ota`, `xmodem_blocks`, `send_xmodem` | Raise `NotImplementedError`. The legacy reboot field has no handler in the inspected firmware; XModem is filesystem transfer, not firmware installation. |
+| `help`, `authors` | Usage and attribution. |
+
+Admin commands accept the transport, addressing, and authentication options documented in [Admin](admin.md). Use exactly one transport. Successful submission is **not confirmation that hardware supports or performed the operation**. A routing acknowledgement alone cannot prove an ESP32 OTA loader/partition exists. No automatic board detection is performed.
+
+## ESP32 unified WiFi example
+
+Only use a matching application update `.bin`, not a merged full-flash image, UF2, ZIP, or bootloader. Confirm board, flash layout, power, WiFi configuration, and loader compatibility yourself. Wrong images or interrupted writes may leave the device unbootable; keep a recovery method available.
+
+```ruby
+image = File.binread('firmware-matching-board-update.bin')
+
+# Phase 1: use an existing authenticated Admin connection to pin this image.
+Meshtastic::Admin::Firmware.request_ota(
+  serial_obj: serial_obj,
+  bytes: image,
+  mode: :OTA_WIFI
+)
+
+# Phase 2: connect to the separate loader after it reboots and joins WiFi.
+# Not the Meshtastic TCP PhoneAPI port 4403, nor an existing tcp_obj.
+result = Meshtastic::Admin::Firmware.install(
+  protocol: :unified_wifi,
+  host: '192.0.2.10',
+  bytes: image,
+  port: 3232,
+  timeout: 120,
+  retries: 3,
+  retry_delay: 1
+)
+# { status: :verified, bytes: ..., sha256: '64 hexadecimal characters',
+#   loader_version: 'hardware firmware reboot_count loader_version' }
+```
+
+`request_ota(ota_hash: ...)` also accepts an explicitly supplied **raw** 32-byte digest (not hex). When an image is supplied alongside the digest they must match. It rejects unknown modes. The loader itself checks that the upload hash equals its provisioned NVS hash and verifies the downloaded bytes.
+
+`install` intentionally rejects `serial_obj`, `tcp_obj`, `bluetooth_obj`, `mqtt_obj`, `mode`, mesh destinations, and other unknown options. These are not the unified WiFi transport. `host` must address the actual prepared loader. Protocol selection is explicit: no guessing or fallback to a different flasher.
+
+### Wire behavior and failure handling
+
+1. Connect with a bounded timeout; retry **only** connection refusal/timeouts, up to `retries` additional attempts (0..20). The default is three additional attempts with a one-second delay. Each connect has its own timeout.
+2. Send `VERSION\n`; require `OK <hw> <fw> <count> <loader-version>\n` before sending an OTA command.
+3. Send `OTA <exact-byte-count> <sha256-hex>\n`; accept `ERASING\n` followed by `OK\n`, or immediate `OK\n`. No image bytes are sent until this handshake succeeds.
+4. Send the exact binary without XModem, padding, or EOT. Drain optional TCP `ACK\n` responses concurrently to avoid socket backpressure deadlocks. TCP handles retransmission; no firmware bytes are replayed at application level.
+5. Require the final `OK\n`. `ACK`, successful socket writes, disconnects, and admin submission do not count as completion. `ERR ...`, malformed/oversized lines, premature EOF, and timeout raise errors; the connection and upload worker are cleaned up.
+
+`timeout` also bounds the **whole VERSION/erase/upload/final-verification exchange**, not each received line. Increase it for slow devices/large images. A lost connection after starting OTA is not retried automatically: completion can be ambiguous and replaying raw bytes can corrupt the transfer. Reconnect manually and inspect the device before retrying.
+
+`:verified` means **the loader reported successful integrity verification and boot-partition selection**. It does not mean the new application rebooted, is healthy, or matches a specific board. Independently reconnect and inspect its firmware version. This code does not authenticate the TCP server or add TLS; use a trusted local network. SHA-256 is integrity pinning, not a publisher signature.
+
+## ESP32 unified BLE example
+
+The compatible unified loader must already be installed and its NVS hash pinned with `request_ota(mode: :OTA_BLE, bytes: image, ...)`. Close the application transport before opening the loader; never open serial and BLE on the same radio concurrently. Identify the bootloader's **actual** address explicitly (it can differ from the application's). The backend never guesses an incremented MAC, discovers/selects another device, or pairs automatically. If BlueZ does not know the address, discover that loader explicitly before calling `install`. Application reconnection still requires normal Meshtastic BLE pairing.
+
+```ruby
+result = Meshtastic::Admin::Firmware.install(
+  protocol: :unified_ble,
+  address: 'AA:BB:CC:DD:EE:FF', # selected loader address
+  adapter: 'hci0',
+  firmware: 'firmware-matching-board-update.bin',
+  timeout: 120,
+  verify: {
+    transport: :bluetooth,
+    connection: { address: 'AA:BB:CC:DD:EE:FF', adapter: 'hci0' }, # application address
+    expected_version: '2.7.1.example', # exact version from your chosen release
+    expected_node: 0xaabbccdd,
+    timeout: 90
+  }
+)
+# status: :boot_verified only after a fresh matching application reply
+```
+
+Service UUID is `4fafc201-1fb5-459e-8fcc-c5c9c331914b`; writes use `62ec0272-3ec5-11eb-b378-0242ac130005`, notifications use `62ec0272-3ec5-11eb-b378-0242ac130003`. Subscribe **before** VERSION. Commands are fragmented at 20 bytes (safe for ATT MTU 23), then binary is transferred in 20-byte writes with ATT responses. Each nonfinal binary write must receive `ACK\n`; the final write must receive `OK\n`, not ACK. The source sends final OK instead of final ACK. Newline buffering handles coalesced or fragmented notification data, with a 512-byte response-line bound. Unexpected UUID, ERR, malformed/version responses, silence or missing final OK fail closed. Neither binary chunks nor uncertain sessions are automatically replayed. Conservative 20-byte chunks trade speed for MTU portability; increase the total timeout for large images. BlueZ negotiates link MTU; an undersized/truncated VERSION notification fails safely rather than bypassing the handshake.
+
+For tests or an alternative Ruby GATT implementation, unified BLE accepts `backend:` (Nordic uses `gatt:`). The shared production class is `Meshtastic::Admin::Firmware::BLE::BlueZ.new(address:, adapter:, service_uuid:, timeout:).connect`. Its instance API is `subscribe(uuid:)`, `write(uuid:, bytes:, response: true/false)`, `notification(timeout:)` returning `{uuid:, bytes:}`, and `close`. All GATT service/characteristic lookup and notification match paths are scoped to the selected device. A private Ruby D-Bus connection is used; notification dispatch and synchronous method calls remain on the caller thread. No Python or external flasher process is used.
+
+## Post-reboot verification
+
+`verify:` is an **optional Hash** of `verify_reboot` options, validated before transfer. Omitting it preserves loader-only `:verified` results; it never silently claims boot health. Providing it runs verification only after the installer returns and closes its loader connection. You can also call `verify_reboot` independently.
+
+- Required: `transport: :tcp | :bluetooth | :serial`, `expected_version:` (exact nonempty String).
+- Production default: `connection:` Hash for a **new** application connection, explicitly specifying `host`, `address`, or `block_dev`, respectively. TCP uses PhoneAPI port **4403**, not updater port 3232; set `connection[:port]` only for a custom PhoneAPI port. Do not supply an existing socket/handle.
+- Optional: `expected_node:` numeric node ID, `timeout:` whole-operation deadline (60 seconds), `reboot_delay:` initial wait (3 seconds).
+- Optional advanced `reconnect:` callable receives `{transport:, connection:, timeout:}` and must return a newly connected handle of the selected transport, with configuration requested. The verifier still waits for configuration and issues a fresh Admin metadata request; a callback cannot substitute a cached metadata Hash. The returned handle is closed afterward.
+- Pre-metadata connection/configuration I/O failures retry every 0.25 seconds within the total deadline. Metadata errors/version mismatches do not cause a reflash or get converted to success.
+- A fresh source/request-ID-matched `get_device_metadata_response` is required. Cached `handle[:metadata]`, configuration metadata, loader VERSION, a routing ACK or successful port open cannot satisfy verification.
+- Success merges `status: :boot_verified`, `loader_status: :verified`, `boot_verified: true`, `reboot_verified: true`, current firmware version, node number and metadata into the transfer result. Failure raises; firmware might already have been written, so inspect the device rather than blindly rerunning the installer.
+
+This proves that the selected application responds and reports the expected version/optional identity. It does **not** cryptographically attest the running image, establish board compatibility, or test radio/RF operation. Use the correct release artifact and retain a recovery path.
+
+## Explicit gaps
+
+- No legacy BLE-only updater, ArduinoOTA/espota WiFi updater, Nordic Secure DFU, serial Nordic DFU, RP2040 UF2 filesystem copying, or automatic bootloader installation. Native protocol support is deliberately scoped; a board name alone does not establish its installed bootloader or transport capabilities.
+- No automatic discovery, board/image compatibility parser, OTA partition creation, or firmware downloads. ESP32 unified source targets ESP32/ESP32-S3; this is not a claim that every ESP32 variant or every Meshtastic board has that loader.
+- MQTT can carry an authorized preparation request; it is not an image transport or synchronous post-reboot verifier.
+- Tests exercise fake GATT loaders, real Ruby D-Bus signal marshalling over UNIX sockets, loopback TCP PhoneAPI/configuration/Admin exchanges and the retained TCP uploader. No hardware was contacted or flashed; physical device compatibility and reboot behavior remain hardware-unverified.
+
+## Upstream evidence
+
+Inspected main firmware commit `6d41e279f1f51bd59f687b9d441c1bf47b1594fc` and unified loader commit `e7c0b95e14b6a1ffeca81b71c1ac477593911213`:
+
+- [AdminModule.cpp](https://github.com/meshtastic/firmware/blob/6d41e279f1f51bd59f687b9d441c1bf47b1594fc/src/modules/AdminModule.cpp): `ota_request` checks the 32-byte hash, loader partition and capability; stores settings and schedules reboot. DFU entry is guarded by nRF52/RP2040 architecture. No `reboot_ota_seconds` handler appears.
+- [MeshtasticOTA.cpp](https://github.com/meshtastic/firmware/blob/6d41e279f1f51bd59f687b9d441c1bf47b1594fc/src/platform/esp32/MeshtasticOTA.cpp): stores the hash in NVS and identifies combined/BLE-only/WiFi-only loader project names.
+- [xmodem.cpp](https://github.com/meshtastic/firmware/blob/6d41e279f1f51bd59f687b9d441c1bf47b1594fc/src/xmodem.cpp): sequence-zero packet contains a filename; receiver uses `FSCom.open`/`file.write`. This is filesystem transfer, not an application updater.
+- [Unified protocol README](https://github.com/meshtastic/esp32-unified-ota/blob/e7c0b95e14b6a1ffeca81b71c1ac477593911213/README.md): VERSION/OTA commands, GATT UUIDs, hashes and completion response.
+- [ota_processor.cpp](https://github.com/meshtastic/esp32-unified-ota/blob/e7c0b95e14b6a1ffeca81b71c1ac477593911213/src/ota_processor.cpp): actual command parser, NVS hash gate, erasure, binary streaming, final hash check and boot-partition selection.
+- [ble_ota.cpp](https://github.com/meshtastic/esp32-unified-ota/blob/main/src/ble_ota.cpp): custom GATT UUIDs, 4096-byte input stream buffer, ACK-enabled processor, and two-second reboot delay. [ota_processor.cpp](https://github.com/meshtastic/esp32-unified-ota/blob/main/src/ota_processor.cpp) sends ACK only for nonfinal chunks and OK after final integrity/boot-partition checks.
+- [net_ota.cpp](https://github.com/meshtastic/esp32-unified-ota/blob/e7c0b95e14b6a1ffeca81b71c1ac477593911213/src/net_ota.cpp): TCP 3232 and **`setAckEnabled(true)`**. This differs from the README claim that WiFi has no application ACK. The implementation accepts either behavior. UDP discovery is emitted as broadcasts by this implementation; no discovery behavior is assumed by the Ruby client.
+
+[Admin documentation](admin.md)