# adafruit/adafruit_wippersnapper_arduino architecture

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

- Interactive diagram: https://gitdiagram.com/adafruit/adafruit_wippersnapper_arduino
- Repository: https://github.com/adafruit/adafruit_wippersnapper_arduino

## Overview

##### Project type and purpose
- This is an embedded IoT firmware project (Adafruit WipperSnapper) built with Arduino/PlatformIO.
- Purpose: turn supported Wi-Fi boards (ESP32, ESP8266, RP2040-W, RP2350-W, ATSAMD51+AirLift) into configurable sensors and actuators that communicate with Adafruit IO without any Arduino code.

##### File structure
- Top-level:
- .github, workflows, CODE_OF_CONDUCT, LICENSE, README.md, Doxyfile for CI & documentation
- examples/ shows sample firmware projects for many boards
- platformio.ini and library.properties define build and library metadata
- src/ contains the firmware code, broken into subdirectories
- tools/ contains helper scripts (rename_usb_config.py, UF2 bootloader files)
- src/ breakdown:
- Core: Wippersnapper.cpp/h, component registry, networking interface abstractions
- components/: driver wrappers for analog, digital I/O, I2C, PWM, pixels, servos, DS18X20, status LED, UART
- /: OLED/TFT UI helpers, symbols
- provisioning/: filesystem (LittleFS, TinyUSB/FAT) and JSON config loader
- nanopb/: Protocol Buffers C runtime & helpers
- wippersnapper/: generated .pb.c/.pb.h for each service (pin, i2c, servo, pixels, etc)
- network_interfaces/: board-specific Wi-Fi and AirLift abstractions
- Build and CI: GitHub Actions workflows for builds, Doxygen docs

##### README for additional insights
- Describes target boards, Adafruit IO requirement, build methods

##### Elements
– Clear labels for each module or layer
– Annotations showing build/CI tools as a side note (PlatformIO, GitHub Actions, Doxygen)

