rble 0.7.0

data/lib/rble/cli/doctor.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'etc'
+begin
+  require_relative '../bluez'
+rescue LoadError
+  # BlueZ backend not available (non-Linux platform)
+end
+
+module RBLE
+  module CLI
+    class Doctor
+      def initialize(options)
+        @options = options
+      end
+
+      def execute
+        results = run_checks
+
+        if @options["json"]
+          print_json(results)
+        else
+          print_text(results)
+        end
+
+        has_errors = results.any? { |r| r[:severity] == :error }
+        exit 1 if has_errors
+      end
+
+      private
+
+      def linux?
+        RUBY_PLATFORM.include?('linux')
+      end
+
+      def run_checks
+        checks = %i[check_adapter_present check_adapter_powered]
+
+        if linux?
+          checks = %i[
+            check_ruby_dbus
+            check_kernel_module
+            check_bluetoothd_running
+            check_dbus_permissions
+            check_adapter_present
+            check_adapter_powered
+            check_rfkill
+            check_bluetooth_group
+            check_bluetoothd_version
+          ]
+        end
+
+        checks.filter_map do |check|
+          begin
+            send(check)
+          rescue => e
+            { severity: :warning, title: check.to_s.sub("check_", "").tr("_", " "),
+              message: "Check failed: #{e.message}" }
+          end
+        end
+      end
+
+      def print_text(results)
+        # Phase 1: Compact checklist
+        results.each do |result|
+          case result[:severity]
+          when :info
+            extra = compact_extra(result)
+            puts "  OK  #{result[:title]}#{extra}"
+          when :warning
+            puts "WARN  #{result[:title]}"
+          when :error
+            puts "FAIL  #{result[:title]}"
+          end
+        end
+
+        # Phase 2: Summary line
+        issues = results.select { |r| r[:severity] == :error || r[:severity] == :warning }
+        puts
+        if issues.empty?
+          puts "All checks passed"
+        else
+          puts "#{issues.size} issue#{'s' unless issues.size == 1} found:"
+
+          # Phase 3: Detailed issue section
+          puts
+          issues.each do |result|
+            label = result[:severity] == :error ? "ERROR" : "WARNING"
+            puts "  #{label}: #{result[:title]}"
+            puts "    #{result[:message]}"
+            puts "    Fix: #{result[:fix]}" if result[:fix]
+            puts
+          end
+        end
+      end
+
+      def compact_extra(result)
+        case result[:title]
+        when "Bluetooth adapter"
+          if result[:message] =~ /Adapter (\S+) found \(([^)]+)\)/
+            " (#{$1} #{$2})"
+          else
+            ""
+          end
+        when "BlueZ version"
+          if result[:message] =~ /BlueZ (.+)/
+            " (#{$1})"
+          else
+            ""
+          end
+        else
+          ""
+        end
+      end
+
+      def print_json(results)
+        errors = results.count { |r| r[:severity] == :error }
+        warnings = results.count { |r| r[:severity] == :warning }
+        info = results.count { |r| r[:severity] == :info }
+
+        output = {
+          summary: { errors: errors, warnings: warnings, info: info },
+          checks: results.map { |r|
+            h = { severity: r[:severity].to_s, title: r[:title], message: r[:message] }
+            h[:fix] = r[:fix] if r[:fix]
+            h
+          }
+        }
+
+        puts JSON.generate(output)
+      end
+
+      # Check 0: ruby-dbus gem available (Linux only)
+      def check_ruby_dbus
+        require 'dbus'
+        { severity: :info, title: "ruby-dbus gem", message: "ruby-dbus gem is available" }
+      rescue LoadError
+        { severity: :error, title: "ruby-dbus gem",
+          message: "ruby-dbus gem is not installed. The BlueZ backend requires it.",
+          fix: "gem install ruby-dbus" }
+      end
+
+      # Check 1: Kernel module loaded
+      def check_kernel_module
+        if File.exist?("/sys/module/bluetooth")
+          { severity: :info, title: "Kernel module", message: "Bluetooth kernel module is loaded" }
+        else
+          { severity: :error, title: "Kernel module",
+            message: "Bluetooth kernel module is not loaded",
+            fix: "sudo modprobe bluetooth" }
+        end
+      end
+
+      # Check 2: bluetoothd running
+      def check_bluetoothd_running
+        running = if command_exists?("systemctl")
+                    system("systemctl", "is-active", "--quiet", "bluetooth")
+                  elsif command_exists?("pgrep")
+                    system("pgrep", "-x", "bluetoothd", out: File::NULL, err: File::NULL)
+                  else
+                    return nil
+                  end
+
+        if running
+          { severity: :info, title: "Bluetooth daemon", message: "bluetoothd is running" }
+        else
+          { severity: :error, title: "Bluetooth daemon",
+            message: "bluetoothd service is not active",
+            fix: "sudo systemctl start bluetooth" }
+        end
+      end
+
+      # Check 3: D-Bus permissions
+      def check_dbus_permissions
+        conn = RBLE::BlueZ::DBusConnection.new
+        conn.connect
+        conn.disconnect
+        { severity: :info, title: "D-Bus access", message: "Can connect to BlueZ D-Bus service" }
+      rescue => e
+        { severity: :error, title: "D-Bus access",
+          message: "Cannot connect to BlueZ D-Bus service: #{e.message}",
+          fix: "Ensure bluetoothd is running: sudo systemctl start bluetooth" }
+      end
+
+      # Check 4: Adapter present
+      def check_adapter_present
+        backend = RBLE::Backend.for_platform
+        adapters = backend.adapters
+        if adapters.empty?
+          { severity: :error, title: "Bluetooth adapter",
+            message: "No Bluetooth adapter found",
+            fix: "Check that adapter is plugged in or not blocked by rfkill" }
+        else
+          @first_adapter = adapters.first
+          { severity: :info, title: "Bluetooth adapter",
+            message: "Adapter #{@first_adapter[:name]} found (#{@first_adapter[:address]})" }
+        end
+      rescue RBLE::AdapterNotFoundError
+        { severity: :error, title: "Bluetooth adapter",
+          message: "No Bluetooth adapter found",
+          fix: "Check that adapter is plugged in or not blocked by rfkill" }
+      end
+
+      # Check 5: Adapter powered
+      def check_adapter_powered
+        return nil unless @first_adapter
+
+        if @first_adapter[:powered]
+          { severity: :info, title: "Adapter power", message: "Adapter is powered on" }
+        else
+          { severity: :error, title: "Adapter power",
+            message: "Adapter #{@first_adapter[:name]} is not powered on",
+            fix: "rble adapter power on" }
+        end
+      end
+
+      # Check 6: rfkill blocks
+      def check_rfkill
+        return nil unless command_exists?("rfkill")
+
+        output, success = run_command("rfkill --json 2>/dev/null")
+        unless success
+          output, success = run_command("rfkill list bluetooth 2>/dev/null")
+          return nil unless success
+          return parse_rfkill_text(output)
+        end
+
+        data = JSON.parse(output)
+        bt_devices = data.dig("rfkilldevices")&.select { |d| d["type"] == "bluetooth" } || []
+
+        if bt_devices.empty?
+          { severity: :info, title: "RF kill", message: "No Bluetooth devices in rfkill" }
+        else
+          hard_blocked = bt_devices.any? { |d| d["hard"] == "blocked" }
+          soft_blocked = bt_devices.any? { |d| d["soft"] == "blocked" }
+
+          if hard_blocked
+            { severity: :error, title: "RF kill",
+              message: "Bluetooth is hard-blocked (hardware switch)",
+              fix: "Check for a physical Bluetooth/wireless switch on your device" }
+          elsif soft_blocked
+            { severity: :error, title: "RF kill",
+              message: "Bluetooth is soft-blocked by rfkill",
+              fix: "sudo rfkill unblock bluetooth" }
+          else
+            { severity: :info, title: "RF kill", message: "Bluetooth is not blocked" }
+          end
+        end
+      end
+
+      # Check 7: User in bluetooth group
+      def check_bluetooth_group
+        group = Etc.getgrnam("bluetooth")
+        if Process.groups.include?(group.gid)
+          { severity: :info, title: "Bluetooth group",
+            message: "User is in 'bluetooth' group" }
+        else
+          username = Etc.getlogin || ENV["USER"] || "unknown"
+          { severity: :warning, title: "Bluetooth group",
+            message: "User '#{username}' is not a member of the 'bluetooth' group",
+            fix: "sudo usermod -aG bluetooth #{username}" }
+        end
+      rescue ArgumentError
+        { severity: :info, title: "Bluetooth group",
+          message: "'bluetooth' group does not exist on this system" }
+      end
+
+      # Check 8: bluetoothd version
+      def check_bluetoothd_version
+        return nil unless command_exists?("bluetoothd")
+
+        output, success = run_command("bluetoothd --version 2>/dev/null")
+        return nil unless success
+
+        version = output.strip
+        return nil if version.empty?
+
+        { severity: :info, title: "BlueZ version", message: "BlueZ #{version}" }
+      end
+
+      def command_exists?(cmd)
+        system("which", cmd, out: File::NULL, err: File::NULL)
+      end
+
+      def run_command(cmd)
+        output = `#{cmd}`
+        [output, $?.success?]
+      end
+
+      def parse_rfkill_text(output)
+        hard_blocked = output.include?("Hard blocked: yes")
+        soft_blocked = output.include?("Soft blocked: yes")
+
+        if hard_blocked
+          { severity: :error, title: "RF kill",
+            message: "Bluetooth is hard-blocked (hardware switch)",
+            fix: "Check for a physical Bluetooth/wireless switch on your device" }
+        elsif soft_blocked
+          { severity: :error, title: "RF kill",
+            message: "Bluetooth is soft-blocked by rfkill",
+            fix: "sudo rfkill unblock bluetooth" }
+        else
+          { severity: :info, title: "RF kill", message: "Bluetooth is not blocked" }
+        end
+      end
+    end
+  end
+end

