rble 0.7.0

data/ext/macos_ble/extconf.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Extension configuration for macOS BLE helper
+# This runs during `gem install` to compile the Swift CLI
+
+require 'mkmf'
+
+# Create a dummy Makefile - actual build happens below
+# We need a Makefile for RubyGems to consider the extension "built"
+File.write('Makefile', <<~MAKEFILE)
+  .PHONY: all install clean
+
+  all:
+  \t@echo "Swift build completed during extconf.rb"
+
+  install:
+  \t@echo "No install step needed"
+
+  clean:
+  \t@echo "Run 'swift package clean' to clean Swift build"
+MAKEFILE
+
+# Only build on macOS
+unless RUBY_PLATFORM.include?('darwin')
+  puts 'Skipping macOS BLE helper build (not on macOS)'
+  exit 0
+end
+
+# Check for Swift
+swift_path = find_executable('swift')
+unless swift_path
+  warn <<~MSG
+
+    WARNING: Swift compiler not found.
+    The macOS BLE helper requires Swift to compile.
+    Install Xcode or Xcode Command Line Tools:
+      xcode-select --install
+
+    You can build manually later with:
+      cd #{Dir.pwd} && swift build -c release
+
+  MSG
+  exit 0 # Don't fail the gem install, just warn
+end
+
+# Build the Swift CLI
+puts 'Building macOS BLE helper (Swift CLI)...'
+puts "  Source: #{Dir.pwd}"
+
+# Run swift build in release mode
+success = system('swift build -c release')
+
+if success
+  binary = File.join(Dir.pwd, '.build', 'release', 'RBLEHelper')
+  if File.exist?(binary)
+    puts "  Built: #{binary}"
+    puts "  Size: #{File.size(binary)} bytes"
+  else
+    warn "  WARNING: Build succeeded but binary not found at #{binary}"
+  end
+else
+  warn <<~MSG
+
+    WARNING: Swift build failed.
+    You can try building manually:
+      cd #{Dir.pwd} && swift build -c release
+
+    Check that Xcode Command Line Tools are installed:
+      xcode-select --install
+
+  MSG
+  # Don't fail gem install - user can build manually
+end

