# Class BlePeripheral

java.lang.Object
com.codename1.bluetooth.BluetoothDevice
com.codename1.bluetooth.le.BlePeripheral

Direct Known Subclasses:
  `HelperBlePeripheral`

public abstract class BlePeripheral extends BluetoothDevice

A remote BLE peripheral: connection lifecycle, GATT client operations and L2CAP channels. Obtained from scans (`ScanResult.getPeripheral()`) or from `BluetoothLE.getPeripheral(String)`.

All operations return independent `AsyncResource` handles and may be issued concurrently -- an internal per-peripheral queue serializes them toward the platform stack (which only allows one in-flight GATT request per connection) and applies a safety timeout so a lost platform callback can never wedge the queue. Operations on different peripherals run fully concurrently.

Ports subclass this and implement the protected `do*` methods; they report events through the `fire*` methods, which are safe to call from any thread. All application-facing callbacks are delivered on the EDT.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `BlePeripheral()`
  Ports construct subclasses; application code receives instances from scans and `BluetoothLE`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `addConnectionListener(ConnectionListener l)`
  Registers a listener notified on the EDT of every connection state transition.
  `final AsyncResource<BlePeripheral>`
  `connect()`
  Connects with default `ConnectionOptions`.
  `final AsyncResource<BlePeripheral>`
  `connect(ConnectionOptions options)`
  Establishes a connection.
  `final AsyncResource<Boolean>`
  `createBond()`
  Initiates bonding/pairing.
  `final void`
  `disconnect()`
  Disconnects.
  `final AsyncResource<List<GattService>>`
  `discoverServices()`
  Discovers the peripheral's services.
  `protected abstract void`
  `doConnect(ConnectionOptions options, AsyncResource<BlePeripheral> out)`
  Establishes the platform connection and completes/fails `out`.
  `protected abstract void`
  `doCreateBond(AsyncResource<Boolean> out)`
  Initiates bonding and completes `out` when the bond state settles.
  `protected abstract void`
  `doDisconnect()`
  Tears down the platform connection; `fireConnectionStateChanged(ConnectionState, BluetoothException)` reports the resulting `DISCONNECTED` transition.
  `protected abstract void`
  `doDiscoverServices(AsyncResource<List<GattService>> out)`
  Performs service discovery and completes `out` with the discovered `GattService` list (constructed via the public gatt-package constructors).
  `protected abstract void`
  `doOpenL2cap(int psm, boolean secure, AsyncResource<L2capChannel> out)`
  Opens an L2CAP channel and completes `out` with it.
  `protected abstract void`
  `doReadCharacteristic(GattCharacteristic c, AsyncResource<byte[]> out)`
  Reads a characteristic and completes `out` with its value.
  `protected abstract void`
  `doReadDescriptor(GattDescriptor d, AsyncResource<byte[]> out)`
  Reads a descriptor and completes `out` with its value.
  `protected abstract void`
  `doReadRssi(AsyncResource<Integer> out)`
  Reads the connection RSSI and completes `out`.
  `protected abstract void`
  `doRequestConnectionPriority(ConnectionPriority priority, AsyncResource<Boolean> out)`
  Requests a connection-interval preference and completes `out`.
  `protected abstract void`
  `doRequestMtu(int mtu, AsyncResource<Integer> out)`
  Requests an MTU and completes `out` with the granted value.
  `protected abstract void`
  `doSetNotifications(GattCharacteristic c, boolean enable, boolean indication, AsyncResource<Boolean> out)`
  Arms or disarms notifications/indications (including the CCCD write) and completes `out` once done.
  `protected abstract void`
  `doWriteCharacteristic(GattCharacteristic c, byte[] value, boolean withResponse, AsyncResource<Boolean> out)`
  Writes a characteristic and completes `out` once acknowledged (`withResponse`) or queued to the controller.
  `protected abstract void`
  `doWriteDescriptor(GattDescriptor d, byte[] value, AsyncResource<Boolean> out)`
  Writes a descriptor and completes `out` once acknowledged.
  `protected final void`
  `fireConnectionStateChanged(ConnectionState newState, BluetoothException reason)`
  Reports an (unsolicited) connection state transition -- link loss, remote disconnect, or connection established outside a pending connect call.
  `protected final void`
  `fireNotification(GattCharacteristic c, byte[] value)`
  Delivers a notification/indication value to the subscribed listeners on the EDT.
  `protected final void`
  `fireServicesInvalidated()`
  Invalidates the cached service database (iOS `didModifyServices`); the app should re-run `discoverServices()`.
  `final GattCharacteristic`
  `getCharacteristic(BluetoothUuid service, BluetoothUuid characteristic)`
  Convenience for `getService(service).getCharacteristic(characteristic)` that returns `null` instead of throwing when either is absent.
  `final ConnectionState`
  `getConnectionState()`
  The current connection state.
  `final int`
  `getMtu()`
  The current MTU of the connection; `23` (the BLE default) until a larger value was negotiated.
  `final GattService`
  `getService(BluetoothUuid uuid)`
  The first cached service with the given UUID, or `null`.
  `final List<GattService>`
  `getServices()`
  The cached service list from the last `discoverServices()` call; empty before discovery.
  `final boolean`
  `isSubscribed(GattCharacteristic c)`
  `true` while notifications are armed for the characteristic.
  `final AsyncResource<L2capChannel>`
  `openL2capChannel(int psm, boolean secure)`
  Opens an L2CAP connection-oriented channel to the given PSM.
  `final AsyncResource<byte[]>`
  `readCharacteristic(GattCharacteristic c)`
  Reads a characteristic value; prefer the convenience `GattCharacteristic.read()`.
  `final AsyncResource<byte[]>`
  `readDescriptor(GattDescriptor d)`
  Reads a descriptor value; prefer the convenience `GattDescriptor.read()`.
  `final AsyncResource<Integer>`
  `readRssi()`
  Reads the current RSSI of the connection.
  `final void`
  `removeConnectionListener(ConnectionListener l)`
  Removes a listener added via `addConnectionListener(ConnectionListener)`.
  `final AsyncResource<Boolean>`
  `requestConnectionPriority(ConnectionPriority priority)`
  Requests a connection-interval preference; a successful no-op on platforms that manage intervals themselves (iOS).
  `final AsyncResource<Integer>`
  `requestMtu(int mtu)`
  Requests an MTU; resolves with the granted value (which may be smaller).
  `protected final void`
  `setMtu(int mtu)`
  Records the negotiated MTU -- for ports whose platform reports MTU changes outside a `requestMtu(int)` call.
  `protected final void`
  `setOperationTimeout(int millis)`
  Adjusts the safety timeout applied to each queued GATT operation (default 30000ms; `0` disables).
  `final AsyncResource<Boolean>`
  `subscribe(GattCharacteristic c, GattNotificationListener l)`
  Subscribes a listener to a characteristic's notifications; prefer the convenience `GattCharacteristic.subscribe(GattNotificationListener)`.
  `final AsyncResource<Boolean>`
  `unsubscribe(GattCharacteristic c, GattNotificationListener l)`
  Removes a notification listener; prefer the convenience `GattCharacteristic.unsubscribe(GattNotificationListener)`.
  `final AsyncResource<Boolean>`
  `writeCharacteristic(GattCharacteristic c, byte[] value, boolean withResponse)`
  Writes a characteristic value; prefer the convenience [GattCharacteristic#write(byte[])] / [GattCharacteristic#writeWithoutResponse(byte[])].
  `final AsyncResource<Boolean>`
  `writeDescriptor(GattDescriptor d, byte[] value)`
  Writes a descriptor value; prefer the convenience [GattDescriptor#write(byte[])].

  ### Methods inherited from class BluetoothDevice

  `equals, getAddress, getBondState, getName, getType, hashCode, toString`

  ### Methods inherited from class Object

  `clone, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### BlePeripheral

    protected BlePeripheral()
    Ports construct subclasses; application code receives instances from scans and `BluetoothLE`.

- ## Method Details

  - ### connect

    public final AsyncResource<BlePeripheral> connect()
    Connects with default `ConnectionOptions`.

  - ### connect

    public final AsyncResource<BlePeripheral> connect(ConnectionOptions options)
    Establishes a connection. Resolves with this peripheral once connected or fails with a `BluetoothException`. Calling `connect` while already `ConnectionState.CONNECTING` returns the existing attempt's handle; while `ConnectionState.CONNECTED` it resolves immediately.

  - ### disconnect

    public final void disconnect()
    Disconnects. A no-op while already disconnected; an in-flight connect attempt is aborted with `BluetoothError.USER_CANCELED`.

  - ### getConnectionState

    public final ConnectionState getConnectionState()
    The current connection state.

  - ### addConnectionListener

    public final void addConnectionListener(ConnectionListener l)
    Registers a listener notified on the EDT of every connection state transition.

  - ### removeConnectionListener

    public final void removeConnectionListener(ConnectionListener l)
    Removes a listener added via `addConnectionListener(ConnectionListener)`.

  - ### discoverServices

    public final AsyncResource<List<GattService>> discoverServices()
    Discovers the peripheral's services. Resolves with the service list (also cached -- see `getServices()`) or fails with a `BluetoothException`.

  - ### getServices

    public final List<GattService> getServices()
    The cached service list from the last `discoverServices()` call; empty before discovery.

  - ### getService

    public final GattService getService(BluetoothUuid uuid)
    The first cached service with the given UUID, or `null`.

  - ### getCharacteristic

    public final GattCharacteristic getCharacteristic(BluetoothUuid service, BluetoothUuid characteristic)
    Convenience for `getService(service).getCharacteristic(characteristic)` that returns `null` instead of throwing when either is absent.

  - ### readCharacteristic

    public final AsyncResource<byte[]> readCharacteristic(GattCharacteristic c)
    Reads a characteristic value; prefer the convenience `GattCharacteristic.read()`.

  - ### writeCharacteristic

    public final AsyncResource<Boolean> writeCharacteristic(GattCharacteristic c, byte[] value, boolean withResponse)
    Writes a characteristic value; prefer the convenience [GattCharacteristic#write(byte[])] / [GattCharacteristic#writeWithoutResponse(byte[])].

  - ### readDescriptor

    public final AsyncResource<byte[]> readDescriptor(GattDescriptor d)
    Reads a descriptor value; prefer the convenience `GattDescriptor.read()`.

  - ### writeDescriptor

    public final AsyncResource<Boolean> writeDescriptor(GattDescriptor d, byte[] value)
    Writes a descriptor value; prefer the convenience [GattDescriptor#write(byte[])].

  - ### subscribe

    public final AsyncResource<Boolean> subscribe(GattCharacteristic c, GattNotificationListener l)
    Subscribes a listener to a characteristic's notifications; prefer the convenience `GattCharacteristic.subscribe(GattNotificationListener)`. The CCCD is written only on the transition from zero to one listener.

  - ### unsubscribe

    public final AsyncResource<Boolean> unsubscribe(GattCharacteristic c, GattNotificationListener l)
    Removes a notification listener; prefer the convenience `GattCharacteristic.unsubscribe(GattNotificationListener)`. The CCCD is disarmed when the last listener is removed.

  - ### isSubscribed

    public final boolean isSubscribed(GattCharacteristic c)
    `true` while notifications are armed for the characteristic.

  - ### readRssi

    public final AsyncResource<Integer> readRssi()
    Reads the current RSSI of the connection.

  - ### requestMtu

    public final AsyncResource<Integer> requestMtu(int mtu)
    Requests an MTU; resolves with the granted value (which may be smaller). iOS negotiates the MTU itself -- there the request resolves immediately with the current value.

  - ### getMtu

    public final int getMtu()
    The current MTU of the connection; `23` (the BLE default) until a larger value was negotiated.

  - ### requestConnectionPriority

    public final AsyncResource<Boolean> requestConnectionPriority(ConnectionPriority priority)
    Requests a connection-interval preference; a successful no-op on platforms that manage intervals themselves (iOS).

  - ### createBond

    public final AsyncResource<Boolean> createBond()
    Initiates bonding/pairing. On iOS bonding is OS-managed (triggered by encrypted characteristics), so the request resolves `true` without user interaction.

  - ### openL2capChannel

    public final AsyncResource<L2capChannel> openL2capChannel(int psm, boolean secure)
    Opens an L2CAP connection-oriented channel to the given PSM. Not serialized with GATT operations. On Android this establishes its own link and does not require `connect()` first; on iOS the peripheral must be connected.

  - ### doConnect

    protected abstract void doConnect(ConnectionOptions options, AsyncResource<BlePeripheral> out)
    Establishes the platform connection and completes/fails `out`.

  - ### doDisconnect

    protected abstract void doDisconnect()
    Tears down the platform connection; `fireConnectionStateChanged(ConnectionState, BluetoothException)` reports the resulting `DISCONNECTED` transition.

  - ### doDiscoverServices

    protected abstract void doDiscoverServices(AsyncResource<List<GattService>> out)
    Performs service discovery and completes `out` with the discovered `GattService` list (constructed via the public gatt-package constructors).

  - ### doReadCharacteristic

    protected abstract void doReadCharacteristic(GattCharacteristic c, AsyncResource<byte[]> out)
    Reads a characteristic and completes `out` with its value.

  - ### doWriteCharacteristic

    protected abstract void doWriteCharacteristic(GattCharacteristic c, byte[] value, boolean withResponse, AsyncResource<Boolean> out)
    Writes a characteristic and completes `out` once acknowledged (`withResponse`) or queued to the controller.

  - ### doReadDescriptor

    protected abstract void doReadDescriptor(GattDescriptor d, AsyncResource<byte[]> out)
    Reads a descriptor and completes `out` with its value.

  - ### doWriteDescriptor

    protected abstract void doWriteDescriptor(GattDescriptor d, byte[] value, AsyncResource<Boolean> out)
    Writes a descriptor and completes `out` once acknowledged.

  - ### doSetNotifications

    protected abstract void doSetNotifications(GattCharacteristic c, boolean enable, boolean indication, AsyncResource<Boolean> out)
    Arms or disarms notifications/indications (including the CCCD write) and completes `out` once done.

  - ### doReadRssi

    protected abstract void doReadRssi(AsyncResource<Integer> out)
    Reads the connection RSSI and completes `out`.

  - ### doRequestMtu

    protected abstract void doRequestMtu(int mtu, AsyncResource<Integer> out)
    Requests an MTU and completes `out` with the granted value.

  - ### doRequestConnectionPriority

    protected abstract void doRequestConnectionPriority(ConnectionPriority priority, AsyncResource<Boolean> out)
    Requests a connection-interval preference and completes `out`.

  - ### doCreateBond

    protected abstract void doCreateBond(AsyncResource<Boolean> out)
    Initiates bonding and completes `out` when the bond state settles.

  - ### doOpenL2cap

    protected abstract void doOpenL2cap(int psm, boolean secure, AsyncResource<L2capChannel> out)
    Opens an L2CAP channel and completes `out` with it. Called directly (not through the operation queue).

  - ### fireConnectionStateChanged

    protected final void fireConnectionStateChanged(ConnectionState newState, BluetoothException reason)
    Reports an (unsolicited) connection state transition -- link loss, remote disconnect, or connection established outside a pending connect call. `reason` is `null` for app-requested transitions.

  - ### fireNotification

    protected final void fireNotification(GattCharacteristic c, byte[] value)
    Delivers a notification/indication value to the subscribed listeners on the EDT. Ports must pass the canonical `GattCharacteristic` instance from the discovered database.

  - ### fireServicesInvalidated

    protected final void fireServicesInvalidated()
    Invalidates the cached service database (iOS `didModifyServices`); the app should re-run `discoverServices()`.

  - ### setOperationTimeout

    protected final void setOperationTimeout(int millis)
    Adjusts the safety timeout applied to each queued GATT operation (default 30000ms; `0` disables).

  - ### setMtu

    protected final void setMtu(int mtu)
    Records the negotiated MTU -- for ports whose platform reports MTU changes outside a `requestMtu(int)` call.