Updating Server Characteristics on the RN4870

Last modified by Microchip on 2023/11/09 09:03

Objective

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 on the "Adding a Public Service to a RN4870 Bluetooth Low Energy Module Application" page.

Back to Top


Reference Materials

Back to Top


Procedure

If you have already established a CoolTerm connection and entered Command mode; 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.

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).

Board View: Jumper settings

If hardware flow control is enabled, then RTS and CTS jumpers must be installed.

Back to Top


Verify COM Port

Open the Device Manager window by going to Start Menu > Control Panel > Hardware and Sound > 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 may probably be different.

Device Manager window showing which COM Port has been assigned to the RN4870 PICtail

Back to Top


Start a CoolTerm Connection

Launch CoolTerm and establish a connection with the following settings. (Your COM port might be different).

CoolTerm window showing COM port used and 15200 baudrate

Back to Top


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>.

CoolTerm Window showing Command Mode

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.

CoolTerm window in Command Mode showing ECHO ON

Back to Top


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 accompanying table).
    • Current configuration settings for the characteristic configuration handle:

Current configuration settings for the characteristic configuration handle:

As we can see from the results of the LS command, 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.

CoolTerm window Listing all Services

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.

Client Characteristic Configuration Descriptor (CCCD)

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 has started, and 2 means indication has started.

Back to Top


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 should show up (shown as DeveloperHelp here). Tap on it to connect to your RN4870 module.

Smart Discover App  scanning for Bluetooth devices nearby

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.

CoolTerm window indicating a connection has been established

Back to Top


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.

Smart Discover app showing Heartrate Services

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.

Smart Discover app showing Heart Rate Measurement

On the CoolTerm side, you will notice the following message appear:

CoolTerm window displaying %WC, 0073, 0000%

Back to Top


Heart Rate Measurement Characteristic

Once inside the Heart Rate Measurement characteristic, enable notifications by sliding the button next to Enable Notify/Indicate button to ON.

Slide button next to Enable Notify/Indicate button to ON

When you enable the notifications, the following message will appear on the CoolTerm window.

CoolTerm window showing message %WC, 0073, 0100%

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.

Back to Top


Update Characteristic

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.

CoolTerm window showing handles

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.

Smard Discover app sending a value of 0x00A0 to the Heart Rate Measurement characteristic's handle

Notice that immediately after sending the command SHW,0072,00A0, the smartphone app automatically updated to show the new value, 00 A0.

Smartphone app automatically updates to show the new value, 00 A0

Back to Top


Send Different Characteristic Values

Continue using the command SHW to write local Heart Rate Measurement characteristic values as a server.

Send Different Characteristic Values

Check your smartphone to make sure the characteristic value was updated.

Screenshot showing verification that the characteristic value was updated

Back to Top


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.

CoolTerm window indicating that the notifications/indications have stopped

Select the Body Sensor Location characteristic this time.

Select the Body Sensor Location characteristic

Issue the Server Handle Write command, SHW,0075,0002, to update the Body Sensor Location characteristic whose handle is 0x0075 with the value 0x0002.

Update the Body Sensor Location characteristic

This time you will need to manually poll (Read) the characteristic value in the app by tapping the Read button. As highlighted in green, the value will then be updated on the app.

Manually poll (Read) the characteristic value in the app

Back to Top


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.

CoolTerm window Command SHR

Back to Top

Conclusions

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.

Back to Top