### Install Git and Raspi-gpio Utility

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/Linux_based_readme.md

Installs Git for version control and the raspi-gpio utility, which are required tools for the ESP-IoT-Bridge setup on Raspberry Pi.

```bash
$ sudo apt install git raspi-gpio
```

--------------------------------

### Create Project from ESP-IoT-Bridge Example

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/README.md

Generate a new project from an ESP-IoT-Bridge example template using the `create-project-from-example` command. The `wifi_router` example is shown.

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

--------------------------------

### Get esptool Help

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md

Run this command to view the full features and options available for the esptool.

```bash
./components/esptool_py/esptool/esptool.py --help
```

--------------------------------

### Create All Kconfig-Enabled Netifs with ESP-IDF Initialization

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Initializes ESP-IDF components and creates all network interfaces enabled in `idf.py menuconfig`. This is the recommended starting point for most applications.

```c
#include "nvs_flash.h"
#include "esp_netif.h"
#include "esp_event.h"
#include "esp_bridge.h"

void app_main(void)
{
    // Required ESP-IDF initialization
    ESP_ERROR_CHECK(nvs_flash_init());
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());

    // Creates all netifs configured in menuconfig
    // e.g. SoftAP (data-forwarding) + Station (external) for Wi-Fi Router mode
    esp_bridge_create_all_netif();

    // At this point, the bridge is running.
    // Clients connecting to the SoftAP will get DHCP addresses and
    // have their traffic NAT-forwarded through the Station interface.
}
```

--------------------------------

### Install Python

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/Linux_based_readme.md

Installs Python, which is a requirement for the ESP-IoT-Bridge solution. This command installs Python 2.x. For Python 3.x, use 'python3'.

```bash
$ sudo apt install python
```

--------------------------------

### Install Bluetooth Stack

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/Linux_based_readme.md

Installs the Bluetooth stack and utilities required for the ESP-IoT-Bridge solution on Raspberry Pi.

```bash
$ sudo apt install pi-bluetooth
```

--------------------------------

### Install Raspberry Pi Kernel Headers

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/Linux_based_readme.md

Installs the necessary kernel headers for Raspberry Pi, which are required for driver compilation. Run this command before proceeding with other setup steps.

```bash
$ sudo apt update
$ sudo apt install raspberrypi-kernel-headers
```

--------------------------------

### Install Python 3

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/Linux_based_readme.md

Installs Python 3, which is a requirement for the ESP-IoT-Bridge solution. This command installs Python 3.x.

```bash
$ sudo apt install python3
```

--------------------------------

### Verify Kernel Headers Installation

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/Linux_based_readme.md

Verifies if the kernel headers are installed correctly by checking for the presence of the build directory. If this command fails, kernel headers may not be installed properly.

```bash
$ ls /lib/modules/$(uname -r)/build
```

--------------------------------

### JavaScript: Get Available Wi-Fi Networks

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Requests a list of available Wi-Fi networks from the device and initializes the Wi-Fi list display. Handles potential errors during the request.

```javascript
function getaprecord(){showLoading();console.log("getaprecord");Ajax.get("/getaprecord",function(c){c=JSON.parse(c);console.log(c);try{if(c.state==0){wifiList=c.aplist;initWifiList(wifiList,null);hideLoading("msg-load")}else{showMessage(getPrompt("getWifiFailed"),2000)}}catch(d){showMessage(getPrompt("getWifiFailed"),2000)}})}
```

--------------------------------

### Update IDF Component Manager

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/README.md

If you encounter issues with the package manager, update it by running `pip install -U idf-component-manager` in your ESP-IDF environment.

```bash
pip install -U idf-component-manager
```

--------------------------------

### esp_bridge_create_softap_netif

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates a Wi-Fi SoftAP network interface used as a downstream (LAN/data-forwarding) interface. Requires `CONFIG_BRIDGE_DATA_FORWARDING_NETIF_SOFTAP`. The SoftAP gets a DHCP server and NAT enabled automatically; its SSID/password are configured via menuconfig or `esp_bridge_wifi_set`.

```APIDOC
## esp_bridge_create_softap_netif — Create SoftAP (LAN) netif

### Description
Creates a Wi-Fi SoftAP network interface used as a downstream (LAN/data-forwarding) interface. Requires `CONFIG_BRIDGE_DATA_FORWARDING_NETIF_SOFTAP`. The SoftAP gets a DHCP server and NAT enabled automatically; its SSID/password are configured via menuconfig or `esp_bridge_wifi_set`.

### Usage Example
```c
#include "esp_bridge.h"

// Custom IP for SoftAP subnet (optional; NULL = auto-allocate from pool)
esp_netif_ip_info_t ap_ip = {
    .ip      = { .addr = ESP_IP4TOADDR(192, 168, 5, 1) },
    .gw      = { .addr = ESP_IP4TOADDR(192, 168, 5, 1) },
    .netmask = { .addr = ESP_IP4TOADDR(255, 255, 255, 0) },
};

// data_forwarding=true, enable_dhcps=true
esp_netif_t *ap = esp_bridge_create_softap_netif(&ap_ip, NULL, true, true);
if (ap == NULL) {
    ESP_LOGE("app", "Failed to create SoftAP netif");
    return;
}

