meshtastic 0.0.179 → 0.0.181

data/documentation/admin.md

@@ -1,54 +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`, or `tcp_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::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/atak.md

@@ -1,27 +1,110 @@
 # Meshtastic::ATAK
 
-Encodes `Meshtastic::TAKPacket` and sends it on `ATAK_PLUGIN` (port 72).
+TAK / ATAK over Meshtastic. Three wire formats, same as the official clients:
+
+| Format | Port | Payload |
+| --- | --- | --- |
+| V1 `ATAK_PLUGIN` | 72 | Bare `TAKPacket` (PLI, GeoChat, optional `detail` bytes) |
+| V2 `ATAK_PLUGIN_V2` | 78 | `[flags][TAKPacketV2]`. This gem emits uncompressed frames (`flags=0xFF`) |
+| V1 `ATAK_FORWARDER` | 257 | zlib-compressed CoT XML (single packet, max `DATA_PAYLOAD_LEN`) |
+
+V2 typed payloads: GeoChat, aircraft, shapes, markers, range-and-bearing, routes, CASEVAC, emergency, task, TAKTALK, raw detail. Contact / group / status on V1; callsign / team / role / lat-lon on V2.
+
+Firmware ≥ 2.8.0 speaks V2. Older radios use V1 PLI/chat, and generic CoT on the forwarder port.
+
+Compressed V2 (zstd dictionary id 0 or 1) is not unpacked here; `decode_v2` raises unless `flags=0xFF`.
 
 ## Methods
 
-- `encode(is_compressed:, chat:, message:)` — `message:` builds a `GeoChat`
-- `send`
+- `encode` / `encode_v1` — `TAKPacket`
+- `send` / `send_v1` / `send_chat` / `send_pli` — port 72
+- `build_v2` / `encode_v2` / `wrap_v2` / `decode_v2` / `send_v2` — port 78
+- `compress_cot` / `decompress_cot` / `send_cot` — port 257 (`cot:` XML string)
+- `decode(payload:, portnum:)` — dispatches on port
 - `help` / `authors`
 
-## Example
+`lat` / `lon` are decimal degrees (stored × 1e7). Pass a connected `serial_obj`, `bluetooth_obj`, or `tcp_obj`.
+
+## V1 GeoChat and PLI
 
 ```ruby
-Meshtastic::ATAK.send(
+Meshtastic::ATAK.send_chat(
+  serial_obj: serial_obj,
+  message: 'ATAK chat',
+  to: 'ANDROID-aabbccdd',
+  callsign: 'ALPHA',
+  device_callsign: 'RADIO-1',
+  team: :Cyan,
+  role: :TeamMember,
+  battery: 87
+)
+
+Meshtastic::ATAK.send_pli(
+  serial_obj: serial_obj,
+  lat: 37.7749,
+  lon: -122.4194,
+  altitude: 10,
+  speed: 0,
+  course: 90,
+  callsign: 'ALPHA',
+  team: :Cyan
+)
+```
+
+## V2 typed events
+
+```ruby
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, message: 'v2 chat', callsign: 'ALPHA')
+
+Meshtastic::ATAK.send_v2(
   serial_obj: serial_obj,
-  message: 'ATAK chat'
+  callsign: 'ALPHA',
+  lat: 37.7749,
+  lon: -122.4194,
+  aircraft: Meshtastic::AircraftTrack.new(icao: 'ABC123', flight: 'N1')
 )
 
-packet = Meshtastic::ATAK.encode(message: 'ATAK chat')
-packet.chat.message # => "ATAK chat"
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, shape: Meshtastic::DrawnShape.new(kind: :Kind_Circle, major_cm: 1000))
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, marker: Meshtastic::Marker.new(kind: :Kind_Spot))
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, route: Meshtastic::Route.new(prefix: 'R1'))
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, casevac: Meshtastic::CasevacReport.new(title: 'CASEVAC'))
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, emergency: Meshtastic::EmergencyAlert.new(type: :Type_Alert911))
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, task: Meshtastic::TaskRequest.new(task_type: 'recon'))
+Meshtastic::ATAK.send_v2(serial_obj: serial_obj, taktalk: Meshtastic::TakTalkMessage.new(text: 'hi', chatroom_id: 'room1'))
 ```
 
-Related protobufs: `TAKPacket`, `GeoChat`, `Contact`, `Group`, `PLI`, `TAKPacketV2`. See [protobufs.md](protobufs.md).
+Receive V2:
+
+```ruby
+Meshtastic::Serial.subscribe(serial_obj: serial_obj, include: 'ATAK_PLUGIN') do |message|
+  port = message.dig(:packet, :decoded, :portnum)
+  payload = message.dig(:packet, :decoded, :payload)
+  decoded = Meshtastic::ATAK.decode(payload: payload, portnum: port)
+  p decoded
+end
+```
+
+## Generic CoT (forwarder)
+
+```ruby
+Meshtastic::ATAK.send_cot(
+  serial_obj: serial_obj,
+  cot: '<event type="b-m-p-s-m" uid="marker-1"><point lat="37.77" lon="-122.41"/></event>'
+)
+```
+
+Raises if zlib output exceeds `Meshtastic::Constants::DATA_PAYLOAD_LEN`. Multi-packet fountain (FTN) is not implemented; keep CoT small or use V2 typed payloads.
+
+## Radio TAK module
+
+Device role `TAK` / `TAK_TRACKER` and Module Config → TAK (`team` / `role`) are [Admin](admin.md) / [ModuleConfig](module-config.md), not this client:
+
+```ruby
+Meshtastic::ModuleConfig.get(serial_obj: serial_obj, module_config_type: :TAK_CONFIG)
+```
 
 ## Related
 
