Exploring the GATT table for an unknown device

       Right now the BLE (Bluetooth Low Energy) SensorTag (BLE SensorTag - blessTags) application is able to work with 4 different sensors tags: CC2541, CC2650 (both produced by TexasInstruments Company), Thunderboard React and Thunderboard Sense (both produced by Silicon Labs Company). Additionally, the application can work with unknown BLE devices. Here, in this post, we define unknowns BLE devices as all devices other than those listed above.

          In order to present the application's functionality with unknown devices, we will use a previous version of it, in which the features for the Thunderboard React and Thunderboard Sense have not yet been implemented. The main goal is to present, at the end of this post, the complete attribute table for Thuneroard Sense and the way it came to it. This document is also necessary due to the fact that in the official product documentation the attribute table is not provided to the users - at least as much as I know about this subject.

         The first step to figure out how to interact and work with Thunderboard Sense is to investigate the GATT services exposed by the SensorTag and the GATT service’s characteristics. 
          GATT (generic attribute) is a protocol for interacting with BLE devices. All the BLE devices expose a list of services and each service exposes a list of characteristics which can be read and/or written by a BLE application (as the blessTags - BLE SensorTag application). A service can have one or more characteristics. Each service distinguishes itself from other services by means of a unique numeric ID called a UUID. UUID can be either on 16-bits (for officially adopted BLE Services) or 128-bits (for custom services).

         In order to be able to obtain the complete GATT attribute table for Thunderboard React, we will use two basic documents: Thnuderboard React Kit User's Guide (we're leaving from the idea that ThunderBoard Sense is an improved version of the Thunderboard React) and the official Android application code (mainly, we are interested in ThunderBoardUuids.java file - see the path to this file, shown in the figure below).

         

        With the ThunderBoardSense sensor tag turned on and paired with the computer, push the “Refresh SensorTag List” button (in this mode you can get a lists of all the BLE devices that are advertising themselves) and, after this, select “Unknown BLE devices” radio button. In the end, select “Developer Mode” check box.

  As a result a new panel will open – the developer panel. Using 2 main buttons, of this panel, the information regarding 2 main services on the unknown sensor tag can be acquired and displayed: Generic Access Service (UUID: 0x1800), it is a mandatory service on BLE standard, and Device Information Service (UUID: 0x180a), this service exposes manufacturer and/or vendor information about a BLE device. These 2 officially adopted BLE services will provide us with basic BLE device-related information. To get a complete list of all officially adopted BLE services check this link.

           In this mode, based on these two services, we can have a first impression (a first “touch”), related with the unknown BLE device. The query result, of these 2 services, is presented below. One of the most important thing to note here is the MAC address of the BLE device, D5:75:36:57:0B:00. The MAC address is a unique ID that will be different for every BLE device.

The results presented in the Developer Panel will always include, both, the user’s required information, from the BLE device, and many other types of information related to the operation of the SensorTag BLE application. The usefulness of this information, related to the intimate operation of the SensorTag BLE application, will be presented in another post.

_____________________________________________________________________
The following messages are generated in the process of getting information from Generic Access Service (0x1800):

Handle to bluetooth device found
  1 services founded.
  ----------------------
   2 characteristics founded.
    UUID_0 = 2a00
    UUID_1 = 2a01
  ----------------------
Device Name {2A00}: Thunder Sense #30165
Appearance values {2A01}: 00

The handle to SensorTag was closed successfully (getting information from Generic Access Service)
_____________________________________________________________________________________
 The following messages are generated in the process of getting data from SensorTag Device Information service (0x180A): Handle to bluetooth device found
  1 services founded.
  ----------------------
   6 characteristics founded.
    UUID_0 = 2a29
    UUID_1 = 2a24
    UUID_2 = 2a25
    UUID_3 = 2a27
    UUID_4 = 2a26
    UUID_5 = 2a23
  ----------------------
