How wasdwasd0105/superwifiduck works
Project type and purpose
• This is an embedded full-stack firmware project for an ESP32 S2/S3 that turns the module into a “BadUSB”/keyboard injector with a WiFi-hosted web UI.
• Key features:
• Emulate USB HID keyboard (future USB mouse/disk functions)
• Host scripts in SPIFFS and run “Ducky Script” commands
• Offer a web interface (HTML/JS/CSS) and a CLI (serial & websocket)
File structure
• Top level:
• custom_usb_descriptors/ – USB descriptors for VID/PID customization
• / & lib/ – third-party and common headers
• src/ – all firmware modules: USB HID, webserver, parser, CLI, settings, SPIFFS, LED, keyboard, parser, DuckScript engine
• web/ – static web UI files (HTML, CSS, JS)
• webconverter.py + webfiles.h – pipeline to gzip & embed web files into firmware
• platformio.ini – build targets & flags (ESP32 S2/S3 environments)
• test/ + testscript/ – test suites and example scripts
Key insights from README
• Architecture elements explicitly mentioned:
• SPIFFS filesystem to store scripts & web UI
• ESPAsyncWebServer + ESPAsyncTCP for HTTP & websocket
• SimpleCLI for serial CLI interface
• duckparser & duckscript modules for parsing Ducky Script
• Native USB stack for HID keyboard emulation (Adafruit DotStar & NeoPixel for LEDs)
Main components
A. Hardware Layer (ESP32 S2/S3 chip)
• Native USB controller (VID/PID, HID descriptor, composite support)
• WiFi radio (acts as SoftAP)
• Flash storage (SPIFFS)
• On-board LEDs (NeoPixel/DotStar)
• UART for serial CLI (115200 baud)
B. Firmware Services
1. USB HID Service
• custom_usb_descriptors
• keyboard.cpp/h (USB HID report generation)
• eeprom/settings (store VID/PID overrides)
2. Network & Web UI
• ESPAsyncTCP → ESPAsyncWebServer (HTTP, websocket)
• webfiles.h (embedded gzipped web/* assets)
• webserver.cpp/h (serves HTML/CSS/JS, handles websocket messages for CLI)
3. File System (SPIFFS)
• spiffs.cpp/h (mount, format, list, read/write scripts)
• CLI commands for file management
4. CLI Engine
• SimpleCLI integration (cli.cpp/h)
• Exposed over UART & websocket terminal page (terminal.html/js)
5. Ducky Script Engine
• duckparser.cpp/h (tokenizes & interprets script lines)
• duckscript.cpp/h (executes key events, delays, LED commands)
6. Peripheral Modules
• LED control (led.cpp/h using Adafruit_NeoPixel & DotStar)
• keyboard layout & locale (src/locale/*.h + usb_hid_keys.h)
• parser.c/h (legacy C parser)
C. External Entities
• Web browser (connects to SoftAP, fetches UI, opens websocket)
• Target host computer (USB HID keyboard device)
• Developer’s serial console (UART CLI)
Relationships and data flows
• User opens browser → connects to ESP32 SoftAP → HTTP GET web UI → served by webserver module (→ SPIFFS)
• Browser UI sends commands (save, list, run script) via HTTP POST or websocket → webserver forwards to CLI engine → file ops via SPIFFS or triggers duckparser
• Serial console commands → CLI engine → same path for script exec or FS ops
• duckparser instructs USB HID service to emit key reports → target computer sees keystrokes
• duckscript can call LED service → feedback via Neopixel/DotStar
Architectural patterns & principles
• Layered architecture: Hardware → Drivers (USB, WiFi, SPIFFS) → Services (webserver, CLI, parser) → Application logic (script execution)
• Event-driven: Async TCP & HTTP callbacks, websocket message handlers
• Modular: Each feature (USB, FS, CLI, parsing, web UI) in its own module/subdirectory
• Single-responsibility: parser only parses, duckscript only executes, webserver only serves & delegates
• Clear labels for every component/module