rble 0.7.0

data/lib/rble/characteristic.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module RBLE
+  # Immutable representation of a GATT characteristic (data only)
+  #
+  # @!attribute uuid [String] Characteristic UUID (128-bit format)
+  # @!attribute flags [Array<String>] Capability flags: "read", "write", "write-without-response", "notify", "indicate"
+  # @!attribute service_uuid [String] Parent service UUID
+  Characteristic = Data.define(:uuid, :flags, :service_uuid) do
+    def initialize(uuid:, flags: [], service_uuid: nil)
+      super
+    end
+
+    # Get short UUID for standard characteristics
+    def short_uuid
+      if uuid =~ /^0000([0-9a-f]{4})-0000-1000-8000-00805f9b34fb$/i
+        Regexp.last_match(1).downcase
+      else
+        uuid
+      end
+    end
+
+    # Check if characteristic supports reading
+    def readable?
+      flags.include?('read')
+    end
+
+    # Check if characteristic supports writing with response
+    def writable?
+      flags.include?('write')
+    end
+
+    # Check if characteristic supports writing without response
+    def writable_without_response?
+      flags.include?('write-without-response')
+    end
+
+    # Check if characteristic supports notifications
+    def notifiable?
+      flags.include?('notify')
+    end
+
+    # Check if characteristic supports indications
+    def indicatable?
+      flags.include?('indicate')
+    end
+
+    # Check if characteristic supports any form of subscription
+    def subscribable?
+      notifiable? || indicatable?
+    end
+  end
+
+  # Active characteristic with read/write/subscribe operations
+  #
+  # Returned by Connection service discovery. Wraps immutable Characteristic
+  # data with operations that interact with the device via the backend.
+  #
+  # @example Reading a value
+  #   hr_char = service.characteristic('2a37')
+  #   value = hr_char.read  # => binary string
+  #   bytes = hr_char.read_bytes  # => [0x10, 0x65, ...]
+  #
+  # @example Writing a value
+  #   char.write([0x01, 0x02])  # write with response
+  #   char.write([0x01], response: false)  # write without response
+  #
+  # @example Subscribing to notifications
+  #   char.subscribe do |value|
+  #     puts "Got notification: #{value.bytes.inspect}"
+  #   end
+  #   # ... later ...
+  #   char.unsubscribe
+  #
+  class ActiveCharacteristic
+    attr_reader :uuid, :flags, :service_uuid, :path, :descriptors
+
+    # Create an active characteristic
+    # @param characteristic [Characteristic] Underlying characteristic data
+    # @param path [String] D-Bus object path
+    # @param connection [Connection] Parent connection (for state checks)
+    # @param backend [Backend::Base] Backend for GATT operations
+    # @param descriptors [Array<Hash>] Descriptor info hashes with :uuid and :path keys
+    def initialize(characteristic:, path:, connection:, backend:, descriptors: [])
+      @uuid = characteristic.uuid
+      @flags = characteristic.flags
+      @service_uuid = characteristic.service_uuid
+      @path = path
+      @connection = connection
+      @backend = backend
+      @descriptors = descriptors
+      @subscribed = false
+    end
+
+    # Get short UUID for standard characteristics (e.g., "2a37" from full UUID)
+    # @return [String] Short UUID if standard, otherwise full UUID
+    def short_uuid
+      if uuid =~ /^0000([0-9a-f]{4})-0000-1000-8000-00805f9b34fb$/i
+        Regexp.last_match(1).downcase
+      else
+        uuid
+      end
+    end
+
+    # Check if characteristic supports reading
+    # @return [Boolean]
+    def readable?
+      flags.include?('read')
+    end
+
+    # Check if characteristic supports writing with response
+    # @return [Boolean]
+    def writable?
+      flags.include?('write')
+    end
+
+    # Check if characteristic supports writing without response
+    # @return [Boolean]
+    def writable_without_response?
+      flags.include?('write-without-response')
+    end
+
+    # Check if characteristic supports notifications
+    # @return [Boolean]
+    def notifiable?
+      flags.include?('notify')
+    end
+
+    # Check if characteristic supports indications
+    # @return [Boolean]
+    def indicatable?
+      flags.include?('indicate')
+    end
+
+    # Check if characteristic supports any form of subscription
+    # @return [Boolean]
+    def subscribable?
+      notifiable? || indicatable?
+    end
+
+    # Read the characteristic value
+    # @param timeout [Numeric] Read timeout in seconds
+    # @return [String] Binary string (ASCII-8BIT encoding)
+    # @raise [NotSupportedError] if characteristic doesn't support read
+    # @raise [NotConnectedError] if not connected
+    # @raise [ReadError] if read fails
+    def read(timeout: 30)
+      raise NotSupportedError, 'read' unless readable?
+      raise NotConnectedError unless @connection.connected?
+
+      # Serialize GATT operations through the connection's queue
+      enqueue_gatt_operation do
+        @backend.read_characteristic(@path, connection: @connection, timeout: timeout)
+      end
+    end
+
+    # Read the characteristic value as byte array
+    # @param timeout [Numeric] Read timeout in seconds
+    # @return [Array<Integer>] Byte array
+    # @raise [NotSupportedError] if characteristic doesn't support read
+    # @raise [NotConnectedError] if not connected
+    # @raise [ReadError] if read fails
+    def read_bytes(timeout: 30)
+      read(timeout: timeout).bytes
+    end
+
+    # Write a value to the characteristic
+    # @param data [String, Array<Integer>] Data to write (binary string or byte array)
+    # @param response [Boolean] Wait for write response (default: true)
+    # @param timeout [Numeric] Write timeout in seconds
+    # @return [Boolean] true on success
+    # @raise [NotSupportedError] if write type not supported
+    # @raise [NotConnectedError] if not connected
+    # @raise [WriteError] if write fails
+    def write(data, response: true, timeout: 30)
+      if response
+        raise NotSupportedError, 'write' unless writable?
+      else
+        raise NotSupportedError, 'write-without-response' unless writable_without_response?
+      end
+      raise NotConnectedError unless @connection.connected?
+
+      # Serialize GATT operations through the connection's queue
+      enqueue_gatt_operation do
+        @backend.write_characteristic(@path, data, connection: @connection, response: response, timeout: timeout)
+      end
+    end
+
+    # Subscribe to characteristic notifications/indications
+    # @yield [String] Called with value (binary string) on each notification
+    # @return [Boolean] true on success
+    # @raise [ArgumentError] if no block given
+    # @raise [NotifyNotSupported] if characteristic doesn't support notifications
+    # @raise [NotConnectedError] if not connected
+    # @raise [NotifyError] if subscription fails
+    def subscribe(&block)
+      raise ArgumentError, 'Block required' unless block_given?
+      raise NotifyNotSupported.new(short_uuid, flags) unless subscribable?
+      raise NotConnectedError unless @connection.connected?
+
+      # Serialize GATT operations through the connection's queue
+      enqueue_gatt_operation do
+        @backend.subscribe_characteristic(@path, connection: @connection, &block)
+      end
+      @subscribed = true
+    end
+
+    # Unsubscribe from notifications
+    # @return [void]
+    def unsubscribe
+      return unless @subscribed
+
+      @backend.unsubscribe_characteristic(@path)
+      @subscribed = false
+    end
+
+    # Check if currently subscribed to notifications
+    # @return [Boolean]
+    def subscribed?
+      @subscribed
+    end
+
+    private
+
+    # Enqueue a GATT operation through the connection's queue
+    # Falls back to direct execution if queue is not available (non-BlueZ backend)
+    # @yield Block containing the GATT operation
+    # @return [Object] Result from the block
+    def enqueue_gatt_operation(&block)
+      if @connection.respond_to?(:gatt_queue)
+        @connection.gatt_queue.enqueue(&block)
+      else
+        block.call
+      end
+    end
+  end
+end

