meshtastic 0.0.178 → 0.0.179

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: or tcp_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.
+
+## 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)

data/documentation/protobufs.md

@@ -0,0 +1,162 @@
+# Generated protobuf types
+
+These classes and enums come from `lib/meshtastic/*_pb.rb` (Meshtastic protobufs via `grpc_tools_ruby_protoc`). They live in the `Meshtastic` namespace. Typical API:
+
+```ruby
+msg = Meshtastic::User.new(long_name: 'Node', short_name: 'N1')
+bytes = msg.to_proto
+again = Meshtastic::User.decode(bytes)
+msg.to_h
+```
+
+Enums: `Meshtastic::PortNum::TEXT_MESSAGE_APP`, `Meshtastic::PortNum.lookup(1)`, `Meshtastic::PortNum.resolve(:TEXT_MESSAGE_APP)`.
+
+A few generated **classes** are reopened with extra class methods: `Channel`, `Config`, `ModuleConfig`, `Paxcount`, `Position`, `Telemetry`. Do not name those extras `send` or `encode`.
+
+First-class wrappers for many of these types: [documentation index](README.md).
+
+## admin.proto
+
+- Messages: `AdminMessage`, `AdminMessage::InputEvent`, `AdminMessage::OTAEvent`, `LockdownAuth`, `HamParameters`, `NodeRemoteHardwarePinsResponse`, `SharedContact`, `KeyVerificationAdmin`, `SensorConfig`, `SCD4X_config`, `SEN5X_config`, `SEN6X_config`, `SCD30_config`, `SHTXX_config`, `DS248X_config`, `AS3935_config`
+- Enums: `AdminMessage::ConfigType`, `AdminMessage::ModuleConfigType`, `AdminMessage::BackupLocation`, `KeyVerificationAdmin::MessageType`, `OTAMode`
+
+See [Admin](admin.md).
+
+## apponly.proto
+
+- `ChannelSet` — [Apponly](apponly.md)
+
+## atak.proto
+
+- Messages: `TAKPacket`, `GeoChat`, `Group`, `Status`, `Contact`, `PLI`, `AircraftTrack`, `CotGeoPoint`, `DrawnShape`, `Marker`, `RangeAndBearing`, `Route`, `Route::Link`, `CasevacReport`, `ZMistEntry`, `EmergencyAlert`, `TaskRequest`, `TAKEnvironment`, `SensorFov`, `TakTalkMessage`, `TakTalkRoomData`, `Marti`, `TAKPacketV2`
+- Enums: `GeoChat::ReceiptType`, `DrawnShape::Kind`, `DrawnShape::StyleMode`, `Marker::Kind`, `Route::Method`, `Route::Direction`, `CasevacReport::Precedence`, `CasevacReport::HlzMarking`, `CasevacReport::Security`, `EmergencyAlert::Type`, `TaskRequest::Priority`, `TaskRequest::Status`, `SensorFov::SensorType`, `Team`, `MemberRole`, `CotHow`, `CotType`, `GeoPointSource`
+
+See [ATAK](atak.md).
+
+## cannedmessages.proto
+
+- `CannedMessageModuleConfig` — [Cannedmessages](cannedmessages.md)
+
+## channel.proto
+
+- `ChannelSettings`, `ModuleSettings`, `Channel`, `Channel::Role` — [Channel](channel.md)
+
+## clientonly.proto
+
+- `DeviceProfile` — [Clientonly](clientonly.md)
+
+## config.proto
+
+- `Config` and nested `DeviceConfig`, `PositionConfig`, `PowerConfig`, `NetworkConfig`, `DisplayConfig`, `LoRaConfig`, `BluetoothConfig`, `SecurityConfig`, `SessionkeyConfig` plus their enums — [Config](config.md)
+
+## connection_status.proto
+
+- `DeviceConnectionStatus`, `WifiConnectionStatus`, `EthernetConnectionStatus`, `NetworkConnectionStatus`, `BluetoothConnectionStatus`, `SerialConnectionStatus` — [ConnectionStatus](connection-status.md)
+
+## device_ui.proto
+
+- `DeviceUIConfig`, `NodeFilter`, `NodeHighlight`, `GeoPoint`, `Map`
+- Enums: `DeviceUIConfig::GpsCoordinateFormat`, `CompassMode`, `Theme`, `Language`
+
+No dedicated wrapper; set via Admin `DEVICEUI_CONFIG` / `Config.device_ui`.
+
+## deviceonly.proto / deviceonly_legacy.proto
+
+- `PositionLite`, `UserLite`, `NodeInfoLite`, `DeviceState`, `NodePositionEntry`, `NodeTelemetryEntry`, `NodeEnvironmentEntry`, `NodeStatusEntry`, `NodeDatabase`, `ChannelFile`, `BackupPreferences`
+- Legacy: `NodeInfoLite_Legacy`, `NodeDatabase_Legacy`
+
+See [Deviceonly](deviceonly.md).
+
+## interdevice.proto
+
+- `FileTransfer`, `DirectoryListing`, `I2CTransaction`, `SdCardInfo`, `I2CResult`, `InterdeviceMessage`
+- Enums: `SdCardInfo::CardType`, `SdCardInfo::FatType`, `I2CResult::Status`, `InterdeviceVersion`, `FileOperation`, `FileStatus`, `SdCommand`
+
+No dedicated wrapper. Encode/decode the generated classes directly.
+
+## localonly.proto
+
+- `LocalConfig`, `LocalModuleConfig` — [Localonly](localonly.md)
+
+## lorawan_bridge.proto
+
+- `LoRaWANBridge` plus nested `Uplink`, `Downlink`, `PayloadChunk`, `TxResult`
+
+No dedicated wrapper. Port `LORAWAN_BRIDGE` (75).
+
+## mesh_beacon.proto
+
+- `MeshBeacon` — port `MESH_BEACON_APP` (37)
+
+## mesh.proto
+
+Core radio types:
+
+- `Position` ([Position](position.md)), `User`, `RouteDiscovery` ([Traceroute](traceroute.md)), `Routing`, `Data`, `KeyVerification`, `StoreForwardPlusPlus`, `RemoteShell`, `BoundingBox`, `Waypoint`, `StatusMessage`, `MqttClientProxyMessage`, `MeshPacket`, `NodeInfo`, `MyNodeInfo`, `LogRecord`, `QueueStatus`, `FromRadio`, `LockdownStatus`, `ClientNotification`, `KeyVerificationNumberInform`, `KeyVerificationNumberRequest`, `KeyVerificationFinal`, `DuplicatedPublicKey`, `LowEntropyKey`, `FileInfo`, `ToRadio`, `Compressed`, `NeighborInfo`, `Neighbor`, `DeviceMetadata`, `LoRaPresetGroup`, `LoRaRegionPresets`, `LoRaRegionPresetMap`, `Heartbeat`, `NodeRemoteHardwarePin`, `ChunkedPayload`, `resend_chunks`, `ChunkedPayloadResponse`
+- Enums: `HardwareModel`, `Constants`, `CriticalErrorCode`, `FirmwareEdition`, `ExcludedModules`, plus nested enums on Position, Routing, MeshPacket, LogRecord, LockdownStatus, RemoteShell, StoreForwardPlusPlus
+
+Serial/TCP frames carry `ToRadio` / `FromRadio`. MQTT publishes `ServiceEnvelope` wrapping `MeshPacket`.
+
+## module_config.proto
+
+- `ModuleConfig` and nested MQTT/Serial/StoreForward/Telemetry/… configs — [ModuleConfig](module-config.md)
+- `RemoteHardwarePin`, `RemoteHardwarePinType`
+
+## mqtt.proto
+
+- `ServiceEnvelope`, `MapReport` — [MQTT](mqtt.md)
+
+## paxcount.proto
+
+- `Paxcount` — [Paxcount](paxcount.md)
+
+## portnums.proto
+
+- `PortNum` — [Portnums](portnums.md)
+
+## powermon.proto
+
+- `PowerMon`, `PowerStressMessage` (and nested enums)
+
+No dedicated wrapper. Port `POWERSTRESS_APP` (74).
+
+## remote_hardware.proto
+
+- `HardwareMessage`, `HardwareMessage::Type` — [RemoteHardware](remote-hardware.md)
+
+## rtttl.proto
+
+- `RTTTLConfig` — [RTTTL](rtttl.md)
+
+## serial_hal.proto
+
+- `SerialHalCommand`, `SerialHalResponse`
+
+GPIO serial HAL, not USB CDC. See [Serial](serial.md) for the USB Stream API.
+
+## storeforward.proto
+
+- `StoreAndForward` plus `Statistics`, `History`, `Heartbeat`, `RequestResponse` — [Storeforward](storeforward.md)
+
+## telemetry.proto
+
+- `Telemetry` ([Telemetry](telemetry.md)), `DeviceMetrics`, `EnvironmentMetrics`, `SoilWaterMetrics`, `PowerMetrics`, `AirQualityMetrics`, `LocalStats`, `TrafficManagementStats`, `HealthMetrics`, `HostMetrics`, `Nau7802Config`, `AS3935Config`, `SEN5XState`, `SEN6XState`, `TelemetrySensorType`
+
+## xmodem.proto
+
+- `XModem`, `XModem::Control` — [Xmodem](xmodem.md)
+
+## nanopb
+
+`require 'nanopb_pb'` is loaded with the gem. It is not a `Meshtastic::` module.
+
+## Example: inspect a type
+
+```ruby
+require 'meshtastic'
+
+Meshtastic::AdminMessage.descriptor.each { |f| puts f.name }
+Meshtastic::PortNum.constants.sort
+user = Meshtastic::User.new(long_name: 'Node', short_name: 'N1')
+Meshtastic::User.decode(user.to_proto)
+```

