Introduction

Bluetooth 5 introduces several enhancements to advertising. This article discusses the concept of chained advertising.

Discussion

Chained advertising allows advertising packets to be linked or chained together to allow for larger advertisements, up to 1650 bytes, to be sent. A new packet type, AUX_CHAIN_IND, is used to transmit the individual portions of these advertisements. Chained advertising works together with extended advertising and periodic advertising. The following example allows a synchronizer, i.e. the receiver of a periodic advertisement, to synchronize to a chained periodic advertisement and begin receiving these advertisements.

Implementation

Advertiser

The maximum size of a BGAPI command is 255B, which does not allow to use one command to set 1650B of advertisement data. Therefore, version 2.12 of Silicon Labs Bluetooth SDK introduces a new API: gecko_cmd_system_data_buffer_write() to write up to 255 bytes of data to the system data buffer, in which the stacks assembles the full advertisement data. This API can be called multiple times when more than 255 bytes must be written to the buffer.

The sample code provided with this article implements a simple function, writeSystemDataBuffer(), to simplify writing up to 1650 bytes to the system data buffer. Once the desired advertising data has been written to the buffer the application starts advertising. The advertisement will include a service UUID, which the synchronizer will look for, and the sync info, on which the synchronizer can sync on. Next, the periodic advertisement is started. Finally, the data assembled in the system data buffer is transferred to the periodic advertisement by calling another new API: gecko_cmd_le_gap_set_long_advertising_data().

Scanner

The scanner, or synchronizer, begins by starting scanning for advertisements containing the ‘watchable’ service with the UUID f69dd7f9-340a-4693-9e46-c8630c898558. The first step is to request the extended scan response by calling gecko_cmd_le_gap_set_discovery_extended_scan_response(), this provides more information about the scanner than the basic scan response. Next, the scanner sets the discovery timing and type and starts discovery. Advertisements or scan responses are handled by gecko_evt_le_gap_extended_scan_response_id event handler. This event handler first filters out any packets which are not extended advertising packets. Next, the advertisement is searched for the service UUID mentioned above by calling findServiceInAdvertisement(). When an advertisement containing this UUID is found, the scanner syncs to this device by calling gecko_cmd_sync_open().

The sample code for the scanner/synchronizer includes event handlers for sync_open and sync_closed events. The sync_closed event is triggered when a sync timeout expires and is used to start scanning again. The gecko_evt_sync_opened_id event is purely informative and simply prints a message indicating that a sync has been opened. The gecko_evt_sync_data_id is triggered whenever sync data is received. This event handler handles three situations:

• data received complete,

• data received with more to follow and

• data truncated.

The first situation occurs either when the advertisement fits in a single packet or when the last packet in a chain is received, in either case the data is saved. The second situation occurs when data is received, and more is expected. When this happens, event handler saves the data and begins reassembly the advertisement. If subsequent data is expected, but none is received, the status is set to data truncated. In this case, the sample application considers the data to be corrupt and discards it all by clearing it’s buffer.

Chained advertisements are buffered using the bluetooth_stack_heap found in main.c. The definition must be increased as shown below to provide sufficient space for the data.

uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)+1650];

Running the Example

The attached example requires two WSTK/radioboards.

1. Create a soc-empty project for your desired radio board.

2. Overwrite the app.c file in this project with app.c from the advertiser folder in the attached zip file.

3. Open main.c and modify the heap size uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)+1650];

4. Import gatt.xml from the advertiser folder using the ‘Import GATT’ icon in the GATT Configurator. When finished the result should look like this

5. Click generate.

6. Build and download to the first kit.

7. Create another soc-empty for the second kit.

8. Overwrite app.c in this project with app.c from the scanner folder in the attached zip file.

9. Open main.c and modify the heap size uint8_t bluetooth_stack_heap[DEFAULT_BLUETOOTH_HEAP(MAX_CONNECTIONS)+1650];

10. Open app.h and change the value of DEBUG_LEVEL from 0 to 1 to enable debug printing.

11. Build and download to the second board.

12. Open a terminal program, such as the SimplicityStudio serial console, to view the output from the device. The result should look similar to the followingShortly after starting up, the scanner discovers an advertiser that has come into range and synchronizes with it. Each gecko_evt_sync_data_id comes with a maximum of 250 bytes. The entire advertising packet contains 1650 bytes so we see the final event contains 150 bytes and displays a message indicating that the sync is complete. In the next chained advertisement, one of the advertising packet PDUs is not received, so the data is discarded. After one more successful chained advertisement, the sync is closed due to a timeout 

Conclusion

Chained advertising provides a way of distributing larger amounts of data to multiple synchronizers without the need for connections. The focus of this article is chained advertising, for more information on periodic advertising in general please see our periodic advertising knowledgebase article

 

IV Index & Sequence Number

Below is the definition of Sequence number and IV index from chapters 3.8.3 and 3.8.4 of Mesh Profile Specification v1.0.1.

Sequence Number

The sequence number, a 24-bit value contained in the sequence number field of the Network PDU, is primarily designed to protect against replay attacks. Elements within the same node may or may not share the sequence number space with each other. Having a different sequence number in each new Network PDU for every message source (identified by the unicast address contained in the SRC field) is critical for the security of the mesh network.

With a 24-bit sequence number, an element can transmit 16,777,216 messages before repeating a nonce. If an element transmits a message on average once every five seconds (representing a fairly high frequency message for known use cases), the element can transmit for 2.6 years before the nonce repeats.

Each element shall use strictly increasing sequence numbers for the Network PDUs it generates. Before the sequence number approaches the maximum value (0xFFFFFF), the element shall update the IV Index using the IV Update procedure (see Section 3.10.5). This is done to ensure that the sequence number will never wrap around.

Sequence number Storing Strategy

Sequence number should be non-volatile, software stacks should make sure that every time the device sends a valid packet, it should never use the sequence numbers which had been already used before, so it would be a good way to store it in the flash. However, writing flash once per each sequence number increment is probably too often so that the flash may easily wear out before the life time of the real product. To balance the impact, the stack will only write the sequence number to flash at a fixed interval when the sequence number increases by pstore_write_interval_elem_seq times, which is adjustable and located in the dcd.c file in your project. Given that there is a chance that the device may loss power unexpectedly before the interval, which means the real sequence number has not been written to flash, next time when the device boots, it will use the old value in the flash. To avoid the node uses any old sequence number, the node will always increase pstore_write_interval_elem_seq after reset. Besides, the stack will detect if there is valid sequence number increasing between the 2 times of reset, if no, the stack won't increase the sequence number. For more information, you can refer to the example in Figure 1.

NOTE: This is not standard but Silicon Labs' current solution and it may change in the future.

IV Index

The IV Index is a 32-bit value that is a shared network resource (i.e., all nodes in a mesh network share the same value of the IV Index and use it for all subnets they belong to).

The IV Index starts at 0x00000000 and is incremented during the IV Update procedure as described in Section 3.10.5. The timing when the value is incremented does not have to be exact, since the least significant bit is communicated within every Network PDU. Since the IV Index value is a 32-bit value, a mesh network can function approximately 5 trillion years before the IV Index will wrap.

The IV Index is shared within a network via Secure Network beacons (see Section 3.9.3). IV updates received on a subnet are processed and propagated to that subnet. The propagation happens by the device transmitting Secure Network beacons with the updated IV Index for that particular subnet. If a device on a primary subnet receives an update on the primary subnet, it shall propagate the IV update to all other subnets. If a device on a primary subnet receives an IV update on any other subnet, the update shall be ignored.

If a node is absent from a mesh network for a period of time, it can scan for Secure Network beacons (see Section 3.10.1) or use the IV Index Recovery procedure (see Section 3.10.6), and therefore set the IV Index value autonomously.

Environments

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.5.0 GA or newer, the latest version are always recommended.
• Hardware – At least 2 Bluetooth Mesh compatible boards - EFR32xG12 or EFR32xG13 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• Provisioner - Bluetooth Mesh app on smartphones, or the Host Provisioner.
• Tools – J-Link RTT viewer or serial terminal for print, if using serial terminal, the parameters are as below:
  • Baud rate: 115200
  • Data bits: 8
  • Stop bit: 1
  • Flow control: False

IV Update & Recovery Introduction

IV Update & Recovery Procedure

IV Update Procedure:

The sequence number is 24-bit length, as the example provided above, with 5 seconds cadence, the sequence number will repeat after 2.6 years. To avoid this, the node could start the IV update procedure to update the network to a new IV index so that the sequence number could be reset to 0. The IV update procedure can be initiated by any node in the primary subnet. Table 1 shows the summary of IV update procedure.

IV Recovery Procedure:

A node shall support the IV index recovery procedure because a node that is away from the network for a long time may miss IV Update procedures, in which case it can no longer communicate with the other nodes. In order to recover the IV Index, the node must listen for a Secure Network beacon, which contains the Network ID and the current IV Index.

IV Update & Recovery Limitations

There are some limitations on initiating IV update and recovery procedure, mentioned in chapters 3.10.5 and 3.10.6 of Mesh Profile Specification v1.0.1. Generally, as below:

