中文版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.Table of Contents
1 Overview
2 Hardware
3 Development Environment
4 SDK
5 Configuration
6 Build Flash Monitor
7 Network Configuration
8 OTA
9 Solution Highlights
10 GPIO Map1 Overview
ESP-IoT-Bridge is supported by various Espressif chips, as shown in the table below:
ChipESP-IDF Release/v5.2ESP-IDF Release/v5.3ESP-IDF Release/v5.4ESP-IDF Release/v5.5ESP-IDF Release/v6.0ESP-IDF Release/v6.1
ESP32alt textalt textalt textalt textalt textalt text
ESP32-C3alt textalt textalt textalt textalt textalt text
ESP32-S2alt textalt textalt textalt textalt textalt text
ESP32-S3alt textalt textalt textalt textalt textalt text
ESP32-C2alt textalt textalt textalt textalt textalt text
ESP32-C6alt textalt textalt textalt textalt textalt text
ESP32-C5 alt textalt textalt textalt text
ESP32-C61 alt textalt textalt textalt text
The ESP-IoT-Bridge solution provides several network interfaces, which can be divided into two main categories:
Interfaces for connecting to the Internet
Interfaces for forwarding network packets for other devices so that they can access the Internet
Users can achieve personalized network interface connection solutions through a variety of different network interface combinations to maximize the network advantages of espressif chips.
A variety of functions can be achieved depending on the combination of interfaces, as shown in the table below:
SoftAPEthernet InterfaceUSB InterfaceSPI/SDIOBluetooth LE InterfaceThread Interface
StationWi-Fi RouterWi-Fi RouterWireless NICWireless NICBluetooth LE Border RouterThread Border Router
EthernetWi-Fi RouterUnsupportedWired NICWired NICBluetooth LE Border RouterThread Border Router
SPI/SDIOMCU Wi-Fi BridgeMCU Ethernet BridgeMCU USB BridgeUnsupportedUnsupportedUnsupported
Cat.1 4G (UART)4G Router4G Router4G NIC4G NICBluetooth LE Border RouterThread Border Router
Cat.1 4G (USB)4G Router4G RouterUnsupported4G NICBluetooth LE Border RouterThread Border Router
Notes:
Station, Ethernet, Cat.1 4G (UART/USB), and SPI/SDIO in the first column are interfaces for connecting to the Internet.
SoftAP, Ethernet interface, USB interface, SPI/SDIO interface, Bluetooth LE interface, and Thread interface in the first row are the interfaces that provide Internet access to other devices.
In the current version, Ethernet and SPI/SDIO cannot act as both external netif (connecting to an external network) and data forwarding netif (forwarding data for other devices) at the same time. However, SPI/SDIO can enable both to create separate WAN/LAN netifs, and switch roles at runtime via esp_bridge_spi_set_netif_type() / esp_bridge_sdio_set_netif_type() (IOT_BRIDGE_NETIF_WAN or IOT_BRIDGE_NETIF_LAN). Ethernet can also enable Ethernet acts as WAN or LAN automatically to switch roles based on the network environment.
To summarize, the above table mainly involves the following application scenarios: Wi-Fi Router, 4G Router, 4G NIC, wireless NIC, wired NIC, MCU Wi-Fi Bridge, MCU Ethernet Bridge, MCU USB Bridge, Bluetooth LE Border Router and Thread Border Router. The table below shows what scenarios each specific ESP chip supports:
ESP ChipsWi-Fi Router4G Router4G NICWireless NICWired NICMCU Wi-Fi BridgeMCU Ethernet BridgeMCU USB BridgeBluetooth LE Border RouterThread Border Router
ESP32alt textalt textalt text(SDIO/SPI)alt text(SDIO/SPI)alt text(SDIO/SPI)alt text(SDIO/SPI)alt text(SDIO/SPI)N/ATODOTODO
ESP32-C3alt textalt textalt text(SPI)alt text(SPI)alt text(SPI)alt text(SPI)alt text(SPI)N/ATODOTODO
ESP32-S2alt textalt textalt text(SPI)alt text(USB/SPI)alt text(USB/SPI)alt text(USB/SPI)alt text(USB/SPI)alt text(USB/SPI)N/ATODO
ESP32-S3alt textalt textalt text(SPI)alt text(USB/SPI)alt text(USB/SPI)alt text(USB/SPI)alt text(USB/SPI)alt text(USB/SPI)TODOTODO
ESP32-C2alt textalt textalt text(SPI)alt text(SPI)alt text(SPI)alt text(SPI)alt text(SPI)N/ATODOTODO
ESP32-C6alt textalt textalt text(SPI)alt text(SPI)alt text(SPI)alt text(SDIO/SPI)alt text(SDIO/SPI)N/ATODOTODO
ESP32-C5alt textalt textalt text(SPI)alt text(SPI)alt text(SPI)alt text(SDIO/SPI)alt text(SDIO/SPI)N/ATODOTODO
ESP32-C61alt textalt textTODOTODOTODOTODOTODON/ATODOTODO
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.Notes
Current releases require ESP-IDF ≥5.2 (see idf_component.yml). CI validates against release 5.2–5.5 and 6.0–6.1.
Starting from iot_bridge v1.0.0, USB features require ESP-IDF v5.1.4 or later. For systems using ESP-IDF 5.0-5.1.3:
Recommended: Upgrade ESP-IDF to ≥ v5.2.0
Legacy compatibility: Downgrade iot_bridge to v0.11.9 (the latest esp_tinyusb component does not support RNDIS; use this configuration if RNDIS is required)
```yml
espressif/iot_bridge:
version: "0.11.9"
usb_device:
path: components/usb/usb_device
git: https://github.com/espressif/esp-iot-bridge.git
rules:
- if: "target in [esp32s2, esp32s3]"
- if: "idf_version < 5.1.4"
Component VersionESP-IDF VersionUSB SupportRNDIS SupportSolution
iot_bridge ≥1.0.0ESP-IDF ≥5.1.4 (incl. 6.1)✅ Supported❌ UnsupportedUse esp_tinyusb component
iot_bridge ≥1.0.0ESP-IDF 5.0-5.1.3❌ Unsupported❌ UnsupportedUpgrade ESP-IDF or downgrade to iot_bridge 0.11.9
iot_bridge 0.11.9ESP-IDF 5.0+✅ Supported✅ Supported (idf5.0-5.1.3)espressif/iot_bridge: version: "0.11.9"usb_device: path: components/usb/usb_device git: https://github.com/espressif/esp-iot-bridge.git rules: - if: "target in esp32s2, esp32s3" - if: "idf_version < 5.1.4"
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.
UARTUSB
A7670CML302-DNLM/CNLM
EC600N-CNAir724UG-NFM
SIM76000EC600N-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_DPUSB_DM
ESP32-S2/S3GPIO20GPIO19
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_DPUSB_DM
ESP32-S2/S3GPIO20GPIO19
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