// Configure SoftAP credentials
ESP_ERROR_CHECK(esp_bridge_wifi_set(WIFI_MODE_AP, "ESP_Bridge_AP", "bridge123", NULL));
// Clients can now connect to "ESP_Bridge_AP" and receive IPs in 192.168.5.x
```
```

--------------------------------

### Set Minimum CMake Version and Include Project Script

Source: https://github.com/espressif/esp-iot-bridge/blob/master/examples/wired_nic/CMakeLists.txt

Specifies the minimum required CMake version and includes the main project build script from the ESP-IDF tools directory. This is a standard setup for ESP-IDF projects.

```cmake
cmake_minimum_required(VERSION 3.5)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
```

--------------------------------

### Load IP Info from NVS and Control Conflict Check

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Loads previously persisted IP information from NVS for a named netif and allows enabling/disabling IP conflict-check behavior per netif at runtime. Use this to restore saved configurations or disable conflict checks for static setups.

```c
#include "esp_bridge.h"

// Load saved IP config for the SoftAP netif from NVS
esp_netif_ip_info_t loaded_ip = {0};
bool conflict_check = true;
esp_err_t err = esp_bridge_load_ip_info_from_nvs("WIFI_AP_DEF", &loaded_ip, &conflict_check);
if (err == ESP_OK) {
    ESP_LOGI("app", "Loaded IP: " IPSTR ", conflict_check=%d",
             IP2STR(&loaded_ip.ip), conflict_check);
} else {
    ESP_LOGW("app", "No saved IP found in NVS, using auto-allocation");
}

// Disable conflict checking for a specific netif (e.g. for a static known-good config)
esp_netif_t *ap = esp_bridge_get_softap_netif();
ESP_ERROR_CHECK(esp_bridge_netif_set_conflict_check(ap, false));
```

--------------------------------

### Build the Project

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md

After configuring the project using 'idf.py menuconfig', run this command to generate the project's binary files.

```bash
idf.py build
```

--------------------------------

### Flash the Project onto the Device

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md

Connect the ESP device via USB and use this command to flash the compiled project onto the device.

```bash
idf.py flash
```

--------------------------------

### Configure Wi-Fi Provisioning Manager Component

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/wifi_prov_mgr/CMakeLists.txt

Defines the source files, include directories, and dependencies for the Wi-Fi provisioning manager component. Ensure 'wifi_provisioning', 'qrcode', and 'esp_wifi' are available.

```cmake
set(srcs "src/wifi_prov_mgr.c")
set(requires "wifi_provisioning" "qrcode" "esp_wifi")

idf_component_register(SRCS "${srcs}"
                       INCLUDE_DIRS "include"
                       REQUIRES "${requires}")
```

--------------------------------

### Initialize Wi-Fi List Display Logic

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Sets up event listeners for showing and hiding the Wi-Fi list, and for handling user input in the SSID field. It also manages the display of the Wi-Fi list based on mobile device detection.

```javascript
function initShowList(){
 document.getElementById("show-wifi-list").onclick=function(b){
 console.log(isShowWifi);
 isShowWifi=!isShowWifi;
 console.log(isShowWifi);
 if(isShowWifi){
 getaprecord()
 }else{
 removeWifiList()
 }
 document.getElementById("ssid").focus();
 window.event?window.event.cancelBubble=true:b.stopPropagation()
 };
 document.getElementById("ssid").onclick=function(b){
 window.event?window.event.cancelBubble=true:b.stopPropagation()
 };
 document.getElementById("body-wrap").onclick=function(b){
 if(!isMobile){
 isShowWifi=false;
 removeWifiList()
 }
 };
 document.getElementById("ssid").oninput=function(){
 console.log("oninput");
 console.log(isShowWifi);
 console.log(isMobile);
 if(isShowWifi&&!isMobile){
 var b=document.getElementById("wifi-list-wrap");
 console.log(b);
 if(b){
 console.log(this.value);
 document.getElementById("ssid-wrap").removeChild(b);
 initWifiList(wifiList,this.value)
 }
 }
 }
}
```

--------------------------------

### Create Wi-Fi Station (WAN) Netif and Connect

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates a Wi-Fi Station network interface for upstream connectivity and connects to a router. Requires `CONFIG_BRIDGE_EXTERNAL_NETIF_STATION` to be enabled. Handles DNS and IP-segment conflict updates automatically upon connection.

```c
#include "esp_bridge.h"
#include "esp_bridge_wifi.h" // for esp_bridge_wifi_set

// Create station netif (ip_info=NULL: DHCP client; mac=NULL: auto-assign)
esp_netif_t *sta = esp_bridge_create_station_netif(NULL, NULL, false, false);
if (sta == NULL) {
    ESP_LOGE("app", "Failed to create station netif");
}

// Connect to an upstream router
ESP_ERROR_CHECK(esp_bridge_wifi_set(WIFI_MODE_STA, "MyRouter_SSID", "MyRouter_Pass", NULL));
ESP_ERROR_CHECK(esp_wifi_connect());
// On IP_EVENT_STA_GOT_IP, bridge automatically updates DNS and resolves
// IP segment conflicts for all data-forwarding netifs.
```

--------------------------------

### AJAX Request Handling in JavaScript

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Provides functions for making GET, POST, and file POST requests using XMLHttpRequest. Use these for asynchronous communication with the server.

