rble 0.7.0

data/lib/rble/tasks/check.rake

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+namespace :rble do
+  desc 'Check system BLE readiness'
+  task :check do
+    require_relative '../../rble'
+
+    checker = RBLE::SystemChecker.new
+    checker.run
+    exit(checker.success? ? 0 : 1)
+  end
+end
+
+module RBLE
+  # System BLE readiness checker
+  #
+  # Validates that the system is properly configured for BLE operations.
+  # Performs platform-specific checks and provides actionable fix suggestions.
+  #
+  # @api private
+  class SystemChecker
+    def initialize
+      @checks_run = 0
+      @failures = []
+      @suggestions = {}
+    end
+
+    # Run all platform-specific checks
+    def run
+      puts "RBLE System Check"
+      puts "=" * 40
+      puts
+
+      case RUBY_PLATFORM
+      when /linux/
+        run_linux_checks
+      when /darwin/
+        run_macos_checks
+      else
+        puts "[FAIL] Unsupported platform: #{RUBY_PLATFORM}"
+        @failures << "Unsupported platform"
+        return
+      end
+
+      print_summary
+      print_suggestions unless @failures.empty?
+    end
+
+    # Check if all checks passed
+    # @return [Boolean]
+    def success?
+      @failures.empty?
+    end
+
+    private
+
+    # Run a single check with standardized output
+    #
+    # @param name [String] Check name
+    # @param suggestion [String, nil] Fix suggestion if check fails
+    # @yield Block that returns truthy/falsy result
+    def check(name, suggestion: nil)
+      @checks_run += 1
+      result = yield
+      if result
+        puts "[OK] #{name}"
+        true
+      else
+        puts "[FAIL] #{name}"
+        @failures << name
+        @suggestions[name] = suggestion if suggestion
+        false
+      end
+    rescue StandardError => e
+      puts "[FAIL] #{name}: #{e.message}"
+      @failures << name
+      @suggestions[name] = suggestion if suggestion
+      false
+    end
+
+    # Linux-specific BLE readiness checks
+    def run_linux_checks
+      puts "Platform: Linux"
+      puts
+
+      check("BlueZ D-Bus service",
+            suggestion: "Install BlueZ: sudo apt install bluez") do
+        system("busctl list 2>/dev/null | grep -q org.bluez")
+      end
+
+      check("bluetoothd running",
+            suggestion: "Start Bluetooth: sudo systemctl start bluetooth") do
+        system("systemctl is-active --quiet bluetooth 2>/dev/null") ||
+          system("pgrep -x bluetoothd >/dev/null 2>&1")
+      end
+
+      check("Bluetooth adapter found",
+            suggestion: "No adapter found. Connect USB adapter or enable built-in.") do
+        RBLE.adapters.any?
+      end
+
+      check("Bluetooth adapter powered",
+            suggestion: "Enable adapter: bluetoothctl power on") do
+        RBLE.adapters.any? { |a| a[:powered] }
+      end
+    end
+
+    # macOS-specific BLE readiness checks
+    def run_macos_checks
+      puts "Platform: macOS"
+      puts
+
+      # Determine helper path relative to gem root
+      helper_path = File.expand_path('../../../ext/macos_ble/.build/release/RBLEHelper', __dir__)
+
+      helper_exists = check("Helper binary exists",
+                            suggestion: "Build helper: rake build:macos") do
+        File.exist?(helper_path)
+      end
+
+      helper_executable = check("Helper binary executable",
+                                suggestion: "Fix permissions: chmod +x #{helper_path}") do
+        File.executable?(helper_path)
+      end
+
+      # Only try RBLE operations if helper exists and is executable
+      # This avoids triggering CoreBluetooth permission prompts unnecessarily
+      if helper_exists && helper_executable
+        check("Bluetooth powered",
+              suggestion: "Enable Bluetooth in System Settings > Bluetooth") do
+          RBLE.adapters.any? { |a| a[:powered] }
+        end
+      end
+    end
+
+    # Print summary of check results
+    def print_summary
+      puts
+      passed = @checks_run - @failures.length
+      puts "#{passed}/#{@checks_run} checks passed"
+    end
+
+    # Print grouped fix suggestions for failures
+    def print_suggestions
+      puts
+      puts "Suggestions:"
+      @failures.each do |name|
+        if (suggestion = @suggestions[name])
+          puts "  - #{name}: #{suggestion}"
+        end
+      end
+    end
+  end
+end

