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

    • Driver: drivers for different devices, such as frequently used buttons and LEDs
    • Miniz: lossless, high performance data compression library
    • Aliyun: Aliyun IoT kit

  • Transmission: the way of data transmission between devices

    • Mwifi: adds to ESP-MESH the retransmission filter, data compression, fragmented transmission, and P2P multicast features
    • Mespnow: adds to ESP-NOW the retransmission filter, Cyclic Redundancy Check (CRC), and data fragmentation features

  • Mcommon: modules shared by all ESP-MDF components

    • Event loop: deals with ESP-MDF events
    • Error Check: manages ESP-MDF's code errors

• Components:

  • Mconfig: network configuration module
  • Mupgrade: upgrade module
  • Mdebug: debugging module
  • Mlink: LAN control module

• 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.

1. Setup Toolchain: please set up according to your PC's operating system (Windows, Linux or Mac OS).

2. 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 command git submodule update --init

3. 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 variable IDF_PATH. Please refer to Add IDF_PATH to User Profile.

   export MDF_PATH=~/esp/esp-mdf

4. 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/

5. 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

6. Monitor/Debugging: If you want to exit the monitor, please use the shortcut key Ctrl+].

   make monitor

7. Update ESP-MDF:

   cd ~/esp/esp-mdf
   git pull
   git submodule update --init --recursive

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 (CMake).

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.

1. Setup Toolchain: please set up according to your PC's operating system (Windows, Linux or Mac OS).

2. 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 command git submodule update --init

3. 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 variable IDF_PATH. Please refer to Add IDF_PATH & idf.py PATH to User Profile (CMake).

   export MDF_PATH=~/esp/esp-mdf
   export PATH="$MDF_PATH/esp-idf/tools:$PATH"

4. 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/

5. Build and Flash: Only the serial port number needs to be modified. For the rest, just keep the default configuration untouched.

   idf.py menuconfig
   idf.py erase_flash flash

6. Monitor/Debugging: If you want to exit the monitor, please use the shortcut key Ctrl+].

   idf.py monitor

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