System ID {2A23}:          00:0B:57:FF:FE:36:75:D5
BLE MAC address:           D5:75:36:57:0B:00
Model Number {2A24}:       BRD4160A
Serial number {2A25}:      1234 (31:32:33:34)
Firmware Revision {2A26}:  0.4.1
Hardware Revision {2A27}:  A00
Manufacturer Name {2A29}:  Silicon Laboratories

The handle to SensorTag was closed successfully (in Get Tag Info Functions)
______________________________________________________________________________________

The same information as above can be obtained entering the UUID in the CLSID field and clicking the button “Check a device for service and characteristics”. For example using the UUID 0x1800 (00001800-0000-1000-8000-00805f9b34fb) we will get from the BLE sensor tag the following data.

--------------------------------------------------------------------------------------------------------------------------------

 1 services founded:

  |0x01| 1| 0x2800                      | GATT Primary Service Declaration | [R]
{00001800-0000-1000-8000-00805f9b34fb}

--------------------------------------------------------------------------------------------------------------------------------

  2 characteristics founded:

--------------------------------------------------------------------------------------------------------------------------------

  |0x02| 2| 0x2803                      | GATT Characteristic Declaration    | [R]

  |0x03| 3| UUID_0 = {0x2a00}   | Characteristic Value Declaration    | [R,W] Value(s) = [54:68:75:6E:64:65:72:20:53:65:6E:73:65:20:23:33:30:31:36:35] or [20 bytes]

--------------------------------------------------------------------------------------------------------------------------------

  |0x04| 4| 0x2803                      | GATT Characteristic Declaration    | [R]

  |0x05| 5| UUID_1 = {0x2a01}   | Characteristic Value Declaration    | [R] Value(s)= [00] or [1 byte]

--------------------------------------------------------------------------------------------------------------------------------

We observe that the information obtained it is similar, with the one previously founded (by pressing the “Get Generic Access data” button), but it is put in another format. So we have 1 service (with the UUID: 0x00001800-0000-1000-8000-00805f9b34fb) that has 2 characteristics (with the UUIDs: 0x2a00 and 0x2a01). If we convert the HEX values (54:68:75:6E:64:65:72:20:53:65:6E:73:65:20:23:33:30:31:36:35) from the first characteristics, we will get “Thunder Sense #30165”.

If when a specific service will be interrogated (like 0x00001800-0000-1000-8000-00805f9b34fb), it is possible to get the following error: “Error of BluetoothGATTGetServices in GetGattService function - error value 6, message: The handle is invalid”. In such case please check the “GATT permissions – only read” check box. From this service, the characteristics can only be read.

From the Thunderboard Sense User's Guide (UG250) we know that the Thunderboard Sense includes the following key hardware sensors and devices:

1. 6-Axis Inertial Sensor  - InvenSense ICM-20648
2. Relative Humidity and Temperature Sensor - Silicon Labs Si7021
3. UV Index and Ambient Light Sensor - Silicon Labs Si1133
4. Barometric Pressure Sensor - Bosch Sensortec BMP280
5. Indoor Air Quality Gas Sensor - Cambridge CMOS Sensors CCS811
6. MEMS Microphone Knowles SPV1840 and
7. Four high brightness RGB LEDs, one bi-color LED and two push buttons

        Android applications (for both Thunderboard React and Thunderboard Sense BLE sensor tags) groups the access to all these sensors in three sections: motion, environment and I/O.

      Starting having Thunderboard React (RD-0057-0201) User's Guide (UG164) as a reference point, the Acceleration and Orientation Service (UUID: a4e649f4-4be5-11e5-885d-feff819cdc9f) exposes the following characteristics:

By querying the Thunderboard Sense BLE sensor tags with our application, we will get the following information:

  In conclusion, we note that Silicon Labs Company has not changed anything in Acceleration and Orientation Service and the information presented in the ThunderboardReact (RD-0057-0201) User's Guide are reliable and can be used in the same mode with Thunderboard Sense BLE sensor tag. 

