Mesh Device

Mesh Device Sample demonstrates how to use Mesh Device and develop applications based on Mesh Device.

When the Mesh Device has not been provisioned, it is called an Unprovisioned device and cannot send or receive mesh messages. At this time, it will send appropriate advertising to inform the Mesh Provisioner of its existence.
After the Mesh Device has been provisioned, it is called a Node, and information such as addresses and keys are provided by the Mesh Provisioner during the Provisioning phase.

Requirements

This example supports the following development kits:

Requirements
Hardware Platforms	Board Name
RTL87x2G HDK	RTL87x2G EVB

This example also requires another device to run Mesh Provisioner Sample as the network manager.

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_device\src\app_flags.h.
For the configuration required for Mesh, please refer to samples\bluetooth\mesh\mesh_device\src\app_mesh_flags.h.

Building and Downloading

This example can be found in the SDK folder:

Keil

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

GCC

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

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

Open the project file.
Compile the target file, please refer to Quick Start for the steps listed in Generating App Image.
After successful compilation, the file app_MP_sdk_xxx.bin will be generated in the directory samples\bluetooth\mesh\mesh_device\proj\rtl87x2g\mdk\bin.
Download the bin to the EVB board, please refer to Quick Start for the steps listed in MP Tool Download.
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 Provisioner project for testing.

Preparation Stage

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

Testing Phase

This section mainly introduces the testing part of the Mesh Device 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 related to Mesh Device, please refer to mesh_cmd.c, device_cmd.c.

As the majority of the testing process for Mesh Devices is led by the Mesh Provisioner, please refer to the section on the testing phases of the Mesh Provisioner: Testing Stage.

Device Startup

If the Mesh Device is in the unprovisioned state, after reset, the following information will be displayed in the serial port assistant.

>> Hello MeshDevice <<
>unprov device!
>bt addr: 0x000000000076

If the Mesh Device has been provisioned, after reset, the following information will be displayed in the serial port assistant.

>> Hello MeshDevice <<
>ms addr: 0x0100
>bt addr: 0x000000000076

Information Display

When the Mesh Device is in the unprovisioned state, entering ls in the serial port assistant will yield the following information, including Device UUID, Bluetooth address, Elements, and Models information.

>ls
MeshState:      0
DevUUID:        0x760000000000060708090A0B0C0D0E0F
BTAddr:         0x000000000076
IVindex:        0-0x0
Seq:            0x000000
NodeAddr:       0x0000-1-8
Element:        0-8
Model:          0-0-0x0000ffff
Model:          1-1-0x0002ffff
Model:          2-2-0x0000005d
Model:          3-3-0x0003005d
Model:          4-4-0x0004005d

After the Mesh Device has been provisioned, entering ls in the command line will provide the following information, which will include DevKey, NetKey, etc. More information will continue to be displayed based on the configuration of the Mesh Provisioner.

>ls
MeshState:      1
DevUUID:        0x760000000000060708090A0B0C0D0E0F
BTAddr:         0x000000000076
DevKey:         0-0x0100-1-0xE8950FD2FBC15F6932B3D0A426FC1FE9
NetKey:         0-0x0000-1-0-0
                0x7DD7364CD842AD18C17C2B820C84C3D6
IVindex:        0-0x0
Seq:            0x000000
NodeAddr:       0x0100-1-8
Element:        0-8
Model:          0-0-0x0000ffff
Model:          1-1-0x0002ffff
Model:          2-2-0x0000005d
Model:          3-3-0x0003005d
Model:          4-4-0x0004005d

Code Overview

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

Source Code Directory.
The section Initialization introduces the initialization process of the Mesh Device.
The section Participating in Network introduces how the Mesh Device joins the network and sends/receives messages.

Source Code Directory

Project directory: sdk\samples\bluetooth\mesh\mesh_device\proj
Source code directory: sdk\samples\bluetooth\mesh\mesh_device\src

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

└── Project: mesh_device
    └── 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_dev.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_device 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
            ├── device_app.c                 includes device application code
            ├── mesh_sdk.c                   includes mesh sdk version record
            ├── mesh_cmd.c                   includes mesh user commands
            ├── device_cmd.c                 includes device user commands
            ├── test_cmd.c                   includes test user commands
            ├── delay_msg_rsp.c              includes delay message response
            ├── ping_app.c                   includes ping model application code
            ├── datatrans_server_app.c       includes datatrans server model application code
            ├── io_management.c              includes io management
            ├── blob_client_app.c            includes blob client model application code
            ├── dfu_updater_app.c            includes dfu updater application code
            └── dfu_distributor_app.c        includes dfu distributor application code

Among them, mesh_dev.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_dev.lib, subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_0\gcc\mesh_dev.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_dev.lib, subsys\bluetooth\mesh\chips\rtl87x2g\lib\v1_1\gcc\mesh_dev.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.

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

Participating in Network

Device can only act as a node in the network after being provisioned by the provisioner. It supports different Models based on actual needs to support corresponding profiles or functionalities.

Provisioning: For details on provisioning, please refer to Mesh Provisioning; For the operation process, please refer to Provisioning Operation Process.
Model: Device 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.