This article describes:

• Advertising Sets
• Advertising Sets Used by Bluetooth Mesh stack
• Adding Customized Advertising Sets to Bluetooth Mesh Applications

Advertising Sets

Advertising Sets are defined in Section 4.4.2.10, Part B, Vol 6, Bluetooth Specification Version 5.2. With advertising sets supported, Bluetooth stack actually provides a way to interleave multiple advertising events. Each advertising set has its own parameters, payload, timing etc. and is independed to the other advertising sets. For example, if you want to send a connectable advertisement and a non-connectable beacon simultaneously, you don't necessarily need to send the connectable advertisement once then modify the content and parameters to send the non-connectable beacon repeatedly, this will easy to achieve by using 2 advertising sets.

Advertising Sets Used by Bluetooth Mesh Stack

When the Bluetooth stack initializes, user application needs to configure the number of the maximum advertising sets used by both the stack and application. Other than the regular BLE examples, which typically don't use any advertising set, the Bluetooth Mesh stack uses some advertising sets to send data. You can find below inline description of the advertising sets used by Bluetooth Mesh stack in the main.c file of all Bluetooth Mesh examples.

/// Bluetooth advertisement set configuration
///
/// At minimum the following is required:
/// * One advertisement set for Bluetooth LE stack (handle number 0)
/// * One advertisement set for Mesh data (handle number 1)
/// * One advertisement set for Mesh unprovisioned beacons (handle number 2)
/// * One advertisement set for Mesh unprovisioned URI (handle number 3)
/// * N advertisement sets for Mesh GATT service advertisements
/// (one for each network key, handle numbers 4 .. N+3)
///
#define MAX_ADVERTISERS (4 + MESH_CFG_MAX_NETKEYS)

Here is a more verbose explanation for each set:

Advertising Set 0 - Reserved for Application

This advertising set is reserved for regular BLE advertising. It's created when the stack initializes by default and ready to be used by the application. For example, you can call the API gecko_cmd_le_gap_start_advertising with handle 0 to start advertising with this advertising set. This is NOT used by the Bluetooth Mesh stack, but has to be counted into the maximum number of the advertising sets.

Advertising Set 1 - Bluetooth Mesh Data

This advertising set is used for Bluetooth Mesh data traffic, which is the traffic happens on the Advertising bearer (section 3.3.1 of Mesh Profile v1.0.1) and PB-ADV (section 5.2.1 of Mesh Profile v1.0.1) . The stack is in control of the advertising data and the advertising parameters for this set, and the user application MUST NOT override the parameters or use this set for any other purpose.

Advertising Set 2 - Bluetooth Mesh Unprovisioned Device Beacon Without URI

This advertising set is used for sending the Unprovisioned Device Beacon (section 3.9.2 of Mesh Profile v1.0.1) when devices are in unprovisioned state. The Bluetooth Mesh stack will construct the advertising payload according to the definition of the Unprovisioned Device beacon format. User application shall not modify the advertising payload to this advertising set. What the user application can control in this case is the cadence for sending the Unprovisioned Device beacon, call the API - gecko_cmd_le_gap_set_advertise_timing with handle 2 BEFORE starting the Unprovisioned Device beacon.

Advertising Set 3 - Bluetooth Mesh Unprovisioned Device Beacon With URI

This advertising set is also used for sending the Unprovisioned Device Beacon (section 3.9.2 of Mesh Profile v1.0.1) when devices are in unprovisioned state. The only difference is there are 4-byte of URI hash appended to the data payload. See below lines from the Mesh Profile.

Along with the Unprovisioned Device beacon, the device may also advertise a separate non-connectable advertising packet with a Uniform Resource Identifier (URI) data type (as defined in [7]) that points to outof-band (OOB) information such as a public key. To allow the association of the advertised URI with the Unprovisioned Device beacon, the beacon may contain an optional 4-octet URI Hash field.

The latest Bluetooth Mesh stack doesn't support sending Unprovisioned Device beacon with URI, so this is reserved for future use.

Advertising Set 4 to N - Bluetooth Mesh Proxy Service Advertising

The usage of this advertising set is device state dependent.

If a device is in unprovisioned state, this advertising set will be used to advertise the Mesh Provisioning Service (section 7.1 of Mesh Profile v1.0.1) if the application call gecko_cmd_mesh_node_start_unprov_beaconing with PB-GATT bit set in the bearer parameter.

If a device is in provisioned state and supports Proxy feature, it shall start advertising the Mesh Proxy Service (section 7.2 of Mesh Profile v1.0.1) if the given situations are met. Alternatively, user application can start the advertising munally whenever the device is expected to connect to a proxy client.

Because a provisioned device could belong to multiple subnets, it could advertise multiple Mesh Proxy Service advertisements simultaneously. The maximum network key number that the device supports decides the maximum number of subnets the device can be in, so N is calculated to be 4 + the maximum network key on the device.

