meshtastic 0.0.169 → 0.0.171

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f7b8b0a9e3ef3d3830a06af9e4115b2a86e82ab0051a355601631622893cf5
-  data.tar.gz: c25b3a7ca577b8ab7477b15b2f16bc9ed502578741be845580cb773db4fa50aa
+  metadata.gz: 9c5cf87c010662bcc98b9738bc6e1a4692bc67ba03e9f9c92b57b31b8b9211c2
+  data.tar.gz: f35c8128b63a7152fbfc31aeeb1814a2b66637ab9d5c049d045f6eaea46456ac
 SHA512:
-  metadata.gz: 5339975316659ee89aca979cea79b9d79e61ead161bfdbd7b6a2c0bdbe9eb136469bedbf4e3c2a5c50d1bdb58bc0d4f309c3019bbc9ace9cfe5d811b6af9c5e3
-  data.tar.gz: acb50a768aee9d2a3f4a7c3e868d8b509a4ea5c447356dffd25e8f9a3c283a5211af412ab94a523c71e62e555c5b6752b3e0f4728dbc21da62111b71a67607ad
+  metadata.gz: bc536784d826a5be06cc4c2385e0573d0b8f67a5ddb4ce2edb2c6a90c1cfca366ff68fe03436360adda292247575a02fdef2a29b99b2e4f6c272a101b77f2183
+  data.tar.gz: 10c01895bf08c5a026bff5b465e0ab57d47d2a470bfeca990485eb61a6b66e1aaaccae66b329b21336523902413391ee0927c471f8b137eaeb96d406ecf32646

data/README.md

