# Bluetooth Low Energy

## Description

Bluetooth Low Energy, or BLE, is used to wirelessly connect two devices to one another. The BLE component allows you to find and connect to BLE devices and to communicate directly with them.

{% hint style="info" %}
BLE functionality can't be tested with the [Thunkable Live](https://docs.thunkable.com/get-started/live-test) app on iOS. \
To test the BLE functionality in your app on iOS, please [download](https://docs.thunkable.com/download#download-and-install-ios-app) your app.
{% endhint %}

{% embed url="<https://youtu.be/sNpCTsVifo4>" %}

## Blocks

### Scan

This function is used to scan for nearby BLE or Bluetooth enabled devices. Scanning happens for 10 seconds. Once scanning has successfully completed then a list of the available device ids and a list of available names will be returned. If the scanning function can not be completed then an error will be returned.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2F3uUO2UNKcfxCscXalf93%2Fimage%20-%202024-10-11T213647.098.png?alt=media&#x26;token=1d1364a8-3820-451f-900d-89ec955192f2" alt=""><figcaption></figcaption></figure>

| Parameter    | Type   | Description                                                                                                     |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
| Device Ids   | List   | **Returns** a list of the IDs of the available devices                                                          |
| Device Names | List   | **Returns** a list of the names of the available devices                                                        |
| Device RSSIs | List   | **Returns** a list of the signal strengths (in dBm) for the available devices, measured relative to 1 milliwatt |
| error        | String | **Returns** an error message from the function                                                                  |

**Example**

<div align="left"><figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FuyDqZy4UwJf0LM7TNO9t%2Fimage%20-%202024-10-11T213842.836.png?alt=media&#x26;token=4c1bc8e7-3e25-400a-8d04-cf8a50f187d9" alt=""><figcaption></figcaption></figure></div>

The Location Sensor returns a list of names of the available BLE devices which can be connected to a Simple List.

### Connect to Device Id

The `Connect to Device Id` function allows your app to connect to a BLE enabled device based in the Id of that device.

