Adding a Public Service to a RN4870 Bluetooth Low Energy module Application
Objective
This lab exercise will have you configure the Generic Attribute Profile (GATT) Heart Rate Service on the RN4870 module.
You will:
- Configure the Heart Rate Service on an RN4870 module by:
- Issuing the ASCII command to add a Service
- Issuing the ASCII command to add Characteristics to a Service
Reference Materials
- RN4870 PICtail™ Board
- Terminal Emulator
- Windows/MAC/Linux: CoolTerm
Connection Diagram
Procedure
The RN4870 PICtail is shipped with a default configuration that does not include any GATT services. This lab will walk you through the steps of adding a public service to your module. We will be using the Heart Rate Service for this lab, but the process will be the same for any other public or private services you might want to add.
Connect RN4870 PICtail to PC
Make sure the jumpers are configured as the following picture suggests and that the blue dip switch is set to 1 (APP Mode).
Verify COM Port
Open the Device Manager window by going to Start Menu > Control Panel > Hardware and Sound and then selecting Device Manager. Once open, check which COM Port has been assigned to the RN4870 PICtail. In this case, it is COM18, please note that yours will probably be different.
Start a CoolTerm Connection
Launch CoolTerm and establish a connection with the following settings. (Your COM port might be different)
Enter Command Mode
To be able to configure and control the RN4870 module we need to put it in Command Mode. In Command Mode, all Universal asynchronous receiver/transmitter (UART) data is treated as ASCII commands sent to the module's UART interface.
To enter Command Mode, issue the $ command. The module will respond with CMD>.
The next command we will issue is the + command. This toggles the Local Echo on and off. Once we have entered this command while in Command Mode, it will allow all typed characters to be echoed to the output. The module will respond with ECHO ON.
Add Default Services
Command SS sets the default services to be supported by the RN4870 in the GAP server role. Supporting services in the server role means that the host MCU must supply the values of all characteristics in supported services and provide client access to those values upon request.
The input parameter for command SS,<hex8> is an 8-bit bitmap that indicates the services to be supported as a server. To demonstrate how this command works, we will add the Transparent UART service as well as the Device Information service.
| Service | Bitmap |
|---|---|
| Transparent UART | 0x40 |
| Device Information | 0x80 |
Issue the following command SS,C0 to add both services mentioned above. The module will respond with AOK.
Change the Module's Name
Next, we will rename the module using the command SN,<text>. The module will respond with AOK.
All configuration changes made by Set commands are stored in the Non-Volatile Memory (NVM) and survive the power cycle. Any configuration changes take effect after a reboot via the R,1 command.
After the device reboots, it defaults to Data Mode. To place the module back in Command Mode, issue the $ command. Immediately after that, send the + command to turn local echo on. The module will respond with ECHO ON.
Add Heart Rate Service
All BTLE Services are built on top of the Generic Attribute Profile (GATT), where GATT defines the accessibility of Attributes called Characteristics. If you are not familiar with the way attributes are organized, please visit the GATT Data Organization and Hierarchy page.
All Service/Characteristic Configuration commands start with the letter P. The main function of those commands is to define services and their characteristics. All definitions are saved in NVM which can be restored after a power cycle. The command to add service is the PS command. If we take a look at Bluetooth's website list of services, we can see that the universally unique identifier (UUID) for the Heart Rate service is 0x180D.
In order to add the Heart Rate Service to our RN4870 module, we have to issue the following command: PS, 180D.
Add Heart Rate Service Characteristics
If you take a look at the Heart Rate Service, you will notice it is made up of three different characteristics: Heart Rate Measurement, Body Sensor Location, and Heart Rate Control Point. The command used to add characteristics to service in the RN4870 module is the PC command.
The PC command expects three parameters:
- The first one is the UUID for the public characteristic.
- The second parameter is the accessibility of each characteristic, which is defined by an 8-bit characteristic property in bitmap format as shown in the accompanying table.
| Property | Bitmap Value |
|---|---|
| Notify | 0x10 |
| Write | 0x08 |
| Read | 0x02 |
- The third parameter is an 8-bit value that indicates the maximum data size in octet where the value of the characteristic holds in the range from 1 to 20 (01 to 14 in hex format). The real data size can be smaller.
Add the Heart Rate Measurement Characteristic
The first characteristic we will add is the Heart Rate Measurement Characteristic. The screenshot below is taken from a previous version of the Heart Rate Service webpage.
- You can find the UUID for this characteristic by downloading the Assigned Numbers Document. The UUID for the Heart Rate Measurement Characteristic is 0x2A37.
- The second parameter we need is the accessibility of this characteristic. From the screenshot above we can see that the only Mandatory Property is the Notify Property. If we take a look at the table in Step 8, we can see that the bitmap value for Notify is 0x10.
- Lastly, the third parameter we need is the maximum data size. For the purposes of this lab, we chose five octets, 0x05.
Using all the information we just gathered, we are finally ready to issue the PC,0x2A37,10,05 command. The module will respond with AOK.
Add the Body Sensor Location Characteristic
We will follow the same procedure for the next two characteristics. Find the UUID, find the characteristic property, and lastly determine the maximum data size.
- The UUID for the Body Sensor Location Characteristic is 0x2A38.
- The Mandatory Property is Read, 0x02.
- Lastly, for maximum data size, we chose 5 octets again.
The command we will issue then looks like this: PC,2A38,02,05.
The module will respond with AOK.
Add the Heart Rate Control Point Characteristic
The last characteristic we will add is the Heart Rate Control Point Characteristic.
- The UUID for this characteristic is 0x2A39.
- From the screenshot below, we see that the mandatory property is Write which has an opcode of 0x08.
- We will continue using a size of five octets for the data size parameter, 0x05.
The command we need to issue then becomes PC,2A39,08,05, as you can see in the accompanying image.
The module responds with AOK.
Save Changes
In order for the changes to take effect, reboot the module using command R,1.
Verify Changes
After the reboot, you need to enter Command Mode ($) and enable Local Echo (+) as we've done before. To verify the GATT service was configured correctly, issue the LS command which lists the server services and their characteristics.
Conclusions
In this lab, you have seen how you can add a public service to the RN4870 module. The process would be the same if you were adding a private service, but instead of 16-bit SIG-established UUIDs, you would use your own 128-bit UUIDs. The Updating Server Characteristics page is a continuation of this lab and will show you how to work with all the different characteristics we added to the Heart Rate Service.