Bluetooth LE

We have created the BLE Developer Tool to support you in the creation of Bluetooth Low Energy apps. This tool makes it easy to explore the functionality of a device without having to write code.

Overview

You can find the BLE Developer Tool in the Homey Developer Portal.

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

Peripheral

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

Some devices cannot be connected to, for example when all their data is shown in the advertisement already and a connection is not necessary.

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.

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.

Column 2: Peripheral

Services

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

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.

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.

Reading, Writing and Descriptor discovery.

Read results from a characteristic user description descriptor

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

The Characteristic User Description Descriptor. Reading from this descriptor is often a good idea.

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.

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.

A live feed of incoming notifications.

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.