data/documentation/remote-hardware.md

@@ -0,0 +1,33 @@
+# Meshtastic::RemoteHardware
+
+GPIO control on `REMOTE_HARDWARE_APP` (port 2) using `Meshtastic::HardwareMessage`.
+
+## Methods
+
+- `encode(type:, gpio_mask:, gpio_value:)`
+- `send`
+- `read_gpios(gpio_mask:)`
+- `write_gpios(gpio_mask:, gpio_value:)`
+- `watch_gpios(gpio_mask:)`
+- `help` / `authors`
+
+`type` values: `:UNSET`, `:WRITE_GPIOS`, `:WATCH_GPIOS`, `:GPIOS_CHANGED`, `:READ_GPIOS`, `:READ_GPIOS_REPLY`.
+
+## Example
+
+```ruby
+Meshtastic::RemoteHardware.write_gpios(
+  serial_obj: serial_obj,
+  gpio_mask: 0x01,
+  gpio_value: 0x01
+)
+
+Meshtastic::RemoteHardware.read_gpios(serial_obj: serial_obj, gpio_mask: 0x01)
+Meshtastic::RemoteHardware.watch_gpios(serial_obj: serial_obj, gpio_mask: 0x01)
+```
+
+Enable the Remote Hardware module on the node and only drive pins the firmware exposes.
+
+## Related
+
+- [Meshtastic::ModuleConfig](module-config.md)

