# Class BluetoothLE

java.lang.Object
com.codename1.bluetooth.le.BluetoothLE

public class BluetoothLE extends Object

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.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `BluetoothLE()`
  Ports construct subclasses.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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.
  `protected final void`
  `fireScanResult(ScanResult result)`
  Reports one advertisement sighting from the platform scan; safe to call from any thread.
  `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.
  `List<BlePeripheral>`
  `getBondedPeripherals()`
  The LE peripherals bonded with this device.
  `List<BlePeripheral>`
  `getConnectedPeripherals(BluetoothUuid serviceFilter)`
  The peripherals the system currently holds connected (e.g. paired wearables), optionally filtered to those offering the given service.
  `BlePeripheral`
  `getPeripheral(String address)`
  Re-obtains a peripheral from an address persisted earlier (see `BluetoothDevice.getAddress()` for the address semantics) without scanning.
  `protected boolean`
  `isScanSupported()`
  `true` when this port can scan; the base class returns `false`, making `startScan(ScanSettings, ScanListener)` fail fast.
  `protected void`
  `onScanRegistrationsChanged()`
  Called after every scan registration change.
  `AsyncResource<GattServer>`
  `openGattServer(GattServerListener listener)`
  Opens the local GATT server for the peripheral role; the listener's methods fire on the EDT.
  `AsyncResource<L2capServer>`
  `openL2capServer(boolean secure)`
  Opens a listening L2CAP endpoint for the peripheral role; publish `L2capServer.getPsm()` to centrals (typically via a GATT characteristic).
  `AsyncResource<BleAdvertisement>`
  `startAdvertising(AdvertiseSettings settings, AdvertiseData data, AdvertiseData scanResponse)`
  Starts advertising.
  `protected void`
  `startPlatformScan()`
  Starts the single underlying platform scan; called when the first `BleScan` handle registers.
  `final BleScan`
  `startScan(ScanSettings settings, ScanListener listener)`
  Starts scanning; the listener fires on the EDT for every advertisement passing the settings' filters.
  `protected void`
  `stopPlatformScan()`
  Stops the underlying platform scan; called when the last handle stops.

  ### Methods inherited from class Object

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

- ## 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.