meshtastic 0.0.180 → 0.0.181

data/documentation/admin-firmware.md

@@ -1,69 +1,126 @@
 # Meshtastic::Admin::Firmware
 
-Install Meshtastic firmware using the PhoneAPI / admin path (not esptool). Nested under [Admin](admin.md) because OTA is an `AdminMessage`.
+**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`.
 
-## What it does
+## Supported operations
 
-1. SHA-256 the image (`-update.bin` for ESP32 BLE/WiFi OTA).
-2. Send `ota_request` (`OTAEvent`: 32-byte hash + `:OTA_BLE` or `:OTA_WIFI`) on `ADMIN_APP`.
-3. On serial / TCP / Bluetooth, stream the image as `ToRadio.xmodemPacket` (SOH 128-byte blocks, CRC16, EOT). MQTT has no PhoneAPI XModem; it only publishes the admin `ota_request` so the node can reboot into OTA.
+| 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. |
 
-`enter_dfu` sends `enter_dfu_mode_request` (nRF52 USB UF2 / serial DFU). `reboot_ota(seconds:)` is the older `reboot_ota_seconds` field.
+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.
 
-Use a firmware file that matches the board. Interrupting a flash can brick the radio. Keep battery high.
+## ESP32 unified WiFi example
 
-This is not the web flasher / `esptool` USB bootloader path, and not nRF `.zip` via `adafruit-nrfutil`.
-
-## Methods
-
-- `install(firmware:, mode:, serial_obj: | tcp_obj: | bluetooth_obj: | mqtt_obj:)`
-- `request_ota` — admin hash + mode only
-- `enter_dfu`
-- `reboot_ota(seconds: 10)`
-- `xmodem_blocks(bytes)` / `send_xmodem(xmodem:)`
-- `sha256`
-- `help` / `authors`
-
-`mode:` is `:OTA_BLE` or `:OTA_WIFI`. `firmware:` is a path; `bytes:` is raw image bytes.
-
-## Serial / TCP / Bluetooth
+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
-Meshtastic::Admin::Firmware.install(
-  serial_obj: serial_obj,
-  firmware: 'firmware-heltec-v3-update.bin',
-  mode: :OTA_BLE
-)
+image = File.binread('firmware-matching-board-update.bin')
 
-Meshtastic::Admin::Firmware.install(
-  tcp_obj: tcp_obj,
-  firmware: 'firmware-heltec-v3-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
 )
 
-Meshtastic::Admin::Firmware.install(
-  bluetooth_obj: bluetooth_obj,
-  firmware: 'firmware-heltec-v3-update.bin',
-  mode: :OTA_BLE
+# 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' }
 ```
 
-## MQTT (remote admin)
+`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.
 
-Publishes one encrypted `ADMIN_APP` envelope. The node must accept remote admin. It does not push XModem over the broker.
+## 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
-Meshtastic::Admin::Firmware.install(
-  mqtt_obj: mqtt_obj,
-  firmware: 'firmware-heltec-v3-update.bin',
-  mode: :OTA_WIFI,
-  to: '!aabbccdd',
-  psks: { LongFast: 'AQ==' }
+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
 ```
 
-## Related
+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.
 
-- [Meshtastic::Admin](admin.md)
-- [Meshtastic::Xmodem](xmodem.md)
-- [Meshtastic::MQTT](mqtt.md)
+[Admin documentation](admin.md)

data/documentation/admin.md

@@ -1,55 +1,107 @@
 # Meshtastic::Admin
 
-Builds `Meshtastic::AdminMessage` and sends it on `ADMIN_APP` (port 6) through [Meshtastic.deliver_data](meshtastic.md). Pass a connected `serial_obj`, `bluetooth_obj`, `tcp_obj`, or `mqtt_obj`.
+Build and send `AdminMessage` on `ADMIN_APP` through a connected `serial_obj`, `bluetooth_obj`, `tcp_obj`, or `mqtt_obj`. These operations can change configuration, reboot, erase files, or reset a device. Sending is not confirmation of successful execution.
 