data/lib/rble/backend/base.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module RBLE
+  module Backend
+    # Abstract base class for platform-specific BLE backends.
+    # Subclasses must implement all public methods.
+    class Base
+      # Start scanning for BLE devices
+      #
+      # @param service_uuids [Array<String>, nil] Filter by service UUIDs (nil = all devices)
+      # @param allow_duplicates [Boolean] If true, callback fires on every advertisement
+      # @param adapter [String, nil] Specific adapter to use (nil = default)
+      # @yield [Device] Called when a device is discovered
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented by subclass
+      def start_scan(service_uuids: nil, allow_duplicates: false, adapter: nil, active: true, &block)
+        raise NotImplementedError, "#{self.class}#start_scan must be implemented"
+      end
+
+      # Stop the current scan
+      #
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented by subclass
+      def stop_scan
+        raise NotImplementedError, "#{self.class}#stop_scan must be implemented"
+      end
+
+      # Check if a scan is currently running
+      #
+      # @return [Boolean]
+      # @raise [NotImplementedError] if not implemented by subclass
+      def scanning?
+        raise NotImplementedError, "#{self.class}#scanning? must be implemented"
+      end
+
+      # List available Bluetooth adapters
+      #
+      # @return [Array<Hash>] Array of adapter info hashes with :name, :address, :powered keys
+      # @raise [NotImplementedError] if not implemented by subclass
+      def adapters
+        raise NotImplementedError, "#{self.class}#adapters must be implemented"
+      end
+
+      # Get the default adapter name
+      #
+      # @return [String, nil] Default adapter name or nil if none available
+      def default_adapter
+        adapters.first&.dig(:name)
+      end
+
+      # Connection methods (implement in subclass)
+
+      # Connect to a BLE device
+      #
+      # @param device_path [String] D-Bus device path
+      # @param timeout [Numeric] Connection timeout in seconds
+      # @return [Boolean] true on successful connection
+      # @raise [NotImplementedError] if not implemented by subclass
+      def connect_device(device_path, timeout: 30)
+        raise NotImplementedError, "#{self.class}#connect_device must be implemented"
+      end
+
+      # Disconnect from a BLE device
+      #
+      # @param device_path [String] D-Bus device path
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented by subclass
+      def disconnect_device(device_path)
+        raise NotImplementedError, "#{self.class}#disconnect_device must be implemented"
+      end
+
+      # Discover GATT services on a connected device
+      #
+      # @param device_path [String] D-Bus device path
+      # @param connection [Connection, nil] Connection for D-Bus session routing (BlueZ only)
+      # @param timeout [Numeric] Discovery timeout in seconds
+      # @return [Array<Service>] Discovered services
+      # @raise [NotImplementedError] if not implemented by subclass
+      def discover_services(device_path, connection: nil, timeout: 30)
+        raise NotImplementedError, "#{self.class}#discover_services must be implemented"
+      end
+
+      # Get the device D-Bus path for a given MAC address
+      #
+      # @param address [String] Device MAC address
+      # @param adapter [String, nil] Specific adapter to use
+      # @return [String, nil] Device path or nil if not found
+      # @raise [NotImplementedError] if not implemented by subclass
+      def device_path_for_address(address, adapter: nil)
+        raise NotImplementedError, "#{self.class}#device_path_for_address must be implemented"
+      end
+
+      # GATT operations (implement in subclass)
+
+      # Read a characteristic value
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param connection [Connection, nil] Connection for D-Bus session routing (BlueZ only)
+      # @param timeout [Numeric] Read timeout in seconds
+      # @return [String] Binary string (ASCII-8BIT encoding)
+      # @raise [NotImplementedError] if not implemented by subclass
+      def read_characteristic(char_path, connection: nil, timeout: 30)
+        raise NotImplementedError, "#{self.class}#read_characteristic must be implemented"
+      end
+
+      # Write a value to a characteristic
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param data [String, Array<Integer>] Data to write
+      # @param connection [Connection, nil] Connection for D-Bus session routing (BlueZ only)
+      # @param response [Boolean] Wait for write response (true = write with response)
+      # @param timeout [Numeric] Write timeout in seconds
+      # @return [Boolean] true on success
+      # @raise [NotImplementedError] if not implemented by subclass
+      def write_characteristic(char_path, data, connection: nil, response: true, timeout: 30)
+        raise NotImplementedError, "#{self.class}#write_characteristic must be implemented"
+      end
+
+      # Subscribe to characteristic notifications
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param connection [Connection, nil] Connection for D-Bus session routing (BlueZ only)
+      # @yield [String] Called with value (binary string) on each notification
+      # @return [Boolean] true on success
+      # @raise [NotImplementedError] if not implemented by subclass
+      def subscribe_characteristic(char_path, connection: nil, &)
+        raise NotImplementedError, "#{self.class}#subscribe_characteristic must be implemented"
+      end
+
+      # Unsubscribe from characteristic notifications
+      #
+      # @param char_path [String] D-Bus characteristic path
+      # @param connection [Connection, nil] Connection for D-Bus session routing (BlueZ only)
+      # @return [Boolean] true on success
+      # @raise [NotImplementedError] if not implemented by subclass
+      def unsubscribe_characteristic(char_path, connection: nil)
+        raise NotImplementedError, "#{self.class}#unsubscribe_characteristic must be implemented"
+      end
+
+      # Get active subscriptions for a connection
+      #
+      # @param connection [Connection] Connection to query
+      # @return [Array<Hash>] Subscription info hashes with :uuid and :path
+      def subscriptions_for_connection(connection)
+        []
+      end
+
+      # Pairing operations (implement in subclass)
+
+      # Pair with a BLE device
+      #
+      # @param device_path [String] D-Bus device path
+      # @param io_handler [#display, #prompt, #confirm] IO handler for user interaction
+      # @param force [Boolean] Skip interactive prompts (auto-accept)
+      # @param capability [String, nil] Security capability level ("low", "medium", "high", or nil for default)
+      # @param timeout [Numeric] Pairing timeout in seconds
+      # @return [Symbol] :paired on success, :already_paired if already paired
+      # @raise [NotImplementedError] if not implemented by subclass
+      def pair_device(device_path, io_handler:, force: false, capability: nil, timeout: 30)
+        raise NotImplementedError, "#{self.class}#pair_device must be implemented"
+      end
+
+      # Remove pairing bond from a device
+      #
+      # @param device_path [String] D-Bus device path
+      # @return [Symbol] :unpaired on success, :not_paired if not paired
+      # @raise [NotImplementedError] if not implemented by subclass
+      def unpair_device(device_path)
+        raise NotImplementedError, "#{self.class}#unpair_device must be implemented"
+      end
+
+      # List all bonded/paired devices
+      #
+      # @return [Array<Hash>] Array of device info hashes
+      # @raise [NotImplementedError] if not implemented by subclass
+      def bonded_devices
+        raise NotImplementedError, "#{self.class}#bonded_devices must be implemented"
+      end
+    end
+  end
+end