Skip to content
Espressif Mesh Development Framework
Branch: master
Clone or download
zhanzhaocheng Merge branch 'MeshKit_Sense_Example_doc' into 'master'
docs:  ESP32-MeshKit-Sense Example CN&EN Update

See merge request application/esp-mdf!237
Latest commit 40f42e5 Mar 15, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
components feat(submoudel): Update esp-idf to release/v3.2 Feb 27, 2019
docs fix: A little typo in contribution guide #26 Feb 17, 2019
esp-idf @ 8a69ffc
examples docs: ESP32-MeshKit-Sense Example CN&EN Update Mar 15, 2019
tools feat: Refactoring Nov 13, 2018
.gitignore docs: Readme update Nov 14, 2018
.gitlab-ci.yml feat: Add ESP32-Mesh-Buttton sample code Jan 25, 2019
.gitmodules feat: Refactoring Nov 13, 2018
LICENSE Init public version Apr 20, 2018 feat: Add documentation for development_kit Jan 21, 2019
mdf_framework.jpg feat: Refactoring Nov 13, 2018 feat: Refactoring Nov 13, 2018

ESP-MESH Development Framework [中文]

alt text

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.

Develop with ESP-MDF

Development Boards


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

Quick Start

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

    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

ESP-MESH Highlights

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

Related Documentation

  • 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.
You can’t perform that action at this time.