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.
- 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 Map
ESP-IoT-Bridge is supported by various Espressif chips, as shown in the table below:
Chip | ESP-IDF Release/v4.3 | ESP-IDF Release/v4.4 | ESP-IDF Release/v5.0 | ESP-IDF Release/v5.1 |
---|---|---|---|---|
ESP32 | ||||
ESP32-C3 | ||||
ESP32-S2 | ||||
ESP32-S3 | ||||
ESP32-C2 | N/A | N/A | ||
ESP32-C6 | N/A | N/A | N/A | |
ESP32-H2 | N/A | N/A | N/A |
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:
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:
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.
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. -
A single ESP-IoT-Bridge device supports up to 10 stations connected at the same time, and bandwidth is shared by these stations.
-
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)
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 |
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.
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:
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.
- 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.
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.
Please refer to Standard Toolchain Setup for Linux to download and set up the toolchain for building your project.
-
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
$ git clone https://github.com/espressif/esp-iot-bridge.git
-
Get Espressif SDK from ESP-IDF.
-
To ensure that the ESP-IDF is successfully obtained, please enter
idf.py --version
in the terminal. If the output is similar toESP-IDF v4.4-dev-3675-g35b20cadce
, ESP-IDF is installed successfully. For detailed installation and configuration instructions, please refer to ESP-IDF Get Started. -
After successfully obtaining ESP-IDF, please switch its version to the
release/v4.3
or a higher version.
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/v4.3/v4.4 Not Support Only one network data forwarding interface can be selected ESP-IDF Release/v5.0/v5.1 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
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
Connect the ESP device to the PC with a USB cable, and make sure the right port is used.
$ idf.py flash
$ idf.py monitor
You can combine building, flashing and monitoring into one step by running:
idf.py build flash monitor
.
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.
- 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
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 toPROV_SEC2_DEV_MODE
. For mass-produced firmware, it is recommended to choosePROV_SEC2_PROD_MODE
and add your ownsalt
andverifier
. For specific instructions, please refer to wifi_prov_mgr.c.
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.
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 |
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.