# wiznet-ionic/wiznet-pico-freertos-c architecture

> Architecture diagram of the GitHub repository wiznet-ionic/wiznet-pico-freertos-c, 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/wiznet-ionic/wiznet-pico-freertos-c
- Repository: https://github.com/wiznet-ionic/wiznet-pico-freertos-c

## Overview

##### Project type and purpose
- This is an embedded firmware project providing FreeRTOS-based network examples for the Raspberry Pi Pico (RP2040) paired with WIZnet W5x00 Ethernet chips.
- It is organized around a layered architecture: hardware → hardware-abstraction (port) → OS kernel → network/security libraries → application examples.

##### Main components
a. Hardware Layer
- RP2040 MCU (CPU, PIO, SPI, GPIO, Timer peripherals)
- WIZnet W5x00 Ethernet chip (W5100S or W5500…)
- Physical connections: SPI bus lines, Chip-Select GPIO, Reset GPIO, IRQ line
b. Port / HAL Layer (under port/)
- port/ioLibrary_Driver: SPI read/write, GPIO IRQ callbacks
- port/FreeRTOS-Kernel: board-specific FreeRTOSConfig.h
- port/mbedtls: SSL configuration adaptations
- port/timer: 1 ms timer and delay functions
c. RTOS Layer
- FreeRTOS Kernel (scheduling, tasks, queues, critical sections)
- CMake integration (FreeRTOS_Kernel_import.cmake)
d. Middleware Layer
- ioLibrary_Driver (network stack API: socket, init, DHCP/DNS support)
- mbedtls (TLS/SSL functionality)
- pico-sdk & pico-extras (board support, SDK utilities)
e. Application Layer (examples/)
- DHCP & DNS task
- MQTT client task
- TCP client over SSL task
f. Build & Tooling
- CMakeLists.txt (top-level and per-module)
- Git submodules (sdk, FreeRTOS, mbedtls, ioLibrary_Driver)
- Patches (patches/0001–0003 to support clocks, TFTP, FTP)

##### Relationships and data flows
- Application tasks create sockets or initiate TLS sessions via ioLibrary_Driver and mbedtls APIs.
- These libraries invoke port layer functions (wizchip_spi_initialize, wizchip_read/write, timer callbacks, IRQ callbacks).
- Port functions control the RP2040 peripherals (SPI, PIO, GPIO, timers).
- SPI transactions go over the physical bus to/from the W5x00 chip, which handles Ethernet frames.
- The RTOS scheduler manages task execution, context switches, and critical‐section locks around SPI calls.
- Build system ties all modules together via CMake, pulling submodules and patches.

