How thingpulse/superwifiduck works
Project type and purpose
• This is an embedded firmware project for an ESP32-S2/S3 “BadUSB” device (“Super WiFi Duck”).
• It provides a Wi-Fi-hosted web interface and CLI to upload, manage, and run DuckyScript payloads.
• When executed, scripts are interpreted and injected as USB HID keyboard events into a target host, with status LEDs and optional button input.
File structure
• Top-level platformio.ini defines build targets and embeds web files into SPIFFS.
• custom_usb_descriptors/: custom USB VID/PID/descriptors.
• /: public headers and configuration.
• lib/: third-party libraries (e.g., SimpleCLI).
• src/:
• Hardware drivers (button, LED: Adafruit_DotStar, NeoPixel)
• duckparser / duckscript: script interpreter
• keyboard: USB HID abstraction
• webserver + spiffs: HTTP server, WebSocket, static file serving
• cli: serial & WebSocket command interface
• settings, eeprom: persistent config
• main.cpp: boot & component initialization
• web/: front-end UI (HTML/CSS/JS) for script editing, terminal, settings.
• test/: test scripts and docs.
Key insights from README
• The firmware runs an Access Point (“wifiduck”) and webserver at 192.168.4.1.
• Uses SPIFFS to serve and store Ducky scripts and web assets.
• Offers a CLI over serial (UART) or WebSocket for managing files, settings, and executing scripts.
• On script execution, the duckparser drives the keyboard HID stack to inject keystrokes.
• LED drivers provide RGB feedback; a push-button can reset or trigger actions.
• Wi-Fi Manager & Access Point
• SPIFFS File System
• HTTP/WebSocket Server (ESPAsyncWebServer)
• Front-end UI (Browser)
• CLI Module (SimpleCLI)
• Script Interpreter (duckparser + duckscript VM)
• USB HID Keyboard Driver
• Hardware Peripherals:
– DotStar/NeoPixel LED driver
– Push-button
– (Optional) I²C/Atmega32U4 link for legacy boards
• Browser ←HTTP/WebSocket→ WebServer
• WebServer → SPIFFS (read/write scripts & web assets)
• Browser → CLI Module (over WebSocket) → SPIFFS / Settings
• CLI “run” → Script Interpreter → Keyboard Driver → USB HID → Host PC
• Script Interpreter → LED Driver (status updates)
• Main Loop → Button Interrupt → CLI/Reset logic
• Serial (UART) ←→ CLI Module (alternative to WebSocket)
c. Architectural patterns / principles:
• Modular separation: network stack, file storage, command parsing, execution engine, hardware abstraction.
• Event-driven I/O: asynchronous TCP/WebSocket with callbacks (ESPAsyncTCP).
• Single binary containing firmware + embedded web assets (via platformio.ini).
d. Technologies & libraries:
• ESP-IDF/Arduino on ESP32-S3
• PlatformIO build system
• SPIFFS for file storage
• ESPAsyncWebServer / ESPAsyncTCP for HTTP & WebSocket
• SimpleCLI for serial & WebSocket commands
• Adafruit DotStar / NeoPixel for RGB LED
• Custom USB descriptors for HID keyboard emulation