rble 0.7.0

data/lib/rble/cli/value_parser.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module RBLE
+  module CLI
+    # Smart parser registry for known BLE characteristic data types.
+    #
+    # Converts raw binary characteristic values into human-readable strings
+    # with appropriate units and formatting. Unknown UUIDs return nil,
+    # allowing callers to fall back to hex dump display.
+    #
+    # @example Parse a known characteristic
+    #   ValueParser.parse("2a19", "\x5F".b)  # => "95%"
+    #   ValueParser.parse("2a37", "\x00\x48".b)  # => "72 bpm"
+    #
+    # @example Check if a UUID has a parser
+    #   ValueParser.known?("2a19")  # => true
+    #   ValueParser.known?("ffff")  # => false
+    module ValueParser
+      # Body Sensor Location enum (Bluetooth SIG)
+      BODY_SENSOR_LOCATIONS = {
+        0 => "Other",
+        1 => "Chest",
+        2 => "Wrist",
+        3 => "Finger",
+        4 => "Hand",
+        5 => "Ear Lobe",
+        6 => "Foot"
+      }.freeze
+
+      # Registry of parsers keyed by short 4-char characteristic UUID (lowercase).
+      # Each parser is a lambda: (raw_bytes_string) -> formatted_string
+      PARSERS = {
+        # Battery Level: uint8, percentage
+        "2a19" => ->(raw) {
+          return "malformed" if raw.bytesize < 1
+          "#{raw.unpack1('C')}%"
+        },
+
+        # Heart Rate Measurement: flags + uint8/uint16
+        "2a37" => ->(raw) {
+          return "malformed" if raw.bytesize < 2
+          flags = raw.getbyte(0)
+          hr_16bit = (flags & 0x01) == 1
+          if hr_16bit
+            return "malformed" if raw.bytesize < 3
+            hr = raw[1, 2].unpack1('S<')
+          else
+            hr = raw.getbyte(1)
+          end
+          "#{hr} bpm"
+        },
+
+        # Temperature (Environmental Sensing): sint16 LE / 100
+        "2a6e" => ->(raw) {
+          return "malformed" if raw.bytesize < 2
+          raw_val = raw.unpack1('s<')
+          temp = raw_val / 100.0
+          format('%.2f C', temp)
+        },
+
+        # Temperature Measurement (Health Thermometer): flags + IEEE 11073 FLOAT
+        "2a1c" => ->(raw) {
+          return "malformed" if raw.bytesize < 5
+          flags = raw.getbyte(0)
+          unit = (flags & 0x01) == 0 ? 'C' : 'F'
+          temp = ieee_11073_float(raw[1, 4])
+          format('%.1f %s', temp, unit)
+        },
+
+        # Tx Power Level: sint8, dBm
+        "2a07" => ->(raw) {
+          return "malformed" if raw.bytesize < 1
+          "#{raw.unpack1('c')} dBm"
+        },
+
+        # Blood Pressure Measurement: flags + 3x SFLOAT
+        "2a35" => ->(raw) {
+          return "malformed" if raw.bytesize < 5
+          flags = raw.getbyte(0)
+          unit = (flags & 0x01) == 0 ? 'mmHg' : 'kPa'
+          systolic = ieee_11073_sfloat(raw[1, 2])
+          diastolic = ieee_11073_sfloat(raw[3, 2])
+          format('%.0f/%.0f %s', systolic, diastolic, unit)
+        },
+
+        # Humidity: uint16 LE / 100
+        "2a6f" => ->(raw) {
+          return "malformed" if raw.bytesize < 2
+          raw_val = raw.unpack1('S<')
+          humidity = raw_val / 100.0
+          format('%.2f%%', humidity)
+        },
+
+        # Device Name: UTF-8 string
+        "2a00" => ->(raw) { raw.force_encoding('UTF-8').scrub('?').strip },
+
+        # Model Number String: UTF-8 string
+        "2a24" => ->(raw) { raw.force_encoding('UTF-8').scrub('?').strip },
+
+        # Serial Number String: UTF-8 string
+        "2a25" => ->(raw) { raw.force_encoding('UTF-8').scrub('?').strip },
+
+        # Firmware Revision String: UTF-8 string
+        "2a26" => ->(raw) { raw.force_encoding('UTF-8').scrub('?').strip },
+
+        # Hardware Revision String: UTF-8 string
+        "2a27" => ->(raw) { raw.force_encoding('UTF-8').scrub('?').strip },
+
+        # Software Revision String: UTF-8 string
+        "2a28" => ->(raw) { raw.force_encoding('UTF-8').scrub('?').strip },
+
+        # Manufacturer Name String: UTF-8 string
+        "2a29" => ->(raw) { raw.force_encoding('UTF-8').scrub('?').strip },
+
+        # Body Sensor Location: uint8 enum
+        "2a38" => ->(raw) {
+          return "malformed" if raw.bytesize < 1
+          val = raw.unpack1('C')
+          BODY_SENSOR_LOCATIONS.fetch(val, "Location: #{val}")
+        }
+      }.freeze
+
+      # Parse raw characteristic bytes into a human-readable string.
+      #
+      # @param uuid [String] Characteristic UUID (short, full, or with 0x prefix)
+      # @param raw_bytes [String] Binary string of raw characteristic data
+      # @return [String, nil] Formatted value string, or nil if UUID is unknown
+      def self.parse(uuid, raw_bytes)
+        key = normalize_key(uuid)
+        PARSERS[key]&.call(raw_bytes)
+      end
+
+      # Check if a UUID has a registered parser.
+      #
+      # @param uuid [String] Characteristic UUID
+      # @return [Boolean]
+      def self.known?(uuid)
+        key = normalize_key(uuid)
+        PARSERS.key?(key)
+      end
+
+      # Parse IEEE 11073 32-bit FLOAT.
+      # Format: 8-bit exponent (signed) + 24-bit mantissa (signed)
+      # Value = mantissa * 10^exponent
+      #
+      # @param bytes [String] 4-byte binary string (little-endian)
+      # @return [Float] Parsed value
+      def self.ieee_11073_float(bytes)
+        return Float::NAN if bytes.nil? || bytes.bytesize < 4
+
+        # Little-endian: bytes[0..2] = mantissa (24-bit), bytes[3] = exponent (8-bit)
+        # Pad to 4 bytes for uint32 unpack, then mask to 24 bits
+        mantissa = (bytes[0, 3] + "\x00".b).unpack1('V') & 0x00FFFFFF
+        # Sign-extend 24-bit to Ruby integer
+        mantissa -= 0x1000000 if mantissa >= 0x800000
+        exponent = bytes.getbyte(3)
+        exponent -= 256 if exponent >= 128 # sign-extend 8-bit
+
+        # Special values
+        return Float::NAN if mantissa == 0x7FFFFF && exponent == 0
+        return Float::INFINITY if mantissa == 0x7FFFFE && exponent == 0
+        return -Float::INFINITY if mantissa == -0x7FFFFE && exponent == 0
+
+        mantissa * (10.0**exponent)
+      end
+
+      # Parse IEEE 11073 16-bit SFLOAT.
+      # Format: 4-bit exponent (signed) + 12-bit mantissa (signed)
+      # Value = mantissa * 10^exponent
+      #
+      # @param bytes [String] 2-byte binary string (little-endian)
+      # @return [Float] Parsed value
+      def self.ieee_11073_sfloat(bytes)
+        return Float::NAN if bytes.nil? || bytes.bytesize < 2
+
+        raw = bytes.unpack1('S<')
+        mantissa = raw & 0x0FFF
+        exponent = (raw >> 12) & 0x0F
+
+        # Sign-extend
+        mantissa -= 0x1000 if mantissa >= 0x800
+        exponent -= 16 if exponent >= 8
+
+        # Special values
+        return Float::NAN if mantissa == 0x7FF && exponent == 0
+        return Float::INFINITY if mantissa == 0x7FE && exponent == 0
+        return -Float::INFINITY if mantissa == -0x7FE && exponent == 0
+
+        mantissa * (10.0**exponent)
+      end
+
+      # Normalize a UUID input to a short 4-char key for PARSERS lookup.
+      # Handles: "2a19", "2A19", "0x2a19", "00002a19-0000-1000-8000-00805f9b34fb"
+      #
+      # @param uuid [String] UUID input
+      # @return [String] Normalized short key (lowercase)
+      def self.normalize_key(uuid)
+        key = uuid.downcase.sub(/\A0x/, '')
+        if key =~ /\A0000([0-9a-f]{4})-0000-1000-8000-00805f9b34fb\z/
+          Regexp.last_match(1)
+        elsif key =~ /\A0000([0-9a-f]{4})\z/
+          Regexp.last_match(1)
+        else
+          key
+        end
+      end
+
+      private_class_method :normalize_key
+    end
+  end
+end