• If a node in Normal Operation receives a Secure Network beacon with an IV index less than the last known IV Index or greater than the last known IV Index + 42, the Secure Network beacon shall be ignored. Note: This above requirement allows a node to be away from the network for 48 weeks. A node that is away from a network for longer than 48 weeks must be reprovisioned.
• A node shall not start an IV Update procedure more often when once every 192 hours.
• The transition from Normal Operation state to IV Update in Progress state must occur at least 96 hours before the sequence numbers are exhausted.
• After at least 96 hours and before 144 hours of operating in IV Update in Progress state, the node shall transition back to the IV Normal Operation state and not change the IV Index. At the point of transition, the node shall reset the sequence number to 0x000000.
• The node shall not execute more than one IV Index Recovery within a period of 192 hours.

IV Test Mode

Because the limitations mentioned above, it's not easy to test the IV update & recovery procedure. So the IV test mode removes the 96 hours limit. All other behavior of the devices remains unchanged.

Secure Network Beacon

The secure network beacon must be enabled to do the IV update & recovery since it's the carrier of the information that a node is updating the IV index.

NOTE: the Bluetooth Mesh app may not support to configure the secure network beacon state, so you may need to enable it locally with the mesh test class commands. If using the Host Provisioner, then it's not a problem since it supports that.

Running The Example

The example contains two projects - iv_update and iv_recovery, they needs to work together to show how the IV update & recovery procedure works, as well as showing the sequence number storing strategy. Let's call the node flashed with iv_update firmware node U, and the node flashed with iv_recovery firmware node R.

BGAPI Commands & Events

Below is a list of BGAPI commands and events related to the IV update & recovery procedure, all of which are demonstrated in the example.

Commands:

• gecko_cmd_mesh_node_request_ivupdate(...) - this command is used to initiate an IV update procedure.
• gecko_cmd_mesh_node_set_ivrecovery_mode(...) - this command is used for enabling/disabling the IV recovery mode, this can typically be called when the stack reports it's found that the IV of the network is different than the IV of node itself.
• gecko_cmd_mesh_test_set_iv_index(...) - this command is used to set the IV index of the node itself.
• gecko_cmd_mesh_test_set_ivupdate_state(...) - this command is used to forcedly set the iv update procedure state

Events:

• gecko_evt_mesh_node_changed_ivupdate_state_id - This event is generated whenever the node IV update state changes.
• gecko_evt_mesh_node_ivrecovery_needed_id - this event is generated whenever the stack consider the found network IV index is too far to catch up automatically, so that the application will decide if to catch up or not.

Import The Projects

1. Download the attachment and extract it, create a soc-btmesh-switch example project and a soc-btmesh-light example and specify the names, e.g. iv_update and iv_recovery.
2. Replace the main.c file of the iv_update project with the main.c in the ${extract_folder}/iv_update folder.
3. Replace the app.c file of the iv_recovery project with the app.c in the ${extract_folder}/iv_recovery folder.
4. The example uses the Logging System, if you want to use printf instead, you can comment out the #define USE_LOG_MODULE in app.c.
5. Build both projects and flash them to 2 boards respectively.
6. Use Bluetooth Mesh app on smartphones or any other kinds of provisioner to provision the 2 boards to the same network and configure them properly.

Behaviors of The Example

As you can see from the last section that the examples are based on the light and switch examples, so they still keep the basic functionalities and behaviors as the original example. What is modified is listed below:

On the Node U side - iv_update project:

• Very long press on PB0 - It will start the IV update procedure by increasing the IV index by MIN(TEST_IV_HOP, MAX_IV_HOP - 1) + 1 to demonstrate the IV index hop if the node is not in IV update state. Otherwise, it will terminate the IV update procedure if it's in IV update procedure.
• Very long press on PB1 - It will start the IV update procedure by increasing the IV index by 1 to demonstrate the typical IV update procedure if the node is not in IV update state. Otherwise, it will terminate the IV update procedure if it's in IV update procedure.
• Whenever the node sends a packet, it will print the current and remaining sequence number.

On the Node R side - iv_recovery project:

• Press on PB0 - It will disable the IV recovery mode.
• Press on PB1 - It will enable the IV recovery mode.

Test The Sequence Number Increasing

Every time the node U boots and if the node is provisioned, it will print the current and remaining sequence number. Every time any button is pressed to send a packet, the current and remaining sequence number will be printed. You can try to send some packets then reset the device to see what happens. How about if not send packets but reset the node directly? See the result in Figure 1, the pstore_write_interval_elem_seq here is 0x10000.

Figure 1. Sequence Number Increasing

1. System boots, node Sequence number is 0x30000.
2. Short press the PB0 once, the sequence number increments to 0x30001.
3. The same as step 2. After that, reset the device.
4. System boots, node sequence number is 0x40000. After that, directly reset the device without letting it send any packet.
5. System boots, node sequence number is still 0x40000.

Test IV Update & Recovery

Figure 2 shows the procedure of IV update and IV recovery, there are 2 nodes in the same network, as you can see from figure 1, on the left side, it's the print of the node which initiates IV update procedure, this is node U, on the right side, it's the print of the node which catches up the IV update, this is node R. There are 4 times of the IV update & recovery procedure, describing below:

1. From the print of node R you can see the IV recovery mode is disabled after reset. Both node U and R have IV index 158. Node U initiates the IV update from 158 to 159, which is the value of the current IV index of node R plus 1, at the same time, the IV update flag in the secure network beacon is set. So it catches up the IV update procedure automatically without application involved.
2. Manually set the IV index to 189, then starts IV update procedure. Because the current IV index of node R is 159, the IV index sent from node U is 190 which is not equal to 159 + 1, so the node R generates the event gecko_evt_mesh_node_ivrecovery_needed_id to let the application to decide if to catch up the IV update and start the IV recovery procedure. As you can see the IV recovery mode is enabled after it gets the event, so the node catches up to 190.
3. The IV index of node U is 156 and the flag in secure network beacon is not set, which means it's not in IV update procedure. The IV index of node R is 155, it generates the event gecko_evt_mesh_node_ivrecovery_needed_id to let the application to decide if to catch up the IV update and start the IV recovery procedure. The application didn't do it in this case, so the IV index didn't change after reset after a while.
4. The situation is the same as step 3, the only difference is the application enabled the IV recovery mode, so the node catches up the IV index to 156.

Figure 2. IV Update & Recovery Procedure

Introduction

Proxy protocol

The proxy protocol is designed to enable nodes to send and receive the Bluetooth Mesh network packets over a connection-oriented bearer. For example, a node could support GATT but not be able to advertise the Mesh Message AD Type. This node will establish a GATT connection with another node that supports the GATT bearer and the advertising bearer, using the Proxy protocol to forward messages between these bearers.

Roles

The proxy protocol defines two roles: the Proxy Server and the Proxy Client.

The Proxy Server is a node that supports a mesh bearer using the Proxy protocol and at least one other mesh bearer. For example, the Proxy Server can forward mesh messages between the advertising bearer and the GATT bearer.

The Proxy Client supports a mesh bearer using the Proxy protocol. For example, the Proxy Client can use the GATT bearer to send mesh messages to a node that supports the advertising bearer.

Filters

The proxy server uses a filter to decide if to forward the message to the proxy client or not. There are 2 types of filters could be used - white list or black list.

A white list filter has an associated white list, which is a list of destination addresses that are of interest for the Proxy Client. The white list filter blocks all destination addresses except those that have been added to the white list.

A black list filter has an associated black list, which is a list of destination addresses that the Proxy Client does not want to receive. The black list filter accepts all destination addresses except those that have been added to the black list.

The white list filter with an empty list is the default filter type. The Proxy Client can change the filter type as well as configure the addresses in the proxy filter.

 

Environments

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.5.0 GA or newer, the latest version are always recommended.
• Hardware – At least 3 Bluetooth Mesh compatible boards - EFR32xG12 or EFR32xG13 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• Tools – J-Link RTT viewer or serial terminal for print, if using serial terminal, the parameters are as below:
• Baud rate: 115200
• Data bits: 8
• Stop bit: 1
• Flow control: False

 

Details About The Example

The example is based on the light example which is available in the Bluetooth Mesh SDK. The light example is a proxy server which can be connected to forward Bluetooth Mesh network packets to the proxy client. With modification, the proxy client light will disable the PB-ADV bearer and rely on a proxy server to communicate with the network. For demonstration, 3 nodes are needed in the example - one light, one switch and the proxy client light. Because the PB-ADV bearer is turned off, the proxy client light node cannot receive any commands from the switch directly unless it connects to a proxy server node which is the original light node in this setup.

How It Works

Figure 1 shows how the 3 nodes network works.

 

Figure 1. Network Topology

How to Identify The Server Node

After the proxy client node being provisioned, it needs to find a proxy server to communicate with the network. For the proxy server nodes, once they are provisioned with PB-GATT bearer or explicitly enabled the proxy feature, they will start advertising with Mesh Proxy Service immediately. So there must be a way for the proxy client to identify if the advertising node is in the same network or not, is the target node or not? The advertisement sent by proxy server nodes has 2 types of payload for the client nodes to parse and decide if to connect - Network ID and node identity, both of which are encrypted. Currently, the SDK doesn't provide a way to decrypt the payload for application layer, so we probably need some other ways to identify the target server node. In the example, it provides 2 workarounds:

1. Match the network ID without decryption. You can use any Bluetooth scanner to get the proxy service advertisement payload, then record the 8 bytes encrypted network ID. For the client node, it can simply compare the scanned advertisement with the encrypted network ID.
2. Match the BD_ADDR.

