ESP-Gateway is a smart gateway solution offered by Espressif. This document describes how to configure and use ESP-Gateway.
- 1. Overview
- 2. Hardware
- 3. Development Environment
- 4. SDK
- 5. Configuration
- 6. Build & Flash & Monitor the Output
- 7. Network Configuration
- 8. Solution Highlights
- 9. GPIO Map
ESP-Gateway is supported by various Espressif chips, as shown in the table below:
| Chip | ESP-IDF Release/v4.4 | ESP-IDF Release/v5.0 |
|---|---|---|
| ESP32 | ||
| ESP32-C3 | ||
| ESP32-S2 | ||
| ESP32-S3 | ||
| ESP32-H2 | TODO | TODO |
| ESP32-C2 | N/A | TODO |
The ESP-Gateway 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 realize personalized smart gateway solutions through 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 | Wireless NIC | Wireless NIC | Wireless NIC | Wireless NIC | Bluetooth LE Gateway | Thread Border Router |
| Ethernet | Wi-Fi Router | Unsupported | Wired NIC | Wired NIC | Wired NIC | Bluetooth LE Gateway | Thread Border Router |
| Cat.1 4G (UART) | 4G Hotspot | 4G NIC | 4G NIC | 4G NIC | 4G NIC | Bluetooth LE Gateway | Thread Border Router |
| Cat.1 4G (USB) | 4G Hotspot | 4G NIC | Unsupported | 4G NIC | 4G NIC | Bluetooth LE Gateway | 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 hotspot, 4G NIC, wireless NIC, wired NIC, Bluetooth LE gateway and Thread Border Router. The table below shows what scenarios each specific ESP chip supports:
| ESP Chips | Wi-Fi Router | 4G Hotspot | 4G NIC | Wireless NIC | Wired NIC | Bluetooth LE Gateway | Thread Border Router |
|---|---|---|---|---|---|---|---|
| ESP32 | TODO | TODO | |||||
| ESP32-C3 | TODO | TODO | |||||
| ESP32-S2 | N/A | TODO | |||||
| ESP32-S3 | 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.
ESP-Gateway 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 can connect to the SoftAP hotspot from the ESP-Gateway to access the Internet.
-
Currently, ESP-Gateway supports lightweight mesh networking — LiteMesh. Users can customize the hierarchical network provision.
-
By enabling
ESP_GATEWAY_SOFTAP_SSID_END_WITH_THE_MACin menuconfig (Gateway Configuration>SoftAP Config), users can add MAC information at the end of SoftAP SSID. -
A single ESP-Gateway 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-Gateway 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-Gateway device can be equipped with a mobile network module with a SIM card and then convert the cellular network into a Wi-Fi signal. The surrounding smart devices can connect to the hotspot from the ESP-Gateway device 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-Gateway 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 (ETH/SDIO/SPI) to gain Internet access.
Please contact [email protected] for source code or firmware for the 4G NIC solution.
ESP-Gateway device can be connected to the PC or MCU through multiple network interfaces (USB/ETH/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:
Please contact [email protected] for source code or firmware for wireless NIC solution.
ESP-Gateway 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-Gateway 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.
Please contact [email protected] for source code or firmware for wired NIC solution.
- 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.pyof ESP-IDF. -
Run the following command to get the full features for esptool:
$ ./components/esptool_py/esptool/esptool.py --help
$ git clone --recursive https://github.com/espressif/esp-gateway.git
-
Get Espressif SDK from ESP-IDF.
-
To ensure that the ESP-IDF is successfully obtained, please enter
idf.py --versionin 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.4branch. -
Patch the ESP-IDF, please refer to Patch for ESP-IDF.
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.4 Not Support Only one network data forwarding interface can be selected ESP-IDF Release/v5.0 Support Currently, SDIO and SPI interfaces cannot be selected at the same time +-- USB <-+-> Computer | RasPi + ethsta0 +-- SPI -- ESP32 --> External WiFi（Router） | +-- SoftAP <-+-> Phone -
The LiteMesh function can be enabled through the Enable LiteMesh option. For details, please refer to LiteMesh.
ETH Configuration
Modem Configuration
Navigate to the esp-gateway directory and run the following command:
$ idf.py menuconfig
After selecting the appropriate configuration items according to Configuration Items, 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.
After the PC or MCU connects to the hotspot from the ESP-Gateway device and obtains the IP address successfully, 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_gateway_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"}
Since ESP32-S2 does not support Bluetooth LE, this network configuration method is not applicable to ESP32-S2.
| Features | Highlights |
|---|---|
| Wi-Fi Router (Station) | Act as a Wi-Fi repeater or Wi-Fi signal amplifier, effectively reducing the burden of the router and expanding Wi-Fi coverage |
| Wi-Fi Router (ETH) | Reduce the number of routers used and lower the deployment cost |
| 4G Hotspot | Network provision is not required; strong mobility; can be used for shared massage chairs, shared power bank and other similar scenarios; low cost (only one shared device equipped with a mobile network module is required, and other devices can connect to the Internet by simply connecting to its hotspot |
| Wireless NIC (ETH) | Driver-free; support using MCU that needs to connect to the network through network cables at any location |
| Wireless NIC (USB) | Driver-free; hot-swappable; easy to use; low development cost |
| Wireless NIC (SPI/SDIO) | High transfer rate |
Please refer to the ESP-Gateway Video which demonstrates some of the features of the ESP-Gateway.
