meshtastic 0.0.176 → 0.0.177

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61f04c58cb881e95ff006f4f2300c017c31156ef4e95624fc6945e29be079ea8
-  data.tar.gz: fa39514939d9122b38738840dfc21eca15e4efe50aad7cbb7c9d2f54d3c1a0d5
+  metadata.gz: 5f02b5c39c6c878904d2d2d7fb765bf0a66d48de021323ebc20ca55221e29f64
+  data.tar.gz: 592e7bf735c228217e2484f139f8682c8923d5ba1846a2f6212563df1f841a67
 SHA512:
-  metadata.gz: b933ce6912f6cfc7a2e78bc53478f1793f7d8dc32842d3a8f7e7838d4ea21adbcb0b83266f9eba69285e1ca2ec8a7241be52a695a962bb1657e1030c66885857
-  data.tar.gz: fde6712097aa9d534066fa00b6ba13d6de7058bdd9d775e8ed88fb440b507e0049571e50fd28aa8a0b0597c1b5ff92b3a8c3f9958bf0e511ad573ab98ee8f238
+  metadata.gz: ef44a3860a9a12450cff1902e4167377d47268a20a399741de32f5da0e0e6d9be9084d9485f4699e3726e23f7ff4de027b36b9a04e6b2164f27f1e438e591ee2
+  data.tar.gz: e355b9bf3afb4fc6394528ba85764307b9d7b2acc01d22dd85ae9c597388af793214a90d7cd7af0829d521ae2d430ab72e1fe365a9e92fd98bfd9bc3cd5bd309

data/.rubocop.yml

@@ -1,6 +1,7 @@
 AllCops: 
   UseCache: false
   NewCops: enable
+  SuggestExtensions: false
 Layout/LineLength:
   Max: 293
 Lint/UselessRescue:

data/.rubocop_todo.yml

@@ -22,13 +22,6 @@ Layout/EmptyLineAfterMagicComment:
 Layout/EmptyLines:
   Enabled: false
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
-# SupportedStylesAlignWith: start_of_line, relative_to_receiver
-Layout/IndentationWidth:
-  Exclude:
-    - 'lib/meshtastic/serial_interface.rb'
 
 # Offense count: 26
 # This cop supports safe autocorrection (--autocorrect).
@@ -37,14 +30,6 @@ Layout/IndentationWidth:
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, EnforcedStyleForEmptyBraces.
-# SupportedStyles: space, no_space
-# SupportedStylesForEmptyBraces: space, no_space
-Layout/SpaceBeforeBlockBraces:
-  Exclude:
-    - 'lib/meshtastic/serial_interface.rb'
 
 # Offense count: 49
 # Configuration parameters: AllowComments, AllowEmptyLambdas.
@@ -63,7 +48,6 @@ Lint/UnusedMethodArgument:
 # This cop supports safe autocorrection (--autocorrect).
 Lint/UselessAssignment:
   Exclude:
-    - 'lib/meshtastic/serial_interface.rb'
     - 'lib/meshtastic/stream_interface.rb'
     - 'meshtastic.gemspec'
 
@@ -86,11 +70,6 @@ Style/CommentAnnotation:
 Style/Documentation:
   Enabled: false
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Style/ExplicitBlockArgument:
-  Exclude:
-    - 'lib/meshtastic/serial_interface.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).

data/Gemfile

@@ -20,6 +20,7 @@ gem 'rspec', '3.13.2'
 gem 'rubocop', '1.91.0'
 gem 'rubocop-rake', '0.7.1'
 gem 'rubocop-rspec', '3.10.2'
+gem 'ruby-dbus', '0.25.0'
 gem 'rvm', '1.11.3.9'
 gem 'uart', '1.0.0'
 gem 'yard', '0.9.45'

data/README.md

@@ -24,7 +24,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-The primary interaction modules today are `Meshtastic::MQTT` (broker) and `Meshtastic::SerialInterface` (USB/UART). Examples for each follow.
+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
 
@@ -101,111 +101,108 @@ 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
+### Serial and Bluetooth (send / receive)
 
-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.
+`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.
 
-To inspect available methods and open a serial session:
+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]`.
 
-```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
-```
+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.
 
-This code will dump every FromRadio packet (blocks until CTRL+C):
+#### Serial (`Meshtastic::Serial`)
 
-```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:
+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 = 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
+
+serial_obj = nil
+begin
+  serial_obj = Meshtastic::Serial.connect(block_dev: '/dev/ttyACM2', 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: '!83726fb1',
+    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
 ```
 
-Sending a message over serial:
+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).
 
-```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)
-```
+#### Bluetooth (`Meshtastic::Bluetooth`)
 
