# thingpulse/superwifiduck architecture

> Architecture diagram of the GitHub repository thingpulse/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/thingpulse/superwifiduck
- Repository: https://github.com/thingpulse/superwifiduck

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    Browser["User Browser"]:::network

    %% Network Layer
    WebServer["HTTP/WebSocket Server"]:::network
    click WebServer "https://github.com/thingpulse/superwifiduck/blob/master/src/webserver.cpp"

    SerialPort["Serial UART"]:::hardware

    %% Storage Layer
    SPIFFS["SPIFFS File System"]:::storage
    click SPIFFS "https://github.com/thingpulse/superwifiduck/blob/master/src/spiffs.cpp"
    WebAssets["Embedded Web Assets"]:::storage
    click WebAssets "https://github.com/thingpulse/superwifiduck/blob/master/src/webfiles.h"
    Settings["Settings Storage"]:::storage
    click Settings "https://github.com/thingpulse/superwifiduck/blob/master/src/settings.cpp"
    Eeprom["EEPROM Abstraction"]:::storage
    click Eeprom "https://github.com/thingpulse/superwifiduck/blob/master/src/eeprom.cpp"

    %% Execution Logic
    CLI["CLI Module"]:::execution
    click CLI "https://github.com/thingpulse/superwifiduck/blob/master/src/cli.cpp"
    ParserC["Auxiliary C Parser"]:::execution
    click ParserC "https://github.com/thingpulse/superwifiduck/blob/master/src/parser.c"
    DuckParser["Script Interpreter"]:::execution
    click DuckParser "https://github.com/thingpulse/superwifiduck/blob/master/src/duckparser.cpp"
    DuckVM["DuckScript VM"]:::execution
    click DuckVM "https://github.com/thingpulse/superwifiduck/blob/master/src/duckscript.cpp"

    %% Hardware Abstraction
    Keyboard["USB HID Keyboard Driver"]:::hardware
    click Keyboard "https://github.com/thingpulse/superwifiduck/blob/master/src/keyboard.cpp"
    USBDesc["Custom USB Descriptors"]:::hardware
    click USBDesc "https://github.com/thingpulse/superwifiduck/blob/master/custom_usb_descriptors/USB.cpp"
    LED["LED Drivers"]:::hardware
    click LED "https://github.com/thingpulse/superwifiduck/blob/master/src/led.cpp"
    Button["Push-Button Input"]:::hardware
    click Button "https://github.com/thingpulse/superwifiduck/blob/master/src/button.cpp"
    HostPC["Target Host PC"]:::hardware

    %% Configuration & Boot
    Main["Main Application Entry"]:::config
    click Main "https://github.com/thingpulse/superwifiduck/blob/master/src/main.cpp"
    Config["Configuration & Debug"]:::config
    click Config "https://github.com/thingpulse/superwifiduck/blob/master/src/config.h"
    Locale["Localization/Keymaps"]:::config
    click Locale "https://github.com/thingpulse/superwifiduck/tree/master/src/locale/"
    PlatformIO["PlatformIO Build Config"]:::config
    click PlatformIO "https://github.com/thingpulse/superwifiduck/blob/master/platformio.ini"

    %% Connections
    Browser -->|HTTP/WebSocket| WebServer
    WebServer -->|serve files| SPIFFS
    WebServer -->|load assets| WebAssets
    WebServer -->|commands| CLI
    SerialPort <-->|CLI over UART| CLI
    CLI -->|read/write| SPIFFS
    CLI -->|execute run| DuckParser
    DuckParser -->|parse| ParserC
    ParserC -->|tokens| DuckVM
    DuckParser -->|execute| DuckVM
    DuckVM -->|HID reports| Keyboard
    Keyboard -->|USB HID| HostPC
    DuckParser -->|status updates| LED
    Main -->|init modules| WebServer
    Main -->|init modules| SPIFFS
    Main -->|init modules| CLI
    Main -->|init modules| DuckParser
    Main -->|init modules| Keyboard
    Button -->|interrupt| Main
    PlatformIO -->|embed web assets| SPIFFS

    %% Styles
    classDef network fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#333,stroke-width:1px
    classDef execution fill:#90EE90,stroke:#333,stroke-width:1px
    classDef hardware fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:1px
```