```javascript
var Ajax={
    get:function(e,d){
        var f;
        if(window.XMLHttpRequest){
            f=new XMLHttpRequest()
        }else{
            if(window.ActiveObject){
                f=new ActiveXobject("Microsoft.XMLHTTP")
            }
        }
        f.open("GET",e,true);
        f.onreadystatechange=function(){
            if(f.readyState==4){
                console.log(f.status);
                if(f.status==200||f.status==304){
                    d.call(this,f.responseText)
                }else{
                    showMessage(getPrompt("requestFailed"),1000);
                    hideLoading("msg-load")
                }
            }
        };
        f.send()
    },
    post:function(e,g,h){
        showLoading();
        var f;
        if(window.XMLHttpRequest){
            f=new XMLHttpRequest()
        }else{
            if(window.ActiveObject){
                f=new ActiveXobject("Microsoft.XMLHTTP")
            }
        }
        f.open("POST",e,true);
        f.setRequestHeader("Content-Type","application/x-www-form-urlencoded;charset=UTF-8");
        f.onreadystatechange=function(){
            if(f.readyState==4){
                if(f.status==200||f.status==304){
                    h.call(this,f.responseText)
                }else{
                    hideLoading("msg-load");
                    showMessage(getPrompt("connectFailed"),2000)
                }
            }
        };
        f.send(g)
    },
    postFile:function(e,g,h){
        showLoading();
        var f;
        if(window.XMLHttpRequest){
            f=new XMLHttpRequest()
        }else{
            if(window.ActiveObject){
                f=new ActiveXobject("Microsoft.XMLHTTP")
            }
        }
        f.open("POST",e,true);
        f.setRequestHeader("Content-Type","application/octet-stream;charset=UTF-8");
        f.onreadystatechange=function(){
            if(f.readyState==4){
                if(f.status==200||f.status==304){
                    h.call(this,f.responseText)
                }else{
                    hideLoading("msg-load");
                    showConfirm(getPrompt("prompt"),getPrompt("otaFailed"),getPrompt("confirm"))
                }
            }
        };
        f.send(g)
    }
};
```

--------------------------------

### Initialize Host Driver on Raspberry Pi

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SDIO_setup.md

Execute these commands in the root directory of the ESP-IoT-Bridge repository on the Raspberry Pi to compile and load the host driver for SDIO communication.

```bash
cd esp-iot-bridge/examples/spi_and_sdio_host/host_driver/linux/host_control
./rpi_init.sh sdio
```

--------------------------------

### JavaScript: Get Wi-Fi Station Info

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Fetches the current Wi-Fi station information from the device. It handles success and failure cases, including timeouts and connection failures.

```javascript
function getStatus(){if(timeoutNum>40){hideLoading("msg-load");showMessage(getPrompt("connectTimeout"),2000);return false}timeoutNum++;Ajax.get("/getstainfo",function(b){b=JSON.parse(b); console.log(b);document.getElementById("message").value=b.message;if(b.state==1){getResult()}else{if(b.state==0){setTimeout(function(){getStatus()},1000)}else{hideLoading("msg-load");showMessage(getPrompt("connectFailed"),2000)}}})}
```

--------------------------------

### Configure ESP-IoT-Bridge Driver Sources and Includes

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/drivers/CMakeLists.txt

Defines the main source files and include directories for the drivers. Conditionally appends source files based on build configurations like SDIO, SPI, or Bluetooth.

```cmake
set(sub_srcs "drivers/src/network_adapter.c" "drivers/src/mempool.c" "drivers/src/mempool_ll.c")

set(drivers_include "drivers/include")

if (CONFIG_BRIDGE_EXTERNAL_NETIF_SDIO OR CONFIG_BRIDGE_DATA_FORWARDING_NETIF_SDIO)
    list(APPEND sub_srcs "drivers/src/sdio_slave_api.c")
endif()

if (CONFIG_BRIDGE_EXTERNAL_NETIF_SPI OR CONFIG_BRIDGE_DATA_FORWARDING_NETIF_SPI)
    list(APPEND sub_srcs "drivers/src/spi_slave_api.c")
endif()

if(CONFIG_BRIDGE_BT_ENABLED)
    list(APPEND sub_srcs "drivers/src/slave_bt.c")
endif()

set(include_dirs "${include_dirs}" "${drivers_include}" PARENT_SCOPE)
set(srcs "${srcs}" "${sub_srcs}" PARENT_SCOPE)
```

--------------------------------

### JavaScript: Initialize Wi-Fi List

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Renders the list of Wi-Fi networks in the UI. It supports filtering and highlights the currently selected network. Includes mobile-specific styling with a mask.

