> For the complete documentation index, see [llms.txt](https://cavedu.gitbook.io/linkit-7697/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cavedu.gitbook.io/linkit-7697/linkit-7697-development-guide-for-arduino-ide/developer-guide/using-bluetooth/lble-library-api-guide/lbleclient.md).

# 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 use `getCharacteristicCount` and `getCharacteristicUuid` to 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 <a href="#lbleclient-constructors" id="lbleclient-constructors"></a>

&#x20;LBLEClient

{% tabs %}
{% tab title="LBLEClient" %}
Creates a LBLEClient instance that can be used to connect to peripheral devices.

**Syntax**

**Parameters**

none

**Returns**

LBLEClient instance
{% endtab %}
{% endtabs %}

### Connection Methods <a href="#lbleclient-connectionmethods" id="lbleclient-connectionmethods"></a>

&#x20;connect()

&#x20;connected()

&#x20;disconnect()

{% tabs %}
{% tab title=" connect()" %}
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.
{% endtab %}

{% tab title=" connected()" %}
Check if the connection to remote device has been established.&#x20;

**Syntax**

**Parameters**

none

**Returns**

true if the connection has been established. false otherwise.
{% endtab %}

{% tab title="disconnect()" %}
Disconnect from the remote device.&#x20;

**Syntax**

**Parameters**

none

**Returns**

none
{% endtab %}
{% endtabs %}

### Service Methods <a href="#lbleclient-servicemethods" id="lbleclient-servicemethods"></a>

&#x20;hasService()

&#x20;getServiceCount()

&#x20;getServiceName()

&#x20;getServiceUuid()

&#x20;getCharacteristicCount()

{% tabs %}
{% tab title=" hasService()" %}
Check if a service, identified with an UUID, is available on the remote connected device.

**Syntax**

**Parameters**

<table><thead><tr><th width="358.5"></th><th></th></tr></thead><tbody><tr><td>serviceUUID</td><td>128-bit or 16-bit UUID to identify the service.</td></tr></tbody></table>

**Returns**

true if the service is available on the remote device; false otherwise.
{% endtab %}

{% tab title=" getServiceCount()" %}
Get the number of services available on the connected remote device.

**Syntax**

**Parameters**

none

**Returns**

Number of services available on the connected device.
{% endtab %}

{% tab title=" getServiceName()" %}
Helper function that returns name of the service if it is known.

**Syntax**

**Parameters**

|              |                                           |
| ------------ | ----------------------------------------- |
| serviceIndex | ranges from 0 to (getServiceCount() - 1). |

**Returns**

Service name
{% endtab %}

{% tab title=" getServiceUuid()" %}
Get service UUID by index.

**Syntax**

**Parameters**

|              |                                           |
| ------------ | ----------------------------------------- |
| serviceIndex | ranges from 0 to (getServiceCount() - 1). |

**Returns**

UUID of the service
{% endtab %}

{% tab title="getCharacteristicCount()" %}
Get the number of characteristics in the service.

**Syntax**

**Parameters**

|              |                                           |
| ------------ | ----------------------------------------- |
| serviceIndex | ranges from 0 to (getServiceCount() - 1). |

**Returns**

Number of characteristics in the service.
{% endtab %}
{% endtabs %}

### Characteristic Methods <a href="#lbleclient-characteristicmethods" id="lbleclient-characteristicmethods"></a>

&#x20;getCharacteristicUuid()

&#x20;readCharacteristicString()

&#x20;readCharacteristicInt()

&#x20;writeCharacteristicFloat()

&#x20;writeCharacteristicString()

&#x20;writeCharacteristicInt()

&#x20;writeCharacteristicFloat()

{% tabs %}
{% tab title="getCharacteristicUuid()" %}
Get the UUID of a characteristic in the service by its index

**Syntax**

**Parameters**

| serviceIndex        | ranges from 0 to (getServiceCount() - 1).                      |
| ------------------- | -------------------------------------------------------------- |
| characteristicIndex | ranges from 0 to `(getCharacteristicCount(serviceIndex) - 1).` |

**Returns**

Number of characteristics in the service.
{% endtab %}

{% tab title="readCharacteristicString()" %}
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.
{% endtab %}

{% tab title="readCharacteristicInt()" %}
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.
{% endtab %}

{% tab title="writeCharacteristicFloat()" %}
Read float value from a characteristic on remote device.

**Syntax**

**Parameters**

<table><thead><tr><th width="620.5"></th><th></th></tr></thead><tbody><tr><td>serviceIndex</td><td>ranges from 0 to <code>(getServiceCount() - 1)</code>.</td></tr><tr><td>characteristicIndex</td><td>ranges from 0 to <code>(getCharacteristicCount(serviceIndex) - 1).</code></td></tr></tbody></table>

**Returns**

Float value of the characteristic. 0.0f is returned if fails to read the characteristic.
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title=" writeCharacteristicString()" %}
Hepler API that write a characteristic on the remote device as a string.

**Syntax**

**Parameters**

| uuid              | The UUID of the characteristic to read from. |
| ----------------- | -------------------------------------------- |
| 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.
{% endtab %}

{% tab title=" writeCharacteristicInt()" %}
Hepler API that write a characteristic on the remote device as an integer.

**Syntax**

**Parameters**

| uuid       | The UUID of the characteristic to read from. |
| ---------- | -------------------------------------------- |
| 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.
{% endtab %}

{% tab title="writeCharacteristicFloat()" %}
Hepler API that write a characteristic on the remote device as a float.

**Syntax**

**Parameters**

| uuid         | The UUID of the characteristic to read from. |
| ------------ | -------------------------------------------- |
| float\_value | The float value to write.                    |

<table><thead><tr><th width="358.5"></th><th></th></tr></thead><tbody><tr><td>serviceIndex</td><td>ranges from 0 to <code>(getServiceCount() - 1)</code>.</td></tr><tr><td>characteristicIndex</td><td>ranges from 0 to <code>(getCharacteristicCount(serviceIndex) - 1).</code></td></tr></tbody></table>

**Returns**

\>0 if written successfully.

0 if failed to write.
{% endtab %}
{% endtabs %}