##### Summary
- Interactions through the core scheduler
- Provisioning and display subsystems as side branches

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer" 
        style Hardware fill:#f9f,stroke:#333,stroke-width:2px
        MCU["MCU + Peripherals"]:::hardware
    end

    %% Provisioning Layer
    subgraph "Provisioning Layer" 
        style Provisioning fill:#ff9,stroke:#333,stroke-width:2px
        FS["LittleFS"]:::provisioning
        USB["TinyUSB + FATFS"]:::provisioning
        JSON["Config JSON Loader"]:::provisioning
    end

    %% Component Abstraction Layer
    subgraph "Component Drivers" 
        style Components fill:#9ff,stroke:#333,stroke-width:2px
        AIO["Analog I/O"]:::component
        DIO["Digital I/O"]:::component
        I2C["I2C"]:::component
        PWM["PWM"]:::component
        LEDC["LEDC / Servo"]:::component
        PIX["Pixels"]:::component
        SERVO["Servo"]:::component
        DS["DS18X20"]:::component
        UART["UART"]:::component
        STLED["Status LED"]:::component
        REG["Component Registry"]:::component
    end

    %% Core Scheduler & Registry
    subgraph "Core Scheduler & Registry" 
        style Core fill:#cfc,stroke:#333,stroke-width:2px
        Core["Wippersnapper Core"]:::core
    end

    %% Serialization Layer
    subgraph "Serialization (nanopb)" 
        style Serialization fill:#ccf,stroke:#333,stroke-width:2px
        NPBR["nanopb Runtime & Helpers"]:::serialization
        PBUF["Generated .pb Services"]:::serialization
    end

    %% Networking Layer
    subgraph "Networking Layer" 
        style Network fill:#fcf,stroke:#333,stroke-width:2px
        ESP32["ESP32 Wi-Fi"]:::network
        ESP8266["ESP8266 Wi-Fi"]:::network
        AIRLIFT["AirLift SPI"]:::network
        PICO["RP2040 Wi-Fi"]:::network
    end

    %% Cloud Interface
    AdafruitIO["Adafruit IO (MQTT/HTTP)"]:::cloud

    %% Display/UI Helpers
    subgraph "Display/UI Helpers" 
        style Display fill:#ffa,stroke:#333,stroke-width:2px
        DISP["Display Driver"]:::display
        UIH["UI Helper & Tooltips"]:::display
    end

    %% Examples and CI
    subgraph "Examples & CI" 
        style Notes fill:#ddd,stroke:#333,stroke-width:2px
        EX["User Examples"]:::examples
        CI["PlatformIO & GitHub Actions & Doxygen"]:::ci
    end

    %% Connections
    MCU -->|interfaces| AIO
    MCU -->|interfaces| DIO
    MCU -->|interfaces| I2C
    MCU -->|interfaces| PWM
    MCU -->|interfaces| LEDC
    MCU -->|interfaces| PIX
    MCU -->|interfaces| SERVO
    MCU -->|interfaces| DS
    MCU -->|interfaces| UART
    MCU -->|interfaces| STLED

    JSON -->|loads config| REG
    FS -->|loads config| REG
    USB -->|loads config| REG

    REG -->|registers| Core
    Core -->|polls drivers| AIO
    Core -->|polls drivers| DIO
    Core -->|polls drivers| I2C
    Core -->|polls drivers| PWM
    Core -->|polls drivers| LEDC
    Core -->|polls drivers| PIX
    Core -->|polls drivers| SERVO
    Core -->|polls drivers| DS
    Core -->|polls drivers| UART
    Core -->|controls| STLED

    Core -->|encodes| NPBR
    Core -->|encodes| PBUF

    NPBR -->|"uses"| PBUF
    PBUF -->|to| Core

    Core -->|uses| ESP32
    Core -->|uses| ESP8266
    Core -->|uses| AIRLIFT
    Core -->|uses| PICO

    ESP32 -->|connects| AdafruitIO
    ESP8266 -->|connects| AdafruitIO
    AIRLIFT -->|connects| AdafruitIO
    PICO -->|connects| AdafruitIO

    Core -->|feedback| DISP
    DISP -->|UI| UIH

    EX -->|instantiates| Core
    CI -->|builds & docs| Core

    %% Click Events
    click Core "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/Wippersnapper.cpp"
    click Core "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/Wippersnapper.h"
    click Core "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/Wippersnapper_Networking.h"
    click Core "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/Wippersnapper_Boards.h"
    click AIO "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/analogIO/Wippersnapper_AnalogIO.cpp"
    click AIO "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/analogIO/Wippersnapper_AnalogIO.h"
    click DIO "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/digitalIO/Wippersnapper_DigitalGPIO.cpp"
    click DIO "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/digitalIO/Wippersnapper_DigitalGPIO.h"
    click I2C "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/i2c/WipperSnapper_I2C.cpp"
    click I2C "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/i2c/WipperSnapper_I2C.h"
    click PWM "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/pwm/ws_pwm.cpp"
    click PWM "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/pwm/ws_pwm.h"
    click LEDC "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/ledc/ws_ledc.cpp"
    click LEDC "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/ledc/ws_ledc.h"
    click LEDC "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/ledc/drivers/servo/ws_ledc_servo.cpp"
    click LEDC "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/ledc/drivers/servo/ws_ledc_servo.h"
    click PIX "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/pixels/ws_pixels.cpp"
    click PIX "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/pixels/ws_pixels.h"
    click SERVO "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/servo/ws_servo.cpp"
    click SERVO "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/servo/ws_servo.h"
    click DS "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/ds18x20/ws_ds18x20.cpp"
    click DS "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/ds18x20/ws_ds18x20.h"
    click UART "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/uart/ws_uart.cpp"
    click UART "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/uart/ws_uart.h"
    click REG "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/register/Wippersnapper_Register.cpp"
    click REG "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/components/register/Wippersnapper_Register.h"
    click ESP32 "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/network_interfaces/Wippersnapper_ESP32.h"
    click ESP8266 "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/network_interfaces/Wippersnapper_ESP8266.h"
    click AIRLIFT "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/network_interfaces/Wippersnapper_AIRLIFT.h"
    click PICO "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/network_interfaces/ws_networking_pico.h"
    click JSON "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/provisioning/ConfigJson.cpp"
    click JSON "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/provisioning/ConfigJson.h"
    click FS "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/provisioning/littlefs/WipperSnapper_LittleFS.cpp"
    click FS "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/provisioning/littlefs/WipperSnapper_LittleFS.h"
    click USB "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/provisioning/tinyusb/Wippersnapper_FS.cpp"
    click USB "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/provisioning/tinyusb/Wippersnapper_FS.h"
    click NPBR "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/nanopb/ws_pb_helpers.cpp"
    click NPBR "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/src/nanopb/ws_pb_helpers.h"
    click EX "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/examples/Wippersnapper_demo/Wippersnapper_demo.ino"
    click CI "https://github.com/adafruit/adafruit_wippersnapper_arduino/blob/main/platformio.ini"
    click CI "https://github.com/adafruit/adafruit_wippersnapper_arduino/tree/main/.github/workflows"
    click CI "https://github.com/adafruit/adafruit_wippersnapper_arduino/tree/main/Doxyfile"

    %% Styles
    classDef hardware fill:#f9f,stroke:#333;
    classDef provisioning fill:#ff9,stroke:#333;
    classDef component fill:#9ff,stroke:#333;
    classDef core fill:#cfc,stroke:#333;
    classDef serialization fill:#ccf,stroke:#333;
    classDef network fill:#fcf,stroke:#333;
    classDef cloud fill:#eef,stroke:#333,stroke-dasharray: 5 5;
    classDef display fill:#ffa,stroke:#333;
    classDef examples fill:#ddd,stroke:#333,stroke-dasharray: 2 2;
    classDef ci fill:#ddd,stroke:#333,stroke-dasharray: 2 2;
```