NOTE, this is only the limitation for the time being, this should be deprecated when the SDK exposes the APIs for parsing the encrypted payload.

Network Configuration

You need to provision both nodes and configure them properly before you can verify the functionality. Basically, you need 2 addresses to let the node publish to and subscribe from, follow the setup in below picture.

 

Figure 2. Typical Setup

Proxy Client Node Work Flow

The work flow of the proxy client node shows in figure 3.

 

Figure 3. Work Flow

 

Running The Example

1. Download the attachment and extract it, create a soc-btmesh-light project in Simplicity Studio with a specified name.
2. Replace the app.c in your project with the app.c in the attachment.
3. The example uses the Logging System, if you want to use printf instead, you can comment out the #define USE_LOG_MODULE in app.c.
4. Flash 2 boards respectively with light and switch, then provision and configure them properly. Remember to enable the proxy feature on the light node.
5. If using the 1st workaround to identify the proxy server node, do the 6th step, if using the 2nd workaround, do the 7th step.
6. Find a Bluetooth scanner to scan for the proxy server advertisement and record the 8 bytes encrypted network ID in the payload.
7. Get the BD_ADDR of the light node which is the proxy server, e.g. using Simplicity Commander or a Bluetooth scanner etc.
8. If using 1st workaround, modify the #define USE_FAKE_NETWORK_ID 1 and fill the dummy_network_id with the value recorded in the 6th step. If using 2nd workaround, modify the #define USE_FAKE_NETWORK_ID 0 and fill the target_server_node_bd_addr with the value recorded in the 7th step. Build and flash the project to the remaining board.
9. Factory reset the board if needed, then provision and configure the node properly. After which, it will start to find the target server node and connect to it automatically. You can either check the LCD or the logging via serial/RTT to check the status. Once you see the "Proxy configured" on the LCD or "Proxy configured"/"Filter Length = " depending on what type of filter you are using on the logging, you can operate on the switch node to verify if the proxy client light will react or not. If everything goes well, you should be able to see "Req x" where x indicates the number of received requests sent from the switch, see figure 4.

 

Figure 4. LCD Status

Introduction

Bluetooth mesh is based on advertisements, meaning that under the hood the stack is scanning all the time. By default, the scan response events are not passed to the application but they are just consumed by the mesh stack and then silently discarded.

This article illustrated a way to scan BLE advertisements when the Bluetooth mesh stack is running. It uses advertising event filter which allows you to configure which type of events you want to have exposed to the application. It can be used to scan mesh nodes and possibly report the advertisements found to a master node which processes the data.

Implementation

Step1: Configure the advertising event filter by adding this in your boot event handler. For more details about the command refer the Bluetooth Mesh Software API reference manual.

gecko_cmd_mesh_node_set_adv_event_filter(0x7,0,NULL);

0x7: Enabled advertising packet type mask. This indicates the advertisement could be Connectable undirected, Scannable undirected or, Non connectable undirected advertising.

Step 2: Handle the scan response event by adding following case to the handle_gecko_event() function:

case gecko_evt_le_gap_scan_response_id:
        print_scan_resp(&(evt->data.evt_le_gap_scan_response));
        break;

Step 3: Add a function that handles the BLE scan responses, here's a sample:

static void print_scan_resp(struct gecko_msg_le_gap_scan_response_evt_t *pResp)
{
    // decoding advertising packets is done here. The list of AD types can be found
    // at: https://www.bluetooth.com/specifications/assigned-numbers/Generic-Access-Profile
​
    // example of adv data including proxy service data:020106030328180c16281800f03f4f79774c65a2
    // (UUID 0x1828)
​
    // 020106-03032818-0c16281800f03f4f79774c65a2
    const uint8 proxy_UUID[2] = {0x28, 0x18};
​
    int i = 0;
    int ad_match_found = 0;
    int ad_len;
    int ad_type;
​
    while (i < (pResp->data.len - 1))
    {
​
        ad_len  = pResp->data.data[i];
        ad_type = pResp->data.data[i+1];
​
        if (ad_type == 0x03)
        {
            // type 0x03= Complete List of 16-bit Service Class UUIDs
​
            if(memcmp(proxy_UUID, &(pResp->data.data[i+2]),2) == 0)
            {
                ad_match_found = 1;
            }
        }
​
        //jump to next AD record
        i = i + ad_len + 1;
    }
​
    if(ad_match_found)
    {
        for(i=5;i>=0;i--)
        {
            printf("%2.2x", pResp->address.addr[i]);
        }
​
        printf(", RSSI: %d\r\n", pResp->rssi);
    }
}

The above code looks through advertising data in scan response events and searches for the mesh proxy UUID 0x1828. If a proxy advertisement is found, the address of the sender and RSSI are printed to debug output.

Testing

• In Simplicity Studio, select your radio board, select the latest Bluetooth Mesh SDK and create soc-btmesh-light example project for your device.

• Copy and replace the attached file (app.c) into your project.

• Compile and flash to your radio board.

• Open serial console and observe the print statements.

• On another radio board, flash any Bluetooth mesh application consisting of the Mesh Proxy service with UUID 0x1828 and provision it.

This functionality was tested with two BGM13P22 radio boards and v1.4.3 of the Silabs Bluetooth Mesh stack.

Introduction

This article will introduce how to blacklist nodes from a Bluetooth Mesh network and the related APIs when developing with Silicon Labs Bluetooth Mesh SDK. Blacklisting nodes is an important part of the Bluetooth network management, which prevents the "trash-can-attach" risk. It utilizes the key refresh procedure to remove the nodes whose keys are compromised.

When a node is removed from the network, all remaining nodes would have their keys changed such that the removed node would not have knowledge of the new security credentials being used if that node was compromised after being disposed. This is known as the ”trash-can attack.”

There are 2 ways for Bluetooth Mesh network to remove one or more nodes from the network. The first one is via "Config Node Reset" command, the other way is via key refresh, both ways are supported by Silicon Labs Bluetooth Mesh SDK. Table 1 shows a comparison between these 2 ways.

In addition to blacklist node(s) from the network, the key refresh procedure is also capatible to refresh the application key(s), which results in blacklisting node(s) from some specific group(s) but remaining in the network. One note for refreshing the application keys, it's impossible to refresh only the application keys without refresh the bound network key.

How Key Refresh Works

If you are interested with the detailed information about how the key refresh procedure is designed and how it works, you can look into the chapter 3.10.4 of the Mesh Profile Specification 1.0.

Because the Silabs Bluetooth Mesh SDK has implemented this and packed the procedure to simple API calls, it's OK to just understand the procedure in general, it has 3 phase:

1. Receive the net key.
2. Inform the provisioner that the new key has been received.
3. Use the new key and revoke the old key.

Related APIs In Silabs Bluetooth SDK

Commands

• gecko_cmd_mesh_prov_set_key_refresh_blacklist - this is used to add a node to the blacklist list which is maintained by the stack.
• gecko_cmd_mesh_prov_set_key_refresh_appkey_blacklist - same as the above one but for refreshing appkey.
• gecko_cmd_mesh_prov_get_key_refresh_blacklist - this is used to check if a node is in the blacklist list which is maintained by the stack.
• gecko_cmd_mesh_prov_get_key_refresh_appkey_blacklist - same as the above one but for refreshing appkey.
• gecko_cmd_mesh_prov_key_refresh_start - command to start the key refresh procedure, nodes in the blacklist list will get blacklisted.

Test Class Commands

The test class commands are for developing and testing purpose, it's NOT recommended to use in the production firmware.

• gecko_cmd_mesh_test_update_local_key - this is used to update the key locally by a node.
• gecko_cmd_mesh_test_prov_prepare_key_refresh - this command will set the network key and the application key(s) if any which will be used for the next key refresh procedure.

Events

• gecko_evt_mesh_prov_key_refresh_node_update_id - there are 3 parameters carried in this event, key (network key index), phase (which phase the node has moved into) and uuid (UUID of the node). This event indicates that the node has moved to the specific phase.
• gecko_evt_mesh_prov_key_refresh_phase_update_id - this event indicates that the whole network has moved to the specific phase.
• gecko_evt_mesh_prov_key_refresh_complete_id - this event indicates that the key refresh procedure has completed.

Typical Flow

Below is a pseudo code to demonstrate to blacklist 3 nodes with UUID - uuid1, uuid2 and uuid3.

  #define BLACKLIST 1
  #define UUID_LEN  16
  #define NET_KEY_INDEX 0
  #define APP_KEY_NUM_TO_REFRESH 0
  struct gecko_msg_mesh_prov_set_key_refresh_blacklist_rsp_t *pBgRet = NULL;
  struct gecko_msg_mesh_prov_key_refresh_start_rsp_t *pKeyRefStartRet = NULL;

  pBgRet = gecko_cmd_mesh_prov_set_key_refresh_blacklist(netkey_id,
                                                         BLACKLIST,
                                                         UUID_LEN,
                                                         uuid1);
  check the result value, pBgRet->result.
  pBgRet = gecko_cmd_mesh_prov_set_key_refresh_blacklist(netkey_id,
                                                         BLACKLIST,
                                                         UUID_LEN,
                                                         uuid2);
  check the result value, pBgRet->result.
  pBgRet = gecko_cmd_mesh_prov_set_key_refresh_blacklist(netkey_id,
                                                         BLACKLIST,
                                                         UUID_LEN,
                                                         uuid3);
  check the result value, pBgRet->result.


  pKeyRefStartRet = gecko_cmd_mesh_prov_key_refresh_start(netkey_id,
                                                          NET_KEY_INDEX,
                                                          APP_KEY_NUM_TO_REFRESH,
                                                          NULL);
  check the result value, pKeyRefStartRet->result.

  while(1) {
     check the events from the stack.
    switch(evt_id) {
      case gecko_evt_mesh_prov_key_refresh_node_update_id:
        record any information carried by the event if needed.
        break;

      case gecko_evt_mesh_prov_key_refresh_phase_update_id:
        record any information carried by the event if needed.
        break;

      case gecko_evt_mesh_prov_key_refresh_complete_id:
           check the e->data.evt_mesh_prov_key_refresh_complete.result to see if success?
        record the new network key index
        break;
    }
  }

  ...

