meshtastic 0.0.182 → 0.0.184

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b5946f218daad08b39581b432ce784a6f5e87dbb65604c56fb13ca80668f146
-  data.tar.gz: 71bb00a58a69e32525c4c802d4cccaa31123ace62547a0d4be35bc5416dd39fc
+  metadata.gz: 763ef1042cfde175868eab3896f7b53eaa75daf8984e64295b1b6db22a39a31e
+  data.tar.gz: eb3ba83188a23a19013c769fd8181962c8d8e0ca9e35c98a8c87efa600bef281
 SHA512:
-  metadata.gz: 7bac94e05a8015138bee0e41d110cc988236ded6403321876876b175985036f035768e3870a47ab516e328b9c05cea13f84e127f33a4b2e62ff5ccd3bb109c55
-  data.tar.gz: 11de3c970720a9775c5cdbbf3f1f311aa2d180be57a9c3da85b2ddef394c04eb7deec0b80cb8d6fe996f907ee813c799839a341fd3a965579c912770e51bddb4
+  metadata.gz: 03e7f64573c6baaa1a52624a184dd6c119f3e56fa0dd39dae82ed3540451fd835e6783fc59a6dd7cc2af2a3b0fe965c70c64a6049e0626f225762e6185141765
+  data.tar.gz: 394b62b327b1ca44b89d961f2896d9e1c1389a677353314cd7319a589e009372ab56868fb5ece662d84d6f2e0a1a3e29d9b13f622e89d9c85c417acbb7f2d19c

data/documentation/README.md

@@ -28,9 +28,14 @@ Do not open Serial and Bluetooth to the same radio at once. Always `disconnect`
 ## Feature modules
 
 - [Meshtastic::Admin](admin.md)
+- [Meshtastic::Admin::Backup](admin-backup.md)
 - [Meshtastic::Admin::Channel](admin-channel.md)
 - [Meshtastic::Admin::Config](admin-config.md)
 - [Meshtastic::Admin::Firmware](admin-firmware.md)
+  - [UF2 mounted bootloader volumes](admin-firmware-uf2.md)
+  - [Intel HEX through an SWD programmer](admin-firmware-hex.md)
+  - [ESP serial ROM installer](admin-firmware-serial.md)
+  - [Nordic legacy BLE DFU packages](admin-firmware-nordic.md)
 - [Meshtastic::ModuleConfig](module-config.md)
 - [Meshtastic::Position](position.md)
 - [Meshtastic::Telemetry](telemetry.md)

data/documentation/admin-backup.md