-A typical end-to-end send + receive session looks like this (connect once, send, then subscribe):
+Linux only (BlueZ + `ruby-dbus`). Connect with a BLE address (`AA:BB:CC:DD:EE:FF`), not a mesh id (`!03d52a07`). 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: 'E8:EE:03:D5:2A:07', name: '📺_2a07', paired: true }, ...]
+```
 
-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
+Pair while discovery is running. Screen devices typically show a random 6-digit PIN:
+
+```text
+bluetoothctl
+agent KeyboardDisplay
+default-agent
+scan on
+pair E8:EE:03:D5:2A:07
+trust E8:EE:03:D5:2A:07
+scan off
+quit
 ```
 
-Non-blocking receive helpers (useful when you drive the loop yourself):
+`Failed to pair: AuthenticationFailed` means the agent never got the PIN. `Device … not available` means scan first; the advertisement dropped.
 
-```ruby
-# Pop one framed FromRadio (or nil on timeout)
-fr = Meshtastic::SerialInterface.recv_from_radio(timeout: 2)
-puts fr&.to_h
+Send and receive (same options as Serial, `bluetooth_obj:` instead of `serial_obj:`):
 
-# Drain whatever is already queued
-Meshtastic::SerialInterface.drain_from_radio.each { |fr| puts fr.to_h }
+```ruby
+require 'meshtastic'
 
-# 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
+bluetooth_obj = nil
+begin
+  bluetooth_obj = Meshtastic::Bluetooth.connect(address: 'E8:EE:03:D5:2A:07')
+  Meshtastic::Bluetooth.wait_for_config(bluetooth_obj: bluetooth_obj, timeout: 30)
+
+  Meshtastic::Bluetooth.send_text(
+    bluetooth_obj: bluetooth_obj,
+    to: '!83726fb1',
+    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
 ```
 