```javascript
function initWifiList(x,r){removeWifiList();var s=document.createElement("div");s.setAttribute("id","wifi-list-wrap");s.setAttribute("class","wifi-list-wrap");if(isMobile){var q=document.createElement("div");q.setAttribute("class","mask");q.setAttribute("id","mask");q.onclick=function(){removeWifiList()};s.appendChild(q)}var y=document.createElement("ul");var v="";var t=document.getElementById("ssid").value;console.log(t);for(var u=0;u<x.length;u++){var p=x[u];if(r&&p.ssid.indexOf(r)==-1){continue}var z="";if(t==p.ssid){z="active"}v+='<li data-value="'+p.ssid+'" onclick="selectCurWifi(event)" class="d-flex d-a-i '+z+'"><span class="selected"></span>'+p.ssid;if(p.auth_mode&&p.auth_mode!=0){v+='<span class="lock-img"><svg class="icon" width="12px" height="12px" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg"><path d="M800.421 436.525H736.76V287.852c0-124.507-100.762-225.757-224.732-225.757-123.98 0-224.857 101.25-224.857 225.766v148.662h-63.593c-30.667 0-55.532 24.952-55.532 55.752v407.048c0 30.848 24.865 55.82 55.532 55.82h576.9c30.667 0 55.465-24.97 55.465-55.82V492.275c0-30.802-24.855-55.752-55.532-55.752zM543.203 706.409v88.88a7.354 7.354 0 0 1-7.282 7.325h-47.733a7.373 7.373 0 0 1-7.334-7.322V706.41c-22.423-11.518-37.953-34.602-37.953-61.659 0-38.288 30.945-69.425 69.07-69.425 38.183 0 69.138 31.136 69.138 69.415 0.057 27.067-15.473 50.152-37.905 61.659z m107.311-269.884H373.525V291.539c0-76.691 62.196-139.146 138.552-139.146
```

--------------------------------

### esp_bridge_netif_request_ip / esp_bridge_netif_request_mac

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Allocates an IP address and MAC address that do not conflict with any existing bridge-registered netif. Used internally during netif creation but also available for custom netif setup.

```APIDOC
## `esp_bridge_netif_request_ip` / `esp_bridge_netif_request_mac` — Auto IP and MAC allocation

Allocates an IP address and MAC address that do not conflict with any existing bridge-registered netif. Used internally during netif creation but also available for custom netif setup.

```c
#include "esp_bridge_internal.h"

// Request a non-conflicting IP for a new DHCP-server netif
esp_netif_ip_info_t new_ip = {0};
esp_err_t err = esp_bridge_netif_request_ip(NULL, &new_ip);
if (err == ESP_OK) {
    ESP_LOGI("app", "Allocated IP: " IPSTR, IP2STR(&new_ip.ip));
    ESP_LOGI("app", "Netmask: " IPSTR, IP2STR(&new_ip.netmask));
    // e.g., output: "Allocated IP: 192.168.2.1", "Netmask: 255.255.255.0"
}

// Request a non-conflicting MAC address
uint8_t new_mac[6] = {0};
err = esp_bridge_netif_request_mac(new_mac);
if (err == ESP_OK) {
    ESP_LOGI("app", "Allocated MAC: " MACSTR, MAC2STR(new_mac));
}
```
```

--------------------------------

### Fetching Station Information

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Retrieves station information (like SSID and password) from the server using an AJAX GET request. The response is parsed as JSON and used to populate input fields.

```javascript
function getData(){
    Ajax.get("/getstainfo",function(c){
        c=JSON.parse(c);
        console.log(c);
        try{
            document.getElementById("ssid").value=c.sta_ssid;
            document.getElementById("password").value=c.sta_password;
            document.getElem
```

--------------------------------

### esp_bridge_create_all_netif

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates all network interfaces that are enabled via `idf.py menuconfig`. This is the recommended entry point for most applications as it internally calls each individual `esp_bridge_create_*_netif` factory and registers the DNS-update event handler.

```APIDOC
## esp_bridge_create_all_netif — Create all Kconfig-enabled netifs

### Description
Creates all network interfaces that are enabled via `idf.py menuconfig` (SoftAP, USB, SPI, SDIO, Ethernet, Modem, Station). This is the recommended entry point for most applications; it internally calls each individual `esp_bridge_create_*_netif` factory and registers the DNS-update event handler.

### Usage Example
```c
#include "nvs_flash.h"
#include "esp_netif.h"
#include "esp_event.h"
#include "esp_bridge.h"

void app_main(void)
{
    // Required ESP-IDF initialization
    ESP_ERROR_CHECK(nvs_flash_init());
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());

    // Creates all netifs configured in menuconfig
    // e.g. SoftAP (data-forwarding) + Station (external) for Wi-Fi Router mode
    esp_bridge_create_all_netif();

    // At this point, the bridge is running.
    // Clients connecting to the SoftAP will get DHCP addresses and
    // have their traffic NAT-forwarded through the Station interface.
}
```
```

--------------------------------

### Request Non-Conflicting IP and MAC Addresses

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Allocates an IP address and MAC address that do not conflict with any existing bridge-registered netif. Use this for custom netif setup when automatic allocation is needed.

```c
#include "esp_bridge_internal.h"

// Request a non-conflicting IP for a new DHCP-server netif
esp_netif_ip_info_t new_ip = {0};
esp_err_t err = esp_bridge_netif_request_ip(NULL, &new_ip);
if (err == ESP_OK) {
    ESP_LOGI("app", "Allocated IP: " IPSTR, IP2STR(&new_ip.ip));
    ESP_LOGI("app", "Netmask: " IPSTR, IP2STR(&new_ip.netmask));
    // e.g., output: "Allocated IP: 192.168.2.1", "Netmask: 255.255.255.0"
}

// Request a non-conflicting MAC address
uint8_t new_mac[6] = {0};
err = esp_bridge_netif_request_mac(new_mac);
if (err == ESP_OK) {
    ESP_LOGI("app", "Allocated MAC: " MACSTR, MAC2STR(new_mac));
}
```

