# arduino-libraries/wifi architecture

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

- Interactive diagram: https://gitdiagram.com/arduino-libraries/wifi
- Repository: https://github.com/arduino-libraries/wifi

## Overview

##### Project type and purpose
- This is an Arduino “WiFi” library (an SDK-style library) that exposes a simple C++ API to Arduino sketches, letting an Arduino board talk over Wi-Fi via the official Arduino WiFi Shield.

##### File structure
- Top-level “src/” folder holds the core C++ API: WiFi, WiFiClient, WiFiServer, WiFiUdp.
- Under src/utility a thin C “driver” layer lives: spi_drv, wifi_drv, server_drv, debug helpers, plus low-level definitions (wl_definitions, wl_types).
- “examples/” contains user-facing Arduino .ino sketches demonstrating how to use the API.
- “extras/” holds binary firmware blobs (wifiHD, wifi_dnld) and scripts/tools to upgrade the shield’s on-board AT32 microcontroller firmware.
- docs/, README.adoc, library.properties, keywords.txt provide documentation, build info, CI workflows in .github/workflows.

##### Key insights from the README
- The library plugs into the Arduino WiFi Shield hardware.
- It provides a standard Arduino-style C++ interface (WiFi, WiFiClient, etc.) that wraps an underlying C driver layer talking over SPI to an on-shield Atmel AT32 microcontroller that runs lwIP for TCP/IP.

