Represents a Bluetooth Low Energy (BLE) peripheral. More...

Classes
interface	MtuRequestCallback
	Interface for MTU change request callbacks. More...

interface	ReadRssiRequestCallback
	Interface for RSSI read request callbacks. More...

interface	ReadValueRequestCallback
	Interface for characteristic's value read request callbacks. More...

interface	RequestCallback
	Interface for most BLE request callbacks. More...

Public Member Functions
Constructor
	Peripheral (final BluetoothDevice device, final ConnectionObserver connectionObserver)
	Initializes a peripheral for the given Android BluetoothDevice object and with a connection observer.

Connection and disconnection
void	connect (final String requiredServicesUuids, final boolean autoReconnect, final RequestCallback requestCallback)
	Queues a request to connect to the peripheral.

void	disconnect (final RequestCallback requestCallback)
	Immediately disconnects the peripheral.

Getters valid even when not connected
String	getAddress ()
	Gets the Bluetooth address of the peripheral.

String	getName ()
	Gets the name of the peripheral.

boolean	isConnected ()
	Indicates whether the peripheral is connected.

boolean	isReady ()
	Indicates whether the peripheral is ready.

Peripheral operations
Valid only for connected peripherals.
int	getMtu ()
	Gets the Maximum Transmission Unit (MTU).

void	requestMtu (int mtu, final MtuRequestCallback mtuChangedCallback)
	Queues a request for the peripheral to change its MTU to the given value.

void	readRssi (final ReadRssiRequestCallback rssiReadCallback)
	Queues a request to read the Received Signal Strength Indicator (RSSI).

Services operations
Valid only for ready peripherals.
String	getDiscoveredServices ()
	Gets the list of discovered services.

String	getServiceCharacteristics (final String serviceUuid)
	Gets the list of discovered characteristics for the given service.

Characteristic operations
Valid only for peripherals in ready state.
int	getCharacteristicProperties (final String serviceUuid, final String characteristicUuid, final int instanceIndex)
	Gets the standard BLE properties of the specified service's characteristic.

void	readCharacteristic (final String serviceUuid, final String characteristicUuid, final int instanceIndex, final ReadValueRequestCallback valueReadCallback)
	Queues a request to read the value of the specified service's characteristic.

void	writeCharacteristic (final String serviceUuid, final String characteristicUuid, final int instanceIndex, final byte[] data, boolean withoutResponse, final RequestCallback requestCallback)
	Queues a request to write the value of specified service's characteristic.

void	subscribeCharacteristic (final String serviceUuid, final String characteristicUuid, final int instanceIndex, final DataReceivedCallback valueChangedCallback, final RequestCallback requestCallback)
	Queues a request to subscribe for value changes of the specified service's characteristic.

void	unsubscribeCharacteristic (final String serviceUuid, final String characteristicUuid, final int instanceIndex, final RequestCallback requestCallback)
	Queues a request to unsubscribe from the specified service's characteristic.

Static Public Member Functions
static BluetoothDevice	getDeviceFromAddress (final long bluetoothAddress)
	Gets the BluetoothDevice object for the given Bluetooth address.

Detailed Description

Represents a Bluetooth Low Energy (BLE) peripheral.

Note: This class was designed to work in a Unity plugin and its marshaling mechanism, and as such its methods uses strings for the services and characteristics UUIDs rather than ParcelUuid objects.

The most common BLE operations are supported, such as reading the peripheral name, MTU, RSSI, listing services and characteristics. It has support for getting characteristics properties and when applicable reading and writing their value, as well as subscribing for value changes.

Several of those operations are asynchronous and take a RequestCallback object as a parameter. The appropriate method is called on this object when the request has completed (successfully or not).

Once created, a peripheral must be connected before most its methods may be used. and it must be ready before accessing the services. The peripheral becomes ready once all the required services have been discovered.

