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