Introduction

Starting from Bluetooth SDK 2.11 (Gecko SDK Suite 2.5), it is possible to set the HFXO crystal tuning setting (CTUNE) by storing the value in the User Data page as a manufacturing token. This makes it possible to have a unique CTUNE setting for each device (instead using one single calibration value for all devices).

There are multiple ways to set the CTUNE, these are listed in UG136: Silicon Labs Bluetooth ® C Application Developer's Guide (Chapter 4). Storing the CTUNE as a manufacturing token is one of the many available options.

Changes visible to the application developer

Because of this change introduced into the SDK and the sample applications, you may see the following type of pop-up window when connecting your development kit.

The text in the pop-up is: “This device contains a factory programmed CTUNE value in it’s eeprom. Do you want to apply this as a manufacturing token?”

This pop-up means that Studio has detected a CTUNE calibration value in the EEPROM that is mounted on the radio board. The device on the radio board (e.g. a BGM11S module) cannot access the EEPROM memory directly. Therefore, to use this board-specific calibration value it needs to be written into the device internal flash memory (i.e. copied from the radio board EEPROM into the EFR32 internal flash).

If you select YES in the dialog, then the tuning value from radio board EEPROM is saved in the User Data page of the module as a manufacturing token. The startup code in the Bluetooth sample applications can then access the tuning value when setting up the internal clocks. (the relevant code is in function initMcu_clocks() )

NOTE: If your application uses the User Data page for some other purposes, then you should select NO in the pop-up dialog. Otherwise the data you have in the User Data page is erased and overwritten with the CTUNE value.

If you select NO, then the CTUNE value detected in radio board EEPROM is simply ignored. You can tick the “Do not ask again” checkbox if you do not want to see this pop-up each time you connect the kit to your PC. 

Additional details

The CTUNE calibration value is stored in User Data page at a fixed offset 0x100.

You can also write the CTUNE value into this location manually by using Simplicity Commander. Following example shows how to write CTUNE value 300 (0x012C) as a manufacturing token:

commander.exe ctune set --value 0x012C

You can also check the value of the CTUNE manufacturing token with command:

commander.exe ctune get

Sample output of the ctune get command is shown below.

Getting CTUNE values from the Device Info page, stored in EEPROM on the board, and MFG token.
DI:    Not set
Board: 345
Token: 300
DONE

The “ctune get” command tries to read the CTUNE calibration value from three different locations:

1. Device Information (DI) page – some parts have the calibration value stored in DI page (set at production, not possible to change by user)
2. Board: the second value is the one written on the EEPROM that is mounted on the radio board
3. Token: this is the value programmed into the manufacturing token (located in User Data page)

Note that there can be several CTUNE values set in different places. The logic how the actual CTUNE tuning word is selected is explained in UG136.

An alternative way to access the CTUNE manufacturing token is to use Device Configurator in Simplicity Studio, as shown in the following screenshot.

Note: This KBA has been marked as deprecated. A more updated KBA can be found here: Adding Watchdog in NCP Mode

This KBA describes how to implement the watchdog functionality on a Bluetooth NCP firmware. The watchdog is an EFR32 peripheral which allows you to detect and reset/reboot an EFR32/BGM device when it hangs and becomes unresponsive (e.g. software stalemate). The example below can be applied to the standard NCP target - Empty from the Bluetooth SDK for any EFR32/BGM device or WSTK radio board.

For more information about NCP mode refer to AN1042: Using the Silicon Labs Bluetooth® Stack in Network Co-Processor Mode and for more details on the watchdog please refer to the EFR32 Reference Manual for the specific EFR32 variant you are using.

The sample code described in this KBA was implemented on Bluetooth SDK 2.11.x but it can be used with later SDK versions. The basic objective accomplished with this sample code is to feed the watchdog timer every time the soft timer ticks. If the soft timer stops ticking, then the watchdog will expire and reset the device.

How to add the Watchdog to the NCP firmware

1. Create a new NCP target - Empty project in Simplicity Studio for the specific radio board or OPN where you want to run this example.

2. Copy em_wdog.c and em_wdog.h into the project folders platform\emlib\src and platform\emlib\inc respectively. The em_wdog.c/h files are located in the following SDK path:

C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\<sdk_version>\platform\emlib ('src' folder for *em_wdog.c* and 'inc' folder for *em_wdog.h*)

3. Add #include "em_wdog.h" to main.c

4. Configure the watchdog timer in main.c by adding the code below before gecko_init() function. This is where you can set the threshold timeout in addition to other configuration options.

