Mesh Provisioner

The Mesh Provisioner Sample demonstrates how to use the Mesh Provisioner and how to develop applications based on it.

Mesh Provisioner, as the administrator of the mesh network, has the following main functions:

• Distributing addresses and keys when the Mesh Device joins the network.

• Managing various nodes.

Requirements

This example supports the following development kits:

Requirements

Hardware Platforms	Board Name
RTL87x2G HDK	RTL87x2G EVB

This example also requires another device or multiple devices to run Mesh Device Sample as nodes in the network.

For more information, please refer to the Quick Start.

Wiring

Please refer to RTL87x2G EVB Interfaces and Modules in Quick Start.

Configurations

• For the configuration needed for LE, please refer to samples\bluetooth\mesh\mesh_provisioner\src\app_flags.h.

• For the configuration required for Mesh, please refer to samples\bluetooth\mesh\mesh_provisioner\src\app_mesh_flags.h.

Building and Downloading

This example can be found in the SDK folder:

Keil

Project file: samples\bluetooth\mesh\mesh_provisioner\proj\rtl87x2g\mdk

GCC

Project file: samples\bluetooth\mesh\mesh_provisioner\proj\rtl87x2g\gcc

To compile and run this example, please follow the steps below:

1. Open the project file.

2. Compile the target file, please refer to Quick Start for the steps listed in Generating App Image.

3. After successful compilation, the file app_MP_sdk_xxx.bin will be generated in the directory samples\bluetooth\mesh\mesh_provisioner\proj\rtl87x2g\mdk\bin.

4. Download the bin to the EVB board, please refer to Quick Start for the steps listed in MP Tool Download.

5. Press the reset button on the EVB board, and the program will start running.

Experimental Verification

After downloading the example project to the EVB board, users can use another development board running the Mesh Device project for testing.

Preparation Stage

1. Prepare a Mesh Provisioner, if necessary, use the Debug Analyzer to get logs.

2. Prepare one or more Mesh Devices, if necessary, use the Debug Analyzer to get logs.

Testing Stage

This section mainly introduces the testing part of Mesh Provisioner and the usage of related User Command, which facilitates users’ early learning and later debugging. For detailed information about User Command, please refer to User Command Interface.

Users can use any serial port assistant software to interact with the EVB board. For detailed user commands of Mesh Provisioner, please refer to mesh_cmd.c, provisioner_cmd.c, client_cmd.c

Provisioning

Provisioner can collect and display nearby node information, controlled through the dis command.

Mesh Device Information Collection

Step	Provisioner	Description
1	dis 1	Display surrounding mesh devices
2	dis 0	Stop searching after collecting the target device’s information (device UUID or Bluetooth address)

Device will obtain address and network key during provisioning, and will join the network successfully after which mesh communication can be conducted. Use the transport layer ping function, namely the tping command, for network layer testing. Any node within the network can send and receive transport layer ping/pong messages. The provisioner can also use the configuration client to communicate with a specified device, e.g., to get composition data page 0.

PB-ADV Provisioning

Step	Provisioner	Device	Description
1	pbadvcon 000102030405060708090a0b0c0d0e0f		Initiate connection to the device with UUID 000102030405060708090a0b0c0d0e0f, wait for a prompt whether PB-ADV bearer is successfully established
2	prov		Wait for a prompt indicating provisioning process completion
3		ls	Check if the device has successfully obtained the address and key, assuming the address is 0x0100
4		tping xffff	Test if they can communicate at the network layer
5	cdg x100		Get the composition data page 0 of device 0x100

PB-GATT Provisioning

Step	Provisioner	Device	Description
1	con ff0011223344		Establish an LE link with the device 0xff0011223344, wait for the link to be successfully established
2	provdis		Discover provision service
3	provcmd 0 1		Enable provision service CCCD
4	prov		Wait for provisioning process to complete
5		ls	Check if the device has successfully obtained address and key
6		tping xffff	Test network layer communication between devices
7	cdg x100		Get device 0x100 composition data page 0

A device that has already been provisioned can be restored to the unprovisioned state using the nr command.

Key Management

Devices that have been provisioned can be configured by a configuration client. For example, users can add an AppKey and bind it to the ping model. The ping model can then send ping messages at the model layer.

Key Management

Step	Provisioner	Device	Instructions
1	aka x100 0 0		Add AppKey 0 to target node 0x100 and bind it to NetKey 0
2		ls	Check if the device successfully added AppKey 0
3	mab x100 0 x5d 0		Bind AppKey 0 to the ping model (model id 0x5d) of the 0th element on the target node 0x100
4		ls	Check if the device’s ping model has successfully bound AppKey 0
5		ping xffff 3	Test ping model control model

Subscription Configuration

The Provisioner can manage the model subscription addresses of devices. For example, adding a subscription address to the ping model.

Model Subscription Configuration

Step	Provisioner	Device	Description
1	msa x100 0 x5d xc000		Add a subscription address 0xc000 to the ping model with model id 0x5d at element 0 of target node 0x100
2		ls	Check if the device model has successfully added the subscription address 0xc000
3	ping xc000 3		Test if the device subscribes to 0xc000