data/lib/rble/cli/adapter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RBLE
+  module CLI
+    class AdapterCli < Thor
+      def self.namespace
+        "adapter"
+      end
+
+      class_option :json, type: :boolean, default: false,
+                          desc: "Output as JSON"
+      class_option :adapter, type: :string,
+                             desc: "Adapter name, e.g. hci1"
+
+      desc "list", "Show all available Bluetooth adapters"
+      def list
+        formatter = options["json"] ? Formatters::Json.new : Formatters::Text.new
+        adapter_list = Backend.for_platform.adapters
+        formatter.adapter_list(adapter_list)
+      rescue RBLE::Error => e
+        $stderr.puts "Error: #{e.message}"
+        exit 1
+      end
+
+      desc "power STATE", "Turn adapter power on or off"
+      def power(state)
+        bool = parse_on_off(state)
+        name = resolve_adapter_name
+        Backend.for_platform.adapter_set_property(name, :powered, bool)
+        formatter_for_options.adapter_confirm("Adapter #{bool ? 'powered on' : 'powered off'}")
+      rescue RBLE::Error => e
+        $stderr.puts "Error: #{e.message}. Run `rble doctor` to diagnose."
+        exit 1
+      end
+
+      desc "discoverable STATE", "Set discoverable mode on or off"
+      def discoverable(state)
+        bool = parse_on_off(state)
+        name = resolve_adapter_name
+        Backend.for_platform.adapter_set_property(name, :discoverable, bool)
+        formatter_for_options.adapter_confirm("Discoverable mode #{bool ? 'enabled' : 'disabled'}")
+      rescue RBLE::Error => e
+        $stderr.puts "Error: #{e.message}. Run `rble doctor` to diagnose."
+        exit 1
+      end
+
+      desc "pairable STATE", "Set pairable mode on or off"
+      def pairable(state)
+        bool = parse_on_off(state)
+        name = resolve_adapter_name
+        Backend.for_platform.adapter_set_property(name, :pairable, bool)
+        formatter_for_options.adapter_confirm("Pairable mode #{bool ? 'enabled' : 'disabled'}")
+      rescue RBLE::Error => e
+        $stderr.puts "Error: #{e.message}. Run `rble doctor` to diagnose."
+        exit 1
+      end
+
+      desc "name NAME", "Set adapter friendly name"
+      def name(new_name)
+        adapter_name = resolve_adapter_name
+        Backend.for_platform.adapter_set_property(adapter_name, :alias, new_name)
+        formatter_for_options.adapter_confirm("Adapter name set to '#{new_name}'")
+      rescue RBLE::Error => e
+        $stderr.puts "Error: #{e.message}. Run `rble doctor` to diagnose."
+        exit 1
+      end
+
+      private
+
+      def parse_on_off(state)
+        case state.downcase
+        when "on"  then true
+        when "off" then false
+        else
+          raise Thor::Error, "Invalid state '#{state}'. Use 'on' or 'off'."
+        end
+      end
+
+      def resolve_adapter_name
+        options["adapter"] || Backend.for_platform.default_adapter_name
+      end
+
+      def formatter_for_options
+        options["json"] ? Formatters::Json.new : Formatters::Text.new
+      end
+    end
+  end
+end