-> **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.
+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/lib/meshtastic/bluetooth/bluez.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'dbus'
+require 'timeout'
+
+module Meshtastic
+  module Bluetooth
+    # Linux BlueZ transport for raw Meshtastic protobuf messages.
+    class BlueZ # rubocop:disable Metrics/ClassLength
+      # https://github.com/meshtastic/python/blob/master/meshtastic/ble_interface.py
+      SERVICE_UUID = '6ba1b218-15a8-461f-9fa8-5dcae273eafd'
+      TORADIO_UUID = 'f75c76d2-129e-4dad-a1dd-7866124401e7'
+      FROMRADIO_UUID = '2c55e69e-4993-11ed-b878-0242ac120002'
+
+      def self.scan(adapter: 'hci0', timeout: 5)
+        new(address: '00:00:00:00:00:00', adapter: adapter, timeout: timeout).scan_adapter
+      end
+
+      def connect
+        @mutex.synchronize { connect_locked }
+      end
+
+      def connect_locked
+        @bus = DBus::ASystemBus.allocate
+        bounded { @bus.__send__(:initialize) }
+        objects = managed_objects
+        check_adapter(objects)
+        @device_path = objects.find do |_path, interfaces|
+          device = interfaces['org.bluez.Device1']
+          device && device['Address']&.casecmp?(@address) && device['Adapter'] == "/org/bluez/#{@adapter}"
+        end&.first
+        raise IOError, "Bluetooth device #{@address} not found on #{@adapter}; scan first" unless @device_path
+        raise IOError, "Bluetooth device is not Paired. Run: bluetoothctl pair #{@address} (enter the PIN shown by your radio), then retry." unless properties(@device_path, 'org.bluez.Device1')['Paired']
+
+        @disconnect_needed = true
+        call(@device_path, 'org.bluez.Device1', 'Connect')
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+        until properties(@device_path, 'org.bluez.Device1')['ServicesResolved']
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise IOError, 'Bluetooth ServicesResolved timed out' unless remaining.positive?
+
+          sleep [0.1, remaining].min
+        end
+        @to_radio = characteristic(TORADIO_UUID)
+        @from_radio = characteristic(FROMRADIO_UUID)
+        self
+      rescue StandardError
+        close_locked
+        raise
+      end
+
+      def close
+        @mutex.synchronize { close_locked }
+      end
+
+      def close_locked
+        call(@device_path, 'org.bluez.Device1', 'Disconnect') if @bus && @disconnect_needed
+      ensure
+        @disconnect_needed = false
+        release_bus
+      end
+
+      def scan_adapter
+        started = false
+        @mutex.synchronize do
+          @bus = DBus::ASystemBus.allocate
+          bounded { @bus.__send__(:initialize) }
+          objects = managed_objects
+          check_adapter(objects)
+          adapter_path = "/org/bluez/#{@adapter}"
+          begin
+            call(adapter_path, 'org.bluez.Adapter1', 'StartDiscovery')
+            started = true
+          rescue DBus::Error
+            nil
+          end
+          sleep @timeout
+          managed_objects.filter_map do |_path, interfaces|
+            device = interfaces['org.bluez.Device1']
+            next unless device && device['Adapter'] == adapter_path
+            next unless Array(device['UUIDs']).any? { |uuid| uuid.to_s.casecmp?(SERVICE_UUID) }
+
+            { address: device['Address'], name: device['Name'], paired: device['Paired'] }
+          end
+        ensure
+          if @bus && started
+            begin
+              call("/org/bluez/#{@adapter}", 'org.bluez.Adapter1', 'StopDiscovery')
+            rescue DBus::Error
+              nil
+            end
+          end
+          release_bus
+        end
+      end
+
+      def connected!
+        raise IOError, 'Bluetooth device disconnected' unless @bus && @from_radio && properties(@device_path, 'org.bluez.Device1')['Connected']
+      end
+
+      def read
+        @mutex.synchronize do
+          connected!
+          call(@from_radio, 'org.bluez.GattCharacteristic1', 'ReadValue', ['a{sv}', {}]).first.pack('C*')
+        end
+      end
+
+      def write(bytes)
+        @mutex.synchronize do
+          connected!
+          # BlueZ request uses Write Request <= MTU-3, Prepare/Execute Write above it.
+          # Never fragment protobufs ourselves: each WriteValue is one message.
+          call(@to_radio, 'org.bluez.GattCharacteristic1', 'WriteValue', ['ay', bytes.bytes], ['a{sv}', { 'type' => %w[s request] }])
+          bytes.bytesize
+        end
+      end
+
+      def characteristic(uuid)
+        objects = managed_objects
+        service = objects.find do |_path, interfaces|
+          properties = interfaces['org.bluez.GattService1']
+          properties && properties['Device'] == @device_path && properties['UUID']&.casecmp?(SERVICE_UUID)
+        end&.first
+        raise IOError, 'Meshtastic GATT service not found on selected device' unless service
+
+        match = objects.find do |_path, interfaces|
+          properties = interfaces['org.bluez.GattCharacteristic1']
+          properties && properties['Service'] == service && properties['UUID']&.casecmp?(uuid)
+        end&.first
+        raise IOError, "Meshtastic GATT characteristic #{uuid} not found" unless match
+
+        match
+      end
+
+      def check_adapter(objects)
+        adapter = objects.dig("/org/bluez/#{@adapter}", 'org.bluez.Adapter1')
+        raise IOError, "Bluetooth adapter #{@adapter} not found" unless adapter
+        raise IOError, "Bluetooth adapter #{@adapter} is not powered" unless adapter['Powered']
+      end
+
+      def release_bus
+        socket = @bus&.message_queue&.socket
+        socket.close if socket && !socket.closed?
+        @bus = nil
+      end
+
+      def properties(path, interface)
+        call(path, 'org.freedesktop.DBus.Properties', 'GetAll', ['s', interface]).first
+      end
+
+      def managed_objects
+        call('/', 'org.freedesktop.DBus.ObjectManager', 'GetManagedObjects').first
+      end
+
+      def call(path, interface, member, *parameters)
+        message = DBus::Message.new(DBus::Message::METHOD_CALL)
+        message.destination = 'org.bluez'
+        message.path = path
+        message.interface = interface
+        message.member = member
+        parameters.each { |type, value| message.add_param(type, value) }
+        bounded { @bus.send_sync_or_async(message) }
+      end
+
+      # ruby-dbus 0.25 has no method timeout API. An interrupted bus must never
+      # be reused because its pending reply bookkeeping may be inconsistent.
+      def bounded(&)
+        Timeout.timeout(@timeout, &)
+      rescue Timeout::Error
+        release_bus
+        raise IOError, 'Bluetooth D-Bus operation timed out'
+      end
+
+      def initialize(address:, adapter: 'hci0', timeout: 15)
+        raise ArgumentError, 'Invalid Bluetooth address' unless address.is_a?(String) && /\A(?:[0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}\z/.match?(address)
+
+        raise ArgumentError, 'Invalid Bluetooth adapter (expected hciN)' unless adapter.is_a?(String) && /\Ahci\d+\z/.match?(adapter)
+        raise ArgumentError, 'Invalid Bluetooth timeout (expected positive finite seconds)' unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout.positive?
+
+        @address = address
+        @adapter = adapter
+        @timeout = timeout
+        @mutex = Mutex.new
+      end
+    end
+  end
+end