##### Architectural patterns and design principles
- Layered architecture: clear separation of hardware access (port), OS (FreeRTOS), middleware (network+TLS), and application logic (examples).
- Hardware‐abstraction via port directory to support multiple MCUs.
- Modularity by using Git submodules for third-party dependencies.
- Use of FreeRTOS for real-time scheduling and synchronization (mutexes around SPI).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        RP2040["RP2040 MCU<br/>(SPI, GPIO, Timer, PIO)"]:::hardware
        W5x00["W5x00 Ethernet Chip"]:::hardware
    end
    RP2040 -->|"SPI, CS, IRQ, Reset"| W5x00

    %% Port/HAL Layer
    subgraph "Port/HAL Layer"
        IOLib["port/ioLibrary_Driver"]:::hal
        FreeRTOS_Port["FreeRTOS Config"]:::hal
        Mbedtls_Port["port/mbedtls"]:::hal
        TimerC["timer.c"]:::hal
        TimerH["timer.h"]:::hal
    end
    IOLib -->|wizchip_read/write| RP2040
    TimerC -->|1ms tick| RP2040
    TimerH -->|delay functions| RP2040
    FreeRTOS_Port -.->|board config| FreeRTOS_Kernel
    Mbedtls_Port -.->|SSL config| Mbedtls_MW

    %% RTOS Layer
    subgraph "RTOS Layer"
        FreeRTOS_Kernel["FreeRTOS Kernel"]:::rtos
        RTOS_CMake["FreeRTOS_Kernel_import.cmake"]:::rtos
    end
    FreeRTOS_Kernel -->|schedules tasks| DHCP_Task
    FreeRTOS_Kernel -->|mutex around SPI| IOLib
    RTOS_CMake -.->|integrates| FreeRTOS_Kernel

    %% Middleware Layer
    subgraph "Middleware Layer"
        IOLib_MW["ioLibrary_Driver"]:::middleware
        Mbedtls_MW["mbedtls"]:::middleware
        Pico_SDK["pico-sdk & pico-extras"]:::middleware
    end
    DHCP_Task -->|socket API| IOLib_MW
    MQTT_Task -->|socket API| IOLib_MW
    TCPSSL_Task -->|TLS API| Mbedtls_MW
    IOLib_MW -->|calls port| IOLib
    Mbedtls_MW -->|calls port| Mbedtls_Port
    IOLib_MW -->|uses SDK| Pico_SDK

    %% Application Layer
    subgraph "Application Layer"
        DHCP_Task["DHCP & DNS Task"]:::app
        MQTT_Task["MQTT Client Task"]:::app
        TCPSSL_Task["TCP over SSL Task"]:::app
        DHCP_C["w5x00_dhcp_dns.c"]:::app
        DHCP_Cmake["CMakeLists.txt"]:::app
        MQTT_C["w5x00_mqtt.c"]:::app
        MQTT_Cmake["CMakeLists.txt"]:::app
        TCP_C["w5x00_tcp_client_over_ssl.c"]:::app
        TCP_Cmake["CMakeLists.txt"]:::app
    end
    DHCP_Task --> DHCP_C
    DHCP_Task --> DHCP_Cmake
    MQTT_Task --> MQTT_C
    MQTT_Task --> MQTT_Cmake
    TCPSSL_Task --> TCP_C
    TCPSSL_Task --> TCP_Cmake

    %% Build & Tooling
    subgraph "Build & Tooling"
        TopCMake["Top-level CMakeLists.txt"]:::tool
        PicoImport["pico_sdk_import.cmake"]:::tool
        GitModules[".gitmodules"]:::tool
        Patch1["0001_pico_sdk_clocks.patch"]:::tool
        Patch2["0002_iolibrary_driver_tftp.patch"]:::tool
        Patch3["0003_iolibrary_driver_ftp_client.patch"]:::tool
    end
    GitModules -->|defines submodules| FreeRTOS_Kernel
    GitModules -->|defines submodules| Mbedtls_MW
    GitModules -->|defines submodules| IOLib_MW
    GitModules -->|defines submodules| Pico_SDK
    TopCMake -->|includes| RTOS_CMake
    TopCMake -->|includes| PicoImport
    TopCMake -->|applies| Patch1
    TopCMake -->|applies| Patch2
    TopCMake -->|applies| Patch3

    %% Click Events
    click IOLib "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/tree/main/port/ioLibrary_Driver/inc"
    click FreeRTOS_Port "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/port/FreeRTOS-Kernel/inc/FreeRTOSConfig.h"
    click Mbedtls_Port "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/port/mbedtls/inc/ssl_config.h"
    click TimerC "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/port/timer/timer.c"
    click TimerH "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/port/timer/timer.h"
    click FreeRTOS_Kernel "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/tree/main/libraries/FreeRTOS-Kernel"
    click RTOS_CMake "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/FreeRTOS_Kernel_import.cmake"
    click IOLib_MW "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/tree/main/libraries/ioLibrary_Driver"
    click Mbedtls_MW "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/tree/main/libraries/mbedtls"
    click Pico_SDK "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/tree/main/libraries/pico-sdk"
    click DHCP_C "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/examples/dhcp_dns/w5x00_dhcp_dns.c"
    click DHCP_Cmake "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/examples/dhcp_dns/CMakeLists.txt"
    click MQTT_C "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/examples/mqtt/w5x00_mqtt.c"
    click MQTT_Cmake "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/examples/mqtt/CMakeLists.txt"
    click TCP_C "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/examples/tcp_client_over_ssl/w5x00_tcp_client_over_ssl.c"
    click TCP_Cmake "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/examples/tcp_client_over_ssl/CMakeLists.txt"
    click TopCMake "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/CMakeLists.txt"
    click PicoImport "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/pico_sdk_import.cmake"
    click Patch1 "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/patches/0001_pico_sdk_clocks.patch"
    click Patch2 "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/patches/0002_iolibrary_driver_tftp.patch"
    click Patch3 "https://github.com/wiznet-ionic/wiznet-pico-freertos-c/blob/main/patches/0003_iolibrary_driver_ftp_client.patch"

    %% Styles
    classDef hardware fill:#d3d3d3,stroke:#555;
    classDef hal fill:#add8e6,stroke:#555;
    classDef rtos fill:#87cefa,stroke:#555;
    classDef middleware fill:#90ee90,stroke:#555;
    classDef app fill:#ffa500,stroke:#555;
    classDef tool fill:#f0e68c,stroke:#555;
```
