meshtastic 0.0.178 → 0.0.180

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89ae445ffe5b5a92527ac776eefac452593bdd34473a325c6048d8b19d3b7d9a
-  data.tar.gz: b3173a5209a3b9efefad113218573f399bb2f62ae794c037a1f5ea9c4ba24ed7
+  metadata.gz: f12d73c0e68d9f1171a2b92d2cfe2277d22e4e78c7c33788cc52924ee6d40778
+  data.tar.gz: b0be149633c2a659dcea3ce83546f9a2ea5121f632a90bb3ee9b21a43ae79221
 SHA512:
-  metadata.gz: 2e94b436cb0340c13a372e1e11c3cb85b9f26303ed2e7d667ba754eb205e30a84383894b494904d548b4d86bcce2c8a245fd85b03fd42b4a9e9c4d64de2cc696
-  data.tar.gz: 4d784f09138ee9ecf2c9fde1503adf3974b651a82a35e5f96ed3cb64109ecd9ceae007e582ca3e3b208fb0a2e574d9e9f11a3c1c5fd584518d199cd9c14ec3b3
+  metadata.gz: a4d41dbc793a0eb380cbfb815ce9cd15ac98802e80a3903ea7ed765d09c42ff9a4009a2d68ff44338026e553f18fd7d96d4419233018185ff3f733735b033149
+  data.tar.gz: d035c8f9c42d536ad97bdefc0de870dff4694ef651c86dd1e7002ada63145f089e9e70a74d73144ebac991d0d9dd8365f5c53ae0b0b6154c466d99f849e4b34a

data/README.md