Another very important service is Environmental Sensing Service (UUID: 0x181a). This service in Thunderboard React sensor tag include only three characteristics (associated with the corresponding sensors): humidity (UUID: 0x2a6f), temperature (UUID: 0x2a6e) and UV Index (0x2a76).

 By querying the Thunderboard Sense device for the Environmental Sensing Service we will get the following features shown in the following figure. It is noted that on Thunderboard Sense BLE sensor tag, the Silicon Labs Company has significantly improved the Environmental Sensing Service by adding many new characteristics.
 

          After a series of tests I noticed that the characteristics 0x2a6f, 0x2a6e and 0x2a76 retain their significance and their role existing on the Thunderboard React device. So, the user guide for the Thunderboard React device can also be used with the Thunderboard Sense device for these specific services.

        Analyzing ThunderBoardUuids.java file (see the figure below) and comparing with the results obtained by querying the Thunderboard Sense device, we can see a small error in this file. The characteristic with the UUID = 0xc8546913-bf01-45eb-8dde-9f8754f4a32e does not exist in Thunderboard Sense.

                
         So, we'll have the following characteristics:

1. Characteristics with the UUID = 0xc8546913-bfd9-45eb-8dde-9f8754f4a32e => ambient Light Sensor information. The Silicon Labs manufacturer have documented this characteristic in Thunderboard React User's Guide.
2. Characteristics with the UUID = 0xc8546913-bf02-45eb-8dde-9f8754f4a32e => sound level, and
3. Characteristics with the UUID = 0xc8546913-bf03-45eb-8dde-9f8754f4a32e => environment control point.

Another very important information that is presented to us in the developer window is the way to access the data provided by the services within the characteristics. From the previous figures, we notice that the data provided by the Acceleration and Orientation Service can only be retrieved after we received a notification (marked by [N]) from the Thunderboard Sense  device. Instead, the data from the Environmental Service can be read (marked by [R]) at any time by the user.

If the BLE device manufacturer includes characteristic descriptors (Characteristic User Description, UUID: 0x2901) within the service, then understanding the characteristics function of the BLE device is a lot easier. Below is the result of the UUID = 0xf000aa00-0451-4000-b000-000000000000 service query for the CC2541 sensor tag. Analyzing the information obtained, especially the descriptors of the characteristics, we can conclude that this service is related to the temperature sensor. The first characteristic gives us the 4-byte temperature value, by means of a user-initiated readings ([R] symbol in the last column) or by notifications transmitted by the sensor ([N]). The second feature allows us to configure the existing temperature sensor in the CC2541 device. The last characteristic allows us to configure the temperature acquisition period.

Another very important feature of the application is its ability to provide real-time data from the BLE device – only in the case when the Characteristic Value Attribute is readable.  For example, if we look at the Profile User Interface Service (UUID: FCB89C40-C600-59F3-7DC3-5ECE444A401B), we notice that when we hold the left button pressed (USB jack is up) on the device we get the value shown in the first figure below.

When we press the right button we get:

And if we do not press any button, we get:

In conclusion, the characteristic with UUID = 0xFCB89C40-C601-59F3-7DC3-5ECE444A401B returns to us, in a byte, the state of the buttons.  Thus: (1) if no button is pressed the value is zero, (2) if the right button is pressed, the value will be 1 and (3) if the left button is pressed, the value returned will be 2.

This feature, to take real-time data, will allow us (when we will work with an unknown BLE device) to understand its services and characteristics through a direct interaction with it.

Comparing the data from the ThunderBoardUuids.java file, with the results obtained by querying the various services on the BLE ThunderboardSense device and performing many tests, the complete GATT table for Thunderboard Sense resulted and can been downloaded from here. 

This application,  blessTags (BLE SensorTag) application, can be downloaded from the Windows Store Apps: https://www.microsoft.com/store/apps/9p054xsjjr1n.