-Responses come back as `FromRadio` packets on the same transport (`subscribe` / `recv_from_radio`).
+## Addressing and defaults
 
-## Methods
+- Radio transports default `to` to their connected `my_node_num` and `from` to zero (the local PhoneAPI client). Complete the transport configuration handshake first, or supply `to` explicitly.
+- Remote administration requires an explicit unicast destination: an integer or `!` followed by exactly eight hexadecimal digits. Broadcast, zero, malformed strings, and missing destinations are rejected. MQTT always requires `to`.
+- Getter requests default `want_response: true`; state-changing operations default false. Explicit `want_response` overrides this. `want_ack` requests a separate routing acknowledgment. Some firmware setters answer with `ROUTING_APP` rather than an admin response when a response is requested.
+- Common transport options include `channel`, `hop_limit`, `want_ack`, `last_packet_id`, and MQTT `psks`. Device-owned remote PKI uses `pki_encrypted` and `public_key` on radio transports; MQTT channel encryption is not PKI admin authorization.
+- `get_channel(index: 0)` takes a **zero-based** index 0–7 and adds one exactly once for the wire. Raw `get_channel_request` passed to `encode`/`send` is already a wire value. `set_channel` retains the Channel protobuf's zero-based index.
 
-- `encode` — copies matching keys onto an `AdminMessage`
-- `send` — wrap and deliver (`want_response` default true)
-- `reboot(seconds: 5)`
-- `shutdown(seconds: 5)`
-- `get_owner` / `set_owner(long_name:, short_name:, owner:)`
-- `get_channel(index:)` / `set_channel(channel_settings:)`
-- `get_config(config_type:)` / `set_config(config:)`
-- `nodedb_reset`
-- `help` / `authors`
+## Encoding and validation
 
-`config_type` values: `:DEVICE_CONFIG`, `:POSITION_CONFIG`, `:POWER_CONFIG`, `:NETWORK_CONFIG`, `:DISPLAY_CONFIG`, `:LORA_CONFIG`, `:BLUETOOTH_CONFIG`, `:SECURITY_CONFIG`, `:SESSIONKEY_CONFIG`, `:DEVICEUI_CONFIG`.
+`encode` returns an `AdminMessage`, copying rather than modifying `message:` when provided. Supply exactly one payload variant. Conflicting variants, unknown option names, missing payloads, and nil payload values are rejected rather than silently overwriting the protobuf oneof. Protobuf field types and numeric bounds are enforced by the generated Ruby classes. False and zero are preserved, including `nodedb_reset: false`, `get_config_request: :DEVICE_CONFIG`, and backup location `:FLASH`.
 
-Any other `AdminMessage` field can be passed to `send` / `encode` (for example `set_ringtone_message`, `get_module_config_request`).
+Every generated payload field is available through `encode` and `send`, including response fields for tooling. Wrappers below accept the common transport options as well. Missing required scalar values are not silently converted to zero or empty text. An explicit empty ringtone or canned-message string may clear it.
 