@@ -24,12 +24,16 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-At the moment the only module available is `Meshtastic::MQTT`.  To view MQTT messages, and include only messages containing `_APP` _and_ `LongFast` strings, use the following code:
+The primary interaction modules today are `Meshtastic::MQTT` (broker) and `Meshtastic::SerialInterface` (USB/UART). 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 = Meshastic::MQTT.connect
+mqtt_obj = Meshtastic::MQTT.connect
 puts mqtt_obj.inspect
 Meshtastic::MQTT.subscribe(
   mqtt_obj: mqtt_obj,
@@ -41,7 +45,7 @@ This code will dump the contents of every message:
 
 ```ruby
 require 'meshtastic'
-mqtt_obj = Meshastic::MQTT.connect
+mqtt_obj = Meshtastic::MQTT.connect
 Meshtastic::MQTT.subscribe(
   mqtt_obj: mqtt_obj,
   root_topic: 'msh',
@@ -57,7 +61,7 @@ Sending a message over MQTT:
 
 ```ruby
 require 'meshtastic'
-mqtt_obj = Meshastic::MQTT.connect
+mqtt_obj = Meshtastic::MQTT.connect
 client_id = "!#{mqtt_obj.client_id}"
 Meshtastic::MQTT.send_text(
   mqtt_obj: mqtt_obj,
@@ -76,7 +80,7 @@ One of the "gotchas" when sending messages is ensuring you're sending over the p
 
 ```ruby
 require 'meshtastic'
-mqtt_obj = Meshastic::MQTT.connect
+mqtt_obj = Meshtastic::MQTT.connect
 Meshtastic::MQTT.subscribe(
   mqtt_obj: mqtt_obj,
   root_topic: 'msh',
@@ -97,6 +101,112 @@ You should see something like this:
 
 Note where is says `channel: 93`.  This is the `channel` value required to send messages in this particular example.
 
+### Serial Interface
+
+Talk directly to a Meshtastic node over USB/UART (`/dev/ttyUSB*`, `/dev/ttyACM*`). Unlike MQTT, the radio owns channel crypto for serial: payloads are sent *decoded* and the device encrypts with its configured channel key.
+
+To inspect available methods and open a serial session:
+
+```ruby
+require 'meshtastic'
+Meshtastic::SerialInterface.help
+serial_obj = Meshtastic::SerialInterface.connect(
+  block_dev: '/dev/ttyUSB0', # or /dev/ttyACM0
+  baud: 115_200
+)
+puts serial_obj.inspect
+```
+
+This code will dump every FromRadio packet (blocks until CTRL+C):
+
+```ruby
+require 'meshtastic'
+serial_obj = Meshtastic::SerialInterface.connect(
+  block_dev: '/dev/ttyUSB0',
+  baud: 115_200
+)
+Meshtastic::SerialInterface.subscribe(
+  serial_obj: serial_obj
+) do |message|
+  puts message.inspect
+end
+```
+
+Filter with `include` / `exclude` (comma-delimited substrings), same idea as MQTT:
+
+```ruby
+require 'meshtastic'
+serial_obj = Meshtastic::SerialInterface.connect(block_dev: '/dev/ttyUSB0')
+Meshtastic::SerialInterface.subscribe(
+  serial_obj: serial_obj,
+  include: 'TEXT_MESSAGE_APP',
+  exclude: 'TELEMETRY_APP'
+) do |message|
+  puts message.inspect
+end
+```
+
+Sending a message over serial:
+
+```ruby
+require 'meshtastic'
+serial_obj = Meshtastic::SerialInterface.connect(
+  block_dev: '/dev/ttyUSB0',
+  baud: 115_200
+)
+Meshtastic::SerialInterface.send_text(
+  serial_obj: serial_obj,
+  to: '!ffffffff',   # broadcast; or a node id like '!f33ddad5'
+  channel: 0,        # primary channel index on the radio
+  text: 'Hello over serial!'
+)
+Meshtastic::SerialInterface.disconnect(serial_obj: serial_obj)
+```
+
+A typical end-to-end send + receive session looks like this (connect once, send, then subscribe):
+
+```ruby
+require 'meshtastic'
+
+serial_obj = Meshtastic::SerialInterface.connect(
+  block_dev: '/dev/ttyUSB0',
+  baud: 115_200
+)
+
+# Optional: give the device a moment to finish want_config / my_info
+sleep 2
+puts "local node: !#{serial_obj[:my_node_num].to_s(16)}" if serial_obj[:my_node_num]
+
+Meshtastic::SerialInterface.send_text(
+  serial_obj: serial_obj,
+  to: '!ffffffff',
+  channel: 0,
+  text: 'Hello over serial!'
+)
+
+# Blocks; CTRL+C disconnects cleanly
+Meshtastic::SerialInterface.subscribe(serial_obj: serial_obj) do |message|
+  puts message.inspect
+end
+```
+
+Non-blocking receive helpers (useful when you drive the loop yourself):
+
+```ruby
+# Pop one framed FromRadio (or nil on timeout)
+fr = Meshtastic::SerialInterface.recv_from_radio(timeout: 2)
+puts fr&.to_h
+
+# Drain whatever is already queued
+Meshtastic::SerialInterface.drain_from_radio.each { |fr| puts fr.to_h }
+
+# Debug console / proto dumps collected by the RX thread
+puts Meshtastic::SerialInterface.dump_stdout_data(type: :console)
+puts Meshtastic::SerialInterface.dump_stdout_data(type: :proto).size
+```
+
+> **Note:** Serial path leaves mesh packets *decoded* and lets the radio encrypt with its configured channel key. The MQTT path still pre-encrypts with the PSK you supply via `psks:`. Channel index (`channel:`) on serial is the index configured on the *device*, not the MQTT channel hash.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/0dayinc/meshtastic. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/0dayinc/meshtastic/blob/master/CODE_OF_CONDUCT.md).

data/README.md.bak.20260709105815

@@ -0,0 +1,152 @@
+# Meshtastic
+
+Ruby gem for interfacing with Meshtastic nodes / network.
+
+# Setting Expectations
+
+This gem was created to support alt-comm capabilities w/in a security research framework known as [PWN](https://github.com/0dayInc/pwn).  Contributors of this effort cannot guarantee full functionality or support for all Meshtastic features.
+
+# Objectives
+
+- Consume the latest [Meshtastic Protobof Specs](https://github.com/meshtastic/protobufs) and [auto-generate Ruby protobuf modules for Meshtastic](https://github.com/0dayInc/meshtastic/blob/master/AUTOGEN_meshtastic_protobufs.sh) using the `grpc_tools_ruby_protoc` command: `Complete`
+- Integrate auto-generated Ruby protobuf modules into a working Ruby gem: `Complete`
+- Scale out Meshtastic Ruby Modules for their respective protobufs within the meshtastic gem (e.g. Meshtastic::MQTTPB is auto-generated based on latest Meshtastic protobuf specs and extended via Meshtastic::MQTT for more MQTT interaction as desired): `Ongoing Effort`
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add meshtastic
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install meshtastic
+
+## Usage
+
+At the moment the only module available is `Meshtastic::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 = Meshastic::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 = Meshastic::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 = Meshastic::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:
+
+```ruby
+require 'meshtastic'
+mqtt_obj = Meshastic::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:
+
+```
+{packet: {from: 4080917205, to: 4294967295, channel: 93, id: 1198634591, rx_time: 1738614021, 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/!f33ddad5", node_id_from: "!f33ddad5", node_id_to: "!ffffffff", rx_time_utc: "2025-01-01 07:00:00 UTC"}, channel_id: "LongFast", gateway_id: "!f33ddad5"}
+```
+
+Note where is says `channel: 93`.  This is the `channel` value required to send messages in this particular example.
+
+
+## Serial Interface
+
+Talk directly to a Meshtastic node over USB/UART (`/dev/ttyUSB*`, `/dev/ttyACM*`).
+
+```ruby
+require 'meshtastic'
+
+serial_obj = Meshtastic::SerialInterface.connect(
+  block_dev: '/dev/ttyUSB0', # or /dev/ttyACM0
+  baud: 115_200
+)
+
+# Send a text message (device applies channel PSK)
+Meshtastic::SerialInterface.send_text(
+  serial_obj: serial_obj,
+  to: '!ffffffff',
+  channel: 0,
+  text: 'Hello over serial!'
+)
+
+# Subscribe to FromRadio packets (blocks; CTRL+C to stop)
+Meshtastic::SerialInterface.subscribe(serial_obj: serial_obj) do |msg|
+  puts msg.inspect
+end
+
+Meshtastic::SerialInterface.disconnect(serial_obj: serial_obj)
+```
+
+Non-blocking helpers:
+
+```ruby
+# Pop one framed FromRadio (or nil on timeout)
+fr = Meshtastic::SerialInterface.recv_from_radio(timeout: 2)
+puts fr&.to_h
+
+# Drain whatever is already queued
+Meshtastic::SerialInterface.drain_from_radio.each { |fr| puts fr.to_h }
+
+# Debug console / proto dumps collected by the RX thread
+puts Meshtastic::SerialInterface.dump_stdout_data(type: :console)
+puts Meshtastic::SerialInterface.dump_stdout_data(type: :proto).size
+```
+
+> **Note:** Serial path leaves mesh packets *decoded* and lets the radio encrypt with its configured channel key. The MQTT path still pre-encrypts with the PSK you supply.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/0dayinc/meshtastic. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/0dayinc/meshtastic/blob/master/CODE_OF_CONDUCT.md).
+
+## Code of Conduct
+
+Everyone interacting in the Meshtastic project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/0dayinc/meshtastic/blob/master/CODE_OF_CONDUCT.md).

data/lib/meshtastic/mesh_interface.rb

@@ -213,10 +213,16 @@ module Meshtastic
       hop_limit = opts[:hop_limit] ||= 3
 
       public_psk = '1PG7OiApB1nwvP+rz05pAQ=='
-      psks = opts[:psks] ||= { LongFast: public_psk }
-      raise 'ERROR: psks parameter must be a hash of :channel => psk key value pairs' unless psks.is_a?(Hash)
+      # Explicit nil means "do not encrypt" (serial/radio path — device owns PSK).
+      if opts.key?(:psks) && opts[:psks].nil?
+        psks = nil
+      else
+        psks = opts[:psks] || { LongFast: public_psk }
+        raise 'ERROR: psks parameter must be a hash of :channel => psk key value pairs' unless psks.is_a?(Hash)
 
-      psks[:LongFast] = public_psk if psks[:LongFast] == 'AQ=='
+        psks = psks.dup
+        psks[:LongFast] = public_psk if psks[:LongFast] == 'AQ=='
+      end
 
       # my_info = Meshtastic::FromRadio.my_info
       # wait_connected if to != my_info.my_node_num && my_info.is_a(Meshtastic::Deviceonly::MyInfo)
@@ -228,7 +234,10 @@ module Meshtastic
       mesh_packet.hop_limit = hop_limit
       mesh_packet.id = generate_packet_id(last_packet_id: last_packet_id)
 
-      if psks
+      # When psks is nil/empty, leave the packet decoded so the radio (serial/TCP)
+      # device can apply the channel PSK itself. MQTT callers must pass psks so the
+      # ServiceEnvelope payload is pre-encrypted for the mesh.
+      if psks && !psks.empty?
         nonce_packet_id = [mesh_packet.id].pack('V').ljust(8, "\x00")
         nonce_from_node = [from].pack('V').ljust(8, "\x00")
         nonce = "#{nonce_packet_id}#{nonce_from_node}"
@@ -305,10 +314,15 @@ module Meshtastic
       raise "ERROR: Invalid port_num" unless port_num.positive? && port_num < max_port_num
 
       public_psk =  '1PG7OiApB1nwvP+rz05pAQ=='
-      psks = opts[:psks] ||= { LongFast: public_psk }
-      raise 'ERROR: psks parameter must be a hash of :channel => psk key value pairs' unless psks.is_a?(Hash)
+      if opts.key?(:psks) && opts[:psks].nil?
+        psks = nil
+      else
+        psks = opts[:psks] || { LongFast: public_psk }
+        raise 'ERROR: psks parameter must be a hash of :channel => psk key value pairs' unless psks.is_a?(Hash)
 
-      psks[:LongFast] = public_psk if psks[:LongFast] == 'AQ=='
+        psks = psks.dup
+        psks[:LongFast] = public_psk if psks[:LongFast] == 'AQ=='
+      end
 
       data_len = data.payload.length
       max_len = Meshtastic::Constants::DATA_PAYLOAD_LEN
@@ -369,10 +383,15 @@ module Meshtastic
       on_response = opts[:on_response]
 
       public_psk =  '1PG7OiApB1nwvP+rz05pAQ=='
-      psks = opts[:psks] ||= { LongFast: public_psk }
-      raise 'ERROR: psks parameter must be a hash of :channel => psk key value pairs' unless psks.is_a?(Hash)
+      if opts.key?(:psks) && opts[:psks].nil?
+        psks = nil
+      else
+        psks = opts[:psks] || { LongFast: public_psk }
+        raise 'ERROR: psks parameter must be a hash of :channel => psk key value pairs' unless psks.is_a?(Hash)
 
-      psks[:LongFast] = public_psk if psks[:LongFast] == 'AQ=='
+        psks = psks.dup
+        psks[:LongFast] = public_psk if psks[:LongFast] == 'AQ=='
+      end
 
       # TODO: verify text length validity
       max_txt_len = Meshtastic::Constants::DATA_PAYLOAD_LEN
@@ -381,7 +400,7 @@ module Meshtastic
       port_num = Meshtastic::PortNum::TEXT_MESSAGE_APP
 
       data = Meshtastic::Data.new
-      data.payload = text.force_encoding('ASCII-8BIT')
+      data.payload = text.to_s.dup.force_encoding('ASCII-8BIT')
       data.portnum = port_num
       data.want_response = want_response
       # puts data.to_h