A specific Service may be retrieved with getDiscoveredService(). A service contains characteristics for which data may be read or written.

It relies on Nordic's Android-BLE-Library library for most of the work.

See also: https://github.com/NordicSemiconductor/Android-BLE-Library

Constructor & Destructor Documentation

◆ Peripheral()

com.systemic.bluetoothle.Peripheral.Peripheral	(	final BluetoothDevice	device,
		final ConnectionObserver	connectionObserver
	)

Initializes a peripheral for the given Android BluetoothDevice object and with a connection observer.

BluetoothDevice may be retrieved either with from a scan using the Scanner class or with their Bluetooth address using the getDeviceFromAddress() static method.

Parameters

device	The Android Bluetooth device object for the BLE peripheral.
connectionObserver	The callback for notifying of changes of the connection status of the peripheral.

Member Function Documentation

◆ connect()

void com.systemic.bluetoothle.Peripheral.connect	(	final String	requiredServicesUuids,
		final boolean	autoReconnect,
		final RequestCallback	requestCallback
	)

Queues a request to connect to the peripheral.

This request timeouts after 30 seconds.

Parameters

requiredServicesUuids	Comma separated list of services UUIDs that the peripheral should support, may be null or empty.
autoReconnect	Whether to automatically reconnect after an unexpected disconnection (i.e. not requested by a call to disconnect()).
requestCallback	The callback for notifying of the request result.

◆ disconnect()

void com.systemic.bluetoothle.Peripheral.disconnect ( final RequestCallback requestCallback )

Immediately disconnects the peripheral.

As a consequence any on-going request either fails or is canceled, including connection requests. Any pending request is dropped.

Parameters

requestCallback The callback for notifying of the request result.

◆ getAddress()

String com.systemic.bluetoothle.Peripheral.getAddress ( )

Gets the Bluetooth address of the peripheral.

Returns: The Bluetooth address, or null if the call failed.

◆ getCharacteristicProperties()

int com.systemic.bluetoothle.Peripheral.getCharacteristicProperties	(	final String	serviceUuid,
		final String	characteristicUuid,
		final int	instanceIndex
	)

Gets the standard BLE properties of the specified service's characteristic.

See also: https://developer.android.com/reference/android/bluetooth/BluetoothGattCharacteristic#PROPERTY_BROADCAST, PROPERTY_READ, PROPERTY_NOTIFY, etc.

Parameters

serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.

Returns: The standard BLE properties of a service's characteristic, or zero if the call failed.

◆ getDeviceFromAddress()

static BluetoothDevice com.systemic.bluetoothle.Peripheral.getDeviceFromAddress ( final long bluetoothAddress )

static

Gets the BluetoothDevice object for the given Bluetooth address.

Parameters

bluetoothAddress The address of a Bluetooth device.

Returns: A BluetoothDevice or null if there is none for the given address.

◆ getDiscoveredServices()

String com.systemic.bluetoothle.Peripheral.getDiscoveredServices ( )

Gets the list of discovered services.

Returns: A comma separated list of services UUIDs, or null if the call failed.

◆ getMtu()

int com.systemic.bluetoothle.Peripheral.getMtu ( )

Gets the Maximum Transmission Unit (MTU).

Returns: The MTU, or zero if the call failed.

◆ getName()

String com.systemic.bluetoothle.Peripheral.getName ( )

Gets the name of the peripheral.

Returns: The name, or null if the call failed.

◆ getServiceCharacteristics()

String com.systemic.bluetoothle.Peripheral.getServiceCharacteristics ( final String serviceUuid )

Gets the list of discovered characteristics for the given service.

The same characteristic may be listed several times according to the peripheral's configuration.

Parameters

serviceUuid The service UUID for which to retrieve the characteristics.

Returns: A comma separated list of characteristics UUIDs, or null if the call failed.

◆ isConnected()

boolean com.systemic.bluetoothle.Peripheral.isConnected ( )