-## Examples
+## Operation catalog
+
+| Group | Methods and payload arguments |
+| --- | --- |
+| Identity | `get_owner`; `set_owner(owner:)` or `set_owner(long_name:, short_name:)`; `set_ham_mode(ham:)` or callsign/frequency/power/name fields |
+| Channels | `get_channel(index: 0)`; `set_channel(channel_settings:)` (or `channel_pb:`) |
+| Configuration | `get_config(config_type: :DEVICE_CONFIG)`; `set_config(config:)`; `get_module_config(module_config_type: :MQTT_CONFIG)`; `set_module_config(module_config:)` |
+| UI | `get_ui_config`; `store_ui_config(ui_config:)`; `send_input_event(event:)` or `event_code`, `kb_char`, `touch_x`, `touch_y` |
+| Canned messages | `get_canned_messages`; `set_canned_messages(messages:)` with pipe-separated text |
+| Ringtone | `get_ringtone`; `set_ringtone(ringtone:)` with RTTTL text |
+| Device information | `get_device_metadata`; `get_device_connection_status`; `get_node_remote_hardware_pins` |
+| Position/time | `set_fixed_position(position:)` or `lat`, `lon`, `altitude`; `remove_fixed_position`; `set_time(time:)` with Unix seconds |
+| Node database | `remove_by_nodenum(node_num:)`; `set_favorite_node(node_num:)`; `remove_favorite_node(node_num:)`; `set_ignored_node(node_num:)`; `remove_ignored_node(node_num:)`; `toggle_muted_node(node_num:)`; `add_contact(contact:)` |
+| Edit transactions | `begin_edit`; `commit_edit` — defer implicit persistence/reboot for owner/channel/config/module changes until commit |
+| Preferences | `backup_preferences(location: :FLASH)`; `restore_preferences(location: :FLASH)`; `remove_backup_preferences(location: :FLASH)`; location may also be `:SD` |
+| Files and sensors | `delete_file(path:)`; `set_scale(scale:)`; `sensor_config(sensor_config:)` |
+| Authentication | `key_verification(key_verification:)`; `lockdown_auth(lockdown_auth:)` — typed protobuf payloads, not an automatic authentication workflow |
+| Power | `reboot(seconds: 5)`; `shutdown(seconds: 5)`; negative delays cancel pending actions |
+| Firmware | `enter_dfu`; `ota_request(event:)` with `AdminMessage::OTAEvent`; `reboot_ota(seconds: 5)` for deprecated legacy firmware only |
+| Resets | `factory_reset_device(value: 1)`; `factory_reset_config(value: 1)`; `nodedb_reset(preserve_favorites: true)`; `exit_simulator` |
+| Utilities | `encode`; `send`; `request`; `decode`; `response`; `help`; `authors` |
+
+Device reset clears BLE bonds; config reset preserves them. `nodedb_reset(preserve_favorites: false)` requests removal of favorites too, but firmware CLIENT_BASE/ROUTER/ROUTER_LATE roles can preserve favorites regardless. DFU is hardware-specific (upstream documents NRF52); OTA depends on the installed loader and supported mode. Modern firmware uses `ota_request`; `reboot_ota_seconds` is deprecated and absent from the inspected current AdminModule switch. Use [Admin::Firmware](admin-firmware.md) for the firmware transfer workflow.
+
+## Responses, correlation and session passkeys
+
+`decode(payload: bytes)` decodes raw AdminMessage bytes. `decode(packet:)` accepts a protobuf `FromRadio`, `MeshPacket`, or `Data` and requires decoded `ADMIN_APP` data. Malformed protobuf bytes raise the protobuf decoder error.
+
+`response(packet:, request_id:, from:)` accepts a `FromRadio` or `MeshPacket`, optionally matches the outgoing packet ID and numeric sender, and returns:
 
 ```ruby
-require 'meshtastic'
-
-serial_obj = Meshtastic::Serial.connect(block_dev: '/dev/ttyACM0')
-Meshtastic::Serial.wait_for_config(serial_obj: serial_obj)
-
-Meshtastic::Admin.set_owner(serial_obj: serial_obj, long_name: 'Node', short_name: 'N1')
-Meshtastic::Admin.get_owner(serial_obj: serial_obj)
-Meshtastic::Admin.get_config(serial_obj: serial_obj, config_type: :LORA_CONFIG)
-Meshtastic::Admin.get_channel(serial_obj: serial_obj, index: 0)
-Meshtastic::Admin.reboot(serial_obj: serial_obj, seconds: 5)
-# Meshtastic::Admin.shutdown(serial_obj: serial_obj, seconds: 5)
-# Meshtastic::Admin.nodedb_reset(serial_obj: serial_obj)
+{ message: admin_message, variant: :get_owner_response, value: owner,
+  session_passkey: passkey_bytes, request_id: packet_id, from: node_number }
 ```
 
