meshtastic 0.0.178 → 0.0.180

data/documentation/bluetooth.md

@@ -0,0 +1,87 @@
+# Meshtastic::Bluetooth
+
+Linux BLE client (BlueZ + `ruby-dbus`). Same send/receive API as Serial, with `bluetooth_obj:` instead of `serial_obj:`.
+
+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).
+
+Do not open Serial and Bluetooth to the same radio at once. Disconnect the phone’s Meshtastic BLE session while Linux is connected.
+
+## Methods
+
+- `scan(adapter:, timeout:)`
+- `connect(address:, adapter:, timeout:, want_config:)`
+- `wait_for_config` — 30 seconds is a reasonable BLE timeout
+- `send_text` / `send_data` / `send_to_radio`
+- `recv_from_radio` / `drain_from_radio`
+- `dump_stdout_data` / `flush_data`
+- `subscribe`
+- `disconnect`
+- `help` / `authors`
+
+## Scan
+
+```ruby
+require 'meshtastic'
+Meshtastic::Bluetooth.scan(adapter: 'hci0', timeout: 5)
+# => [{ address: 'AA:BB:CC:DD:EE:FF', name: 'Meshtastic_eeff', paired: true }, ...]
+```
+
+## Pair
+
+Pair while discovery is running. Screen devices typically show a random 6-digit PIN. Do not invent PIN values.
+
+```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 / receive
+
+```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
+```
+
+After an aborted reconnect (`le-connection-abort-by-local`), `bluetoothctl disconnect <addr>` and wait a couple of seconds before `connect` again.
+
+GATT UUIDs (see [BlueZ](bluetooth-bluez.md)):
+
+- Service `6ba1b218-15a8-461f-9fa8-5dcae273eafd`
+- ToRadio `f75c76d2-129e-4dad-a1dd-7866124401e7`
+- FromRadio `2c55e69e-4993-11ed-b878-0242ac120002`
+
+## Related
+
+- [Meshtastic::Bluetooth::BlueZ](bluetooth-bluez.md)
+- [Meshtastic::Serial](serial.md)

data/documentation/cannedmessages.md

@@ -0,0 +1,25 @@
+# Meshtastic::Cannedmessages
+
+Wraps `Meshtastic::CannedMessageModuleConfig` (`messages` is a newline-separated string).
+
+## Methods
+
+- `encode(messages:)`
+- `send` — publishes the string on `TEXT_MESSAGE_APP` (not an admin set). To store canned lines on the device, use [Admin](admin.md) `set_canned_message_module_messages` or [ModuleConfig](module-config.md).
+- `help` / `authors`
+
+## Example
+
+```ruby
+cfg = Meshtastic::Cannedmessages.encode(messages: "Yes\nNo\nMaybe")
+cfg.messages # => "Yes\nNo\nMaybe"
+
+Meshtastic::Admin.send(
+  serial_obj: serial_obj,
+  set_canned_message_module_messages: "Yes\nNo\nMaybe"
+)
+```
+
+## Related
+
+- [Meshtastic::Admin](admin.md)

data/documentation/channel.md

@@ -0,0 +1,3 @@
+# Meshtastic::Channel
+
+Generated protobuf (`index`, `settings`, `role`). Get/set on a live node is [Meshtastic::Admin::Channel](admin-channel.md).

data/documentation/clientonly.md

@@ -0,0 +1,21 @@
+# Meshtastic::Clientonly
+
+Client-side `Meshtastic::DeviceProfile` encode/decode (`clientonly.proto`).
+
+## Methods
+
+- `encode(long_name:, short_name:)`
+- `decode(bytes)`
+- `help` / `authors`
+
+## Example
+
+```ruby
+profile = Meshtastic::Clientonly.encode(long_name: 'Node', short_name: 'N1')
+profile.long_name # => "Node"
+Meshtastic::Clientonly.decode(profile.to_proto)
+```
+
+## Related
+
+- [Meshtastic::Admin](admin.md) (`set_owner`)

data/documentation/config.md

@@ -0,0 +1,3 @@
+# Meshtastic::Config
+
+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/connection-status.md

@@ -0,0 +1,22 @@
+# Meshtastic::ConnectionStatus
+
+Decodes `Meshtastic::DeviceConnectionStatus`.
+
+## Methods
+
+- `decode(bytes)`
+- `help` / `authors`
+
+## Example
+
+```ruby
+status = Meshtastic::ConnectionStatus.decode(
+  Meshtastic::DeviceConnectionStatus.new.to_proto
+)
+```
+
+Related types: `WifiConnectionStatus`, `EthernetConnectionStatus`, `NetworkConnectionStatus`, `BluetoothConnectionStatus`, `SerialConnectionStatus`.
+
+## Related
+
+- [Generated protobuf types](protobufs.md)

data/documentation/deviceonly.md

@@ -0,0 +1,22 @@
+# Meshtastic::Deviceonly
+
+Decodes device-only snapshots: `DeviceState` and `NodeDatabase`.
+
+## Methods
+
+- `decode_state(bytes)`
+- `decode_nodedb(bytes)`
+- `help` / `authors`
+
+## Example
+
+```ruby
+state = Meshtastic::Deviceonly.decode_state(Meshtastic::DeviceState.new.to_proto)
+nodedb = Meshtastic::Deviceonly.decode_nodedb(Meshtastic::NodeDatabase.new.to_proto)
+```
+
+Related types: `PositionLite`, `UserLite`, `NodeInfoLite`, `ChannelFile`, `BackupPreferences`.
+
+## Related
+
+- [Meshtastic::Localonly](localonly.md)

data/documentation/localonly.md

@@ -0,0 +1,21 @@
+# Meshtastic::Localonly
+
+Decodes `LocalConfig` and `LocalModuleConfig` (full config blobs stored on the client).
+
+## Methods
+
+- `decode_config(bytes)`
+- `decode_module_config(bytes)`
+- `help` / `authors`
+
+## Example
+
+```ruby
+Meshtastic::Localonly.decode_config(Meshtastic::LocalConfig.new.to_proto)
+Meshtastic::Localonly.decode_module_config(Meshtastic::LocalModuleConfig.new.to_proto)
+```
+
+## Related
+
+- [Meshtastic::Config](config.md)
+- [Meshtastic::ModuleConfig](module-config.md)

data/documentation/mesh-interface.md

@@ -0,0 +1,52 @@
+# Meshtastic::MeshInterface
+
+Packet builder used by Serial, Bluetooth, TCP, and MQTT. Instantiated internally; you can also call it directly to get protobuf bytes without writing a radio.
+
+## Instance methods
+
+- `initialize(debug_out:, is_connected:, is_proto:, no_nodes:)`
+- `generate_packet_id(last_packet_id:)`
+- `get_cipher_keys(psks:)` — normalize Base64 PSK hash keys
+- `gps_search(lat:, lon:)` — Geocoder reverse lookup
+- `start_config` — `ToRadio.want_config_id` bytes
+- `my_node_info`
+- `send_packet` — encrypt when `psks` present; `via: :radio` → `ToRadio`, `via: :mqtt` → `ServiceEnvelope`
+- `send_data` / `send_text`
+- `send_to_radio` / `send_to_mqtt` — serialize only
+- `decode_payload` — TEXT_MESSAGE_APP as UTF-8; other portnums as nested protobufs when known
+- `help` / `authors`
+
+On Serial/Bluetooth/TCP, transports pass `psks: nil` so the radio owns channel crypto. MQTT must pass `psks`.
+
+`send_text` refuses payloads larger than `Meshtastic::Constants::DATA_PAYLOAD_LEN`.
+
+## Example
+
+```ruby
+mesh = Meshtastic::MeshInterface.new
+bytes = mesh.start_config
+
+text_bytes = mesh.send_text(
+  from: '!11223344',
+  to: '!ffffffff',
+  channel: 0,
+  text: 'Hello',
+  via: :radio,
+  psks: nil
+)
+
+envelope = mesh.send_text(
+  from: '!c0ffee00',
+  to: '!ffffffff',
+  channel: 93,
+  text: 'Hello MQTT',
+  via: :mqtt,
+  psks: { LongFast: 'AQ==' }
+)
+```
+
+## Related
+
+- [Meshtastic::Serial](serial.md)
+- [Meshtastic::MQTT](mqtt.md)
+- [Meshtastic::Portnums](portnums.md)

data/documentation/meshtastic.md

@@ -0,0 +1,45 @@
+# Meshtastic (top-level)
+
+`require 'meshtastic'` loads protobufs, autoloads client modules, and reopens a few generated classes (`Channel`, `Config`, `ModuleConfig`, `Paxcount`, `Position`, `Telemetry`).
+
+## Constants
+
+| Name | Value | Meaning |
+| --- | --- | --- |
+| `NODELESS_WANT_CONFIG_ID` | `69420` | Config handshake id when `no_nodes` is set |
+| `START1` | `0x94` | UART/TCP frame magic |
+| `START2` | `0xC3` | UART/TCP frame magic |
+| `HEADER_LEN` | `4` | Frame header bytes |
+| `MAX_TO_FROM_RADIO_SIZE` | `512` | Max ToRadio/FromRadio body |
+| `VERSION` | gem version string | `Meshtastic::VERSION` |
+
+## Methods
+
+### `Meshtastic.help`
+
+Returns sorted constants in the namespace (not printed usage).
+
+```ruby
+require 'meshtastic'
+Meshtastic.help
+# => [:ADMIN_APP, :ATAK, :Admin, :AdminMessage, ...]
+```
+
+### `Meshtastic.deliver_data`
+
+Routes a `Meshtastic::Data` payload to a connected radio.
+
+```ruby
+Meshtastic.deliver_data(
+  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`, `tcp_obj`, or `mqtt_obj` is present.
+
+## Related
+
+- [Transports](README.md#transports)
+- [Generated protobuf types](protobufs.md)

data/documentation/module-config.md

@@ -0,0 +1,26 @@
+# Meshtastic::ModuleConfig
+
+Reopens the generated `Meshtastic::ModuleConfig` protobuf class. Get/set module configuration via [Admin](admin.md).
+
+## Methods
+
+- `get(serial_obj:, module_config_type: :MQTT_CONFIG)`
+- `set(serial_obj:, module_config:)`
+- `help` / `authors`
+
+`module_config_type` values include `:MQTT_CONFIG`, `:SERIAL_CONFIG`, `:STOREFORWARD_CONFIG`, `:TELEMETRY_CONFIG`, `:REMOTEHARDWARE_CONFIG`, `:CANNEDMSG_CONFIG`, `:AUDIO_CONFIG`, `:PAXCOUNTER_CONFIG`, `:NEIGHBORINFO_CONFIG`, `:DETECTIONSENSOR_CONFIG`, `:EXTNOTIF_CONFIG`, `:RANGETEST_CONFIG`, `:AMBIENTLIGHTING_CONFIG`, `:STATUSMESSAGE_CONFIG`, `:MESHBEACON_CONFIG`, `:TAK_CONFIG`, `:TRAFFICMANAGEMENT_CONFIG`.
+
+## Example
+
+```ruby
+Meshtastic::ModuleConfig.get(serial_obj: serial_obj, module_config_type: :MQTT_CONFIG)
+
+mod = Meshtastic::ModuleConfig.new
+mod.mqtt = Meshtastic::ModuleConfig::MQTTConfig.new(enabled: true, address: 'mqtt.example.test')
+Meshtastic::ModuleConfig.set(serial_obj: serial_obj, module_config: mod)
+```
+
+## Related
+
+- [Meshtastic::Admin](admin.md)
+- [Meshtastic::Config](config.md)

data/documentation/mqtt.md

@@ -0,0 +1,101 @@
+# Meshtastic::MQTT
+
+Broker client. The host encrypts and decrypts with channel PSKs. Default public broker is `mqtt.meshtastic.org` (port 1883, user `meshdev`).
+
+`channel:` on MQTT is the integer hash seen in envelopes, not the radio channel index (that is Serial/Bluetooth/TCP).
+
+## Methods
+
+- `connect` — returns an `MQTT::Client`
+- `subscribe` — blocking loop; yields a hash per envelope, or pretty-prints without a block. Disconnects on exit.
+- `send_text` — publishes a `ServiceEnvelope` (raises if text exceeds `Meshtastic::Constants::DATA_PAYLOAD_LEN`)
+- `disconnect`
+- `help` / `authors`
+
+### `connect`
+
+```ruby
+mqtt_obj = Meshtastic::MQTT.connect(
+  host: 'mqtt.meshtastic.org',
+  port: 1883,
+  tls: false,
+  username: 'meshdev',
+  password: 'large4cats',
+  client_id: nil,          # default: random 4-byte hex
+  keep_alive: 15,
+  ack_timeout: 30
+)
+```
+
+### `subscribe`
+
+```ruby
+Meshtastic::MQTT.subscribe(
+  mqtt_obj: mqtt_obj,
+  root_topic: 'msh',
+  region: 'US',
+  topic: '2/e/LongFast/#',
+  psks: { LongFast: 'AQ==' },
+  qos: 0,
+  exclude: nil,            # comma-delimited substrings to hide
+  include: nil,            # all listed substrings must appear
+  gps_metadata: false,
+  include_raw: false
+) do |message|
+  puts message.inspect
+end
+```
+
+`include: '_APP, LongFast'` keeps only messages whose flattened inspect contains both strings.
+
+### `send_text`
+
+```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==' }
+)
+```
+
+Default `channel` is `6`. The value that actually works is the integer in a received envelope for that mesh channel. Subscribe with `include: '!YOUR_CLIENT_ID'` while sending a test message from the official app:
+
+```ruby
+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: '!c0ffee00'
+) do |message|
+  puts message.inspect
+end
+```
+
+Example envelope (placeholders):
+
+```
+{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"}
+```
+
+Use `channel: 93` from that dump when publishing.
+
+`AQ==` is expanded to the well-known LongFast PSK. Pass a Base64 channel key for private channels.
+
+## Related
+
+- [Meshtastic::MeshInterface](mesh-interface.md) (`via: :mqtt`)
+- [Meshtastic::Portnums](portnums.md)
+- Protobuf: `ServiceEnvelope`, `MapReport` in [protobufs.md](protobufs.md)

data/documentation/paxcount.md

@@ -0,0 +1,25 @@
+# Meshtastic::Paxcount
+
+Reopens the generated `Meshtastic::Paxcount` protobuf class. Transmits `PAXCOUNTER_APP` (port 34).
+
+Use `build` / `transmit`, not `send` / `encode`.
+
+## Methods
+
+- `build(wifi:, ble:, uptime:)`
+- `transmit`
+- `help` / `authors`
+
+## Example
+
+```ruby
+Meshtastic::Paxcount.transmit(
+  serial_obj: serial_obj,
+  wifi: 3,
+  ble: 2
+)
+```
+
+## Related
+
+- [Meshtastic::Telemetry](telemetry.md)

data/documentation/portnums.md

@@ -0,0 +1,67 @@
+# Meshtastic::Portnums
+
+Looks up `Meshtastic::PortNum` names and numbers.
+
+## Methods
+
+- `lookup(name_or_number)` — symbol → integer, integer → symbol
+- `help` / `authors`
+
+The enum itself is `Meshtastic::PortNum` (`lookup` / `resolve` / constants).
+
+## Example
+
+```ruby
+Meshtastic::Portnums.lookup(:TEXT_MESSAGE_APP) # => 1
+Meshtastic::Portnums.lookup(1)                 # => :TEXT_MESSAGE_APP
+Meshtastic::PortNum::ADMIN_APP                 # => 6
+```
+
+| Name | Value |
+| --- | --- |
+| UNKNOWN_APP | 0 |
+| TEXT_MESSAGE_APP | 1 |
+| REMOTE_HARDWARE_APP | 2 |
+| POSITION_APP | 3 |
+| NODEINFO_APP | 4 |
+| ROUTING_APP | 5 |
+| ADMIN_APP | 6 |
+| TEXT_MESSAGE_COMPRESSED_APP | 7 |
+| WAYPOINT_APP | 8 |
+| AUDIO_APP | 9 |
+| DETECTION_SENSOR_APP | 10 |
+| ALERT_APP | 11 |
+| KEY_VERIFICATION_APP | 12 |
+| REMOTE_SHELL_APP | 13 |
+| REPLY_APP | 32 |
+| IP_TUNNEL_APP | 33 |
+| PAXCOUNTER_APP | 34 |
+| STORE_FORWARD_PLUSPLUS_APP | 35 |
+| NODE_STATUS_APP | 36 |
+| MESH_BEACON_APP | 37 |
+| PAGING_APP | 38 |
+| SERIAL_APP | 64 |
+| STORE_FORWARD_APP | 65 |
+| RANGE_TEST_APP | 66 |
+| TELEMETRY_APP | 67 |
+| ZPS_APP | 68 |
+| SIMULATOR_APP | 69 |
+| TRACEROUTE_APP | 70 |
+| NEIGHBORINFO_APP | 71 |
+| ATAK_PLUGIN | 72 |
+| MAP_REPORT_APP | 73 |
+| POWERSTRESS_APP | 74 |
+| LORAWAN_BRIDGE | 75 |
+| RETICULUM_TUNNEL_APP | 76 |
+| CAYENNE_APP | 77 |
+| ATAK_PLUGIN_V2 | 78 |
+| LORA_OTA_APP | 79 |
+| GROUPALARM_APP | 112 |
+| PRIVATE_APP | 256 |
+| ATAK_FORWARDER | 257 |
+| MAX | 511 |
+
+## Related
+
+- [Meshtastic::MeshInterface](mesh-interface.md)
+- [Generated protobuf types](protobufs.md)

data/documentation/position.md

@@ -0,0 +1,34 @@
+# Meshtastic::Position
+
+Reopens the generated `Meshtastic::Position` protobuf class. Sends `POSITION_APP` (port 3). Latitude/longitude are scaled by 1e7.
+
+Do not define class methods named `send` or `encode` on this class. Use `transmit` and `build`.
+
+## Methods
+
+- `build(lat:, lon:, altitude:, time:)`
+- `transmit` — deliver `POSITION_APP`
+- `help` / `authors`
+
+## Example
+
+```ruby
+Meshtastic::Position.transmit(
+  serial_obj: serial_obj,
+  lat: 37.7749,
+  lon: -122.4194,
+  altitude: 10
+)
+
+pos = Meshtastic::Position.build(lat: 37.7749, lon: -122.4194)
+# pos.latitude_i == 377749000
+```
+
+Same kwargs as other radio sends: `to:`, `channel:`, `want_ack:`, plus `bluetooth_obj:` / `tcp_obj:`.
+
+Protobuf fields also include `location_source`, `ground_speed`, `sats_in_view`, `precision_bits`, and related GPS metadata. See [protobufs.md](protobufs.md).
+
+## Related
+
+- [Meshtastic::Telemetry](telemetry.md)
+- [Meshtastic::MeshInterface](mesh-interface.md)