data/lib/rble/cli/characteristic_helpers.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'rble/gatt/uuid_database'
+require_relative 'value_parser'
+require_relative 'hex_dump'
+
+module RBLE
+  module CLI
+    # Shared helpers for GATT commands (read, write, monitor).
+    #
+    # Provides UUID normalization, characteristic discovery, connection
+    # management, and value formatting used by all three commands.
+    #
+    # @example Including in a command class
+    #   class Read
+    #     include CharacteristicHelpers
+    #
+    #     def execute
+    #       connection = connect_and_discover(@address, timeout: @timeout)
+    #       char = find_characteristic(connection, "2a37")
+    #       puts format_value(char.uuid, char.read)
+    #     end
+    #   end
+    module CharacteristicHelpers
+      # Bluetooth Base UUID suffix for short UUID expansion
+      BLUETOOTH_BASE_SUFFIX = "-0000-1000-8000-00805f9b34fb"
+
+      # Normalize user UUID input to full 128-bit lowercase UUID.
+      #
+      # Handles:
+      # - Short 4-char UUIDs: "2a37" -> "00002a37-0000-1000-8000-00805f9b34fb"
+      # - "0x" prefix: "0x2a37" -> expanded
+      # - Case-insensitive: "2A37" -> lowercase
+      # - Full 128-bit UUIDs: passed through lowercase
+      #
+      # @param input [String] UUID from user input
+      # @return [String] Full 128-bit UUID in lowercase
+      def normalize_char_uuid(input)
+        stripped = input.sub(/\A0x/i, '').downcase
+        case stripped.length
+        when 4
+          "0000#{stripped}#{BLUETOOTH_BASE_SUFFIX}"
+        when 8
+          "#{stripped}#{BLUETOOTH_BASE_SUFFIX}"
+        else
+          stripped
+        end
+      end
+
+      # Find an ActiveCharacteristic across all services on a connection.
+      #
+      # Searches all services and their characteristics for a match by UUID.
+      # First match wins (per design decision -- no disambiguation).
+      #
+      # @param connection [Connection] Connected device with discovered services
+      # @param uuid_input [String] UUID from user (short, full, or with 0x prefix)
+      # @return [ActiveCharacteristic] The found characteristic
+      # @raise [RBLE::Error] if characteristic not found
+      def find_characteristic(connection, uuid_input)
+        normalized = normalize_char_uuid(uuid_input)
+        short_input = uuid_input.sub(/\A0x/i, '').downcase
+
+        connection.services.each do |service|
+          service.characteristics.each do |char|
+            return char if char.uuid.downcase == normalized || char.short_uuid == short_input
+          end
+        end
+
+        raise RBLE::Error,
+              "Characteristic #{uuid_input} not found on device. " \
+              "Run `rble show <address>` to see available characteristics."
+      end
+
+      # Connect to a device, discover services, and return the connection.
+      #
+      # Reuses Show's connect_with_retry pattern: one retry for
+      # ConnectionTimeout/ConnectionFailed, no retry for DeviceNotFound.
+      # Status messages are written to stderr.
+      #
+      # @param address [String] Device MAC address
+      # @param timeout [Numeric] Connection timeout in seconds
+      # @return [Connection] Connected device with services discovered
+      # @raise [SystemExit] on unrecoverable connection errors
+      def connect_and_discover(address, timeout:)
+        connection = connect_with_retry(address, timeout: timeout)
+        $stderr.puts "Discovering services..."
+        connection.discover_services
+        connection
+      end
+
+      # Format a characteristic value for display.
+      #
+      # Known UUIDs are parsed with smart parsers (e.g., "72 bpm").
+      # Unknown UUIDs are displayed as hex+ASCII dump.
+      #
+      # @param uuid [String] Characteristic UUID
+      # @param raw_bytes [String] Binary string of raw characteristic data
+      # @return [String] Formatted value string
+      def format_value(uuid, raw_bytes)
+        if ValueParser.known?(uuid)
+          ValueParser.parse(uuid, raw_bytes)
+        else
+          HexDump.format(raw_bytes)
+        end
+      end
+
+      # Get human-readable name + UUID display for a characteristic.
+      #
+      # Standard UUIDs: "Heart Rate Measurement (2a37)"
+      # Vendor UUIDs: "12345678-1234-1234-1234-123456789abd"
+      #
+      # @param uuid [String] Characteristic UUID (full 128-bit)
+      # @return [String] Display name
+      def resolve_char_name(uuid)
+        name = RBLE::GATT::UUIDDatabase.resolve(uuid, type: :characteristic)
+        short = RBLE::GATT::UUIDDatabase.extract_short_uuid(uuid)
+
+        if name
+          if RBLE::GATT::UUIDDatabase.standard_uuid?(uuid)
+            "#{name} (#{short})"
+          else
+            "#{name} (#{uuid})"
+          end
+        else
+          short == uuid.downcase ? uuid : short
+        end
+      end
+
+      private
+
+      # Connect with one retry on timeout/connection failure.
+      # No retry for DeviceNotFoundError.
+      #
+      # @param address [String] Device MAC address
+      # @param timeout [Numeric] Connection timeout in seconds
+      # @return [Connection] Connected device
+      # @raise [SystemExit] on unrecoverable errors
+      def connect_with_retry(address, timeout:)
+        $stderr.puts "Connecting to #{address}..."
+        RBLE.connect(address, timeout: timeout)
+      rescue RBLE::DeviceNotFoundError
+        raise # No retry for device not found
+      rescue RBLE::ConnectionTimeoutError, RBLE::ConnectionFailed
+        $stderr.puts "Connection failed, retrying..."
+        begin
+          RBLE.connect(address, timeout: timeout)
+        rescue RBLE::ConnectionTimeoutError, RBLE::ConnectionFailed => e
+          $stderr.puts "Error: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end