Example

The project in KBA_BT_0509: Bluetooth Mesh Host Provisioner implements the blacklisting feature, you can use it to try out blacklisting nodes from the network. If you don't have time to go through and understand the whole project, you can just poll out the stuff in blacklisting_devices.c which contains all the blacklisting related code.

A provisioner plays an important role in the Bluetooth Mesh network, which creates and manages the network by adding, configuring and removing devices into/from the network. This article will provide you a ncp host example which works with the ncp target to act as the provisioner. For more information about the ncp mode and ncp host and target, please go through KBA_BT_1602: NCP Host Implementation and Example.

Prior to this example, we have the SoC mode provisioner example introduced in KBA_BT_0501: BT Mesh embedded provisioner example, but it has some limitations

• In SoC mode, only 14 devices can be added to the same network, while in ncp mode, it supports to add up to 255 devices for now.
• Application and network configuration are fixed at the compiling time, any changes to the network require to rebuild and flash the provsioner.
• Due to the limitation of the resources on the WSTK, it has limited features.

Given the above limitations, the host provisioner was developed with below ideas in mind.

• Make it as automatic as possible so that it can be used for any automatic testing.
• Separate the application and configuration, so that it doesn't need to rebuild the application to apply any configuration changes to the network.
• Configuration file can be changed at any time, the application will reload them before issuing a command.
• Robustness improvement, every process may fail because of any reason. Retry and some recovery mechanisms are needed to make the network more robust.
• A console to receive commands from the user. Easy to add any customized command to extend the application.

Note: the SoC provisioner has the full implementation of provisioning and configuring a device into a network, which is easier to understand and more suitable for beginners.

 

Capabilities

The host provisioner supports below functionalities:

• Create network and application keys
• Provision multiple devices into a network simultaneously
• Configure multiple devices simultaneously
• Add application keys
• Bind application keys to models
• Set publication address to models
• Add subscription addresses to models
• Set default TTL value
• Set relay/friend/proxy feature on or off
• Set the network/relay transmission - count and interval
• Set Secure Network Beacon on or off
• Remove devices from a network
• Blacklist devices from a network

NOTE: Removing a node is different than blacklisting a node from the network. Removing is like to ask the node to leave the network actively - provisioner sends a command to force the node to factory reset itself, while blacklist is passively being blacklisted from the network - provisioner sends packets to the reset of the nodes to migrate to a new network key. For more information, you can go through KBA_BT_0510: Blacklisting Nodes From Bluetooth Mesh Network.

 

Configuration File

The example supports 2 configuration file format - XML or JSON. Examples of both file formats are available in the config folder of the project.

NOTE: XML is NOT PLANNED TO MAINTAIN after this article is out, it doesn't make a lot sense to maintain 2 parsers to do the same thing. The current XML related stuff can be a reference, but JSON will be used for further development.

 

Dependencies

Hardware & SDK

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.4.0 GA or newer, the latest version is always recommended.
• NCP target – At least 1 Bluetooth Mesh compatible boards - EFR32xG12, EFR32xG13 or EFR32MG21 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• NCP host - POSIX compatiable machine to run the host application. Running the application on Windows may need some porting afford, THIS HAS ONLY BEEN TESTED ON Linux and Cygwin.

Library

This project uses the open source library for parsing the XML and JSON files, by setting the symbols XML_SUP or JSON_SUP to 1 to include the corresponding parser source file to the project, as well as below library.

• libxml2 - Download and install it from xmlsoft.org or https://github.com/GNOME/libxml2. It's a XML parser and used for parsering the xml configuration files.
• json-c - Download and install it from https://github.com/json-c/json-c. It's used for parsing the JSON configuration files.

 

Architecture

 

Figure 1. Functional Diagram

The architecture of the host provisioner is as shown in figure 1. Below is a brief introduction to each module in this diagram

• Event dispenser - read events from NCP target and dispense them to all modules.
• Config generic parser - Abstract layer for parsing different types of config files, provides the configuration to all other modules.
• Main Loop - Coordinates all the other modules, has below main tasks.
  • Loads configuration via Config generic parser
  • Executes the loaded action callbacks.
  • Sends data to Config generic parser to synchronize with the configuration files if any configuration changes, e.g. any device gets provisioned.
  • Sends data to logging.
  • Reads project configuration via project config, write back on changes.
• Action Loader
  • Decides which action (adding, configuring, removing or blacklisting) to take according to the configuration passed from Config generic parser.
• Logging - Receives data from other layers and writes to the log file.
• Console - Receives user input.
• Project config - Loads the project configurations from the Project config file.
• Add/Configure/Remove/Blacklist Devices - Main loop loads the action and execute the action callbacks in these modules.

Note: 1. The dashed boxes are not implemented, it's reserved for further development. 2. JSON and XML are the only supported file format by now.

Configuration Files

The host provisioner takes 2 configuration files as input - template file and node configuration file. The template file contains the templates that could be referenced by the node, it's like a group configuration. For example, there are 100 nodes using the same configuration, all the 100 nodes can reference to the same template to avoid the same configuration duplicates for 100 times. The node configuration file includes all the configuration information to each node which will be configured later. For the configurations both present in the the node configuration file and the template file, the ones in the node configuration will be useLibraryd.

Template File

Below are the fields may present in the template file.

Node Configuration FileTemplate File

Keys

When it comes to Bluetooth Mesh, there are 3 types of key which are used and known by users - Network key, application key and device key. Network and application key can be assigned by the user application, and the device key is automatically generated.

Note: Currently, only one subnet, meaning one network key, is supported by the example.

Nodes

All the fields defined in table 1 can present in the node configuration file.

Truth table and behaviors:

 

Features

There are some features available from this example, showing as below. Be aware that the more features and  the example is, the more complex the code is.

Provision & Configure Devices Simultaneously

Silicon Labs Bluetooth Mesh SDK supports this feature, as most of the demos uses a 'single thread' way to do it (provision one -> configure one -> provision another -> ...), users maybe misled that provision/configure the next device must wait for the compete of the previous one.

To benefit from this, you need to set the 2 fields in the "Memory Configuration" in the NCP target isc file.

• Max Prov Sessions - this determines how many devices can be provisioned by the provisioner simultaneously. There is a define #define MAX_PROV_SESSIONS 4 in adding_devices.h of the host project, this value must be equal or less than the setting in the NCP target memory configuration.
• Max Foundation Client Cmds - this determines how many nodes can be configured by the provisioner simultaneously. There is a define #define MAX_CONCURRENT_CONFIG_NODES 6 in async_config_client.c of the host project, this value must be equal or less than the setting in the NCP target memory configuration.

Below is a rough time comparison of provisioning and configuring a 15-node network between using 'single thread' way and the asynchronous way. The time itself is meaningless because it heavily depends on the environment, how you configure each node, how many retries for timeouts and interval between retries etc..

• 'Single thread' way - around 6 minutes
• Asynchronous way - around 1 minute

Console

A simple console is implemented to receive commands from user. Users can add any customized command by adding an new item to CMDs array in console_callback.c and corresponding callback in the console_callbacks.c.

Action Loader

The action loader will read the node configurations and decides which action (adding, configuring, removing or blacklisting) to take. The action loader will use the truth table and the priority action to determine the next action that the main loop should handle. Note, configuring devices can happen together with adding devices or alone, but not with blacklisting/removing devices.

Secure & Insecure NCP support

The provisioner supports both secure NCP and the insecure NCP. With secure NCP, the ncp secure daemon must be running and user needs to feed the socket file path with parameter if it's encrypted to the application. With the insecure NCP, user needs to feed the UART port and baud rate.

Retry

To increase the robustness, retry has been implemented. Given that retry probably won't solve the error other than timeout and out of memory, so the current implementation will only retry on timeout and out of memory events received. For other errors, it will end the current operation immediately and record the failure status to the node configuration file. It is easy to add any error events to retry, add any specific error event to below the timeout event case in each state callback switch block.

Free Mode

When enable the free mode, the provisioner will scan for nearby unprovisioned device beacons, and create one item for each in the node configuration XML file with UUID recorded and tmpl field to be 0xFF which is used to identify if the node template is valid (not 0xFF) or not. The next time provisioner loads the XML file, it will pass all the tmpl=0xFF items and gives a warning to users to configure them. Typical procedure to configure a 2-light and 1-switch network.

• type 'set fm' to enable free mode
• open the xml file and find them in the xml file to configure the recorded items
• type 'g' to provision and configure them