-- [Meshtastic::ModuleConfig](module-config.md) (`:TAK_CONFIG`)
+- [Meshtastic::ModuleConfig](module-config.md)
+- [Generated protobuf types](protobufs.md)
+- [TAK wire formats](https://meshtastic.org/docs/software/apple/developer/tak-protocol/)

data/documentation/channel.md

@@ -1,30 +1,3 @@
 # Meshtastic::Channel
 
-Reopens the generated `Meshtastic::Channel` protobuf class with get/set helpers that call [Admin](admin.md).
-
-This is a protobuf class, not a Ruby module. Do not add class methods named `send` or `encode`.
-
-## Methods
-
-- `get(serial_obj:, index:)` — `get_channel_request`
-- `set(serial_obj:, channel:)` — `set_channel`
-- `help` / `authors`
-
-Also all protobuf instance fields: `index`, `settings` (`ChannelSettings`), `role` (`:DISABLED`, `:PRIMARY`, `:SECONDARY`).
-
-## Example
-
-```ruby
-Meshtastic::Channel.get(serial_obj: serial_obj, index: 0)
-
-settings = Meshtastic::ChannelSettings.new(name: 'LongFast', psk: "\x01")
-channel = Meshtastic::Channel.new(index: 0, settings: settings, role: :PRIMARY)
-Meshtastic::Channel.set(serial_obj: serial_obj, channel: channel)
-```
-
-Listen for `ADMIN_APP` replies on the same transport.
-
-## Related
-
-- [Meshtastic::Admin](admin.md)
-- [Meshtastic::Apponly](apponly.md) (`ChannelSet`)
+Generated protobuf (`index`, `settings`, `role`). Get/set on a live node is [Meshtastic::Admin::Channel](admin-channel.md).

data/documentation/config.md

@@ -1,29 +1,3 @@
 # Meshtastic::Config
 
-Reopens the generated `Meshtastic::Config` protobuf class. Get/set go through [Admin](admin.md).
-
-## Methods
-
-- `get(serial_obj:, config_type: :DEVICE_CONFIG)`
-- `set(serial_obj:, config:)` — `config` is a `Meshtastic::Config`
-- `help` / `authors`
-
-Protobuf oneofs include `device`, `position`, `power`, `network`, `display`, `lora`, `bluetooth`, `security`, `sessionkey`, `device_ui`.
-
-## Example
-
-```ruby
-Meshtastic::Config.get(serial_obj: serial_obj, config_type: :LORA_CONFIG)
-
-config = Meshtastic::Config.new
-config.device = Meshtastic::Config::DeviceConfig.new(role: :CLIENT)
-Meshtastic::Config.set(serial_obj: serial_obj, config: config)
-```
-
-`config_type` list: [Admin](admin.md).
-
-## Related
-
-- [Meshtastic::Admin](admin.md)
-- [Meshtastic::ModuleConfig](module-config.md)
-- [Meshtastic::Localonly](localonly.md)
+Generated protobuf (device, position, power, network, display, lora, bluetooth, security, sessionkey, device_ui). Get/set on a live node is [Meshtastic::Admin::Config](admin-config.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/documentation/meshtastic.md

@@ -31,13 +31,13 @@ Routes a `Meshtastic::Data` payload to a connected radio.
 
 ```ruby
 Meshtastic.deliver_data(
-  serial_obj: serial_obj,   # or bluetooth_obj: or tcp_obj:
+  serial_obj: serial_obj,   # or bluetooth_obj: / tcp_obj: / mqtt_obj:
   data: Meshtastic::Data.new(portnum: :TEXT_MESSAGE_APP, payload: 'hi'),
   port_num: Meshtastic::PortNum::TEXT_MESSAGE_APP
 )
 ```
 
-Raises `ArgumentError` unless `data` is a `Meshtastic::Data` and one of `serial_obj`, `bluetooth_obj`, or `tcp_obj` is present.
+Raises `ArgumentError` unless `data` is a `Meshtastic::Data` and one of `serial_obj`, `bluetooth_obj`, `tcp_obj`, or `mqtt_obj` is present.
 
 ## Related
 

data/lib/meshtastic/admin/channel.rb

@@ -0,0 +1,164 @@
+# 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 = {})
+        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.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]
+        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
+
+      public_class_method def self.get(opts = {})
+        index = opts[:index]
+        index = 0 if index.nil?
+        Admin.get_channel(opts.merge(index: index))
+      end
+
+      public_class_method def self.set(opts = {})
+        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
+
+      public_class_method def self.help
+        puts "USAGE:
+          # Build ChannelSettings for a mesh channel.
+          #{self}.build_settings(
+            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 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 copied before overlay',
+            index: 'optional - integer channel slot zero through seven',
+            role: 'optional - :PRIMARY, :SECONDARY, or :DISABLED',
+            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 - zero-based channel slot; Admin adds one on wire (default: 0)'
+          )
+
+          # Write a channel slot on the node.
+          #{self}.set(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
+            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 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.
+          #{self}.authors
+        "
+      end
+    end
+  end
+end