data/documentation/rtttl.md

@@ -0,0 +1,24 @@
+# Meshtastic::RTTTL
+
+Ringtone helpers. `encode` builds `RTTTLConfig`. `set` / `get` go through [Admin](admin.md) (`set_ringtone_message` / `get_ringtone_request`).
+
+## Methods
+
+- `encode(ringtone:)`
+- `set(serial_obj:, ringtone:)`
+- `get(serial_obj:)`
+- `help` / `authors`
+
+## Example
+
+```ruby
+Meshtastic::RTTTL.set(
+  serial_obj: serial_obj,
+  ringtone: 'Mario:d=4,o=5,b=125:16e6'
+)
+Meshtastic::RTTTL.get(serial_obj: serial_obj)
+```
+
+## Related
+
+- [Meshtastic::Admin](admin.md)

data/documentation/serial.md

@@ -0,0 +1,78 @@
+# Meshtastic::Serial
+
+USB/UART Stream API. Framing is `[0x94][0xC3][len_hi][len_lo]` plus a `ToRadio` / `FromRadio` protobuf.
+
+The radio applies channel crypto. Payloads go out decoded. `channel:` is the device channel index (usually `0`), not an MQTT hash.
+
+## Setup
+
+Use the 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.
+
+Do not open Serial and Bluetooth to the same radio at once.
+
+## Methods
+
+- `connect(block_dev:, baud:, data_bits:, stop_bits:, parity:, debug_out:, want_config:)`
+- `wait_for_config(serial_obj:, timeout:)` — raises `Timeout::Error` if handshake never completes
+- `wake_up_device` — writes 32 × `START2`
+- `request` — raw bytes
+- `send_to_radio` — framed `ToRadio`
+- `send_text` / `send_data`
+- `recv_from_radio(timeout:)` — `0` polls, `nil` blocks, default `5`. Closed empty queue → `nil`. Unplug → `IOError`
+- `drain_from_radio`
+- `dump_stdout_data` / `flush_data` / `monitor_stdout` (`:proto` or `:console`)
+- `subscribe` — blocking FromRadio loop
+- `disconnect`
+- `help` / `authors`
+
+`send_text` / `send_data` return bytes written, not mesh delivery. `want_ack: true` asks for `ROUTING_APP` (`error_reason: NONE` means the local radio accepted the route). Incoming text is UTF-8 under `message[:packet][:decoded][:payload]`.
+
+Call `wait_for_config` before using `my_node_num` or sending. Opening a port is not a completed handshake.
+
+## Send / receive
+
+```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)}"
+
+  Meshtastic::Serial.send_text(
+    serial_obj: serial_obj,
+    to: '!aabbccdd',       # or '!ffffffff' for the shared channel
+    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:
+
+```ruby
+from_radio = Meshtastic::Serial.recv_from_radio(serial_obj: serial_obj, timeout: 0)
+msgs = Meshtastic::Serial.drain_from_radio(serial_obj: serial_obj, max: 256)
+```
+
+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).
+
+Default `block_dev` is `/dev/ttyUSB0`, baud `115200`, 8N1.
+
+## Related
+
+- [Meshtastic::TCP](tcp.md) (same framing)
+- [Meshtastic::Bluetooth](bluetooth.md)
+- [Meshtastic::Admin](admin.md)

data/documentation/storeforward.md

@@ -0,0 +1,24 @@
+# Meshtastic::Storeforward
+
+Sends `Meshtastic::StoreAndForward` on `STORE_FORWARD_APP` (port 65).
+
+## Methods
+
+- `encode(rr:)` — request/response enum, default `:ROUTER_HEARTBEAT`
+- `send`
+- `help` / `authors`
+
+`rr` includes values such as `:CLIENT_HISTORY`, `:ROUTER_HEARTBEAT`.
+
+## Example
+
+```ruby
+Meshtastic::Storeforward.send(
+  serial_obj: serial_obj,
+  rr: :CLIENT_HISTORY
+)
+```
+
+## Related
+
+- [Meshtastic::ModuleConfig](module-config.md) (`:STOREFORWARD_CONFIG`)