As a person who makes their living in the IOT world, I decided it would be handy to learn how to get data to and from the venerable NRF51288, which is certainly a contender for the best bluetooth SoC out there. One annoying thing is that the wonderful Softdevice that Nordic provides does not have a particularly clear English translation, or good pictures in their documentation. Here I will try to describe with pictures and arrows that my mechE brain is accustomed to, instead of with comments like “Attribute metadata for the User Description descriptor, or NULL for default”. Hopefully after reading this, you will have a better feel for how to make a custom service, as well as what the more formal terms are for the different parts of the service in the softdevice API.
How to read this:
The 10,000 meter view will start with the softdevce and the GATT server, then at 1,000 meters, we will inspect bas.h to see what the minimum viable functions for a bluetooth service are. At 100 meters we will look at the softdevice calls that add the information to the GATT server. at 10 meters we will look at what gets passed to those calls- the real key to understanding how to add things. At the very end, I will show you how I changed the bas example to report acceleration values. This is by no means a definitive guide, but hopefully it will give you a jumping off point for adding services to your code.
10,000 Meters: GATT and the Softdevice
The thing we want to do is add a new service to our Generic Attribute Profile (GATT) server. Adafruit does a wonderful job of explaining it here, with pictures. Once you connect to a BTLE device over a Generic Access Profile (GAP), your bluetooth client, usually something like a phone or computer, can access the GATT server, usually something like a the NRF5.
A GATT server can have characteristics, as well as services. Services are groupings of characteristics. Services are distinguished by a 128-bit UUID. Some of them are reserved for particular types of services, like a heart rate monitor, but we will deal with making sure we don’t use those later. Two that are always included are the Generic Access Service and The Generic Attribute Service.
Characteristics live inside of services, and have characteristic values. These characteristics can also have descriptors, which can tell you useful stuff like what the name of the characteristic is. Characteristics are things that can be read and written to the server. A client might read log data or a sensor value, and it might write a new state for the device or a device name.
The way that you access the GATT server on the NRF51288 (as well as the NRF52) is through the nordic softdevice (SD), which is a pre-compiled binary that you append to the beginning of your user application code. It handles all the GATT and GAP stuff, and you need to tell it to do things like add services and characteristics using calls to the softdevice that are provided by nordic.
1000 Meters: What is in bas.h
typedef struct
{
...
} ble_bas_init_t;
typedef struct ble_bas_s
{
...
} ble_bas_t;
uint32_t ble_bas_init(ble_bas_t * p_bas, const ble_bas_init_t * p_bas_init);
void ble_bas_on_ble_evt(ble_bas_t * p_bas, ble_evt_t * p_ble_evt);
uint32_t ble_bas_battery_level_update(ble_bas_t * p_bas, uint8_t battery_level);
Taking a look at an abbreviated version of what is in bas.h will let us know what kinds of things a a bluetooth service might need to do, and what kind of stuff we should have to use the SDK as a template. Here is a listing of the most important stuff in bas.h
Structs:
ble_bas_init_t- this holds all the data for initializing the service
ble_bas_t – this holds all the data for actually running the service
Functions:
ble_bas_init – this initializes the service, and inserts your vendor specific UUID, your service, and characteristics into the softdevice
ble_bas_on_ble_evt – this is called when the softdevice thinks something interesting has happened over BT that concerns the bas service. For example, a client might write a new value to the server, or want to read a new value from the server.
ble_bas_battery_level_update – this actually updates the value of the characteristic with the new battery level.
So, all the stuff you need is in ble_bas_init_t and ble_bas_t, for the actual data about the services, and then you call ble_bas_init and it gets added to the softdevice. After that ble_bas_battery_level update gets called every now and then, and if anything interesting happens bluetooth-wise to the service, ble_bas_on_ble_evt handles it.
100 Meters: Adding a Service and Characteristics
Of these, ble_bas_init and ble_bas_battery_level_update are the most interesting functions, so we should look inside of them to see what is going on. Here we will be focusing on sd_ble_XXXXXX calls, which actually add things to the Bluetooth Low Energy SoftDevice- hence sd_ble. later we will go back and look at what we are actually feeding these functions.
ble_bas_init is a small function , but it also calls batter_level_char_add which we will need to take a look at- it is something we did not see in bas.h, but it adds the actual battery level characteristic to the service. The big ble_sd calls here are:
BLE_UUID_BLE_ASSIGN
this is just a macro to put the BLE_UUID_BATTERY_SERVICE information into a struct for later- if we want to make a custom service we will have to do it a different way, since our custon ble UUID needs to be added to the softdevice.
sd_ble_gatts_service_add
This adds our service. There are some options here, but as long as you have this you will be able to see a service with the BLE_UUID_BATTERY_SERVICE if you look at your device with something like the nrf master control panel app.
inside of battery_level_char_add, a lot of other ble_sd calls happen- lets take a look!
sd_ble_gatts_characteristic_add
this actually adds our characteristic. This is pretty useful, since we want it added.
sd_ble_gatts_descriptor_add
this actually adds the descriptor of the characteristic to the characteristic.
10 Meters: What goes into Softdevice BLE Calls
This is the real dive into the nonsense that is the NRF5 SDK. I think that a flow chart/visual way of organizing this information is nice, although you have to zoom way in to read the text. This is just another way of organizing the data, but instead of having to jump around a bunch of windows and files, I put it all in one place- like a cheat sheet.
These are meant to be read from the bottom up- look at the “what can you control” bar to see what you can change, the “where it comes from” bar to see how to actually make the change, and then the “where you can put it” bar shows where you need to put the variables in the sd_ble call.
sd_ble_gatts_service_add
This char has three layers explaining the arguments of the sd call. The bottom layer is what you can change, the middle layer is how to generate the change, and the top layer is the actual argument and type that gets passed to sd_ble_gatts_service_add.
Here you can change the type of service between primary and secondary. A secondary service is a service within a service, which seems fairly unusual. You can also set the UUID of the service. If you want to use a bluetooth SIG approved service, then you want to something like:
BLE_UUID_BLE_ASSIGN(ble_uuid, BLE_UUID_BATTERY_SERVICE);
which is a macro that will fill the appropriate fields of ble_uuid with the info for a battery service UUID. NB, if you put weird characteristics inside of this service, the client may not be able to find the correct data, and you will not be compliant with the BTLE spec.
If you want to make your own custom service, you should do something like
sd_ble_uuid_vs_add(&acc_acce_uuid, &p_acc->uuid_type);
ble_uuid.type = p_acc->uuid_type;
ble_uuid.uuid = BLE_UUID_TYPE_VENDOR_BEGIN;
This will make a new vendor specific (vs) UUID and then you manually stuff the values into ble_uuid before passing it to sd_ble_gatts_service_add. When the function is called, the softdevice will write to the pointer for the service handle. This is important for later on, when you may want to modify the service- for example, adding a characteristic.
sd_ble_gatts_characteristic_add
Here you can change the service the characteristic is attached to, the characteristic metadata, and the structure that holds the characteristic value. Just like sd_ble_gatts_service_add we also pass it a pointer to a handle that gets filled in by this function. Unlike sd_ble_gatts_service_add there are about a million things that go in here, so each one will need its own diagram.
In the bas service example, we are adding a battery level characteristic to the service, so we should pass in the handle that was written by sd_ble_gatts_service_add. We could pass in any service handle that was written by the softdevice, and it would add the service to that softdevice.
The characteristic metadata is how you control the properties of the characteristic, such as the read/write permissions and user description (a text description of the characteristic), but nothing to do with the value itself. It has many many fields and some of those are actually other kinds of metadata structs. The main groupings of structures are:
First, things that have to do with the properties of the characteristic, such as broadcast, indication, notification and read write permissions, writing with queued request and writing the characteristic user description, as well as the use of bluetooth assigned numbers to indicate the unit, exponent, and format, of the characteristic. These are all about the actual characteristic and the value that it represents. This is useful if you wanted to say that the value you are sending to the client is a uint16_t that represents micro-coulumbs for your battery measurement.
Second, the user description- this is really handy if you want to have a string associated with the value that you send that says “battery level”. Here the important things are a pointer to a string buffer that holds the value, as well as the current length of the value, and the maximum length. Maximum length is important if the descriptor is re-written. The last part of this grouping is the ble_gatts_attr_md_t, which controls how the description can be read and written.
The final grouping has to do with permissions around turning on and off notifications and indications, which live in the Server Characteristic Configuration Descriptor (SCCD) and Client Characteristic Configuration Descriptor (CCCD). This post does a decent job of explaining it.
The last thing that goes into sd_ble_gatts_characterisitc_add is a structure that holds the characteristic value contains two main groupings. The first is a pointer to a buffer that holds values of the characteristic, as well as information about the max length of the buffer, the size of each record in the buffer and the current offset. The other grouping contains the metadata about r/w permissions.
sd_ble_gatts_descriptor_add
This is the last softdevicecall, and mercifully it is pretty short. Just like the other calls, you give it the handle of the characteristic it belongs to, as well as a pointer to store the handle for the descriptor. The only real data you need to set up for it is a ble_gatts_attr_t which is the same as the one used in the sd_ble_gatts_characteristic_add call.
1 meter view- Custom Service
Lets make a new service- this will document the major changes from bas to a custom accelerometer service with three characteristics that represent x, y, and z accelerations. For the sake of clarity, we will assume there are functions that do things like get the accelerometer data. I will show code snippets in the post, but you can also see the whole project here, commit 705deb.
First off, we need to add a custom UUID to our service in ble_bas_init.
ble_uuid_t ble_uuid;
ble_uuid128_t acc_acce_uuid = {{0xAA, 0xCA, 0x55, 0xAC, ..., 0xEF}};
err_code = sd_ble_uuid_vs_add(&acc_acce_uuid, &p_acc->uuid_type);
ble_uuid.type = p_acc->uuid_type;
ble_uuid.uuid = BLE_UUID_TYPE_VENDOR_BEGIN;
This adds our new made-up UUID to the softdevice, and then we pack the data into ble_uuid for later use in sd_ble_gatts_service_add.
Next up, we need to make some characteristics to belong to this service! I will focus on only one characteristic here, because they are all acceleration data (just in different axes).
Compared to the battery level, we will want to make it a uint16_t instead of a uint8_t, give it a text description and add some nice units to our characteristic.
Lets start with making the value a uint16_t. To change this in the GATT server, we will need to edit the ble_gatts_attr_t that represents the characteristic value that gets passed into sd_ble_gatts_characteristic_add. In the code, that is called att_char_value. To make the characteristic value a uint16_t instead of uint8_t, we need to do this:
attr_char_value.init_len = sizeof(uint16_t);
attr_char_value.max_len = sizeof(uint16_t);
This will change the expected size of the record in the characteristic. Now it is expected to be a uint16_t. NB this only changes what the softdevice expects, so there are several other places in the code that will need to be changed to use the proper variable size.
Now for the text description. This is handy, because your app might want to know what each characteristic represents, other than some crazy uuid. This is pretty easy, since this information lives in the ble_gatts_char_md_t struct that we already passed to sd_ble_gatts_characteristic add. We just have to change it by actually making a char buffer and passing the information about the user description size and max size into the struct, like this:
uint8_t user_desc[] = "ACCEL";
char_md.p_char_user_desc = user_desc;
char_md.char_user_desc_max_size = 5;
char_md.char_user_desk_size = 5;
We also have to give ble_gatts_add_descriptor an idea of the read/write permissions for the description. We do this with a ble_gatts_attr_md_t
ble_gatts_attr_md_t user_desc_md;
memset(&user_desc_md, 0, sizeof(user_desc_md));
BLE_GAP_CONN_MODE_SET_OPEN(&user_desc_md.read_perm);
Although I could have set whatever permissions I wanted.
Finally, this all gets put into sd_ble_gatts_descriptor_add via the attr_char_value that holds all of the data.
Finally, lets add presentation format data. We make a presentation format characteristic variable and put some values in it:
ble_gatts_char_pf_t accel_pf;
memset(&accel_pf, 0, sizeof(accel_pf));
accel_pf.format = BLE_GATT_CPF_FORMAT_UINT16;
accel_pf.exponent = 0;
accel_pf.unit = 0x2713; //code for acceleration
then add it to the characteristic metadata:
char_md.p_char_pf = &accel_pf;
With this field filled in, it will automatically be added when the characteristic is added with sd_ble_gatts_add_characteristic.
0 Meters: Inspecting The GATT Server
To check to make sure the device is working properly, I used the nrf master control panel app to connect to and interrogate the GATT server. As you can see, everything is working!