-Raw field:
+Unrelated ports, non-response variants, encrypted/absent data, and mismatched IDs/senders return nil. These helpers do not authenticate packets or decrypt encrypted packets. `response` remains a pure decoder; use `request` for synchronous routing-error handling.
+
+### Synchronous request/readback
+
+`request` accepts raw `send` options or `message: AdminMessage`, plus `timeout:` (positive finite seconds, default 10), `request_id:` and `wait:`. By default it sends and waits on the connected radio's `from_radio_queue`. A getter returns the response hash above plus `result:` (the transport submission result). It requires both the outgoing request ID and target node, and the expected response variant. A local routing ACK is **not** remote readback. State-changing requests wait for a target-correlated `ROUTING_APP/NONE` and return `{ variant: :routing, value: :NONE, request_id:, from:, result: }`; even this is acknowledgment, not verification of persistent configuration.
 
 ```ruby
-Meshtastic::Admin.send(
-  serial_obj: serial_obj,
-  factory_reset_config: true
+reply = Meshtastic::Admin.request(
+  serial_obj: serial_obj, # alternatively bluetooth_obj: or tcp_obj:
+  to: '!aabbccdd',
+  message: Meshtastic::AdminMessage.new(get_device_metadata_request: true),
+  timeout: 10
 )
+version = reply[:value].firmware_version
 ```
 