##### Main components & relationships
a. Application Layer (Arduino Sketches)
- examples/*.ino
- Calls WiFi.h API classes (WiFi, WiFiClient, WiFiServer, WiFiUdp).
b. Library API Layer (C++ wrapper)
- src/WiFi.cpp/h, WiFiClient.cpp/h, etc.
- Implements high-level calls: begin(ssid), connect(), hostByName(), server(), udp().
c. Utility/Driver Layer (C layer)
- src/utility/spi_drv.cpp/h → abstracts the SPI bus on the Arduino MCU.
- src/utility/wifi_drv.cpp/h → wraps hardware protocol to the AT32.
- src/utility/server_drv.cpp/h → manages socket-style sessions over the firmware.
- debug.h → logging over Serial for debugging.
d. Atmel AT32 Microcontroller on Shield
- Pre-loaded firmware (wifiHD) implements IEEE802.11 MAC, TCP/IP stack (lwIP), DHCP, DNS, sockets.
- Receives SPI commands from driver, serves back network packets.
e. Wi-Fi Radio & External Network
- AT32’s Wi-Fi radio link to an Access Point → Router → Internet.
f. Firmware Tools (extras)
- Scripts and ELF/HEX binaries for flashing or upgrading the shield’s AT32 firmware (wifi_dnld).

##### Architectural patterns & design principles
- Layered architecture: Sketch → C++ API → C-based hardware abstraction → on-board firmware → network link → Internet.
- Adapter/Facade: WiFiClient etc. adapt low-level driver calls into Arduino-style APIs.
- Hardware abstraction: spi_drv isolates board-specific SPI calls; wifi_drv isolates protocol specifics.
- Separation of concerns: application vs. API vs. driver vs. firmware.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Arduino Sketch Layer
    subgraph "Arduino Sketch Layer"
        Sketch["examples/*.ino"]:::sketch
    end

    %% C++ API Layer
    subgraph "C++ API Layer"
        WiFi_h["WiFi.h"]:::api
        WiFi_cpp["WiFi.cpp"]:::api
        WiFiClient_h["WiFiClient.h"]:::api
        WiFiClient_cpp["WiFiClient.cpp"]:::api
        WiFiServer_h["WiFiServer.h"]:::api
        WiFiServer_cpp["WiFiServer.cpp"]:::api
        WiFiUdp_h["WiFiUdp.h"]:::api
        WiFiUdp_cpp["WiFiUdp.cpp"]:::api
    end

    %% Utility Driver Layer
    subgraph "Utility Driver Layer"
        spi_drv_h["spi_drv.h"]:::driver
        spi_drv_cpp["spi_drv.cpp"]:::driver
        wifi_drv_h["wifi_drv.h"]:::driver
        wifi_drv_cpp["wifi_drv.cpp"]:::driver
        server_drv_h["server_drv.h"]:::driver
        server_drv_cpp["server_drv.cpp"]:::driver
        debug_h["debug.h"]:::driver
        wifi_spi_h["wifi_spi.h"]:::driver
        wl_definitions_h["wl_definitions.h"]:::driver
        wl_types_h["wl_types.h"]:::driver
    end

    %% Hardware Interface
    SPIBus["SPI Bus (Physical)"]:::hw

    %% On-Shield Firmware Layer
    subgraph "On-Shield Firmware"
        AT32FW["AT32 UC3A MCU + lwIP v1.3.2\nFirmware (wifiHD)"]:::firmware
    end

    %% External Network Layer
    subgraph "External Network"
        WiFiRadio["802.11 Radio"]:::external
        AP["Access Point"]:::external
        Router["Router"]:::external
        Internet["Internet"]:::external
    end

    %% Firmware Tools (Extras)
    subgraph "Firmware Tools"
        scripts_sh["ArduinoWifiShield_upgrade.sh"]:::extras
        wifiHD_elf["wifiHD.elf"]:::extras
        wifiHD_hex["wifiHD.hex"]:::extras
        wifi_dnld_elf["wifi_dnld.elf"]:::extras
        wifi_dnld_hex["wifi_dnld.hex"]:::extras
        extras_wifiHD_src["extras/wifiHD/src/..."]:::extras
        extras_dnld_src["extras/wifi_dnld/src/..."]:::extras
    end

    %% Connections
    Sketch -->|"uses"| WiFi_h
    WiFi_h -->|"implements"| spi_drv_cpp
    WiFi_cpp --> spi_drv_cpp
    WiFiClient_cpp --> wifi_drv_cpp
    WiFiServer_cpp --> server_drv_cpp
    WiFiUdp_cpp --> wifi_drv_cpp

    spi_drv_cpp -->|"communicates"| SPIBus
    wifi_drv_cpp --> SPIBus
    server_drv_cpp --> SPIBus

    SPIBus -->|"sends commands"| AT32FW
    AT32FW -->|"network frames"| WiFiRadio
    WiFiRadio --> AP --> Router --> Internet

    %% Bidirectional arrows for responses
    Internet -->|"data"| Router --> AP --> WiFiRadio --> AT32FW --> SPIBus --> spi_drv_cpp --> WiFi_h --> Sketch

    %% Click Events
    click Sketch "https://github.com/arduino-libraries/wifi/blob/master/examples/*/*.ino"
    click WiFi_h "https://github.com/arduino-libraries/wifi/blob/master/src/WiFi.h"
    click WiFi_cpp "https://github.com/arduino-libraries/wifi/blob/master/src/WiFi.cpp"
    click WiFiClient_h "https://github.com/arduino-libraries/wifi/blob/master/src/WiFiClient.h"
    click WiFiClient_cpp "https://github.com/arduino-libraries/wifi/blob/master/src/WiFiClient.cpp"
    click WiFiServer_h "https://github.com/arduino-libraries/wifi/blob/master/src/WiFiServer.h"
    click WiFiServer_cpp "https://github.com/arduino-libraries/wifi/blob/master/src/WiFiServer.cpp"
    click WiFiUdp_h "https://github.com/arduino-libraries/wifi/blob/master/src/WiFiUdp.h"
    click WiFiUdp_cpp "https://github.com/arduino-libraries/wifi/blob/master/src/WiFiUdp.cpp"
    click spi_drv_h "https://github.com/arduino-libraries/wifi/blob/master/src/utility/spi_drv.h"
    click spi_drv_cpp "https://github.com/arduino-libraries/wifi/blob/master/src/utility/spi_drv.cpp"
    click wifi_drv_h "https://github.com/arduino-libraries/wifi/blob/master/src/utility/wifi_drv.h"
    click wifi_drv_cpp "https://github.com/arduino-libraries/wifi/blob/master/src/utility/wifi_drv.cpp"
    click server_drv_h "https://github.com/arduino-libraries/wifi/blob/master/src/utility/server_drv.h"
    click server_drv_cpp "https://github.com/arduino-libraries/wifi/blob/master/src/utility/server_drv.cpp"
    click debug_h "https://github.com/arduino-libraries/wifi/blob/master/src/utility/debug.h"
    click wifi_spi_h "https://github.com/arduino-libraries/wifi/blob/master/src/utility/wifi_spi.h"
    click wl_definitions_h "https://github.com/arduino-libraries/wifi/blob/master/src/utility/wl_definitions.h"
    click wl_types_h "https://github.com/arduino-libraries/wifi/blob/master/src/utility/wl_types.h"
    click scripts_sh "https://github.com/arduino-libraries/wifi/blob/master/extras/scripts/ArduinoWifiShield_upgrade.sh"
    click wifiHD_elf "https://github.com/arduino-libraries/wifi/blob/master/extras/binary/wifiHD.elf"
    click wifiHD_hex "https://github.com/arduino-libraries/wifi/blob/master/extras/binary/wifiHD.hex"
    click wifi_dnld_elf "https://github.com/arduino-libraries/wifi/blob/master/extras/binary/wifi_dnld.elf"
    click wifi_dnld_hex "https://github.com/arduino-libraries/wifi/blob/master/extras/binary/wifi_dnld.hex"
    click extras_wifiHD_src "https://github.com/arduino-libraries/wifi/blob/master/extras/wifiHD/src/..."
    click extras_dnld_src "https://github.com/arduino-libraries/wifi/blob/master/extras/wifi_dnld/src/..."

    %% Styles
    classDef sketch fill:#9f6,stroke:#393,stroke-width:1px
    classDef api fill:#6bf,stroke:#036,stroke-width:1px
    classDef driver fill:#f90,stroke:#c60,stroke-width:1px
    classDef hw fill:#ccc,stroke:#888,stroke-width:1px
    classDef firmware fill:#d6c,stroke:#940,stroke-width:1px
    classDef external fill:#6ff,stroke:#039,stroke-width:1px
    classDef extras fill:#fc9,stroke:#c60,stroke-width:1px
```
