Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Provide BLE Mesh documentation

Browse source
This commit is contained in:
Krzysztof Budzynski 2019-10-30 17:01:18 +08:00
parent 9d5a7f8df6
commit 2c3548b65e
38 changed files with 1973 additions and 333 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

153
components/bt/esp_ble_mesh/Kconfig.in
View file

@ -14,7 +14,9 @@ if BLE_MESH
default y
help
Enable this option to allow using specific duplicate scan filter
in BLE Mesh, and Scan Duplicate Type must be set to 0x02.
in BLE Mesh, and Scan Duplicate Type must be set by choosing the
option in the Bluetooth Controller section in menuconfig, which is
"Scan Duplicate By Device Address and Advertising Data".
config BLE_MESH_FAST_PROV
bool "Enable BLE Mesh Fast Provisioning"
@ -24,16 +26,24 @@ if BLE_MESH
default n
help
Enable this option to allow BLE Mesh fast provisioning solution to be used.
When there are multiple unprovisioned devices around, fast provisioning can
greatly reduce the time consumption of the whole provisioning process.
When this option is enabled, and after an unprovisioned device is provisioned
into a node successfully, it can be changed to a temporary Provisioner.
config BLE_MESH_NODE
bool "Support for BLE Mesh Node"
help
Enable the device to be provisioned into a node.
Enable the device to be provisioned into a node. This option should be
enabled when an unprovisioned device is going to be provisioned into a
node and communicate with other nodes in the BLE Mesh network.
config BLE_MESH_PROVISIONER
bool "Support for BLE Mesh Provisioner"
help
Enable the device to be a provisioner.
Enable the device to be a Provisioner. The option should be enabled when
a device is going to act as a Provisioner and provision unprovisioned
devices into the BLE Mesh network.
if BLE_MESH_PROVISIONER
@ -42,8 +52,10 @@ if BLE_MESH
default 20
range 1 100
help
This option specifies how may unprovisioned devices can be added to device
queue for provisioning.
This option specifies how many unprovisioned devices can be added to device
queue for provisioning. Users can use this option to define the size of the
queue in the bottom layer which is used to store unprovisioned device
information (e.g. Device UUID, address).
config BLE_MESH_MAX_STORED_NODES
int "Maximum number of nodes whose information can be stored"
@ -51,48 +63,64 @@ if BLE_MESH
range 1 1000
help
This option specifies the maximum number of nodes whose information can be
stored by a provisioner in its upper layer.
stored by a Provisioner in its upper layer.
Users can change this value according to the number of nodes whose information
(e.g. Device UUID, unicast address, element number) are going to be stored by
a Provisioner. And the nodes include the provisioned ones and user-added ones.
config BLE_MESH_MAX_PROV_NODES
int "Maximum number of devices that can be provisioned by provisioner"
int "Maximum number of devices that can be provisioned by Provisioner"
default 20
range 1 100
help
This option specifies how many devices can be provisioned by provisioner.
This option specifies how many devices can be provisioned by a Provisioner.
This value indicates the maximum number of unprovisioned devices which can be
provisioned by a Provisioner. For instance，if the value is 6, it means the
Provisioner can provision up to 6 unprovisioned devices.
Theoretically a Provisioner without the limitation of its memory can provision
up to 32766 unprovisioned devices, here we limit the maximum number to 100
just to limit the memory used by a Provisioner. The bigger the value is, the
more memory it will cost by a Provisioner to store the information of nodes.
if BLE_MESH_PB_ADV
config BLE_MESH_PBA_SAME_TIME
int "Maximum number of PB-ADV running at the same time by provisioner"
int "Maximum number of PB-ADV running at the same time by Provisioner"
default 2
range 1 10
help
This option specifies how many devices can be provisioned at the same
time using PB-ADV.
This option specifies how many devices can be provisioned at the same time
using PB-ADV. For examples, if the value is 2, it means a Provisioner can
provision two unprovisioned devices with PB-ADV at the same time.
endif # BLE_MESH_PB_ADV
if BLE_MESH_PB_GATT
config BLE_MESH_PBG_SAME_TIME
int "Maximum number of PB-GATT running at the same time by provisioner"
int "Maximum number of PB-GATT running at the same time by Provisioner"
default 1
range 1 5
help
This option specifies how many devices can be provisioned at the same
time using PB-GATT.
time using PB-GATT. For example, if the value is 2, it means a Provisioner
can provision two unprovisioned devices with PB-GATT at the same time.
endif # BLE_MESH_PB_GATT
config BLE_MESH_PROVISIONER_SUBNET_COUNT
int "Maximum number of mesh subnets that can be created by provisioner"
int "Maximum number of mesh subnets that can be created by Provisioner"
default 3
range 1 4096
help
This option specifies how many subnets per network a provisioner can create.
This option specifies how many subnets per network a Provisioner can create.
Indeed, this value decides the number of network keys which can be added by a Provisioner.
config BLE_MESH_PROVISIONER_APP_KEY_COUNT
int "Maximum number of application keys that can be owned by provisioner"
int "Maximum number of application keys that can be owned by Provisioner"
default 9
range 1 4096
help
This option specifies how many application keys the provisioner can have.
This option specifies how many application keys the Provisioner can have.
Indeed, this value decides the number of the application keys which can be added by a Provisioner.
endif # BLE_MESH_PROVISIONER
@ -110,7 +138,8 @@ if BLE_MESH
default y
help
Enable this option to allow the device to be provisioned over the
advertising bearer.
advertising bearer. This option should be enabled if PB-ADV is
going to be used during provisioning procedure.
config BLE_MESH_PB_GATT
bool "Provisioning support using GATT (PB-GATT)"
@ -118,6 +147,8 @@ if BLE_MESH
select BLE_MESH_PROV
help
Enable this option to allow the device to be provisioned over GATT.
This option should be enabled if PB-GATT is going to be used during
provisioning procedure.
# Virtual option enabled whenever any Proxy protocol is needed
config BLE_MESH_PROXY
@ -133,6 +164,7 @@ if BLE_MESH
help
This option enables support for Mesh GATT Proxy Service, i.e. the
ability to act as a proxy between a Mesh GATT Client and a Mesh network.
This option should be enabled if a node is going to be a Proxy Server.
config BLE_MESH_NODE_ID_TIMEOUT
int "Node Identity advertising timeout"
@ -144,6 +176,9 @@ if BLE_MESH
Node Identity. The given value is in seconds. The specification limits
this to 60 seconds and lists it as the recommended value as well.
So leaving the default value is the safest option.
When an unprovisioned device is provisioned successfully and becomes a
node, it will start to advertise using Node Identity during the time
set by this option. And after that, Network ID will be advertised.
if BLE_MESH_PROXY
@ -154,6 +189,9 @@ if BLE_MESH
range 1 32767
help
This option specifies how many Proxy Filter entries the local node supports.
The entries of Proxy filter (whitelist or blacklist) are used to store a
list of addresses which can be used to decide which messages will be forwarded
to the Proxy Client by the Proxy Server.
endif # BLE_MESH_PROXY
@ -161,7 +199,9 @@ if BLE_MESH
bool "BLE Mesh net buffer pool usage tracking"
default y
help
Enable BLE Mesh net buffer pool tracking.
Enable BLE Mesh net buffer pool tracking. This option is used to introduce another
variable in the bottom layer to record the usage of advertising buffers of BLE Mesh
devices. Recommend to enable this option as default.
config BLE_MESH_SETTINGS
bool "Store BLE Mesh Node configuration persistently"
@ -170,6 +210,8 @@ if BLE_MESH
When selected, the BLE Mesh stack will take care of storing/restoring the
BLE Mesh configuration persistently in flash. Currently this only supports
storing BLE Mesh node configuration.
Currently enabling this option will only store BLE Mesh nodes' information
in the flash.
if BLE_MESH_SETTINGS
config BLE_MESH_STORE_TIMEOUT
@ -179,6 +221,9 @@ if BLE_MESH
help
This value defines in seconds how soon any pending changes are actually
written into persistent storage (flash) after a change occurs.
The option allows nodes to delay a certain period of time to save proper
information to flash. The default value is 0, which means information
will be stored immediately once there are updates.
config BLE_MESH_SEQ_STORE_RATE
int "How often the sequence number gets updated in storage"
@ -200,16 +245,17 @@ if BLE_MESH
range 0 1000000
default 5
help
This value defines in seconds how soon the RPL(Replay Protection List)
This value defines in seconds how soon the RPL (Replay Protection List)
gets written to persistent storage after a change occurs. If the node
receives messages frequently, then a large value is recommended. If the
node receives messages rarely, then the value can be as low as 0 (which
means the PRL is written into the storage immediately).
means the RPL is written into the storage immediately).
Note that if the node operates in a security-sensitive case, and there is
a risk of sudden power-off, then a value of 0 is strongly recommended.
Otherwise, a power loss before RPL being written into the storage may
introduce message replay attacks and system security will be in a
vulnerable state.
endif # if BLE_MESH_SETTINGS
config BLE_MESH_SUBNET_COUNT
@ -218,6 +264,7 @@ if BLE_MESH
range 1 4096
help
This option specifies how many subnets a Mesh network can have at the same time.
Indeed, this value decides the number of the network keys which can be owned by a node.
config BLE_MESH_APP_KEY_COUNT
int "Maximum number of application keys per network"
@ -225,6 +272,7 @@ if BLE_MESH
range 1 4096
help
This option specifies how many application keys the device can store per network.
Indeed, this value decides the number of the application keys which can be owned by a node.
config BLE_MESH_MODEL_KEY_COUNT
int "Maximum number of application keys per model"
@ -248,6 +296,7 @@ if BLE_MESH
range 0 4096
help
This option specifies how many Label UUIDs can be stored.
Indeed, this value decides the number of the Virtual Addresses can be supported by a node.
config BLE_MESH_CRPL
int "Maximum capacity of the replay protection list"
@ -256,6 +305,9 @@ if BLE_MESH
help
This option specifies the maximum capacity of the replay protection list.
It is similar to Network message cache size, but has a different purpose.
The replay protection list is used to prevent a node from replay attack,
which will store the source address and sequence number of the received
mesh messages.
config BLE_MESH_MSG_CACHE_SIZE
int "Network message cache size"
@ -265,6 +317,8 @@ if BLE_MESH
Number of messages that are cached for the network. This helps prevent
unnecessary decryption operations and unnecessary relays. This option
is similar to Replay protection list, but has a different purpose.
A node is not required to cache the entire Network PDU and may cache
only part of it for tracking, such as values for SRC/SEQ or others.
config BLE_MESH_ADV_BUF_COUNT
int "Number of advertising buffers"
@ -310,6 +364,11 @@ if BLE_MESH
range 1 BLE_MESH_ADV_BUF_COUNT
help
Maximum number of simultaneous outgoing multi-segment and/or reliable messages.
The default value is 1, which means the device can only send one segmented
message at a time. And if another segmented message is going to be sent, it
should wait for the completion of the previous one.
If users are going to send multiple segmented messages at the same time, this
value should be configured properly.
config BLE_MESH_RX_SEG_MSG_COUNT
int "Maximum number of simultaneous incoming segmented messages"
@ -317,6 +376,11 @@ if BLE_MESH
range 1 255
help
Maximum number of simultaneous incoming multi-segment and/or reliable messages.
The default value is 1, which means the device can only receive one segmented
message at a time. And if another segmented message is going to be received,
it should wait for the completion of the previous one.
If users are going to receive multiple segmented messages at the same time, this
value should be configured properly.
config BLE_MESH_RX_SDU_MAX
int "Maximum incoming Upper Transport Access PDU length"
@ -353,12 +417,18 @@ if BLE_MESH
config BLE_MESH_RELAY
bool "Relay support"
help
Support for acting as a Mesh Relay Node.
Support for acting as a Mesh Relay Node. Enabling this option will allow
a node to support the Relay feature, and the Relay feature can still
be enabled or disabled by proper configuration messages. Disabling this
option will let a node not support the Relay feature.
config BLE_MESH_LOW_POWER
bool "Support for Low Power features"
help
Enable this option to operate as a Low Power Node.
Enable this option to operate as a Low Power Node. If low power consumption
is required by a node, this option should be enabled. And once the node
enters the mesh network, it will try to find a Friend node and establish a
friendship.
if BLE_MESH_LOW_POWER
@ -370,6 +440,9 @@ if BLE_MESH
reduced scan duty cycle. The downside of this is that the node may miss
out on messages intended for it until it has successfully set up Friendship
with a Friend node.
When this option is enabled, the node will stop scanning for a period of
time after a Friend Request or Friend Poll is sent, so as to reduce more
power consumption.
config BLE_MESH_LPN_AUTO
bool "Automatically start looking for Friend nodes once provisioned"
@ -378,6 +451,9 @@ if BLE_MESH
Once provisioned, automatically enable LPN functionality and start looking
for Friend nodes. If this option is disabled LPN mode needs to be manually
enabled by calling bt_mesh_lpn_set(true).
When an unprovisioned device is provisioned successfully and becomes a node,
enabling this option will trigger the node starts to send Friend Request at
a certain period until it finds a proper Friend node.
config BLE_MESH_LPN_AUTO_TIMEOUT
int "Time from last received message before going to LPN mode"
@ -389,7 +465,7 @@ if BLE_MESH
before starting to look for Friend nodes.
config BLE_MESH_LPN_RETRY_TIMEOUT
int "Retry timeout for Friend requests"
int "Retry timeout for Friend Requests"
default 8
range 1 3600
help
@ -403,6 +479,8 @@ if BLE_MESH
help
The contribution of the RSSI, measured by the Friend node, used in Friend
Offer Delay calculations. 0 = 1, 1 = 1.5, 2 = 2, 3 = 2.5.
RSSIFactor, one of the parameters carried by Friend Request sent by Low Power
node, which is used to calculate the Friend Offer Delay.
config BLE_MESH_LPN_RECV_WIN_FACTOR
int "ReceiveWindowFactor, used in Friend Offer Delay calculation"
@ -411,6 +489,8 @@ if BLE_MESH
help
The contribution of the supported Receive Window used in Friend Offer
Delay calculations. 0 = 1, 1 = 1.5, 2 = 2, 3 = 2.5.
ReceiveWindowFactor, one of the parameters carried by Friend Request sent by
Low Power node, which is used to calculate the Friend Offer Delay.
config BLE_MESH_LPN_MIN_QUEUE_SIZE
int "Minimum size of the acceptable friend queue (MinQueueSizeLog)"
@ -441,6 +521,8 @@ if BLE_MESH
the Friend node before the PollTimeout timer expires, then the
friendship is considered terminated. The value is in units of 100
milliseconds, so e.g. a value of 300 means 30 seconds.
The smaller the value, the faster the Low Power node tries to get
messages from corresponding Friend node and vice versa.
config BLE_MESH_LPN_INIT_POLL_TIMEOUT
int "The starting value of the PollTimeout timer"
@ -468,6 +550,7 @@ if BLE_MESH
default 8
help
Maximum number of groups to which the LPN can subscribe.
endif # BLE_MESH_LOW_POWER
config BLE_MESH_FRIEND
@ -490,6 +573,8 @@ if BLE_MESH
default 16
help
Minimum number of buffers available to be stored for each local Friend Queue.
This option decides the size of each buffer which can be used by a Friend node
to store messages for each Low Power node.
config BLE_MESH_FRIEND_SUB_LIST_SIZE
int "Friend Subscription List Size"
@ -497,7 +582,9 @@ if BLE_MESH
default 3
help
Size of the Subscription List that can be supported by a Friend node for a
Low Power node.
Low Power node. And Low Power node can send Friend Subscription List Add or
Friend Subscription List Remove messages to the Friend node to add or remove
subscription addresses.
config BLE_MESH_FRIEND_LPN_COUNT
int "Number of supported LPN nodes"
@ -505,6 +592,9 @@ if BLE_MESH
default 2
help
Number of Low Power Nodes with which a Friend can have Friendship simultaneously.
A Friend node can have friendship with multiple Low Power nodes at the same time,
while a Low Power node can only establish friendship with only one Friend node at
the same time.
config BLE_MESH_FRIEND_SEG_RX
int "Number of incomplete segment lists per LPN"
@ -522,7 +612,8 @@ if BLE_MESH
depends on BLE_MESH
default n
help
Select this to save the BLE Mesh related rodata code size.
Select this to save the BLE Mesh related rodata code size. Enabling this option
will disable the output of BLE Mesh debug log.
menu "BLE Mesh STACK DEBUG LOG LEVEL"
depends on BLE_MESH && !BLE_MESH_NO_LOG
@ -603,6 +694,10 @@ if BLE_MESH
help
To improve the real-time requirements of bt controller in BLE Mesh,
task lock is used to replace IRQ lock.
With this option enabled, interrupt lock instead of the mutex will
be used and the BLE Mesh stack will try to change interrupt level to
protect some critical situations. Users need to ensure that this option
is disabled so mutex will be used in the bottom layer.
config BLE_MESH_CLIENT_MSG_TIMEOUT
int "Timeout(ms) for client message response"
@ -611,6 +706,10 @@ if BLE_MESH
help
Timeout value used by the node to get response of the acknowledged
message which is sent by the client model.
This value indicates the maximum time that a client model waits for
the response of the sent acknowledged messages. If a client model
uses 0 as the timeout value when sending acknowledged messages, then
the default value will be used which is four seconds.
menu "Support for BLE Mesh Client Models"
@ -717,6 +816,7 @@ if BLE_MESH
help
This option removes the 96 hour limit of the IV Update Procedure and
lets the state to be changed at any time.
If IV Update test mode is going to be used, this option should be enabled.
menu "BLE Mesh specific test option"
@ -802,3 +902,4 @@ if BLE_MESH
endmenu
endif # BLE_MESH