data/lib/rble/cli/write.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative 'characteristic_helpers'
+
+module RBLE
+  module CLI
+    class Write
+      include CharacteristicHelpers
+
+      # Type flag names -> encoder method symbols
+      ENCODERS = {
+        "hex"    => :encode_hex,
+        "string" => :encode_string,
+        "uint8"  => :encode_uint8,
+        "uint16" => :encode_uint16,
+        "uint32" => :encode_uint32,
+        "int8"   => :encode_int8,
+        "int16"  => :encode_int16,
+        "int32"  => :encode_int32
+      }.freeze
+
+      # Range limits for integer types
+      RANGES = {
+        uint8:  0..255,
+        uint16: 0..65_535,
+        uint32: 0..4_294_967_295,
+        int8:   -128..127,
+        int16:  -32_768..32_767,
+        int32:  -2_147_483_648..2_147_483_647
+      }.freeze
+
+      def initialize(options)
+        @options = options
+        @formatter = options["json"] ? Formatters::Json.new : Formatters::Text.new
+        @address = options["address"]
+        @characteristic_uuid = options["characteristic"]
+        @value = options["value"]
+        @timeout = options["timeout"] || 10
+        @verify = options["verify"] || false
+      end
+
+      def execute
+        type_flag = detect_type_flag
+        encoded = encode(@value, type_flag)
+
+        connection = connect_and_discover(@address, timeout: @timeout)
+
+        begin
+          char = find_characteristic(connection, @characteristic_uuid)
+
+          # Auto-detect write mode: prefer write-with-response, fall back to write-without-response
+          response = if char.writable?
+                       true
+                     elsif char.writable_without_response?
+                       false
+                     else
+                       $stderr.puts "Error: Characteristic #{@characteristic_uuid} does not support write."
+                       $stderr.puts "Supported: #{char.flags.join(', ')}"
+                       exit 1
+                     end
+
+          name = resolve_char_name(char.uuid)
+          $stderr.puts "Writing to #{name}..."
+          char.write(encoded, response: response)
+          $stderr.puts "Write successful"
+
+          verified_value = nil
+          if @verify
+            if char.readable?
+              $stderr.puts "Verifying..."
+              raw_readback = char.read
+              verified_value = format_value(char.uuid, raw_readback)
+              $stderr.puts "Verified: #{verified_value}"
+            else
+              $stderr.puts "Warning: Cannot verify -- characteristic is not readable"
+            end
+          end
+
+          char_name = RBLE::GATT::UUIDDatabase.resolve(char.uuid, type: :characteristic)
+          @formatter.write_result(
+            address: @address,
+            uuid: char.uuid,
+            name: char_name,
+            success: true,
+            verified: verified_value,
+            written_bytes: encoded
+          )
+        ensure
+          connection.disconnect if connection.connected?
+        end
+      rescue RBLE::DeviceNotFoundError => e
+        $stderr.puts "Error: #{e.message}"
+        $stderr.puts "Run `rble scan` first to discover nearby devices."
+        exit 1
+      rescue RBLE::Error => e
+        $stderr.puts "Error: #{e.message}"
+        exit 1
+      end
+
+      private
+
+      # Detect which type flag the user set. Exactly one must be present.
+      # @return [String] The type flag name ("hex", "string", "uint8", etc.)
+      # @raise [SystemExit] if zero or multiple type flags set
+      def detect_type_flag
+        active = ENCODERS.keys.select { |flag| @options[flag] }
+
+        if active.empty?
+          $stderr.puts "Error: Exactly one type flag required: --hex, --string, --uint8, --uint16, --uint32, --int8, --int16, --int32"
+          exit 1
+        elsif active.size > 1
+          $stderr.puts "Error: Only one type flag allowed, got: #{active.map { |f| "--#{f}" }.join(', ')}"
+          exit 1
+        end
+
+        active.first
+      end
+
+      # Encode value string based on type flag.
+      # @param value_string [String] User-provided value
+      # @param type_flag [String] Type flag name
+      # @return [String] Encoded binary string
+      def encode(value_string, type_flag)
+        send(ENCODERS[type_flag], value_string)
+      end
+
+      def encode_hex(value)
+        hex = value.sub(/\A0x/i, '')
+        unless hex.match?(/\A[0-9a-fA-F]+\z/)
+          $stderr.puts "Error: Invalid hex string: '#{value}'. Expected hex digits (e.g., '0A1BFF')"
+          exit 1
+        end
+        unless hex.length.even?
+          $stderr.puts "Error: Hex string must have even length, got #{hex.length} characters"
+          exit 1
+        end
+        [hex].pack('H*')
+      end
+
+      def encode_string(value)
+        value.encode('UTF-8')
+      end
+
+      def encode_uint8(value)
+        v = parse_integer(value)
+        validate_range(v, :uint8)
+        [v].pack('C')
+      end
+
+      def encode_uint16(value)
+        v = parse_integer(value)
+        validate_range(v, :uint16)
+        [v].pack('S<')
+      end
+
+      def encode_uint32(value)
+        v = parse_integer(value)
+        validate_range(v, :uint32)
+        [v].pack('L<')
+      end
+
+      def encode_int8(value)
+        v = parse_integer(value)
+        validate_range(v, :int8)
+        [v].pack('c')
+      end
+
+      def encode_int16(value)
+        v = parse_integer(value)
+        validate_range(v, :int16)
+        [v].pack('s<')
+      end
+
+      def encode_int32(value)
+        v = parse_integer(value)
+        validate_range(v, :int32)
+        [v].pack('l<')
+      end
+
+      def parse_integer(value)
+        Integer(value, 10)
+      rescue ArgumentError
+        $stderr.puts "Error: Invalid integer: '#{value}'. Use decimal digits only."
+        exit 1
+      end
+
+      def validate_range(v, type)
+        range = RANGES[type]
+        return if range.include?(v)
+
+        $stderr.puts "Error: Value #{v} out of range for #{type} (#{range.min} to #{range.max})"
+        exit 1
+      end
+    end
+  end
+end

data/lib/rble/cli.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'rble'
+require_relative 'cli/formatters/text'
+require_relative 'cli/formatters/json'
+require_relative 'cli/adapter'
+
+module RBLE
+  module CLI
+    class Main < Thor
+      package_name "rble"
+
+      def self.namespace
+        "rble"
+      end
+
+      def self.exit_on_failure?
+        true
+      end
+
+      check_unknown_options!
+
+      class_option :json, type: :boolean, default: false,
+                          desc: "Output as JSON (NDJSON for streaming)"
+      class_option :verbose, type: :boolean, aliases: "-v", default: false,
+                             desc: "Show detailed error information"
+
+      desc "scan", "Discover nearby BLE devices"
+      method_option :timeout, type: :numeric, aliases: "-t",
+                              desc: "Stop after N seconds (default: continuous)"
+      method_option :name, type: :string, aliases: "-n",
+                           desc: "Filter by device name (case-insensitive substring)"
+      method_option :rssi, type: :numeric, aliases: "-r",
+                           desc: "Minimum RSSI threshold (e.g., -70)"
+      method_option :passive, type: :boolean, default: false,
+                              desc: "Use passive scanning (no scan requests sent)"
+      method_option :unique, type: :boolean, aliases: "-u", default: false,
+                             desc: "Show each device only once (suppress duplicate advertisements)"
+      def scan
+        require_relative 'cli/scan'
+        Scan.new(options).execute
+      end
+
+      desc "show ADDRESS", "Display GATT services and characteristics"
+      method_option :timeout, type: :numeric, aliases: "-t", default: 10,
+                              desc: "Connection timeout in seconds"
+      def show(address)
+        require_relative 'cli/show'
+        merged = options.merge("address" => address)
+        Show.new(merged).execute
+      end
+
+      desc "pair ADDRESS", "Pair with a BLE device"
+      method_option :timeout, type: :numeric, aliases: "-t", default: 30,
+                              desc: "Pairing timeout in seconds"
+      method_option :security, type: :string, aliases: "-s",
+                               desc: "Security level (low, medium, high)"
+      method_option :force, type: :boolean, default: false,
+                            desc: "Auto-accept pairing prompts"
+      def pair(address)
+        require_relative 'cli/pair'
+        merged = options.merge("address" => address)
+        Pair.new(merged).execute
+      end
+
+      desc "unpair ADDRESS", "Remove pairing bond from a device"
+      def unpair(address)
+        require_relative 'cli/unpair'
+        merged = options.merge("address" => address)
+        Unpair.new(merged).execute
+      end
+
+      desc "paired", "List bonded devices"
+      def paired
+        require_relative 'cli/paired'
+        Paired.new(options).execute
+      end
+
+      desc "read ADDRESS CHARACTERISTIC", "Read a characteristic value"
+      method_option :timeout, type: :numeric, aliases: "-t", default: 10,
+                              desc: "Connection timeout in seconds"
+      def read(address, characteristic)
+        require_relative 'cli/read'
+        merged = options.merge("address" => address, "characteristic" => characteristic)
+        Read.new(merged).execute
+      end
+
+      desc "write ADDRESS CHARACTERISTIC VALUE", "Write a value to a characteristic"
+      method_option :timeout, type: :numeric, aliases: "-t", default: 10,
+                              desc: "Connection timeout in seconds"
+      method_option :hex, type: :boolean, default: false,
+                          desc: "Value is hex bytes (e.g., '0A1BFF')"
+      method_option :string, type: :boolean, default: false,
+                             desc: "Value is UTF-8 string"
+      method_option :uint8, type: :boolean, default: false,
+                            desc: "Value is unsigned 8-bit integer"
+      method_option :uint16, type: :boolean, default: false,
+                             desc: "Value is unsigned 16-bit integer (LE)"
+      method_option :uint32, type: :boolean, default: false,
+                             desc: "Value is unsigned 32-bit integer (LE)"
+      method_option :int8, type: :boolean, default: false,
+                           desc: "Value is signed 8-bit integer"
+      method_option :int16, type: :boolean, default: false,
+                            desc: "Value is signed 16-bit integer (LE)"
+      method_option :int32, type: :boolean, default: false,
+                            desc: "Value is signed 32-bit integer (LE)"
+      method_option :verify, type: :boolean, default: false,
+                             desc: "Read back after writing to confirm"
+      def write(address, characteristic, value)
+        require_relative 'cli/write'
+        merged = options.merge("address" => address, "characteristic" => characteristic, "value" => value)
+        Write.new(merged).execute
+      end
+
+      desc "monitor ADDRESS CHARACTERISTIC", "Subscribe to characteristic notifications"
+      method_option :timeout, type: :numeric, aliases: "-t", default: 10,
+                              desc: "Connection timeout in seconds"
+      method_option :reconnect, type: :boolean, default: false,
+                                desc: "Auto-reconnect on disconnect"
+      def monitor(address, characteristic)
+        require_relative 'cli/monitor'
+        merged = options.merge("address" => address, "characteristic" => characteristic)
+        Monitor.new(merged).execute
+      end
+
+      desc "status", "Show Bluetooth adapter status"
+      method_option :adapter, type: :string, desc: "Adapter name (default: auto)"
+      def status
+        require_relative 'cli/status'
+        Status.new(options).execute
+      end
+
+      desc "doctor", "Diagnose Bluetooth problems"
+      def doctor
+        require_relative 'cli/doctor'
+        Doctor.new(options).execute
+      end
+
+      desc "adapter SUBCOMMAND", "Manage Bluetooth adapters"
+      subcommand "adapter", AdapterCli
+
+      desc "version", "Show rble version"
+      def version
+        puts "rble #{RBLE::VERSION}"
+      end
+
+      map "--version" => :version
+      map "-V" => :version
+    end
+  end
+end

data/lib/rble/company_ids.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RBLE
+  # Bluetooth SIG assigned Company Identifiers.
+  # Used to identify device manufacturers from BLE advertisement data
+  # when no device name is broadcast.
+  #
+  # Loaded on-demand (not auto-required by lib/rble.rb).
+  # Use: require 'rble/company_ids'
+  #
+  # Source: Bluetooth SIG Assigned Numbers
+  # https://www.bluetooth.com/specifications/assigned-numbers/
+  #
+  # @example Resolve a company ID
+  #   RBLE::CompanyIdentifiers.resolve(0x004C) # => "Apple"
+  module CompanyIdentifiers
+    # Curated subset of ~80 common BLE device/chipset manufacturers.
+    # Keys are 16-bit Company ID integers, values are short display names.
+    COMPANIES = {
+      0x0000 => "Ericsson",
+      0x0001 => "Nokia",
+      0x0002 => "Intel",
+      0x0004 => "Toshiba",
+      0x0006 => "Microsoft",
+      0x0008 => "Motorola",
+      0x000A => "Qualcomm",
+      0x000D => "Texas Instruments",
+      0x000F => "Broadcom",
+      0x0022 => "NEC",
+      0x0025 => "NXP",
+      0x0030 => "ST Microelectronics",
+      0x0034 => "Renesas",
+      0x003A => "Panasonic",
+      0x003C => "BlackBerry",
+      0x0040 => "Seiko Epson",
+      0x0043 => "Parrot",
+      0x0046 => "MediaTek",
+      0x0047 => "Bluegiga",
+      0x0048 => "Marvell",
+      0x004C => "Apple",
+      0x004E => "Avago",
+      0x0055 => "Plantronics",
+      0x0057 => "Harman",
+      0x0058 => "Vizio",
+      0x0059 => "Nordic Semiconductor",
+      0x005D => "Realtek",
+      0x0065 => "HP",
+      0x006B => "Polar",
+      0x0075 => "Samsung",
+      0x0076 => "Creative",
+      0x0078 => "Nike",
+      0x0087 => "Garmin",
+      0x0094 => "Airoha",
+      0x00C3 => "Adidas",
+      0x00C4 => "LG Electronics",
+      0x00E0 => "Google",
+      0x0131 => "Cypress Semiconductor",
+      0x0171 => "Amazon",
+      0x018E => "Google",
+      0x01AB => "Meta",
+      0x01DA => "Logitech",
+      0x01DD => "Philips",
+      0x01D1 => "August Home",
+      0x01FC => "Wahoo Fitness",
+      0x027D => "Huawei",
+      0x02E5 => "Espressif",
+      0x02FF => "Silicon Labs",
+      0x038F => "Xiaomi",
+      0x03C1 => "Ember Technologies",
+      0x03FF => "Withings",
+      0x040F => "OnePlus",
+      0x0499 => "Ruuvi Innovations",
+      0x05A7 => "Sonos",
+      0x060F => "Signify",
+      0x067C => "Tile",
+      0x0768 => "Peloton",
+      0x07D0 => "Tuya",
+      0x07D6 => "Ecobee",
+      0x079A => "Roku",
+    }.freeze
+
+    # Resolve a company identifier to a human-readable name.
+    #
+    # @param company_id [Integer] 16-bit Bluetooth SIG Company Identifier
+    # @return [String, nil] Company name, or nil if unknown
+    def self.resolve(company_id)
+      COMPANIES[company_id]
+    end
+  end
+end