1************ 2ESP-BLE-MESH 3************ 4 5:link_to_translation:`zh_CN:[中文]` 6 7Bluetooth® mesh networking enables many-to-many (m:m) device communications and is optimized for creating large-scale device networks. 8 9Devices 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. 10 11Bluetooth 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. 12 13Built on top of Zephyr Bluetooth 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. 14 15Please 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. 16 17ESP-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. 18 19.. note:: 20 21 If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-WIF-MESH. For more information and documentation see :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`. 22 23 24.. _getting-started-with-ble-mesh: 25 26Getting Started with ESP-BLE-MESH 27================================= 28 29This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the {IDF_TARGET_NAME} chip by Espressif. 30 31We 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. 32 33If 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. 34 35 36What You Need 37------------- 38 39Hardware: 40 41* Three {IDF_TARGET_NAME} boards, see :ref:`options <get-started-ble-mesh-check-hardware>`. 42* USB cables to connect the boards. 43* Computer configured with ESP-IDF. 44* Mobile phone or tablet running Android or iOS. 45 46Software: 47 48* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the {IDF_TARGET_NAME} boards. 49* Mobile App: **nRF Mesh** for Android or iOS. Optionally you can use some other Apps: 50 51 - `EspBleMesh <https://github.com/EspressifApp/EspBLEMeshForAndroid/releases/tag/v1.0.0>`_ Android App 52 - Silicon Labs Android or iOS App 53 54Installation Step by Step 55------------------------- 56 57This is a detailed roadmap to walk you through the installation process. 58 59 60.. _get-started-ble-mesh-check-hardware: 61 62Step 1. Check Hardware 63"""""""""""""""""""""" 64 65Both `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`` 66 67.. note:: 68 69 If you plan to use `ESP32-DevKitC`_, connect a RGB LED to GPIO pins 25, 26 and 27. 70 71 72Step 2. Configure Software 73"""""""""""""""""""""""""" 74 75Enter the :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` example directory, run :code:`idf.py menuconfig` to select your board and then run :code:`idf.py build` to compile the example. 76 77Step 3. Upload Application to Nodes 78""""""""""""""""""""""""""""""""""" 79 80After the :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` 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. 81 82Once boards are powered on, the RGB LED on each board should turn **GREEN**. 83 84.. figure:: ../../../_static/ble-mesh-device-power-on.png 85 :align: center 86 87 ESP-BLE-MESH Devices Power On 88 89Step 4. Provision Nodes 90""""""""""""""""""""""" 91 92In 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. 93 944.1 Scanner 95^^^^^^^^^^^ 96 97The 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. 98 99.. figure:: ../../../_static/ble-mesh-scanner.png 100 :align: center 101 :height: 370 102 103 nRF Mesh - Scanner 104 1054.2 Identify 106^^^^^^^^^^^^ 107 108Users 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. 109 110.. note:: 111 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. 112 113After the **IDENTIFY** interface button is pressed, users can see the **PROVISION** interface button. 114 115.. figure:: ../../../_static/ble-mesh-identify-provision.png 116 :align: center 117 :height: 370 118 119 nRF Mesh - IDENTIFY - PROVISION 120 1214.3 Provision 122^^^^^^^^^^^^^ 123 124Then, 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: 125 126#. Disconnect with the node 127#. Try to reconnect with the node 128#. Connect successfully and discover ESP-BLE-MESH GATT Service 129#. Get Composition Data of the node and add AppKey to it 130 131When 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. 132 133.. figure:: ../../../_static/ble-mesh-config-complete.png 134 :align: center 135 :height: 370 136 137 nRF Mesh - Configuration Complete 138 139Sometimes 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. 140 141.. figure:: ../../../_static/ble-mesh-initial-config-fail.png 142 :align: center 143 :height: 370 144 145 nRF Mesh - Initial Configuration Failed 146 147After connecting successfully, the App will show the interface buttons which can be used to get Composition Data and add AppKey. 148 149.. figure:: ../../../_static/ble-mesh-reconnect-initial-config.png 150 :align: center 151 :height: 370 152 153 nRF Mesh - Reconnect - Initial Configuration 154 155If 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. 156 157Here an example of three devices listed. 158 159* 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. 160* 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. 161 162.. figure:: ../../../_static/ble-mesh-reconnect-three.png 163 :align: center 164 :height: 370 165 166 nRF Mesh - Reconnect - Three Nodes 167 1684.4 Configuration 169^^^^^^^^^^^^^^^^^ 170 171When 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. 172 173Example below shows how to bind AppKey with Generic OnOff Server Model within the Primary Element. 174 175.. figure:: ../../../_static/ble-mesh-model-bind-appkey.png 176 :align: center 177 :height: 370 178 179 nRF Mesh - Model Bind AppKey 180 181.. note:: 182 183 No need to bind AppKey with the Configuration Server Model, since it only uses the DevKey to encrypt messages in the Upper Transport Layer. 184 185Step 5. Operate Network 186""""""""""""""""""""""" 187 188After 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. 189 190In the :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` 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. 191 192.. figure:: ../../../_static/ble-mesh-generic-onoff.png 193 :align: center 194 :height: 370 195 196 nRF Mesh - Generic OnOff Control 197 198The following screenshot shows different board with different color on. 199 200.. figure:: ../../../_static/ble-mesh-three-nodes-on.png 201 :align: center 202 203 Three ESP-BLE-MESH Nodes On 204 205.. note:: 206 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. 207 208 209.. _esp-ble-mesh-examples: 210 211ESP-BLE-MESH Examples 212===================== 213 214* :example_file:`ESP-BLE-MESH Node OnOff Server <bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server/tutorial/BLE_Mesh_Node_OnOff_Server_Example_Walkthrough.md>` - shows the use of ESP-BLE-MESH as a node having a Configuration Server model and a Generic OnOff Server model. A ESP-BLE-MESH Provisioner can then provision the unprovisioned device and control a RGB LED representing on/off state, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server>`. 215 216* :example_file:`ESP-BLE-MESH Node OnOff Client <bluetooth/esp_ble_mesh/ble_mesh_node/onoff_client/tutorial/BLE_Mesh_Node_OnOff_Client_Example_Walkthrough.md>` - shows how a Generic OnOff Client model works within a node. The node has a Configuration Server model and a Generic OnOff Client model, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_node/onoff_client>`. 217 218* :example_file:`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 an 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>`. 219 220* ESP-BLE-MESH Fast Provisioning - :example_file:`Client <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>` and :example_file:`Server <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/fast_prov_client>` and :example:`example server code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/fast_prov_server>`. 221 222* :example_file:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`. 223 224* ESP-BLE-MESH Console - an example that implements BLE Mesh basic features. Within this example 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>`. 225 226 227.. _esp-ble-mesh-demo-videos: 228 229ESP-BLE-MESH Demo Videos 230======================== 231 232* `Provisioning of ESP-BLE-MESH nodes using Smartphone App <http://download.espressif.com/BLE_MESH/Docs4Customers/esp-ble-mesh-demo.mp4>`_ 233* `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>`_ 234* `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>`_ 235 236 237ESP-BLE-MESH FAQ 238================ 239 240* :ref:`ble-mesh-faq-provisioner-development` 241* :ref:`ble-mesh-faq-node-development` 242* :ref:`ble-mesh-faq-ble-mesh-and-wi-fi-coexistence` 243* :ref:`ble-mesh-faq-fast-provisioning` 244* :ref:`ble-mesh-faq-log-help` 245* :ref:`ble-mesh-faq-example-help` 246* :ref:`ble-mesh-faq-others` 247 248 249Related Documents 250================= 251 252.. toctree:: 253 :maxdepth: 1 254 255 ble-mesh-feature-list 256 ble-mesh-architecture 257 ble-mesh-faq 258 ble-mesh-terminology 259 260 261 262Bluetooth SIG Documentation 263--------------------------- 264 265- `BLE Mesh Core Specification <https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429633>`_ 266- `BLE Mesh Model Specification <https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=429634>`_ 267- `An Intro to Bluetooth Mesh Part 1 <https://blog.bluetooth.com/an-intro-to-bluetooth-mesh-part1>`_ / `Part 2 <https://blog.bluetooth.com/an-intro-to-bluetooth-mesh-part2>`__ 268- `The Fundamental Concepts of Bluetooth Mesh Networking, Part 1 <https://blog.bluetooth.com/the-fundamental-concepts-of-bluetooth-mesh-networking-part-1>`_ / `Part 2 <https://blog.bluetooth.com/the-fundamental-concepts-of-bluetooth-mesh-networking-part-2>`__ 269- `Bluetooth Mesh Networking: Friendship <https://blog.bluetooth.com/bluetooth-mesh-networking-series-friendship>`_ 270- `Management of Devices in a Bluetooth Mesh Network <https://blog.bluetooth.com/management-of-devices-bluetooth-mesh-network>`_ 271- `Bluetooth Mesh Security Overview <https://blog.bluetooth.com/bluetooth-mesh-security-overview>`_ 272- `Provisioning a Bluetooth Mesh Network Part 1 <https://blog.bluetooth.com/provisioning-a-bluetooth-mesh-network-part-1>`_ / `Part 2 <https://blog.bluetooth.com/provisioning-a-bluetooth-mesh-network-part-2>`__ 273 274 275.. _ESP32-DevKitC: https://www.espressif.com/en/products/hardware/esp32-devkitc/overview 276.. _ESP-WROVER-KIT: https://www.espressif.com/en/products/hardware/esp-wrover-kit/overview 277
