# wasdwasd0105/superwifiduck architecture

> Architecture diagram of the GitHub repository wasdwasd0105/superwifiduck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wasdwasd0105/superwifiduck
- Repository: https://github.com/wasdwasd0105/superwifiduck

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        USBInterface["USB Controller"]:::hw
        WiFi["WiFi SoftAP"]:::hw
        Flash["SPIFFS Flash"]:::storage
        LEDs["On-board LEDs"]:::hw
        UART["UART Serial (UART)"]:::hw
    end

    subgraph "Firmware Modules"
        subgraph "USB HID Service"
            USBDesc["custom_usb_descriptors/USB.cpp"]:::fw
            Keyboard["keyboard.cpp/h"]:::fw
            EEPROM["eeprom & settings"]:::fw
        end

        subgraph "Network & Web UI"
            WebServ["webserver.cpp/h"]:::fw
            WebFiles["webfiles.h"]:::fw
            subgraph "Static Web UI"
                IndexHTML["index.html"]:::fw
                StyleCSS["style.css"]:::fw
                IndexJS["index.js"]:::fw
                ScriptJS["script.js"]:::fw
                SettingsHTML["settings.html"]:::fw
                SettingsJS["settings.js"]:::fw
                TerminalHTML["terminal.html"]:::fw
                TerminalJS["terminal.js"]:::fw
                CreditsHTML["credits.html"]:::fw
                Error404HTML["error404.html"]:::fw
            end
            WebConv["webconverter.py"]:::fw
        end

        subgraph "SPIFFS FS"
            SPIFFS["spiffs.cpp/h"]:::fw
        end

        subgraph "CLI Engine"
            CLI["cli.cpp/h"]:::fw
            Main["main.cpp"]:::fw
        end

        subgraph "Ducky Script Engine"
            DuckParser["duckparser.cpp/h"]:::fw
            DuckScript["duckscript.cpp/h"]:::fw
            ParserLegacy["parser.c/h"]:::fw
        end

        subgraph "LED & Peripherals"
            LEDDrv["led.cpp/h"]:::fw
            DotStar["Adafruit_DotStar.cpp/h"]:::fw
            NeoPixel["NeoPixel.cpp/h"]:::fw
        end

        subgraph "Keyboard Layouts & Locale"
            Locale["src/locale/*.h"]:::fw
        end

        Config["config.h & debug.h"]:::fw
        BuildCfg["platformio.ini"]:::fw
    end

    subgraph "External Entities"
        Browser["Web Browser"]:::external
        HostPC["Target Host PC"]:::external
        SerialConsole["Developer Serial Console"]:::external
    end

    Browser -->|HTTP GET /index.html| WebServ
    WebServ -->|Serves UI| SPIFFS
    WebServ -->|Serves UI| WebFiles
    Browser -->|WebSocket commands| CLI
    SerialConsole -->|UART CLI| CLI
    CLI -->|FS ops| SPIFFS
    CLI -->|Executes script| DuckParser
    DuckParser -->|Parses| DuckScript
    DuckScript -->|Emits key events| USBDesc
    DuckScript -->|LED commands| LEDDrv
    USBDesc --> USBInterface
    LEDDrv --> LEDs
    WiFi --> Browser
    Flash --> SPIFFS
    HostPC --> USBInterface
    IndexHTML --> WebConv
    StyleCSS --> WebConv
    IndexJS --> WebConv
    ScriptJS --> WebConv
    SettingsHTML --> WebConv
    SettingsJS --> WebConv
    TerminalHTML --> WebConv
    TerminalJS --> WebConv
    CreditsHTML --> WebConv
    Error404HTML --> WebConv
    WebConv --> WebFiles

    click USBDesc "https://github.com/wasdwasd0105/superwifiduck/blob/master/custom_usb_descriptors/USB.cpp"
    click Keyboard "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/keyboard.cpp"
    click Keyboard "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/keyboard.h"
    click EEPROM "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/eeprom.cpp"
    click EEPROM "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/eeprom0.h"
    click EEPROM "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/settings.cpp"
    click EEPROM "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/settings.h"

    click WebServ "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/webserver.cpp"
    click WebServ "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/webserver.h"
    click WebFiles "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/webfiles.h"
    click IndexHTML "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/index.html"
    click StyleCSS "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/style.css"
    click IndexJS "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/index.js"
    click ScriptJS "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/script.js"
    click SettingsHTML "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/settings.html"
    click SettingsJS "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/settings.js"
    click TerminalHTML "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/terminal.html"
    click TerminalJS "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/terminal.js"
    click CreditsHTML "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/credits.html"
    click Error404HTML "https://github.com/wasdwasd0105/superwifiduck/blob/master/web/error404.html"
    click WebConv "https://github.com/wasdwasd0105/superwifiduck/blob/master/webconverter.py"

    click SPIFFS "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/spiffs.cpp"
    click SPIFFS "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/spiffs.h"

    click CLI "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/cli.cpp"
    click CLI "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/cli.h"
    click Main "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/main.cpp"

    click DuckParser "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/duckparser.cpp"
    click DuckParser "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/duckparser.h"
    click DuckScript "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/duckscript.cpp"
    click DuckScript "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/duckscript.h"
    click ParserLegacy "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/parser.c"
    click ParserLegacy "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/parser.h"

    click LEDDrv "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/led.cpp"
    click LEDDrv "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/led.h"
    click DotStar "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/Adafruit_DotStar.cpp"
    click DotStar "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/Adafruit_DotStar.h"
    click NeoPixel "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/NeoPixel.cpp"
    click NeoPixel "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/NeoPixel.h"

    click Config "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/config.h"
    click Config "https://github.com/wasdwasd0105/superwifiduck/blob/master/src/debug.h"
    click BuildCfg "https://github.com/wasdwasd0105/superwifiduck/blob/master/platformio.ini"

    classDef fw fill:#ADD8E6,stroke:#0000FF
    classDef storage fill:#90EE90,stroke:#008000
    classDef hw fill:#D3D3D3,stroke:#666666
    classDef external fill:#FFA500,stroke:#CC8400
```
