Addreess

This will be in the form of a mac address. This is 6 pairs of numbers separate by colons. e.g. 11:22:33:44:55:66 This should be unique to each device.

UUID

A UUID is a 128-bit value that are written in groups 0f 8-4-4-4-12. For example 00002A00-0000-1000-8000-00805F9B34FB.

Each characteristic will have a UUID that represents what it is. The number above is for the Device Name Characteristic.

Writing those long numbers is cumbersome so Bluetooth official characteristics can be shortened to 16-bits. This means you will often see the above Device Name Characteristic written as 0x2A00 although on the system it will still be the 128-bit value. The official Bluetooth base UUID is: 0000xxxx-0000-1000-8000-00805F9B34FB and the 16-bit value replaces the x’s.

Create a device object

Import the library to you code and tell it about the address of the peripheral device to connect to.

import BLE_GATT
my_device = BLE_GATT.Central('11:22:33:44:55:66')

Connect and disconnect

Establish (or remove) a Bluetooth connection between the Linux computer your code runs on and the peripheral device.

my_device.connect()
my_device.disconnect()

Exchange Information

The API uses the structure of the command name is the activity you want to perform on the characteristic. The first parameter is the UUID of the characteristic you want to perform that on. To save us keep writing the long UUID, it is a good idea to create a constant/variable with the UUID value

Bluetooth data is always an array of unsigned bytes. We can represent that in Python as a list of values between 0 and 255. Numbers that are bigger than 255 will take multiple bytes. We can connect these together in Python with int.from_bytes or struct.unpack.

To create the values to write we can use int.to_bytes or stuct.pack

Expect Bluetooth data to be in little endian format.

my_custom_uuid = '12345678-1234-1234-1234-123456789ABC'
value = my_device.char_read(my_custom_uuid)
my_device.char_write(my_custom_uuid, [255, 255, 0, 123])

Asynchronous Data

As well as reading and writing data, it is also possible get notifications from a Bluetooth peripheral when the value of a characteristic has changed. This is very efficient on Bluetooth traffic and also the battery of the peripheral as it can turn the radio off when there isn’t new data. For programming the client it means we don’t know when there is going to be data to handle. This requires us to code using asynchronous technique.

We do this be using the on_value_change command for the GATT characteristic UUID of interest. We give it a function that will get called when the value changes. We also need to use wait_for_notifications to stop the code exiting. This runs an event loop listening for updates.

def my_callback(value):
    print(value)
on_value_change(my_custom_uuid, my_callback)
wait_for_notifications())

If you want to stop getting notifications from a GATT characteristic UUID then there is:

remove_notify(my_custom_uuid)

There is also a command that will remove all notifications, exit the event loop, and disconnect from the peripheral device.

cleanup()

From bytes

If we had three values of 12.34, 23.45, 34.56 they would arrive as [210, 4, 41, 9, 128, 13]. Let’s see how we could covert them using firstly struct.

>>> value = [210, 4, 41, 9, 128, 13]
>>> import struct
>>> struct.unpack('<HHH', bytes(value))
(1234, 2345, 3456)
>>> [value * (10 ** -2) for value in struct.unpack('<HHH', bytes(value))]
[12.34, 23.45, 34.56]

And doing the same using int.from_bytes

>>> int.from_bytes(value[0:2], byteorder='little', signed=False)
1234
>>> int.from_bytes(value[0:2], byteorder='little', signed=False) * (10 ** -2)
12.34
>>> int.from_bytes(value[2:4], byteorder='little', signed=False) * (10 ** -2)
23.45
>>> int.from_bytes(value[4:6], byteorder='little', signed=False) * (10 ** -2)
34.56

To Bytes

If we were sending this data then it needs to go from being floating point numbers to a list of bytes.

Using struct

>>> c_min = 12.34
>>> c_typ = 23.45
>>> c_max = 34.56
>>> expo = 10 ** 2
>>> list(struct.pack('<HHH', int(c_min * expo),
                             int(c_typ * expo),
                             int(c_max * expo)))
[210, 4, 41, 9, 128, 13]

Using int.to_bytes

>>> list(b''.join((int(c_min * expo).to_bytes(2, byteorder='little', signed=False),
...                int(c_typ * expo).to_bytes(2, byteorder='little', signed=False),
....               int(c_max * expo).to_bytes(2, byteorder='little', signed=False))))
[210, 4, 41, 9, 128, 13]