--------------------------------

### Initiate OTA Update Process

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Submits the selected firmware file for the OTA update. It displays loading indicators and provides feedback on the success or failure of the update process.

```javascript
function postOta(){
 timeoutNum=0;
 var b=document.getElementById("file-info").files;
 if(b&&b.length>0){
 b=b[0];
 Ajax.postFile("/setotadata",b,function(a){
 a=JSON.parse(a);
 console.log(a);
 hideLoading("msg-load");
 if(a.state==0){
 showConfirm(getPrompt("prompt"),getPrompt("otaSuc"),getPrompt("confirm"))
 }else{
 showConfirm(getPrompt("prompt"),getPrompt("otaFailed"),getPrompt("confirm"))
 }
 })
 }else{
 showMessage(getPrompt("selectFile"),2000)
 }
}
```

--------------------------------

### Configure ethsta0 Network Interface

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SDIO_setup.md

After the SDIO driver is loaded, use this script to enable and configure the `ethsta0` network interface. The MAC address can be customized.

```bash
$ cd esp-iot-bridge/example/spi_and_sdio_host/host_driver/linux/host_control
$ ./ethsta0_config.sh 12:34:56:78:9a:bc
```

--------------------------------

### Compile and Flash ESP Firmware

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SPI_setup.md

Compile the ESP-IoT-Bridge project and flash it to the ESP device using the specified serial port. Replace `<serial_port>` with the actual port of your ESP device.

```bash
idf.py -p <serial_port> build flash
```

--------------------------------

### Create All Network Interfaces

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/README.md

The application layer can create all network interfaces by calling this API. Ensure the correct external and data forwarding netifs are selected in menuconfig.

```c
esp_bridge_create_all_netif()
```

--------------------------------

### Create All Network Interfaces

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/README.md

This API is the primary entry point for the application layer to initialize all network interfaces managed by the ESP-IoT-Bridge. It allows selection of external and data forwarding network interfaces via menuconfig.

```APIDOC
## esp_bridge_create_all_netif()

### Description
Initializes all network interfaces for the ESP-IoT-Bridge. Users can select specific network interfaces (external and data forwarding) through the Bridge Configuration menu in menuconfig.

### Usage
This function should be called by the application to set up the bridge functionality.

### Note
By default, calling this function is sufficient. Alternatively, specific netif creation APIs like `esp_bridge_create_xxx_netif` can be called manually.
```

--------------------------------

### Configure Wi-Fi Station or SoftAP Credentials

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Sets SSID, password, and optional BSSID for Wi-Fi Station or SoftAP. Appends MAC address to SSID if `CONFIG_BRIDGE_SOFTAP_SSID_END_WITH_THE_MAC` is enabled.

```c
#include "esp_bridge.h"
#include "esp_wifi.h"

// Connect Station to upstream router
ESP_ERROR_CHECK(esp_bridge_wifi_set(WIFI_MODE_STA, "HomeRouter", "securepass123", NULL));
ESP_ERROR_CHECK(esp_wifi_connect());

// Change SoftAP SSID and password at runtime
ESP_ERROR_CHECK(esp_bridge_wifi_set(WIFI_MODE_AP, "MyBridge", "mypassword", NULL));
// All currently connected SoftAP clients are deauthenticated automatically.

// Connect STA with a specific BSSID (to pin to a particular AP)
uint8_t bssid[6] = {0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF};
ESP_ERROR_CHECK(esp_bridge_wifi_set(WIFI_MODE_STA, "HomeRouter", "securepass123", (const char *)bssid));
```

--------------------------------

### Enable SPI on Raspberry Pi

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SPI_setup.md

Add these lines to `/boot/config.txt` to enable the SPI master driver and disable Bluetooth. Reboot is required after changes.

```bash
dtparam=spi=on
dtoverlay=disable-bt
```

--------------------------------

### CMakeLists.txt Configuration

Source: https://github.com/espressif/esp-iot-bridge/blob/master/examples/wifi_router/CMakeLists.txt

Sets the minimum CMake version, includes ESP-IDF build scripts, and defines the project name based on the current directory.

```cmake
cmake_minimum_required(VERSION 3.5)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)

string(REGEX REPLACE ".*/\\(.*)" "\\1" CURDIR ${CMAKE_CURRENT_SOURCE_DIR})
project(${CURDIR})
```

--------------------------------

### Configure ESP-IoT-Bridge for SDIO Interface

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SDIO_setup.md

Use `idf.py menuconfig` to open the project configuration. Navigate to 'Bridge Driver Configuration -> Transport layer -> SDIO interface' and select it to configure the project for SDIO communication.

```bash
cd esp-iot-bridge
idf.py menuconfig
```

--------------------------------

### Initialize Host Driver on Raspberry Pi

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SPI_setup.md

This script compiles and loads the host driver for SPI communication on the Raspberry Pi. It creates a virtual serial interface `/dev/esps0` for control.

```bash
$ cd esp-iot-bridge/examples/spi_and_sdio_host/host_driver/linux/host_control
$ ./rpi_init.sh spi
```

--------------------------------