@@ -0,0 +1,369 @@
+# Admin::Backup — native host-side configuration snapshots
+
+`Meshtastic::Admin::Backup` exports a versioned JSON document (default) or binary
+Meshtastic `DeviceProfile` (`format: :device_profile`) using fresh,
+request-ID/source-correlated Admin requests. It imports validated protobuf
+sections with bounded routing ACK waits. It does not invoke the firmware's
+filesystem backup/restore commands or shell out to another client.
+
+**Backups contain secrets by default**, including channel PSKs, Wi-Fi/MQTT
+credentials, private security keys and UI PINs when firmware returns them in
+selected sections. Keep the file and returned Hash private; do not print either
+in logs. Firmware can redact secrets or return default/empty values. Such a
+snapshot cannot recover values the device did not disclose. Importing those
+values can clear existing settings. Review the selection before exporting and
+before restoring, especially across devices or firmware versions.
+
+## Export
+
+```ruby
+require 'meshtastic'
+require 'meshtastic/admin/backup'
+
+snapshot = Meshtastic::Admin::Backup.export(
+  transport_obj: connection,
+  path: '/private/directory/node-backup.json', # optional; MUST NOT exist
+  config_types: %i[DEVICE_CONFIG POSITION_CONFIG POWER_CONFIG DISPLAY_CONFIG LORA_CONFIG],
+  module_config_types: %i[MQTT_CONFIG TELEMETRY_CONFIG],
+  channel_indexes: [0, 1],
+  include_owner: true,
+  include_ui: false,
+  timeout: 10
+)
+# Safe to display status/count; NOT snapshot[:backup].
+snapshot.slice(:status, :count)
+```
+
+`transport_obj:` is a connected Serial, Bluetooth or TCP handle with a receive
+queue. **MQTT synchronous export/import is explicitly unsupported**, including
+dry runs. `to:` optionally selects a unicast target; otherwise the connected
+local node is used. `channel:` and `hop_limit:` are Admin delivery options.
+Pause external queue consumers and do not interleave other Admin edits with a
+backup/restore. The underlying Admin layer serializes individual requests,
+not an entire multi-request snapshot or transaction.
+
+JSON selection defaults (binary-specific differences are listed below):
+
+- `include_owner: true`: only `long_name`, `short_name`, `is_licensed`.
+  Never clone User ID, MAC, hardware model, public key, role or messaging
+  capability metadata. Role belongs to device configuration; security keys
+  belong to explicitly selected security configuration.
+- `config_types:` defaults to `DEVICE_CONFIG`, `POSITION_CONFIG`, `POWER_CONFIG`,
+  `NETWORK_CONFIG`, `DISPLAY_CONFIG`, `LORA_CONFIG`, `BLUETOOTH_CONFIG`,
+  `SECURITY_CONFIG`. Use a narrower list for firmware that lacks sections.
+- `module_config_types: []`: opt in to supported module ConfigType symbols.
+  All 17 currently generated ModuleConfig sections are supported, including
+  `EXTNOTIF_CONFIG`, `STOREFORWARD_CONFIG`, `CANNEDMSG_CONFIG`,
+  `STATUSMESSAGE_CONFIG`, `TRAFFICMANAGEMENT_CONFIG`, `TAK_CONFIG`,
+  `MESHBEACON_CONFIG`. `Backup::MODULE_TYPES` lists the complete set.
+- `channel_indexes: [0, 1, 2, 3, 4, 5, 6, 7]`: explicit zero-based slots,
+  including disabled channels. Wire getters use one-based indexes.
+- `include_ui: false`: opt in to dedicated get/store UI operations.
+- `timeout: 10`: positive finite seconds **per Admin request**, not a deadline
+  for the entire backup. Remote writes can first acquire an Admin session.
+
+Unsupported selected sections fail the export; they are not silently skipped.
+No file is created until every selected response has been collected and the
+document validated. Empty JSON selections are allowed. A successful JSON return contains
+`:status => :exported`, `:count`, `:backup` and `:warnings`. A read error raises.
+Snapshots are sequential fresh reads, not an atomic device-wide snapshot.
+
+Files are exclusively created with mode `0600`, `O_EXCL` and `O_NOFOLLOW`, then
+flushed and fsynced. There is no overwrite flag. Existing files and final-path
+symlinks fail. Use a trusted parent directory: parent-directory symlinks are not
+resolved or pinned. A disk write/sync failure raises and can leave a partial
+0600 file; it is never reported as a successful backup. File mode protection is
+not encryption and does not protect against privileged host access.
+
+## Validate, plan and import
+
+```ruby
+plan = Meshtastic::Admin::Backup.import(
+  transport_obj: connection,
+  path: '/private/directory/node-backup.json',
+  dry_run: true
+)
+
+result = Meshtastic::Admin::Backup.import(
+  transport_obj: connection,
+  backup: snapshot[:backup], # use exactly one of backup: or path:
+  edit_transaction: true,   # ONLY when target firmware supports it
+  verify: true,
+  timeout: 10
+)
+```
+
+`dry_run: true` performs **no radio requests or writes**, including no session
+acquisition, edit begin, getters or readback. It validates the entire document
+first. `dry_run`, `edit_transaction` and `verify` default to `false` and must be
+booleans. Unknown options are rejected. Import paths must be regular files and
+must not be final-path symlinks.
+
+The importer rejects incompatible format/version, unknown document/record/
+protobuf fields, unknown section selectors, duplicate section/slot records,
+invalid channel indexes, section/slot mismatches, conflicting oneofs, malformed
+protobuf scalar values, null values and noncanonical bytes/base64 **before any
+radio request**. A version-1 document is a Hash with string keys:
+
+```json
+{
+  "format": "meshtastic-admin-backup",
+  "version": 1,
+  "warning": "A human-readable limitations notice",
+  "records": [
+    {
+      "section": "config",
+      "slot": "DEVICE_CONFIG",
+      "value": { "device": { "serial_enabled": false } }
+    }
+  ]
+}
+```
+
+Sections are `owner`, `config`, `module_config`, `channel`, `ui`. Owner/UI slots
+are JSON null; config/module slots are uppercase enum names; channel slots are
+integers. `value` is protobuf JSON with **snake_case protobuf field names**,
+canonical base64 bytes, protobuf enum representations and emitted scalar
+defaults. Known fields and protobuf presence/default semantics round-trip;
+unknown binary wire fields are not archived. This is not an opaque protobuf
+wire backup. Missing fields in a manually edited document mean protobuf
+defaults, not a patch/merge. YAML and arbitrary object deserialization are never
+used. Session envelope passkeys and `SESSIONKEY_CONFIG` are never exported or
+accepted; automatic session state stays inside the existing Admin connection.
+
+Writes preserve input order within priority groups: ordinary owner/module/UI/
+core settings first, channels next, then LoRa, Bluetooth, network and security.
+These latter settings can disrupt the connection. Other firmware-specific
+settings can also disrupt it; ordering cannot guarantee connectivity.
+
+## Binary DeviceProfile (`.cfg`) export and import
+
+Select binary output explicitly; export accepts only `format: :json` (default)
+or `format: :device_profile`, not `:auto`. The path extension does not choose
+export format. JSON version-1 output and return keys are unchanged.
+
+```ruby
+snapshot = Meshtastic::Admin::Backup.export(
+  transport_obj: connection,
+  format: :device_profile,
+  path: '/private/directory/nodeConfig.cfg', # optional; MUST NOT exist
+  config_types: %i[DEVICE_CONFIG POSITION_CONFIG LORA_CONFIG],
+  module_config_types: %i[MQTT_CONFIG TELEMETRY_CONFIG],
+  channel_indexes: [0, 1], # actual contiguous PRIMARY/SECONDARY slots only
+  include_owner: true,
+  include_ui: false,
+  include_ringtone: true,
+  include_canned_messages: true,
+  timeout: 10
+)
+# Safe status fields only. NEVER print backup bytes or decoded profile.
+snapshot.slice(:status, :format, :count)
+# snapshot[:backup] is a raw ASCII-8BIT String, not JSON/base64 or a protobuf object.
+# Pass it directly to Backup.import(transport_obj: connection,
+#                                 backup: snapshot[:backup], dry_run: true).
+```
+
+Binary returns `{ status: :exported, format: :device_profile, count: Integer,
+backup: binary_string, warnings: [...] }`. `count` is the number of restorable
+sections (owner counts once, each channel counts once, duplicate URL/config
+LoRa counts once), not the byte count or number of protobuf fields. The `.cfg`
+file contains exactly `snapshot[:backup]`. File protections are the same
+exclusive/no-follow 0600 creation, flush and fsync as JSON. No file is created
+until reads and strict binary validation succeed.
+
+Binary selection uses the same core/module/owner/channel defaults as JSON,
+with these format-specific rules:
+
+- All eight core and 17 module selections are supported. Present empty nested
+  messages, byte fields, repeated values and scalar defaults round-trip. Local
+  container storage versions are not invented.
+- Owner names and license flag are explicitly present, including empty names
+  and `false`. Optional `is_unmessagable` is copied only when present in the
+  fresh User response, including explicitly present `false`. ID, MAC, hardware,
+  public key and envelope session passkeys are not copied.
+- `include_ui: true` is **rejected before any radio requests**: DeviceProfile
+  has no UI field. Use JSON for UI snapshots.
+- ChannelSet URLs cannot preserve arbitrary indexes or disabled slots. Select
+  `channel_indexes: []` to omit channels, or an ordered contiguous prefix such
+  as `[0]` or `[0, 1]`. Sparse/reordered selections are rejected before requests.
+  Returned slot 0 must be PRIMARY, later selected slots SECONDARY, each with
+  settings; mismatched indexes, disabled slots and other roles fail export
+  without creating a file. No selected channel is silently skipped or moved.
+  **The default all-eight selection therefore fails if any slot is disabled**;
+  choose the actual enabled prefix or use JSON to preserve disabled/sparse slots.
+  Selected LoRa is included identically in both `config.lora` and the URL;
+  if LoRa is not selected, the URL does not invent or fetch it. Unselected
+  trailing channel slots are not disabled by a later binary import.
+- `include_ringtone: true` and `include_canned_messages: true` request fresh
+  strings and preserve present empty strings. Both default to false and are
+  binary-only options; JSON rejects these keys rather than ignoring them.
+- `fixed_position:` optionally accepts an explicit `Meshtastic::Position` or
+  field Hash, e.g. `{ latitude_i: 0, longitude_i: 0, altitude: 0 }`. It is
+  validated before any requests and copied with protobuf presence/defaults.
+  This is caller-supplied input, **not a fresh radio read**: no dedicated Admin
+  getter exists. It defaults to absent and is binary-only. No position is
+  inferred from cached GPS data or the position configuration.
+- An entirely empty binary selection is rejected before requests because it
+  would not produce an importable profile. JSON still permits empty records.
+
+The importer accepts the same binary `meshtastic.DeviceProfile` used by
+Meshtastic clients, entirely in Ruby.
+Use exactly one source and select `format: :device_profile` explicitly, or use
+`format: :auto` (the default for import):
+
+```ruby
+plan = Meshtastic::Admin::Backup.import(
+  transport_obj: connection,
+  path: '/private/directory/nodeConfig.cfg',
+  format: :device_profile,
+  dry_run: true
+)
+# Only section/slot identities and counts are returned; no profile contents.
+plan.slice(:status, :planned, :plan)
+
+# Alternative in-memory source, still offline validation with no radio requests:
+plan = Meshtastic::Admin::Backup.import(
+  transport_obj: connection,
+  backup: binary_profile_string,
+  format: :device_profile,
+  dry_run: true
+)
+```
+
+`format:` accepts only `:auto`, `:json`, or `:device_profile`. In auto mode a
+`.cfg` path (case-insensitive) selects binary, `.json` selects JSON, and a Hash
+selects the existing JSON document API. Other paths and Strings are validated
+as binary first, then as JSON when JSON-looking content fails binary validation.
+This avoids confusing a valid binary name field beginning with a newline and
+`{` with JSON. Explicit format overrides the extension. JSON Strings are also
+accepted; versioned JSON Hash behavior and JSON export selections are unchanged.
+No YAML, executable serialization, or implicit protobuf object input is used.
+
+Presence-aware mapping:
+
+- Present `long_name`, `short_name`, `is_licensed`, and `is_unmessagable` become
+  one `owner`/`set_owner` operation. Explicit `false` and empty names are not
+  treated as absent. User identity/MAC/hardware/public-key fields are never
+  synthesized. The Admin User schema has no presence for names/license, so
+  omitted members of a sent owner message carry protobuf defaults; this is not
+  a read/merge patch API. Firmware determines how those defaults are applied.
+- Every present `LocalConfig` and `LocalModuleConfig` message becomes its own
+  writable Config/ModuleConfig oneof, including present empty submessages.
+  All eight core and 17 module sections are supported. Nested bytes, repeated
+  values, defaults and optional presence are retained. The local containers'
+  `version` fields are storage-schema metadata, not Admin settings; they are
+  validated but not written. A metadata-only/empty profile is rejected.
+- `channel_url` must be an HTTPS `meshtastic.org/e/` or `/d/` URL with a valid
+  base64url ChannelSet and one through eight settings, no query or userinfo.
+  Settings map in order to primary slot 0 and secondary slots 1–7; unlisted
+  trailing slots are **not** disabled. PSK lengths and channel-name bounds are
+  checked. Embedded LoRa configuration is restored too. If both the profile and
+  URL carry LoRa, equal messages are deduplicated; conflicting messages reject
+  the entire profile rather than silently choosing one.
+- Present `fixed_position`, `ringtone`, and `canned_messages` map respectively
+  to `set_fixed_position`, `set_ringtone_message`, and
+  `set_canned_message_module_messages`, with nil slots and matching section
+  names in the plan. Zero coordinates/altitude and present empty strings are
+  preserved. Absent fields are not turned into clears or removal operations.
+
+The **entire** binary profile and nested ChannelSet are validated before any
+Admin request, including session acquisition or begin-edit. A strict recursive
+wire check rejects unknown tags (including sessionkey additions), unknown enum
+values, duplicate singular fields/conflicting oneofs, invalid wire types,
+truncation, oversized/noncanonical varints, invalid booleans and nonfinite
+floats. Binary messages are limited to 1 MiB and 32 nested levels. Empty or
+arbitrary bytes are not accepted as an empty restore. Strictness intentionally
+rejects unsupported future schemas rather than dropping fields. This is format
+validation, not authentication: protobuf has no file magic or signature, so a
+valid nonempty DeviceProfile cannot be distinguished from another byte stream
+that happens to encode the same schema. Session passkeys are never imported.
+
+`verify: true` compares fresh owner/config/module/channel/ringtone/canned-message
+responses. Fixed position has **no dedicated Admin getter**: its record reports
+`readback: :unsupported`, making the overall status `:readback_incomplete` even
+when all available comparisons match. No cached position or config flag is
+misrepresented as fixed-position verification. All existing ACK, transaction,
+no-replay, secret-handling and persistence limitations apply.
+
+## Transactions and failure reporting
+
+`edit_transaction: true` explicitly sends `begin_edit_settings`, waits for its
+ACK, sends each section once with a correlated ACK wait (or matching timeout
+readback as described below), then sends
+`commit_edit_settings` and waits again. Current upstream
+[AdminModule.cpp](https://github.com/meshtastic/firmware/blob/master/src/modules/AdminModule.cpp)
+implements a begin flag and commit save of configuration/module/device/channel/
+node database segments. Commit also disables Bluetooth. **This is not an atomic
+rollback facility**: firmware may apply values before commit, UI has its own
+storage operation, and the protocol has no supported cancel/rollback here.
+There is no reliable capability probe, so enable this option only with firmware
+you have verified supports it. Default `false` avoids claiming universal edit
+transaction support.
+
+Result fields:
+
+- `status`: `dry_run`, `acknowledged`, `applied`, `partial_failure`,
+  `readback_matched` or `readback_incomplete`. `applied` means all sections
+  completed, but at least one required timeout readback instead of an ACK;
+  it does not claim every mutation was acknowledged or persisted.
+- `planned`, `attempted`, `acknowledged`, `readback_confirmed`: section counts, excluding transaction
+  commands and automatic session requests. Attempted is an API attempt and
+  does not prove the write reached the wire.
+- `plan`: ordered section/slot identities, including in dry runs; no secret values.
+- `acknowledged` counts only actual successful setter ACKs. `readback_confirmed`
+  counts only setters whose ACK timed out but whose fresh getter matched.
+  These counts are separate, never double-counted, and retained on later failure.
+- `records`: completed section/slot statuses (`acknowledged` or
+  `readback_confirmed`), without configuration values.
+- `transaction`: `not_requested`, `begin_uncertain`, `open`, `commit_uncertain`
+  or `commit_acknowledged`.
+- `failure`: on write/begin/commit failure, the operation, section/slot where
+  applicable, exception class and routing reason where available. Exception
+  contents and secrets are not included. Failed timeout recovery also includes
+  `readback: mismatch|unsupported|failed`; getter exceptions retain their class
+  and routing reason where available.
+- `warnings`: secret/redaction/persistence limitations.
+- `persistence_verified`: always `false`.
+
+Only a section setter's `Timeout::Error` triggers recovery: if a supported
+getter exists, import issues one **new**, request-ID/source-correlated Admin GET
+with its own per-request timeout. This happens even with `verify: false`.
+It continues only if the entire expected protobuf setting matches, using the
+same presence-aware comparison as optional verification. Portable owner fields
+are compared while generated owner identity/hardware metadata is excluded.
+No cached value, unrelated response, late setter ACK, or transport submission
+is substituted for that fresh read. The mutation is **never resent**.
+
+Mismatch (including redacted/empty secrets in place of expected nonempty
+secrets), absent getter, getter timeout/error, and correlated routing rejection
+remain partial failures. Secret fields are not ignored or treated as wildcards;
+the report never includes expected/actual values. Firmware normalization can
+also prevent exact matching. A matching empty/default value cannot establish
+that firmware disclosed a secret; existing backup completeness limitations
+still apply. Fixed-position writes have no supported getter. Begin and commit
+timeouts do not use this recovery, and routing errors do not trigger it.
+
+After an unresolved failed write, no later sections, commit, rollback or replay are sent.
+A transaction may remain open. A missing commit ACK is uncertain even when all
+section ACKs arrived; the node may have committed and rebooted. Inspect the
+node and establish a fresh connection before deciding on any manual recovery.
+Do not automatically rerun the import.
+
+`verify: true` performs another round of fresh correlated reads **after** all
+sections complete and any requested commit ACK arrives. Timeout-recovery reads
+do not replace this optional post-commit check.
+It compares protobuf values (only portable owner fields), adds per-record
+`readback: matched|mismatch|failed` and `readback_matched` count. Redaction,
+normalization, link loss or reboot can prevent a match. Readback failures never
+replay writes. Even a match proves only current reported state, not persistence
+across reboot or successful firmware-side storage.
+
+## Verification scope
+
+The automated peer decodes production Serial framing/ToRadio/Admin protobufs,
+maintains configuration state, and returns encoded correlated FromRadio Admin
+or routing packets through the real Admin queue. Tests cover round-trip bytes
+and defaults, dry runs, validation, secret handling, file permissions/symlinks,
+ACK failures, timeouts, commit uncertainty, optional readback and help
+conventions. No hardware, firmware reboot/persistence, radio-link reliability,
+Bluetooth GATT or live TCP endpoint was exercised for this feature.

data/documentation/admin-channel.md

@@ -19,15 +19,15 @@ settings = Meshtastic::Admin::Channel.build_settings(
   module_settings: { position_precision: 13, is_muted: false }
 )
 Meshtastic::Admin::Channel.set(
-  serial_obj: serial_obj, index: 1, role: :SECONDARY, settings: settings
+  transport_obj: connection, index: 1, role: :SECONDARY, settings: settings
 )
-Meshtastic::Admin::Channel.get(serial_obj: serial_obj, index: 1)
+Meshtastic::Admin::Channel.get(transport_obj: connection, index: 1)
 
 # Explicitly disable a slot.
-Meshtastic::Admin::Channel.set(serial_obj: serial_obj, index: 1, role: :DISABLED)
+Meshtastic::Admin::Channel.set(transport_obj: connection, 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.
+Admin transport/routing/authentication options pass through (`transport_obj: connection`, `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
 
@@ -45,14 +45,14 @@ url = Meshtastic::Admin::Channel.export_url(
 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)
+Meshtastic::Admin::Channel.apply_url(transport_obj: connection, 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.
+Writes are submissions, not delivery/persistence acknowledgements. No live hardware was exercised. Admin's automatic remote session-key acquisition applies. No automatic write-acknowledgment collection, 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
 

data/documentation/admin-config.md

@@ -27,23 +27,23 @@ ModuleConfig is a different protobuf: use `Admin.get_module_config` / `Admin.set
 
 ## 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).
+Read/write helpers pass through Admin options, including `transport_obj: connection`, `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.
+A return value means transport submission, **not confirmed persistence**. These methods inherit Admin's automatic remote session-key acquisition, but do not wait for write acknowledgments 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)
+Meshtastic::Admin::Config.get_lora(transport_obj: connection)
 
 # Supply the full desired section; prefer editing the returned protobuf.
 Meshtastic::Admin::Config.set_position(
-  serial_obj: serial_obj,
+  transport_obj: connection,
   position: Meshtastic::Config::PositionConfig.new(position_broadcast_secs: 900)
 )
 
 Meshtastic::Admin::Config.set_device_ui(
-  serial_obj: serial_obj,
+  transport_obj: connection,
   device_ui: Meshtastic::DeviceUIConfig.new
 )
 ```

data/documentation/admin-firmware-hex.md

@@ -0,0 +1,57 @@
+# Intel HEX over SWD — nRF52840 only
+
+`Meshtastic::Admin::Firmware::Hex` validates Intel HEX in native Ruby and programs an explicitly selected **nRF52840** through a separately installed, trusted **OpenOCD 0.12+ executable**. No Python flashing tools are used. Other nRF52 chips, other MCU families, serial HEX upload, and automatic probe/board discovery are unsupported.
+
+## Safety and prerequisites
+
+Calling `install` is destructive: OpenOCD erases sectors containing image data, writes, verifies, and resets the target. Erasing a sector can remove existing bytes outside the image's populated addresses in that sector. Select the exact firmware for your board, and include any required bootloader/SoftDevice components. A syntactically valid HEX is not authenticated firmware and does not prove board compatibility. UICR records can change bootloader/protection configuration.
+
+Supply absolute paths to an installed OpenOCD executable and **trusted local interface and nRF52 target configuration files**. Configurations are executable Tcl, not sandboxed data; never use untrusted downloaded configuration files. They must configure one intended SWD target and its flash banks without independently programming/erasing hardware. Supply its exact OpenOCD target name, normally `nrf52.cpu`, and explicit `expected_chip: :nrf52840`. The implementation selects that target and checks FICR PART (`0x52840`) and flash geometry (256 × 4096 bytes) before issuing the flash write command. This identifies the chip, not the commercial board or probe serial number. Configure probe selection in the trusted interface file when multiple probes exist.
+
+A supported probe, correct board-specific SWD wiring/power, permissions, and working OpenOCD configuration are operator prerequisites. Protected/debug-locked targets fail: no automatic recovery, mass erase, protection bypass, or retry is performed. Runtime uses POSIX process groups for timeout cleanup.
+
+## API
+
+```ruby
+require 'meshtastic/admin/firmware/hex'
+
+# Validation only: no subprocess or hardware access.
+metadata = Meshtastic::Admin::Firmware::Hex.validate(
+  bytes: File.binread('/absolute/path/firmware-board.hex'),
+  expected_chip: :nrf52840
+)
+
+# Destructive: run only when intentionally installing onto the selected hardware.
+result = Meshtastic::Admin::Firmware::Hex.install(
+  protocol: :swd,
+  firmware: '/absolute/path/firmware-board.hex',
+  expected_chip: :nrf52840,
+  expected_target: 'nrf52.cpu',
+  openocd: '/usr/bin/openocd',
+  interface_config: '/absolute/path/trusted-interface.cfg',
+  target_config: '/absolute/path/trusted-nrf52.cfg',
+  timeout: 120
+)
+```
+
+Use exactly one of `firmware:` (regular file) or `bytes:` (String). Input is limited to 16 MiB. `timeout` is positive finite seconds, at most 3600 (default 120). Unknown installation options are rejected. `Hex.install` does not consume a `format:` option; the parent firmware dispatcher selects `format: :hex` and forwards backend options.
+
+Validation checks every record's ASCII hexadecimal syntax, byte count and checksum; requires exactly one terminal EOF and nonempty data; rejects blank lines, trailing records, unknown types, empty data records, 64 KiB record crossings, and overlapping physical address ranges. Types 00/01/02/04 implement data, EOF, segment and linear addressing. Types 03/05 validate a single optional start address within flash; start metadata is not used to override the reset vector. Data may occupy internal flash `[0, 0x100000)` or UICR `[0x10001000, 0x10002000)` only. LF and CRLF are accepted. `validate` returns populated byte count, sorted exclusive-end address ranges and optional start address.
+
+The installer snapshots validated bytes in a private temporary HEX file. It launches OpenOCD with separate argv entries, never a shell command; paths embedded in Tcl are escaped including braces, quotes, backslashes and substitution characters. It disables normal GDB/Telnet/Tcl listener ports before loading configuration. Its guarded script executes:
+
+1. `init`, target selection, `reset init`, `halt`;
+2. FICR chip/geometry checks;
+3. `flash write_image erase <snapshot> 0 ihex`;
+4. `verify_image <snapshot> 0 ihex`;
+5. `reset run`, then a unique completion marker and `shutdown`.
+
+Any script error invokes `shutdown error`. Both successful process termination and the exact post-verification/reset marker are required. Missing/nonexecutable dependencies and failed, incomplete or timed-out subprocesses raise; uncertain flash state is never automatically retried. Temporary files are removed. Returned success is `status: :verified`, `flash_verified: true`, **`reboot_verified: false`**, with image SHA-256, image byte count, chip/target and validation metadata. Reset command completion is not evidence of a healthy Meshtastic application; perform a separate fresh PhoneAPI health/version check.
+
+## Official workflow and limits
+
+The [official Meshtastic nRF52 SWD guide](https://meshtastic.org/docs/getting-started/flashing-firmware/nrf52/swdio/) describes an external SWD probe, OpenOCD interface configuration, `transport select swd`, `target/nrf52.cfg`, HEX firmware, and erase/program/verify/reset commands. Its recovery example uses `nrf5 mass_erase`; this narrower installer deliberately **does not mass-erase**. Recovery requiring full erase remains an explicit separate operator workflow.
+
+[OpenOCD flash programming](https://openocd.org/doc/html/Flash-Programming.html) documents the reset-init, flash-write, verify-image and reset-run sequence. [OpenOCD general commands](https://openocd.org/doc/html/General-Commands.html) documents failure exit via `shutdown error`.
+
+All five `.hex` files in the official `firmware-nrf52840-2.7.26.54e0d8d.zip` [release](https://github.com/meshtastic/firmware/releases/tag/v2.7.26.54e0d8d) were validated locally, including `firmware-wio-sdk-wm1110-2.7.26.54e0d8d.merged.hex` and four RAK4631 variants. This is parser compatibility evidence, not hardware installation evidence. Tests exercise actual fake executable processes and Tcl command simulation (test dependency: `tclsh`); no development test connects to or erases hardware. No claim is made that every Meshtastic board or every historical/future HEX variant is supported.

data/documentation/admin-firmware-serial.md

@@ -47,7 +47,7 @@ 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
+- `port:` is a required dedicated serial device path, **not** `transport_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.

data/documentation/admin-firmware-uf2.md

@@ -0,0 +1,94 @@
+# UF2 mass-storage firmware submission
+
+`Meshtastic::Admin::Firmware::UF2.install(opts)` validates an original UF2 image and copies it to an **explicitly selected bootloader directory**. It does not discover drives, mount filesystems, enter bootloader mode, convert `.bin` files, erase devices, or verify installed flash. Implementation and filesystem safety are currently supported on **Linux with procfs and `O_NOFOLLOW`**; other platforms fail closed rather than use an unpinned destination path.
+
+## Prepare the device yourself
+
+The official Meshtastic workflow is to download and extract the firmware for the **exact board**, then:
+
+- **nRF52840:** double-click reset to enter the USB UF2 bootloader. The bootloader drive exposes `INFO_UF2.TXT`, usually alongside `CURRENT.UF2` and `INDEX.HTM`.
+- **RP2040:** hold BOOTSEL while attaching USB. The drive exposes `INFO_UF2.TXT` and `INDEX.HTM`.
+
+Read `INFO_UF2.TXT`, select its mounted directory yourself, and supply its exact `Board-ID`. Do not select a normal disk or copy identification files there. The marker is the UF2-standard identification mechanism, **not cryptographic device authentication or proof of an OS mount**. A directory deliberately populated with a matching marker can pass validation (including the temporary directories used by tests). Run as a normal user, and do not let untrusted users modify the selected directory.
+
+## API
+
+```ruby
+require 'meshtastic/admin/firmware/uf2'
+
+result = Meshtastic::Admin::Firmware::UF2.install(
+  protocol: :uf2,
+  firmware: '/absolute/path/firmware-for-your-board.uf2',
+  mount: '/media/operator/BOOTLOADER',
+  family_id: 0xada52840,
+  board_id: 'nRF52840-YourBoard-v1' # replace with the exact observed Board-ID
+)
+```
+
+Options:
+
+| Key | Contract |
+| --- | --- |
+| `protocol` | Required, exactly `:uf2`; no extension-based dispatch. |
+| `firmware` | Regular source file, mutually exclusive with `bytes`. Contents, not filename extension, determine validity. |
+| `bytes` | Complete original UF2 binary String, mutually exclusive with `firmware`. Snapshotted before validation/copy. |
+| `mount` | Required existing canonical absolute directory; no root directory, symlink components, `..`, automatic discovery or directory creation. |
+| `family_id` | Required Integer: `0xada52840` (nRF52840) or `0xe48bff56` (RP2040). |
+| `board_id` | Required exact case-sensitive `Board-ID` in `INFO_UF2.TXT`. nRF52840 IDs must begin with `nRF52840-` (prefix case-insensitive); RP2040 must identify as `RPI-RP2`. |
+| `flash_size` | Required **only for RP2040**, actual installed flash capacity in bytes, positive 4096-byte multiple from 4096 through 16 MiB. Check the board documentation; the generic RP2040 marker cannot report physical capacity. Rejected for nRF52840. |
+
+RP2040 example options: `family_id: 0xe48bff56, board_id: 'RPI-RP2', flash_size: 2 * 1024 * 1024` for a board actually fitted with 2 MiB flash.
+
+Unknown options are rejected. Reboot and PhoneAPI verification belong to the parent `Firmware.install` orchestration, not this backend.
+
+## Accepted format and address policy
+
+This is a deliberately narrow installer, not a universal UF2 interpreter:
+
+- Source limit: 32 MiB, nonempty and an exact multiple of 512 bytes.
+- Every block must have both start magic words and the end magic word, little-endian fields, and flags **exactly `0x2000`** (family present, main flash).
+- Every block family must match the explicitly selected supported MCU. Concatenated mixed-family UF2 files are rejected even though the general UF2 format permits them.
+- Payloads must be 256 bytes and target addresses 256-byte aligned, the supported bootloader profile (stricter than the generic UF2 format's four-byte alignment).
+- Every block count must equal the physical file block count. Block numbers must cover `0...count` exactly once. Duplicates (even identical), missing numbers, inconsistent totals and overlapping address ranges are rejected. Out-of-order blocks and address holes are allowed and copied unchanged.
+- **nRF52840:** conservative application-only address window `[0x27000, 0xf4000)`, excluding MBR/SoftDevice and bootloader/UICR space. This supports the S140-v7 application layout; old S140-v6 images beginning at `0x26000`, merged SoftDevice images and custom flash layouts are deliberately unsupported. Address validation alone cannot prove application/SoftDevice compatibility. Select the board's matching release and bootloader.
+- **RP2040:** XIP flash only, `[0x10000000, 0x10000000 + flash_size)`. RAM downloads are unsupported.
+- Non-main-flash metadata, file containers, MD5 descriptors, extension tags, reserved flags, other MCUs (including RP2350), and separately identified bootloader-update families are rejected. Raw BIN/HEX/ZIP data is never converted or reinterpreted as UF2. This API does not implement factory erase; an erase program encoded as an otherwise ordinary application image cannot be distinguished by structural checks, so only submit trusted firmware chosen for this board.
+
+The UF2 family identifies the MCU, **not the precise board/pinout**. INFO target checks cannot prove that a family-only image was built for that exact board; correct release selection remains the operator's responsibility. Structural validation and the returned local SHA-256 are not authenticity or device-flash verification.
+
+## Copy and result semantics
+
+The installer checks one case-insensitive `INFO_UF2.TXT` filename, a bounded regular nonsymlink marker, the bootloader header, an unambiguous exact Board-ID and matching MCU. It pins the selected directory with an open file descriptor and writes relative to `/proc/self/fd/<fd>` so unplugging, replacing or unmounting the selected path cannot redirect firmware into the underlying host directory.
+
+It creates only `FIRMWARE.UF2`, using exclusive creation and no symlink following. Existing files or symlinks are never overwritten. All image and target checks occur before destination creation. It writes the original UF2 bytes without padding, address relocation or reordering, flushes, calls `fsync`, and closes the file. A successful result contains:
+
+```ruby
+{
+  status: :copied, protocol: :uf2,
+  bytes: 512,                  # actual source byte count, not payload count
+  sha256: '...',               # digest of the submitted file
+  family_id: 0xada52840,
+  board_id: 'nRF52840-YourBoard-v1',
+  destination: '/media/operator/BOOTLOADER/FIRMWARE.UF2',
+  flash_verified: false,
+  reboot_verified: false
+}
+```
+
+`:copied` means host filesystem submission completed, **not that the bootloader accepted or flashed it**. UF2 mass storage has no universal flash-acknowledgment protocol. Readback of the created virtual file would not establish flash integrity, and the bootloader may disappear/reboot while the host closes or syncs the file. Any write, flush, sync or close error propagates; no disconnect is converted into success and no transfer is automatically retried. A partial file is left alone because deleting/retrying on a disappeared mount could act on the wrong filesystem or replay a partly flashed image. Inspect the device and re-enter its bootloader manually before deciding what to do next.
+
+## Verification and limitations
+
+RSpec uses actual temporary source files and bootloader directories, including symlinks/FIFOs, valid nRF52840/RP2040 images, invalid magic, truncation, flags, family/count/address errors, duplicate blocks, destination preservation and readback of the copied bytes. Mount replacement and disconnect-at-sync are injected around real filesystem operations. No USB device, physical flash, bootloader reboot, or on-device application health has been tested.
+
+```sh
+bundle exec rspec spec/lib/meshtastic/admin/firmware/uf2_spec.rb spec/conventions_spec.rb
+```
+
+## Sources
+
+- [Microsoft UF2 specification](https://github.com/microsoft/uf2/blob/master/README.md): block layout, flags, alignment, family semantics and INFO identification.
+- [Official UF2 family identifiers](https://github.com/microsoft/uf2/blob/master/utils/uf2families.json).
+- [Meshtastic drag-and-drop nRF52/RP2040 workflow](https://meshtastic.org/docs/getting-started/flashing-firmware/nrf52/drag-n-drop/).
+- [Adafruit nRF52 bootloader documentation](https://github.com/adafruit/Adafruit_nRF52_Bootloader): application start addresses, bootloader entry and separate bootloader family.
+- [Adafruit UF2 bootloader implementation](https://github.com/adafruit/Adafruit_nRF52_Bootloader/blob/master/src/usb/uf2/ghostfat.c): 256-byte payload/address checks, family dispatch and INFO fields.