+After reboot, reconnect, complete the transport handshake, and make this request on the **new handle**. Match the returned version against the expected firmware; neither a successful upload nor an ACK establishes firmware health.
+
+- `Timeout::Error` means no matching response arrived within the monotonic receive budget, or the receive queue closed. The budget includes automatic session acquisition. Blocking transport writes retain their underlying transport's I/O behavior; this is not an interrupting write timeout.
+- `Admin::RoutingError` exposes `reason`, `request_id`, and `from`. Correlated nonzero routing errors from the target **or connected local radio** terminate immediately (including local PKI/no-route failures).
+- Unrelated packets are retained and returned to the queue on success or failure. Deferred packets can move behind newer queued traffic. If the queue closes, the handle receives a replacement closed queue retaining those packets. Do not retain a separate queue reference across disconnects.
+- Pause any external `subscribe`/`recv_from_radio` consumer while a synchronous request owns the receive queue. Concurrent synchronous requests on one handle fail fast with `IOError`; Admin does not install a global transport dispatcher.
+- MQTT has no compatible radio queue; synchronous requests and automatic acquisition are rejected rather than pretending submission is readback.
+- `request(wait: false, ...)` retains the old `{ request_id:, result: }` submission-only API, including MQTT. Use your existing receive loop with `response` in that mode. Automatic remote session acquisition can still wait unless an explicit key or `auto_session: false` is supplied.
+- IDs are generated or supplied with `request_id:` (2 through `0xffffffff`), overriding `last_packet_id`. Use fresh IDs; deliberately reusing one cannot distinguish a stale reply. ID 1 is excluded because transport predecessor zero requests a random ID.
+
+### Automatic sessions
+
+Remote state-changing `send` calls (including convenience setters, reboot, and firmware commands) automatically request `get_config_request: :SESSIONKEY_CONFIG` before transmitting when no passkey was supplied. Acquisition must return a correlated `get_config_response` containing exactly eight passkey bytes; otherwise the write is not sent. Reads and local PhoneAPI operations do not need acquisition. An explicit eight-byte `session_passkey:` or a passkey already in `message:` bypasses acquisition; `auto_session: false` explicitly disables it. For MQTT provide the key obtained through your own authorized receive workflow.
+
+The key is cached **only in the connection handle, scoped by target node**. A matching synchronous getter refreshes that target's cache. Cache entries expire conservatively after 150 seconds measured from the start of acquisition; `refresh_session: true` forces a new acquisition. `ADMIN_BAD_SESSION_KEY` invalidates the target cache, so the **next caller-initiated** write acquires again. No state-changing request is automatically replayed, including on timeout or rejection. Reconnect with a new handle after reboot to discard old state.
+
+The node's passkey is not its public/private key, channel PSK, or a substitute for remote admin authorization. Upstream exempts local PhoneAPI commands (`from == 0`) and enumerated getters/responses from passkey checks. Other remote commands require it. Firmware expires keys after 300 seconds and can rotate them when issuing a response after 150 seconds; another controller can therefore invalidate even a locally unexpired key. The library does not log keys or payloads; response hashes and connection handles contain secrets, so do not log or serialize them. `:SESSIONKEY_CONFIG` carries the key in the **AdminMessage envelope**, not the Config payload.
+
+Convenience getters and `send` still return the transport submission result. They do not wait for readback; use `request` when verification matters.
+
+## Sources and compatibility
+
+Official upstream sources inspected for the wire contract and firmware behavior:
+
+- [admin.proto](https://github.com/meshtastic/protobufs/blob/master/meshtastic/admin.proto)
+- [AdminModule.cpp](https://github.com/meshtastic/firmware/blob/master/src/modules/AdminModule.cpp)
+
+The generated protobuf schema can expose fields not implemented by an installed firmware build. Sensor, key-verification, lockdown, module-specific handlers, simulator, SD, DFU, and OTA functionality remain firmware/hardware dependent. Encoding a field does not establish that a device supports it. This implementation was verified with real Ruby protobuf encoding and fake transports, not live hardware.
+
 ## Related
 
-- [Meshtastic::Admin::Firmware](admin-firmware.md)
-- [Meshtastic::Channel](channel.md)
-- [Meshtastic::Config](config.md)
-- [Meshtastic::ModuleConfig](module-config.md)
-- [Meshtastic::RTTTL](rtttl.md)
+- [Admin::Channel](admin-channel.md)
+- [Admin::Config](admin-config.md)
+- [Admin::Firmware](admin-firmware.md)
+- [Channel](channel.md)
+- [Config](config.md)
+- [ModuleConfig](module-config.md)
+- [RTTTL](rtttl.md)

data/documentation/mesh-interface.md

@@ -18,6 +18,13 @@ Packet builder used by Serial, Bluetooth, TCP, and MQTT. Instantiated internally
 
 On Serial/Bluetooth/TCP, transports pass `psks: nil` so the radio owns channel crypto. MQTT must pass `psks`.
 
+`send_data` and `send_packet` preserve `pki_encrypted: true` and `public_key:`
+(32 raw bytes) for remote administrative requests. The connected radio performs
+the public-key encryption; the Ruby client does not encrypt these packets itself.
+Explicit PKI requests reject MQTT and host-side PSK encryption instead of silently
+falling back to channel encryption. Supplying a recipient key does not grant admin
+rights: the target must authorize the sending radio's key.
+
 `send_text` refuses payloads larger than `Meshtastic::Constants::DATA_PAYLOAD_LEN`.
 
 ## Example

data/lib/meshtastic/admin/channel.rb

@@ -1,28 +1,46 @@
 # frozen_string_literal: true
 
 require 'meshtastic/channel_pb'
+require 'meshtastic/apponly_pb'
+require 'base64'
+require 'uri'
 
 module Meshtastic
   module Admin
     module Channel
       public_class_method def self.build_settings(opts = {})
-        settings = opts[:settings] || Meshtastic::ChannelSettings.new
-        settings.name = opts[:name].to_s if opts[:name]
-        settings.psk = opts[:psk] if opts[:psk]
-        settings.channel_num = opts[:channel_num].to_i if opts[:channel_num]
-        settings.id = opts[:id].to_i if opts[:id]
-        settings.uplink_enabled = opts[:uplink_enabled] unless opts[:uplink_enabled].nil?
-        settings.downlink_enabled = opts[:downlink_enabled] unless opts[:downlink_enabled].nil?
-        settings.module_settings = opts[:module_settings] if opts[:module_settings]
-        settings.use_aead = opts[:use_aead] unless opts[:use_aead].nil?
+        source = opts[:settings]
+        settings = if source.is_a?(Hash)
+                     Meshtastic::ChannelSettings.new(source)
+                   elsif source
+                     Meshtastic::ChannelSettings.decode(source.to_proto)
+                   else
+                     Meshtastic::ChannelSettings.new
+                   end
+        Meshtastic::ChannelSettings.descriptor.each do |field|
+          key = field.name.to_sym
+          next unless opts.key?(key)
+
+          value = opts[key]
+          value = field.subtype.msgclass.new(value) if value.is_a?(Hash) && field.subtype
+          settings[field.name] = value
+        end
+        raise ArgumentError, 'PSK must contain 0, 1, 16, or 32 raw bytes' unless [0, 1, 16, 32].include?(settings.psk.bytesize)
+        raise ArgumentError, 'channel name must be fewer than 12 bytes' unless settings.name.bytesize < 12
+
         settings
       end
 
       public_class_method def self.build(opts = {})
-        channel = opts[:channel] || Meshtastic::Channel.new
-        channel.index = opts[:index].to_i if opts[:index]
+        channel = opts[:channel] ? Meshtastic::Channel.decode(opts[:channel].to_proto) : Meshtastic::Channel.new
+        index = opts.fetch(:index, channel.index)
+        raise ArgumentError, 'index must be an integer from 0 through 7' unless index.is_a?(Integer) && (0..7).cover?(index)
+
+        channel.index = index
         channel.role = opts[:role] if opts[:role]
-        channel.settings = opts[:settings] || build_settings(opts.merge({}))
+        raise ArgumentError, 'role must be PRIMARY, SECONDARY, or DISABLED' unless %i[PRIMARY SECONDARY DISABLED].include?(channel.role)
+
+        channel.settings = build_settings(opts.merge(settings: opts.fetch(:settings, channel.settings)))
         channel
       end
 
@@ -33,12 +51,52 @@ module Meshtastic
       end
 
       public_class_method def self.set(opts = {})
-        channel = opts[:channel] || build(opts.merge({}))
-        merged = opts.merge(channel_settings: channel)
-        merged.delete(:channel)
+        channel = build(opts.merge({}))
+        builder_keys = Meshtastic::ChannelSettings.descriptor.map { |field| field.name.to_sym } + %i[channel index role settings]
+        merged = opts.except(*builder_keys).merge(channel_settings: channel)
         Admin.set_channel(merged)
       end
 
+      public_class_method def self.export_url(opts = {})
+        channels = opts.fetch(:channels)
+        raise ArgumentError, 'exactly one primary channel is required' unless channels.one? { |channel| channel.role == :PRIMARY }
+
+        enabled = channels.select { |channel| channel.role == :PRIMARY || (opts[:include_all] != false && channel.role == :SECONDARY) }
+        raise ArgumentError, 'at most eight enabled channels can be shared' if enabled.length > 8
+
+        enabled = enabled.sort_by { |channel| [channel.role == :PRIMARY ? 0 : 1, channel.index] }
+        settings = enabled.map { |channel| build_settings(settings: channel.settings) }
+        channel_set = Meshtastic::ChannelSet.new(settings: settings, lora_config: opts[:lora_config])
+        "https://meshtastic.org/e/##{Base64.urlsafe_encode64(channel_set.to_proto, padding: false)}"
+      end
+
+      public_class_method def self.import_url(opts = {})
+        uri = URI.parse(opts.fetch(:url))
+        valid = uri.scheme == 'https' && uri.host == 'meshtastic.org' && %w[/e/ /d/].include?(uri.path)
+        valid &&= uri.userinfo.nil? && uri.port == 443 && uri.fragment&.match?(/\A[A-Za-z0-9_-]+={0,2}\z/)
+        raise ArgumentError, 'invalid channel URL' unless valid
+
+        channel_set = Meshtastic::ChannelSet.decode(Base64.urlsafe_decode64(uri.fragment))
+        raise ArgumentError, 'invalid channel URL' unless (1..8).cover?(channel_set.settings.length)
+
+        channel_set
+      rescue URI::InvalidURIError, Google::Protobuf::ParseError, ArgumentError, TypeError
+        raise ArgumentError, 'invalid channel URL'
+      end
+
+      public_class_method def self.apply_url(opts = {})
+        channel_set = import_url(url: opts[:url])
+        raise ArgumentError, 'add-only or query URL application is not supported; import offline and select slots explicitly' if URI.parse(opts[:url]).query
+
+        transport = opts.except(:url)
+        channels = channel_set.settings.each_with_index.map do |settings, index|
+          build(index: index, role: index.zero? ? :PRIMARY : :SECONDARY, settings: settings)
+        end
+        results = channels.map { |channel| set(transport.merge(channel: channel)) }
+        results << Config.set_lora(transport.merge(lora: channel_set.lora_config)) if channel_set.lora_config
+        results
+      end
+
       public_class_method def self.authors
         "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
       end
@@ -47,29 +105,29 @@ module Meshtastic
         puts "USAGE:
           # Build ChannelSettings for a mesh channel.
           #{self}.build_settings(
-            settings: 'optional - existing ChannelSettings protobuf to fill',
-            name: 'optional - channel name such as LongFast',
-            psk: 'optional - raw PSK bytes for the channel',
-            channel_num: 'optional - LoRa channel number',
+            settings: 'optional - ChannelSettings protobuf or Hash copied before overlay',
+            name: 'optional - channel name shorter than twelve UTF-8 bytes',
+            psk: 'optional - raw PSK of zero, one, sixteen, or thirty-two bytes',
+            channel_num: 'optional - deprecated channel number; prefer Config LoRa channel_num',
             id: 'optional - channel hash id',
             uplink_enabled: 'optional - whether MQTT uplink is enabled',
             downlink_enabled: 'optional - whether MQTT downlink is enabled',
-            module_settings: 'optional - ModuleSettings protobuf',
+            module_settings: 'optional - ModuleSettings protobuf or field Hash for precision and mute',
             use_aead: 'optional - whether AEAD crypto is enabled'
           )
 
           # Build a Channel protobuf with index, role, and settings.
           #{self}.build(
-            channel: 'optional - existing Channel protobuf to fill',
-            index: 'optional - channel slot index on the node',
+            channel: 'optional - existing Channel protobuf copied before overlay',
+            index: 'optional - integer channel slot zero through seven',
             role: 'optional - :PRIMARY, :SECONDARY, or :DISABLED',
-            settings: 'optional - ChannelSettings protobuf to attach'
+            settings: 'optional - ChannelSettings protobuf or field Hash to attach'
           )
 
           # Request a channel slot from the node.
           #{self}.get(
             serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