### Create SPI/SDIO Netifs (WAN/LAN)

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates SPI or SDIO network interfaces. Can operate as WAN or LAN, and support dual-role creation. Use `esp_bridge_spi_set_netif_type` or `esp_bridge_sdio_set_netif_type` to switch roles at runtime.

```c
#include "esp_bridge.h"

// SPI as LAN (data-forwarding, DHCP server for MCU host)
esp_netif_t *spi_lan = esp_bridge_create_spi_netif(NULL, NULL, true, true);

// SPI as WAN (external, DHCP client, fixed MAC)
uint8_t spi_wan_mac[6] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06};
esp_netif_t *spi_wan = esp_bridge_create_spi_netif(NULL, spi_wan_mac, false, false);

// Switch the SPI netif active role at runtime
ESP_ERROR_CHECK(esp_bridge_spi_set_netif_type(IOT_BRIDGE_NETIF_LAN));

// Retrieve SPI netif by type
esp_netif_t *spi = esp_bridge_get_spi_netif(IOT_BRIDGE_NETIF_LAN);

// SDIO usage is identical:
esp_netif_t *sdio_lan = esp_bridge_create_sdio_netif(NULL, NULL, true, true);
ESP_ERROR_CHECK(esp_bridge_sdio_set_netif_type(IOT_BRIDGE_NETIF_LAN));
esp_netif_t *sdio = esp_bridge_get_sdio_netif(IOT_BRIDGE_NETIF_LAN);
```

--------------------------------

### Set ESP-IDF Environment Variables

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SPI_setup.md

Source this script in your terminal to set up the necessary ESP-IDF environment variables for compilation and flashing.

```bash
. $HOME/esp/esp-idf/export.sh
```

--------------------------------

### Create Ethernet Netif (WAN/LAN)

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates an Ethernet network interface. Use WAN role for DHCP client and LAN role for DHCP server. Requires `CONFIG_BRIDGE_ETHERNET_NETIF_ENABLE`.

```c
#include "esp_bridge.h"

// --- WAN role: Ethernet receives IP from upstream router via DHCP ---
// data_forwarding=false, enable_dhcps=false
esp_netif_t *eth_wan = esp_bridge_create_eth_netif(NULL, NULL, false, false);

// --- LAN role: Ethernet serves as a downlink NIC with DHCP server ---
// data_forwarding=true, enable_dhcps=true
esp_netif_t *eth_lan = esp_bridge_create_eth_netif(NULL, NULL, true, true);

// Retrieve netif by type later
esp_netif_t *wan = esp_bridge_get_eth_netif(IOT_BRIDGE_NETIF_WAN);
esp_netif_t *lan = esp_bridge_get_eth_netif(IOT_BRIDGE_NETIF_LAN);
```

--------------------------------

### Handle File Input for OTA Update

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Validates the selected file for OTA updates, checking for the '.bin' extension and file size limits. Updates the file name input field and logs the file information.

```javascript
function fileChange(e){
 var c=e.files;
 if(c&&c.length>0){
 c=c[0];
 var d=c.name.toLowerCase();
 if(d.indexOf(".bin")!=(d.length-4)){
 document.getElementById("file-info").value="";
 showMessage(getPrompt("formatError"),2000);
 return
 }
 if(c.size>=2097152){
 document.getElementById("file-info").value="";
 showMessage(getPrompt("fileLarge"),2000);
 return
 }
 document.getElementById("file-name").value=d;
 console.log(document.getElementById("file-info").files)
 }
```

--------------------------------

### Apply Patches with Default Settings

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/cmake/README.md

Includes the patch utilities and applies patches using default configuration file and base directory settings.

```cmake
# Include the patch utilities
include(/path/to/esp-iot-bridge/components/iot_bridge/cmake/patch_utils.cmake)

# Apply patches with default settings
apply_patches_from_list()
```

--------------------------------

### Language Initialization and Handling

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Initializes the application language based on the browser's locale and provides functions to set text content and input placeholders for different languages. Call `loadLanguage()` to apply the correct language on page load.

```javascript
var curLangeage="en";
loadLanguage();
function loadLanguage(){
    var c=navigator.language||navigator.userLanguage;
    c=c.substr(0,2);
    if(c=="zh"){
        curLangeage="zh"
    }else{
        curLangeage="en"
    }
    for(var a=0;a<constHtmlLang.length;a++){
        var b=constHtmlLang[a];
        if(b.type=="input"){
            setInputByLang(b.id,b[curLangeage]);
            continue
        }
        setTextByLang(b.id,b[curLangeage])
    }
}
function setTextByLang(b,a){
    document.getElementById(b).innerText=a
}
function setInputByLang(b,a){
    document.getElementById(b).setAttribute("placeholder",a)
}
function getPrompt(a){
    return constPromptInfo[a][curLangeage]
}
```

--------------------------------

### esp_bridge_create_spi_netif / esp_bridge_create_sdio_netif

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates SPI or SDIO network interfaces that can function as WAN or LAN. These interfaces support runtime role switching between WAN and LAN using `esp_bridge_spi_set_netif_type` and `esp_bridge_sdio_set_netif_type`.

