ESP-MESH Development Framework [中文]
ESP-MDF, or Espressif Mesh Development Framework, is a development framework for ESP-MESH, a networking protocol built on top of the Wi-Fi protocol. ESP-MDF is based on the ESP32 chip.
ESP-MDF is based on the ESP-MESH protocol stack to facilitate your development of ESP-MESH. ESP-MDF provides the following features:
-
Fast network configuration: In addition to manual configuration with the network configuration apps, such as ESP-MESH App or similar third-party apps, ESP-MDF offers a chained way of network configuration, during which devices autonomously and quickly establish a network, and form a greater coverage area.
-
Stable upgrade: The upgrading process has become more efficient with such features as automatic retransmission of failed fragments, data compression, reverting to an earlier version, firmware check, etc.
-
Efficient debugging: Various debugging approaches are supported, such as wireless transmission of logs and wireless debugging, debugging through a command terminal, etc.
-
LAN control: Network can be controlled by an app, sensor, etc.
-
Various application demos: It offers comprehensive solutions based on ESP-MESH in the areas of lighting, indoor positioning, etc.
ESP-MDF consists of Utils, Components and Examples (see the below figure). Utils is the encapsulation and third-party library of ESP-IDF APIs. Components are the ESP-MDF functional modules that use Utils APIs. Examples are the ESP-MESH solutions based on the Components.
-
Utils:
-
Third Party: the third-party items
-
Transmission: the way of data transmission between devices
-
Mcommon: modules shared by all ESP-MDF components
- Event loop: deals with ESP-MDF events
- Error Check: manages ESP-MDF's code errors
-
-
Components:
-
Examples:
- Function demo: demonstrates how functions can be used
- Development Kit: provides ESP32-MeshKit and ESP32-Buddy application demos
- Solution: offers a routerless solution, as well as the solutions for indoor positioning, street light control, etc.
ESP32-MeshKit offers a complete ESP-MESH Lighting Solution (see the below figure), complemented by ESP-Mesh App (iOS version and Android) for research, development and better understanding of ESP-MESH.
![]() ESP32-MeshKit Light |
![]() ESP32-MeshKit Sense |
- Products:
-
ESP32-MeshKit-Light: The RGBCW smart lights that show control results visually. They can be used to test network configuration time, response speed, stability performance, and measure distance, etc.
-
ESP32-MeshKit-Sense: This kit is equipped with a light sensor as well as a temperature & humidity sensor. It can measure power consumption and develop low power applications. The kit may also be used with ESP-Prog for firmware downloading and debugging.
-
ESP32-MeshKit-Button: Serves as an on/off controller, ready for the development of low power applications. It can be used with ESP-Prog for firmware downloading and debugging (Coming soon).
-
ESP32-Buddy is a development board specifically designed to test the development of ESP-MESH. With its small size and USB power input, the board can be conveniently used for testing a large number of devices and measure distances between them (Coming soon).
- Functions:
- 16 MB flash: stores logs
- OLED screen: displays information about the device, such as its layer, connection status, etc.
- LED: indicates the board's status
- Temperature & humidity sensor: collects environmental parameters
This section provides the steps for quick start with your development of ESP-MDF applications. For more details, please refer to ESP-IDF Get Started.
The directory ~/esp
will be used further to install the compiling toolchain, ESP-MDF and demo programs. You can use another directory, but make sure to modify the commands accordingly.
-
Setup Toolchain: please set up according to your PC's operating system (Windows, Linux or Mac OS).
-
Get ESP-MDF:
git clone --recursive https://github.com/espressif/esp-mdf.git
If you clone without the
--recursive
option, please navigate to the esp-mdf directory and run the commandgit submodule update --init
-
Set up ESP-MDF Path: Toolchain uses the environment variable
MDF_PATH
to access ESP-MDF. The setup of this variable is similar to that of the variableIDF_PATH
. Please refer toAdd IDF_PATH to User Profile
.export MDF_PATH=~/esp/esp-mdf
-
Start a Project: The word project refers to the communication example between two ESP-MESH devices.
cp -r $MDF_PATH/examples/get-started/ . cd get-started/
-
Build and Flash: Only the serial port number needs to be modified. For the rest, just keep the default configuration untouched.
make menuconfig make erase_flash flash
-
Monitor/Debugging: If you want to exit the monitor, please use the shortcut key
Ctrl+]
.make monitor
-
Update ESP-MDF:
cd ~/esp/esp-mdf git pull git submodule update --init --recursive
-
Easy setup: ESP-MESH expands the original Wi-Fi hotspot range to the reach of the most distant node in the mesh cloud. Such a network is automatically formed, self-healing and self-organizing. It saves the efforts of laying cables. All you need to do is configure the router password.
-
Gateway free: The decentralized structure of ESP-MESH with the absence of a gateway precludes the overall network breakdown if one single node fails. Even if there is a single ESP-MESH device, the network still works as usual.
-
Safer transmission: Both the data link layer and the application layer can be encrypted.
-
More reliable transmission: The transmission and data flow control between two devices are more reliable. Also, unicast, multicast and broadcast transmissions are supported.
-
Large network capacity: ESP-MESH takes the form of a tree topology, so one single device can connect to 10 devices at maximum, and an entire network can have over 1,000 nodes.
-
Wider transmission coverage: The transmission distance between two devices is 30 m through walls, and 200 m without any obstacles in between (relevant to ESP32-DevKitC).
- Smart Home: Even if there are only three to five devices in your home, they can form a network and communicate with one another through walls.
- Street light: If ESP-MESH is used for the street lighting scenario, two long-distance devices can communicate with each other.
-
High transmission speed: For Wi-Fi transmission, the speed can reach up to 10 Mbps.
- Environment Control System: Directly transfers the raw data collected by sensors and analyzes mass data for calibration of algorithms, thereby improving sensors' accuracy.
- Background Music System: Both audio and video transmissions are supported.
-
Simultaneously run Wi-Fi and BLE protocol stacks: ESP32 chips can run both Wi-Fi and BLE protocol stacks side by side and use ESP-MESH as the main network to transmit data, receive BLE probe beacon, send BLE broadcasts and connect BLE devices.
- Items tracing: Monitors the BLE or Wi-Fi data packets from a device at multiple selected spots.
- Pedestrian counting: Through monitoring Wi-Fi probe request frames.
- Indoor positioning: Each device functions as a Beacon AP, continuously sending Bluetooth signal to the surroundings. The network can analyze a device's signal intensity and calculate its current position.
- Product promotion: Sends real-time product information and promotions through iBeacon.
- Bluetooth gateway: With each device serving as a Bluetooth gateway, traditional Bluetooth devices can also be connected to an ESP-MESH network.
- For ESP-MDF related documents, please go to ESP-MDF Programming Guide.
- ESP-IDF Programming Guide describes Espressif's IoT development framework.
- ESP-MESH is the basic wireless communication protocol for ESP-MDF.
- To report a bug or request a function, please go to Issues on GitHub to submit them. Before submitting an issue, please check if it has already been covered.
- If you want to contribute ESP-MDF related codes, please refer to Code Contribution Guide.
- To visit ESP32 official forum, please go to ESP32 BBS.
- For the hardware documents related to ESP32-MeshKit, please visit Espressif Website.
- ESP32-MeshKit-Light purchase link: Taobao.
- ESP32-Buddy purchase link: Coming soon.