@@ -24,185 +24,13 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-The primary interaction modules today are `Meshtastic::MQTT` (broker), `Meshtastic::Serial` (USB/UART), and `Meshtastic::Bluetooth` (BLE via Linux BlueZ). Examples for each follow.
-
-### MQTT
-
-To view MQTT messages, and include only messages containing `_APP` _and_ `LongFast` strings, use the following code:
-
-```ruby
-require 'meshtastic'
-Meshtastic::MQTT.help
-mqtt_obj = Meshtastic::MQTT.connect
-puts mqtt_obj.inspect
-Meshtastic::MQTT.subscribe(
-  mqtt_obj: mqtt_obj,
-  include: '_APP, LongFast'
-)
-```
-
-This code will dump the contents of every message:
-
-```ruby
-require 'meshtastic'
-mqtt_obj = Meshtastic::MQTT.connect
-Meshtastic::MQTT.subscribe(
-  mqtt_obj: mqtt_obj,
-  root_topic: 'msh',
-  region: 'US',
-  topic: '2/e/LongFast/#',
-  psks: { LongFast: 'AQ==' }
-) do |message|
-  puts message.inspect
-end
-```
-
-Sending a message over MQTT:
-
-```ruby
-require 'meshtastic'
-mqtt_obj = Meshtastic::MQTT.connect
-client_id = "!#{mqtt_obj.client_id}"
-Meshtastic::MQTT.send_text(
-  mqtt_obj: mqtt_obj,
-  from: client_id,
-  to: '!ffffffff',
-  root_topic: 'msh',
-  region: 'US',
-  topic: '2/e/LongFast/#',
-  channel: 93,
-  text: 'Hello, World!',
-  psks: { LongFast: 'AQ==' }
-)
-```
-
-One of the "gotchas" when sending messages is ensuring you're sending over the proper integer for the `channel` parameter.  The best way to determine the proper `channel` value is by sending a test message from within the meshtastic app and then viewing the MQTT message similar to the following:
+All usage examples live under [documentation/](documentation/README.md): transports (MQTT, Serial, Bluetooth, TCP), Admin and other feature modules, internals, and generated protobuf types.
 
 ```ruby
 require 'meshtastic'
-mqtt_obj = Meshtastic::MQTT.connect
-Meshtastic::MQTT.subscribe(
-  mqtt_obj: mqtt_obj,
-  root_topic: 'msh',
-  region: 'US',
-  topic: '2/e/LongFast/#',
-  psks: { LongFast: 'AQ==' },
-  include: '!YOUR_CLIENT_ID'
-) do |message|
-  puts message.inspect
-end
-```
-
-You should see something like this:
-
+Meshtastic.help          # constants in the namespace
+Meshtastic::Serial.help  # methods for one module
 ```
-{packet: {from: 3237997296, to: 4294967295, channel: 93, id: 1, rx_time: 1735689600, rx_snr: 0.0, hop_limit: 3, want_ack: false, priority: :HIGH, rx_rssi: 0, delayed: :NO_DELAY, via_mqtt: false, hop_start: 3, public_key: "", pki_encrypted: false, next_hop: 0, relay_node: 0, tx_after: 0, decoded: {portnum: :TEXT_MESSAGE_APP, payload: "WHAT IS MY channel VALUE?", want_response: false, dest: 0, source: 0, request_id: 0, reply_id: 0, emoji: 0, bitfield: 0}, encrypted: :decrypted, topic: "msh/US/2/e/LongFast/!c0ffee00", node_id_from: "!c0ffee00", node_id_to: "!ffffffff", rx_time_utc: "2025-01-01 00:00:00 UTC"}, channel_id: "LongFast", gateway_id: "!c0ffee00"}
-```
-
-Note where is says `channel: 93`.  This is the `channel` value required to send messages in this particular example.
-
-### Serial and Bluetooth (send / receive)
-
-`Meshtastic::Serial` (USB/UART) and `Meshtastic::Bluetooth` (Linux BLE via BlueZ) talk to a local radio using the same client API. The radio encrypts with its configured channel keys. Payloads are sent decoded; `channel:` is the index on the device, not an MQTT channel hash.
-
-Do not open Serial and Bluetooth to the same radio at once. Disconnect when finished (`ensure` is the reliable pattern). `send_text` / `send_data` report bytes written, not mesh delivery. `want_ack: true` requests a `ROUTING_APP` acknowledgment (`error_reason: NONE` means the local radio accepted the route). Incoming text is a UTF-8 string under `message[:packet][:decoded][:payload]`.
-
-Call `wait_for_config` before using `my_node_num` or sending. It raises `Timeout::Error` if the firmware never completes the handshake. Opening a port or pairing is not the same as a completed handshake.
-
-#### Serial (`Meshtastic::Serial`)
-
-Use the device’s USB CDC port (`/dev/ttyACM*` or `/dev/ttyUSB*`). Enable Radio Configuration → Security → Serial Console (`security.serial_enabled`). That is not Module Configuration → Serial (`TEXTMSG` / `PROTO` on GPIO). Keep “Override Console Serial Port” off.
-
-```ruby
-require 'meshtastic'
-
-serial_obj = nil
-begin
-  serial_obj = Meshtastic::Serial.connect(block_dev: '/dev/ttyACM0', baud: 115_200)
-  Meshtastic::Serial.wait_for_config(serial_obj: serial_obj, timeout: 10)
-  puts "local node: !#{serial_obj[:my_node_num].to_s(16)}"
-
-  # Direct message, or to: '!ffffffff' for the shared channel.
-  Meshtastic::Serial.send_text(
-    serial_obj: serial_obj,
-    to: '!aabbccdd',
-    channel: 0,
-    text: 'Hello over serial!',
-    want_ack: true
-  )
-
-  Meshtastic::Serial.subscribe(
-    serial_obj: serial_obj,
-    include: 'TEXT_MESSAGE_APP'
-  ) do |message|
-    packet = message[:packet]
-    puts "#{packet[:node_id_from]}: #{packet.dig(:decoded, :payload)}"
-  end
-ensure
-  Meshtastic::Serial.disconnect(serial_obj: serial_obj)
-end
-```
-
-Drive the loop yourself with `recv_from_radio(serial_obj:, timeout:)` (`0` polls, `nil` blocks) or `drain_from_radio`. A closed empty queue returns `nil`; an unplugged device raises `IOError`. If `wait_for_config` times out, the USB path is up but the Stream API is not (wrong port, Serial Console disabled, or firmware not responding).
-
-#### Bluetooth (`Meshtastic::Bluetooth`)
-
-Linux only (BlueZ + `ruby-dbus`). Connect with a BLE address (`AA:BB:CC:DD:EE:FF`), not a mesh id (`!11223344`). Pair first; this gem does not guess a PIN. BLE writes unframed ToRadio protobufs (no UART `0x94 0xC3` header).
-
-Scan:
-
-```ruby
-require 'meshtastic'
-Meshtastic::Bluetooth.scan(adapter: 'hci0', timeout: 5)
-# => [{ address: 'AA:BB:CC:DD:EE:FF', name: 'Meshtastic_eeff', paired: true }, ...]
-```
-
-Pair while discovery is running. Screen devices typically show a random 6-digit PIN:
-
-```text
-bluetoothctl
-agent KeyboardDisplay
-default-agent
-scan on
-pair AA:BB:CC:DD:EE:FF
-trust AA:BB:CC:DD:EE:FF
-scan off
-quit
-```
-
-`Failed to pair: AuthenticationFailed` means the agent never got the PIN. `Device … not available` means scan first; the advertisement dropped.
-
-Send and receive (same options as Serial, `bluetooth_obj:` instead of `serial_obj:`):
-
-```ruby
-require 'meshtastic'
-
-bluetooth_obj = nil
-begin
-  bluetooth_obj = Meshtastic::Bluetooth.connect(address: 'AA:BB:CC:DD:EE:FF')
-  Meshtastic::Bluetooth.wait_for_config(bluetooth_obj: bluetooth_obj, timeout: 30)
-
-  Meshtastic::Bluetooth.send_text(
-    bluetooth_obj: bluetooth_obj,
-    to: '!aabbccdd',
-    channel: 0,
-    text: 'Hello over BLE!',
-    want_ack: true
-  )
-
-  Meshtastic::Bluetooth.subscribe(
-    bluetooth_obj: bluetooth_obj,
-    include: 'TEXT_MESSAGE_APP'
-  ) do |message|
-    packet = message[:packet]
-    puts "#{packet[:node_id_from]}: #{packet.dig(:decoded, :payload)}"
-  end
-ensure
-  Meshtastic::Bluetooth.disconnect(bluetooth_obj: bluetooth_obj)
-end
-```
-
-Disconnect the phone’s Meshtastic BLE session while Linux is connected. After an aborted reconnect (`le-connection-abort-by-local`), `bluetoothctl disconnect <addr>` and wait a couple of seconds before `connect` again. Config dumps over BLE can take longer than serial; 30 seconds is a reasonable `wait_for_config` timeout.
 
 ## Contributing
 