```APIDOC
## `esp_bridge_create_spi_netif` / `esp_bridge_create_sdio_netif` — Create SPI/SDIO netifs

Creates SPI or SDIO network interfaces that can operate as WAN (external) or LAN (data-forwarding) interfaces. Both interfaces support dual-role creation (both WAN and LAN simultaneously) with `esp_bridge_spi_set_netif_type` / `esp_bridge_sdio_set_netif_type` to switch the active path at runtime.

```c
#include "esp_bridge.h"

// SPI as LAN (data-forwarding, DHCP server for MCU host)
esp_netif_t *spi_lan = esp_bridge_create_spi_netif(NULL, NULL, true, true);

// SPI as WAN (external, DHCP client, fixed MAC)
uint8_t spi_wan_mac[6] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06};
esp_netif_t *spi_wan = esp_bridge_create_spi_netif(NULL, spi_wan_mac, false, false);

// Switch the SPI netif active role at runtime
ESP_ERROR_CHECK(esp_bridge_spi_set_netif_type(IOT_BRIDGE_NETIF_LAN));

// Retrieve SPI netif by type
esp_netif_t *spi = esp_bridge_get_spi_netif(IOT_BRIDGE_NETIF_LAN);

// SDIO usage is identical:
esp_netif_t *sdio_lan = esp_bridge_create_sdio_netif(NULL, NULL, true, true);
ESP_ERROR_CHECK(esp_bridge_sdio_set_netif_type(IOT_BRIDGE_NETIF_LAN));
esp_netif_t *sdio = esp_bridge_get_sdio_netif(IOT_BRIDGE_NETIF_LAN);
```
```

--------------------------------

### Checking ESP Device Enumeration with dmesg

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SDIO_setup.md

After flashing and booting the ESP device, check the system logs using `dmesg` to confirm successful enumeration and driver loading. Look for messages related to 'mmc1' and 'esp_sdio' to verify the SDIO connection.

```bash
$ dmesg
[   14.309956] Bluetooth: Core ver 2.22
[   14.310019] NET: Registered protocol family 31
[   14.310022] Bluetooth: HCI device and connection manager initialized
[   14.310038] Bluetooth: HCI socket layer initialized
[   14.310045] Bluetooth: L2CAP socket layer initialized
[   14.310069] Bluetooth: SCO socket layer initialized
[   14.327776] Bluetooth: HCI UART driver ver 2.3
[   14.327784] Bluetooth: HCI UART protocol H4 registered
[   14.328014] Bluetooth: HCI UART protocol Three-wire (H5) registered
[   14.328138] Bluetooth: HCI UART protocol Broadcom registered
[   14.650789] Bluetooth: BNEP (Ethernet Emulation) ver 1.3
[   14.650796] Bluetooth: BNEP filters: protocol multicast
[   14.650810] Bluetooth: BNEP socket layer initialized
[   14.715079] Bluetooth: RFCOMM TTY layer initialized
[   14.715109] Bluetooth: RFCOMM socket layer initialized
[   14.715137] Bluetooth: RFCOMM ver 1.11
[   20.556381] mmc1: card 0001 removed
[   69.245969] mmc1: queuing unknown CIS tuple 0x01 (3 bytes)
[   69.253368] mmc1: queuing unknown CIS tuple 0x1a (5 bytes)
[   69.256622] mmc1: queuing unknown CIS tuple 0x1b (8 bytes)
[   69.258842] mmc1: queuing unknown CIS tuple 0x80 (1 bytes)
[   69.258939] mmc1: queuing unknown CIS tuple 0x81 (1 bytes)
[   69.259035] mmc1: queuing unknown CIS tuple 0x82 (1 bytes)
[   69.260840] mmc1: queuing unknown CIS tuple 0x80 (1 bytes)
[   69.260939] mmc1: queuing unknown CIS tuple 0x81 (1 bytes)
[   69.261040] mmc1: queuing unknown CIS tuple 0x82 (1 bytes)
[   69.261236] mmc1: new SDIO card at address 0001
[   76.892073] esp32: loading out-of-tree module taints kernel.
[   76.893083] esp32: Resetpin of Host is 6
[   76.893202] esp32: Triggering ESP reset.
[   76.894498] esp_sdio: probe of mmc1:0001:1 failed with error -110
[   76.894566] esp_sdio: probe of mmc1:0001:2 failed with error -110
[   77.596173] mmc1: card 0001 removed
[   77.649578] mmc1: queuing unknown CIS tuple 0x01 (3 bytes)
[   77.657019] mmc1: queuing unknown CIS tuple 0x1a (5 bytes)
[   77.660243] mmc1: queuing unknown CIS tuple 0x1b (8 bytes)
[   77.662448] mmc1: queuing unknown CIS tuple 0x80 (1 bytes)
[   77.662545] mmc1: queuing unknown CIS tuple 0x81 (1 bytes)
[   77.662643] mmc1: queuing unknown CIS tuple 0x82 (1 bytes)
[   77.664445] mmc1: queuing unknown CIS tuple 0x80 (1 bytes)
[   77.664541] mmc1: queuing unknown CIS tuple 0x81 (1 bytes)
[   77.664637] mmc1: queuing unknown CIS tuple 0x82 (1 bytes)
[   77.664832] mmc1: new SDIO card at address 0001
[   77.665287] esp_probe: ESP network device detected
[   77.877892] Features supported are:
[   77.877901] 	 * WLAN
[   77.877906] 	 * BT/BLE
[   77.877911] 	   - HCI over SDIO
[   77.877916] 	   - BT/BLE dual mode
[   78.096179] esp_sdio: probe of mmc1:0001:2 failed with error -22

```

