OptiFi ESP-IDF Firmware

This repository contains the high-performance network bridging firmware for the OptiFi ESP32-S3 node. It acts as an ultra-low latency bridge, routing IPv4 traffic directly between the host OS (via USB) and the local Wi-Fi network.

📚 OS-Specific Build Guides

To build the firmware, please refer to the specific setup instructions for your operating system:

• Ubuntu / Debian
• Arch Linux
• Windows

---

🏗️ Architectural Overview & Modules

The firmware was fundamentally restructured into isolated domains (core, network, usb, and wifi) to ensure extreme scalability and performance. The architecture bypasses standard LwIP TCP/UDP socket bottlenecks by hooking directly into the MAC-layer Netif interface.

1. The Core Initializer (src/main.c)

Why it was implemented: We needed a clean entry point that delegates functionality rather than acting as a monolith. What it does:

• Initializes the Non-Volatile Storage (NVS).
• Bootstraps the ESP-IDF Event Loops and esp_netif subsystem.
• Provisions isolated FreeRTOS queues (length: 32) to prevent internal SRAM bufferbloat, safeguarding Wi-Fi hardware DMA operations.
• Triggers the usb and wifi tasks and hooks the network bridge once connected.

2. Network Bridge (src/network/bridge.c)

Why it was implemented: To sniff outgoing and incoming Wi-Fi traffic at the lowest possible layer without processing it through the heavy LwIP TCP/IP stack. Signatures & Logic:

• err_t wifi_linkoutput_hook(struct netif *netif, struct pbuf *p): Intercepts raw Ethernet frames leaving the ESP32. It routes packets from the USB TAP interface to the air.
• err_t wifi_input_hook(struct pbuf *p, struct netif *netif): Intercepts raw Ethernet frames arriving from the router. It parses the IP/L4 headers and routes them into the s_wifi_to_usb_queue.
• Anti-Bufferbloat Design: Maintains strict, tiny queues. When queues fill up during burst traffic, packets are safely dropped. This signals TCP Congestion Control algorithms on the PC to regulate speeds, keeping physical latency (ping) well under 1ms.

3. Symmetric NAT Router (src/network/nat.c)

Why it was implemented: Because the ESP32 acts as a Wi-Fi station, the upstream router assigns it a single IP (e.g., 192.168.1.5). We must dynamically rewrite the host's IP (10.137.137.1) to the ESP32's IP. Signatures & Logic:

• void remember_nat_mapping(...): Records outgoing connections into a highly optimized 256-entry LRU (Least Recently Used) cache.
• bool find_nat_mapping(...): Inspects incoming packets and matches them against the LRU cache using Port Preservation (Symmetric NAT architecture).
• PMTUD ICMP Forwarding: The NAT logic detects and automatically forwards all raw IP_PROTO_ICMP frames directly to the host. This guarantees that Path MTU Discovery (PMTUD) works flawlessly, preventing dreaded ERR_SSL_VERSION_OR_CIPHER_MISMATCH drops during TLS handshakes.

4. Custom USB Bulk Driver (src/usb/optifi_usb.c)

Why it was implemented: Standard USB-CDC (Serial) drivers limit throughput to ~1-2 Mbps. We implemented a raw TinyUSB Vendor class driver to push multi-megabit bulk transfers. Signatures & Logic:

• Endpoints: Uses Bulk OUT 0x01 and Bulk IN 0x81.
• void tud_vendor_tx_cb(uint8_t itf, uint32_t sent_bytes): A hardware-level interrupt callback that triggers an RTOS Semaphore (xSemaphoreGive).
• Zero-Latency TX: Replaced traditional vTaskDelay() loops with a blocking xSemaphoreTake. This allows the ESP32 to instantly blast data to the host the exact microsecond the hardware FIFO empties, shattering the previous 180kbps ceiling.

---

🛠️ Configuration

Set your target Wi-Fi credentials inside include/core/optifi_config.h:

#define OPTIFI_WIFI_SSID "YOUR_SSID"
#define OPTIFI_WIFI_PASSWORD "YOUR_PASSWORD"

🚀 Compiling

(See OS-Specific guides for prerequisites)

idf.py set-target esp32s3
idf.py build flash