Adding Customized Advertising Sets to Bluetooth Mesh Applications

This example shows how to add your custom BLE advertising into a Bluetooth Mesh project.

Step 1: Increase the MAX_ADVERTISERS macro by the number of your custom advertising sets.

The .bluetooth.max_advertisers parameter in the gecko_configuration_t structure decides the maximum number of the advertising sets in the application. In all examples of the Bluetooth Mesh SDK, this value is feed by MAX_ADVERTISERS macro. So, modify the MAX_ADVERTISERS macro like below to add your own advertising sets.

/* Number of custom Advertising Sets */
#define MY_ADVERTISERS 2
#define MAX_ADVERTISERS (4 + MESH_CFG_MAX_NETKEYS + MY_ADVERTISERS)
/*
 * Advertising Set ID from the offset. E.g. to get the first custom advertising
 * set ID, put n as 1 like this - MY_ADVERTISING_SET_ID(1)
 */
#define MY_ADVERTISING_SET_ID(n)    (4 + MESH_CFG_MAX_NETKEYS + n)

Step 2: Configure the advertising sets if needed.

You can use the advertising configuration related APIs (gecko_cmd_le_gap_set_advertise_xxx) to configure the advertising sets specifically by the advertising set ID (handle), as well as the gecko_cmd_le_gap_bt5_set_adv_data to set the advertising payload. For more details about the advertising parameters and data payload format, you can check Bluetooth Advertising Data Basics. For constructing the advertising data in a much easier way, you can use the code example - Advertisement or Scan Response Constructor.

Step 3: Start the advertising sets

This is the final step to send your own advertisement, call gecko_cmd_le_gap_start_advertising with advertising set ID (handle) specified to start advertising the specific advertisement.

There is basically no difference compared to regular (non-mesh) BLE case. The key thing to take into account here is configuring the number of advertising sets and selecting the right advertising handle to use.

Introduction

This self provisioning and configuration example provides a function to provision and configure the device itself. This example doesn't perform the provisioning procedure and instead writes provisioning data directly into the persistent storage and configures the models on the device.

The goal of this example is to provide the function for the users who want to run their devices directly in a Bluetooth Mesh network without using a provisioner. This example is mainly used for development and testing purposes and is not recommended to run on final products.

This article describes how to integrate the example into a Bluetooth Mesh project, how to configure the function and how the self provisioning and configuration work.

Project integration

This article assumes app.c is the file that will call the self provisioning function. In your project, you may make the function be called in some conditions, e.g. when a button is held down for seconds. The example uses the DCD configuration from your project so the auto-generated files dcd.c and mesh_app_memory_config.h should exist in your project folder.

The code example consists of two source files: selfprov.c and selfprov.h. Copy the two files to your Bluetooth Mesh project and make the following changes.

1. Add gecko_bgapi_class_mesh_test_init(); to the class initialization function gecko_bgapi_classes_init() in app.c.

2. Add #include "selfprov.h" in app.c.

3. Add the function call self_provisioning(); in app.c at a point after the node has been initialized. For example, in the event handler of the gecko_evt_mesh_node_initialized_id event.

The example performs self provisioning and configuration only when the network and application key counts are 0. You may need to call cmd_flash_ps_erase_all to delete all security keys and then reset the device.

Self provisioning configuration

The example doesn't declare any global variables for data to be changed at runtime. The provisioning and model configuration data are therefore defined at compilation time in selfprov.h and are used by the functions in selfprov.c to provision and configure the device.

The example gets the model IDs configured for the device from dcd.c which is generated from the Bluetooth Mesh Configurator. The example binds all of these model IDs to the application key. The example then recoginzes server and client models from these model IDs and applies server and client settings respectively. The server and client settings are publication parameters and subscription addresses. The same application key is used for all model configuration.

Unicast address

A unicast address is required to provision a device. The self provisioning function generates a unicast address by performing XOR operations on the device's Bluetooth address. Bit 0, 1, 2, and 3 are reserved for secondary element addresses and bit 14 is reserved for manual addresses. This gives 1,023 automatically allocated addresses in the range of 0x0010 and 0x3FF0 with the 4 LSbs and the 2 MSbs set to 0.

If the address 0x0000 or a duplicate address is generated, you need to allocate manually an address to the device and in this case the function doesn't run the automatic address allocation. The addresses you can allocate manually would be in the range of 0x4000 and 0x7FF0 with the 4 LSbs set to 0.

#define UNICAST_ADDRESS         0x0000

Set UNICAST_ADDRESS to 0x0000 to run the automatic unicast address allocation. Alternatively, you can set any value between 0x0001 and 0x7FFF inclusively to allocate a unicast address manually. It is recommended to separate manual and automatic address ranges and the definition UADDR_RSVD_BITS is usded for this purpose.

#define UADDR_ELEM_BITS         4

