1ESP-BLE-MESH FAQ 2================ 3 4This document provides a summary of frequently asked questions about developing with ESP-BLE-MESH, and is divided into seven sections: 5 6* :ref:`ble-mesh-faq-provisioner-development` 7* :ref:`ble-mesh-faq-node-development` 8* :ref:`ble-mesh-faq-ble-mesh-and-wi-fi-coexistence` 9* :ref:`ble-mesh-faq-fast-provisioning` 10* :ref:`ble-mesh-faq-log-help` 11* :ref:`ble-mesh-faq-example-help` 12* :ref:`ble-mesh-faq-others` 13 14Users could refer to the sections for quick answer to their questions. This document will be updated based on the feedback collected via various channels. 15 16 17.. _ble-mesh-faq-provisioner-development: 18 191. Provisioner Development 20-------------------------- 21 22Generally, a Provisioner is used to provision unprovisioned devices and form a mesh network. And after provisioning, roles of the unprovisioned devices will be changed to those of a node. 23 241.1 What is the flow for an unprovisioned device to join ESP-BLE-MESH network? 25^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 26 27 There are two phases for a device to join ESP-BLE-MESH network via a Provisioner, namely, provisioning and configuration. 28 29 - The phase of provisioning is to assign unicast address, add NetKey and etc. to a device. By provisioning, the device joins the ESP-BLE-MESH network and its role is changed from an unprovisioned device to a node. 30 31 - The phase of configuration is to add AppKeys to the node and bind AppKeys to corresponding models. And some items are optional during configuration, including adding subscription addresses to the node, set publication information, etc. By configuration, the node can actually transmit messages to a Provisioner and receive messages from it. 32 331.2 If a Provisioner wants to change states of a node, what requirements should be met for a Provisioner? 34^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 35 36 - Client model that corresponds to server model of the node is required. 37 - NetKey and AppKey used to encrypt messages shall be owned by both the node and the Provisioner. 38 - The address owned by the node shall be known, which could be its unicast address or subscription address. 39 401.3 How can NetKey and AppKey be used? 41^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 42 43 - NetKey is used for encryption of messages in Network Layer. Nodes with the same NetKey are assumed to be in the same subnet while those with different NetKeys cannot communicate with each other. 44 - AppKey is used for encryption of messages in Upper Transport Layer. If client model and server model are bound to different AppKeys, the communication cannot be achieved. 45 461.4 How to generate a NetKey or AppKey for Provisioner? Can we use a fixed NetKey or AppKey? 47^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 48 49 - The API :cpp:func:`esp_ble_mesh_provisioner_add_local_net_key` can be used to add a NetKey with a fixed or random value. 50 - The API :cpp:func:`esp_ble_mesh_provisioner_add_local_app_key` can be used to add an AppKey with a fixed or random value. 51 521.5 Is the unicast address of Provisioner fixed? 53^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 54 55 The value of :code:`prov_unicast_addr` in :cpp:type:`esp_ble_mesh_prov_t` is used to set the unicast address of Provisioner, it can be set only once during initialization and can't be changed afterwards. 56 571.6 Can the address of Provisioner serve as destination address of the node-reporting-status message？ 58^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 59 60 The unicast address of Provisioner can be set only once during initialization and can't be changed afterwards. In theory, it can serve as the destination address of the node-reporting-status message, provided that the unicast address of the Provisioner is known by nodes. Nodes can know the unicast address of Provisioner during configuration since Provisioner sends messages to them with its unicast address used as the source address. 61 Subscription address can also be used. Provisioner subscribes to a group address or virtual address, and nodes send messages to the subscription address. 62 631.7 Is the unicast address of the node that is firstly provisioned by Provisioner to ESP-BLE-MESH network fixed？ 64^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 65 66 The value of :code:`prov_start_address` in :cpp:type:`esp_ble_mesh_prov_t` is used to set the starting address when the Provisioner provisions unprovisioned devices, i.e. the unicast address of the node it firstly provisioned. It can be set only once during initialization and can't be changed afterwards. 67 681.8 Is the unicast address of the node that mobile App firstly provisioned fixed? 69^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 70 71 The App will decide the unicast address, and currently most of them are fixed. 72 731.9 How to know which unprovisioned device is the Provisioner that is provisioning currently? 74^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 75 76 The value of :code:`prov_attention` in :cpp:type:`esp_ble_mesh_prov_t` is used by Provisioner set to unprovisioned device during provisioning. It can be set only once during initialization and can't be changed afterwards. When the unprovisioned device is joining the mesh network, it can display in a specific way like flashing light to notify Provisioner that it is being provisioned. 77 781.10 How many ways to authenticate the devices during provisioning? Which way was used in the :example:`provided examples <bluetooth/esp_ble_mesh>`? 79^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 80 81 There are four authentication methods, i.e. No OOB, Static OOB, Output OOB and Input OOB. In the provided examples, No OOB is used. 82 831.11 What information can be carried by the advertising packets of the unprovisioned device before provisioning into the network? 84^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 85 86 - Device UUID 87 - OOB Info 88 - URL Hash (optional) 89 901.12 Can such information be used for device identification? 91^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 92 93 For example, each unprovisioned device contains a unique Device UUID, which can be used for device identification. 94 951.13 How is the unicast address assigned when the node provisioned by Provisioner contains multiple elements? 96^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 97 98 - Provisioner will assign an unicast address for the primary element of the node, and unicast address of the remaining elements are incremented one by one. 99 - For example: If an unprovisioned device has three elements, i.e. the primary element, the second element and the third element. After provisioning, the primary element address of the node is 0x0002 while the second element address is 0x0003, and the third element address is 0x0004. 100 1011.14 How can Provisioner get and parse the :ref:`Composition Data <ble-mesh-terminology-composition>` of nodes through Configuration Client Model? 102^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 103 104 - Provisioner can get the Composition Data of nodes using the :ref:`Configuration Client Model <ble-mesh-terminology-foundation-models>` API :cpp:func:`esp_ble_mesh_config_client_set_state` with :code:`comp_data_get` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_get_state_t` set properly. 105 - Users can refer to the following code to parse the Composition Data: 106 107 .. code:: c 108 109 #include <stdio.h> 110 #include <string.h> 111 #include <stdint.h> 112 113 //test date: 0C001A0001000800030000010501000000800100001003103F002A00 114 //0C00 1A00 0100 0800 0300 0001 05 01 0000 0080 0100 0010 0310 3F002A00 115 116 // CID is 0x000C 117 // PID is 0x001A 118 // VID is 0x0001 119 // CRPL is 0x0008 120 // Features is 0x0003 – Relay and Friend features. 121 // Loc is “front” – 0x0100 122 // NumS is 5 123 // NumV is 1 124 // The Bluetooth SIG Models supported are: 0x0000, 0x8000, 0x0001, 0x1000, 0x1003 125 // The Vendor Models supported are: Company Identifier 0x003F and Model Identifier 0x002A 126 127 typedef struct { 128 int16_t cid; 129 int16_t pid; 130 int16_t vid; 131 int16_t crpl; 132 int16_t features; 133 int16_t all_models; 134 uint8_t sig_models; 135 uint8_t vnd_models; 136 } esp_ble_mesh_composition_head; 137 138 typedef struct { 139 uint16_t model_id; 140 uint16_t vendor_id; 141 } tsModel; 142 143 typedef struct { 144 // reserve space for up to 20 SIG models 145 uint16_t SIG_models[20]; 146 uint8_t numSIGModels; 147 148 // reserve space for up to 4 vendor models 149 tsModel Vendor_models[4]; 150 uint8_t numVendorModels; 151 } esp_ble_mesh_composition_decode; 152 153 int decode_comp_data(esp_ble_mesh_composition_head *head, esp_ble_mesh_composition_decode *data, uint8_t *mystr, int size) 154 { 155 int pos_sig_base; 156 int pos_vnd_base; 157 int i; 158 159 memcpy(head, mystr, sizeof(*head)); 160 161 if(size < sizeof(*head) + head->sig_models * 2 + head->vnd_models * 4) { 162 return -1; 163 } 164 165 pos_sig_base = sizeof(*head) - 1; 166 167 for(i = 1; i < head->sig_models * 2; i = i + 2) { 168 data->SIG_models[i/2] = mystr[i + pos_sig_base] | (mystr[i + pos_sig_base + 1] << 8); 169 printf("%d: %4.4x\n", i/2, data->SIG_models[i/2]); 170 } 171 172 pos_vnd_base = head->sig_models * 2 + pos_sig_base; 173 174 for(i = 1; i < head->vnd_models * 2; i = i + 2) { 175 data->Vendor_models[i/2].model_id = mystr[i + pos_vnd_base] | (mystr[i + pos_vnd_base + 1] << 8); 176 printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].model_id); 177 178 data->Vendor_models[i/2].vendor_id = mystr[i + pos_vnd_base + 2] | (mystr[i + pos_vnd_base + 3] << 8); 179 printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].vendor_id); 180 } 181 182 return 0; 183 } 184 185 void app_main(void) 186 { 187 esp_ble_mesh_composition_head head = {0}; 188 esp_ble_mesh_composition_decode data = {0}; 189 uint8_t mystr[] = { 0x0C, 0x00, 0x1A, 0x00, 190 0x01, 0x00, 0x08, 0x00, 191 0x03, 0x00, 0x00, 0x01, 192 0x05, 0x01, 0x00, 0x00, 193 0x00, 0x80, 0x01, 0x00, 194 0x00, 0x10, 0x03, 0x10, 195 0x3F, 0x00, 0x2A, 0x00}; 196 int ret; 197 198 ret = decode_comp_data(&head, &data, mystr, sizeof(mystr)); 199 if (ret == -1) { 200 printf("decode_comp_data error"); 201 } 202 } 203 2041.15 How can Provisioner further configure nodes through obtained Composition Data? 205^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 206 207 Provisioner do the following configuration by calling the :ref:`Configuration Client Model <ble-mesh-terminology-foundation-models>` API :cpp:func:`esp_ble_mesh_config_client_set_state`. 208 209 - Add AppKey to nodes with :code:`app_key_add` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. 210 - Add subscription address to the models of nodes with :code:`model_sub_add` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. 211 - Set publication information to the models of nodes with :code:`model_pub_set` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. 212 2131.16 Can nodes add corresponding configurations for themselves? 214^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 215 216 This method can be used in special cases like testing period. 217 218 - Here is an example to show nodes add new group addresses for their models. 219 220 .. code:: c 221 222 esp_err_t example_add_fast_prov_group_address(uint16_t model_id, uint16_t group_addr) 223 { 224 const esp_ble_mesh_comp_t *comp = NULL; 225 esp_ble_mesh_elem_t *element = NULL; 226 esp_ble_mesh_model_t *model = NULL; 227 int i, j; 228 229 if (!ESP_BLE_MESH_ADDR_IS_GROUP(group_addr)) { 230 return ESP_ERR_INVALID_ARG; 231 } 232 233 comp = esp_ble_mesh_get_composition_data(); 234 if (!comp) { 235 return ESP_FAIL; 236 } 237 238 for (i = 0; i < comp->element_count; i++) { 239 element = &comp->elements[i]; 240 model = esp_ble_mesh_find_sig_model(element, model_id); 241 if (!model) { 242 continue; 243 } 244 for (j = 0; j < ARRAY_SIZE(model->groups); j++) { 245 if (model->groups[j] == group_addr) { 246 break; 247 } 248 } 249 if (j != ARRAY_SIZE(model->groups)) { 250 ESP_LOGW(TAG, "%s: Group address already exists, element index: %d", __func__, i); 251 continue; 252 } 253 for (j = 0; j < ARRAY_SIZE(model->groups); j++) { 254 if (model->groups[j] == ESP_BLE_MESH_ADDR_UNASSIGNED) { 255 model->groups[j] = group_addr; 256 break; 257 } 258 } 259 if (j == ARRAY_SIZE(model->groups)) { 260 ESP_LOGE(TAG, "%s: Model is full of group addresses, element index: %d", __func__, i); 261 } 262 } 263 264 return ESP_OK; 265 } 266 267.. note:: 268 269 When the NVS storage of the node is enabled, group address added and AppKey bound by this method will not be saved in the NVS when the device is powered off currently. These configuration information can only be saved if they are configured by Configuration Client Model. 270 2711.17 How does Provisioner control nodes by grouping? 272^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 273 274 Generally there are two approaches to implement group control in ESP-BLE-MESH network, group address approach and virtual address approach. And supposing there are 10 devices, i.e., five devices with blue lights and five devices with red lights. 275 276 - Method 1: 5 blue lights can subscribe to a group address, 5 red lights subscribe to another one. By sending messages to different group addresses, Provisioner can realize group control. 277 278 - Method 2: 5 blue lights can subscribe to a virtual address, 5 red lights subscribe to another one. By sending messages to different virtual addresses, Provisioner can realize group control. 279 2801.18 How does Provisioner add nodes to multiple subnets? 281^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 282 283 Provisioner can add multiple NetKeys to nodes during configuration, and nodes sharing the same NetKey belong to the same subnet. Provisioner can communicate with nodes on different subnets by using different NetKeys. 284 2851.19 How does Provisioner know if a node in the mesh network is offline? 286^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 287 288 Node offline is usually defined as: the condition that the node cannot be properly communicated with other nodes in the mesh network due to power failure or some other reasons. 289 290 There is no connection between nodes and nodes in the ESP-BLE-MESH network. They communicate with each other through advertising channels. 291 292 An example is given here to show how to detect a node is offline by Provisioner. 293 294 - The node can periodically send heartbeat messages to Provisioner. And if Provisioner failed to receive heartbeat messages in a certain period, the node is considered to be offline. 295 296.. note:: 297 298 The heartbeat message should be designed into a single package (less than 11 bytes), so the transmission and reception of it can be more efficient. 299 3001.20 What operations should be performed when Provisioner removes nodes from the network? 301^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 302 303 Usually when Provisioner tries to remove node from the mesh network, the procedure includes three main steps: 304 305 - Firstly, Provisioner adds the node that need to be removed to the "blacklist". 306 307 - Secondly, Provisioner performs the :ref:`Key Refresh procedure <ble-mesh-terminology-network-management>`. 308 309 - Lastly, the node performs node reset procedure, and switches itself to an unprovisioned device. 310 3111.21 In the Key Refresh procedure, how does Provisioner update the Netkey owned by nodes? 312^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 313 314 - Provisioner updates the NetKey of nodes using the :ref:`Configuration Client Model <ble-mesh-terminology-foundation-models>` API :cpp:func:`esp_ble_mesh_config_client_set_state` with :code:`net_key_update` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. 315 316 - Provisioner updates the AppKey of nodes using the :ref:`Configuration Client Model <ble-mesh-terminology-foundation-models>` API :cpp:func:`esp_ble_mesh_config_client_set_state` with :code:`app_key_update` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. 317 3181.22 How does Provisioner manage nodes in the mesh network? 319^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 320 321 ESP-BLE-MESH implements several functions related to basic node management in the example, such as :cpp:func:`esp_ble_mesh_store_node_info`. And ESP-BLE-MESH also provides the API :cpp:func:`esp_ble_mesh_provisioner_set_node_name` which can be used to set the node's local name and the API :cpp:func:`esp_ble_mesh_provisioner_get_node_name` which can be used to get the node's local name. 322 3231.23 What does Provisioner need when trying to control the server model of nodes? 324^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 325 326 Provisioner must include corresponding client model before controlling the server model of nodes. 327 328 Provisioner shall add its local NetKey and AppKey. 329 330 - Provisioner add NetKey by calling the API :cpp:func:`esp_ble_mesh_provisioner_add_local_net_key`. 331 332 - Provisioner add AppKey by calling the API :cpp:func:`esp_ble_mesh_provisioner_add_local_app_key`. 333 334 Provisioner shall configure its own client model. 335 336 - Provisioner bind AppKey to its own client model by calling the API :cpp:func:`esp_ble_mesh_provisioner_bind_app_key_to_local_model`. 337 3381.24 How does Provisoner control the server model of nodes? 339^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 340 341 ESP-BLE-MESH supports all SIG-defined client models. Provisioner can use these client models to control the server models of nodes. And the client models are divided into 6 categories with each category has the corresponding functions. 342 343 - Configuration Client Model 344 345 - The API :cpp:func:`esp_ble_mesh_config_client_get_state` can be used to get the :cpp:type:`esp_ble_mesh_cfg_client_get_state_t` values of Configuration Server Model. 346 - The API :cpp:func:`esp_ble_mesh_config_client_set_state` can be used to set the :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` values of Configuration Server Model. 347 348 - Health Client Model 349 350 - The API :cpp:func:`esp_ble_mesh_health_client_get_state` can be used to get the :cpp:type:`esp_ble_mesh_health_client_get_state_t` values of Health Server Model. 351 - The API :cpp:func:`esp_ble_mesh_health_client_set_state` can be used to set the :cpp:type:`esp_ble_mesh_health_client_set_state_t` values of Health Server Model. 352 353 - Generic Client Models 354 355 - The API :cpp:func:`esp_ble_mesh_generic_client_get_state` can be used to get the :cpp:type:`esp_ble_mesh_generic_client_get_state_t` values of Generic Server Models. 356 - The API :cpp:func:`esp_ble_mesh_generic_client_set_state` can be used to set the :cpp:type:`esp_ble_mesh_generic_client_set_state_t` values of Generic Server Models. 357 358 - Lighting Client Models 359 360 - The API :cpp:func:`esp_ble_mesh_light_client_get_state` can be used to get the :cpp:type:`esp_ble_mesh_light_client_get_state_t` values of Lighting Server Models. 361 - The API :cpp:func:`esp_ble_mesh_light_client_set_state` can be used to set the :cpp:type:`esp_ble_mesh_light_client_set_state_t` values of Lighting Server Models. 362 363 - Sensor Client Models 364 365 - The API :cpp:func:`esp_ble_mesh_sensor_client_get_state` can be used to get the :cpp:type:`esp_ble_mesh_sensor_client_get_state_t` values of Sensor Server Model. 366 - The API :cpp:func:`esp_ble_mesh_sensor_client_set_state` can be used to set the :cpp:type:`esp_ble_mesh_sensor_client_set_state_t` values of Sensor Server Model. 367 368 - Time and Scenes Client Models 369 - The API :cpp:func:`esp_ble_mesh_time_scene_client_get_state` can be used to get the :cpp:type:`esp_ble_mesh_time_scene_client_get_state_t` values of Time and Scenes Server Models. 370 - The API :cpp:func:`esp_ble_mesh_time_scene_client_set_state` can be used to set the :cpp:type:`esp_ble_mesh_time_scene_client_set_state_t` values of Time and Scenes Server Models. 371 372 373.. _ble-mesh-faq-node-development: 374 3752. Node Development 376------------------- 377 3782.1 What kind of models are included by nodes? 379^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 380 381 - In ESP-BLE-MESH, nodes are all composed of a series of models with each model implements some functions of the node. 382 383 - Model has two types, client model and server model. Client model can get and set the states of server model. 384 385 - Model can also be divided into SIG model and vendor model. All behaviors of SIG models are officially defined while behaviors of vendor models are defined by users. 386 3872.2 Is the format of messages corresponding to each model fixed? 388^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 389 390 - Messages, which consist of opcode and payload, are divided by opcode. 391 392 - The type and the format of the messages corresponding to models are both fixed, which means the messages transmitted between models are fixed. 393 3942.3 Which functions can be used to send messages with the models of nodes? 395^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 396 397 - For client models, users can use the API :cpp:func:`esp_ble_mesh_client_model_send_msg` to send messages. 398 399 - For server models, users can use the API :cpp:func:`esp_ble_mesh_server_model_send_msg` to send messages. 400 401 - For publication, users call the API :cpp:func:`esp_ble_mesh_model_publish` to publish messages. 402 4032.4 How to achieve the transmission of messages without packet loss? 404^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 405 406 Acknowledegd message is needed if users want to transmit messages without packet loss. The default time to wait for corresponding response is set in :ref:`CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT`. If the sender waits for the response until the timer expires, the corresponding timeout event would be triggered. 407 408.. note:: 409 410 Response timeout can be set in the API :cpp:func:`esp_ble_mesh_client_model_send_msg`. The default value (4 seconds) would be applied if the parameter :code:`msg_timeout` is set to **0**. 411 4122.5 How to send unacknowledged messages? 413^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 414 415 For client models, users can use the API :cpp:func:`esp_ble_mesh_client_model_send_msg` with the parameter :code:`need_rsp` set to :code:`false` to send unacknowledged messages. 416 417 For server models, the messages sent by using the API :cpp:func:`esp_ble_mesh_server_model_send_msg` are always unacknowledged messages. 418 4192.6 How to add subscription address to models? 420^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 421 422 Subscription address can be added through Configuration Client Model. 423 4242.7 What is the difference between messages sent and published by models? 425^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 426 427 Messages sent by calling the API :cpp:func:`esp_ble_mesh_client_model_send_msg` or :cpp:func:`esp_ble_mesh_server_model_send_msg` will be sent in the duration determined by the Network Transmit state. 428 429 Messages published by calling the API :cpp:func:`esp_ble_mesh_model_publish` will be published determined by the Model Publication state. And the publication of messages is generally periodic or with a fixed number of counts. The publication period and publication count are controlled by the Model Publication state, and can be configured through Configuration Client Model. 430 4312.8 How many bytes can be carried when sending unsegmented messages? 432^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 433 434 The total payload length (which can be set by users) of unsegmented message is 11 octets, so if the opcode of the message is 2 octets, then the message can carry 9-octets of valid information. For vendor messages, due to the 3-octets opcode, the remaining payload length is 8 octets. 435 4362.9 When should the :ref:`Relay <ble-mesh-terminology-features>` feature of nodes be enabled? 437^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 438 439 Users can enable the Relay feature of all nodes when nodes detected in the mesh network are sparse. 440 441 For dense mesh network, users can choose to just enable the Relay feature of several nodes. 442 443 And users can enable the Relay feature by default if the mesh network size is unknown. 444 4452.10 When should the :ref:`Proxy <ble-mesh-terminology-features>` feature of node be enabled? 446^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 447 448 If the unprovisioned device is expected to be provisioned by a phone, then it should enable the Proxy feature since almost all the phones do not support sending ESP-BLE-MESH packets through advertising bearer currently. And after the unprovisioned device is provisioned successfully and becoming a Proxy node, it will communicate with the phone using GATT bearer and using advertising bearer to communicate with other nodes in the mesh network. 449 4502.11 How to use the Proxy filter? 451^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 452 453 The Proxy filter is used to reduce the number of Network PDUs exchanged between a Proxy Client (e.g. the phone) and a Proxy Server (e.g. the node). And with the Proxy filter, Proxy Client can explicitly request to receive only mesh messages with certain destination addresses from Proxy Server. 454 4552.12 When a message can be relayed by a Relay node? 456^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 457 458 If a message need to be relayed, the following conditions should be met. 459 460 - The message is in the mesh network. 461 462 - The message is not sent to the unicast address of the node. 463 464 - The value of TTL in the message is greater than 1. 465 4662.13 If a message is segmented into several segments, should the other Relay nodes just relay when one of these segments is received or wait until the message is received completely? 467^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 468 469 Relay nodes will forward segments when one of them are received rather than keeping waiting until all the segments are received. 470 4712.14 What is the principle of reducing power consumption using :ref:`Low Power <ble-mesh-terminology-features>` feature? 472^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 473 474 - When the radio is turned on for listening, the device is consuming energy. When low power feature of the node is enabled, it will turn off its radio in the most of the time. 475 476 - And cooperation is needed between low power node and friend node, thus low power node can receive messages at an appropriate or lower frequency without the need to keep listening. 477 478 - When there are some new messages for low power node, its friend node will store the messages for it. And low power node can poll friend nodes to see if there are new messages at a fixed interval. 479 4802.15 How to continue the communication on the network after powering-down and powering-up again? 481^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 482 483 Enable the configuration :code:`Store ESP-BLE-MESH Node configuration persistently` in `menuconfig`. 484 4852.16 How to send out the self-test results of nodes? 486^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 487 488 It is recommended that nodes can publish its self-test results periodically through Health Server Model. 489 4902.17 How to transmit information between nodes? 491^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 492 493 One possible application scenario for transmitting information between nodes is that spray nodes would be triggered once smoke alarm detected high smoke concentration. There are two approaches in implementation. 494 495 - Approach 1 is that spray node subscribes to a group address. When smoke alarm detects high smoke concentration, it will publish a message whose destination address is the group address which has been subscribed by spray node. 496 497 - Approach 2 is that Provisioner can configure the unicast address of spray node to the smoke alarm. When high smoke concentration is detected, smoke alarm can use send messages to the spray node with the spray node's unicast address as the destination address. 498 4992.18 Is gateway a must for nodes communication? 500^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 501 502 - Situation 1: nodes only communicate within the mesh network. In this situation, no gateway is need. ESP-BLE-MESH network is a flooded network, messages in the network have no fixed paths, and nodes can communicate with each other freely. 503 504 - Situation 2: if users want to control the nodes remotely, for example turn on some nodes before getting home, then a gateway is needed. 505 5062.19 When will the IV Update procedure be performed? 507^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 508 509 IV Update procedure would be performed once sequence number of messages sent detected by the bottom layer of node reached a critical value. 510 5112.20 How to perform IV Update procedure? 512^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 513 514 Nodes can perform IV Update procedure with Secure Network Beacon. 515 516 517.. _ble-mesh-faq-ble-mesh-and-wi-fi-coexistence: 518 5193. ESP-BLE-MESH and Wi-Fi Coexistence 520------------------------------------- 521 5223.1 Which modes does Wi-Fi support when it coexists with ESP-BLE-MESH? 523^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 524 525 Currently only Wi-Fi station mode supports the coexistence. 526 5273.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist? 528^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 529 530 The `ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. 531 532 And some configurations in menuconfig shall be enabled to support PSRAM. 533 534 - :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` 535 - :code:`Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the memory from the PSRAM` 536 - :code:`Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation in BT/BLE stack.` 537 - :code:`Bluetooth --> Bluetooth controller --> BLE full scan feature supported.` 538 - :code:`Wi-Fi --> Software controls Wi-Fi/Bluetooth coexistence --> Wi-Fi` 539 540 541.. _ble-mesh-faq-fast-provisioning: 542 5434. Fast Provisioning 544-------------------- 545 5464.1 Why is fast provisioning needed? 547^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 548 549 Normally when they are several unprovisioned devices, users can provision them one by one. But when it comes to a large number of unprovisioned devices (e.g. 100), provisioning them one by one will take huge amount of time. With fast provisioning, users can provision 100 unprovisioned devices in about 50 seconds. 550 5514.2 Why EspBleMesh App would wait for a long time during fast provisioning? 552^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 553 554 After the App provisioned one Proxy node, it will disconnect from the App during fast provisioning, and reconnect with the App when all the nodes are provisioned. 555 5564.3 Why is the number of node addresses displayed in the App is more than that of existing node addresses? 557^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 558 559 Each time after a fast provisioning process, and before starting a new one, the node addresses in the App should be cleared, otherwise the number of the node address will be incorrect. 560 5614.4 What is the usage of the **count** value which was input in EspBleMesh App? 562^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 563 564 The **count** value is provided to the Proxy node which is provisioned by the App so as to determine when to start Proxy advertising in advance. 565 5664.5 When will Configuration Client Model of the node running :example:`fast_prov_server <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/fast_prov_server>` example start to work? 567^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 568 569 Configuration Client Model will start to work after the Temporary Provisioner functionality is enabled. 570 5714.6 Will the Temporary Provisioner functionality be enabled all the time? 572^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 573 574 After the nodes receive messages used to turn on/off lights, all the nodes will disable its Temporary Provisioner functionality and become nodes. 575 576 577.. _ble-mesh-faq-log-help: 578 5795. Log Help 580----------- 581 582You can find meaning of errors or warnings when they appear at the bottom of ESP-BLE-MESH stack. 583 5845.1 What is the meaning of warning :code:`ran out of retransmit attempts`? 585^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 586 587 When the node transmits a segmented message, and due to some reasons, the receiver doesn't receive the complete message. Then the node will retransmit the message. When the retransmission count reaches the maximum number, which is 4 currently, then this warning will appear. 588 5895.2 What is the meaning of warning :code:`Duplicate found in Network Message Cache`? 590^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 591 592 When the node receives a message, it will compare the message with the ones stored in the network cache. If the same has been found in the cache, which means it has been received before, then the message will be dropped. 593 5945.3 What is the meaning of warning :code:`Incomplete timer expired`? 595^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 596 597 When the node doesn't receive all the segments of a segmented message during a certain period (e.g. 10 seconds), then the Incomplete timer will expire and this warning will appear. 598 5995.4 What is the meaning of warning :code:`No matching TX context for ack`? 600^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 601 602 When the node receives a segment ack and it doesn't find any self-send segmented message related with this ack, then this warning will appear. 603 6045.5 What is the meaning of warning :code:`No free slots for new incoming segmented messages`? 605^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 606 607 When the node has no space for receiving new segmented message, this warning will appear. Users can make the space larger through the configuration :ref:`CONFIG_BLE_MESH_RX_SEG_MSG_COUNT`. 608 6095.6 What is the meaning of error :code:`Model not bound to Appkey 0x0000`？ 610^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 611 612 When the node sends messages with a model and the model has not been bound to the AppKey with AppKey Index 0x000, then this error will appear. 613 6145.7 What is the meaning of error :code:`Busy sending message to DST xxxx`? 615^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 616 617 This error means client model of the node has transmitted a message to the target node and now is waiting for a response, users can not send messages to the same node with the same unicast address. After the corresponding response is received or timer is expired, then another message can be sent. 618 619 620.. _ble-mesh-faq-example-help: 621 6226. Example Help 623--------------- 624 6256.1 How are the ESP-BLE-MESH callback functions classified? 626^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 627 628 - The API :cpp:func:`esp_ble_mesh_register_prov_callback` is used to register callback function used to handle provisioning and networking related events. 629 - The API :cpp:func:`esp_ble_mesh_register_config_client_callback` is used to register callback function used to handle Configuration Client Model related events. 630 - The API :cpp:func:`esp_ble_mesh_register_config_server_callback` is used to register callback function used to handle Configuration Server Model related events. 631 - The API :cpp:func:`esp_ble_mesh_register_health_client_callback` is used to register callback function used to handle Health Client Model related events. 632 - The API :cpp:func:`esp_ble_mesh_register_health_server_callback` is used to register callback function used to handle Health Server Model related events. 633 - The API :cpp:func:`esp_ble_mesh_register_generic_client_callback` is used to register callback function used to handle Generic Client Models related events. 634 - The API :cpp:func:`esp_ble_mesh_register_light_client_callback` is used to register callback function used to handle Lighting Client Models related events. 635 - The API :cpp:func:`esp_ble_mesh_register_sensor_client_callback` is used to register callback function used to handle Sensor Client Model related events. 636 - The API :cpp:func:`esp_ble_mesh_register_time_scene_client_callback` is used to register callback function used to handle Time and Scenes Client Models related events. 637 - The API :cpp:func:`esp_ble_mesh_register_custom_model_callback` is used to register callback function used to handle vendor model and unrealized server models related events. 638 639 640.. _ble-mesh-faq-others: 641 6427. Others 643--------- 644 6457.1 How to print the message context? 646^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 647 648 The examples use :cpp:func:`ESP_LOG_BUFFER_HEX` to print the message context while the ESP-BLE-MESH protocol stack uses :cpp:func:`bt_hex`. 649 6507.2 Which API can be used to restart {IDF_TARGET_NAME}? 651^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 652 653 The API :cpp:func:`esp_restart`. 654 6557.3 How to monitor the remaining space of the stack of a task? 656^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 657 658 The API :cpp:func:`vTaskList` can be used to print the remaining space of the task stack periodically. 659 6607.4 How to change the level of log without changing the menuconfig output level? 661^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 662 663 The API :cpp:func:`esp_log_level_set` can be used to change the log output level rather than using menuconfig to change it. 664