data/lib/rble/cli/formatters/json.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'rble/company_ids'
+
+module RBLE
+  module CLI
+    module Formatters
+      class Json
+        def device(device)
+          data = {
+            address: device.address,
+            name: device.name,
+            rssi: device.rssi,
+            address_type: device.address_type
+          }
+
+          if device.manufacturer_data.any?
+            company_id = device.manufacturer_data.keys.first
+            data[:company_id] = company_id
+            data[:company] = RBLE::CompanyIdentifiers.resolve(company_id)
+          end
+
+          puts JSON.generate(data)
+        end
+
+        def status(info)
+          puts JSON.generate(info)
+        end
+
+        def adapter_list(adapters)
+          puts JSON.generate(adapters)
+        end
+
+        def adapter_confirm(message)
+          puts JSON.generate({ status: "ok", message: message })
+        end
+
+        def paired_list(devices)
+          puts JSON.generate(devices)
+        end
+
+        def pair_result(success:, address:, message:)
+          puts JSON.generate({
+            status: success ? "ok" : "error",
+            address: address,
+            message: message
+          })
+        end
+
+        def read_value(address:, uuid:, name:, raw:, formatted:)
+          puts JSON.generate({
+            address: address,
+            characteristic: {
+              uuid: uuid,
+              name: name,
+              value: formatted,
+              raw_hex: raw.bytes.map { |b| format("%02x", b) }.join
+            }
+          })
+        end
+
+        def write_result(address:, uuid:, name:, success:, verified: nil, written_bytes: nil)
+          output = {
+            address: address,
+            characteristic: {
+              uuid: uuid,
+              name: name
+            },
+            status: success ? "ok" : "error"
+          }
+          output[:written] = written_bytes.bytes if written_bytes
+          output[:verified] = verified unless verified.nil?
+          puts JSON.generate(output)
+        end
+
+        def monitor_value(address:, uuid:, name:, raw:, formatted:, timestamp:)
+          puts JSON.generate({
+            timestamp: timestamp.iso8601(3),
+            address: address,
+            uuid: uuid,
+            name: name,
+            raw_hex: raw.bytes.map { |b| format("%02x", b) }.join,
+            value: formatted
+          })
+        end
+
+        def show_tree(tree_data)
+          output = {
+            address: tree_data[:address],
+            name: tree_data[:name],
+            services: tree_data[:services].map do |service|
+              {
+                uuid: service[:uuid],
+                name: service[:resolved_name],
+                primary: service[:primary],
+                characteristics: service[:characteristics].map do |char|
+                  {
+                    uuid: char[:uuid],
+                    name: char[:resolved_name],
+                    properties: char[:properties],
+                    handle: char[:handle],
+                    descriptors: (char[:descriptors] || []).map do |desc|
+                      {
+                        uuid: desc[:uuid],
+                        name: desc[:resolved_name],
+                        handle: desc[:handle]
+                      }
+                    end
+                  }
+                end
+              }
+            end
+          }
+
+          puts JSON.generate(output)
+        end
+      end
+    end
+  end
+end