data/documentation/README.md

@@ -0,0 +1,60 @@
+# Meshtastic Ruby documentation
+
+Usage for every constant in the `Meshtastic` namespace lives here. The root [README](../README.md) is install, expectations, and contributing only.
+
+`require 'meshtastic'` then `Meshtastic.help` lists loaded constants. Each first-class API module also has `.help` and `.authors`.
+
+Examples use placeholder addresses only:
+
+- Serial port: `/dev/ttyACM0`
+- BLE: `AA:BB:CC:DD:EE:FF`
+- Mesh node: `!aabbccdd` (destination), `!11223344` (local)
+- MQTT sample node: `!c0ffee00`
+- TCP radio: `192.0.2.10`
+- Broadcast: `!ffffffff` (protocol all-nodes address)
+
+## Transports
+
+- [Meshtastic::MQTT](mqtt.md)
+- [Meshtastic::Serial](serial.md)
+- [Meshtastic::Bluetooth](bluetooth.md)
+- [Meshtastic::Bluetooth::BlueZ](bluetooth-bluez.md)
+- [Meshtastic::TCP](tcp.md)
+
+Feature modules send protobufs over Serial, Bluetooth, or TCP via `Meshtastic.deliver_data`. Pass `serial_obj:`, `bluetooth_obj:`, or `tcp_obj:`. MQTT encrypts on the host; the radio encrypts on the other three.
+
+Do not open Serial and Bluetooth to the same radio at once. Always `disconnect` in `ensure`.
+
+## Feature modules
+
+- [Meshtastic::Admin](admin.md)
+- [Meshtastic::Admin::Channel](admin-channel.md)
+- [Meshtastic::Admin::Config](admin-config.md)
+- [Meshtastic::Admin::Firmware](admin-firmware.md)
+- [Meshtastic::ModuleConfig](module-config.md)
+- [Meshtastic::Position](position.md)
+- [Meshtastic::Telemetry](telemetry.md)
+- [Meshtastic::Traceroute](traceroute.md)
+- [Meshtastic::RemoteHardware](remote-hardware.md)
+- [Meshtastic::Storeforward](storeforward.md)
+- [Meshtastic::ATAK](atak.md)
+- [Meshtastic::Paxcount](paxcount.md)
+- [Meshtastic::Cannedmessages](cannedmessages.md)
+- [Meshtastic::RTTTL](rtttl.md)
+- [Meshtastic::Portnums](portnums.md)
+- [Meshtastic::Apponly](apponly.md)
+- [Meshtastic::Clientonly](clientonly.md)
+- [Meshtastic::Deviceonly](deviceonly.md)
+- [Meshtastic::Localonly](localonly.md)
+- [Meshtastic::ConnectionStatus](connection-status.md)
+- [Meshtastic::Xmodem](xmodem.md)
+
+## Internals
+
+- [Meshtastic (top-level)](meshtastic.md)
+- [Meshtastic::MeshInterface](mesh-interface.md)
+- [Meshtastic::StreamInterface](stream-interface.md)
+- [Meshtastic::Util](util.md)
+- [Generated protobuf types](protobufs.md)
+
+Protobuf message classes that this gem reopens (`Channel`, `Config`, `Position`, `Telemetry`, `ModuleConfig`, `Paxcount`) must not define class methods named `send` or `encode` (those belong to protobuf). Use `get`/`set`, `transmit`, `build`, or `request` instead.