Logging

If turn on the symbol DEBUG_PRINT, all the log will be written to the file log/prov.log with the format - FILE:LINE -> Real log. Log Level, it supports any levels of logging, currently 3 are used - log (highest level), message and error (lowest), with setting the log level to a specific value, the logging equals to or less than it will take affect.

Symbols in Makefile

There are some symbols in the makefile, which affect how the project is compiled. Below are the description for them.

• DBG - Possible value 1 and 0.
  • 1 - Use the parameters defined in config.h.
  • 0 - Parameters need to pass when run the application.
• DBGP - As mentioned above in section Logging
• PLVL - Print level, there are some levels (Error, Message, Log) defined in config.h, if the value is less than the defined level, the defined level print will not be out to terminal.
• JSON_SUP - 1 to support Json configuration file, 0 to disable.
• XML_SUP - 1 to support XML configuration file, 0 to disable.

It's recommended to enable all levels of print for debugging, and you may need to modify the implementation to fit your own requirements. The provided implementation is just an example.

 

Use It

The config/template.[xml|json] files in the project is an example to get started with a scenario that 5 rooms, each room has light and switch, there is a master switch to control all the lights in all rooms. The config/conf_xxx.xml files in the project are examples of the node configuration files.

Follow below steps to run it:

1. Create a ncp-empty-target example based on the board you use, build and program the board. If using a WSTK, you can flash the pre-built image directly.
2. Check if Max Prov Sessions >= MAX_PROV_SESSIONS and Max Foundation Client Cmds >= MAX_CONCURRENT_CONFIG_NODES. If you want more nodes can be configured at the same time, modify the Max Prov Sessions and Max Foundation Client Cmds and do the 1st step again.
3. Connect the NCP target and host UART interface, it uses hardware flow control by default. If you want to disable it, you should modify both sides.
4. Unzip the attachment, then build the host application, e.g. "make". NOTE: You may need to specify where the json-c or xml2 path and the corresponding header files path because we may have different settings on installation of the libraries.
5. If want to use the secure NCP, you need to run the ncp daemon which is located in ${SDK_FOLDER}//app/bluetooth/examples_ncp_host/ncp_daemon firstly.
6. Run the application, e.g. "sudo ./build/asyncprov -m u -p /dev/ttyACM0 -b 115200 -f config/conf_full.xml" if _DBG is 0, "sudo ./build/asyncprov" if _DBG is 1.
7. If everything is OK, you will soon see "Ready" on the terminal. Then you can interact with the application by typing commands.

 

Some Usage Examples:

Here are some typical operations:

• To add a node, modify both blacklist and done to "00"
• To blacklist a node from a network, modify the 4 LSB bits of blacklist to 1 - "01"
• To remote a node from a network, modify the 4 MSB bits of blacklist to 1 - "10"
• To re-add a blacklisted/removed node, after the node is blacklisted, its blacklist field should not equal to "00" and done field should be "00", modify the blacklist to "00". NOTE: Make sure the node is in unprovisioned state and sending unprovisioned beacon.
• To retry configure nodes which are failed previously, type "g" command.
• To change the configuration to a node, change the configuration in the config file, then modify the done flag of the node to 01 and type "g" command.

Below is the flow to configure a network from scratch, which contains 50 lights and 6 switches. Each 10 of the 50 nodes are assigned to room 1-5 configuration in the template, and 6 switches are assigned to room 1-5 switch and the master switch.

1. Make sure that there is no device other than the 50+6 devices is sending unprovisioned device beacons. This is based on the assumption that you don't have a way to get the UUID from a device. If you could get the UUID of devices, this step doesn't matter.
2. Run the application with a non-existing config file as the parameter, the application will create a basic node configuration file. E.g. sudo ./provisioner -m u -p /dev/ttyACM0 -b 115200 -f config/confnew.json, then the conf_new.json will be created automatically, if _DBG is set to 0, you need to specify the file name in config.h file.
3. Turn off all the lights and switches. Type "set fm [1]" to the application console so that it will start to scan for unprovisioned device beacons and record them if found.
4. Turn on the switches one by one after you see "Found an unprovisioned device, recorded it into the config file", because the application will always add the newly found device before all the nodes so you will know the real device and UUID pair. Modify the 'tmpl' fields in the node configuration file to reference them to the specific room switch template.
5. Do the same to record all the lights, because each 10 lights will have the same configuration, so each time turn on 10 lights to record. Also modify the 'tmpl' feild of each node to the specific room light template.
6. All the nodes should have been added to the node configuration file, type 'g' to start adding and configuring them. This takes time.
7. Ideally, all nodes should be added and configured properly. Press the buttons on the switches to verify. If any configuration fails, type 'g' to start reconfigure those failed nodes.
8. Then you can start to try other functionalities, e.g. removing the room 1 lights, blacklist the 2 lights from room 2, move all the lights in room 3 to room 4.

 

Figure 2. 50 lights all off

 

Figure 3. 50 lights all on

1. Introduction

This article lays out the different ways of doing device firmware updates (DFU), especially over-the-air updates (OTA), when using NCP Mode in your design. We will use the NCP-target-empty example project as the starting point. Normally the NCP empty example just acts as a bridge between the NCP host and the BLE stack running inside an EFR32 device. In these cases, OTA logic has been included in the NCP-target-empty firmware.

1.1 Adding a bootloader to example projects

When starting with software examples in Simplicity Studio, the project will not contain a bootloader by default. To get the bootloader, either flash an NCP target - Empty demo or create and flash a Gecko Bootloader example project for your part.

1.2 Creating Upgrade Images of your project

SDK examples provide scripts, which generate .gbl-files, create_bl_files.bat/.sh for Windows and Linux/Mac respectively. The images (application.gbl, full.gbl and possible secure variants) are created into output_gbl folder.

1.3 OTA Client

For methods other than the UART DFU, we will use the Blue Gecko mobile app as the OTA client to perform the upgrade. A guide to using the app can be found here.

2. Firmware Update Methods

2.1 UART DFU

This is probably the most used firmware update method in NCP-mode. A Gecko Bootloader image (.GBL file) containing the new firmware is written to target device using UART and BGAPI binary protocol. The target device needs to be programmed with the Gecko Bootloader as BGAPI UART DFU Bootloader.

The default configuration, suitable for testing with Wireless Starter Kit, is as follows:

UART Option	Default
USART	USART0
Baud rate	115200
TX pin	PA0
RX pin	PA1
HW flow control	OFF
UART enable port	PA5 (VCOM_ENABLE)

The UART DFU process follows these basic steps:

1. Boot the target device into DFU mode (dfu_reset(1)).
2. Wait for DFU boot event.
3. Send command DFU Flash Set Address to start the upgrade (set as zero, offsets are calculated automatically).
4. Send the whole Gecko Bootloader image (.GBL) using DFU flash upload.
5. After sending image, the host sends command DFU upload finish.
6. Finally, the host resets target to normal mode dfu_reset(0).

An NCP host example is provided with the SDK at <StudioPath>\<version X>\developer\sdks\gecko_sdk_suite\<version>\app\bluetooth\examples_ncp_host\uart_dfu. For more information about compiling and developing host examples, see AN1042. The host example compiles to an executable, which takes the COM port number, baud rate and full.gbl file as arguments.

 

2.1.1 Testing UART DFU

1. Create a new NCP-empty-target project for your part. Here a BGM13P22 module is used.

2. Create a new BGAPI UART DFU Bootloader project for your part.

3. Flash the <projectname>-combined.s37 file of the bootloader project to your part first.

4. Build and flash the default NCP-empty-target project to your part. At this point, you should be able to connect to your part with e.g. BGTool to verify that it's running. You should not see any advertisements by default.

5. Next, we'll add functionality to the NCP-target project, by including the following code in function local_handle_event in main.c:

// In the switch-statement 
case gecko_evt_system_boot_id: 
  {
   // Start advertising automatically at boot (just to make testing easier) 
    gecko_cmd_le_gap_start_advertising(0, le_gap_general_discoverable,le_gap_connectable_scannable); 
  } 
  break;

This will make the device start advertising with name "BLE Device" by default.

       6.Build the project again and run the create_bl_files script.

       7. Navigate to the uart-dfu host example directory mentioned above and compile the host project with e.g. mingw32-make.

       8. Copy the full.gbl image to the \exe directory, which now also contains the executable program.

       9. Run the program from using a command like utility.

     uart-dfu.exe <your port> 115200 full.gbl

     10. After the upgrade is finished, you should see "BLE Device" from, for example, Blue Gecko mobile app                  Bluetooth Browser. -Success!

 

2.2 AppLoader

The Apploader is a simple application with a minimal Bluetooth stack, that handles the upload process. The Apploader uses the API of the Gecko Bootloader to decode the GBL files and to store the application image in the flash.

For NCP projects, AppLoader should be linked in the project C/C++ Build->Settings->GNU ARM C Linker->Miscellaneous->${workspace_loc:/${ProjName}/protocol/bluetooth/lib/<partname>/GCC/binapploader.o} and copied there from the ${StudioSdkPath}/protocol/bluetooth/lib/<partname>/GCC/ SDK directory. The Silicon Labs OTA service should also be added to your GATT either via the GATT Configurator or gatt.xml file.

The standard OTA DFU sequence implemented in the AppLoader goes as follows:

1. App is running.

2. Device is reset into DFU mode. In this mode the bootloader will start the Apploader instead of the Application.

3. The Apploader advertises and waits for a Bluetooth connection.

4. The AppLoader waits for the OTA start command (ota_control characteristic).

5. The Apploader starts receiving the GBL file (using ota_data characteristic).

6. The headers of the GBL file are stored in Slot 0 to be parsed.

7. After parsing the headers, the rest of the GBL file is decoded on-the-fly, and the application is copied right to the application area, overwriting the old application.

8. The Apploader receives the OTA end command and restarts the device in normal mode.

To implement this and test it, you need to capture the write request to ota_control in local event-handling loop to get to step 2. Connection closed event needs to be handled as well.

/* Check if the user-type OTA Control Characteristic was written.
* If ota_control was written, boot the device into Device Firmware Upgrade (DFU) mode. */
// static uint8_t boot_to_dfu = 0; defined at the top
case gecko_evt_gatt_server_user_write_request_id:

  if(evt->data.evt_gatt_server_user_write_request.characteristic == gattdb_ota_control) {
      /* Set flag to enter to OTA mode */
      boot_to_dfu = 1;
      /* Send response to Write Request */
    gecko_cmd_gatt_server_send_user_write_response(evt->data.evt_gatt_server_user_write_request.connection,
                                              gattdb_ota_control,
                                              bg_err_success);
    /* Close connection to enter to DFU OTA mode */
    gecko_cmd_le_connection_close(evt->data.evt_gatt_server_user_write_request.connection);
  }
  break;

  /*-----------------------------------------------*/
  // In connection_closed event to enter OTA mode
  if (boot_to_dfu) {gecko_cmd_system_reset(2);}

This is implemented in the attached Apploader_OTA_main.c file. The procedure is also described in AN1086 section 3.6.

For testing, flash the modified NCP-empty project to your kit, make another example project for the same part, e.g. SoC-Thermometer and generate the GBL files with the script as described in the beginning sections of this article. Now you should be able to perform OTA with Blue Gecko app and see that the new example is running.

2.3 Application-level OTA

In addition to the basic UART and OTA DFU solutions discussed above, it is possible to implement the firmware update functionality completely in the user application.

The main difference here compared to AppLoader based OTA above is that there is no separate DFU mode and step 2 in the above list is not needed at all. The GBL file is uploaded to the target device under the control of the user application. In this example, the file upload is done using the Silicon Labs proprietary OTA service (as specified in AN1086), but it is possible to use a customer specific service and protocol to handle the file upload.

Some of the benefits of this approach are:

• The user application remains fully functional while the OTA image is being uploaded.
• It's possible to implement customer specific OTA service/protocol (with application level security if needed).
• EM2 deep sleep is supported during OTA upload. *
• normal BLE security features (link encryption, bonding...) can be used.

* Sleep and BLE encryption/bonding are not supported by AppLoader to reduce the flash footprint.

An obvious disadvantage of this solution is the requirement to have dedicated flash space available to be used as the download area.

To use this approach, your device needs to be programmed with a suitable Gecko bootloader. When creating the bootloader project select Internal Storage Bootloader (single image on 512kB/1MB device), depending on the size of internal flash in your device.

Gecko bootloader has a key part in the OTA update. After GBL file is uploaded, it is Gecko bootloader that takes care of parsing the GBL file and installing the new firmware. The bootloader is also needed during the OTA file upload.

Gecko bootloader has an application interface exposed through a function table in the bootloader. This means that the user application can call functions implemented in the bootloader, even though the application is running in normal mode. In other words, the bootloader API functions are called from the user application context, but the implementation is in the Gecko bootloader project. As a practical example, the user application can call function bootloader_writeStorage to write data into the download area, without even knowing where the download area is physically located.

A list of the key bootloader API calls needed to implement OTA update is found in AN1086, Chapter 4. The commands are also shown below in short.

// Bring in needed bootloader functions
#include "btl_interface.h"
#include "btl_interface_storage.h"

// Erase download slot before update started
bootloader_eraseStorageSlot(0);
// Write 0 to ota_control characteristic -> init
bootloader_init();'
// Write received bytes to download area
bootloader_writeStorage(...);
// When 3 is written to ota_control, the update ends and you verify the image
bootloader_verifyImage(0, NULL);
//  Specify slot of new image
bootloader_setImageToBootload(0);
// Reboot and perform update
bootloader_rebootAndInstall();

 

2.3.1 Implementing and testing application-level OTA

Changes made in the NCP-target-empty example:

In GATT Configurator (.isc):

• Set Device Name characteristic variable length checkbox checked and length to 10.
• Drag&Drop Silicon Labs OTA service from the left hand side list
  • change both characteristic types to user
  • ota_data to variable length and length 255
  • add write property for ota_data
• Save and Generate

New files and include paths that need to be added into the project (versus having just binapploader.o linked):

• files btl_interface.c and btl_interface_storage.c need to be added to the project so that the Gecko bootloader API can be used
  • these can be copied from <studio install>\developer\sdks\gecko_sdk_suite\vX.Y\platform\bootloader\api
• following include paths added in the C build settings
  • "${StudioSdkPath}/platform/bootloader"
  • "${StudioSdkPath}/platform/bootloader/api"

Changes in main.c:
The NCP empty example includes a skeleton for adding customized event handling code, it is the function local_handle_event. This function is called whenever an event is caught in the main loop. The default implementation is empty, it is merely a placeholder for user code.

All the changes in main.c are in the local_handle_event(), with some additional includes and definitions added just before this function definition.

To support OTA in the NCP firmware, the following event handlers are implemented:

• gecko_evt_system_boot_id
• gecko_evt_hardware_soft_timer_id
• gecko_evt_gatt_server_user_write_request_id
• gecko_evt_le_connection_closed_id

See attached example in file app_level_OTA_main.c.

 

2.3.2 How it works

The implementation follows the same idea that is described in application note AN1086. The boot event handler initializes GPIOs and checks the state of button PB0. If button is pressed at the time of reboot, then the download area is erased by calling bootloader_eraseStorageSlot(0);. The boot event also sets the device name dynamically and starts advertising automatically so that OTA can be tested without any NCP host at all.

Soft timer is only used for LED blinking. A soft timer is started if the download area is erased. The soft timer handler will then simply toggle the LED pin state.

The user write request event handler is where most of the OTA work is done. Note that the type of ota_data characteristic was changed to type user in GATT configurator. Writes to ota_control characteristic will start and terminate the OTA update. Only control values 0 and 3 need to be handled, no other control values are supported by this example.

When OTA image data is received (write to ota_data), the event handler writes the data directly to the internal flash memory using Gecko bootloader API (bootloader_writeStorage).

When client writes the value 3 to ota_control indicating that all the data has been sent, the application verifies the received GBL file by calling bootloader_verifyImage. GBL file includes checksum which makes it possible to check if the file was corrupted.

After successful GBL image upload, the disconnect event triggers the actual firmware update. If the verification was successful, the new GBL image is installed by calling:

• bootloader_setImageToBootload(0);
• bootloader_rebootAndInstall();

If the image verification failed, the application does not try to install or reboot. Instead, it restarts advertising and includes the error code from the verify function in the device name.

To test the verify feature, you can try OTA update with a corrupted file. The file truncated.gbl is a GBL file from the project that has been intentionally modified so that it does not pass the check (some data has been cut from the end of the file). If you try OTA update with this file, the expected result is that the application will not change and it will restart advertising with name “err XXXX”. You can then erase the download area and try again with a valid GBL file.

 

2.3.3 How to test it

Preparations:

• Build and flash the bootloader built with default settings (*combined.s37).
• Flash the application image (*.hex).
• Copy the provided GBL files to your phone.

First, verify the device starts advertising with name “NCP APP 1”. You can also use BGTool to test that the device is responding to BGAPI commands.

To test OTA, you need to manually erase the download area. To do this, keep PB0 pressed and reset the kit. LED1 turns on and after a short delay it starts blinking. The delay is because of the flash erase (~256kB area) which takes time to complete.

The device should now advertise with name “NCP APP 1*”.

Now you can run OTA using the Blue Gecko app. OTA is performed using one single file (fullv1.gbl). In the OTA options, use the partial update which asks you to specify only one GBL file. Select file fullv2.gbl to change the application from version 1 to version 2.

After the OTA upload is complete, you press END button on the mobile app. At this point, the connection is closed and the NCP firmware completes the firmware update. Gecko bootloader is used to install the new image from the download slot.

Installation of the new image takes about 8 seconds and then the device reboots with new firmware installed. At this point, you should see it advertising with a different name “NCP APP 2”.

You can repeat the process and do another update to the original version by using file fullv1.gbl.

Remember that you need to erase the download area before each OTA update.

2.4 Bluetooth in-place OTA DFU

The download area must not overlap with the user application and therefore the above DFU solution is not applicable to devices or modules based on the EFR32xG1, as they have smaller flash size (256 kB). For EFR32xG1, the Bluetooth in-place OTA DFU Bootloader configuration is used as a default. In this configuration, the upper half of the main flash, normally used to hold the Bluetooth application, is repurposed as a storage area while a Bluetooth stack upgrade is downloaded. The flash layout is illustrated in Fig. 3.1. in AN1086 Section 3.2. For these parts, you can follow the same workflow as described in the Apploader section, but make sure to flash the Bluetooth in-place OTA DFU Bootloader example project (or demo) first.