data/lib/rble/cli/formatters/text.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'rble/company_ids'
+
+module RBLE
+  module CLI
+    module Formatters
+      class Text
+        def device(device)
+          name = truncate(device.name || company_label(device) || "(unknown)", 25)
+          rssi_str = device.rssi ? format("%4d dBm", device.rssi) : "     N/A"
+          puts format("%-17s  %-25s  %s  %s", device.address, name, rssi_str, device.address_type)
+        end
+
+        def status(info)
+          puts "Adapter:       #{info[:name]}"
+          puts "Address:       #{info[:address]}"
+          puts "Alias:         #{info[:alias]}" if info[:alias]
+          puts "Powered:       #{info[:powered] ? 'yes' : 'no'}"
+          puts "Discoverable:  #{info[:discoverable] ? 'yes' : 'no'}"
+          puts "Pairable:      #{info[:pairable] ? 'yes' : 'no'}"
+          puts "Discovering:   #{info[:discovering] ? 'yes' : 'no'}"
+        end
+
+        def adapter_list(adapters)
+          if adapters.empty?
+            puts "No Bluetooth adapters found"
+            return
+          end
+
+          adapters.each do |a|
+            powered = a[:powered] ? "up" : "down"
+            puts format("%-8s  %-17s  %s", a[:name], a[:address], powered)
+          end
+        end
+
+        def adapter_confirm(message)
+          puts message
+        end
+
+        def paired_list(devices)
+          if devices.empty?
+            puts "No bonded devices"
+            return
+          end
+
+          devices.each do |device|
+            name = truncate(device[:name] || "Unknown", 25)
+            connected_str = device[:connected] ? "connected" : "not connected"
+            type_str = device[:address_type] == "random" ? "BLE (random)" : "BLE (public)"
+            puts format("%-17s  %-25s  %-13s  %s", device[:address], name, connected_str, type_str)
+          end
+
+          puts "\n#{devices.size} bonded device#{'s' unless devices.size == 1}"
+        end
+
+        def pair_result(success:, address:, message:)
+          # Text mode: status already printed on stderr, no stdout output needed
+        end
+
+        def read_value(address:, uuid:, name:, raw:, formatted:)
+          short = RBLE::GATT::UUIDDatabase.extract_short_uuid(uuid)
+          label = name ? "#{name} (#{short})" : short
+          puts "#{label}: #{formatted}"
+        end
+
+        def write_result(address:, uuid:, name:, success:, verified: nil, written_bytes: nil)
+          # Text mode: status already printed on stderr, no stdout output needed
+        end
+
+        def monitor_value(address:, uuid:, name:, raw:, formatted:, timestamp:)
+          ts = timestamp.strftime("%H:%M:%S.%L")
+          label = name || uuid
+          puts "[#{ts}] #{label}: #{formatted}"
+        end
+
+        def show_tree(tree_data)
+          header = if tree_data[:name]
+                     "#{tree_data[:name]} (#{tree_data[:address]})"
+                   else
+                     tree_data[:address]
+                   end
+          service_count = tree_data[:services].size
+          char_count = tree_data[:total_characteristics]
+          puts "#{header} - #{service_count} service#{'s' unless service_count == 1}, " \
+               "#{char_count} characteristic#{'s' unless char_count == 1}"
+          puts
+
+          tree_data[:services].each do |service|
+            puts format_uuid_line(service[:uuid], service[:resolved_name], type: :service)
+
+            chars = service[:characteristics]
+            chars.each_with_index do |char, ci|
+              last_char = ci == chars.size - 1
+              char_prefix = last_char ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 "
+              props = "(#{char[:properties].join(', ')})"
+              char_line = format_uuid_line(char[:uuid], char[:resolved_name], type: :characteristic)
+              puts "#{char_prefix}#{char_line} #{props}"
+
+              descs = char[:descriptors] || []
+              descs.each_with_index do |desc, di|
+                last_desc = di == descs.size - 1
+                vert = last_char ? "    " : "\u2502   "
+                desc_prefix = last_desc ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 "
+                desc_line = format_uuid_line(desc[:uuid], desc[:resolved_name], type: :descriptor)
+                puts "#{vert}#{desc_prefix}#{desc_line}"
+              end
+            end
+            puts
+          end
+        end
+
+        private
+
+        def format_uuid_line(uuid, resolved_name, type:)
+          type_label = case type
+                       when :service then "Service"
+                       when :characteristic then "Characteristic"
+                       when :descriptor then "Descriptor"
+                       else "Unknown"
+                       end
+
+          is_standard = RBLE::GATT::UUIDDatabase.standard_uuid?(uuid)
+          short = RBLE::GATT::UUIDDatabase.extract_short_uuid(uuid)
+
+          if resolved_name
+            if is_standard
+              "#{resolved_name} [0x#{short.upcase}]"
+            else
+              "#{resolved_name} [#{uuid}]"
+            end
+          else
+            if is_standard
+              "Unknown #{type_label} [0x#{short.upcase}]"
+            else
+              "Unknown #{type_label} [#{uuid}]"
+            end
+          end
+        end
+
+        def company_label(device)
+          return nil if device.manufacturer_data.empty?
+
+          company_id = device.manufacturer_data.keys.first
+          name = RBLE::CompanyIdentifiers.resolve(company_id)
+          name ? "(#{name})" : nil
+        end
+
+        def truncate(str, max)
+          return str if str.length <= max
+
+          str[0, max - 1] + "~"
+        end
+      end
+    end
+  end
+end

