meshtastic 0.0.180 → 0.0.181

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f12d73c0e68d9f1171a2b92d2cfe2277d22e4e78c7c33788cc52924ee6d40778
-  data.tar.gz: b0be149633c2a659dcea3ce83546f9a2ea5121f632a90bb3ee9b21a43ae79221
+  metadata.gz: 27355386b939c892e3fb2bc5ab98181fa0a02995663fadd66021153f9fbbf219
+  data.tar.gz: 5de937dd2654b8bbb7b8a5859251a63de35cef66f3fd6304bb714f3e6344d0ed
 SHA512:
-  metadata.gz: a4d41dbc793a0eb380cbfb815ce9cd15ac98802e80a3903ea7ed765d09c42ff9a4009a2d68ff44338026e553f18fd7d96d4419233018185ff3f733735b033149
-  data.tar.gz: d035c8f9c42d536ad97bdefc0de870dff4694ef651c86dd1e7002ada63145f089e9e70a74d73144ebac991d0d9dd8365f5c53ae0b0b6154c466d99f849e4b34a
+  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/admin-channel.md

@@ -1,33 +1,64 @@
 # Meshtastic::Admin::Channel
 
-Admin get/set for mesh channels. The generated protobuf remains `Meshtastic::Channel`; this module talks to the node on `ADMIN_APP`.
+Build, read, write, and share mesh channels using `ADMIN_APP`. The generated protobuf remains `Meshtastic::Channel`. All public methods accept one options Hash.
 
-Roles: `:PRIMARY`, `:SECONDARY`, `:DISABLED`.
+## Channel operations
 
-## Methods
+- `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.
 
-- `build_settings` — `ChannelSettings` (name, psk, uplink/downlink, AEAD)
-- `build` — `Channel` (index, role, settings)
-- `get(index:)` — `get_channel_request`
-- `set` — `set_channel` with a Channel protobuf
-- `help` / `authors`
+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.
 
-Do not pass a Channel protobuf as MeshInterface `channel:` (that field is the numeric channel index). This module strips that key before send.
+```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
 
-## Example
+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
-settings = Meshtastic::Admin::Channel.build_settings(name: 'LongFast', uplink_enabled: true)
-Meshtastic::Admin::Channel.set(
-  serial_obj: serial_obj,
-  index: 0,
-  role: :PRIMARY,
-  settings: settings
+# channels and lora_config are protobufs already obtained from the node.
+url = Meshtastic::Admin::Channel.export_url(
+  channels: channels, lora_config: lora_config
 )
-Meshtastic::Admin::Channel.get(serial_obj: serial_obj, index: 0)
+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)
 ```
 
-## Related
+**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.
 
-- [Meshtastic::Admin](admin.md)
-- [Meshtastic::Admin::Config](admin-config.md)
+Related: [Admin](admin.md), [Config](admin-config.md).

data/documentation/admin-config.md

@@ -1,28 +1,59 @@
 # Meshtastic::Admin::Config
 
-Admin get/set for radio `Meshtastic::Config` sections. The generated protobuf remains `Meshtastic::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`.
 
-## Methods
+## Operations
 
-- `get(config_type:)` — default `:DEVICE_CONFIG`
-- `set(config:)`
-- Named getters: `get_device`, `get_position`, `get_power`, `get_network`, `get_display`, `get_lora`, `get_bluetooth`, `get_security`, `get_sessionkey`, `get_device_ui`
-- `set_device(device:)`, `set_lora(lora:)`
-- `help` / `authors`
+| 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 |
 
-`config_type` values: `:DEVICE_CONFIG`, `:POSITION_CONFIG`, `:POWER_CONFIG`, `:NETWORK_CONFIG`, `:DISPLAY_CONFIG`, `:LORA_CONFIG`, `:BLUETOOTH_CONFIG`, `:SECURITY_CONFIG`, `:SESSIONKEY_CONFIG`, `:DEVICEUI_CONFIG`.
+- `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)
 
-config = Meshtastic::Config.new
-config.device = Meshtastic::Config::DeviceConfig.new(role: :CLIENT)
-Meshtastic::Admin::Config.set(serial_obj: serial_obj, config: config)
+# 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
+)
 ```
 
-## Related
+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.
 
-- [Meshtastic::Admin](admin.md)
-- [Meshtastic::Admin::Channel](admin-channel.md)
+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.