Friendship

The low power node device that has been provisioned can start establishing friendship.

Friendship

Step	Friend Node	Low Power Node	Description
1	fninit 1 5	lpninit 1	Initialize a friend node that supports establishing friendship with 1 LPN node and has a queue size of 5; Initialize an LPN node that supports establishing friendship with 1 friend node
2		lpnreq 0 0	Wait for the friendship establishment result
3		tping xffff 3	Notice that tping takes longer

Remote Provisioning

A remote provisioning server device that has been provisioned can help collect information about nearby nodes and pass it on to the remote provisioning client.

RPR Information Collection

Step	Provisioner	RPR server	Description
1	rpsst x100 10 20		Instruct the RPR server to search for nearby mesh devices
2	rpssp x100 0		After collecting information about the target device (device UUID or Bluetooth address), instruct it to stop searching

Remote Provisioning

Step	Provisioner	RPR server	Description
1	rplop x100 0 x000102030405060708090a0b0c0d0e0f 10		Instructs the RPR server to initiate a connection to 000102030405060708090a0b0c0d0e0f, waiting for the RPR server to indicate connection success
2	prov		Wait for the provisioning process to complete
3		ls	Check if the device has successfully obtained an address and key
4		tping xffff	Test if network layer communication is possible
5	cdg x101		Get device 0x101’s composition data page 0

Device Key Refresh

Step	Provisioner	RPR server	Description
1	rplod x100 0 0		Initiate a connection to the RPR server and specify the procedure for device key refresh
2	rprdk		Start the refresh device key process

Node Address Refresh

Step	Provisioner	RPR server	Description
1	rplod x100 0 1		Initiate a connection to the RPR server and specify the procedure for node address refresh
2	rprna x103		Start the refresh node address process

Composition Data Refresh

Step	Provisioner	RPR server	Description
1		pids x21	Set new data for composition page 128
2	rplod x103 0 2		Initiate a connection to the RPR server and specify the procedure for composition data refresh
3	rprcd		Start the refresh composition data process

Directed Forwarding

Devices that have already been provisioned and wish to use the directed forwarding feature can refer to the following procedure. First, configure the directed forwarding control state, and set the publish policy of the model already configured with the AppKey to directed forwarding.

Directed Forwarding

Step	Provisioner	Device	Description
1	dcs x100 0 0 1 1 1 1 1		Enable the device’s directed forwarding control state
2	dpps x100 0 1 x100 x5d		Set the ping model’s publish policy to directed forwarding mode
3		ping x1 3	Ping while automatically triggering the path discovery procedure
4		dfpdis 0 x1 0 0	Manually trigger the path discovery procedure
5		dfpsol 0 x100	Manually trigger the path solicitation procedure
6		dfpdupt 0 x100 x120 1	Manually trigger the path dependents update procedure
7	fta x100 0 0 1 1 x200 2 x300 2 1 1		Add fixed path via the directed forwarding model
8	ftda x100 0 0 x200 x300 1 1 x700 10 x220 1		Add dependents for the fixed path via the directed forwarding model

Subnet Bridge

When a node is simultaneously in net 0 (NetKey index is 0) and net 1 (NetKey index is 1) networks, a subnet bridge client can use the subnet bridge model to configure the subnet bridge table for the node. After configuration, the node can forward messages from net 0 to net 1. Note that the message in the bridge will be encrypted with the corresponding NetKey during forwarding, but the AppKey will not change. Nodes that send and receive messages need the AppKey to be consistent to accurately decrypt the data in the access layer.

Subnet Bridge

Step	Provisioner	Device	Description
1	bta x100 0 1 0 1 x102 x103		Configure subnet bridge table 0x102 (net 0) –> 0x103 (net 1)

Binary Large Object Transfer

Devices that have already been provisioned can refer to the following procedure to use BLOB models for transfer.

BLOB Transfer

Step	Provisioner	Device	Description
1	mab x100 0 x1400ffff 0		Add AppKey 0 to blob transfer server of 0x100 node
2		btsi 0x1100000000000011 10 3	Initialize blob transfer server
3	btccr 0 2 1 x100		Start capability retrieve procedure
4	btcbt x100 0 2 0x1100000000000011 2000 1 1 0 1 x100		Start blob transfer procedure
5	btctc 0x1100000000000011 1 x100		Cancel blob transfer procedure

Device Firmware Update

Please refer to Bluetooth Mesh OTA.

Code Overview

The main purpose of this chapter is to help users get familiar with the development process related to Mesh Provisioner. This chapter will introduce according to the following sections:

• Source Code Directory.

• The section Initialization introduces the initialization process of the Mesh Provisioner.

• The section Network Management introduces how the Mesh Provisioner manages the network and sends/receives messages.

Source Code Directory

• Project directory: sdk\samples\bluetooth\mesh\mesh_provisioner\proj

• Source code directory: sdk\samples\bluetooth\mesh\mesh_provisioner\src

The source file structure of the Mesh Provisioner application project is shown below.