data/lib/rble/cli/hex_dump.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RBLE
+  module CLI
+    # Hex + ASCII dump formatter for unknown BLE characteristic data.
+    #
+    # Produces output similar to `hexdump -C` with hex bytes on the left
+    # and printable ASCII on the right, wrapped in pipe delimiters.
+    #
+    # @example Short data (single line)
+    #   HexDump.format("\x10\x41\x00\xFF".b)
+    #   # => "10 41 00 FF  |.A..|"
+    #
+    # @example Multi-line data
+    #   HexDump.format(long_data)
+    #   # => "41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50  |ABCDEFGHIJKLMNOP|"
+    #   #    "51 52 53 54                                        |QRST|"
+    module HexDump
+      BYTES_PER_ROW = 16
+
+      # Format raw bytes as hex + ASCII dump.
+      #
+      # @param raw_bytes [String, nil] Binary string to format
+      # @return [String] Formatted hex+ASCII dump (empty string if no data)
+      def self.format(raw_bytes)
+        return "" if raw_bytes.nil? || raw_bytes.empty?
+
+        bytes = raw_bytes.bytes
+        rows = bytes.each_slice(BYTES_PER_ROW).map { |row| format_row(row) }
+        rows.join("\n")
+      end
+
+      # Format a single row of bytes.
+      #
+      # @param row [Array<Integer>] Up to 16 bytes
+      # @return [String] Formatted row with hex and ASCII sections
+      def self.format_row(row)
+        hex = row.map { |b| "%02X" % b }.join(' ')
+        # Pad hex section to consistent width: 16 * 3 - 1 = 47 chars
+        hex = hex.ljust(47)
+        ascii = row.map { |b| (0x20..0x7E).include?(b) ? b.chr : '.' }.join
+        "#{hex}  |#{ascii}|"
+      end
+
+      private_class_method :format_row
+    end
+  end
+end