3. Further reading

• AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications
• UG266: Silicon Labs Gecko Bootloader User’s Guide - for more about bootloading in general.
• AN1042: Using the Silicon Labs Bluetooth Stack in Network Co-Processor Mode
• Using Blue Gecko App OTA article - mobile app OTA guide.

MIDI basics

This article shows how a Blue Gecko can be used as a MIDI controller over Bluetooth Low Energy. At first we give some basic info about the MIDI standard then on the Apple Bluetooth Low Energy MIDI Specification. Finally, we highlight and explain the most important code snippets from the attached sample application which implements a very basic MIDI controller.

The protocol

MIDI is an industry standard music technology protocol that connects products from many different companies including digital musical instruments, computers, tablets and smartphones. MIDI is used everyday around the world by musicians, DJs, producers, educators, artists and hobbyists to create, perform, learn and share music and artistic works. Nearly every hit album, film score, TV show and theatrical production uses MIDI to connect and create. MIDI information is transmitted in "MIDI messages", which can be thought of as instructions which tell a music synthesizer how to play a piece of music. The synthesizer receiving the MIDI data must generate the actual sounds.

Physical layer

The MIDI specification for the electrical interface is based on a fully isolated current loop. The MIDI OUT port nominally sources a +5 volt source through a 220 ohm resistor out through pin 4 on the MIDI OUT DIN connector, in on pin 4 of the receiving device's MIDI IN DIN connector, through a 220 ohm protection resistor and the LED of an optoisolator. The current then returns via pin 5 on the MIDI IN port to the originating device's MIDI OUT port pin 5, again with a 220 ohm resistor in the path, giving a nominal current of about 5 milliamperes. Despite the cable's appearance, there is no conductive path between the two MIDI devices, only an optically isolated one. The data rate on this system is a relatively slow (by today standards) 31,250 bits per second, logic 0 being current ON. The MIDI data stream is a unidirectional asynchronous bit stream with 10 bits transmitted per byte (a start bit, 8 data bits, and one stop bit). The MIDI data stream is usually originated by a MIDI controller, such as a musical instrument keyboard.

MIDI controller and sound module

A MIDI controller is a device which is played as an instrument, and it translates the performance into a MIDI data stream in real time (as it is played). The MIDI data output from a MIDI controller is transmitted via the devices' MIDI OUT connector. The recipient of this MIDI data stream is commonly a MIDI sound generator or sound module, which will receive MIDI messages at its MIDI IN connector, and respond to these messages by playing sounds.

MIDI messages

There are a number of different types of MIDI messages. See the https://www.midi.org for details.

In the example code attached we implemented only Note On and Note Off messages. The Note On message is used for turning on MIDI notes. This is typically sent when a key pressed on keyboard. The Note Off message is used for turning off MIDI notes. This is typically sent when a key released on keyboard.

MIDI over BLE

There are number of solutions where the standard DIN connector and physical layer changed to a more modern medium like USB or Ethernet. Apple defined a custom BLE service for MIDI support. This is now part of the MIDI standard.

This specification can be found here:

https://www.midi.org/specifications/item/bluetooth-le-midi

To support MIDI over BLE the accessory has to fulfill a set requirements collected below.

Connection interval

The accessory shall request a connection interval of 15 ms or less. Apple recommends starting with a request for a connection interval of 11.25 ms and going to 15 ms if the connection request is rejected by the Apple product. Intervals higher than 15 ms are unsuitable for live playback situations.

MTU negotiation

The accessory shall support MTU negotiation. See the MTU Size section in the Bluetooth Low Energy chapter of the Bluetooth Accessory Design Guidelines for Apple Products for implementation details.

Multiple packet transmissions

The accessory shall support sending and receiving the maximum number of Bluetooth Low Energy packets that can fit into the connection interval. MIDI minimum bandwidth requirements may not be met otherwise.

Custom MIDI Service and Characteristic

The GATT should contain the following service and characteristic

Name	UUID
MIDI Service	03B80E5A-EDE8-4B33-A751-6CE34EC4C700
MIDI I/O Characteristic	7772E5DB-3868-4112-A1A9-F2669D106BF3

The MIDI I/O characteristics

Name	Type	Security	Properties	Comment
MIDI I/O	blob	Read, Write, Notify	Pairing required	Shall require encryption. Writes must not expect a response.

Header and Timestamp fields

Additional Header and Timestamp fields has to be added before the standard MIDI message format

• Header bit 7 is start bit and set to 1
• Header bit 6 is reserved and set to 0
• Header bits 0-5 are upper 6 bits of 13 bit timestamp
• Timestamp bit 7 is start bit and set to 1

Note that the actual timestamp value is splitted between the Header and Timestamp fields.

The 13-bit timestamp for a MIDI event in any given Bluetooth Low Energy packet is formed from the bottom 6 bits of the Header field and the bottom 7 bits of the Timestamp filed. Timestamps are in expressed in milliseconds, implying that the maximum timestamp range is 8192 ms. Timestamps shall be sent in monotonically increasing order.

Example application

The attached application act as a very basic MIDI controller. It can send MIDI note on and MIDI note off messages when a button pressed or released on the WSTK. Pressing PB0 button repeatedly will play the Imperial March from Star Wars. Pressing PB1 is resetting the sequence so the melody can start from the beginning.

The application is built upon the Simplicity Studio Bluetooth SDK ver. 2.11 and tested with the BGM13S Starter Kit (SLWSTK4305A) but it should work with other EFR32 based Bluetooth enabled targets with minimal changes.

We going to highlight the most important steps which are needed for building a MIDI over BLE compatible device.

GATT definition

The GATT.xml file has to contain the MIDI service definition as it is showed below.

  <!--MIDI Service-->
  <service advertise="true" name="MIDI Service" requirement="mandatory" sourceId="custom.type" type="primary" uuid="03B80E5A-EDE8-4B33-A751-6CE34EC4C700">
    <informativeText>Custom service</informativeText>
    <!--MIDI I/O Characteristic-->
    <characteristic id="xgatt_midi" name="MIDI I/O Characteristic" sourceId="custom.type" uuid="7772E5DB-3868-4112-A1A9-F2669D106BF3">
      <informativeText>Custom characteristic</informativeText>
      <value length="20" type="hex" variable_length="true">0x20</value>
      <properties encrypted_read="true" encrypted_read_requirement="optional" encrypted_write="true" encrypted_write_requirement="optional" notify="true" notify_requirement="optional" read="true" read_requirement="optional" write_no_response="true" write_no_response_requirement="optional"/>
    </characteristic>
  </service>

Enable the bonding before connection

void midi_init_ble_connection(void)
{
    gecko_cmd_sm_set_bondable_mode(1);
}

Set the connection interval to the required 15 ms.

void midi_ble_connected(uint8_t connection)
{
    /* store the connection ID */
    connectionId = connection;
    /* connection parameter constrains for ble MIDI */
    gecko_cmd_le_connection_set_timing_parameters(connection, 0x12, 0x12, 0, 0x64, 0, 0xFFFF);
}

Setup CRYOTIMER for creating 1ms timer for the timestamp

This timestamp has to be included to the MIDI message.

void midi_init_timer(void)
{
    CRYOTIMER_Init_TypeDef cryoInit = CRYOTIMER_INIT_DEFAULT;

    /* General settings */
    cryoInit.enable    = 1;
    cryoInit.debugRun  = 0;
    cryoInit.em4Wakeup = 0;

    /* Clocking settings */
    /* With a frequency of 1000Hz on ULFRCO, this will result in a 1.00 ms timeout */
    cryoInit.osc    = cryotimerOscULFRCO;
    cryoInit.presc  = cryotimerPresc_1;
    cryoInit.period = cryotimerPeriod_1;
    CRYOTIMER_Init(&cryoInit);
}

Setup GPIO interrupt for button press

Here is the PBB0_pressed function registered as a GPIO interrupt service routine and will be triggered for both rising and falling edges. The function is reading the GPIO state and sends a note on or note off message accordingly. The code snippet below shows the recommended way for registering the ISR.