└── Project: mesh_provisioner
    └── secure_only_app
        ├── Device                           includes startup code
        ├── CMSE Library                     Non-secure callable lib
        ├── lib                              includes all binary symbol files that user application is built on
            ├── ROM_NS.lib
            ├── rtl87x2g_sdk.lib
            ├── rtl87x2g_io.lib
            ├── gap_utils.lib
            ├── mesh_prov.lib
            └── lowerstack.lib
        ├── io                               includes all peripheral drivers and module code used by the application
        ├── profile                          includes LE profiles or services used by the application
        ├── model                            includes mesh models used by the application
        ├── dfu                              includes dfu source code used by the application
        └── APP                              includes the mesh_provisioner user application implementation
            ├── main.c                       includes the io, os, platform, le host and mesh stack initialization
            ├── app_task.c                   includes app task initialization and main loop
            ├── provisioner_app.c            includes provisioner application code
            ├── mesh_sdk.c                   includes mesh sdk version record
            ├── mesh_cmd.c                   includes mesh user commands
            ├── provisioner_cmd.c            includes provisioner user commands
            ├── test_cmd.c                   includes test user commands
            ├── client_cmd.c                 includes client user commands
            ├── delay_msg_rsp.c              includes delay message response
            ├── ping_app.c                   includes ping model application code
            ├── generic_client_app.c         includes generic client model application code
            ├── light_client_app.c           includes light client model application code
            ├── datatrans_client_app.c       includes datatrans client model application code
            ├── rmt_prov_client_app.c        includes remote provisioning client model application code
            ├── blob_client_app.c            includes blob client model application code
            ├── dfu_distributor_app.c        includes dfu distributor application code
            └── dfu_initiator_app.c          includes dfu Initiator application code

Among them, mesh_prov.lib is divided into V1.0 and V1.1 according to the Mesh Protocol version, users can choose the appropriate lib according to the required features.

V1.0

Library file: subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_0\mdk\mesh_prov.lib, subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_0\gcc\mesh_prov.a

Header file: subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_0\mesh_config.h

V1.1

Library file: subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_1\mdk\mesh_prov.lib, subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_1\gcc\mesh_prov.a

Header file: subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_1\mesh_config.h

Initialization

When the EVB board resets, the main() function executes, and the initialization process is as follows:

int main(void)
{
    extern uint32_t random_seed_value;
    srand(random_seed_value);
    board_init();
    driver_init();
    le_gap_init(APP_MAX_LINKS);
    gap_lib_init();
    app_le_gap_init();
    app_le_profile_init();
    mesh_stack_init();
    pwr_mgr_init();
    task_init();
    os_sched_start();

    return 0;
}

• le_gap_init() is used to initialize GAP and set the number of links.

• app_le_gap_init() is used to initialize GAP parameters.

• app_le_profile_init() is used to initialize the Profiles.

• mesh_stack_init() is used to initialize the Mesh Stack, for configuration, refer to Device Information Configuration, Device UUID Configuration, Network Features and Parameters Configuration, Mesh Log Configuration, etc.

Compared to other nodes in the network, the provisioner needs to allocate a mesh address and some keys for itself during initialization, as illustrated below.

void mesh_stack_init(void)
{
    ......
    /** init mesh stack */
    mesh_init();

    /** configure provisioner */
    mesh_node.node_state = PROV_NODE;
    mesh_node.unicast_addr = bt_addr[0] % 99 + 1;
    const uint8_t net_key[] = MESH_NET_KEY;
    const uint8_t net_key1[] = MESH_NET_KEY1;
    const uint8_t app_key[] = MESH_APP_KEY;
    const uint8_t app_key1[] = MESH_APP_KEY1;
    uint16_t net_key_index = net_key_add(0, net_key);
    app_key_add(net_key_index, 0, app_key);
    uint8_t net_key_index1 = net_key_add(1, net_key1);
    app_key_add(net_key_index1, 1, app_key1);
    mesh_model_bind_all_key();
    ......
}

After calling os_sched_start, app_main_task() will get scheduled, and the processing of mesh messages is as follows:

#define EVENT_MESH                    0x80
......

void app_main_task(void *p_param)
{
    ......
    mesh_start(EVENT_MESH, EVENT_IO_TO_APP, evt_queue_handle, io_queue_handle);
    ......

    while (true)
    {
        if (os_msg_recv(evt_queue_handle, &event, 0xFFFFFFFF) == true)
        {
            if (event == EVENT_IO_TO_APP)
            {
                ......
            }
            else if (event == EVENT_MESH)
            {
                mesh_inner_msg_handle(event);
            }
            else
            {
                ......
            }
        }
    }
}

Network Management

As a network administrator, a provisioner needs to manage all nodes joining the network, including the provisioning process, the configurations, and subsequent message interactions.

• Provisioning: For details on provisioning, please refer to Mesh Provisioning; and for the operation process, please refer to Provisioning Operation Process.

• Model: Provisioner will include some fixed models and some user-registered models. For details on models, please refer to Mesh Model.

• Message Send: For message sending details, please refer to Mesh Message Send.