WDOG_Init_TypeDef init =
{
 .enable = true,             /* Start watchdog when init done */
 .debugRun = false,          /* WDOG not counting during debug halt */
 .em2Run = true,             /* WDOG counting when in EM2 */
 .em3Run = true,             /* WDOG counting when in EM3 */
 .em4Block = false,          /* EM4 can be entered */
 .swoscBlock = false,        /* Do not block disabling LFRCO/LFXO in CMU */
 .lock = false,              /* Do not lock WDOG configuration (if locked, reset needed to unlock) */
 .clkSel = wdogClkSelULFRCO, /* Select 1kHZ ULFRCO as WDOG clock source */
 .perSel = wdogPeriod_4k,    /* Set the watchdog period to 4097 clock periods (ie ~4 seconds)*/
};
​
WDOG_Init(&init);

5. In the local_handle_event function in main.c initialize the soft timer with a suitable timeout for your application requirements (for this example we use 2 seconds) after the boot event and add a soft timer event handler to feed the watchdog.

 static uint32_t local_handle_event(struct gecko_cmd_packet *evt)
{
  bool evt_handled = false;
  switch (BGLIB_MSG_ID(evt->header)) {
​
    case gecko_evt_system_boot_id:
      //Set a soft timer for 2 seconds. If the firmware hangs, then the soft timer will stop feeding the watchdog and cause it to reset.
      gecko_cmd_hardware_set_soft_timer(32768*2,0,0);
    break;
    case gecko_evt_hardware_soft_timer_id:
      //Feed the watchdog if the firmware hangs and the soft timer stops running.
      WDOG_Feed();
    break;
    default:
    break;
}
return evt_handled; 
}

6. (Optional) To check if the device was reset due to watchdog you can use the RMU (Reset Management Unit). Check if em_rmu.c/.h are added to your project (this is part of the NCP target - empty project by default as of SDK 2.11.x), in the same folders where em_wdog.c/h files are located. If not, then copy em_rmu.c/h into the project from the same SDK path as the em_wdog.c/h files.

6.1 Add #include "em_rmu.h" to main.c

6.2 Check at the beginning of main() if the reset was caused by watchdog and any suitable actions for you application.

uint32_t resetCause = RMU_ResetCauseGet();
RMU_ResetCauseClear();
​
/* Check if the watchdog triggered the last reset */
if (resetCause & RMU_RSTCAUSE_WDOGRST)
{
  /* watchdog reset occured - add your code here */
}

Testing the Example

You can use BGTool to test the example described in this article. In the Simplicity Studio Launcher view go to "Compatible Tools", launch BGTool and connect to your target.

Assuming you have flashed an NCP firmware modified as instructed here you will start observing soft timer events coming every 2 seconds. In the BGTool command prompt you can stop the soft timer by sending the command depicted below which will cause the watchdog to reset the device after the 4 second timeout.

Introduction

Bluetooth Low Energy (BLE) defines a framework for a wide variety of communication schemes. It allows devices to discover each other, broadcast data, establish connections and many other fundamental operations.

The primary objective is to focus on the procedures defined for the following elements of the BLE stack:

• The "Generic Access Profile" (GAP): advertising, scanning and connections.
• The "Generic Attribute Profile" (GATT): primary service discovery, GATT characteristics operations, notifications and indications.
• The "Security Manager": pairing and bonding.

In order to present those procedures in a comprehensive way, a series of sequence diagrams will be used, focusing on the following items:

• BGAPI function calls.
• Messages exchanged over the air.
• Events raised by the BLE stack.

Besides, the sequence diagrams will use the terms of master and slave or server and client, depending on the context (GAP or GATT protocol).

This article does not expose the Bluetooth stack packet management nor it describes the host controller interface (HCI).

Note: Readers are welcome to make any suggestions on improvement that can be brought to that article.

We assume in this article that the necessary Bluetooth hardware is being used, that is, an EFR32 SoC or a BGM module.

1) Generic Access Profile (GAP)

For two devices A and B to establish a BLE connection, the following has to happen: one device, say A, has to advertise, and the other one, say B, has to scan for connectable devices. As a result, only the scanning device B can initiate the connection. The scanning device B is then the master and the advertising device A is the slave.

1.1) Advertising and Scanning

BLE implements a time division duplex scheme. This means that on a given frequency channel, duplex communication (i.e. sending and receiving data) is taking place on one physical link. This differs, for example, from a wired serial link, where TX and RX wires would be used respectively for transmission and reception.