void midi_init_buttons(void)
{
    /* Init GPIO ISR dispatcher */
    CMU_ClockEnable(cmuClock_GPIO, true);
    GPIOINT_Init();

    /* Setup PB0 */
    /* GPIO init for button pins */
    GPIO_PinModeSet(BSP_BUTTON0_PORT, BSP_BUTTON0_PIN, gpioModeInput, 0);

    /* Register GPIO ISR */
    GPIOINT_CallbackRegister(BSP_BUTTON0_PIN, PB0_pressed);

    /* Trigger for both edge */
    GPIO_IntConfig(BSP_BUTTON0_PORT, BSP_BUTTON0_PIN, true, true, true);
...

Function to send a note on message

The midi_note_on() function prepare and send a note on message. First the function gets the timestamp from the CRYOTIMER. The CRYTIMER provides a 32 bit counter but according to the specification we need only the lower 13 bit, so the rest of the bits are masked. Then the function fills the header and timestamp fields. The header byte is 0b10xxxxxx where xxxxxxx is top 6 bits of timestamp. The timestamp byte is 0b1xxxxxxx where xxxxxxx is lower 7 bits of timestamp.

The status byte is 0x90 is 0b1sssnnnn where sss is message type and nnnn is the MIDI channel.

The last two bytes contains the 2 byte long event field in this case it is the note and velocity.

Finally the function sends the message with the gecko_cmd_GATT_server_send_characteristic_notification API function.

void midi_note_on(uint8 note, uint8 velocity)
{
  static midi_data_t note_on;

  /* Get the timestamp from the CRYOTIMER */
  uint32 temp = CRYOTIMER_CounterGet();
  /* Mask it - only the lower 13 bit needed */
  temp = temp & 0x00001fff;
  /* Header byte = 0b10xxxxxx where xxxxxxx is top 6 bits of timestamp */
  note_on.midi_event.header = 0x80 | (temp >> 7);
  /* Timestamp byte = 0b1xxxxxxx where xxxxxxx is lower 7 bits of timestamp */
  note_on.midi_event.timestamp = 0x80 | (temp & 0x003f);
  /* Status byte = 0b1sssnnnn where sss is message type and nnnn is channel */
  note_on.midi_event.status = 0x90;
  /* setting the note parameter */
  note_on.midi_event.note = note;
  /* setting the velocity parameter */
  note_on.midi_event.velocity = velocity;
  /* sending the assembled MIDI message */
  gecko_cmd_GATT_server_send_characteristic_notification(connectionId, GATTdb_xGATT_MIDI, 5, (uint8 const *) &note_on);
}

Testing

Once the application flashed to kit it starts advertise itself. After connection it pairs and bonds with just work method. The application tested with the following IOS apps:

• Korg Module
• Korg Gadget
• Apple GarageBand

References

[1] https://www.midi.org

[2] https://www.midi.org/specifications/item/bluetooth-le-midi

[3] https://en.wikipedia.org/wiki/MIDI

Introduction

The EFR32xG13 devices (revision D or newer) include an internal oscillator, the PLFRCO, or Precision Low Frequency RC Oscillator, which is a self-calibrating RC oscillator that eliminates the need for a 32.768kHz crystal.

The PLFRCO can be used by the Bluetooth stack as the low frequency clock source (instead of the LFXO) that is used by the system to wake-up the device on each connection interval when sleep is enabled in the stack.

The PLFRCO has a frequency accuracy of +/-500 ppm which is within the Bluetooth specification requirements.

It is best suited for some BLE use cases such as applications with very constrained cost targets or board layout space, devices that maintain short connection intervals or have infrequent BLE connections as well as devices that advertise most of the time (such as iBeacon or Google Eddystone devices).

Selecting the PLFRCO

Using the PLFRCO requires only a few changes in init_mcu.c and one change in the Bluetooth stack configuration structure.

In the Bluetooth stack configuration structure the sleep clock accuracy needs to be changed to 500 ppm.

static gecko_configuration_t config = {
    ...
    ...
    .bluetooth.sleep_clock_accuracy = 500, // ppm
    ...
    ...
};

In init_mcu.c it is required to initialize the PLFRCO and select it as a clock source for the low frequency clock branches. There’s essentially 2 steps to take:

• Remove the LFXO related initialization code
• Uncomment PLFRCO related code to change clock sources LFA, LFB, LFE and init oscillator

// UNCOMMENT THIS >>

//To use PLFRCO please remove commenting of these lines
//and comment out or delete the LFXO lines if they are present
//If using PLFRCO update gecko_configuration_t config's
//.bluetooth.sleep_clock_accuracy to 500 (ppm)
//  #if defined(PLFRCO_PRESENT)
//    /* Ensure LE modules are accessible */
//    CMU_ClockEnable(cmuClock_CORELE, true);
//    /* Enable PLFRCO as LFECLK in CMU (will also enable oscillator if not enabled) */
//    CMU_ClockSelectSet(cmuClock_LFA, cmuSelect_PLFRCO);
//    CMU_ClockSelectSet(cmuClock_LFB, cmuSelect_PLFRCO);
//    CMU_ClockSelectSet(cmuClock_LFE, cmuSelect_PLFRCO);
//  #endif

// DELETE OR UNCOMMENT THIS >>

// Initialize LFXO
CMU_LFXOInit_TypeDef lfxoInit = BSP_CLK_LFXO_INIT;
lfxoInit.ctune = BSP_CLK_LFXO_CTUNE;
CMU_LFXOInit(&lfxoInit);
// Set system LFXO frequency
SystemLFXOClockSet(BSP_CLK_LFXO_FREQ);

// Set LFXO if selected as LFCLK
CMU_ClockSelectSet(cmuClock_LFA, cmuSelect_LFXO);
CMU_ClockSelectSet(cmuClock_LFB, cmuSelect_LFXO);
CMU_ClockSelectSet(cmuClock_LFE, cmuSelect_LFXO);

Tradeoffs

The most obvious benefit of using the PLFRCO instead of the LFXO is the cost savings from not using the low frequency crystal. The drawback is that the PLFRCO increases the sleep current by up to 500 nA and extends the RX receive window on the slave side at the beginning of each connection interval.

Sleep Current

Below are sleep current measurements on the same device with LFXO and PLFRCO where the sleep current difference is about 280 nA.

Figure 1. EFR32xG13 sleep current with LFXO

Figure 2. EFR32xG13 sleep current with PLFRCO

 

RX Period Extension

At the beginning of each connection interval the master device is the first to send out a packet. This makes it a hard requirement that the slave must be listening (in RX) in order not to lose that initial packet from the master device. The combined clock accuracy from master and slave (sum of both accuracy values in ppm) is used to calculate when the slave should wake-up to listen for the incoming packet.

When the accuracy is lower, the slave must wake-up earlier, so there will be a longer RX receive window when using a PLFRCO compared to the LFXO due to the lower accuracy. The images below show an empty packet taken from the slave side with 1 second connection interval and 0 dBm output power. When using PLFRCO the RX receive window is extended by ~250 µs. The longer the connection intervals the more pronounced will be the RX window extension when compared to LFXO usage.

Figure 3. Empty packet using LFXO

Figure 4. Empty packet using PLFRCO

 

One final note, when the slave misses connection intervals (e.g. device was temporarily out of range or due to interference) then the RX receive window will be widened by the combined accuracy until the slave is able to catch the initial packet from the master. Let's consider a combined accuracy of +/-600 ppm. If the connection interval is 1 s and the slave misses a connection interval, the next interval's RX receive window will be widened by 600 µs = 600 parts of 1 million micro-seconds.

This example duplicates the functionalities of the SDK example - soc-btmesh-switch with NCP mode, instead of controlling the light by the push buttons on the WSTK, it implements a lightweight console, so that you can use the CLI to control the lights in the network. For more information about the ncp mode and ncp host and target, please go through KBA_BT_1602: NCP Host Implementation and Example.

Hardware & SDK Requirements

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.4.0 GA or newer, the latest version is always recommended.
• NCP target – At least 1 Bluetooth Mesh compatible boards - EFR32xG12, EFR32xG13 or EFR32xG21 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• NCP host - POSIX compatible machine to run the host application. Running the application on Windows needs some porting afford, this has only been tested with Linux and Cygwin.

How to Use It

The NCP mode requires both the host and target to work.

Supported Commands

A simple console is implemented to receive commands from user. Users can add any customized command by adding an new item to CMDs array in app.c.

Command	Usage	Description
l	l [1/0]	Set light on[1] or off[0]
ln	ln [0-100]	Set lightness [0% - 100%]
ct	ct [0-100]	Set Color Temperature [0% - 100%]
fr	fr [1/0]	1 - Factory Reset, 0 - normal reset
h	h	Print usage
exit	exit	Exit program

Generate NCP target

1. Create "NCP - Mesh Empty Target" project based on the attached board and the latest Bluetooth Mesh SDK.
2. Open the ${projectname}.isc file, add "Light Lightness Client", "Generic Power OnOff Client" and "Light CTL Client" models to the Bluetooth SIG Models section. It's recommended to delete "Configuration Client" and "Generic OnOff Server" models from it. Modify the _Features Bitmask to 0x000b, then click "Generate" button.
3. If the NCP target needs to sleep, you need to make step 4-5 changes to the project. The provided example DOESN'T enable the sleep mode.
4. Add below code right before while(1) in main.c:

#if defined(_SILICON_LABS_32B_SERIES_1_CONFIG_3)
  /* xG13 devices have two RTCCs, one for the stack and another for the application.
     * The clock for RTCC needs to be enabled in application code. In xG12 RTCC init
     * is handled by the stack */
  CMU_ClockEnable(cmuClock_RTCC, true);
#endif

1. Open the hal-config.h file and define the symbol NCP_DEEP_SLEEP_ENABLED. After that, you need to specify the wake up pin location to the symbols NCP_WAKEUP_PORT, NCP_WAKEUP_PIN and NCP_WAKEUP_POLARITY. The same rule applies to the symbol NCP_HOST_WAKEUP_ENABLED if you want the NCP target could wakeup the host.
2. Erase the attached board, then build and program to it.

Run the example

• Download the attachment and extract it.
• cd to the foler and run "make SDK_DIR=xxx", where xxx is the real directory of your BT Mesh SDK. Assuming it builds without errors.
• The executable takes 2 parameters - serial port and baud rate. Run it as "sudo ./exe/switch /dev/ttyACM2 115200"
• If the shell starts normally, type "h" to get usage example
• Find a provisioner and light node to test it.