espressif/iot_bridge

readme

# ESP-IoT-Bridge Component

[![Component Registry](https://components.espressif.com/components/espressif/iot_bridge/badge.svg)](https://components.espressif.com/components/espressif/iot_bridge)

- [User Guide](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md)

ESP-IoT-Bridge solution is mainly aimed at bridging between various network interfaces in IoT application scenarios, such as SPI, SDIO, USB, Wi-Fi, Ethernet and other network interfaces. ESP-IoT-Bridge is a smart bridge solution offered by Espressif. 

## Feature

- Provide Wi-Fi router function that can provide accessing the Internet for other devices
- Provide Wi-Fi network card function for other devices to access the Internet
- Provide wired ethernet network card function for other devices to access the Internet
- Provide 4G network card function for other devices to access the Internet
- Provide 4G Hotspot function that can provide accessing the Internet for other devices

## API

- The application layer only needs to call this API at the code level, and select the corresponding `external netif` and `dataforwarding netif` under menuconfig(Bridge Configuration).

	```
	esp_bridge_create_all_netif()
	```

    > Note: By default, you only need to call this API, or you can manually call the corresponding netif api, such as `esp_bridge_create_xxx_netif`.

- Registered users check network segment conflict interface.

	```
	esp_bridge_network_segment_check_register
	```

- Check whether other data forwarding netif IP network segments conflict with incoming netif network segments.

	```
	esp_bridge_netif_network_segment_conflict_update
	```

    > Note: Generally, it is called in the event callback when external netif (Station, Ethernet, 4G) obtains IP.

## Add component to your project
Please use the component manager command `add-dependency` to add the `iot_bridge` to your project's dependency, during the CMake step the component will be downloaded automatically.

```
idf.py add-dependency "espressif/iot_bridge=*"
```

## Examples

Please use the component manager command `create-project-from-example` to create the project from example template.

```
idf.py create-project-from-example "espressif/iot_bridge=*:wifi_router"
```

Then the example will be downloaded in current folder, you can check into it for build and flash.

> Or you can download examples from `esp-iot-bridge` repository: [wifi_router](https://github.com/espressif/esp-iot-bridge/tree/master/examples/wifi_router)

## Q&A

Q1. I encountered the following problems when using the package manager

```
Executing action: create-project-from-example
CMakeLists.txt not found in project directory /home/username
```

A1. This is because an older version packege manager was used, please run `pip install -U idf-component-manager` in ESP-IDF environment to update.

changelog

# ChangeLog

## v0.11.3 - 2024.4.7

### Chore

- include lwip/lwip_napt.h

## v0.11.2 - 2024.3.29

### Enhancements

- Support setting IP info for netifs

## v0.11.1 - 2024.2.18

### Chore

- Change some log output level
- fix undefined IP_NAPT_PORTMAP

## v0.11.0 - 2023.12.8

### Enhancements

- Update the DNS information of the external netif to the data forwarding netif.

## v0.10.0 - 2023.11.13

### Enhancements

- Support ESP32C6 SDIO netif
- Add esp_bridge_wifi_set_config API
- Remove modom function on idf4.3

## v0.9.0 - 2023.9.21

### Enhancements

- Support SPI and SDIO drivers as external netif

## v0.8.0 - 2023.9.15

### Enhancements

- Update SPI and SDIO drivers

## v0.7.2 - 2023.8.10

### Enhancements

- Update iot_bridge component yml, the idf component manager now supports uploading components with rules.

## v0.7.1 - 2023.8.1

### Enhancements

- Add limit to the length of the SoftAP SSID and password strings

### Docs

- Update images url

## v0.7.0 - 2023.6.20

### Enhancements

- Add 4g nic, wired nic, wireless nic examples

## v0.6.0 - 2023.6.19

### Supported ESP-IDF Version

- Add v5.1

### Supported Socs

- ESP32-C6
- ESP32-H2

### Enhancements

- feature: Make sure SOFTAP_MAX_CONNECT_NUMBER is not larger than DHCPS_MAX_STATION_NUM

### Docs

- Update images and hyperlinks

## v0.5.0 - 2023.4.3

### Supported Socs

- ESP32-C2

## v0.4.0 - 2023.3.16

### Supported ESP-IDF Version

- Add v4.3

## v0.3.0 - 2023.3.9

### Enhancements

- Add multiple bridging interfaces(Ethernet, USB, SPI, SDIO)

## v0.2.0 - 2023.2.24

### Enhancements

- Provide 4G network card function for other devices to access the internet
- Provide 4G Hotspot function that can provide accessing the internet for other devices

## v0.1.0 - 2022.12.26

This is the first released version for iot-bridge component, more detailed descriptions about the project, please refer to [User_Guide](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md).

### Enhancements

- Provide Wi-Fi router function that can provide accessing the internet for other devices
- Provide Wi-Fi network card function for other devices to access the internet
- Provide wired ethernet network card function for other devices to access the internet

### Supported Socs

- ESP32
- ESP32-C3
- ESP32-S2
- ESP32-S3

### Supported ESP-IDF Version

- v4.4
- v5.0

                                        
                                        | Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 | ESP32-H2 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- |

# 4G to Hotspot example

## Overview

This example focuses on the networking part, enables forwarding packets between network interfaces. It creates a WiFi soft AP, which uses NAT to forward packets to and from the PPP network interface.

<img src="https://raw.githubusercontent.com/espressif/esp-iot-bridge/master/components/iot_bridge/docs/_static/4g_router_en.png" style="zoom:80%;" />

### How to use example
#### Hardware Required
- A 4G module
- An esp32 series development board
- A Micro-USB cable for power supply and programming

Follow detailed instructions provided specifically for this example.

#### Choose the interface of the modem

You can select the interface (UART or USB) connected to the Modem in `Component config → Bridge Configuration → Modem Configuration` of `menuconfig`.

#### Build and Flash
Run `idf.py flash monitor` to build, flash and monitor the project.

Once a complete flash process has been performed, you can use `idf.py app-flash monitor` to reduce the flash time.

(To exit the serial monitor, type `Ctrl-]`. Please reset the development board f you cannot exit the monitor.)

For more information, see [User_Guide.md](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md).

                                    

                                        
                                        | Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 | ESP32-H2 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- |

# 4G NIC example

## Overview

This example focuses on the networking part, enabling packet forwarding between network interfaces. It can be connected to PC or MCU through multiple network interfaces (ETH/SPI/SDIO), and ESP32 series chips use NAT to forward data packets in and out of the PPP network interface.

<img src="https://raw.githubusercontent.com/espressif/esp-iot-bridge/master/components/iot_bridge/docs/_static/4g_nic_en.png" style="zoom:80%;" />

### How to use example

#### Hardware Required

**Required**
- A 4G module
- An esp32 series development board
- A Micro-USB cable for power supply and programming

**Optional**
- One Ethernet cable
- A USB cable for communication
- Some DuPont cables to connect to the SPI or SDIO interface of the MCU

Follow detailed instructions provided specifically for this example.

#### Choose the interface of the modem

You can select the interface (UART or USB) connected to the Modem in `Component config → Bridge Configuration → Modem Configuration` of `menuconfig`.

#### Choose the interface used to provide network data forwarding for other devices

You can select the interface (ETH/SPI/SDIO) connected to the PC/MCU in `Component config → Bridge Configuration → The interface used to provide network data forwarding for other devices` of `menuconfig`.

#### Build and Flash
Run `idf.py flash monitor` to build, flash and monitor the project.

Once a complete flash process has been performed, you can use `idf.py app-flash monitor` to reduce the flash time.

(To exit the serial monitor, type `Ctrl-]`. Please reset the development board f you cannot exit the monitor.)

For more information, see [User_Guide.md](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md).

                                    

                                        
                                        | Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 | ESP32-H2 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- |

# Wi-Fi Router example

## Overview

This example focuses on the networking part, enables forwarding packets between network interfaces. It creates a WiFi soft AP, which uses NAT to forward packets to and from the Station network interface.

<img src="https://raw.githubusercontent.com/espressif/esp-iot-bridge/master/components/iot_bridge/docs/_static/wifi_router_en.png" style="zoom:80%;" />

### How to use example
#### Hardware Required
- An esp32 series development board
- A Micro-USB cable for power supply and programming

Follow detailed instructions provided specifically for this example.

#### Build and Flash
Run `idf.py flash monitor` to build, flash and monitor the project.

Once a complete flash process has been performed, you can use `idf.py app-flash monitor` to reduce the flash time.

(To exit the serial monitor, type `Ctrl-]`. Please reset the development board f you cannot exit the monitor.)

For more information, see [User_Guide.md](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md).

                                    

                                        
                                        | Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 | ESP32-H2 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- |

# Wired NIC example

## Overview

This example focuses on the networking part, implementing packet forwarding between network interfaces. It can be connected to PC or MCU through various network interfaces (USB/SPI/SDIO). ESP32 series chips use NAT to forward data packets in and out of the Ethernet network interface.

<img src="https://raw.githubusercontent.com/espressif/esp-iot-bridge/master/components/iot_bridge/docs/_static/wired_nic_en.png" style="zoom:80%;" />

### How to use example
#### Hardware Required
**Required**
- An Ethernet cable
- An esp32 series development board
- A Micro-USB cable for power supply and programming

**Optional**
- A USB cable for communication
- Some DuPont cables to connect to the SPI or SDIO interface of the MCU

Follow detailed instructions provided specifically for this example.

#### Choose the interface used to provide network data forwarding for other devices

You can select the interface (USB/SPI/SDIO) connected to the PC/MCU in `Component config → Bridge Configuration → The interface used to provide network data forwarding for other devices` of `menuconfig`.

#### Build and Flash
Run `idf.py flash monitor` to build, flash and monitor the project.

Once a complete flash process has been performed, you can use `idf.py app-flash monitor` to reduce the flash time.

(To exit the serial monitor, type `Ctrl-]`. Please reset the development board f you cannot exit the monitor.)

For more information, see [User_Guide.md](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md).

                                    

                                        
                                        | Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 | ESP32-H2 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -------- |

# Wireless NIC example

## Overview

This example focuses on the networking part, implementing packet forwarding between network interfaces. It can be connected to PC or MCU through various network interfaces (USB/ETH/SPI/SDIO). ESP32 series chips use NAT to forward data packets in and out of the Station network interface.

<img src="https://raw.githubusercontent.com/espressif/esp-iot-bridge/master/components/iot_bridge/docs/_static/wireless_nic_en.png" style="zoom:80%;" />

### How to use example
#### Hardware Required
**Required**
- An Ethernet cable
- An esp32 series development board
- A Micro-USB cable for power supply and programming

**Optional**
- A USB cable for communication
- Some DuPont cables to connect to the SPI or SDIO interface of the MCU

Follow detailed instructions provided specifically for this example.

#### Choose the interface used to provide network data forwarding for other devices

You can select the interface (USB/ETH/SPI/SDIO) connected to the PC/MCU in `Component config → Bridge Configuration → The interface used to provide network data forwarding for other devices` of `menuconfig`.

#### Build and Flash
Run `idf.py flash monitor` to build, flash and monitor the project.

Once a complete flash process has been performed, you can use `idf.py app-flash monitor` to reduce the flash time.

(To exit the serial monitor, type `Ctrl-]`. Please reset the development board f you cannot exit the monitor.)

For more information, see [User_Guide.md](https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md).