data/lib/rble/tasks/integration.rake

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+namespace :test do
+  desc 'Run integration test with real BLE hardware'
+  task :integration do
+    require_relative '../../rble'
+
+    test = RBLE::IntegrationTest.new
+    test.run
+    exit(test.success? ? 0 : 1)
+  end
+end
+
+module RBLE
+  # Dynamic integration test for BLE hardware
+  #
+  # Scans for devices, then tries each device until finding one with
+  # a readable characteristic. Prioritizes devices advertising Device
+  # Information Service (0x180A) for reliability.
+  #
+  # @api private
+  class IntegrationTest
+    DEVICE_INFO_SERVICE = '180a'
+    MANUFACTURER_NAME = '2a29'
+    MODEL_NUMBER = '2a24'
+    SCAN_TIMEOUT = 5
+    CONNECTION_TIMEOUT = 10
+
+    def initialize
+      @success = false
+      @connection = nil
+      @results = []
+      @devices = []
+    end
+
+    # Run the integration test
+    def run
+      scan_for_devices
+      return if @devices.empty?
+
+      try_devices_until_success
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+      @results << "Error: #{e.class} - #{e.message}"
+    ensure
+      cleanup
+      print_summary
+    end
+
+    # Check if test passed
+    # @return [Boolean]
+    def success?
+      @success
+    end
+
+    private
+
+    def scan_for_devices
+      puts "Scanning for BLE devices (#{SCAN_TIMEOUT}s timeout)..."
+
+      scanner = Scanner.new(timeout: SCAN_TIMEOUT)
+      scanner.start do |device|
+        # Deduplicate by address
+        unless @devices.any? { |d| d.address == device.address }
+          @devices << device
+        end
+      end
+
+      if @devices.empty?
+        puts
+        puts "No BLE devices found."
+        puts "Suggestions:"
+        puts "  - Ensure BLE devices are nearby and advertising"
+        puts "  - Check that Bluetooth adapter is enabled (rake rble:check)"
+        puts "  - Try increasing scan time or moving closer to devices"
+        @results << "No devices found"
+        return
+      end
+
+      puts "Found #{@devices.length} device(s)"
+      @results << "Scanned and found #{@devices.length} device(s)"
+
+      # Sort: prefer devices with Device Information Service
+      @devices.sort_by! do |d|
+        has_device_info = d.service_uuids.any? { |uuid| uuid.downcase.include?(DEVICE_INFO_SERVICE) }
+        has_device_info ? 0 : 1
+      end
+    end
+
+    def try_devices_until_success
+      @devices.each_with_index do |device, index|
+        device_name = device.name || 'unnamed'
+        puts
+        puts "Trying device #{index + 1}/#{@devices.length}: #{device_name} (#{device.address})"
+
+        result = try_device(device)
+        if result == :success
+          @success = true
+          return
+        end
+        # Continue to next device on :no_readable or :connection_failed
+      end
+
+      puts
+      puts "Tried all #{@devices.length} device(s), none had readable characteristics"
+      @results << "No device with readable characteristics found"
+    end
+
+    # Try a single device: connect, discover, read
+    # Returns :success, :no_readable, or :connection_failed
+    def try_device(device)
+      # Connect
+      puts "  Connecting..."
+      begin
+        @connection = RBLE.connect(device.address, timeout: CONNECTION_TIMEOUT)
+        puts "  Connected!"
+      rescue ConnectionTimeoutError
+        puts "  Connection timed out, skipping..."
+        return :connection_failed
+      rescue ConnectionError => e
+        puts "  Connection failed: #{e.message}, skipping..."
+        return :connection_failed
+      end
+
+      # Discover services
+      puts "  Discovering services..."
+      services = @connection.discover_services
+      char_count = services.sum { |s| s.characteristics.length }
+      puts "  Found #{services.length} services, #{char_count} characteristics"
+
+      # Find and read a characteristic
+      char = find_readable_characteristic(services)
+      unless char
+        puts "  No readable characteristics, trying next device..."
+        disconnect_quietly
+        return :no_readable
+      end
+
+      # Read the characteristic
+      puts "  Reading #{char_name(char)} (#{char.short_uuid})..."
+      value = char.read
+      display = format_value(value)
+      puts "  Value: #{display.inspect}"
+
+      # Record success
+      device_name = device.name || 'unnamed'
+      @results << "Connected to #{device_name}"
+      @results << "Discovered #{services.length} services"
+      truncated = display.length > 50 ? "#{display[0..47]}..." : display
+      @results << "Read characteristic #{char.short_uuid}: #{truncated}"
+
+      :success
+    rescue StandardError => e
+      puts "  Error: #{e.message}, trying next device..."
+      disconnect_quietly
+      :connection_failed
+    end
+
+    def find_readable_characteristic(services)
+      # First try Device Information Service
+      device_info = services.find { |s| s.short_uuid == DEVICE_INFO_SERVICE }
+
+      if device_info
+        # Prefer Manufacturer Name, then Model Number
+        [MANUFACTURER_NAME, MODEL_NUMBER].each do |uuid|
+          char = device_info.characteristics.find { |c| c.short_uuid == uuid && c.readable? }
+          return char if char
+        end
+
+        # Try any readable char in Device Info service
+        char = device_info.characteristics.find(&:readable?)
+        return char if char
+      end
+
+      # Fallback: any readable characteristic from any service
+      services.each do |service|
+        char = service.characteristics.find(&:readable?)
+        return char if char
+      end
+
+      nil
+    end
+
+    def format_value(value)
+      if value.bytes.all? { |b| (b >= 32 && b < 127) || b == 0 }
+        # Remove null terminators and clean up
+        value.force_encoding('UTF-8').gsub("\x00", '')
+      else
+        # Display as hex for binary data
+        value.bytes.map { |b| format('%02x', b) }.join(' ')
+      end
+    end
+
+    def char_name(char)
+      case char.short_uuid
+      when MANUFACTURER_NAME then 'Manufacturer Name'
+      when MODEL_NUMBER then 'Model Number'
+      when '2a25' then 'Serial Number'
+      when '2a27' then 'Hardware Revision'
+      when '2a26' then 'Firmware Revision'
+      when '2a28' then 'Software Revision'
+      else 'Characteristic'
+      end
+    end
+
+    def disconnect_quietly
+      return unless @connection
+
+      @connection.disconnect if @connection.connected?
+    rescue StandardError
+      # Ignore disconnect errors
+    ensure
+      @connection = nil
+    end
+
+    def cleanup
+      return unless @connection
+
+      begin
+        if @connection.connected?
+          puts
+          puts "Disconnecting..."
+          @connection.disconnect
+          puts "Disconnected"
+        end
+      rescue StandardError => e
+        puts "Disconnect warning: #{e.message}"
+      end
+    end
+
+    def print_summary
+      puts
+      puts '=' * 40
+      if @success
+        puts 'Integration test PASSED'
+      else
+        puts 'Integration test FAILED'
+      end
+      @results.each { |r| puts "  - #{r}" }
+    end
+  end
+end