21
components/bt/esp_ble_mesh/README.md Normal file
View file

@ -0,0 +1,21 @@
# ESP-BLE-MESH Component
This is Espressif Bluetooth Low Energy Mesh component folder.
This component is a part of Espressif IoT Development Framework (ESP-IDF). For the latest documentation please refer to [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/index.html).
The ESP-BLE-MESH networking enables many-to-many (m:m) device communications and is optimized for creating large-scale device networks.
### [ESP-BLE-MESH Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/esp_ble_mesh/index.html)
- [Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/esp_ble_mesh/index.html##getting-started-with-ble-mesh)
- [Architecture](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/esp_ble_mesh/arhitecture.html)
- [Feature List](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/esp_ble_mesh/ble_mesh-feature-list.html)
- [FAQ](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/esp_ble_mesh/ble_mesh_faq.html)
- [API Reference](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/bluetooth/ble_mesh.html)
### [ESP-BLE-MESH Examples](https://github.com/espressif/esp-idf/tree/master/examples/bluetooth/esp_ble_mesh)
- Refer to **ESP-BLE-MESH Examples** of [Getting Started](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/esp_ble_mesh/index.html##getting-started-with-ble-mesh) for the tutorials of ESP BLE Mesh examples.

9
components/bt/esp_ble_mesh/mesh_docs/BLE-Mesh_FAQs_EN.md
View file

@ -1,9 +0,0 @@
# Frequently Asked Questions
## General Questions
### Why I do not get a reply from the remote device when I perform get operation immediately after set operation has been performed?
* Any Client Model operation needs to wait for the completion event of an ongoing operation. Once the completion event is received the next command can be executed. If a command is executed before the completion event is received, a timeout error will occur.
### When I use the API `esp_ble_mesh_client_model_send_msg`, why does it crash with the log messages *Invalid client value when sent client msg* or *Invalid client value when sent client msg*?
* You should initialize a structure of the type `esp_ble_mesh_client_t` and set its value as the user data of client model.

89
components/bt/esp_ble_mesh/mesh_docs/BLE-Mesh_Feature_List_EN.md
View file

@ -1,89 +0,0 @@
# Espressif BLE Mesh Feature List
## Currently Supported Features
### Mesh Core
* Provisioning: Node Role
* Advertising and GATT bearer
* Authentication OOB
* Provisioning: Provisioner Role
* Advertising and GATT bearer
* Authentication OOB
* Networking
* Relay
* Segmentation and Reassembly
* Key Refresh
* IV Update
* Proxy Support
* Multiple Client Models Run Simultaneously
* Support multiple client models send packets to different nodes simultaneously
* No blocking between client model and server
* NVS Storing
* Store Provisioning Data of The Node Device
### Mesh Applications
* Fast Provisioning
* Fast Provisioning Server Model
* Fast Provisioning Client Model
* Example & Demo Video
* Wi-Fi & BLE Mesh Coexistence
* Example & Demo Video(coming soon)
* Mesh Console Commands
* Example
### Mesh Models
* Foundation Models
* Configuration Server Model
* Configuration Client Model
* Health Server Model
* Health Client Model
* Generic Client Models
* Generic OnOff Client
* Generic Level Client
* Generic Location Client
* Generic Default Transition Timer Client
* Generic Power OnOff Client
* Generic Power Level Client
* Generic Battery Client
* Generic Property Client
* Generic Server Models
* Generic OnOff Server (Simple)
* Lighting Client Models
* Light Lightness Client
* Light CTL Client
* Light HSL Client
* Sensor Client Models
* Sensor Client
* Time and Scenes Client Models
* Scene Client
## Future Release Features
### Mesh Core
* BLE Mesh BQB Certification
* Friend Feature
* Low Power Node Feature
### Mesh Applications
* Fast OTA
### Mesh Models

155
components/bt/esp_ble_mesh/mesh_docs/BLE-Mesh_Getting_Started_EN.md
View file

@ -1,155 +0,0 @@
# Introduction
Bluetooth mesh networking enables many-to-many (m:m) device communications and is optimized for creating large-scale device networks.
Devices may relay data to other devices not in direct radio range of the originating device. In this way, mesh networks can span very large physical areas and contain large numbers of devices. It is ideally suited for building automation, sensor networks, and other IoT solutions where tens, hundreds, or thousands of devices need to reliably and securely communicate with one another.
Bluetooth mesh is not a wireless communications technology, but a networking technology. This technology is dependent upon Bluetooth Low Energy (BLE) - a wireless communications protocol stack.
# Specifications
The official specifications for Bluetooth mesh can be found [here](https://www.bluetooth.com/specifications/mesh-specifications)
# Getting Started with BLE Mesh on ESP32
If you are new to ESP32, you may first need to go through the [Getting Started guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html).
Built on top of Zephyr BLE Mesh stack, the ESP BLE Mesh implementation supports device provisioning and node control. It also supports such node features as Proxy, Relay, Low power and Friend.
## Access to ESP BLE Mesh
Since you are on this page, you should already have access to Espressif BLE Mesh SDK. If you do not have access, please get in touch with your point of contact.
## Documentation
The ESP BLE Mesh code in the SDK is organized as below. Each folder contains source files related to it as well as a subfolder with header files for the exposed functionality.
```
$tree components/bt/ble_mesh/
├── api /* BLE Mesh functionality exposed through esp_ble_mesh_* APIs for the applications */
│   ├── core /* BLE Mesh Core APIs */
│   │   └── include
│   └── models /* Foundation Models and other Client Models APIs */
│   └── include
├── btc
│   └── include
├── mesh_core /* BLE mesh core based on Zephyr BLE stack with miscellaneous modifications and
│ │ an adaptation layer to make it work with ESP32 */
│   └── include
├── mesh_docs /* BLE Mesh docs */
└── mesh_models /* Foundation Models and other Client Models implementations */
└── include
```
To demonstrate the features supported by BLE Mesh SDK, a few sample examples have been added. Each example has a README.md file for quick start as well as a walkthrough file that explains the functionality in detail.
Below is a snapshot of the BLE Mesh examples directory
```
$ tree examples/bluetooth/ble_mesh/
├── ble_mesh_client_model
│   ├── main
│   │   ├── ble_mesh_client_model_main.c
│   │   ├── board.c
│   │   ├── board.h
│   │   ├── component.mk
│   │   └── Kconfig.projbuild
│   ├── Makefile
│   ├── README.md
│   └── sdkconfig.defaults
├── ble_mesh_node
│   ├── main
│   │   ├── ble_mesh_demo_main.c
│   │   ├── board.c
│   │   ├── board.h
│   │   ├── component.mk
│   │   └── Kconfig.projbuild
│   ├── Makefile
│   ├── README.md
│   ├── sdkconfig.defaults
│   └── tutorial
│   └── Ble_Mesh_Node_Example_Walkthrough.md
├── ble_mesh_provisioner
│ ├── main
│ │   ├── ble_mesh_demo_main.c
│ │   ├── board.c
│ │   ├── board.h
│ │   ├── component.mk
│ │   └── Kconfig.projbuild
│ ├── Makefile
│ ├── README.md
│ ├── sdkconfig.defaults
│ └── tutorial
│ └── Ble_Mesh_Provisioner_Example_Walkthrough.md
├──ble_mesh_console
│ ├── ble_mesh_node
│ └── ble_mesh_provisioner
├──ble_mesh_fast_provision
│ ├── ble_mesh_fast_prov_client
│ └── ble_mesh_fast_prov_server
├──ble_mesh_vendor_models
│ ├── fast_prov_vendor_model
└──ble_mesh_wifi_coexist
├── main
├── components
└── tutorial
└── ble_mesh_wifi_coexist.md
8 directories, 26 files
```
## Hardware and Setup
At present ESP32-DevKitC and ESP-WROVER-KIT are supported for BLE Mesh implementation. You can find the details about the modules [here](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html)
You can choose the board through menuconfig: `make menuconfig -> Example Configuration -> Board selection for BLE Mesh`
Note that if you plan to use ESP32-DevKitC, you need to connect an RGB LED to GPIO pins 25, 26 and 27.
## Sample Examples
* BLE Mesh Node
This example shows the use of BLE Mesh as a node device having a Configuration Server model and a Generic OnOff Server model. A BLE Mesh provisioner can then provision the node and control a RGB LED representing on/off state.
* BLE Mesh Client Model
This example shows how a Generic OnOff Client model within a node works. The node has a Configuration Server model, a Generic OnOff Server model and a Generic OnOff Client model.
* BLE Mesh Provisioner
This example shows how a device can act as a BLE Mesh provisioner to provision devices. The provisioner has a Configuration Server model, a Configuration Client model and a Generic OnOff Client model.
## Mobile Apps
ESP BLE Mesh implementation is compatible with a few phone apps, including Silicon Labs BLE Mesh and nRF Mesh. These apps are available on Google Play and App Store. In addition, Espressif offers its own Android app which is currently being actively developed. You can find the latest APK file [here](http://download.espressif.com/BLE_MESH/BLE_Mesh_Tools/BLE_Mesh_App/EspBleMesh-0.9.4.apk).
Note: The most recent tested version 1.1.0 of Silicon Labs App has a bug, which has been fixed by a workaround on the SDK side. The fix is implemented through a configuration option enabled by default. For other Android/iOS apps, this option needs to be disabled from menuconfig:
`make menuconfig -> Example Configuration -> This option fixes the bug of Silicon Lab Android App 1.1.0 when reconnection will cause the sequence number to recount from 0`
## Building and Flashing
If you build the application for the first time, the menuconfig screen will pop up. You can choose the board from the Example Configuration option. Additionally, you can modify the serial settings in the Serial flasher config option in accordance with your port configuration.
BLE Mesh specific configuration options can also be modified through: `make menuconfig -> Component config -> Bluetooth Mesh support`
You can still change options at any other time using `make menuconfig`.
```
$ export IDF_PATH=/path/to/esp-ble-mesh-sdk-v0.x
$ cd examples/bluetooth/ble_mesh/<example_name>
$ make -j8 flash monitor
```
# Reporting Issues
* If you find a bug or have a feature request, go to [the Issues section on GitHub](https://github.com/espressif/esp-idf/issues). Before reporting a new issue, please check the existing issues at the provided link and the FAQs document in the `mesh_docs` folder.
* When you submit an issue or a feature request on GitHub, please add the tag "BLE Mesh" in the issue title for our faster reaction.

1
components/bt/esp_ble_mesh/mesh_docs/BLE-Mesh_Known_Issues_EN.md
View file

@ -1 +0,0 @@
To be added.

50
components/bt/esp_ble_mesh/mesh_docs/README.md
View file

@ -1,50 +0,0 @@
# ESP BLE Mesh Framework
This folder contains all the documents of ESP BLE Mesh.
* Note: breaking changes might be introduced into ESP BLE Mesh on [minor IDF versions](https://docs.espressif.com/projects/esp-idf/en/latest/versions.html)
## Demos
* [Provisioning of BLE Mesh nodes using Smartphone App](http://download.espressif.com/BLE_MESH/Docs4Customers/esp-ble-mesh-demo.mp4)
* [Espressif Fast Provisioning using ESP BLE Mesh App](http://download.espressif.com/BLE_MESH/BLE_Mesh_Demo/V0.4_Demo_Fast_Provision/ESP32_BLE_Mesh_Fast_Provision.mp4)
* [Espressif BLE Mesh and Wi-Fi Coexistence](http://download.espressif.com/BLE_MESH/BLE_Mesh_Demo/V0.5_Demo_Coexistence/ESP_BLE_MESH_%26_WIFI_Coexistence.mp4)
## Examples
* [BLE Mesh Node Example Code](../../../../examples/bluetooth/ble_mesh/ble_mesh_node)
* [BLE_Mesh_Node_Example_Walkthrough](../../../../examples/bluetooth/ble_mesh/ble_mesh_node/tutorial/Ble_Mesh_Node_Example_Walkthrough.md)
* [BLE Mesh Provisioner Example Code](../../../../examples/bluetooth/ble_mesh/ble_mesh_provisioner)
* [BLE_Mesh_Provisioner_Example_Walkthrough](../../../../examples/bluetooth/ble_mesh/ble_mesh_provisioner/tutorial/Ble_Mesh_Provisioner_Example_Walkthrough.md)
* [BLE Mesh Client Model Example Code](../../../../examples/bluetooth/ble_mesh/ble_mesh_client_model)
* [BLE_Mesh_Client_Model_Example_Walkthrough](../../../../examples/bluetooth/ble_mesh/ble_mesh_client_model/tutorial/ble_mesh_client_model.md)
* [BLE Mesh Console Example Code](../../../../examples/bluetooth/ble_mesh/ble_mesh_console)
* [BLE Mesh Fast Prov Client Example Code](../../../../examples/bluetooth/ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client)
* [BLE_Mesh_Fast_Prov_Client_Example_Walkthrough](../../../../examples/bluetooth/ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client/tutorial/ble_mesh_fast_provision_client.md)
* [BLE Mesh Fast Prov Server Example Code](../../../../examples/bluetooth/ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server)
* [BLE_Mesh_Fast_Prov_Server_Example_Walkthrough](../../../../examples/bluetooth/ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server/tutorial/ble_mesh_fast_provision_server.md)
* [BLE Mesh Wifi Coexist Example Code](../../../../examples/bluetooth/ble_mesh/ble_mesh_wifi_coexist)
* [BLE_Mesh_Wifi_Coexist_Example_Walkthrough](../../../../examples/bluetooth/ble_mesh/ble_mesh_wifi_coexist/tutorial%20%20%20%20%20%20/ble_mesh_wifi_coexist.md)
## Documentation
### ESP BLE Mesh Development Documentation
* [Getting started with ESP BLE Mesh](BLE-Mesh_Getting_Started_EN.md)
* [ESP BLE Mesh Feature List](BLE-Mesh_Feature_List_EN.md)
* [FAQs](BLE-Mesh_FAQs_EN.md)
* [Known Issues](BLE-Mesh_Known_Issues_EN.md)
### BLE Mesh Protocol Documentation
* [BLE Mesh Core Specification](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429633)
* [BLE Mesh Model Specification](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429634)
* [An Intro to Bluetooth Mesh Part 1](http://blog.bluetooth.com/an-intro-to-bluetooth-mesh-part1)
* [An Intro to Bluetooth Mesh Part 2](http://blog.bluetooth.com/an-intro-to-bluetooth-mesh-part2)
* [The Fundamental Concepts of Bluetooth Mesh Networking Part 1](http://blog.bluetooth.com/the-fundamental-concepts-of-bluetooth-mesh-networking-part-1)
* [The Fundamental Concepts of Bluetooth Mesh Networking, Part 2](http://blog.bluetooth.com/the-fundamental-concepts-of-bluetooth-mesh-networking-part-2)
* [Bluetooth Mesh Networking: Friendship](http://blog.bluetooth.com/bluetooth-mesh-networking-series-friendship)
* [Management of Devices in a Bluetooth Mesh Network](http://blog.bluetooth.com/management-of-devices-bluetooth-mesh-network)
* [Bluetooth Mesh Security Overview](http://blog.bluetooth.com/bluetooth-mesh-security-overview)
* [Provisioning a Bluetooth Mesh Network Part 1](http://blog.bluetooth.com/provisioning-a-bluetooth-mesh-network-part-1)
* [Provisioning a Bluetooth Mesh Network Part 2](http://blog.bluetooth.com/provisioning-a-bluetooth-mesh-network-part-2)

BIN
docs/_static/ble-mesh-config-complete.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 92 KiB

BIN
docs/_static/ble-mesh-device-power-on.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 372 KiB

BIN
docs/_static/ble-mesh-generic-onoff.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
docs/_static/ble-mesh-identify-provision.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 72 KiB

BIN
docs/_static/ble-mesh-initial-config-fail.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 106 KiB

BIN
docs/_static/ble-mesh-model-bind-appkey.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 141 KiB

BIN
docs/_static/ble-mesh-provision.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
docs/_static/ble-mesh-reconnect-initial-config.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 141 KiB

BIN
docs/_static/ble-mesh-reconnect-three.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 89 KiB

BIN
docs/_static/ble-mesh-scanner.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
docs/_static/ble-mesh-three-nodes-on.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 376 KiB

BIN
docs/_static/esp-ble-mesh-architecture.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 111 KiB

1
docs/_static/esp-ble-mesh-architecture.xml vendored Normal file
View file

@ -0,0 +1 @@
<mxfile modified="2019-09-22T00:58:06.366Z" host="www.draw.io" agent="Mozilla/5.0 (X11; Linux x86_64; rv:69.0) Gecko/20100101 Firefox/69.0" etag="zTkUVhOzP7skpqIPIslP" version="11.3.0" type="device" pages="1"><diagram id="3T7Fh-tElfW0GhIRTNz5" name="Page-1">5Vtbc6M2FP41fkwHJBDw6EucpJu4nthJZ/vSwSBsdjGiAl/SX1+BhS9I2bAdyck63pkNPhK37zs6Ojd3YH+5vaF+tnggIU46wAi3HTjoAGAayGZ/SsnLTuK4zk4wp3HIJx0Ek/hfXJ/Jpas4xPnJxIKQpIizU2FA0hQHxYnMp5RsTqdFJDm9a+bPsSCYBH4iSv+Mw2Kxk7q2cZDf4ni+qO9sGXxk6deTuSBf+CHZHIngdQf2KSHF7mi57eOkBK/GZXfe8JXR/YNRnBZtTliZsXs9+D15QPco+Tq9f/5r8fcVv8raT1b8hR9wvmCSismcP3nxUsNBySoNcXlFswN7m0Vc4EnmB+XohikAky2KZcKHI5IWnFH2bLC3xrSIGbTdJJ6nTFiQ8gTxPeqHYtPx9kjE3+sGkyUu6AubUo/WGHMlg5B/3xwoAy6XLY7o2pPjczWZ7699QJIdcDDlwI5GkfuYQ9LrdqNk++2P2/4ouYKOgKxaMH0OYsBgw7ScECdJnySEHQ9SkuJyDg34KZB9I+zacVFCZBmKcDdOcTcluDtIgrtn68JdVOhuliVM64qYpIr1+RjxDoChj90oYPK8oOQ7PhpBgYtnkR5d36vwMeZAgrmlC3IgQj6+65SPMGT/X6/Ld9WJe2SX/6S4Vx9+hSP57qOJD8f6zX5nRqzXrPoIFxtCv8fp/Be17DZqadmh7WkC1xbAHZbQVQam3jjZ33v/hZllnXqPzdDGjkzvPeRAHyliwDplwHKgyIAlYQBZmghAonZ/JMz1rYUGE9AxJJZGyoWrazGIXk43CHCefxQyNMCOjJag16GPctBdAfSnLCuxNqbUT/OM0OKS8XfNtmqPdKm9JzBwTzafhgEHtd0CdK2AOjtwRAB3bS4Ydtdqbe+Rqwt4Mb4aYr9YUfyr5AosIJgTAVNThimA2kAVI6ghjXEaalXiKIpAIA1XQzRDtiIltmDDdtR++THcsuAI6LLdJpQZbyYY70y4IshN98NAbqJ2kEOgC3IxIH3Eif9yifrtue+t32KAOqZkWz7zBNP1Raq4W6db31RxbXlHMRI6eCQPfurP8VJ5IkzIAZ9t14RAYsZluya0TF2Ii2HQAfE+xTwho1LXf5hzr5Qfo1eU3/FmhqKse1P5bUf0CqXKb2lzx8V46Asun/gRR7TKPH4CFmBLFrTtskAMiu6e2fenLPQL/Bk4sLy224AuowTE+Kji4I5Bva0WREDY+6nzfD4yG5asEnJeywTE0GpEQlwxsSRM+hmIgK7XmghdMS4Qoy5ek2LO6TrO2V6tvCp1PvfIdt92j4CsEG572qqyrxYBe5i9KosCdCTKzgd5szLoQTHKlVZdHV2BFxADr25YvX9eqfYeeK2AN5sSbOyGlsziuGAGkapUZcPieI6YVIP2OeMxIFYJb7rT6UWzYHktWJAGadpYEKPiHjsqCClKS7TLu12nmM7L1+gTWu7MkwwHccRbds7L03DosY+MJ8OwnWp/brSSGNVHj0kzDfDenSRADLJP92tjPHhSnPp/i6SZGYaRISPJNBzoYUVbemMxQUeypcsWk6fLl4VibNEBKGG37YXxmh3Oy8MbzJZTHNQj7E5Hg5L5p3S2PWnwVEtntDmvefbl64blSbJhdR52cdIerKspps4q/Fg5eCL451m+fE6dmq86n2PIqq3nZlWMmsa9q+7g+RIZaK4qhCSlFBn+nq5sDnzDo798Dhy3JQdmXVZVT4Loyavaxsp6WMz4+cRbWdPsnZdwg9xNlzC5xWP49Sm4iQa3WSHpJ+8nse4m8tdbeno2Q3ugyMO3G46DIUlYG5ocfCnY4gajuEj8P8EO/Xyxv5sC5IEjIC/b3s+KvZihqwv1ihX+5wr1A9TbFepVcyBU7Z22jSm6GJC0SvSudnmiyzf1Z/Wv1rP19204vHXWyy9X34zZfTj9R9I9/ogT7OcMZ2DwvkK1i0ABjKihxaYFZG2ZpkSPgYLqihRIMUszXO3AMziiugBVbSMEdF1p0+tZ0RW7G0bPEyaYFISWPx9WCujHLCEiIN0uFfU3sK+H30FXY0e/JofX/wE=</diagram></mxfile>

BIN
docs/_static/esp-ble-mesh-interface.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 54 KiB

1
docs/_static/esp-ble-mesh-interface.xml vendored Normal file
View file

@ -0,0 +1 @@
<mxfile modified="2019-09-06T07:49:40.158Z" host="www.draw.io" agent="Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Firefox/68.0" etag="BUdTiYyUVL7KduKo_ZSl" pages="1" version="11.2.5" type="device"><diagram id="csV9DYBobAVv9VLuABIz" name="Page-1">5V1Zd9o6EP41PJJjyfL2yJImadMebrO0yUuPgxVw6yDXmK2//spggW2pNngnzUssIQtpZr7RzGgkOvLgbX3lme70M7Gw04GSte7Iww6EQFIV+i+o2exqNN3YVUw82wobHSru7D+YvRnWLmwLz2MNfUIc33bjlWMym+GxH6szPY+s4s1eiRP/VtecYK7ibmw6fO032/Knu1odaof6a2xPpuybgRrO781kjcOZzKemRVaRKvmyIw88Qvzd09t6gJ2AeIwuu/c+/OXT/cA8PPOPecH89ji6sqeoD7Vln3gzMH/0u3DXy9J0FuGEw8H6G0YBjyxmFg46AR25v5raPr5zzXHw6YrynNZN/Tcn/PjVdpwBcYhHyzMyo436hDa2/YD9SKJF0xuHXJZpiZ9EOK8l9ny8jlSFk7rC5A373oY2YZ+ikMChhClhcXVgF9LDummEVToTMTMUkcm+6wMV6UNISDFRn/9D4x+uv9xcrdZfVeKB9Z9BV84mKraolIVF4vlTMiEz07k81PYPtbeEuCF5f2Lf34TkMxc+iRP/wCkpjbRzsvDGOGX8DGemN8F+SrtwWsFcUhnlYcf07WUcUSKqb1/teZ65iTRwiT3z55GeR0HFgf9Qj/MfAD2Og9Pa04fdCA78308lv0gATiR6ruvYY0oXMqMf3Job7BWEHpn5oWjAVP6fAC01TipV56GFBNBCJSDrCSs3t78kfwAfwca3Fqun0U0X5QBSHBU5YIXXtv89eP1CU8LiU9hb8DxcRwsbVpjR+UbfCspPrMegcHhvW2Iv5octPBK2oGzYFlKW/ArUv72kFZ/xfEr/9e8HZwMPgGrEx/Of62ul9+yPPj4PH34vDWx8WnRzrTSlAQRE0XEAy4kAkTIAEmEkCF78uXhz2QSpcVEIQkgAIRGdS4dQrpVPkeWY/CFDy1j59LT2hVe+yWLjgsX1qouk6ydp+fTxavXQ1ZpV2QYyIlIJLiQJHimWMZm8gMoJYsm+YoQ9m9IPe7XpdtSUbjduxtLzmzQD6PfNd8MjL0D3uzIozPwxebPH4TOP9G3Njuh6QUnJqbt0pMUFxTCyVvhtKSkae++wmJyIFFgtpnshGwBxNkAHqg4df9+ylzH5UX8vAn95i7bufMvUHm0AFHd9+JA+TYL/I48s7Tk1sAPbQeqyPukQt93uGpX7TfZs8revKWK8WLaHx1tXQR5SGQiMC24dLMGgUUDcoJGBxhk0hsCeAXIJBo1w9QDKORo0sgLjSkGCKI9SSK4pR+kFoeMkcunba9jsY2bMUNHKddHTSFRaKCwDs1U5ISLMQpETUgpoxV5I8WW/AdAWckLyI1Nk2bUXmYiZdAyZeobLgZS09tW4HI2uGXkNSRWgqABSTwVmyGDFS8axLkc7osBJwaQV1Qsa878bi0cCLSZthvFenNs0iWxa0rS4SoNKuZKWNvWyPaQvxMJR1+jFy99Xze5VFUM9AxcNSfEYXq0umlA0VU40e6MbjpZ0en6cYB6mbDJftg0C/RHijrZW+h1lSGsC1TcPyRcUHXsSUNfBr0FXAc3ssen0wmo/UJ/9ebDbPJvcb3VpF1XDBKjHA68AqBwTZAETYFU80EpRD1tgJKByuQzIdBxe3hWPkaFk8lipiMdCB0Bv1tbItfV50s5nSRs7QoAYAmNWROTS4+e5TAw5kaKgqOleVjJul2hfPKVB6JA26uUzo5Vt7BwrkbAhN18ggMJ2slq2BBZSOkzpNbZ9J+lH650ks6IBWd04RRMJPevcPk+aPJSsaHjNoBgxzaDKKN7FTiDDt9JUTLKjMCS772g3Y66jshwgg7NwYmkiPct0/e02z3mkiqgsTbSxVCrQInviaO0NDDmK4650IQEtD5jLU+xsGczU7KUjvhj7+e2OBKACv+F+6mHTKg1NZdnmSTQpBuLQBLRa0WScozGkxuGUZQ1VjSRB8kK7kCQ0kRpOcKojJ7VaHtfjiBWDN5+hMvLIOhgA/e+TMXFapyQRPEJJig5GVJadCuA5KsmmPEbmCWa7jFqr9CH4B5L0G+Byu8xHmY/69+mT5RH6GpSuydwvTSFW5YNpMq8Q603XB03vH58XVLRjFWJjMbTUcUewcnk3ohU7h2tACeQRxzmDqIVm1Bi1ECKm4XCk1oAFkfd8S0oSWSaCQDv2QZIHVhQtfR8EqUpa+8L7IOJDDsWt2toOOeSLup0kvjkOMhSS1OZOM6YM+29RtdHwIYiqfS9N0281xMQzLZtSOHHwnlUPI5kps0B6OvFz+h0ov27/aL1lzqf7YVSwgux3KuuI1ImTkxu2uWAOmwvEAHhaul7ZS8ixQbqW5CsnVgSUsYLIKHnyoIaddNiwx/yPSCRshUQmczVQRm4H0tS09oUlUhk6v66d3n9DRXq5//Hyg+jjS0aqVpjZ+SQySyBLFbd2HcVNG3W6YfK1ZMOkbGuCC2mLrIl6Q9oKR9e7Qe8LR8Z3lRop6/JFfFlVZT4woNaZHAn4GEtv+Pi+2QCRnsmEWjNUWUpJhAlXvfv7980FpGZzoV4o8KlS758LSjK/qkYuiA+uc0z4gv0V8X51yk5RSz/md4qrHs/wQ4KTJaCqUw1CGkKOhrdktU3yu/fM2dylNubZUFPWm6Ymfyvhg+ueKzWVpqnJ29O98RjP5+dDQtg0CVk6SISGN9Rkkx5cy/Rx6wgoJy9HQZAjoMj3qI5+PKI/4WDAX/Grt3Xr2k5BjRfBeiko8IqxOQ5u5Gw56RBoWPjkhndi84TRpQtJjSe8shPztdyyIBZB0cm0Vt3YJWZ/w1mvQI+dC6J8NI6Vgfy3TdZy80GqlLTkXj9Y/IaVare582kHeFJi01FcF5JPsLd9FlwvfsahWq7nys6JrwelbBscrehbvHHK7s853HKS+HWBjFvVE+2ruX9HEOr6EMgbu1V9+3MU89YZc8mkCMiSWKKuGBBYc2Xc4aE4X7TpoDeaf0M/HLP3uvj0CJjMnZcxJ6OYMRfc7avnMebyY5pZ1+013oTcbjjdAOnRK/r2bCvfdmvGVmNC0ZZVu/g537NftaP5lafnJx4N/XqW82IhdYlbMXcZAB8e8cwiXnsXTc7AEC2aLLmv7EVTjKziPnCNyDpbL6h8fVqOQaymG8Qyk09x+4py0aWWi6QkybG4jaYeHbc5SSzLvaxFIKppIt2SlZ/fgmY/z/fZdN3tVYpFdHzVqeKQpYVneUVQP5mAtHj44b0d+A4/Xyhf/g8=</diagram></mxfile>

385
docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst Normal file
View file

@ -0,0 +1,385 @@
ESP-BLE-MESH Architecture
=========================
This document introduces ESP-BLE-MESH architecture overview, ESP-BLE-MESH architecture implementation as well as ESP-BLE-MESH auxiliary routines.
- ESP-BLE-MESH Architecture Overview
- Describes the five major parts of ESP-BLE-MESH architecture and the functionality of each part.
- ESP-BLE-MESH Architecture Implementation
- Describes the basic functions of ESP-BLE-MESH files, the correspondence between files and ESP-BLE-MESH architecture, and the interface for calling among files.
- ESP-BLE-MESH Auxiliary Routines
- Describe the auxiliary routines of ESP-BLE-MESH, such as Mesh network management, Mesh features, etc.
1. ESP-BLE-MESH Architecture Overview
-------------------------------------
Currently ESP-BLE-MESH has implemented most functions of Mesh Profile and all the Client Models defined in Mesh Model specification. Those missing functions/models are under development and will be provided soon. ESP-BLE-MESH architecture has been granted the official Bluetooth `certification <https://launchstudio.bluetooth.com/ListingDetails/76255>`__.
.. figure:: ../../../_static/esp-ble-mesh-architecture.png
:align: center
Figure 1.1 ESP-BLE-MESH Architecture Diagram
ESP-BLE-MESH architecture includes five key parts:
- ``Mesh Protocol Stack``
- ``Mesh Networking`` is responsible for processing of messages of ESP-BLE-MESH nodes.
- ``Mesh Provisioning`` is responsible for provisioning flow of ESP-BLE-MESH devices.
- ``Mesh Models`` is responsible for the implementation of SIG-defined models.
- ``Network Management``
- Implements several network management procedures, including node removal procedure, IV Index recovery procedure, etc.
- ``Features``
- Include several ESP-BLE-MESH features, e.g. Low Power feature, Friend feature, Relay feature, etc.
- ``Mesh Bearer Layer``
- Includes ``Advertising Bearer`` and ``GATT Bearer``. The bearer layer is crucial to ESP-BLE-MESH protocol stack which is built on Bluetooth Low-Energy technology, because the protocol stack must make use of the bearer layer to transmit data via the BLE advertising channel and connection channel.
- ``Applications``
- Based on ESP-BLE-MESH protocol stack and ``Mesh Models``.
- By calling API and handling Event, ``Applications`` interact with ``Mesh Networking`` and ``Mesh Provisioning`` in ESP-BLE-MESH protocol stack, as well as a series of Models provided by ``Mesh Models``.
1.1 Mesh Protocol Stack
-----------------------
1.1.1 Mesh Networking
^^^^^^^^^^^^^^^^^^^^^
``Mesh Networking`` in the protocol stack architecture implements the following functions:
- The communication between nodes in the Mesh network.
- Encryption and decryption of messages in the Mesh network.
- Management of Mesh network resources (Network Key, IV Index, etc.).
- Segmentation and reassembly of Mesh network messages.
- Model mapping of messages between different models.
- For more features, please see :doc:`ble-mesh-feature-list`.
The implementation of ``Mesh Networking`` functions is based on hierarchy structure. Functions of each layer are shown in Table 1.1:
.. list-table:: Table 1.1 Mesh Networking Architecture Description
:widths: 40 150
:header-rows: 1
* - Layer
- Function
* - Access Layer
- Access Layer not only defines the format of application data, but also defines and controls the encryption and decryption of the data packets conducted by Upper Transport Layer.
* - Upper Transport Layer
- Upper Transport Layer encrypts, decrypts, and authenticates application data to and from the access layer; it also handles special messages called "transport control messages", including messages related to "friendship" and heartbeat messages.
* - Lower Transport Layer
- Lower Transport Layer handles segmentation and reassembly of PDU.
* - Network Layer
- Network Layer defines the address type and format of the network messages, and implements the relay function of the device.
1.1.2 Mesh Provisioning
^^^^^^^^^^^^^^^^^^^^^^^
``Mesh Provisioning`` in the protocol stack architecture implements the following functions:
- Provisioning of unprovisioned devices.
- Allocation of Mesh network resources (unicast address, IV Index, NetKey, etc.).
- Four authentication methods support during provisioning.
- For more features, please see :doc:`ble-mesh-feature-list`.
The implementation of ``Mesh Provisioning`` functions is based on hierarchy structure. Functions of each layer are shown in Table 1.2:
.. list-table:: Table 1.2 Mesh Provisioning Architecture Description
:widths: 40 150
:header-rows: 1
* - Layer
- Function
* - Provisioning PDUs
- Provisioning PDUs from different layers are handled using provisioning protocol.
* - Generic Provisioning PDU/Proxy PDU
- The Provisioning PDUs are transmitted to an unprovisioned device using a Generic Provisioning layer or Proxy protocol layer.
* - PB-ADV/PB-GATT
- These layers define how the Provisioning PDUs are transmitted as transactions that can be segmented and reassembled.
* - Advertising/Provisioning Service
- The provisioning bearers define how sessions are established such that the transactions from the generic provisioning layer can be delivered to a single device.
1.1.3 Mesh Models
^^^^^^^^^^^^^^^^^
``Mesh Models`` in the protocol stack architecture implements the following functions:
- Configuration Client/Server Models
- Health Client/Server Models
- Generic Client/Server Models
- Sensor Client/Server Models
- Time and Scenes Client/Server Models
- Lighting Client/Server Models
Functions of each layer are shown in Table 1.3:
.. list-table:: Table 1.3 Mesh Models Architecture Description
:widths: 40 150
:header-rows: 1
* - Layer
- Function
* - Model Layer
- Model Layer implements models used to standardize the operation of typical user scenarios, including Generic Client/Server Models, Sensor Client/Server Models, Time and Scenes Client/Server Models, Lighting Client/Server Models and several vendor models.
* - Foundation Model Layer
- Foundation Model Layer implements models related to ESP-BLE-MESH configuration, management, self diagnosis, etc.
1.2 Mesh Network Management
---------------------------
``Network Management`` implements the following functions:
- Node removal procedure is used to remove a node from the network.
- IV Index recovery procedure is used to recover a node's IV Index.
- IV update procedure is used to update the nodes' IV Index.
- Key refresh procedure is used to update the nodes' NetKey, AppKey, etc.
- Network creation procedure is used to create a mesh network.
- NVS storage is used to store node's networking information.
1.3 Mesh Features
-----------------
``Features`` includes the following options:
- Low Power feature is used to reduce node's power consumption.
- Friend feature is used to store messages for Low Power nodes.
- Relay feature is used to relay/forward Network PDUs received by a node over the advertising bearer.
- Proxy Server/Client are two node roles in proxy protocol, which enable nodes to send and receive Network PDUs, mesh beacons, proxy configuration messages and Provisioning PDUs over a connection-oriented bearer.
1.4 Mesh Bearer Layer
---------------------
``Bearers`` in the protocol stack architecture are responsible for passing of data between ESP-BLE-MESH protocol stack and Bluetooth Low Energy Core.
``Bearers`` can be taken as a carrier layer based on Bluetooth Low Energy Core, which implements the function of receiving and transmitting data for the ESP-BLE-MESH protocol stack.
.. list-table:: Table 1.3 Mesh Bearers Description
:widths: 40 150
:header-rows: 1
* - Layer
- Function
* - GATT Bearer
- The GATT Bearer uses the Proxy protocol to transmit and receive ``Proxy PDUs`` between two devices over a GATT connection.
* - Advertising Bearer
- When using the Advertising Bearer, a mesh packet shall be sent in the Advertising Data of a ``Bluetooth Low Energy advertising PDU`` using the Mesh Message AD Type.
1.5 Mesh Applications
---------------------
The ``Applications`` in the protocol stack architecture implement the corresponding functions by calling the API provided by the ESP-BLE-MESH protocol stack and processing the Event reported by the protocol stack. There are some common applications, such as gateway, lighting and etc.
Interaction between application layer（``Applications``）and ``API / Event``
- Application layer calls API
- Call the provisioning-related API for provisioning.
- Call the model-related API to send messages.
- Call the device-attributes-related API to get local information about the device.
- Application layer processes Event
The application layer is designed based on events, which take parameters to the application layer. Events are mainly divided into two categories.
- The events completed by calling API.
- Such as nodes sending messages.
- The events that the protocol stack actively reports to the application layer.
- The Event that the protocol stack actively reports.
- The Event that Model actively reports.
- The event is reported by the callback function registered by the application layer, and the callback function also contains the corresponding processing of the event.
Interaction between ``API / Event`` and ESP-BLE-MESH protocol stack
- API used by user mainly calls functions provided by ``Mesh Networking``, ``Mesh Provisioning`` and ``Mesh Models``.
- The interaction between ``API / Event`` and the protocol stack does not operate across the hierarchy of the protocol stack. For example, API does not call functions related to ``Network Layer``.
2. ESP-BLE-MESH Architecture Implementation
-------------------------------------------
The design and implementation of ESP-BLE-MESH architecture is based on layers and modules. In details, Section 2.1 (Mesh Networking Implementation), Section 2.2 (Mesh Provisioning Implementation) and Section 2.3 (Mesh Bearers Implementation) are based on layers, and Section 2.4 (Mesh Models Implementation) is on modules.
- **Layer-based Approach**: With Layer-based approach, the architecture is designed according to the layers specified in the Mesh Profile Specification. Each layer has its unique files which include APIs of this layer and etc. The specific design is shown in Figure 2.1.
- **Module-based Approach**: Every file implements an independent function that can be called by other programs.
.. figure:: ../../../_static/esp-ble-mesh-interface.png
:align: center
Figure 2.1 ESP-BLE-MESH Architecture Implementation Diagram
The design of ESP-BLE-MESH architecture uses layer-based approach. The sequence of layers which data packets are processed through is fixed, i.e., the processing of packets will form a ``message flow``. Thus, we could see flows of messages from the Protocol Stack Interface Diagram in Figure 2.1.
2.1 Mesh Protocol Stack Implementation
--------------------------------------
2.1.1 Mesh Networking Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The list of files and the functions implemented in each file in ``Mesh Networking`` are shown in Table 2.1:
.. list-table:: Table 2.1 Mesh Networking File Description
:widths: 40 150
:header-rows: 1
* - File
- Functionality
* - :component_file:`access.c <bt/esp_ble_mesh/mesh_core/access.c>`
- ESP-BLE-MESH Access Layer
* - :component_file:`transport.c <bt/esp_ble_mesh/mesh_core/transport.c>`
- ESP-BLE-MESH Lower/Upper Transport Layer
* - :component_file:`net.c <bt/esp_ble_mesh/mesh_core/net.c>`
- ESP-BLE-MESH Network Layer
* - :component_file:`adv.c <bt/esp_ble_mesh/mesh_core/adv.c>`
- A task used to send ESP-BLE-MESH advertising packets, a callback used to handle received advertising packets and APIs used to allocate adv buffers
2.1.2 Mesh Provisioning Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The implementation of Mesh Provisioning is divided into two chunks due to the Node/Provisioner coexistence.
Specific files that provide implementation of provisioning of Node are shown in Table 2.2:
.. list-table:: Table 2.2 Mesh Provisioning (Node) File Description
:widths: 40 150
:header-rows: 1
* - File
- Functionality
* - :component_file:`prov.c <bt/esp_ble_mesh/mesh_core/prov.c>`
- ESP-BLE-MESH Node provisioning (PB-ADV & PB-GATT)
* - :component_file:`proxy.c <bt/esp_ble_mesh/mesh_core/proxy.c>`
- ESP-BLE-MESH Proxy Server related functionalities
* - :component_file:`beacon.c <bt/esp_ble_mesh/mesh_core/beacon.c>`
- APIs used to handle ESP-BLE-MESH Beacons
Specific files that implement functions of Provisioner are shown in Table 2.3:
.. list-table:: Table 2.3 Mesh Provisioning (Provisioner) File Description
:widths: 40 150
:header-rows: 1
* - File
- Functionality
* - :component_file:`provisioner_prov.c <bt/esp_ble_mesh/mesh_core/provisioner_prov.c>`
- ESP-BLE-MESH Provisioner provisioning (PB-ADV & PB-GATT)
* - :component_file:`provisioner_proxy.c <bt/esp_ble_mesh/mesh_core/provisioner_proxy.c>`
- ESP-BLE-MESH Proxy Client related functionalities
* - :component_file:`provisioner_beacon.c <bt/esp_ble_mesh/mesh_core/provisioner_beacon.c>`
- ESP-BLE-MESH Provisioner receives Unprovisioned Device Beacon
2.1.3 Mesh Models Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Mesh Models are used to implement the specific functions of model in nodes. Server model is used to maintain node status. Client model is used to obtain and modify node state.
.. list-table:: Table 2.4 Mesh Models File Description
:widths: 40 150
:header-rows: 1
* - File
- Functionality
* - :component_file:`cfg_cli.c <bt/esp_ble_mesh/mesh_core/cfg_cli.c>`
- Send Configuration Client messages and receive corresponding response messages
* - :component_file:`cfg_srv.c <bt/esp_ble_mesh/mesh_core/cfg_srv.c>`
- Receive Configuration Client messages and send proper response messages
* - :component_file:`health_cli.c <bt/esp_ble_mesh/mesh_core/health_cli.c>`
- Send Health Client messages and receive corresponding response messages
* - :component_file:`health_srv.c <bt/esp_ble_mesh/mesh_core/health_srv.c>`
- Receive Health Client messages and send proper response messages
* - :component_file:`client_common.c <bt/esp_ble_mesh/mesh_models/client/client_common.c>`
- ESP-BLE-MESH model related operations
* - :component_file:`generic_client.c <bt/esp_ble_mesh/mesh_models/client/generic_client.c>`
- Send ESP-BLE-MESH Generic Client messages and receive corresponding response messages
* - :component_file:`lighting_client.c <bt/esp_ble_mesh/mesh_models/client/lighting_client.c>`
- Send ESP-BLE-MESH Lighting Client messages and receive corresponding response messages
* - :component_file:`sensor_client.c <bt/esp_ble_mesh/mesh_models/client/sensor_client.c>`
- Send ESP-BLE-MESH Sensor Client messages and receive corresponding response messages
* - :component_file:`time_scene_client.c <bt/esp_ble_mesh/mesh_models/client/time_scene_client.c>`
- Send ESP-BLE-MESH Time Scene Client messages and receive corresponding response messages
2.2 Mesh Bearers Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Portability is fully considered in the implementation of Mesh Bearers. When the ESP-BLE-MESH protocol stack is being ported to other platforms, users only need to modify :component_file:`mesh_bearer_adapt.c <bt/esp_ble_mesh/mesh_core/mesh_bearer_adapt.c>`.
.. list-table:: Table 2.5 Mesh Bearers File Description
:widths: 40 150
:header-rows: 1
* - File
- Functionality
* - :component_file:`mesh_bearer_adapt.c <bt/esp_ble_mesh/mesh_core/mesh_bearer_adapt.c>`
- ESP-BLE-MESH Bearer Layer adapter，This file provides the interfaces used to receive and send ESP-BLE-MESH ADV & GATT related packets.
.. note::
:component_file:`mesh_bearer_adapt.c <bt/esp_ble_mesh/mesh_core/mesh_bearer_adapt.c>` is the implementation of ``Advertising Bearer`` and ``GATT Bearer`` in Mesh Networking framework.
2.3 Mesh Applications Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We have provided a series of application examples for customer development, and users can develop products based on :ref:`esp-ble-mesh-examples`.
3. Auxiliary Routine
---------------------
Auxiliary routine refers to optional functions in the ESP-BLE-MESH protocol stack. The design of the auxiliary routine generally implement the truncation of code through :ref:`CONFIG_BLE_MESH`.
3.1 Features
^^^^^^^^^^^^
- Low Power
- Friend
- Relay
- Proxy Client/Server
3.2 Network Management
^^^^^^^^^^^^^^^^^^^^^^
- Node Removal procedure
- IV Index Recovery procedure
- IV Update procedure
- Key Refresh procedure
- Network Creation procedure
- NVS Storage
3.3 Auxiliary Routine Implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When adopting the design of independent module, the two main factors should be considered:
- The module can not be implemented hierarchically, and it can be completely independent, which means it does not rely on the implementation of other modules.
- The functions in the module will be used repeatedly, so it is reasonable to design it into a module. Independent module is shown in Table 3.1:
.. list-table:: Table 3.1 Module File Description
:widths: 40 150
:header-rows: 1
* - File
- Functionality
* - :component_file:`lpn.c <bt/esp_ble_mesh/mesh_core/lpn.c>`
- ESP-BLE-MESH Low Power functionality
* - :component_file:`friend.c <bt/esp_ble_mesh/mesh_core/friend.c>`
- ESP-BLE-MESH Friend functionality
* - :component_file:`net.c <bt/esp_ble_mesh/mesh_core/net.c>`
- ESP-BLE-MESH Relay feature, network creation, IV Update procedure, IV Index recovery procedure, Key Refresh procedure related functionalities
* - :component_file:`proxy.c <bt/esp_ble_mesh/mesh_core/proxy.c>`
- ESP-BLE-MESH Proxy Server related functionalities
* - :component_file:`provisioner_proxy.c <bt/esp_ble_mesh/mesh_core/provisioner_proxy.c>`
- ESP-BLE-MESH Proxy Client related functionalities
* - :component_file:`settings.c <bt/esp_ble_mesh/mesh_core/settings.c>`
- ESP-BLE-MESH Node NVS storage functionality
* - :component_file:`mesh_main.c <bt/esp_ble_mesh/mesh_core/mesh_main.c>`
- ESP-BLE-MESH node removal related functionality

663
docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst Normal file
View file

@ -0,0 +1,663 @@
ESP-BLE-MESH FAQ
================
This document provides a summary of frequently asked questions about developing with ESP-BLE-MESH, and is divided into seven sections:
* :ref:`ble-mesh-faq-provisioner-development`
* :ref:`ble-mesh-faq-node-development`
* :ref:`ble-mesh-faq-ble-mesh-and-wi-fi-coexistence`
* :ref:`ble-mesh-faq-fast-provisioning`
* :ref:`ble-mesh-faq-log-help`
* :ref:`ble-mesh-faq-example-help`
* :ref:`ble-mesh-faq-others`
Users could refer to the sections for quick answer to their questions. This document will be updated based on the feedback collected via various channels.
.. _ble-mesh-faq-provisioner-development:
1. Provisioner Development
--------------------------
Generally, 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.
1.1 What is the flow for an unprovisioned device to join ESP-BLE-MESH network?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are two phases for a device to join ESP-BLE-MESH network via a Provisioner, namely, provisioning and configuration.
- 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.
- 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.
1.2 If a Provisioner wants to change states of a node, what requirements should be met for a Provisioner?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Client model that corresponds to server model of the node is required.
- NetKey and AppKey used to encrypt messages shall be owned by both the node and the Provisioner.
- The address owned by the node shall be known, which could be its unicast address or subscription address.
1.3 How can NetKey and AppKey be used?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 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.
- 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.
1.4 How to generate a NetKey or AppKey for Provisioner? Can we use a fixed NetKey or AppKey?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 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.
- 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.
1.5 Is the unicast address of Provisioner fixed?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
1.6 Can the address of Provisioner serve as destination address of the node-reporting-status message？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
Subscription address can also be used. Provisioner subscribes to a group address or virtual address, and nodes send messages to the subscription address.
1.7 Is the unicast address of the node that is firstly provisioned by Provisioner to ESP-BLE-MESH network fixed？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
1.8 Is the unicast address of the node that mobile App firstly provisioned fixed?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The App will decide the unicast address, and currently most of them are fixed.
1.9 How to know which unprovisioned device is the Provisioner that is provisioning currently?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
1.10 How many ways to authenticate the devices during provisioning? Which way was used in the :example:`provided examples <bluetooth/esp_ble_mesh>`?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are four authentication methods, i.e. No OOB, Static OOB, Output OOB and Input OOB. In the provided examples, No OOB is used.
1.11 What information can be carried by the advertising packets of the unprovisioned device before provisioning into the network?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Device UUID
- OOB Info
- URL Hash (optional)
1.12 Can such information be used for device identification?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For example, each unprovisioned device contains a unique Device UUID, which can be used for device identification.
1.13 How is the unicast address assigned when the node provisioned by Provisioner contains multiple elements?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 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.
- 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.
1.14 How can Provisioner get and parse the :ref:`Composition Data <ble-mesh-terminology-composition>` of nodes through Configuration Client Model?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 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.
- Users can refer to the following code to parse the Composition Data:
.. code:: c
#include <stdio.h>
#include <string.h>
#include <stdint.h>
//test date: 0C001A0001000800030000010501000000800100001003103F002A00
//0C00 1A00 0100 0800 0300 0001 05 01 0000 0080 0100 0010 0310 3F002A00
// CID is 0x000C
// PID is 0x001A
// VID is 0x0001
// CRPL is 0x0008
// Features is 0x0003 – Relay and Friend features.
// Loc is “front” – 0x0100
// NumS is 5
// NumV is 1
// The Bluetooth SIG Models supported are: 0x0000, 0x8000, 0x0001, 0x1000, 0x1003
// The Vendor Models supported are: Company Identifier 0x003F and Model Identifier 0x002A
typedef struct {
int16_t cid;
int16_t pid;
int16_t vid;
int16_t crpl;
int16_t features;
int16_t all_models;
uint8_t sig_models;
uint8_t vnd_models;
} esp_ble_mesh_composition_head;
typedef struct {
uint16_t model_id;
uint16_t vendor_id;
} tsModel;
typedef struct {
// reserve space for up to 20 SIG models
uint16_t SIG_models[20];
uint8_t numSIGModels;
// reserve space for up to 4 vendor models
tsModel Vendor_models[4];
uint8_t numVendorModels;
} esp_ble_mesh_composition_decode;
int decode_comp_data(esp_ble_mesh_composition_head *head, esp_ble_mesh_composition_decode *data, uint8_t *mystr, int size)
{
int pos_sig_base;
int pos_vnd_base;
int i;
memcpy(head, mystr, sizeof(*head));
if(size < sizeof(*head) + head->sig_models * 2 + head->vnd_models * 4) {
return -1;
}
pos_sig_base = sizeof(*head) - 1;
for(i = 1; i < head->sig_models * 2; i = i + 2) {
data->SIG_models[i/2] = mystr[i + pos_sig_base] | (mystr[i + pos_sig_base + 1] << 8);
printf("%d: %4.4x\n", i/2, data->SIG_models[i/2]);
}
pos_vnd_base = head->sig_models * 2 + pos_sig_base;
for(i = 1; i < head->vnd_models * 2; i = i + 2) {
data->Vendor_models[i/2].model_id = mystr[i + pos_vnd_base] | (mystr[i + pos_vnd_base + 1] << 8);
printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].model_id);
data->Vendor_models[i/2].vendor_id = mystr[i + pos_vnd_base + 2] | (mystr[i + pos_vnd_base + 3] << 8);
printf("%d: %4.4x\n", i/2, data->Vendor_models[i/2].vendor_id);
}
return 0;
}
void app_main(void)
{
esp_ble_mesh_composition_head head = {0};
esp_ble_mesh_composition_decode data = {0};
uint8_t mystr[] = { 0x0C, 0x00, 0x1A, 0x00,
0x01, 0x00, 0x08, 0x00,
0x03, 0x00, 0x00, 0x01,
0x05, 0x01, 0x00, 0x00,
0x00, 0x80, 0x01, 0x00,
0x00, 0x10, 0x03, 0x10,
0x3F, 0x00, 0x2A, 0x00};
int ret;
ret = decode_comp_data(&head, &data, mystr, sizeof(mystr));
if (ret == -1) {
printf("decode_comp_data error");
}
}
1.15 How can Provisioner further configure nodes through obtained Composition Data?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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`.
- Add AppKey to nodes with :code:`app_key_add` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly.
- 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.
- 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.
1.16 Can nodes add corresponding configurations for themselves?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This method can be used in special cases like testing period.
- Here is an example to show nodes add new group addresses for their models.
.. code:: c
esp_err_t example_add_fast_prov_group_address(uint16_t model_id, uint16_t group_addr)
{
const esp_ble_mesh_comp_t *comp = NULL;
esp_ble_mesh_elem_t *element = NULL;
esp_ble_mesh_model_t *model = NULL;
int i, j;
if (!ESP_BLE_MESH_ADDR_IS_GROUP(group_addr)) {
return ESP_ERR_INVALID_ARG;
}
comp = esp_ble_mesh_get_composition_data();
if (!comp) {
return ESP_FAIL;
}
for (i = 0; i < comp->element_count; i++) {
element = &comp->elements[i];
model = esp_ble_mesh_find_sig_model(element, model_id);
if (!model) {
continue;
}
for (j = 0; j < ARRAY_SIZE(model->groups); j++) {
if (model->groups[j] == group_addr) {
break;
}
}
if (j != ARRAY_SIZE(model->groups)) {
ESP_LOGW(TAG, "%s: Group address already exists, element index: %d", __func__, i);
continue;
}
for (j = 0; j < ARRAY_SIZE(model->groups); j++) {
if (model->groups[j] == ESP_BLE_MESH_ADDR_UNASSIGNED) {
model->groups[j] = group_addr;
break;
}
}
if (j == ARRAY_SIZE(model->groups)) {
ESP_LOGE(TAG, "%s: Model is full of group addresses, element index: %d", __func__, i);
}
}
return ESP_OK;
}
.. note::
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.
1.17 How does Provisioner control nodes by grouping?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
- 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.
- 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.
1.18 How does Provisioner add nodes to multiple subnets?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
1.19 How does Provisioner know if a node in the mesh network is offline?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
There is no connection between nodes and nodes in the ESP-BLE-MESH network. They communicate with each other through advertising channels.
An example is given here to show how to detect a node is offline by Provisioner.
- 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.
.. note::
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.
1.20 What operations should be performed when Provisioner removes nodes from the network?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Usually when Provisioner tries to remove node from the mesh network, the procedure includes three main steps:
- Firstly, Provisioner adds the node that need to be removed to the "blacklist".
- Secondly, Provisioner performs the :ref:`Key Refresh procedure <ble-mesh-terminology-network-management>`.
- Lastly, the node performs node reset procedure, and switches itself to an unprovisioned device.
1.21 In the Key Refresh procedure, how does Provisioner update the Netkey owned by nodes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 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.
- 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.
1.22 How does Provisioner manage nodes in the mesh network?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
1.23 What does Provisioner need when trying to control the server model of nodes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Provisioner must include corresponding client model before controlling the server model of nodes.
Provisioner shall add its local NetKey and AppKey.
- Provisioner add NetKey by calling the API :cpp:func:`esp_ble_mesh_provisioner_add_local_net_key`.
- Provisioner add AppKey by calling the API :cpp:func:`esp_ble_mesh_provisioner_add_local_app_key`.
Provisioner shall configure its own client model.
- Provisioner bind AppKey to its own client model by calling the API :cpp:func:`esp_ble_mesh_provisioner_bind_app_key_to_local_model`.
1.24 How does Provisoner control the server model of nodes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
- Configuration Client Model
- 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.
- 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.
- Health Client Model
- 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.
- 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.
- Generic Client Models
- 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.
- 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.
- Lighting Client Models
- 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.
- 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.
- Sensor Client Models
- 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.
- 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.
- Time and Scenes Client Models
- 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.
- 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.
.. _ble-mesh-faq-node-development:
2. Node Development
-------------------
2.1 What kind of models are included by nodes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- In ESP-BLE-MESH, nodes are all composed of a series of models with each model implements some functions of the node.
- Model has two types, client model and server model. Client model can get and set the states of server model.
- 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.
2.2 Is the format of messages corresponding to each model fixed?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Messages, which consist of opcode and payload, are divided by opcode.
- The type and the format of the messages corresponding to models are both fixed, which means the messages transmitted between models are fixed.
2.3 Which functions can be used to send messages with the models of nodes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- For client models, users can use the API :cpp:func:`esp_ble_mesh_client_model_send_msg` to send messages.
- For server models, users can use the API :cpp:func:`esp_ble_mesh_server_model_send_msg` to send messages.
- For publication, users call the API :cpp:func:`esp_ble_mesh_model_publish` to publish messages.
2.4 How to achieve the transmission of messages without packet loss?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
.. note::
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**.
2.5 How to send unacknowledged messages?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
For server models, the messages sent by using the API :cpp:func:`esp_ble_mesh_server_model_send_msg` are always unacknowledged messages.
2.6 How to add subscription address to models?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Subscription address can be added through Configuration Client Model.
2.7 What is the difference between messages sent and published by models?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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.
2.8 How many bytes can be carried when sending unsegmented messages?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
2.9 When should the :ref:`Relay <ble-mesh-terminology-features>` feature of nodes be enabled?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Users can enable the Relay feature of all nodes when nodes detected in the mesh network are sparse.
For dense mesh network, users can choose to just enable the Relay feature of several nodes.
And users can enable the Relay feature by default if the mesh network size is unknown.
2.10 When should the :ref:`Proxy <ble-mesh-terminology-features>` feature of node be enabled?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
2.11 How to use the Proxy filter?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
2.12 When a message can be relayed by a Relay node?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If a message need to be relayed, the following conditions should be met.
- The message is in the mesh network.
- The message is not sent to the unicast address of the node.
- The value of TTL in the message is greater than 1.
2.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?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Relay nodes will forward segments when one of them are received rather than keeping waiting until all the segments are received.
2.14 What is the principle of reducing power consumption using :ref:`Low Power <ble-mesh-terminology-features>` feature?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 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.
- 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.
- 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.
2.15 How to continue the communication on the network after powering-down and powering-up again?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Enable the configuration :code:`Store ESP-BLE-MESH Node configuration persistently` in `menuconfig`.
2.16 How to send out the self-test results of nodes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is recommended that nodes can publish its self-test results periodically through Health Server Model.
2.17 How to transmit information between nodes?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
- 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.
- 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.
2.18 Is gateway a must for nodes communication?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 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.
- Situation 2: if users want to control the nodes remotely, for example turn on some nodes before getting home, then a gateway is needed.
2.19 When will the IV Update procedure be performed?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
IV Update procedure would be performed once sequence number of messages sent detected by the bottom layer of node reached a critical value.
2.20 How to perform IV Update procedure?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Nodes can perform IV Update procedure with Secure Network Beacon.
.. _ble-mesh-faq-ble-mesh-and-wi-fi-coexistence:
3. ESP-BLE-MESH and Wi-Fi Coexistence
-------------------------------------
3.1 Which modes does Wi-Fi support when it coexists with ESP-BLE-MESH?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Currently only Wi-Fi station mode supports the coexistence.
3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `ESP32-DevKitC <../../hw-reference/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.
And some configurations in menuconfig shall be enabled to support PSRAM.
- :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...`
- :code:`Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the memory from the PSRAM`
- :code:`Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation in BT/BLE stack.`
- :code:`Bluetooth --> Bluetooth controller --> BLE full scan feature supported.`
- :code:`Wi-Fi --> Software controls Wi-Fi/Bluetooth coexistence --> Wi-Fi`
.. _ble-mesh-faq-fast-provisioning:
4. Fast Provisioning
--------------------
4.1 Why is fast provisioning needed?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
4.2 Why EspBleMesh App would wait for a long time or keep waiting during fast provisioning?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
4.3 Why is the number of node addresses displayed in the App is more than that of existing node addresses?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
4.4 What is the usage of the **count** value which was input in EspBleMesh App?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
4.5 When will Configuration Client Model of the node running :example:`ble_mesh_fast_prov_server <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server>` example start to work?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configuration Client Model will start to work after the Temporary Provisioner functionality is enabled.
4.6 Will the Temporary Provisioner functionality be enabled all the time?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After the nodes receive messages used to turn on/off lights, all the nodes will disable its Temporary Provisioner functionality and become nodes.
.. _ble-mesh-faq-log-help:
5. Log Help
-----------
You can find meaning of errors or warnings when they appear at the bottom of ESP-BLE-MESH stack.
5.1 What is the meaning of warning :code:`ran out of retransmit attempts`?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
5.2 What is the meaning of warning :code:`Duplicate found in Network Message Cache`?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
5.3 What is the meaning of warning :code:`Incomplete timer expired`?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
5.4 What is the meaning of warning :code:`No matching TX context for ack`?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
5.5 What is the meaning of warning :code:`No free slots for new incoming segmented messages`?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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`.
5.6 What is the meaning of error :code:`Model not bound to Appkey 0x0000`？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
5.7 What is the meaning of error :code:`Busy sending message to DST xxxx`?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
.. _ble-mesh-faq-example-help:
6. Example Help
---------------
6.1 How are the ESP-BLE-MESH callback functions classified?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- The API :cpp:func:`esp_ble_mesh_register_prov_callback` is used to register callback function used to handle provisioning and networking related events.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
.. _ble-mesh-faq-others:
7. Others
---------
7.1 How to print the message context?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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`.
7.2 Which API can be used to restart ESP32?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The API :cpp:func:`esp_restart`.
7.3 How to monitor the remaining space of the stack of a task?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The API :cpp:func:`vTaskList` can be used to print the remaining space of the task stack periodically.
7.4 How to change the level of log without changing the menuconfig output level?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The API :cpp:func:`esp_log_level_set` can be used to change the log output level rather than using menuconfig to change it.

116
docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst Normal file
View file

@ -0,0 +1,116 @@
Espressif ESP-BLE-MESH Feature List
===================================
Supported Features
------------------
Mesh Core
"""""""""
* Provisioning: Node Role
* PB-ADV and PB-GATT
* OOB Authentication
* Provisioning: Provisioner Role
* PB-ADV and PB-GATT
* OOB Authentication
* Networking
* Relay
* Segmentation and Reassembly
* Key Refresh Procedure
* IV Update Procedure
* Friend
* Low Power
* Proxy
* Multiple Client Models Run Simultaneously
* Support multiple client models send packets to different nodes simultaneously
* No blocking between client model and server model
* NVS Storing
* Store provisioning and configuration information of ESP-BLE-MESH Node
Mesh Models
"""""""""""
* Foundation Models
* Configuration Server Model
* Configuration Client Model
* Health Server Model
* Health Client Model
* Generic Client Models
* Generic OnOff Client
* Generic Level Client
* Generic Default Transition Time Client
* Generic Power OnOff Client
* Generic Power Level Client
* Generic Battery Client
* Generic Location Client
* Generic Property Client
* Sensor Client Models
* Sensor Client
* Time and Scenes Client Models
* Time Client
* Scene Client
* Scheduler Client
* Lighting Client Models
* Light Lightness Client
* Light CTL Client
* Light HSL Client
* Light xyL Client
* Light LC Client
* Generic Server Models
* Generic OnOff Server (Simple)
Mesh Applications
"""""""""""""""""
* ESP-BLE-MESH Node
* :example:`Tutorial <bluetooth/esp_ble_mesh/ble_mesh_node/tutorial/Ble_Mesh_Node_Example_Walkthrough.md>`
* :example:`Example <bluetooth/esp_ble_mesh/ble_mesh_node>`
* ESP-BLE-MESH Node with client model
* :example:`Tutorial <bluetooth/esp_ble_mesh/ble_mesh_client_model/tutorial/ble_mesh_client_model.md>`
* :example:`Example <bluetooth/esp_ble_mesh/ble_mesh_client_model>`
* ESP-BLE-MESH Provisioner
* :example:`Tutorial <bluetooth/esp_ble_mesh/ble_mesh_provisioner/tutorial/Ble_Mesh_Provisioner_Example_Walkthrough.md>`
* :example:`Example <bluetooth/esp_ble_mesh/ble_mesh_provisioner>`
* ESP-BLE-MESH Fast Provisioning
* :example:`Fast Provisioning Client Model Tutorial <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client/tutorial/ble_mesh_fast_provision_client.md>`
* :example:`Fast Provisioning Server Model Tutorial <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server/tutorial/ble_mesh_fast_provision_server.md>`
* :example:`Example <bluetooth/esp_ble_mesh/ble_mesh_fast_provision>`
* `Demo Video <http://download.espressif.com/BLE_MESH/BLE_Mesh_Demo/V0.4_Demo_Fast_Provision/ESP32_BLE_Mesh_Fast_Provision.mp4>`__
* ESP-BLE-MESH and Wi-Fi Coexistence
* :example:`Tutorial <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/ble_mesh_wifi_coexist.md>`
* :example:`Example <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`
* `Demo Video <http://download.espressif.com/BLE_MESH/BLE_Mesh_Demo/V0.5_Demo_Coexistence/ESP_BLE_MESH_%26_WIFI_Coexistence.mp4>`__
* ESP-BLE-MESH Console Commands
* :example:`Example <bluetooth/esp_ble_mesh/ble_mesh_console>`
Future Release Features
-----------------------
Mesh Core
"""""""""
* Proxy Client
Mesh Models
"""""""""""
* Generic Server Models
* Sensor Server Models
* Time and Scenes Server Models
* Lighting Server Models
Mesh Applications
"""""""""""""""""
* Fast OTA
* Friendship

274
docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst Normal file
View file

@ -0,0 +1,274 @@
************
ESP-BLE-MESH
************
Bluetooth mesh networking enables many-to-many (m:m) device communications and is optimized for creating large-scale device networks.
Devices may relay data to other devices not in direct radio range of the originating device. In this way, mesh networks can span very large physical areas and contain large numbers of devices. It is ideally suited for building automation, sensor networks, and other IoT solutions where tens, hundreds, or thousands of devices need to reliably and securely communicate with one another.
Bluetooth mesh is not a wireless communications technology, but a networking technology. This technology is dependent upon Bluetooth Low Energy (BLE) - a wireless communications protocol stack.
Built on top of Zephyr ESP-BLE-MESH stack, the ESP-BLE-MESH implementation supports device provisioning and node control. It also supports such node features as Proxy, Relay, Low power and Friend.
Please see the :doc:`ble-mesh-architecture` for information about the implementation of ESP-BLE-MESH architecture and :doc:`ESP-BLE-MESH API Reference <../../api-reference/bluetooth/esp-ble-mesh>` for information about respective API.
ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here <https://launchstudio.bluetooth.com/ListingDetails/94304>`_ for the certification details of ESP-BLE-MESH.
.. note::
If you are looking for Wi-Fi based implementation of mesh for ESP32, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`.
.. _getting-started-with-ble-mesh:
Getting Started with ESP-BLE-MESH
=================================
This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the ESP32 chip by Espressif.
We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes. This process will cover device provisioning and node configuration, and then sending on/off commands to Generic OnOff Server Models on specific nodes.
If you are new to ESP-IDF, please first set up development environment, compile , flash and run example application following top level ESP-IDF :doc:`../../get-started/index` documentation.
What You Need
-------------
Hardware:
* Three ESP32 boards, see :ref:`options <get-started-ble-mesh-check-hardware>`.
* USB cables to connect the boards.
* Computer configured with ESP-IDF.
* Mobile phone or tablet running Android or iOS.
Software:
* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node` code to load to the ESP32 boards.
* Mobile App: **nRF Mesh** for Android or iOS. Optionally you can use some other Apps:
- `EspBleMesh <https://github.com/EspressifApp/EspBLEMeshForAndroid/releases/tag/v1.0.0>`_ Android App
- Silicon Labs Android or iOS App
Installation Step by Step
-------------------------
This is a detailed roadmap to walk you through the installation process.
.. _get-started-ble-mesh-check-hardware:
Step 1. Check Hardware
""""""""""""""""""""""
Both `ESP32-DevKitC`_ and `ESP-WROVER-KIT`_ development boards are supported for ESP-BLE-MESH implementation. You can choose particular board through menuconfig: :code:`idf.py menuconfig` > ``Example Configuration`` > ``Board selection for ESP-BLE-MESH``
.. note::
If you plan to use `ESP32-DevKitC`_, connect a RGB LED to GPIO pins 25, 26 and 27.
Step 2. Configure Software
""""""""""""""""""""""""""
Enter the :example:`bluetooth/esp_ble_mesh/ble_mesh_node` example directory, run :code:`idf.py menuconfig` to select your board and then run :code:`idf.py build` to compile the example.
Step 3. Upload Application to Nodes
"""""""""""""""""""""""""""""""""""
After the :example:`bluetooth/esp_ble_mesh/ble_mesh_node` example is compiled successfully, users can run :code:`idf.py flash` to upload the same generated binary files into each of the three development boards.
Once boards are powered on, the RGB LED on each board should turn **GREEN**.
.. figure:: ../../../_static/ble-mesh-device-power-on.png
:align: center
ESP-BLE-MESH Devices Power On
Step 4. Provision Nodes
"""""""""""""""""""""""
In this section, we will use the **nRF Mesh Android** App to demonstrate how to provision an unprovisioned device. Users can also get its iOS version from the App Store.
4.1 Scanner
^^^^^^^^^^^
The Scanner is App's functionality to search for unprovisioned devices in range. Open the App, press **Scanner** at the bottom and the search will start. After a short while we should see three unprovisioned devices displayed.
.. figure:: ../../../_static/ble-mesh-scanner.png
:align: center
:height: 370
nRF Mesh - Scanner
4.2 Identify
^^^^^^^^^^^^
Users can select any unprovisioned device, then the App will try to set up a connection with the selected device. After the BLE connection is established successfully (sometimes users need to try multiple times to get connected), and proper ESP-BLE-MESH GATT Service is discovered, users can see the **IDENTIFY** interface button on the screen. The IDENTIFY operation can be used to tell users which device is going to be provisioned.
.. note::
The IDENTIFY operation also needs some cooperation on the device side, then users can see which device is in the provisioning process. Currently when pressing the **IDENTIFY** interface button, no signs can been seen from the device except from the log on the serial monitor.
After the **IDENTIFY** interface button is pressed, users can see the **PROVISION** interface button.
.. figure:: ../../../_static/ble-mesh-identify-provision.png
:align: center
:height: 370
nRF Mesh - IDENTIFY - PROVISION
4.3 Provision
^^^^^^^^^^^^^
Then, the App will try to provision the unprovisioned device. When the device is provisioned successfully, the RGB LED on the board will turn off, and the App will implement the following procedures:
#. Disconnect with the node
#. Try to reconnect with the node
#. Connect successfully and discover ESP-BLE-MESH GATT Service
#. Get Composition Data of the node and add AppKey to it
When all the procedures are finished, the node is configured properly. And after pressing **OK**, users can see that unicast address is assigned, and Composition Data of the node is decoded successfully.
.. figure:: ../../../_static/ble-mesh-config-complete.png
:align: center
:height: 370
nRF Mesh - Configuration Complete
Sometimes in procedure 2, the App may fail to reconnect with the node. In this case, after pressing **OK**, users can see that only unicast address of the node has been assigned, but no Composition Data has been got. Then users need to press **CONNECT** on the top right, and the previously provisioned node will be displayed on the screen, and users need to choose it and try to connect with the node.
.. figure:: ../../../_static/ble-mesh-initial-config-fail.png
:align: center
:height: 370
nRF Mesh - Initial Configuration Failed
After connecting successfully, the App will show the interface buttons which can be used to get Composition Data and add AppKey.
.. figure:: ../../../_static/ble-mesh-reconnect-initial-config.png
:align: center
:height: 370
nRF Mesh - Reconnect - Initial Configuration
If the device is the second or the third one which has been provisioned by the App, and after pressing **CONNECT**, users can see two or three nodes on the screen. In this situation, users can choose any device to connect with, once succeed then go back to the main screen to choose the node which needs to be configured.
Here an example of three devices listed.
* The left picture shows that the third device is provisioned successfully, but the App failed to connect with it. When it tries to reconnect with the third node, three nodes are displayed on the App.
* The right picture shows that after connecting with any node successfully, the App displays the information of the three nodes. Users can see that the App has got the Composition Data of the first and the second nodes, but for the third one, only the unicast address has been assigned to it while the Composition Data is unknown.
.. figure:: ../../../_static/ble-mesh-reconnect-three.png
:align: center
:height: 370
nRF Mesh - Reconnect - Three Nodes
4.4 Configuration
^^^^^^^^^^^^^^^^^
When provisioning and initial configuration are finished, users can start to configure the node, such as binding AppKey with each model with the elements, setting publication information to it, etc.
Example below shows how to bind AppKey with Generic OnOff Server Model within the Primary Element.
.. figure:: ../../../_static/ble-mesh-model-bind-appkey.png
:align: center
:height: 370
nRF Mesh - Model Bind AppKey
.. note::
No need to bind AppKey with the Configuration Server Model, since it only uses the DevKey to encrypt messages in the Upper Transport Layer.
Step 5. Operate Network
"""""""""""""""""""""""
After all the Generic OnOff Server Models within the three elements are bound with proper AppKey, users can use the App to turn on/off the RGB LED.
In the :example:`bluetooth/esp_ble_mesh/ble_mesh_node` example, the first Generic OnOff Server Model is used to control the **RED** color, the second one is used to control the **GREEN** color and the third one is used to control the **BLUE** color.
.. figure:: ../../../_static/ble-mesh-generic-onoff.png
:align: center
:height: 370
nRF Mesh - Generic OnOff Control
The following screenshot shows different board with different color on.
.. figure:: ../../../_static/ble-mesh-three-nodes-on.png
:align: center
Three ESP-BLE-MESH Nodes On
.. note::
For **nRF Mesh** iOS App [version 1.0.4], when the node contains more than one element, the App is not behaving correctly. If users try to turn on/off the second or the third Generic OnOff Server Model, the message sent by the App is destinated to the first Generic OnOff Server Model within the Primary Element.
.. _esp-ble-mesh-examples:
ESP-BLE-MESH Examples
=====================
* :example:`ESP-BLE-MESH Node <bluetooth/esp_ble_mesh/ble_mesh_node/tutorial/Ble_Mesh_Node_Example_Walkthrough.md>` - shows the use of ESP-BLE-MESH as a node device having a Configuration Server model and a Generic OnOff Server model. A ESP-BLE-MESH provisioner can then provision the node and control a RGB LED representing on/off state, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_node>`.
* :example:`ESP-BLE-MESH Client Model <bluetooth/esp_ble_mesh/ble_mesh_client_model/tutorial/ble_mesh_client_model.md>` - shows how a Generic OnOff Client model works within a node. The node has a Configuration Server model, a Generic OnOff Server model and a Generic OnOff Client model, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_client_model>`.
* :example:`ESP-BLE-MESH Provisioner <bluetooth/esp_ble_mesh/ble_mesh_provisioner/tutorial/Ble_Mesh_Provisioner_Example_Walkthrough.md>` - shows how a device can act as a ESP-BLE-MESH provisioner to provision devices. The provisioner has a Configuration Server model, a Configuration Client model and a Generic OnOff Client model, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_provisioner>`.
* ESP-BLE-MESH Fast Provisioning - :example:`Client <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client/tutorial/ble_mesh_fast_provision_client.md>` and :example:`Server <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server/tutorial/ble_mesh_fast_provision_server.md>` - this demo is used for fast provisioning networks. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client>` and :example:`example server code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server>`.
* :example:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/ble_mesh_wifi_coexist.md>` - a demo that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of ESP32. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`.
* ESP-BLE-MESH Node Console - a demo that implements BLE mesh node basic features. Within this demo a node can be scanned and provisioned by provisioner and reply to get/set message from provisioner, see :example:`example node code <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_node>` and :example:`example provisioner code <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_provisioner>`.
.. _esp-ble-mesh-demo-videos:
ESP-BLE-MESH Demo Videos
========================
* `Provisioning of ESP-BLE-MESH nodes using Smartphone App <http://download.espressif.com/BLE_MESH/Docs4Customers/esp-ble-mesh-demo.mp4>`_
* `Espressif Fast Provisioning using ESP-BLE-MESH App <http://download.espressif.com/BLE_MESH/BLE_Mesh_Demo/V0.4_Demo_Fast_Provision/ESP32_BLE_Mesh_Fast_Provision.mp4>`_
* `Espressif ESP-BLE-MESH and Wi-Fi Coexistence <http://download.espressif.com/BLE_MESH/BLE_Mesh_Demo/V0.5_Demo_Coexistence/ESP_BLE_MESH_%26_WIFI_Coexistence.mp4>`_
ESP-BLE-MESH FAQ
================
* :ref:`ble-mesh-faq-provisioner-development`
* :ref:`ble-mesh-faq-node-development`
* :ref:`ble-mesh-faq-ble-mesh-and-wi-fi-coexistence`
* :ref:`ble-mesh-faq-fast-provisioning`
* :ref:`ble-mesh-faq-log-help`
* :ref:`ble-mesh-faq-example-help`
* :ref:`ble-mesh-faq-others`
Related Documents
=================
.. toctree::
:maxdepth: 1
ble-mesh-feature-list
ble-mesh-architecture
ble-mesh-faq
ble-mesh-terminology
Bluetooth SIG Documentation
---------------------------
- `BLE Mesh Core Specification <https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429633>`_
- `BLE Mesh Model Specification <https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429634>`_
- `An Intro to Bluetooth Mesh Part 1 <http://blog.bluetooth.com/an-intro-to-bluetooth-mesh-part1>`_ / `Part 2 <http://blog.bluetooth.com/an-intro-to-bluetooth-mesh-part2>`__
- `The Fundamental Concepts of Bluetooth Mesh Networking, Part 1 <http://blog.bluetooth.com/the-fundamental-concepts-of-bluetooth-mesh-networking-part-1>`_ / `Part 2 <http://blog.bluetooth.com/the-fundamental-concepts-of-bluetooth-mesh-networking-part-2>`__
- `Bluetooth Mesh Networking: Friendship <http://blog.bluetooth.com/bluetooth-mesh-networking-series-friendship>`_
- `Management of Devices in a Bluetooth Mesh Network <http://blog.bluetooth.com/management-of-devices-bluetooth-mesh-network>`_
- `Bluetooth Mesh Security Overview <http://blog.bluetooth.com/bluetooth-mesh-security-overview>`_
- `Provisioning a Bluetooth Mesh Network Part 1 <http://blog.bluetooth.com/provisioning-a-bluetooth-mesh-network-part-1>`_ / `Part 2 <http://blog.bluetooth.com/provisioning-a-bluetooth-mesh-network-part-2>`__
.. _ESP32-DevKitC: https://www.espressif.com/en/products/hardware/esp32-devkitc/overview
.. _ESP-WROVER-KIT: https://www.espressif.com/en/products/hardware/esp-wrover-kit/overview

219
docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst Normal file
View file

@ -0,0 +1,219 @@
ESP BLE Terminology
===================
.. _ble-mesh-terminology-role:
.. list-table:: Table 1 ESP-BLE-MESH Terminology - Role
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - Unprovisioned Device
- A device that is not a member of a mesh network is known as an unprovisioned device.
- Examples: lighting devices, temperature control devices, manufacturing equipments and electric doors, etc.
* - Node
- A node is a provisioned device.
- The role of unprovisioned device will change to node after being provisioned to ESP-BLE-MESH network. Nodes (such as lighting devices, temperature control devices, manufacturing equipments, and electric doors) are devices that can send, receive, or relay messages in ESP-BLE-MESH network, and they can optionally support one or more subnets.
* - Relay Node
- A node that supports the Relay feature and has the Relay feature enabled is known as a Relay node.
- Relay nodes can receive and resend ESP-BLE-MESH messages, so the messages can be transferred further. Users can decide whether or not to enable forwarding function of nodes according to nodes' status. Messages can be relayed for multiple times, and each relay is considered as a "hop". Messages can hop up to 126 times, which is enough for message transmission in a wide area.
* - Proxy Node
- A node that supports the Proxy feature and has the Proxy feature enabled is known as a Proxy node.
- Proxy nodes receive messages from one bearer (it generally includes advertising bearer and GATT bearer) and resend it from another one. The purpose is to connect communication equipments that only support GATT bearer to ESP-BLE-MESH network. Generally, mobile apps need a Proxy node to access Mesh network. Without Proxy nodes, mobile apps cannot communicate with members in Mesh network.
* - Friend Node
- A node that supports the Friend feature, has the Friend feature enabled, and has a friendship with a node that supports the Low Power feature is known as a Friend node.
- Friend node, like the backup of Low Power node (LPN), can store messages that are sent to Low Power node and security updates; the stored information will be transferred to Low Power node when Low Power node needs it. Low Power node must establish "friendship" with another node that supports the Friend Feature to reduce duty cycle of its receiver, thus power consumption of Low Power node can be reduced. Low Power node needs to find a Friend node to establish a friendship with it. The process involved is called "friendship establishment". Cooperation between Low Power node and Friend nodes enables Low Power node to schedule the use of the radio, thus Low Power node can receive messages at an appropriate or lower frequency without the need of keeping listening. Low Power node will poll Friend node to see if there is new message.
* - Low Power Node
- A node that supports the Low Power feature and has a friendship with a node that supports the Friend feature is known as a Low Power node.
- By polling, Low Power node gets information from Friend node, such as messages, security updates, and etc.
* - Provisioner
- A node that is capable of adding a device to a mesh network.
- The device that can provision unprovisioned devices is called a Provisioner. This process usually needs to be implemented through an app that is typically provided by the product manufacturer and can be used on a gateway, a smartphone, tablet or other carriers.
.. _ble-mesh-terminology-composition:
.. list-table:: Table 2 ESP-BLE-MESH Terminology - Composition
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - State
- A value representing a condition of an element that is exposed by an element of a node.
- Each node in a ESP-BLE-MESH network has an independent set of state values that indicate certain states of the device, like brightness, and color of lighting device. Change of state value will lead to change of the physical state of devices. For example, changing the on/off state of a device is actually turning on/off the device.
* - Model
- A model defines the basic functionality of a node.
- A node may contain multiple models, and each model defines basic functionalities of nodes, like the states needed by the nodes, the messages controlling the states, and actions resulted from messages handling. The function implementation of the nodes is based on models, which can be divided into SIG Model and Vendor Model, with the former defined by SIG and latter defined by users.
* - Element
- An addressable entity within a device.
- A node can contain one or more elements, with each having a unicast address and one or more models, and the models contained by the same element must not be the same.
* - Composition Data State
- The Composition Data state contains information about a node, the elements it includes, and the supported models.
- By reading the value of the Composition Data state, users can know basic information of the node, such as the number of elements, and the models in each element. Provisioner gets this message to further provision the device, such as configuring subscription address and publishing address of nodes.
.. _ble-mesh-terminology-features:
.. list-table:: Table 3 ESP-BLE-MESH Terminology - Features
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - Low Power Feature
- The ability to operate within a mesh network at significantly reduced receiver duty cycles only in conjunction with a node supporting the Friend feature.
- Low Power feature reduces power consumption of nodes. When a Low Power node is searching for a Friend node, and there are multiple Friend nodes nearby, it selects the most suitable Friend node through algorithm.
* - Friend Feature
- The ability to help a node supporting the Low Power feature to operate by storing messages destined for those nodes.
- By enabling friend feature, the node can help to store information for Low Power node. The nodes enabled with friend feature may cause more power and memory consumption.
* - Relay Feature
- The ability to receive and retransmit mesh messages over the advertising bearer to enable larger networks.
- The relay feature enables ESP-BLE-MESH messages to hop among nodes for multiple times, and the transmission distance can exceed the range of direct radio transmission between two nodes, thereby covering the entire network. When a node is enabled with the relay feature to relay messages, it only relays the messages of its own subnet, and does not relay the messages of other subnets. The data integrity will not be considered when the node enabled with relay feature relays segmented messages. The node would relay every segmented message once it receives one rather than waiting for the complete message.
* - Proxy Feature
- The ability to receive and retransmit mesh messages between GATT and advertising bearers.
- The purpose of the proxy feature is to allow nodes without an advertising bearer to access the ESP-BLE-MESH network. The proxy feature is typically used in nodes that need to connect to mobile apps.
.. _ble-mesh-terminology-provisioning:
.. list-table:: Table 4 ESP-BLE-MESH Terminology - Provisioning
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - PB-ADV
- PB-ADV is a provisioning bearer used to provision a device using Generic Provisioning PDUs over the advertising channels.
- PB-ADV transfers packets generated during the provisioning process over the advertising channels. This way can only be used for provisioning when provisioner and unprovisioned device both support PB-ADV.
* - PB-GATT
- PB-GATT is a provisioning bearer used to provision a device using Proxy PDUs to encapsulate Provisioning PDUs within the Mesh Provisioning Service.
- PB-GATT uses connection channels to transfer packets generated during the provisioning process. If an unprovisioned device wants to be provisioned through this method, it needs to implement the related Mesh Provisioning Service. Unprovisioned devices which don't implement such service cannot be provisioned into mesh network through PB-GATT bearer.
* - Provisioning
- Provisioning is a process of adding an unprovisioned device to a mesh network, managed by a Provisioner.
- The process of provisioning turns the "unprovisioned device" into a "node", making it a member of the ESP-BLE-MESH network.
* - Authentication Method
- Authentication is a step during the provisioning of nodes.
- There are four authentication methods for unprovisioned devices: Output OOB, Input OOB, Static OOB, and No OOB.
* - Input OOB
- Input Out-of-Band
- For example, a Provisioner generates and displays a random number, and then prompts users to take appropriate actions to input the random number into the unprovisioned device. Taking lighting switch as an example, users can press the button for several times in a certain period of time to input the random number displayed on the Provisioner. Authentication method of the Input OOB is similar to that of Output OOB, but the role of the device is reversed.
* - Output OOB
- Output Out-of-Band
- For example, an unprovisioned device will choose a random number and output the number in a way that is compatible with its functionality. If the unprovisioned device is a bulb, it can flash a specified number of times. If the unprovisioned device has an LCD screen, the random number can display as a multi-digit value. Users who start provisioning should input the observed number to authenticate the unprovisioned device.
* - Static OOB
- Static Out-of-Band
- Authentication method of Static OOB: use Static OOB information. Use 0 as Static OOB information if No OOB information is needed. Use Static OOB information to authenticate devices which are going through provisioning if OOB information is needed.
* - No OOB
- No Out-of-Band
- Authentication method of No OOB: Set the value of the Static OOB field to 0. Using this way is like not authenticating the unprovisioned devices.
.. _ble-mesh-terminology-address:
.. list-table:: Table 5 ESP-BLE-MESH Terminology - Address
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - Unassigned Address
- This is a special address type, with a value of 0x0000. Its use indicates that an Element has not yet been configured or had a Unicast Address assigned to it.
- The addresses owned by elements which has not been configured yet or no address has been allocated are unassigned addresses. These elements will not be used for messages transfer because they have no fixed address. Unassigned address is recommended to set as the value of the address before setting the address of user code.
* - Unicast Address
- A unicast address is a unique address allocated to each element.
- During provisioning, the Provisioner will assign a unicast address to each element of node within the life cycle of the nodes in the network. A unicast address may appear in the source/destination address field of a message. Messages sent to a unicast address can only be processed by the element that owns the unicast address.
* - Virtual Address
- A virtual address represents a set of destination addresses. Each virtual address logically represents a Label UUID, which is a 128-bit value that does not have to be managed centrally.
- Associated with specific UUID labels, a virtual address may serve as the publishing or subscription address of the model. A UUID label is a 128-bit value associated with elements of one or more nodes. For virtual addresses, the 15th and 14th bits are set to 1 and 0 respectively; bits from 13th to 0 are set to hash values (providing 16384 hash values). The hash is a derivation of the Label UUID. To use subscribing elements to check the full 128-bit UUID is very inefficient while hash values provide a more efficient way to determine which elements that which messages are finally sent to.
* - Group Address
- A group address is an address that is programmed into zero or more elements
- Group address is another kind of multicast address in the ESP-BLE-MESH network, which is usually used to group nodes. A message sent to the all-proxies address shall be processed by the primary element of all nodes that have the proxy functionality enabled. A message sent to the all-friends address shall be processed by the primary element of all nodes that have the friend functionality enabled. A message sent to the all-relays address shall be processed by the primary element of all nodes that have the relay functionality enabled. A message sent to the all-nodes address shall be processed by the primary element of all nodes.
.. _ble-mesh-terminology-security:
.. list-table:: Table 6 ESP-BLE-MESH Terminology - Security
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - Device Key (DevKey)
- There is also a device key, which is a special application key that is unique to each node, is known only to the node and a Configuration Client, and is used to secure communications between the node and a Configuration Client.
- The device key enables you to provision the devices, configure the nodes. The device key is used to encrypt Configuration Messages, i.e. the message transferred between the Provisioner and the node when the device is configured.
* - Application Key (AppKey)
- Application keys are used to secure communications at the upper transport layer.
- Application key is used for decryption of application data before delivering application data to application layer and encryption of them during the delivery of application layer. Some nodes in the network have a specific purpose and can restrict access to potentially sensitive data based on the needs of the application. With specific application keys, these nodes are associated with specific applications. Generally speaking, the fields using different application keys include security (access control of buildings, machine rooms and CEO offices), lighting (plant, exterior building and sidewalks) and HVAC systems. Application keys are bound to Network keys. This means application keys are only used in a context of a Network key they are bound to. An application key shall only be bound to a single Network key.
* - Master Security Material
- The master security material is derived from the network key (NetKey) and can be used by other nodes in the same network. Messages encrypted with master security material can be decoded by any node in the same network.
- The corresponding friendship messages encrypted with the friendship security material: 1. Friend Poll, 2. Friend Update, 3. Friend Subscription List, add/delete/confirm, 4. The Stored Messages" sent by friend nodes to Low Power node. The corresponding friendship messages encrypted with the master security material: 1. Friend Clear, 2. Friend Clear Confirm. Based on the setup of the applications, the messages sent from the Low Power node to the friend nodes will be encrypted with the friendship security material or master security material, with the former being used by the messages transmitted between Low Power node and friend nodes and the latter being used by other network messages.
.. _ble-mesh-terminology-message:
.. list-table:: Table 7 ESP-BLE-MESH Terminology - Message
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - Reassembly / Segmentation
- Segmentation and reassembly (SAR) is a method of communication network, which is divided into small units before transmitting packets and reassembled in a proper order at the communication receiving end.
- The lower transport layer will automatically segment the message whose size is too big. The receiving end will return a response message, and the transmitting end will send the data packet again that the receiving end does not receive according to the response message. This is automatically completed by the lower transport layer. Unsegmented messages have at most 15 bytes, of which 4 bytes are transMIC, so the remaining is 11 bytes; in the case of segmentation, there are 12 valid bytes in the first several packets, and 8 in the last one. Special case: A shorter packet requires mandatory segmentation from lower transport layer, in which case the valid byte is 8 bytes.
* - Unacknowledged / Acknowledged
- There are two types of messages: Unacknowledged or Acknowledged
- Based on the whether or not the receiving end needs to send the response message, the messages sent are divided into two kinds. The sending end should set the maximum number of retransmission.
.. _ble-mesh-terminology-foundation-models:
.. list-table:: Table 8 ESP-BLE-MESH Terminology - Foundation Models
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - Configuration Server Model
- This model is used to represent a mesh network configuration of a device.
- The node must contain the Configuration Server Model, which is responsible for maintaining configuration-related states. The states that Configuration Server Model maintains include: NetKey List, AppKey List, Model to AppKey List, Node Identity, Key Refresh Phase, Heartbeat Publish, Heartbeat Subscription, Network Transmit, Relay Retransmit etc.
* - Configuration Client Model
- The model is used to represent an element that can control and monitor the configuration of a node.
- The Configuration Client Model uses messages to control the state maintained by the Configuration Server Model. The Provisioner must contain the Configuration Client Model, with which the configuration messages, like Configuration Composition Data Get can be sent.
* - Health Server Model
- This model is used to represent a mesh network diagnostics of a device.
- The Health Server Model is primarily used by devices to check their states and see if there is an error. The states maintained by Health Server model include: Current Fault, Registered Fault, Health Period, and Attention Timer.
* - Health Client Model
- The model is used to represent an element that can control and monitor the health of a node.
- The Health Client Model uses messages to control the state maintained by the Health Server Model. The model can get the self-test information of other nodes through the message "Health Fault Get".
.. _ble-mesh-terminology-network-management:
.. list-table:: Table 9 ESP-BLE-MESH Terminology - Network Management
:widths: 10 40 60
:header-rows: 1
* - Term
- Official Definition
- Detailed Explanation
* - Key Refresh procedure
- This procedure is used when the security of one or more network keys and/or one or more of the application keys has been compromised or could be compromised.
- Key Refresh Procedure is used to update network key and application key of ESP-BLE-MESH network. Key Refresh Procedure is used when the security of one or more network keys and/or one or more application keys is threatened or potentially threatened. Keys are usually updated after some nodes in the network are removed.
* - IV (Initialisation Vector) Update Procedure
- A node can also use an IV Update procedure to signal to peer nodes that it is updating the IV Index.
- The IV Update procedure is used to update the value of ESP-BLE-MESH network's IV Index. This value is related to the random number required for message encryption. To ensure that the value of the random number is not repeated, this value is periodically incremented. IV Index is a 32-bit value and a shared network resource. For example, all nodes in a mesh network share the same IV Index value. Starting from 0x00000000, the IV Index increments during the IV Update procedure and maintained by a specific process, ensuring the IV Index shared in the mesh network is the same. This can be done when the node believes that it has the risk of exhausting its sequence number, or when it determines that another node is nearly exhausting its sequence number. Note: The update time must not be less than 96 hours. It can be triggered when a secure network beacon is received, or when the node determines that its sequence number is greater than a certain value.
For more terms, please see: `ESP-BLE-MESH Glossary of Terms <https://www.bluetooth.com/bluetooth-technology/topology-options/le-mesh/mesh-glossary/>`_.

3
docs/en/api-guides/index.rst
View file

@ -13,7 +13,8 @@ API Guides
Console Component <console>
Deep Sleep Wake Stubs <deep-sleep-stub>
Error Handling <error-handling>
ESP-MESH <mesh>
ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
ESP32 Core Dump <core_dump>
Event Handling <event-handling>
External SPI-connected RAM <external-ram>

154
docs/en/api-reference/bluetooth/esp-ble-mesh.rst Normal file
View file

@ -0,0 +1,154 @@
ESP-BLE-MESH
============
With various features of ESP-BLE-MESH, users can create a managed flooding mesh network for several
scenarios, such as lighting, sensor and etc.
For an ESP32 to join and work on a ESP-BLE-MESH network, it must be provisioned firstly. By provisioning,
the ESP32, as an unprovisioned device, will join the ESP-BLE-MESH network and become a ESP-BLE-MESH node,
communicating with other nodes within or beyond the radio range.
Apart from ESP-BLE-MESH nodes, inside ESP-BLE-MESH network, there is also ESP32 that works as ESP-BLE-MESH
Provisioner, which could provision unprovisioned devices into ESP-BLE-MESH nodes and configure the nodes
with various features.
For information how to start using ESP32 and ESP-BLE-MESH, please see the Section :ref:`getting-started-with-ble-mesh`. If you are interested in information on ESP-BLE-MESH architecture, including some details of software implementation, please see Section :doc:`../../api-guides/esp-ble-mesh/ble-mesh-architecture`.
Application Examples and Demos
------------------------------
Please refer to Sections :ref:`esp-ble-mesh-examples` and :ref:`esp-ble-mesh-demo-videos`.
API Reference
-------------
ESP-BLE-MESH APIs are divided into the following parts:
* `ESP-BLE-MESH Definitions`_
* `ESP-BLE-MESH Core API Reference`_
* `ESP-BLE-MESH Models API Reference`_
ESP-BLE-MESH Definitions
------------------------
This section contains only one header file, which lists the following items of ESP-BLE-MESH.
* ID of all the models and related message opcodes
* Structs of model, element and Composition Data
* Structs of used by ESP-BLE-MESH Node/Provisioner for provisioning
* Structs used to transmit/receive messages
* Event types and related event parameters
.. include:: /_build/inc/esp_ble_mesh_defs.inc
ESP-BLE-MESH Core API Reference
-------------------------------
This section contains ESP-BLE-MESH Core related APIs, which can be used to initialize ESP-BLE-MESH
stack, provision, send/publish messages, etc.
This API reference covers six components:
* `ESP-BLE-MESH Stack Initialization`_
* `Reading of Local Data Information`_
* `Low Power Operation (Updating)`_
* `Send/Publish Messages, add Local AppKey, etc.`_
* `ESP-BLE-MESH Node/Provisioner Provisioning`_
* `ESP-BLE-MESH GATT Proxy Server`_
ESP-BLE-MESH Stack Initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_common_api.inc
Reading of Local Data Information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_local_data_operation_api.inc
Low Power Operation (Updating)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_low_power_api.inc
Send/Publish Messages, add Local AppKey, etc.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_networking_api.inc
ESP-BLE-MESH Node/Provisioner Provisioning
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_provisioning_api.inc
ESP-BLE-MESH GATT Proxy Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_proxy_api.inc
ESP-BLE-MESH Models API Reference
---------------------------------
This section contains ESP-BLE-MESH Model related APIs, event types, event parameters, etc.
There are six categories of models:
* `Configuration Client/Server Models`_
* `Health Client/Server Models`_
* `Generic Client/Server Models`_
* `Sensor Client/Server Models`_
* `Time and Scenes Client/Server Models`_
* `Lighting Client/Server Models`_
.. note::
Definitions related to Server Models are being updated, and will be released soon.
Configuration Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_config_model_api.inc
Health Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_generic_model_api.inc
Generic Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_health_model_api.inc
Sensor Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_lighting_model_api.inc
Time and Scenes Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_sensor_model_api.inc
Lighting Client/Server Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. include:: /_build/inc/esp_ble_mesh_time_scene_model_api.inc

1
docs/en/api-reference/bluetooth/index.rst
View file

@ -11,6 +11,7 @@ Bluetooth API
Bluetooth LE <bt_le>
Bluetooth Classic <classic_bt>
NimBLE <nimble/index>
ESP-BLE-MESH <esp-ble-mesh>
ESP-IDF currently supports two host stacks. The Bluedroid based stack (default) supports classic Bluetooth as well as BLE. On the other hand, Apache NimBLE based stack is BLE only. For users to make a choice:
* For usecases involving classic Bluetooth as well as BLE, Bluedroid should be used.

1
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../../en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst

1
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../../en/api-guides/esp-ble-mesh/ble-mesh-faq.rst

1
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../../en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst

1
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../../en/api-guides/esp-ble-mesh/ble-mesh-index.rst

1
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-terminology.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../../en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst

3
docs/zh_CN/api-guides/index.rst
View file

@ -30,7 +30,8 @@ API 指南
ROM debug console <romconsole>
RF Calibration <RF_calibration>
WiFi Driver <wifi>
ESP-MESH <mesh>
ESP BLE Mesh <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
BluFi <blufi>
External SPI-connected RAM <external-ram>
链接脚本生成机制 <linker-script-generation>

1
docs/zh_CN/api-reference/bluetooth/esp-ble-mesh.rst Normal file
View file

@ -0,0 +1 @@
.. include:: ../../../en/api-reference/bluetooth/esp-ble-mesh.rst

2
docs/zh_CN/api-reference/bluetooth/index.rst
View file

@ -11,7 +11,7 @@
Bluetooth LE <bt_le>
Bluetooth Classic <classic_bt>
NimBLE <nimble/index>
ESP BLE Mesh <esp-ble-mesh>
请点击下方链接，查看 ESP32 蓝牙架构：