DOCSEARCHbyAlgolia
Submit Docs

ESP-IoT-Bridge

repository·master·Indexed 42 days ago

https://github.com/espressif/esp-iot-bridge

A framework for bridging network interfaces such as Wi-Fi, Ethernet, USB, SPI, and SDIO to enable internet connectivity across IoT hardware. It provides high-level APIs for network interface initialization, network segment conflict management, and NAT-based packet forwarding. Includes a patch utility system for ESP-IDF components requiring ESP-IDF v4.4+ and CMake v3.16+.

Tokens
10.6K
Snippets
32
Records
65
Agent score
53%

What's inside ESP-IoT-Bridge

  1. Overview of the ESP-IoT-Bridge Solution

    master

    ESP-IoT-Bridge is a framework designed to facilitate connection and communication between various network interfaces in IoT application scenarios. It enables interconnection between interfaces such as SPI, SDIO, USB, Wi-Fi, and Ethernet.

    This solution can be combined with other frameworks like Wi-Fi Mesh Lite or Rainmaker to create complex networking applications. Common use cases include wireless hotspots, wired network cards, and 4G internet access modules.

  2. Overview of the ESP-IoT-Bridge solution framework

    master

    ESP-IoT-Bridge is a framework built upon the IoT-Bridge component designed to facilitate communication and connectivity between various network interfaces in IoT scenarios. It enables bridging between interfaces such as SPI, SDIO, USB, Wi-Fi, and Ethernet.

    This framework can be integrated with other solutions like Wi-Fi Mesh Lite or Rainmaker to create complex networking applications. Common use cases include wireless hotspots, wireless network interface cards (NICs), wired NICs, and 4G internet access.

  3. Overview of ESP-IoT-Bridge solution features and scenarios

    master

    The ESP-IoT-Bridge provides several networking solutions depending on the hardware interface and connectivity requirements. Key solutions include:

    Wi-Fi Router

    • Ethernet/Station to SoftAP: Reduces router load and extends signal coverage. Ideal for large houses, offices, hotels, and renewable energy sites (photovoltaic/wind).
    • Station to Ethernet: Provides network access for devices that only support wired Ethernet (e.g., attendance machines, cash registers) via a Wi-Fi station.

    Network Card (NIC) Solutions

    • Wired/Wireless LAN card (USB): Driver-free and hot-pluggable. Suitable for CCTV, IP cameras, and industrial control panels.
    • Wired/Wireless Network Card (SPI/SDIO): High-speed, stable connection for robots and industrial control.
    • 4G Network Card: Plug-and-play high mobility for charging piles, CCTV, and environmental monitoring.

    Other Connectivity Solutions

    • 4G Hotspot: High mobility wireless connection for shared scenarios like unmanned convenience stores or shared power banks.
    • BLE Border Router: Interconnects BLE devices with other network types (e.g., medical sensing ecosystems, smart homes).
    • Thread Border Router: Interconnects Thread-based smart home devices with other networks.

  4. Overview of the 4G to Hotspot example

    master
    The 4G to Hotspot example demonstrates networking capabilities by enabling packet forwarding between network interfaces. It configures the ESP32 to act as a WiFi Soft Access Point (AP) and uses Network Address Translation (NAT) to forward packets between the WiFi interface and a PPP (Point-to-Point Protocol) network interface connected to a 4G modem.

  5. Wireless NIC Example Overview

    master

    The Wireless NIC example implements packet forwarding between different network interfaces. It allows an ESP32 series chip to act as a bridge between a PC or MCU and a Station network interface. The ESP32 uses Network Address Translation (NAT) to forward data packets in and out of the Station network.

    Supported interfaces for connecting to a PC or MCU include:

    • USB
    • Ethernet (ETH)
    • SPI
    • SDIO

  6. Supported ESP Chips and ESP-IDF Versions

    master

    ESP-IoT-Bridge supports a wide range of Espressif chips across various ESP-IDF releases.

    Supported Chips:

    • ESP32, ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-S2, ESP32-S3.

    Key Compatibility Notes:

    • USB Support: To use USB NIC or Cat.1 4G (USB) functionality, you must use ESP32-S2 or ESP32-S3. ESP32 and ESP32-C3 do not support these features.
    • Ethernet: Only the original ESP32 has a built-in Ethernet interface. Other chips require an external Ethernet chip connected via SPI.
    • Thread Border Router: Requires an 802.15.4 compatible chip, such as the ESP32-H2.
    • SDIO: Hardware requires pull-up resistors on specific pins.

  7. Use the Wired NIC example for packet forwarding

    master

    The Wired NIC example implements packet forwarding between network interfaces, allowing an ESP32 series chip to act as a bridge between an Ethernet network and a PC or MCU. The chip uses NAT (Network Address Translation) to forward data packets.

    Supported targets include:

    • ESP32
    • ESP32-C2
    • ESP32-C3
    • ESP32-C6
    • ESP32-C5
    • ESP32-S2
    • ESP32-S3
    • ESP32-C61

  8. Switch Network Interface Roles for SPI/SDIO and Ethernet

    master

    By default, Ethernet and SPI/SDIO cannot act as both an external network interface (connecting to the internet) and a data forwarding interface (providing access to other devices) simultaneously. However, you can manage these roles using the following methods:

    • SPI/SDIO: Can enable both to create separate WAN/LAN interfaces and switch roles at runtime using:
      • esp_bridge_spi_set_netif_type(IOT_BRIDGE_NETIF_WAN | IOT_BRIDGE_NETIF_LAN)
      • esp_bridge_sdio_set_netif_type(IOT_BRIDGE_NETIF_WAN | IOT_BRIDGE_NETIF_LAN)
    • Ethernet: Can be configured to automatically switch between WAN and LAN roles based on the network environment.

  9. Configure Wireless or Wired NIC Mode

    master

    In NIC mode, the ESP-IoT-Bridge acts as a network card for a host (PC or MCU) using USB, SDIO, or SPI interfaces.

    USB Connection (ESP32-S2/S3): Connect the USB cable between the MCU and the ESP32-S2/S3 pins:

    • USB_DP: GPIO20
    • USB_DM: GPIO19

    SPI/SDIO Connection: Requires host-side configuration. Refer to the following guides for hardware wiring and host setup:

    • Linux Host: See Linux_based_readme.md.
    • SDIO Setup: See SDIO_setup.md.
    • SPI Setup: See SPI_setup.md.

    Provisioning: Requires network provisioning via Web or Wi-Fi Provisioning (Bluetooth LE). Note that Bluetooth LE provisioning is not supported on ESP32-S2.

  10. Configure network via Wi-Fi Provisioning

    master

    You can use Bluetooth LE (BLE) provisioning to configure the network.

    Using Mobile Apps

    Using QR Code Scanning

    Scan the QR code printed in the serial logs. If the QR code is not visible in your terminal, copy the URL provided in the log and paste it into a browser to generate the code: https://espressif.github.io/esp-jumpstart/qrcode.html?data=<DATA_FROM_LOG>

    Important Notes:

    • ESP32-S2 Compatibility: ESP32-S2 does not support Bluetooth LE, so this method is not available for that chip.
    • Security Modes: By default, PROV_MODE is PROV_SEC2_DEV_MODE. For production, use PROV_SEC2_PROD_MODE and define your own salt and verifier in wifi_prov_mgr.c.
    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"}

  11. Configure Raspberry Pi Specific Setup

    master

    For Raspberry Pi hosts, follow these specific requirements:

    1. Kernel Setup: Use a full Raspbian installation. Ensure kernel version is v4.19 or higher. Install kernel headers using sudo apt install raspberrypi-kernel-headers.
    2. Verify Kernel Headers: Run ls /lib/modules/$(uname -r)/build. If this fails, the headers are not installed correctly. You may need to use rpi-source to obtain them.
    3. Install Utilities: Install raspi-gpio and the Bluetooth stack (pi-bluetooth).
    # Install kernel headers
$ sudo apt update
$ sudo apt install raspberrypi-kernel-headers

# Verify kernel headers installation
$ ls /lib/modules/$(uname -r)/build

# Install additional tools
$ sudo apt install raspi-gpio
$ sudo apt install pi-bluetooth

  12. Configure Wi-Fi Router Mode

    master

    In Wi-Fi Router mode, the ESP-IoT-Bridge connects to a router via Wi-Fi or Ethernet, and provides internet access to clients via a SoftAP hotspot or an Ethernet port.

    Configuration & Limits:

    • SSID Customization: Enable BRIDGE_SOFTAP_SSID_END_WITH_THE_MAC in menuconfig (Bridge Configuration > SoftAP Config) to append the MAC address to the SoftAP SSID.
    • Client Limit: Except for the ESP32-C2, a single device supports up to 15 simultaneous client connections (bandwidth is shared).
    • Provisioning: If connecting to a router via Wi-Fi, you must perform network provisioning. Supported methods are:
      1. Web-based provisioning.
      2. Wi-Fi Provisioning via Bluetooth LE (Note: Not supported on ESP32-S2).