Indicates whether the peripheral is connected.

Services may not have been discovered yet.

Returns: Whether the peripheral is connected.

◆ isReady()

boolean com.systemic.bluetoothle.Peripheral.isReady ( )

Indicates whether the peripheral is ready.

The peripheral is ready once it has successfully connected and discovered the required services.

Returns: Whether the peripheral is ready.

◆ readCharacteristic()

void com.systemic.bluetoothle.Peripheral.readCharacteristic	(	final String	serviceUuid,
		final String	characteristicUuid,
		final int	instanceIndex,
		final ReadValueRequestCallback	valueReadCallback
	)

Queues a request to read the value of the specified service's characteristic.

The call fails if the characteristic is not readable.

Parameters

serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.
valueReadCallback	The callback for notifying of the read value and the request status.

◆ readRssi()

void com.systemic.bluetoothle.Peripheral.readRssi ( final ReadRssiRequestCallback rssiReadCallback )

Queues a request to read the Received Signal Strength Indicator (RSSI).

Parameters

rssiReadCallback The callback for notifying of the read RSSI and the request status.

◆ requestMtu()

void com.systemic.bluetoothle.Peripheral.requestMtu	(	int	mtu,
		final MtuRequestCallback	mtuChangedCallback
	)

Queues a request for the peripheral to change its MTU to the given value.

Parameters

mtu	The requested MTU, must be between 23 and 517 included.
mtuChangedCallback	The callback for notifying of the MTU request result.

◆ subscribeCharacteristic()

void com.systemic.bluetoothle.Peripheral.subscribeCharacteristic	(	final String	serviceUuid,
		final String	characteristicUuid,
		final int	instanceIndex,
		final DataReceivedCallback	valueChangedCallback,
		final RequestCallback	requestCallback
	)

Queues a request to subscribe for value changes of the specified service's characteristic.

Replaces a previously registered value change callback for the same characteristic. The call fails if the characteristic doesn't support notifications.

Parameters

serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.
valueChangedCallback	The callback for notifying of the characteristic's value changes.
requestCallback	The callback for notifying of the request result.

◆ unsubscribeCharacteristic()

void com.systemic.bluetoothle.Peripheral.unsubscribeCharacteristic	(	final String	serviceUuid,
		final String	characteristicUuid,
		final int	instanceIndex,
		final RequestCallback	requestCallback
	)

Queues a request to unsubscribe from the specified service's characteristic.

Parameters

serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.
requestCallback	The callback for notifying of the request result.

◆ writeCharacteristic()

void com.systemic.bluetoothle.Peripheral.writeCharacteristic	(	final String	serviceUuid,
		final String	characteristicUuid,
		final int	instanceIndex,
		final byte[]	data,
		boolean	withoutResponse,
		final RequestCallback	requestCallback
	)

Queues a request to write the value of specified service's characteristic.

The call fails if the characteristic is not writable.

Parameters

serviceUuid	The service UUID.
characteristicUuid	The characteristic UUID.
instanceIndex	The instance index of the characteristic if listed more than once for the service, otherwise zero.
data	The data to write to the characteristic (may be empty but not null).
withoutResponse	Whether to wait for the peripheral to respond.
requestCallback	The callback for notifying of the request result.

The documentation for this class was generated from the following file:

Assets/Plugins/Systemic/Plugins/Android/Peripheral.java

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Peripheral()

Member Function Documentation

◆ connect()

◆ disconnect()

◆ getAddress()

◆ getCharacteristicProperties()

◆ getDeviceFromAddress()

◆ getDiscoveredServices()

◆ getMtu()

◆ getName()

◆ getServiceCharacteristics()

◆ isConnected()

◆ isReady()

◆ readCharacteristic()

◆ readRssi()

◆ requestMtu()

◆ subscribeCharacteristic()

◆ unsubscribeCharacteristic()

◆ writeCharacteristic()