-            index: 'optional - channel slot index to request (default: 0)'
+            index: 'optional - zero-based channel slot; Admin adds one on wire (default: 0)'
           )
 
           # Write a channel slot on the node.
@@ -78,7 +136,23 @@ module Meshtastic
             channel: 'optional - Channel protobuf to write',
             index: 'optional - channel slot index when building a channel',
             role: 'optional - :PRIMARY, :SECONDARY, or :DISABLED',
-            settings: 'optional - ChannelSettings protobuf to attach'
+            settings: 'optional - ChannelSettings protobuf or field Hash to attach'
+          )
+
+          # Export enabled channels to a sharing URL.
+          #{self}.export_url(
+            channels: 'required - array of Channel protobufs with one primary',
+            include_all: 'optional - include secondary channels unless false',
+            lora_config: 'optional - LoRaConfig protobuf included in the URL'
+          )
+
+          # Decode a sharing URL without writing hardware.
+          #{self}.import_url(url: 'required - Meshtastic e or d channel URL')
+
+          # Write URL channels and optional LoRa configuration.
+          #{self}.apply_url(
+            url: 'required - Meshtastic channel URL replacing slots from zero',
+            serial_obj: 'optional - connected serial transport; BLE, TCP, MQTT also supported'
           )
 
           # Print the AUTHOR(S) string for this module.