This lab exercise will have you dynamically update the GATT Heart Rate Service characteristics on the RN4870 module using the appropriate ASCII commands. Results will be monitored via a smartphone application.
In order to complete this lab, you must have added the GATT Heart Rate Service to your RN4870 module. If you haven't, follow the steps in the Adding a Public Service page.
- RN4870 PICtail
- Android Smartphone (Lab tested with BLU Advance 5.0)
- OS version 4.4 or higher
- BT 4.0 or higher hardware
- Apple Smartphone
- OS version 5 or later
- BT 4.0 or higher hardware
If you are coming over from the Adding a Public Service lab, you probably have already established a CoolTerm connection and entered Command Mode, so you can skip to Step 5 of this lab. If you already ended your CoolTerm session or exited out of the program, you will need to start with Step 1 below.
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 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.
List all Services
Issue the LS command to list the server services and their characteristics. The output format of command LS is the following:
- The first line is the primary service UUID.
- The next lines (indented) contain the following information separated by commas:
- The characteristic UUID.
- The characteristic handle.
- The characteristic property. (See table below).
- Current configuration settings for the characteristic configuration handle.
As we can see from the results of the LS command below, we have a public GATT service, the Heart Rate Service (UUID: 180D), with three characteristics identified by the following UUIDs: 2A37, 2A38, and 2A39 for the Heart Rate Measurement, Body Sensor Location, and Heart Rate Control Point characteristics respectively. Each characteristic is assigned a 16-bit handle (0072-0077). Handles are used to efficiently reference and identify characteristics in the GATT service. Note that there are two handle references for the characteristic identified by UUID 2A37.
If we take a close look at the Heart Rate Measurement characteristic, we notice that it includes a Descriptor. That descriptor is the Client Characteristic Configuration Descriptor (CCCD). From our results of the LS command, we see that we have four lines of characteristics; one of those four, specifically the second one, is the CCCD which was added by the RN4870 automatically. This means that to write a value to characteristic 2A37, handle 0072 is used, and to enable client notifications on this same characteristic, handle 0073 is used.
The characteristic configuration (fourth parameter in the third line of command LS's output, 2A37,0073,10,0) shows the notification/indication status. Value 0 means notification/indication has not yet started, 1 means notification started, and 2 means indication started.
Launch Smart Discover App
After you open the Smart Discover app on your smartphone, it will immediately scan for Bluetooth devices nearby. The name you chose for your module in the previous lab (DeveloperHelp in my case) should show up. Tap on it to connect to your RN4870 module.
On your CoolTerm window you will see the status message, %CONNECT,1,<MAC>%, returned by the RN4870 UART, indicating a connection has been established. The <MAC> address is the address of the remote device that initiated the connection.
Find the Heart Rate Service
After you connect to the RN4870 module using the Smart Discover app, you can scroll down to see all the supported services. If you remember from the previous lab, we added the Device Information Service, Transparent UART, and the Heart Rate Service. Tap on Heart Rate Service.
All the Heart Rate Service characteristics we added (along with their UUIDs) will then be listed under the Heart Rate Service. The first one we will work with is the Heart Rate Measurement characteristic. Tap on Heart Rate Measurement.
On the CoolTerm side you will notice the following message appear:
Heart Rate Measurement Characteristic
Once inside the Heart Rate Measurement characteristic, enable notifications by sliding the Enable Notify/Indicate button to ON.
When you enable the notifications, the following message will appear on the CoolTerm window.
Notifications and Indications are unsolicited updates sent from the Server to the Client. The Client must enable the notification and indication on a characteristic to receive the updates. Bluetooth specification defines the format to be 0x0000, 0x0001 or 0x0002. Value 0x0001 (01 00 over the air in little Endian) starts the notification, value 0x0002 (02 00 over the air in little Endian) starts the indication, and value 0x0000 stops both.
Issue the SHW command which writes the content of the specified characteristic in the server service to the local device by addressing its handle. This command takes two parameters. The first parameter is the 16-bit hex value of the handle which corresponds to the characteristic of the server service you wish to update. The handle for each characteristic's UUID is the second parameter you see when you issue the LS command.
The second parameter is the content to be written to the characteristic. In the following example we chose to send a value of 0x00A0 to the Heart Rate Measurement characteristic's handle which is 0x0072.
Notice that immediately after sending the command SHW,0072,00A0, the smartphone app automatically updated to show the new value, 00 A0.
Update a Different Characteristic
When you exit out of the HRM characteristic, you will see the following on your CoolTerm Terminal indicating that the notifications/indications have stopped
Select the Body Sensor Location characteristic this time.
Issue the Server Handle Write command, SHW,0075,0002, to update the Body Sensor Location characteristic whose handle is 0x0075 with the value 0x0002.
This time you will need to manually poll (Read) the characteristic value in the app by tapping the Read button. As you see in green below, the value will then be updated on the app.
Read Characteristic's Value
You can also read the value of a characteristic using the SHR command. Command SHR takes one parameter, the 16-bit hex value of the handle which corresponds to the server service characteristic. In this case we will verify the value we issued in our previous step for the Body Sensor Location characteristic.
This lab showed you the commands used to write a server characteristic value, as well as the command used to read the server characteristic's current value.