data/documentation/admin-channel.md

@@ -0,0 +1,33 @@
+# Meshtastic::Admin::Channel
+
+Admin get/set for mesh channels. The generated protobuf remains `Meshtastic::Channel`; this module talks to the node on `ADMIN_APP`.
+
+Roles: `:PRIMARY`, `:SECONDARY`, `:DISABLED`.
+
+## Methods
+
+- `build_settings` — `ChannelSettings` (name, psk, uplink/downlink, AEAD)
+- `build` — `Channel` (index, role, settings)
+- `get(index:)` — `get_channel_request`
+- `set` — `set_channel` with a Channel protobuf
+- `help` / `authors`
+
+Do not pass a Channel protobuf as MeshInterface `channel:` (that field is the numeric channel index). This module strips that key before send.
+
+## Example
+
+```ruby
+settings = Meshtastic::Admin::Channel.build_settings(name: 'LongFast', uplink_enabled: true)
+Meshtastic::Admin::Channel.set(
+  serial_obj: serial_obj,
+  index: 0,
+  role: :PRIMARY,
+  settings: settings
+)
+Meshtastic::Admin::Channel.get(serial_obj: serial_obj, index: 0)
+```
+
+## Related
+
+- [Meshtastic::Admin](admin.md)
+- [Meshtastic::Admin::Config](admin-config.md)

data/documentation/admin-config.md

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

data/documentation/admin-firmware.md

@@ -0,0 +1,69 @@
+# Meshtastic::Admin::Firmware
+
+Install Meshtastic firmware using the PhoneAPI / admin path (not esptool). Nested under [Admin](admin.md) because OTA is an `AdminMessage`.
+
+## What it does
+
+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.
+
+`enter_dfu` sends `enter_dfu_mode_request` (nRF52 USB UF2 / serial DFU). `reboot_ota(seconds:)` is the older `reboot_ota_seconds` field.
+
+Use a firmware file that matches the board. Interrupting a flash can brick the radio. Keep battery high.
+
+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
+
+```ruby
+Meshtastic::Admin::Firmware.install(
+  serial_obj: serial_obj,
+  firmware: 'firmware-heltec-v3-update.bin',
+  mode: :OTA_BLE
+)
+
+Meshtastic::Admin::Firmware.install(
+  tcp_obj: tcp_obj,
+  firmware: 'firmware-heltec-v3-update.bin',
+  mode: :OTA_WIFI
+)
+
+Meshtastic::Admin::Firmware.install(
+  bluetooth_obj: bluetooth_obj,
+  firmware: 'firmware-heltec-v3-update.bin',
+  mode: :OTA_BLE
+)
+```
+
+## MQTT (remote admin)
+
+Publishes one encrypted `ADMIN_APP` envelope. The node must accept remote admin. It does not push XModem over the broker.
+
+```ruby
+Meshtastic::Admin::Firmware.install(
+  mqtt_obj: mqtt_obj,
+  firmware: 'firmware-heltec-v3-update.bin',
+  mode: :OTA_WIFI,
+  to: '!aabbccdd',
+  psks: { LongFast: 'AQ==' }
+)
+```
+
+## Related
+
+- [Meshtastic::Admin](admin.md)
+- [Meshtastic::Xmodem](xmodem.md)
+- [Meshtastic::MQTT](mqtt.md)

