espressif/mesh_lite

readme

# ESP-Mesh-Lite Component

[![Component Registry](https://components.espressif.com/components/espressif/mesh_lite/badge.svg)](https://components.espressif.com/components/espressif/mesh_lite)

- [User Guide](https://github.com/espressif/esp-mesh-lite/tree/master/components/mesh_lite/User_Guide.md)

ESP-MESH-LITE is a Wi-Fi networking application of [IoT-Bridge](https://github.com/espressif/esp-iot-bridge), based on the **SoftAP + Station** mode, a set of Mesh solutions built on top of the Wi-Fi protocol. ESP-MESH-LITE allows numerous devices (henceforth referred to as nodes) spread over a large physical area (both indoors and outdoors) to be interconnected under a single WLAN (Wireless Local-Area Network). The biggest difference between ESP-MESH-LITE and [ESP-MESH](https://docs.espressif.com/projects/esp-idf/en/v5.0/esp32/api-guides/esp-wifi-mesh.html) (also known as ESP-WIFI-MESH) is that ESP-MESH-LITE allows sub-devices in the network to independently access the external network, and the transmission information is insensitive to the parent node, which greatly reduces the difficulty to develop the application layer. ESP-MESH-LITE is self-organizing and self-healing, which means the network can be built and maintained autonomously.

## Feature

- Support self-healing of the mesh network
- Support establishing mesh network by root node even if no router is connected
- Support automatically joining the mesh network without configuring router information
- Support setting node only as root node
- Support setting node only as non-root node
- Support setting whether the mesh network is allowed to join
- Support checking whether the joined devices are legal
- Support root node to communicate with child nodes
  - Child node sends broadcast message to parent node
  - Child node sends message to root node
  - Child node sends message to parent node
  - Parent node sends broadcast message to child nodes
- Support encryption of data communication between mesh network

## API

- The application layer only needs to call this API at the code level to enable Mesh-Lite.

	```
    esp_bridge_create_all_netif();

    esp_mesh_lite_config_t mesh_lite_config = ESP_MESH_LITE_DEFAULT_INIT();
    esp_mesh_lite_init(&mesh_lite_config);
	```

## Add component to your project
Please use the component manager command `add-dependency` to add the `mesh_lite` to your project's dependency, during the CMake step the component will be downloaded automatically.

```
idf.py add-dependency "espressif/mesh_lite=*"
```

## Examples

Please use the component manager command `create-project-from-example` to create the project from example template.

```
idf.py create-project-from-example "espressif/mesh_lite=*:mesh_local_control"
```

Then the example will be downloaded in current folder, you can check into it for build and flash.

> Or you can download examples from `esp-mesh-lite` repository: [mesh_local_control](https://github.com/espressif/esp-mesh-lite/tree/master/examples/mesh_local_control)

## Q&A

Q1. I encountered the following problems when using the package manager

```
Executing action: create-project-from-example
CMakeLists.txt not found in project directory /home/username
```

A1. This is because an older version packege manager was used, please run `pip install -U idf-component-manager` in ESP-IDF environment to update.

Q2. When Mesh-Lite is working, I call the `esp_wifi_scan_start` interface but it does not work.

A2. Because Mesh-Lite also has scan operations inside, it is recommended to use the `esp_mesh_lite_wifi_scan_start()` interface to scan. To call the scan interface externally, there needs to be a flag in the scan_done cb to control whether it is an externally called scan. If it is not an externally called scan, do not enter the external scan_done cb for processing.

```
if (esp_mesh_lite_wifi_scan_start(NULL, 3000 / TICK_MS) == ESP_OK) {
   scan_flag = true;
}
```

changelog

- [中文版本](https://github.com/espressif/esp-mesh-lite/blob/master/components/mesh_lite/CHANGELOG_CN.md)

# ChangeLog

# v0.4.0 - 2023-7-12

### Enhancements:

#### Mesh

- feat: Added event posting for OTA failure and success.

#### Bugfix

- fix: When multiple root nodes are far apart and unable to discover each other, they will continuously disconnect and reconnect to the router.
- fix: During the LAN OTA upgrade process, it suddenly paused.
- fix: LAN OTA upgrade failed.

## v0.3.0 - 2023-6-30

### Enhancements:

#### Mesh

- refactor: add wifi_scan_config param for esp_mesh_lite_wifi_scan_start
- chore: Open APIs to allow external access to router information and root SoftAP IP addr
- feat: Support manually specifying a device as a leaf node.

#### Bugfix

- Disable PMF in the Demo example.
- Remove `CONFIG_LWIP_IPV6=n` to resolve the compilation issue of rainmaker_led_light.
- Optimize the mesh_local_control example to resolve the problem of socket connect blocking the event task.

## v0.2.0 - 2023-6-5

### Enhancements:

#### Mesh

- Check if the level exceeds the maximum level when level changes

#### Supported Socs

- ESP32-C2

#### Bugfix

- API compatible with idf5.x and idf4.x versions
- Update documentation to fix links not jumping correctly
- Compile error when MESH_LITE_ENABLE is n

## v0.1.2 - 2023-3-26

#### Supported ESP-IDF Version

- Add v4.3

## v0.1.1 - 2023-3-1

### Enhancements:

- Adapt to iot_bridge(0.*) component.

## v0.1.0 - 2023-2-7

This is the first released version for mesh-lite component, more detailed descriptions about the project, please refer to [ESP-MESH-LITE](https://github.com/espressif/esp-mesh-lite/blob/master/components/mesh_lite/User_Guide.md).

### Enhancements:

#### Mesh

- Support self-healing of the mesh network
- Support establishing mesh network by root node even if no router is connected
- Support automatically joining the mesh network without configuring router information
- Support setting node only as root node
- Support setting node only as non-root node
- Support setting whether the mesh network is allowed to join
- Support checking whether the joined devices are legal
- Support root node to communicate with child nodes
  - Child node sends broadcast message to parent node
  - Child node sends message to root node
  - Child node sends message to parent node
  - Parent node sends broadcast message to child nodes
- Support encryption of data communication between mesh network
- Support OTA upgrade within the mesh network

#### Supported Socs

- ESP32
- ESP32-C3
- ESP32-S2
- ESP32-S3

#### Supported ESP-IDF Version

- v4.4
- v5.0

                                        
                                        - [中文版本](https://github.com/espressif/esp-mesh-lite/blob/master/examples/mesh_local_control/README_CN.md)

# Mesh Local Control Example

## Introduction

This example will introduce how to implement a device connection to a remote external server based on Mesh-Lite. Different from ESP-WIFI-MESH, each device in the Mesh-Lite network can independently access the external network.

This example implements the function of device data transmission in the mesh network to the TCP server.

**It is recommended to compile with esp-idf version 4.4**

## Hardware

* At least 2 x ESP32 development boards
* 1 x router that supports 2.4G

## Process

### Run TCP server

1. Connect PC or the mobile phone to the router.
2. Use a TCP testing tool (any third-party TCP testing software) to create a TCP server.

### Configure the devices

Enter `idf.py menuconfig`, and configure the followings under the submenu "Example Configuration".

 * The router information.
 * ESP-WIFI-MESH network: The network password length should be between 8 and 64 bits (both exclusive), and the network will not be encrypted if you leave the password blank.
 * TCP server: the information of the TCP server run on the PC.

<div align=center>
<img src="device_config.png"  width="800">
<p> Configure the devices </p>
</div>

### Build and Flash

CMake:
```shell
idf.py erase_flash flash monitor -b 921600 -p /dev/ttyUSBx
```

### Run

ESP-WIFI-MESH devices send the real-time device status to the TCP server at an interval of three seconds.
                                    

                                        
                                        - [中文版本](https://github.com/espressif/esp-mesh-lite/blob/master/examples/rainmaker_led_light/README_CN.md)

# LED Light Example(Nova Home)

This example uses the Rainmaker cloud platform to demonstrate the ESP-IoT-Bridge **Wi-Fi router** function. User can configure the device through the `Nova Home` APP and successfully connect to the Rainmaker cloud. The device is connected to the cloud based on Rainmaker, It can also provide other devices with the ability to surf the Internet wirelessly, and form a network with the Mesh-Lite function, which greatly reduces the load on the router and expands the wireless communication range.

## Get Start

### 1. Apps

- [Google PlayStore](https://play.google.com/store/apps/details?id=com.espressif.novahome)
- [Apple App Store](https://apps.apple.com/us/app/nova-home/id1563728960)

### 2. Get Key

Currently, there are two ways for a device to obtain a certificate:

- Self Claiming: After the network is configured, the device directly sends an http request to pull the certificate from the server, which can only be applied on **ESP32-S3** and **ESP32-C3**. Due to the binding with the MAC, the certificate pulled by each device is the same each time.
- Assisted Claiming: When configuring the network, the mobile APP requests a certificate from the server, and then sends it to the device through Bluetooth. It is not bound to the MAC. By default, an account has a limit of 5 applications.

Currently, ESP32-S3 and ESP32-C3 use Self-Claiming to obtain certificates by default, while ESP32 can only use Assisted Claiming to obtain certificates.

> Nova Home's Assisted Claiming method is currently unstable. If you use ESP32 to obtain a certificate, it is recommended to use the [ESP Rainmaker](https://github.com/espressif/esp-rainmaker#phone-apps) APP for Claiming

### 3. IDF environment setup & SDK

Refer to [README](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md#3-set-up-development-environment)

### 4. Mesh-Lite function

- You can choose whether to enable the Mesh-Lite function in the menuconfig `Bridge Configuration -> The Interface used to provide network data forwarding for other devices -> Enable Mesh-Lite`. This example enables this function by default.
- If the Mesh-Lite function is enabled, the first networked device will connect to the target router and serve as the root node, and subsequent devices will be connected to the root node device and act as child nodes to form a Mesh-Lite network. For details, please refer to [Mesh-Lite](https://github.com/espressif/esp-mesh-lite/blob/master/components/mesh_lite/User_Guide.md).

### 5. Build & Flash

After the ESP-IDF environment is successfully set up, you can execute the following commands to compile and burn the firmware.

```
$ cd esp-mesh-lite/examples/rainmaker/led_light
$ idf.py set-target esp32c3
$ idf.py build
$ idf.py flash
```

### 6. Add devices to Nova Home

- Open `Nova Home`, the APP will automatically search for the device to be configured

<img src="./_static/find_devices.jpg" alt="find_devices" width="25%" div align=center />

- Add devices

<img src="./_static/select_devices.jpg" alt="select_devices" width="25%" div align=center />

- Enter distribution network information

<img src="./_static/select_network.jpg" alt="select_network" width="25%" div align=center />

- Pair and connect to configure the network

<img src="./_static/connect_ble.jpg" alt="connect_ble" width="25%" div align=center />

- Distribution network is successful

<img src="./_static/done.jpg" alt="done" width="25%" div align=center />

- LED control

<img src="./_static/control.jpg" alt="control" width="25%" div align=center />

### 7. Precautions

- Currently `Nova Home` only supports Wi-Fi Provisioning over Bluetooth Low Energy, so this example does not support ESP32-S2 chip currently.