--------------------------------

### Clone ESP-IoT-Bridge Repository

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md

Clone the ESP-IoT-Bridge repository from GitHub to your local machine.

```bash
git clone https://github.com/espressif/esp-iot-bridge.git
```

--------------------------------

### Fetch OTA Information

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/web_server/fs_image/index.html

Retrieves current OTA firmware and AT core version information from the device. Displays loading indicators and handles potential errors during the fetch process.

```javascript
function getotainfo(){
 showLoading();
 Ajax.get("/getotainfo",function(c){
 c=JSON.parse(c);
 console.log(c);
 try{
 if(c.state==0){
 document.getElementById("version-wrap").innerText=c["fw_version"];
 document.getElementById("at-core-wrap").innerText=c["at_core_version"];
 hideLoading("msg-load")
 }else{
 showMessage(getPrompt("getVersionFailed"),2000)
 }
 }catch(d){
 showMessage(getPrompt("getVersionFailed"),2000)
 }
 })
}
```

--------------------------------

### Configure ethsta0 Network Interface

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SPI_setup.md

This script enables the `ethsta0` network interface on the Raspberry Pi and assigns a MAC address. The MAC address can be customized.

```bash
$ cd esp-iot-bridge/examples/spi_and_sdio_host/host_driver/linux/host_control
$ ./ethsta0_config.sh 12:34:56:78:9a:bc
```

--------------------------------

### Create SoftAP (LAN) Netif with Custom IP

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates a Wi-Fi SoftAP network interface for downstream connectivity, enabling DHCP server and NAT. Requires `CONFIG_BRIDGE_DATA_FORWARDING_NETIF_SOFTAP`. The SoftAP can be configured with a custom IP address or auto-allocated.

```c
#include "esp_bridge.h"

// Custom IP for SoftAP subnet (optional; NULL = auto-allocate from pool)
esp_netif_ip_info_t ap_ip = {
    .ip      = { .addr = ESP_IP4TOADDR(192, 168, 5, 1) },
    .gw      = { .addr = ESP_IP4TOADDR(192, 168, 5, 1) },
    .netmask = { .addr = ESP_IP4TOADDR(255, 255, 255, 0) },
};

// data_forwarding=true, enable_dhcps=true
esp_netif_t *ap = esp_bridge_create_softap_netif(&ap_ip, NULL, true, true);
if (ap == NULL) {
    ESP_LOGE("app", "Failed to create SoftAP netif");
    return;
}

// Configure SoftAP credentials
ESP_ERROR_CHECK(esp_bridge_wifi_set(WIFI_MODE_AP, "ESP_Bridge_AP", "bridge123", NULL));
// Clients can now connect to "ESP_Bridge_AP" and receive IPs in 192.168.5.x
```

--------------------------------

### Monitor ESP-IoT-Bridge Output

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/User_Guide.md

Use this command to monitor the output from the ESP-IoT-Bridge device. It can be combined with build and flash steps.

```bash
$ idf.py monitor
```

--------------------------------

### Enable SDIO Pins on Raspberry Pi

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/docs/SDIO_setup.md

Append these lines to `/boot/config.txt` to enable SDIO pins and disable Bluetooth. Reboot the Raspberry Pi after modifying the file.

```bash
dtoverlay=sdio,poll_once=off
dtoverlay=disable-bt
```

--------------------------------

### Add ESP-IoT-Bridge Component to Project

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/README.md

Use the component manager command `add-dependency` to include the `iot_bridge` component in your project. It will be automatically downloaded during the CMake build process.

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

--------------------------------

### Create 4G Modem Netif (WAN)

Source: https://context7.com/espressif/esp-iot-bridge/llms.txt

Creates a 4G modem network interface as the upstream internet source. Supports UART and USB-based modems. Requires `CONFIG_BRIDGE_EXTERNAL_NETIF_MODEM`.

```c
#include "esp_bridge.h"

// Modem as WAN (external, data_forwarding=false, enable_dhcps=false)
// ip_info=NULL: IP assigned by modem/PPP; mac=NULL: auto-assign
esp_netif_t *modem = esp_bridge_create_modem_netif(NULL, NULL, false, false);
if (modem == NULL) {
    ESP_LOGE("app", "Modem netif creation failed");
    return;
}

// Retrieve modem netif
esp_netif_t *modem_handle = esp_bridge_get_modem_netif();

// After PPP connects, bridge automatically propagates DNS to all
// downstream (LAN) interfaces via esp_bridge_update_dns_info()
```

--------------------------------

### Apply Patches with Custom Parameters

Source: https://github.com/espressif/esp-iot-bridge/blob/master/components/iot_bridge/cmake/README.md

Includes the patch utilities and applies patches using custom paths for the patches list file and the patch base directory.

```cmake
# Include the patch utilities
include(/path/to/esp-iot-bridge/components/iot_bridge/cmake/patch_utils.cmake)

# Apply patches with custom configuration
apply_patches_from_list(
    PATCHES_LIST_FILE "${CMAKE_CURRENT_LIST_DIR}/my_patches.list"
    PATCH_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}/patches"
)
```