data/documentation/admin.md

@@ -0,0 +1,55 @@
+# 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`.
+
+Responses come back as `FromRadio` packets on the same transport (`subscribe` / `recv_from_radio`).
+
+## Methods
+
+- `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`
+
+`config_type` values: `:DEVICE_CONFIG`, `:POSITION_CONFIG`, `:POWER_CONFIG`, `:NETWORK_CONFIG`, `:DISPLAY_CONFIG`, `:LORA_CONFIG`, `:BLUETOOTH_CONFIG`, `:SECURITY_CONFIG`, `:SESSIONKEY_CONFIG`, `:DEVICEUI_CONFIG`.
+
+Any other `AdminMessage` field can be passed to `send` / `encode` (for example `set_ringtone_message`, `get_module_config_request`).
+
+## Examples
+
+```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)
+```
+
+Raw field:
+
+```ruby
+Meshtastic::Admin.send(
+  serial_obj: serial_obj,
+  factory_reset_config: true
+)
+```
+
+## Related
+
+- [Meshtastic::Admin::Firmware](admin-firmware.md)
+- [Meshtastic::Channel](channel.md)
+- [Meshtastic::Config](config.md)
+- [Meshtastic::ModuleConfig](module-config.md)
+- [Meshtastic::RTTTL](rtttl.md)

data/documentation/apponly.md

@@ -0,0 +1,22 @@
+# Meshtastic::Apponly
+
+App-side channel export: `Meshtastic::ChannelSet` (from `apponly.proto`).
+
+## Methods
+
+- `encode(settings:, lora_config:)`
+- `decode(bytes)`
+- `help` / `authors`
+
+## Example
+
+```ruby
+set = Meshtastic::Apponly.encode(
+  settings: [Meshtastic::ChannelSettings.new(name: 'LongFast')]
+)
+round_trip = Meshtastic::Apponly.decode(set.to_proto)
+```
+
+## Related
+
+- [Meshtastic::Channel](channel.md)

data/documentation/atak.md

@@ -0,0 +1,110 @@
+# Meshtastic::ATAK
+
+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` / `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`
+
+`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_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,
+  callsign: 'ALPHA',
+  lat: 37.7749,
+  lon: -122.4194,
+  aircraft: Meshtastic::AircraftTrack.new(icao: 'ABC123', flight: 'N1')
+)
+
+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'))
+```
+
+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)
+- [Generated protobuf types](protobufs.md)
+- [TAK wire formats](https://meshtastic.org/docs/software/apple/developer/tak-protocol/)

data/documentation/bluetooth-bluez.md

@@ -0,0 +1,35 @@
+# Meshtastic::Bluetooth::BlueZ
+
+Linux D-Bus backend used by [Meshtastic::Bluetooth](bluetooth.md). You normally call `Meshtastic::Bluetooth.scan` / `connect` instead of this class.
+
+## Constants
+
+- `SERVICE_UUID`
+- `TORADIO_UUID`
+- `FROMRADIO_UUID`
+
+## Methods
+
+- `BlueZ.scan(adapter: 'hci0', timeout: 5)` — `StartDiscovery` then list Device1 objects on that adapter. Returns `{ address:, name:, paired: }`.
+- `#connect` — requires an already paired device; raises if not paired or `ServicesResolved` times out
+- `#read` / write ToRadio characteristic
+- `#close`
+
+Requires `ruby-dbus`. Uses the system bus. D-Bus calls are serialized on a mutex.
+
+```ruby
+require 'meshtastic'
+
+hits = Meshtastic::Bluetooth::BlueZ.scan(adapter: 'hci0', timeout: 5)
+hits.each { |d| puts "#{d[:address]} #{d[:name]} paired=#{d[:paired]}" }
+
+conn = Meshtastic::Bluetooth::BlueZ.new(address: 'AA:BB:CC:DD:EE:FF', adapter: 'hci0', timeout: 15)
+conn.connect
+conn.close
+```
+
+Pairing is outside this class (`bluetoothctl`). The module will not try PIN values.
+
+## Related
+
+- [Meshtastic::Bluetooth](bluetooth.md)