The number of the LSbs reserved for secondary element addresses. If the address 0x0010 is allocated to a node, the address of the primary element (element 0) is 0x0010 and the addresses of secondary elements are 0x0011 (element 1), 0x0012 (element 2) and so on, which are allocated by the Bluetooth Mesh stack. The default value 4 gives maximum 16 elements. Set UADDR_ELEM_BITS to a number N to allow the maximum (2 to the power of N) elements that any node can have.

#define UADDR_RSVD_BITS         1

The number of bits from bit 14 to LSb reserved for manual addresses in the range separate from the automatic address range. The default value 1 means you can set UNICAST_ADDRESS to any of the addresses with bit 14 set to 1, which are in the range of 0x4000 and 0x7FFF. You can set it to 0 if you want and you will need to manage the addresses that are unique among the automatically allocated addresses.

Security keys

The self provisioning function writes the security keys netkey, devkey and appkey directly into the persistent storage on the device. The key length is 128 bits, i.e. 16 bytes.

#define NETWORK_KEY             {1,1,1,1,2,2,2,2,3,3,3,3,4,4,4,4}
#define APPLICATION_KEY         {5,5,5,5,6,6,6,6,7,7,7,7,8,8,8,8}
#define DEVICE_KEY              {9,9,9,9,9,9,9,9,0,0,0,0,0,0,0,0}

The security keys NETWORK_KEY and DEVICE_KEY are required to provision a device and the security key APPLICATION_KEY is required to configure the node. The self provisioning function uses the application key to bind all models configured on the device and to set publication parameters.

Server and client models

The self provisioning function reads model IDs from DCD and splits them into two groups: server and client. The function sets the server publication parameters and subscription addresses to all server models and the client publication parameters and subscription addresses to all client models.

The models Configuration Server, Configuration Client, Health Server, Health Client and Setup servers are excluded.

#define PUB_SUB_SERVER_MODELS   {...}
#define PUB_SUB_CLIENT_MODELS   {...}

The self provisioning function determines whether a model ID is a server model or a client model by comparing it with PUB_SUB_SERVER_MODELS and PUB_SUB_CLIENT_MODELS. The function reads all model IDs from DCD and puts server model IDs to a server model buffer and client model IDs to a client model buffer, or drops the model IDs that don't exist in these definitions. You can remove any model ID from these definitions if you don't want the device running the model to send and receive messages.

#define MAX_PUB_SUB_MODELS      20

The size of the buffers used to store server and client model IDs. It is usually the maximum length of PUB_SUB_SERVER_MODELS and PUB_SUB_CLIENT_MODELS.

Publication address and subscription list

The server publication address and subscription list are set to all server models and the client publication address and subscription list are set to all client models. Therefore, messages sent from the nodes running a server model will go to the nodes running the corresponding client model, and vice versa.

To publish messages to a new group, you can add a new group address to the client subscription list and set the server publication address to the new group address, and vice versa. You can also configure the node not to send messages by setting the publication address to 0x0000, or not to receive messages by clearing the subscription list.

#define GRP_SVR_PUB_ADDRESS     0xC100
#define GRP_SVR_SUB_ADDRESSES   { 0xC000 }

#define GRP_CLI_PUB_ADDRESS     0xC000
#define GRP_CLI_SUB_ADDRESSES   { 0xC100 }

For the nodes running server models to send messages to the nodes running client models, set GRP_SVR_PUB_ADDRESS to an address in the list of GRP_CLI_SUB_ADDRESSES. For the nodes running client models to send messages to the nodes running server models, set GRP_CLI_PUB_ADDRESS to an address in the list of GRP_SVR_SUB_ADDRESSES.

Publication parameters

#define GRP_SVR_PUB_TTL             3
#define GRP_SVR_PUB_PERIOD          0
#define GRP_SVR_PUB_RETRANS         0
#define GRP_SVR_PUB_CREDENTIALS     0

#define GRP_CLI_PUB_TTL             3
#define GRP_CLI_PUB_PERIOD          0
#define GRP_CLI_PUB_RETRANS         0
#define GRP_CLI_PUB_CREDENTIALS     0

The server publication parameters are set to all server models and the client publication parameters are set to all client models on the node.

On December 20, 2020, EN/IEC 60950-1 safety standard will be withdrawn and fully replaced by EN/IEC 62368-1, requiring manufacturers to comply with the new standard for the presumption of conformity. Furthermore, as of February 6, 2020, RF regulatory standard EN 300 328 V2.2.2 has replaced EN 300 328 V2.1.1 with a transition period ending on August 6, 2021.  After the transitions, products on the market must comply with the updated standards.

Silicon Laboratories is committed to perform any required delta testing with the affected wireless modules (except for certain parts reaching EoL) according to the new standards and release the updated test reports and declarations of conformity (DoCs) before the end of the listed transition periods.

The parts planned to be tested are listed in the table below: