中文版

ESP-IoT-Bridge Solution

This document describes how to configure and use ESP-IoT-Bridge.

ESP-IoT-Bridge solution focuses on connectivity and communication between various network interfaces in IoT application scenarios, such as SPI, SDIO, USB, Wi-Fi, Ethernet and other network interfaces. In this solution, the bridge device can not only provide net access for other devices, but also be a separate equipment to connect the remote server.

	Wireless Hotspot	Ethernet Interface	USB Interface	SPI Interface	SDIO Interface	Bluetooth LE Interface	Thread Interface
Wi-Fi	Wi-Fi Router	Wi-Fi Router	Wireless NIC	Wireless NIC	Wireless NIC	Bluetooth LE Border Router	Thread Border Router
Ethernet	Wi-Fi Router	Unsupported	Wired NIC	Wired NIC	Wired NIC	Bluetooth LE Border Router	Thread Border Router
Cat.1 4G (UART)	4G Router	4G Router	4G NIC	4G NIC	4G NIC	Bluetooth LE Border Router	Thread Border Router
Cat.1 4G (USB)	4G Router	4G Router	Unsupported	4G NIC	4G NIC	Bluetooth LE Border Router	Thread Border Router

Notes:

NIC: network interface controller
Wi-Fi, Ethernet, Cat.1 4G (UART), and Cat.1 4G (USB) in the first column are interfaces for connecting to the Internet
The wireless hotspot, Ethernet interface, USB interface, SPI interface, SDIO interface, Bluetooth LE interface, and Thread interface in the first row are the interfaces that provide Internet access to other devices.

To summarize, the above table mainly involves the following application scenarios: Wi-Fi Router, 4G Router, 4G NIC, wireless NIC, wired NIC, Bluetooth LE Border Router and Thread Border Router. The table below shows what scenarios each specific ESP chip supports:

ESP Chips	Wi-Fi Router	4G Router	4G NIC	Wireless NIC	Wired NIC	Bluetooth LE Border Router	Thread Border Router
ESP32			(SDIO/SPI)	(SDIO/SPI)	(SDIO/SPI)	TODO	TODO
ESP32-C3			(SPI)	(SPI)	(SPI)	TODO	TODO
ESP32-S2			(SPI)	(USB/SPI)	(USB/SPI)	N/A	TODO
ESP32-S3			(SPI)	(USB/SPI)	(USB/SPI)	TODO	TODO
ESP32-C2			(SPI)	(SPI)	(SPI)	TODO	TODO
ESP32-C6			(SPI)	(SPI)	(SPI)	TODO	TODO
ESP32-H2	TODO	TODO	TODO	TODO	TODO	TODO	TODO

Notes:

ESP32 doesn't have a USB interface and the USB interface for ESP32-C3 can't be used for application communication. If you need to use USB NIC or Cat.1 4G (USB) function, please choose ESP32-S2 or ESP32-S3.
Only ESP32 supports Ethernet interface. Other chips need to connect with external Ethernet chip over SPI. For ESP32 MAC & PHY configuration, please refer to Configure MAC and PHY.
When using the Thread Border Router, an 802.15.4 chip is required, such as ESP32-H2.
For ESP32 SDIO interface, the pin pull-up requirements should be applied to the hardware. For details, please refer to SD Pull-up Requirements.

1.1 Wi-Fi Router

ESP-IoT-Bridge device can connect to the network by connecting to the router via Wi-Fi or by plugging the Ethernet cable into the LAN port of the router. Then other smart devices or PC can connect to the SoftAP hotspot or LAN interface from the ESP-IoT-Bridge to access the Internet.

By enabling BRIDGE_SOFTAP_SSID_END_WITH_THE_MAC in menuconfig (Bridge Configuration > SoftAP Config), users can add MAC information at the end of SoftAP SSID.
Except for the C2, a single device can support up to 15 sub-devices connected simultaneously (refer to AP Basic Configuration for details on max_connection). Multiple sub-devices share the bandwidth.
You need to configure your network if the ESP-IoT-Bridge device connects to the router via Wi-Fi. Currently, the following ways are supported:
- Configure the network on web page
- Configure the network through Wi-Fi Provisioning (Bluetooth LE)（ESP32-S2 not supported）

1.2 4G Router

ESP-IoT-Bridge device can be equipped with a mobile network module with a SIM card. After the network module is connected to the Internet, the PC or MCU can be connected to it through the Ethernet or SoftAP interface to gain Internet access.

The table below shows modules that are compatible with 4G Cat.1.

UART	USB
A7670C	ML302-DNLM/CNLM
EC600N-CN	Air724UG-NFM
SIM76000	EC600N-CNLA-N05
	EC600N-CNLC-N06
	SIMCom A7600C1

1.3 4G NIC

ESP-IoT-Bridge device can be equipped with a mobile network module with a SIM card. After the network module is connected to the Internet, the PC or MCU can be connected to it through the network interface(SDIO/SPI) to gain Internet access.

1.4 Wireless NIC

ESP-IoT-Bridge device can be connected to the PC or MCU through multiple network interfaces (USB/SDIO/SPI). Once connected, the PC or MCU will have an additional network card. These devices can access the Internet after configuring the network.

Use a USB cable to connect the GPIO19/20 of ESP32-S2 or ESP32-S3 with MCU.

USB_DP USB_DM

ESP32-S2/S3 GPIO20 GPIO19
When using SPI/SDIO interface, it is necessary to configure the MCU (Host). For specific dependencies configuration, please refer to Linux_based_readme.
For SDIO hardware connection and MCU (Host) configuration, please refer to SDIO_setup.
For SPI hardware connection and MCU (Host) configuration, please refer to SPI_setup.
This feature requires you to configure the network. Currently, the following ways are supported:
- Configure the network on web page
- Configure the network through Wi-Fi Provisioning (Bluetooth LE)（not support ESP32-S2）

1.5 Wired NIC

ESP-IoT-Bridge device can connect to the network by plugging the Ethernet cable into the LAN port of router. PC or MCU can connect with the ESP-IoT-Bridge device through multiple interfaces (USB/SDIO/SPI) to gain internet access.

Use a USB cable to connect the GPIO19/20 of ESP32-S2 or ESP32-S3 with MCU.

USB_DP USB_DM

ESP32-S2/S3 GPIO20 GPIO19
Using SPI/SDIO interface needs to configure the MCU (Host). For specific dependencies configuration, please refer to Linux_based_readme.
For SDIO hardware connection and MCU (Host) configuration, please refer to SDIO_setup.
For SPI hardware connection and MCU (Host) configuration, please refer to SPI_setup.

2 Hardware

Linux Environment

The Linux environment is necessary for building, flashing, and running.

For Windows users, it is recommended to install a virtual machine for setting up the Linux environment.

ESP devices

ESP devices include ESP chips, ESP modules, ESP development boards, etc.

For Ethernet Router and Ethernet Wireless Card features:

ESP32 requires an additional Ethernet PHY chip.

Other ESP chips need a chip to convert SPI to Ethernet.

For the Portable Wi-Fi feature, ESP device requires an additional mobile network module with SIM card.

USB Cable

USB cable is used to connect PC with ESP devices, flash or download programs, and view logs, etc.

3 Set Up Development Environment

If you are familiar with the ESP development environment, you can easily understand the following steps. If you are not familiar with a certain part, such as building or flashing, please refer to ESP-IDF Programming Guide.

3.1 Download & Set up Toolchain

Please refer to Standard Toolchain Setup for Linux to download and set up the toolchain for building your project.

3.2 Flash/Download Tool

The flash tool is located under ./components/esptool_py/esptool/esptool.py of ESP-IDF.
Run the following command to get the full features for esptool:

$ ./components/esptool_py/esptool/esptool.py --help

3.3 Clone ESP-IoT-Bridge Repository

$ git clone https://github.com/espressif/esp-iot-bridge.git

4 Get SDK

Get Espressif SDK from ESP-IDF.
To ensure that you have successfully installed the complete ESP-IDF, please enter idf.py --version in the terminal. If the output is similar to ESP-IDF v5.0.5-493-ga463942e14, it means the installation was successful. For detailed installation and configuration instructions, please refer to the Quick Start Guide.
After successfully obtaining ESP-IDF, please switch the ESP-IDF version to release/v5.0 or above.

5 Configuration

Select the interface for connecting to the Internet

Select the interface for forwarding network packets for other devices

Users can choose a combination of different interfaces to achieve different functions.

Whether to support the selection of multiple network data forwarding interfaces to provide network functions to different devices?

IDF Version		Note
ESP-IDF Release/v5.0-v5.3	Support	Currently, SDIO and SPI interfaces cannot be selected at the same time

                             +-- USB  <-+->  Computer
                             |
RasPi + ethsta0 +-- SPI -- ESP32 --> External WiFi（Router）
                             |
                             +-- SoftAP <-+-> Phone

ETH Configuration

Modem Configuration

6 Build Flash Monitor

6.1 Build the Project

Navigate to the esp-iot-bridge directory and run the following command:

$ idf.py menuconfig

After selecting the appropriate configuration items according to Configuration, run the following command to generate the bin file.

$ idf.py build

6.2 Flash & Monitor the Output

Connect the ESP device to the PC with a USB cable, and make sure the right port is used.

6.2.1 Flash onto the Device

$ idf.py flash

6.2.3 Monitor the Output

$ idf.py monitor

You can combine building, flashing and monitoring into one step by running: idf.py build flash monitor.

7 Network Configuration

Configure Network on Web Page

When a PC or MCU connects to the ESP-IoT-Bridge device via hotspot, USB, SPI, SDIO, or Ethernet and successfully obtains an IP address, it can configure the network on the web page by accessing the gateway IP.

Configure Network through Wi-Fi Provisioning

7.2.1 APP Get

Android:
- Bluetooth LE Provisioning app on Play Store.
- Source code on GitHub: esp-idf-provisioning-android.
iOS:
- Bluetooth LE Provisioning app on app store
- Source code on GitHub: esp-idf-provisioning-ios

7.2.2 QR Code Scanning

Scan the QR code shown in the log to configure the network.

I (1604) QRCODE: {"ver":"v1","name":"PROV_806314","pop":"abcd1234","transport":"ble"}
I (1607) NimBLE: GAP procedure initiated: advertise;
I (1618) NimBLE: disc_mode=2
I (1622) NimBLE:  adv_channel_map=0 own_addr_type=0 adv_filter_policy=0 adv_itvl_min=256 adv_itvl_max=256
I (1632) NimBLE:


  █▀▀▀▀▀█ ▄█ ▄▄ █▄▀ ▀▀█▀█▀█ █▀▀▀▀▀█
  █ ███ █ ▄█▀█ ▄ ▄▄▄█▀ ▀  ▀ █ ███ █
  █ ▀▀▀ █ ▄ █ ▀▄ ▄█ ▄▀▀▀▀▀█ █ ▀▀▀ █
  ▀▀▀▀▀▀▀ ▀ ▀ █ ▀ █ ▀▄▀▄█ █ ▀▀▀▀▀▀▀
  ▀▀█▀█ ▀█▀█▀ ▀█▄ ▄▀▀▄▄▄▄█▄▀▄▀ ▀▄█▄
  ██▀▄ █▀▄██▄█▀▀ █ ▀█ ▀█▄▄ █▀▄  ▄█
  ▀ █   ▀▀ ▀▄▀▄▀ ▀█▀▀▄▄▄▄▀ ▀▄▀▀ ▄▀▄
  ▀▀█▄█▀▀▀▀▀▄ ▄▀ ▀▀▀▀▄ █▀▄▀█ ▀█ ▄▀▄
  ▀▀▄▄ █▀ ▀█▄ ▀▀▀▀█▀▀▄ ▄    ▄▀▀▀ █▄
  ▄▄█▄▄ ▀█  ▀█▀▀ ▀▄ ▄▄ ▄ ▄  ▄█▀ ▄▀▄
  ▄▀▀█▀ ▀  █▀▀▄█▀ ▄▀██▀  ▀▀▄▄█▀ ▄ ▄
  █  ▄▄█▀▄▄█  ▄ ▀█▀▀█▄ █▀▄█ █▀▄▄▄▄▄
  ▀ ▀▀  ▀▀▄▄█ ▀▀▀▀▄██▄ ▄ ▄█▀▀▀██▄▄█
  █▀▀▀▀▀█ ▀ ██▀ █▀  ▄  ▄ ▄█ ▀ █ ▄▀
  █ ███ █ █▀█▀█▀ ▀█▀█▄█▄█ █▀▀██▀▄▀
  █ ▀▀▀ █ █▀▄  ▀ █▄▀█▄██ ▄█ ▀█▄▀█▀
  ▀▀▀▀▀▀▀ ▀▀ ▀ ▀▀▀▀▀ ▀  ▀▀▀ ▀▀   ▀


I (1798) esp_bridge_wifi_prov_mgr: If QR code is not visible, copy paste the below URL in a browser.
https://espressif.github.io/esp-jumpstart/qrcode.html?data={"ver":"v1","name":"PROV_806314","pop":"abcd1234","transport":"ble"}

Note:

Since ESP32-S2 does not support Bluetooth LE, this network configuration method is not applicable to ESP32-S2.
By default, PROV_MODE is set to PROV_SEC2_DEV_MODE. For mass-produced firmware, it is recommended to choose PROV_SEC2_PROD_MODE and add your own salt and verifier. For specific instructions, please refer to wifi_prov_mgr.c.

8 OTA

OTA Firmware Upgrade Using a Browser

Introduction

When a PC or MCU connects to the ESP-IoT-Bridge device via hotspot, USB, SPI, SDIO, or Ethernet and successfully obtains an IP address, it can perform a web-based OTA (Over-the-Air) update by accessing the gateway IP. After opening the web page hosted on the Web Server in a browser, it can choose to enter the OTA upgrade page and proceed with firmware updates through the web interface.

9 Solution Highlights

Feature		Advantage	Application Scenario
Wi-Fi Router	Ethernet/Station to SoftAP	Reduce router load and extend signal coverage	● Large-sized and multi-floor house ● Large-sized office space ● Conference site ● Hotel ● Photovoltaic inverter and wind power
Wi-Fi Router	Station to Ethernet	Driver-free, hot-pluggable, user-friendly, and cost-effective to develop	Deploy networks for devices that do not support Wi-Fi and need to be networked via a network cable ● Attendance machine ● Cash register
Network Card	Wired/Wireless LAN card (USB)	Driver-free, hot-pluggable, user-friendly, and cost-effective to develop	● Photovoltaic inverter and wind power ● Closed Circuit Television (CCTV) and IP Camera ● Industrial control panel
	Wired/Wireless Network Card (SPI/SDIO)	Stable with high speed	● Photovoltaic inverter and wind power ● Closed Circuit Television (CCTV) and IP Camera ● Robot ● Industrial control panel
	4G Network Card	Plug-and-play and no provisioning required with high mobility	Use with wired/wireless LAN cards to provide a wider range of Internet access options for devices ● Charging pile ● Attendance machine ● Closed Circuit Television (CCTV) ● Environmental Monitoring
4G Hotspot		Wireless connection and no provisioning required with high mobility	● Shared scenarios such as shared massage chair and shared power bank ● Unmanned convenience store
BLE Border Router		Interconnect BLE devices with other devices	● Establishing a BLE medical sensing ecosystem ● Supermarket electronic price tag management ● Overall smart home Solution
Thread Border Router		Interconnect Thread devices with other devices	Smart home device interconnection

Please refer to the ESP-IoT-Bridge Video which demonstrates some of the features of the ESP-IoT-Bridge.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

User_Guide.md

User_Guide.md

ESP-IoT-Bridge Solution

Table of Contents

1 Overview

1.1 Wi-Fi Router

1.2 4G Router

1.3 4G NIC

1.4 Wireless NIC

1.5 Wired NIC

2 Hardware

3 Set Up Development Environment

3.1 Download & Set up Toolchain

3.2 Flash/Download Tool

3.3 Clone ESP-IoT-Bridge Repository

4 Get SDK

5 Configuration

6 Build Flash Monitor

6.1 Build the Project

6.2 Flash & Monitor the Output

6.2.1 Flash onto the Device

6.2.3 Monitor the Output

7 Network Configuration

Configure Network on Web Page

Configure Network through Wi-Fi Provisioning

7.2.1 APP Get

7.2.2 QR Code Scanning

8 OTA

OTA Firmware Upgrade Using a Browser

Introduction

9 Solution Highlights

10 GPIO Map

Files

User_Guide.md

Latest commit

History

User_Guide.md

File metadata and controls

ESP-IoT-Bridge Solution

Table of Contents

1 Overview

1.1 Wi-Fi Router

1.2 4G Router

1.3 4G NIC

1.4 Wireless NIC

1.5 Wired NIC

2 Hardware

3 Set Up Development Environment

3.1 Download & Set up Toolchain

3.2 Flash/Download Tool

3.3 Clone ESP-IoT-Bridge Repository

4 Get SDK

5 Configuration

6 Build Flash Monitor

6.1 Build the Project

6.2 Flash & Monitor the Output

6.2.1 Flash onto the Device

6.2.3 Monitor the Output

7 Network Configuration

Configure Network on Web Page

Configure Network through Wi-Fi Provisioning

7.2.1 APP Get

7.2.2 QR Code Scanning

8 OTA

OTA Firmware Upgrade Using a Browser

Introduction

9 Solution Highlights

10 GPIO Map