![](https://689802330-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LAn5scXl2uqUJUOqkJo%2F-Lh1y0iWs6BX8EEZjRPo%2F-Lh22ktQnLz3tZoA6dF9%2Fbluetooth_connectToDeviceId.png?alt=media\&token=e86a936b-4bed-48fe-8988-4a7c8b5a2661)

| Parameter   | Type   | Description                                                         |
| ----------- | ------ | ------------------------------------------------------------------- |
| Device Id   | String | **Expects** a text string with the device id you want to connect to |
| Device Name | String | **Returns** the name of the device you have just connected to       |
| error       | String | **Returns** an error message from the function                      |

### Connect to Device Name

When you know the name of the BLE device that you want to connect to you can use the `Connect to Device Name` block to connect directly to it. Please note that device names are not unique and it is relatively easy to change the name of a BLE device.

![](https://689802330-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LAn5scXl2uqUJUOqkJo%2F-Lh1y0iWs6BX8EEZjRPo%2F-Lh22ktOxXrwEjr2FTJ3%2Fbluetooth_connectToDeviceName.png?alt=media\&token=ff05b71b-1a66-43a9-b100-209cd422a4b0)

| Parameter   | Type   | Description                                                        |
| ----------- | ------ | ------------------------------------------------------------------ |
| Device Name | String | **Expects** a text block with the name of the device to connect to |
| Device Id   | String | **Returns** the Id of the device that you have just connected to   |
| error       | String | **Returns** an error message from the function                     |

**Example**

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FFycWAsIFrShpbAM9MCpU%2Fimage%20-%202024-10-11T213902.996.png?alt=media&#x26;token=e1b00ec7-55da-4b21-a49a-30cad43dfef6" alt=""><figcaption></figcaption></figure>

Present the list of names of the available BLE devices in a simple list allowing users to connect on the device they click using the `Connect to Device Name` block and connect it to the `item` block.

| Input Name          | Data Type                                                               | Description                                                                           |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| characteristic UUID | Text                                                                    | Expects a text block with a 32-bit UUID for the BLE type, service or profile required |
| data                | array ([list](https://docs.thunkable.com/snap-to-place/lists)) of bytes | Expects a text block with the message that you want to send to your BLE device        |

#### Outputs

| Output Name | Data Type | Description                                                             |
| ----------- | --------- | ----------------------------------------------------------------------- |
| error       | Text      | If an error message is returned, returns the error. Else returns `null` |

| Output Name       | Type                                                                    | Description                                                                  |
| ----------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| data (string)     | Text                                                                    | Returns a string containing the information received from the BLE device     |
| data (byte array) | array ([list](https://docs.thunkable.com/blocks/blocks/lists)) of bytes | Returns a byte array containing the information received from the BLE device |
| error             | Text                                                                    | If an error message is returned, returns the error. Else returns `null`      |

### Subscribe To Characteristics

To receive data from a BLE device, capable of sending data to another device as notifications, you need to use the `Subscribe To Characteristics` function in your app. This function allows you to listen to updates from the peripheral device by subscribing to its characteristics and receiving data through the "notify" method.&#x20;

To use this functionality, ensure your app is already connected to the desired Bluetooth device.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FHRn8ewl1Omfu4sPkMdXY%2Fsubscribe%20to%20characteristics.jpg?alt=media&#x26;token=02b179a5-ba8e-4154-9953-7dc9a5141050" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name          | Data Type | Description                                                                           |
| ------------------- | --------- | ------------------------------------------------------------------------------------- |
| characteristic UUID | Text      | Expects a text block with a 32-bit UUID for the BLE type, service or profile required |

#### Outputs

| Output Name | Type | Description                                                             |
| ----------- | ---- | ----------------------------------------------------------------------- |
| error       | Text | If an error message is returned, returns the error. Else returns `null` |

### Characteristics Change

If you are connected to a BLE device that is capable of sending data to another device using the  "notify" method and you have already subscribed to a characteristic then you need to use the `Characteristic Change` function in your app. This block alerts you whenever the characteristic value changes on the peripheral (server) device.  Data from the BLE device may be received in either String or Byte format.

Ensure that you have subscribed to the characteristic to use this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2F6Dp1qu32pW97Gh68tLaK%2Fwhen%20characteristics%20changes%20notify.jpg?alt=media&#x26;token=b8745400-6bd3-46bd-a29b-a2641556481a" alt=""><figcaption></figcaption></figure>

Set something to happen when the Characteristics Change.

#### Outputs

| Output Name       | Type                                                                    | Description                                                                  |
| ----------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| data (string)     | Text                                                                    | Returns a string containing the information received from the BLE device     |
| data (byte array) | array ([list](https://docs.thunkable.com/blocks/blocks/lists)) of bytes | Returns a byte array containing the information received from the BLE device |
| error             | Text                                                                    | If an error message is returned, returns the error. Else returns `null`      |

**Example**

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FNQzLXWrsYNHtVfzgJZCM%2Fexample%20notify.png?alt=media&#x26;token=0e3cddef-e2a2-490d-98c0-03bfe9ebbeec" alt=""><figcaption></figcaption></figure>

Connect to a specific device using Device ID. Subscribe to a characteristic using characteristic UUID and set the new data to labels when the characteristics change.

### Disconnect

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FO2BiZtEUO6Ljlsr7CmhA%2Fdisconnect.png?alt=media&#x26;token=1788895c-b63e-445d-bdaa-8b9b67dd1daf" alt=""><figcaption></figcaption></figure>

If connected to another Bluetooth device, this block will disconnect your app from the device.

### Receive String

If you have a BLE device that is capable of sending data to another device then you will need to use the `Receive String` function in your app in order to listen to, or receive, data coming from the BLE device in String format.

You need to be connected to another Bluetooth device in order to use this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2F9DLFRyx2JqWnz7oLrzFw%2Freceive_string.png?alt=media&#x26;token=ee703d4c-dc87-437b-a5d8-d4a28fb90730" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name          | Data Type | Description                                                                           |
| ------------------- | --------- | ------------------------------------------------------------------------------------- |
| characteristic UUID | Text      | Expects a text block with a 32-bit UUID for the BLE type, service or profile required |

#### Outputs

| Output Name   | Type | Description                                                              |
| ------------- | ---- | ------------------------------------------------------------------------ |
| data (string) | Text | Returns a string containing the information received from the BLE device |
| error         | Text | If an error message is returned, returns the error. Else returns `null`  |

### Receive Byte Array

If you have a BLE device that is capable of sending data to another device then you will need to use the `Receive Byte Array` function in your app in order to listen to, or receive, data coming from the BLE device in Byte Array format.

You need to be connected to another Bluetooth device in order to use this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FSUjB0N6wHX0HoBXXf44z%2Freceive_byte_array.png?alt=media&#x26;token=f737c7a7-316c-4916-8dc6-69884bb78cf4" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name          | Data Type | Description                                                                           |
| ------------------- | --------- | ------------------------------------------------------------------------------------- |
| characteristic UUID | Text      | Expects a text block with a 32-bit UUID for the BLE type, service or profile required |

#### Outputs

| Output Name       | Data Type                                                               | Description                                                                  |
| ----------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| data (byte array) | array ([list](https://docs.thunkable.com/snap-to-place/lists)) of bytes | Returns a byte array containing the information received from the BLE device |
| error             | Text                                                                    | If an error message is returned, returns the error. Else returns `null`      |

### Listen for Disconnection

This asynchronous function listens for when your device disconnects from a named Bluetooth device.

You can program some events to happen when your device disconnects from the named device in the `then do` section of this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FOrb8quCRBuhWzIvEYaY9%2Flisten_for_disconnection.png?alt=media&#x26;token=cd6a95a9-cbea-40f6-884b-9197a4a455b1" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name | Data Type | Description                                                        |
| ---------- | --------- | ------------------------------------------------------------------ |
| Device Id  | Text      | Unique ID of the bluetooth device to listen for disconnection with |

#### Outputs

| Output Name | Data Type | Description                                                             |
| ----------- | --------- | ----------------------------------------------------------------------- |
| error       | Text      | If an error message is returned, returns the error. Else returns `null` |

### Transmit String

Use this block to send data as a string of text to a BLE device.

You need to be connected to another Bluetooth device in order to use this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FWsrdxCHxefPDsDAilT6F%2Ftransmit_string.png?alt=media&#x26;token=0799b6c1-7c56-4ccf-b516-06b99be21384" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name          | Data Type | Description                                                                               |
| ------------------- | --------- | ----------------------------------------------------------------------------------------- |
| characteristic UUID | Text      | **Expects** a text block with a 32-bit UUID for the BLE type, service or profile required |
| data                | Text      | Expects a text block with the message that you want to send to your BLE device            |

#### Outputs

| Output Name | Data Type | Description                                                             |
| ----------- | --------- | ----------------------------------------------------------------------- |
| error       | Text      | If an error message is returned, returns the error. Else returns `null` |

### Transmit Byte Array

Use this block to send data as an array ([list](https://docs.thunkable.com/snap-to-place/lists)) of bytes to a BLE device.

You need to be connected to another Bluetooth device in order to use this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FhiWR6qBplHqRLxbh1cFH%2Ftransmit_byte_array.png?alt=media&#x26;token=55405aea-8c21-4087-9791-b40ba40b0ca9" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name          | Data Type                                                               | Description                                                                           |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| characteristic UUID | Text                                                                    | Expects a text block with a 32-bit UUID for the BLE type, service or profile required |
| data                | array ([list](https://docs.thunkable.com/snap-to-place/lists)) of bytes | Expects a text block with the message that you want to send to your BLE device        |

#### Outputs

| Output Name | Data Type | Description                                                             |
| ----------- | --------- | ----------------------------------------------------------------------- |
| error       | Text      | If an error message is returned, returns the error. Else returns `null` |

### Transmit Hexadecimal

Use this block to send data in [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) format to a BLE device.

You need to be connected to another Bluetooth device in order to use this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FqYJszgSaw9V8e3bPNb7A%2Fhex.png?alt=media&#x26;token=a1072dcc-3071-4c73-b477-6092cca50696" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name          | Data Type                                                               | Description                                                                           |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| characteristic UUID | Text                                                                    | Expects a text block with a 32-bit UUID for the BLE type, service or profile required |
| data (hexadecimal)  | data in [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) format | Expects a text block with the message that you want to send to your BLE device        |

#### Outputs

| Output Name | Data Type | Description                                                             |
| ----------- | --------- | ----------------------------------------------------------------------- |
| error       | Text      | If an error message is returned, returns the error. Else returns `null` |

### Transmit Base64

Use this block to send data in [base64](https://en.wikipedia.org/wiki/Base64) format to a BLE device.

You need to be connected to another Bluetooth device in order to use this block.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FMxviHcHsoDxagvtoJlFy%2FScreenshot%202024-11-21%20024745.png?alt=media&#x26;token=2075a1f4-8947-45ad-9230-01503842aa56" alt=""><figcaption></figcaption></figure>

#### Inputs

| Input Name          | Data Type                                                     | Description                                                                           |
| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| characteristic UUID | Text                                                          | Expects a text block with a 32-bit UUID for the BLE type, service or profile required |
| data                | data in [base64](https://en.wikipedia.org/wiki/Base64) format | Expects a text block with the message that you want to send to your BLE device        |

#### Outputs

| Output Name | Data Type | Description                                                             |
| ----------- | --------- | ----------------------------------------------------------------------- |
| error       | Text      | If an error message is returned, returns the error. Else returns `null` |

{% hint style="info" %}
All values (string, HEX, Byte array, Base64) are being converted to a byte array before sending.
{% endhint %}