data/lib/rble/tasks.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Load all RBLE rake tasks
+# Usage in Rakefile: require 'rble/tasks'
+
+Dir.glob(File.join(__dir__, 'tasks', '*.rake')).each do |task_file|
+  load task_file
+end

data/lib/rble/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RBLE
+  VERSION = '0.7.0'
+end

data/lib/rble.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'rble/version'
+require_relative 'rble/errors'
+require_relative 'rble/device'
+require_relative 'rble/service'
+require_relative 'rble/characteristic'
+require_relative 'rble/backend'
+require_relative 'rble/scanner'
+require_relative 'rble/connection'
+
+module RBLE
+  class << self
+    # Logger for debug output
+    # Set to a Logger instance with debug level to see notification flow
+    # @example
+    #   RBLE.logger = Logger.new(STDOUT)
+    #   RBLE.logger.level = Logger::DEBUG
+    attr_accessor :logger
+
+    # Enable trace-level output for connection timing and D-Bus call flow
+    # @example
+    #   RBLE.trace = true
+    attr_accessor :trace
+
+    # Global warning flag. Defaults to true.
+    # Set to false to suppress feature-level warnings from RBLE.
+    # @example
+    #   RBLE.warnings = false
+    attr_writer :warnings
+
+    def warnings
+      @warnings.nil? ? true : @warnings
+    end
+
+    # Output a warning with [RBLE] prefix, respecting RBLE.warnings flag.
+    # @param message [String] Warning message
+    def rble_warn(message)
+      return unless warnings
+
+      warn "[RBLE] #{message}"
+    end
+  end
+
+  # Backend selection API - delegates to RBLE::Backend
+
+  def self.backend
+    Backend.backend
+  end
+
+  def self.backend=(value)
+    Backend.backend = value
+  end
+
+  def self.available_backends
+    Backend.available_backends
+  end
+
+  def self.backend_info
+    Backend.backend_info
+  end
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: rble
+version: !ruby/object:Gem::Version
+  version: 0.7.0
+platform: ruby
+authors:
+- Jonas Tehler
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: Reliable BLE communication for Ruby - scanning, connections, GATT operations
+  on Linux (BlueZ/D-Bus) and macOS (CoreBluetooth). Includes standalone rble CLI tool.
+email:
+- jonas@tehler.se
+executables:
+- rble
+extensions:
+- ext/macos_ble/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/rble
+- ext/macos_ble/Package.swift
+- ext/macos_ble/Sources/RBLEHelper/BLEManager.swift
+- ext/macos_ble/Sources/RBLEHelper/Protocol.swift
+- ext/macos_ble/Sources/RBLEHelper/main.swift
+- ext/macos_ble/extconf.rb
+- lib/rble.rb
+- lib/rble/backend.rb
+- lib/rble/backend/base.rb
+- lib/rble/backend/bluez.rb
+- lib/rble/backend/corebluetooth.rb
+- lib/rble/bluez.rb
+- lib/rble/bluez/adapter.rb
+- lib/rble/bluez/async_call.rb
+- lib/rble/bluez/async_connection_operations.rb
+- lib/rble/bluez/async_gatt_operations.rb
+- lib/rble/bluez/async_introspection.rb
+- lib/rble/bluez/dbus_connection.rb
+- lib/rble/bluez/dbus_session.rb
+- lib/rble/bluez/device.rb
+- lib/rble/bluez/event_loop.rb
+- lib/rble/bluez/gatt_operation_queue.rb
+- lib/rble/bluez/pairing_agent.rb
+- lib/rble/bluez/pairing_session.rb
+- lib/rble/bluez/retry_policy.rb
+- lib/rble/characteristic.rb
+- lib/rble/cli.rb
+- lib/rble/cli/adapter.rb
+- lib/rble/cli/characteristic_helpers.rb
+- lib/rble/cli/doctor.rb
+- lib/rble/cli/formatters/json.rb
+- lib/rble/cli/formatters/text.rb
+- lib/rble/cli/hex_dump.rb
+- lib/rble/cli/monitor.rb
+- lib/rble/cli/pair.rb
+- lib/rble/cli/paired.rb
+- lib/rble/cli/read.rb
+- lib/rble/cli/scan.rb
+- lib/rble/cli/show.rb
+- lib/rble/cli/status.rb
+- lib/rble/cli/unpair.rb
+- lib/rble/cli/value_parser.rb
+- lib/rble/cli/write.rb
+- lib/rble/company_ids.rb
+- lib/rble/connection.rb
+- lib/rble/device.rb
+- lib/rble/errors.rb
+- lib/rble/gatt/uuid_database.rb
+- lib/rble/scanner.rb
+- lib/rble/service.rb
+- lib/rble/tasks.rb
+- lib/rble/tasks/check.rake
+- lib/rble/tasks/integration.rake
+- lib/rble/version.rb
+homepage: https://github.com/jegt/rble
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jegt/rble
+  source_code_uri: https://github.com/jegt/rble/tree/main
+  changelog_uri: https://github.com/jegt/rble/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/jegt/rble/blob/main/README.md
+  bug_tracker_uri: https://github.com/jegt/rble/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.7
+specification_version: 4
+summary: BLE communication library for Ruby with CoreBluetooth and BlueZ backends
+test_files: []