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.

Overview

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.

Framework

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

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

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.

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 command git 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 variable IDF_PATH. Please refer to Add 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

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.

chansdad/esp-mdf