LBLEClient
This class allows users to create connections to remote peripheral devices.
To access device attributes, create LBLEClient object and call LBLEClient::connect to connect to the device in address:
// assume LBLECentral::scan has already performed.
// connect to the 1st device scanned.
LBLEClient client;
LBLEAddress serverAddress = LBLECentral.getBLEAddress(0);
client.connect(serverAddress);
while(!client.connected()){
delay(100);
}
// now we are connnected.Upon successful connection, connected() returns true.
The user can then query if certain GATT services exist on the remote device with getServiceCount(), getServiceUuid() and hasService(uuid).
Once the user confirmed that a service is available, the user may use APIs to read or write characteristics.
There are 2 sets of APIs:
Read or write characteristics based on their UUIDs. This is convenient if you already knew the UUID of the desired characteristics. However, there are many cases that the same UUID may appear on different services on the same BLE device. In these cases, you may end up read or write the characteristics that is not intended.
Read or write characteristics based on service index, and the index of the characteristics in the service, queried by
getCharacteristicCount. This set of API allows you to specify a characteristic in a specific service, thus this covers a more general case. However, you need to usegetCharacteristicCountandgetCharacteristicUuidto ensure the index of the characteristics you want to read or write.
Note that there is no extra "type" checking, so it is up to the user to make sure the value types are matched between read/write APIs and the remote device.
Constructors
LBLEClient
Creates a LBLEClient instance that can be used to connect to peripheral devices.
Syntax
Parameters
none
Returns
LBLEClient instance
Connection Methods
connect()
connected()
disconnect()
Start connecting to a remote peripheral device.
You can use LBLECentral singleton object to scan nearby devices and get their addresses.
Call connected() to check if the connection has been successfully established.
Note: this function also implicitly enumerates all the services and characteristics on the remote device, so it may take a while for this function to return.
Syntax
Parameters
none
Returns
true if the connection attempt starts successfully. Note that this does not mean the connection has been established.
false if fail to start connection.
Check if the connection to remote device has been established.
Syntax
Parameters
none
Returns
true if the connection has been established. false otherwise.
Disconnect from the remote device.
Syntax
Parameters
none
Returns
none
Service Methods
hasService()
getServiceCount()
getServiceName()
getServiceUuid()
getCharacteristicCount()
Check if a service, identified with an UUID, is available on the remote connected device.
Syntax
Parameters
serviceUUID
128-bit or 16-bit UUID to identify the service.
Returns
true if the service is available on the remote device; false otherwise.
Get the number of services available on the connected remote device.
Syntax
Parameters
none
Returns
Number of services available on the connected device.
Helper function that returns name of the service if it is known.
Syntax
Parameters
serviceIndex
ranges from 0 to (getServiceCount() - 1).
Returns
Service name
Get service UUID by index.
Syntax
Parameters
serviceIndex
ranges from 0 to (getServiceCount() - 1).
Returns
UUID of the service
Get the number of characteristics in the service.
Syntax
Parameters
serviceIndex
ranges from 0 to (getServiceCount() - 1).
Returns
Number of characteristics in the service.
Characteristic Methods
getCharacteristicUuid()
readCharacteristicString()
readCharacteristicInt()
writeCharacteristicFloat()
writeCharacteristicString()
writeCharacteristicInt()
writeCharacteristicFloat()
Get the UUID of a characteristic in the service by its index
Syntax
Parameters
characteristicIndex
ranges from 0 to (getCharacteristicCount(serviceIndex) - 1).
Returns
Number of characteristics in the service.
Read string value from a characteristic on remote device.
Syntax
Parameters
serviceIndex
ranges from 0 to (getServiceCount() - 1).
characteristicIndex
ranges from 0 to (getCharacteristicCount(serviceIndex) - 1).
Returns
String value of the characteristic. Empty string is returned if fails to read the characteristic.
Read integer value from a characteristic on remote device.
Syntax
Parameters
serviceIndex
ranges from 0 to (getServiceCount() - 1).
characteristicIndex
ranges from 0 to (getCharacteristicCount(serviceIndex) - 1).
Returns
Integral value of the characteristic. 0 is returned if fails to read the characteristic.
Read float value from a characteristic on remote device.
Syntax
Parameters
serviceIndex
ranges from 0 to (getServiceCount() - 1).
characteristicIndex
ranges from 0 to (getCharacteristicCount(serviceIndex) - 1).
Returns
Float value of the characteristic. 0.0f is returned if fails to read the characteristic.
Hepler API that write a characteristic on the remote device as a string.
Syntax
Parameters
string_to_write
The string value to write.
serviceIndex
ranges from 0 to (getServiceCount() - 1).
characteristicIndex
ranges from 0 to (getCharacteristicCount(serviceIndex) - 1).
Returns
>0 if written successfully.
0 if failed to write.
Hepler API that write a characteristic on the remote device as an integer.
Syntax
Parameters
int_value
The int value to write.
serviceIndex
ranges from 0 to (getServiceCount() - 1).
characteristicIndex
ranges from 0 to (getCharacteristicCount(serviceIndex) - 1).
Returns
>0 if written successfully.
0 if failed to write.
Hepler API that write a characteristic on the remote device as a float.
Syntax
Parameters
float_value
The float value to write.
serviceIndex
ranges from 0 to (getServiceCount() - 1).
characteristicIndex
ranges from 0 to (getCharacteristicCount(serviceIndex) - 1).
Returns
>0 if written successfully.
0 if failed to write.
Last updated