# Bluetooth LE

## Overview

You can find the [BLE Developer Tool](https://tools.developer.homey.app/tools/ble) in the [Homey Developer Portal](https://tools.developer.homey.app/).

With this tool you can discover, make connection, and communicate with these devices through Homey. The tool follows the structure of the BLE hierarchy, which is as follows: *All Advertisements -> Peripheral -> Service -> Characteristic -> Descriptor*. Below each level of the hierarchy is described in more detail.

## Advertisements

Advertisements shows all devices detected by Homey sorted on signal strength (`RSSI`). It is possible to perform a device discovery by clicking the 'discover devices' button at the top of the column. Clicking on one of the advertisements will open the peripheral, which provides more details on that device.

![Column 1: Advertisements](/files/-MYPaE1WHddeDqwvTZ06)

## Peripheral

The peripheral shows more information for the selected device. For most BLE devices it is possible to connect and disconnect with the device.

{% hint style="info" %}
Some devices cannot be connected to, for example when all their data is shown in the advertisement already and a connection is not necessary.
{% endhint %}

To interact with a device, first a connection needs to be made. After a succesfull connection more options become available, such as discovering Services and Characteristics, updating RSSI and disconnection from the device. Selecting a service will show more details and functions that can be performed on the selected service.

{% hint style="info" %}
The *"Discover Services"* and "*Discover Services & Characteristics"* initially perform the same operation, although the latter one will save you some time in the next column, which is the service column.
{% endhint %}

![Column 2: Peripheral](/files/-MYPbb6U1MZvR-nZOEGw)

## Services

Every service is a collection of one ore more Characteristics. These need to be discovered first before more information can be displayed.

![](/files/-MYPdVKBzC2SqpCBX7jd)

## Characteristics

Characteristics are the most complex section in the BLE Developer Tool. Each characteristic is a specific functionality of the device. This can range from reading the device identifier to telling the device to perform a specific action (for instance a BLE light bulb can be told to change it's color).

### Reading and Writing

Most characterisics can be used to read and/or write to the device. Data read from a device will be shown in multiple formats, helping you to quickly decode the data.

{% hint style="info" %}
Often a characteristic that can be written to will also allow you to read the current value of that descriptor. If you have a RGBW lamp it may be possible to read from a characteristic and receive the result \[0, 255, 0, 0]. If your lamp is currently green, the data is probably formatted like \[R, G, B, W]. If your lamp is red, it is probably formatted like \[W, R, G, B]. In such a case you can try writing \[255, 0, 0, 0] to see what it does.
{% endhint %}

![Reading, Writing and Descriptor discovery.](/files/-MYPgA_edYUqB3chDjLV)

![Read results from a characteristic user description descriptor](/files/-MYPgbR07BYhaPvRZCGc)

![Writing data. You need to write the data as a buffer in decimal format. (for example: \[255, 0, 0\])](/files/-MYPgUdi_IJNPxVuFr63)

![The Characteristic User Description Descriptor. Reading from this descriptor is often a good idea.](/files/-MYPgZn-eCHHkWzi-Vyq)

{% hint style="info" %}
Reading from a characteristic often will only give you some raw data without explanation or description. Often there is a "Characteristic User Description" - descriptor present that provides more details on the meaning of these values in the descriptor.
{% endhint %}

### BLE Notifications

The BLE Developer tool allows you to subscribe for BLE Notifications. After subscribing, you can view all the received notifications from the device.

![The buttons for using BLE Notification functionality. If BLE Notifications are not supported by the device these buttons are disabled.](/files/-MYPejiXYjui-FQWyLpg)

![A live feed of incoming notifications.](/files/-MYPff2cieVctgiWlrfA)

## Descriptors

Although not always present, descriptors provide extra information about the characteristic it belongs to, for example a user description or subscription status. The "read" and "write" buttons behave similar to the "read" and "write" buttons in a characteristic.

![The characteristic view for the "Characteristic User Description" - Descriptor.](/files/-MYPjB0yKLttzuXIMQZN)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apps.developer.homey.app/guides/tools/bluetooth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.