As a result, a defined set of tunable timing parameters are available: advertising interval, scanning interval, scanning window. For more information, refer to the BLE core specification .

The advertiser periodically sends advertising packets to any listening device. The scanner starts listening and a "scan response" event is raised each time an advertising packets is received. The advertising packets convey some useful informations, such as the advertiser Bluetooth address for example. Those informations can eventually be used in order to establish a connection.

Two scanning methods are available: passive and active. In passive scanning, the scanner only receives advertising packets. In active scanning, the scanner sends "scan request" messages to the advertiser, containing the scanner Bluetooth address and its address type.

Note: This article does not cover the extended advertising.

1.2) Connection success

Once the scanner has collected all necessary information from an advertiser, it can connect to it. The following sequence diagram illustrates the steps taking place in order to successfully establish a connection:

It is important to note that the scanner is the one that is initiating the connection.

1.3) Connection initiation failure

A connection initiation failure can happen for two reasons: either the connection initiation is canceled or it times out. A device can cancel a pending connection immediately after creation. It is necessary for the slave to respond to the master within a given time interval. The BLE standard defines the fixed number of six connection interval as the limit within whichever host can remain silent (as in, not sending any packet). If one of the host (master or slave) remains silent for longer, the connection is then dropped.

In this example, six connection intervals passed without receiving any data channel PDU from the slave. As a result, the connection is dropped. Similarly, If the master would have failed to send data channel PDU to the slave for that same time interval, the connection would have dropped.

Note: This is different from the supervision timeout. It applies only for the connection initiation, in other words, there is at least one successful connection event where packets are exchanged between the master and slave.

1.4) Updating connection parameters

Once a BLE connection has been established, some parameter adjustments might be requested. To do so, the "Connection parameter request" procedure can be triggered by whichever host, master or slave. The procedure can be triggered at link layer level (i.e. without the application requesting it) during connection initiation. The BGAPI implements the routine gecko_cmd_le_gap_set_conn_parameters() to preset the parameter values. When the connection is initiated, it is still possible, at any point in time, to update the connection parameters via a call to the routine gecko_cmd_le_connection_set_parameters() in the application layer:

Additionally, the sequence diagram above exhibit the "GATT MTU exchange" sub procedure.

The ATT protocol defines a Maximum Transmission Unit (MTU) of 23 bytes by default. In case the two devices connected can support a bigger ATT_MTU value, the "GATT MTU exchange" procedure is triggered to set the ATT protocol MTU. This procedure shall be initiated only once during a connection initiation.

Note that the security mode and the data channel PDU payload length may vary during the connection session. For more information on general BLE security features, please refer to KBA_BT_1101: Using Bluetooth security features in Silicon Labs Bluetooth SDK.

Note: During the "Connection parameter request" procedure, the master has always the priority over parameter decision. In other words, the master has always the "last word" for parameter negotiation.

2) Generic Attribute Profile (GATT)

GATT provides a framework for all profiles defined either by the Bluetooth SIG or by the user. Bluetooth profiles are implemented using a hierarchical structure:

• Services: they consist in GATT entries grouping together attributes that are related to each other.
• Characteristics: they are data containers. A characteristic consist in a declaration (a label) and a value.
• Descriptors: placed under a characteristic, they provide additional information about the characteristic and its values.

GATT database
*--> Services
        |
        --> Characteristics (always placed under a service)
                  |
                  --> Descriptors (always placed under a characteristic)

The BLE specification refers to all the attributes within a single service as the service definition.

2.1) Primary service discovery

A primary service is the standard type of GATT service that includes relevant, standard functionality exposed by the GATT server. In other words, a service is a collection of characteristics. As a result, when a connection is established, it is necessary for the GATT client to be able to discover the available services.

The procedure iterate through all available services of the GATT database, an evt_gatt_service event is generated for each primary service discovered. Once the end of the list is reached, an evt_gatt_end_procedure is raised by the stack.

Once a client has obtained the handle range for a service, a similar procedure exist in order to retrieve a full list of the characteristics under that service.

2.2) Characteristics

As mentioned earlier, characteristics are data containers. They consist in a declaration (a label) and a value.

There are multiple types of characteristic:

• 'hex' or 'utf-8' characteristics: they consist in hex or utf-8 values maintained internally by the BLE stack.
• 'user' characteristics: user characteristics are maintained at the application level. In other words, it is the responsibility of the application to perform the appropriate actions when a Read/Write command is received.

Moreover, on a given characteristic, different types of read/write operations can be performed. We will focus here the following procedures:

• Read/Write on user characteristic.
• Long read/write on user characteristic.
• Notifications and Indications

We won't depict here the following sub-procedures:

• Read multiple characteristics
• Write without response
• Signed write without response
• Reliable writes

For more information on these procedures, please refer to the BLE core specification and KBA_BT_0304: Different characteristic value types

2.2.1) Read/Write hex and utf-8 type characteristics

The BLE stack manages the read and write operations for these characteristics. In case of the read, upon reception of the "Read request", the server's stack sends back a "Read response" containing the characteristic value as depicted below:

The following sequence diagram describes the write operation:

The "Write Response" contains only an error code indicating whether the write was successful or not.

Note that if the maximum length of the payload is reached, the read/write long characteristic is automatically used by the BLE stack.

2.2.2) Read user characteristics

The "Read Characteristic Value" procedure is implemented via the gecko_cmd_gatt_read_characteristic_value() BGAPI command. In this procedure, the characteristic length must be less or equal to the maximum payload, that is (ATT_MTU-1) bytes. In other words, the length of the characteristic has to fit in one "Read Response".

The data are sent from the server to the client via the "Read Response". Then, the client application can retrieve the data via the "evt_gatt_characteristic_value" event.

If the characteristic does not fit in one "Read Response", then the "Read Long Characteristic Value" procedure implemented via the gecko_cmd_gatt_read_characteristic_value() routine can be used. If the payload is bigger than (ATT_MTU-1), the stack will automatically pack and send the data using gecko_cmd_gatt_read_characteristic_value_from_value(). It is not the responsibility of the application to call gecko_cmd_gatt_read_characteristic_value_from_value(), instead, the application will still use the gecko_cmd_gatt_read_characteristic_value() routine. The following sequence diagram describes the "Read Long Characteristic Value" mechanism using the offset routine.

The client reads the characteristic by chunks of (ATT_MTU-1) bytes. The client stack keeps and update the byte offset used for the read request.

For more extensive description on long characteristic operations, refer to KBA_BT_0916: Working with Long Characteristic Values

2.2.3) Write user characteristics

The "Write Characteristic Value" procedure is implemented via the gecko_cmd_gatt_write_characteristic_value() BGAPI command. In this procedure, the characteristic length must be less or equal to the maximum payload, that is (ATT_MTU-3) bytes. In a similar way to the "Read Characteristic", the length of the characteristic has to fit in one "Write Request".

For longer characteristics, the same command can be used to write a characteristic in a remote GATT database. If the payload does not fit in one request, the "write long" procedure is automatically used when gecko_cmd_gatt_write_characteristic_value() is called. The value is buffered on the server side until all data are sent over. Upon reception by the server of all data, the client can issue a "write request execute" to trigger the effective write in the remote GATT database.

If the operation is successful, an evt_gatt_procedure_completed is sent by the server.

For more extensive on long characteristic operations, refer to KBA_BT_0916: Working with Long Characteristic Values

2.2.4) Notifications and Indications

Server initiated updates can be sent from the GATT server to the client without the client having to request it. This has the advantage to save both power and bandwidth. There are two types of server initiated updates: notifications and indications. In both cases, the procedure has to be enabled first on the remote GATT server using the gecko_cmd_gatt_set_characteristic_notification() beforehand.

Notifications includes the handle of the characteristic (i.e. its identifier) and the value. The client receives the notifications but does not send any acknowledgment back to the server.

The indications, on the other hand, have the same behaviour but require an explicit acknowledgment from the client in form of confirmation. In case the confirmation is not sent by the client, the server will not send further indications.

The indications uses the same attribute protocol feature than the notifications.

3) Security Manager Protocol (SMP)

The Security Manager (SM) is both a protocol and a series of security algorithms designed to provide the Bluetooth protocol stack with the ability to generate and exchange security keys, which then allow the peers to communicate securely over an encrypted link, to trust the identity of the remote device, and finally, to hide the public Bluetooth Address if required to avoid malicious peers tracking a particular device.

The Silicon Labs BGAPI implements a series of routines for each feature needed by the security manager. The security mechanisms implemented in BLE such as pairing, bonding, key exchange are described more extensively in KBA_BT_1102: Pairing Processes.

Conclusion

The BLE stack is designed to manage and abstract away the hardware and packet management from the application. The BGAPI implements BLE procedures such as GATT service discovery, characteristic read/write and so on, via function calls. On the other hand, an event driven design implemented by the BLE state machine, allows the application to monitor the status of the BLE stack and control it.