ESP32-S3 USB NCM Web Server

This repository is an open-source reference project providing a high-performance USB NCM virtual Ethernet web server, a LittleFS file browser, and a REST API environment built on the ESP32-S3.

For development productivity and ease of integration with external libraries, it is unified under the PlatformIO (Arduino Core v3) environment.

---

📂 Project Structure

esp32-web-server/
├── src/                           # C++ Source Code
│   ├── main.cpp                   # Main application entry point & Wi-Fi/Event loop control
│   ├── fs_browser.cpp / .hpp      # HTTP request handlers, File browser & REST API engine
│   └── db_manager.cpp / .hpp      # SQLite database control & management module
│
├── lib/                           # PlatformIO private library directory
│   └── Sqlite3Esp32/              # SQLite3 database library for ESP32
│
├── data/                          # Data folder for LittleFS filesystem image upload
├── partitions.csv                 # Flash partition table definition (4MB spiffs partition)
├── platformio.ini                 # PlatformIO configuration file
├── web_serial.html                # Built-in dashboard web interface resource (embedded file)
├── LICENSE                        # MIT License
└── Readme.ko.md                   # Korean project documentation

---

⚙️ Development & Build Environment

Framework	Explicitly Supported Version	Build System	Target Hardware
Arduino Core v3	ESP32 Arduino Core 3.1.3 (using release framework-arduinoespressif32 @ 3.1.3 / pioarduino 53.03.13)	PlatformIO CLI / VSCode Extension	ESP32-S3 (models supporting USB OTG)

---

✨ Key Features

1. USB NCM / RNDIS Virtual Ethernet Connection (Plug & Play Virtual Ethernet):

   • When the ESP32-S3 is connected to a PC via a USB-C data cable, it is instantly recognized as a driverless virtual Ethernet card adapter.
   • An IP address in the 192.168.8.x range is automatically assigned to the PC via a built-in DHCP server running on the ESP32-S3, without requiring an external Wi-Fi router.
   • You can access the web dashboard immediately by opening a web browser and navigating to http://192.168.8.1:8080.

2. Web-based LittleFS File Browser & REST API:

   • Manages the LittleFS partition (/spiffs) in the ESP32 internal flash memory in integration with the web server.
   • Provides features such as file listing, multipart file upload, file streaming download, and file deletion through the web dashboard.
   • Secure Login: Supports secure login based on HTTP Digest Authentication (Default Account: admin / esp32).

3. Wi-Fi Provisioning over SoftAP (No BLE):

   • Maximizes RAM and Flash space by completely excluding the Bluetooth stack (saves approximately 500KB to 1MB of Flash).
   • Operates in Wi-Fi SoftAP mode on initial boot or when pressing the BOOT button for 10 seconds.
   • Allows secure injection of Wi-Fi configurations using the official ESP Provisioning mobile app or via web browser access.
   • Network & Port Conflict Prevention: Separates the USB NCM IP range to 192.168.8.1 to avoid routing conflicts with the Wi-Fi SoftAP range (192.168.4.1), and assigns the main web server port to 8080 (control port 32769) to enable it to run concurrently and independently from the Wi-Fi SoftAP provisioning service, which uses port 80 (control port 32768).
   • Default Provisioning Information: SSID PROV_123, PoP abcd1234.

4. Hardware System Monitoring & Heartbeat:

   • BOOT Button (GPIO 0): Resets the device when pressed for 3 seconds; erases NVS memory and resets when pressed for 10 seconds.
   • Heartbeat Task: Outputs system uptime and operational status logs every 5 seconds.

---

📸 Screenshots & UI Preview

Dashboard Status	LittleFS File Browser
SQLite Database Manager	NVS Editor

---

🛠️ Build & Upload Guide

# 1) Build firmware
pio run

# 2) Upload firmware and launch serial monitor
pio run --target upload --target monitor

# 3) Build and upload LittleFS filesystem image
pio run --target buildfs
pio run --target uploadfs

---

🔌 Connection & Verification

1. Connect the USB OTG (Data) port of the ESP32-S3 to your PC.
2. Verify that the virtual Ethernet device is recognized in Windows under Device Manager -> Network adapters.
3. Open a web browser and navigate to http://192.168.8.1:8080.
4. Enter admin / esp32 in the login prompt to access the dashboard and the LittleFS file browser.

---

📝 License

This project is distributed under the MIT License. Feel free to modify and utilize it.

---

This project and documentation were created in pair programming with Antigravity, an AI coding assistant developed by Google DeepMind.