public class BluetoothLE

Object
BluetoothLE

The BLE central role: scanning for peripherals and re-obtaining known ones. Obtain via Bluetooth.getInstance().getLE(); the instance is owned by the active port and never null – on ports without BLE it reports every operation as unsupported.

Any number of scans may run concurrently. This base class multiplexes them over a single platform scan: each BleScan handle only receives advertisements matching its own ScanSettings filters, and the platform scan stops when the last handle stops.

Constructors

protected BluetoothLE() Ports construct subclasses.

Methods

`public final` `BleScan startScan(ScanSettings settings, ScanListener listener)`	Starts scanning; the listener fires on the EDT for every advertisement passing the settings’ filters.
`public` `BlePeripheral getPeripheral(String address)`	Re-obtains a peripheral from an address persisted earlier (see `BluetoothDevice.getAddress()` for the address semantics) without scanning.
`public` `List<BlePeripheral> getConnectedPeripherals(BluetoothUuid serviceFilter)`	The peripherals the system currently holds connected (e.g. paired wearables), optionally filtered to those offering the given service.
`public` `List<BlePeripheral> getBondedPeripherals()`	The LE peripherals bonded with this device.
`public` `AsyncResource<GattServer> openGattServer(GattServerListener listener)`	Opens the local GATT server for the peripheral role; the listener’s methods fire on the EDT.
`public` `AsyncResource<BleAdvertisement> startAdvertising(AdvertiseSettings settings, AdvertiseData data, AdvertiseData scanResponse)`	Starts advertising.
`public` `AsyncResource<L2capServer> openL2capServer(boolean secure)`	Opens a listening L2CAP endpoint for the peripheral role; publish `L2capServer.getPsm()` to centrals (typically via a GATT characteristic).
`protected boolean isScanSupported()`	`true` when this port can scan; the base class returns `false`, making `startScan(ScanSettings, ScanListener)` fail fast.
`protected void startPlatformScan()`	Starts the single underlying platform scan; called when the first `BleScan` handle registers.
`protected void stopPlatformScan()`	Stops the underlying platform scan; called when the last handle stops.
`protected void onScanRegistrationsChanged()`	Called after every scan registration change.
`protected final` `List<ScanSettings> getActiveScanSettings()`	The settings of all currently active scan handles – for ports that optimize the platform scan.
`protected final` `ScanMode getAggregateScanMode()`	The most aggressive `ScanMode` among the active handles – convenience for ports mapping the merged scan onto a platform scan mode.
`protected final void fireScanResult(ScanResult result)`	Reports one advertisement sighting from the platform scan; safe to call from any thread.
`protected final void fireScanFailed(BluetoothException reason)`	Reports that the OS aborted the platform scan; every active handle fails with the given reason and the registry is cleared.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Constructor details

BluetoothLE

protected BluetoothLE()

Ports construct subclasses. Application code obtains the active instance via Bluetooth.getInstance().getLE().

Method details

startScan

public final BleScan startScan(ScanSettings settings, ScanListener listener)

Starts scanning; the listener fires on the EDT for every advertisement passing the settings’ filters. Returns a live BleScan handle – keep a reference and call BleScan.stop() when done. On ports without BLE the returned handle is already failed with BluetoothError.NOT_SUPPORTED.

getPeripheral

public BlePeripheral getPeripheral(String address)

Re-obtains a peripheral from an address persisted earlier (see BluetoothDevice.getAddress() for the address semantics) without scanning. Returns null when the platform cannot resolve the address.

getConnectedPeripherals

public List<BlePeripheral> getConnectedPeripherals(BluetoothUuid serviceFilter)

The peripherals the system currently holds connected (e.g. paired wearables), optionally filtered to those offering the given service. Empty on ports without BLE.

iOS filters exactly (CoreBluetooth resolves services); Android can only consult its cached SDP/GATT UUIDs, so the filter is best-effort there and devices with an empty cache are retained.

getBondedPeripherals

public List<BlePeripheral> getBondedPeripherals()

The LE peripherals bonded with this device. Empty on ports without BLE or without a bonded-device registry (iOS).

openGattServer

public AsyncResource<GattServer> openGattServer(GattServerListener listener)

Opens the local GATT server for the peripheral role; the listener’s methods fire on the EDT. Fails with BluetoothError.NOT_SUPPORTED on ports without peripheral mode – branch via Bluetooth.getInstance().isPeripheralModeSupported().

startAdvertising

public AsyncResource<BleAdvertisement> startAdvertising(AdvertiseSettings settings, AdvertiseData data, AdvertiseData scanResponse)

Starts advertising. Resolves with a live BleAdvertisement handle once the platform actually started broadcasting, or fails with BluetoothError.ADVERTISE_FAILED / BluetoothError.NOT_SUPPORTED. scanResponse may be null.

openL2capServer

public AsyncResource<L2capServer> openL2capServer(boolean secure)

Opens a listening L2CAP endpoint for the peripheral role; publish L2capServer.getPsm() to centrals (typically via a GATT characteristic). Fails with BluetoothError.NOT_SUPPORTED where L2CAP or peripheral mode is unavailable.

isScanSupported

protected boolean isScanSupported()

true when this port can scan; the base class returns false, making startScan(ScanSettings, ScanListener) fail fast.

startPlatformScan

protected void startPlatformScan()

Starts the single underlying platform scan; called when the first BleScan handle registers. Sightings are reported via fireScanResult(ScanResult). May throw a RuntimeException to fail the initiating handle.

stopPlatformScan

protected void stopPlatformScan()

Stops the underlying platform scan; called when the last handle stops.

onScanRegistrationsChanged

protected void onScanRegistrationsChanged()

Called after every scan registration change. Ports may retune the platform scan (e.g. push down filters or raise the scan mode) based on getActiveScanSettings(). Default does nothing.

getActiveScanSettings

protected final List<ScanSettings> getActiveScanSettings()

The settings of all currently active scan handles – for ports that optimize the platform scan.

getAggregateScanMode

protected final ScanMode getAggregateScanMode()

The most aggressive ScanMode among the active handles – convenience for ports mapping the merged scan onto a platform scan mode.

fireScanResult

protected final void fireScanResult(ScanResult result)

Reports one advertisement sighting from the platform scan; safe to call from any thread. The base class demultiplexes it to every active handle whose filters match, applying per-handle duplicate suppression, and dispatches the listeners on the EDT.

fireScanFailed

protected final void fireScanFailed(BluetoothException reason)

Reports that the OS aborted the platform scan; every active handle fails with the given reason and the registry is cleared. The base class does NOT call stopPlatformScan() on this path – the platform scan is presumed dead, so ports must clean up their own scanner state before (or when) calling this.