# wiznet-ionic/w55rp20-s2e architecture

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

## Overview

##### Project type and overall purpose
- This is embedded firmware for the W55RP20 System-in-Package (RP2040 + W5500 + Flash).
- It implements a Serial-to-Ethernet gateway (S2E), hosts an HTTP server, speaks Modbus, and optionally connects to AWS IoT over TLS.
- There is a two-stage firmware flow: a small Bootloader (“main/Boot” + port/boot/... ) and the full Application (“main/App” + port/app/...).

##### File structure
- Top level:
– CMake scripts (pico_sdk_import, FreeRTOS_Kernel_import, project CMakeLists).
– libraries/ (third-party code: FreeRTOS, AWS IoT SDK, mbedtls, ioLibrary_Driver, pico‐sdk).
– main/Boot and main/App (bootloader and application entry points).
- port/boot/… and port/app/… hold the Hardware Abstraction Layer (HAL) / Board Support Package:
– board drivers, configuration parser, serial_to_ethernet, HTTP server modules, Modbus, timers, platform handlers, etc.
- main/App/App.c is where FreeRTOS is brought up, tasks are created, peripherals initialized.

##### Extract behavioral cues from the README
- The firmware runs under FreeRTOS on RP2040.
- W5500 Ethernet is accessed via SPI through the ioLibrary_Driver.
- Serial data (UART) is bridged to Ethernet (TCP/UDP) or Modbus-TCP.
- An HTTP server serves static pages from flash and provides a management interface.
- Optionally, AWS IoT Device SDK + mbedtls provides an MQTT over TLS client.

##### Sketch the high-level components (layered view)
a. Hardware block
– W55RP20 SiP: RP2040 MCU core + internal 2 MB flash + W5500 Ethernet controller.
– External interfaces: UART pins for data and debug, GPIO pins for status, SPI bus to W5500.
b. HAL / Port layer
– SPI driver (wiznet_spi.c, w5x00_gpio_irq.c)
– UART driver (uartHandler.c)
– Timer driver (timer.c)
– Flash configuration parser (ConfigData.c, segcp.c)
– GPIO, network, storage, DHCP/DNS callbacks (platform_handler/*.c)
c. Middleware / libraries
– ioLibrary_Driver (network socket API over W5500 SPI)
– HTTP server modules (httpParser.c, httpServer.c, httpUtil.c)
– Modbus library (mb*.c)
– AWS-IoT Device SDK (core_http, core_mqtt)
– mbedtls (SSLInterface.c, SSL_Random.c)
d. RTOS kernel
– FreeRTOS core (task scheduler, queues, semaphores)
e. Application modules (FreeRTOS tasks)
– Serial-to-Ethernet task
– HTTP-server task
– Modbus-TCP task
– MQTT/AWS-IoT task
– Configuration management task
– Maintenance/Bootloader fallback (in Bootloader stage)
f. External systems
– Ethernet LAN and remote clients (web browsers, Modbus-TCP masters)
– AWS IoT Core (MQTT broker)
– Serial host (RS-232/422/485 devices)

##### Relationships & data-flow
- Bootloader initializes clocks, board, Flash, then optionally jumps to Application.
- Application starts FreeRTOS, spins up tasks.
- Each task uses port layer (HAL) to access hardware.
- Network-related tasks call ioLibrary_Driver → SPI → W5500.
- TLS/MQTT tasks call mbedtls + AWS IoT SDK → ioLibrary_Driver.
- HTTP server reads Web_page.bin from flash (html_file) via storageHandler.
- Serial data enters via UART driver → serial_to_ethernet module → socket API (ioLibrary_Driver) → network.
- Configuration is stored/read in flash via ConfigData and segcp modules.

##### Architectural patterns & principles
- Layered architecture: Hardware → HAL → Drivers → Middleware → Application → External
- Clear separation: Boot vs. App
- Concurrency via RTOS tasks with well-defined interfaces (queues/callbacks)
- Hardware abstraction for portability (port_common.h, platform_handler)
- Reuse of open-source libraries (FreeRTOS, pico-sdk, AWS SDK, mbedtls)

##### Diagramming recommendations
– HAL / drivers (blue)
– Middleware libraries (green)
– RTOS kernel (purple)
– Application tasks/modules (orange)
– External systems (light purple)
– Task → HAL calls (downward)
– HAL → hardware (downward)
– Middleware → HAL (downward)
– Hardware interrupts → RTOS callbacks (upward)
– Network flows → external cloud/clients
- That Flash memory holds both firmware (Boot/App) and static web pages (Web_page.bin).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Bootloader Stage
    subgraph "Bootloader Stage"
        direction TB
        BL["Bootloader Entry Point\n(main/Boot/Boot.c)"]:::app
        B_HAL1["WIZnet_board.c"]:::hal
        B_HAL2["w5x00_spi.c"]:::hal
        B_HAL3["uartHandler.c"]:::hal
        B_HAL4["timer.c"]:::hal
        B_HAL5["seg.c"]:::hal
    end

    %% Application Stage
    subgraph "Application Stage"
        direction TB
        APP["Application Entry Point\n(main/App/App.c)"]:::app
        subgraph "HAL / Port Layer"
            direction TB
            A_HAL1["WIZnet_board.c"]:::hal
            A_HAL2["w5x00_spi.c & wiznet_spi_pio.c"]:::hal
            A_HAL3["uartHandler.c"]:::hal
            A_HAL4["timer.c"]:::hal
            A_HAL5["ConfigData.c & segcp.c"]:::hal
            A_HAL6["platform_handler/*.c"]:::hal
        end
        subgraph "Middleware Libraries"
            direction TB
            ML1["ioLibrary_Driver"]:::middleware
            ML2["mbedtls"]:::middleware
            ML3["aws-iot-device-sdk"]:::middleware
            ML4["pico-sdk"]:::middleware
            ML5["FreeRTOS-Kernel"]:::middleware
        end
        subgraph "RTOS Kernel"
            direction TB
            RTOS["FreeRTOS Core"]:::rtos
        end
        subgraph "Application Tasks"
            direction TB
            T1["Serial-to-Ethernet Task"]:::app
            T2["HTTP Server Task"]:::app
            T3["Modbus-TCP Task"]:::app
            T4["MQTT/AWS-IoT Task"]:::app
            T5["Configuration Management Task"]:::app
            T6["Maintenance/Bootloader Fallback"]:::app
        end
    end

    %% Hardware
    subgraph "Hardware (W55RP20 SiP)" 
        direction TB
        HW1["RP2040 MCU"]:::hardware
        HW2["Internal Flash"]:::hardware
        HW3["W5500 Ethernet Controller"]:::hardware
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        EXT1["Ethernet LAN & Clients"]:::external
        EXT2["AWS IoT Core"]:::external
        EXT3["Serial Host"]:::external
    end

    %% Connections
    BL -->|"boots/jump"| APP
    BL -->|init board| B_HAL1
    B_HAL1 --> B_HAL2
    B_HAL2 --> B_HAL3
    B_HAL3 --> B_HAL4
    B_HAL4 --> B_HAL5

    APP -->|calls HAL| A_HAL1
    APP -->|calls HAL| A_HAL2
    APP -->|calls HAL| A_HAL3
    APP -->|calls HAL| A_HAL4
    APP -->|reads config| A_HAL5

    A_HAL* -->|SPI/I2C/UART| HW1
    ML1 -->|SPI calls| A_HAL2
    ML2 -->|crypto| ML1
    ML3 -->|MQTT API| ML1
    ML4 -->|SDK support| APP
    ML5 -->|RTOS| APP

    RTOS -->|schedules| T1
    RTOS -->|schedules| T2
    RTOS -->|schedules| T3
    RTOS -->|schedules| T4
    RTOS -->|schedules| T5
    RTOS -->|schedules| T6

    T1 -->|socket API| ML1
    T2 -->|httpParser/httpServer| ML1
    T2 -->|serve Web_page.bin| HW2
    T3 -->|mbtcp| ML1
    T4 -->|TLS handshake| ML2
    T4 -->|MQTT publish| ML3
    T5 -->|flash config| A_HAL5
    T6 -->|fallback boot| BL

    HW3 -->|Ethernet| EXT1
    T4 -->|MQTT| EXT2
    T1 -->|UART data| EXT3

    %% Click Events
    click BL "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/main/Boot/Boot.c"
    click B_HAL1 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/boot/board/src/WIZnet_board.c"
    click B_HAL2 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/boot/ioLibrary_Driver/src/w5x00_spi.c"
    click B_HAL3 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/boot/platform_handler/src/uartHandler.c"
    click B_HAL4 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/boot/timer/src/timer.c"
    click B_HAL5 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/boot/serial_to_ethernet/src/seg.c"
    click APP "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/main/App/App.c"
    click A_HAL1 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/board/src/WIZnet_board.c"
    click A_HAL2 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/ioLibrary_Driver/src/w5x00_spi.c"
    click A_HAL2 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/ioLibrary_Driver/src/wiznet_spi_pio.c"
    click A_HAL3 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/platform_handler/src/uartHandler.c"
    click A_HAL4 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/timer/src/timer.c"
    click A_HAL5 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/configuration/src/ConfigData.c"
    click A_HAL5 "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/configuration/src/segcp.c"
    click ML1 "https://github.com/wiznet-ionic/w55rp20-s2e/tree/main/libraries/ioLibrary_Driver"
    click ML2 "https://github.com/wiznet-ionic/w55rp20-s2e/tree/main/libraries/mbedtls"
    click ML3 "https://github.com/wiznet-ionic/w55rp20-s2e/tree/main/libraries/aws-iot-device-sdk-embedded-C"
    click ML4 "https://github.com/wiznet-ionic/w55rp20-s2e/tree/main/libraries/pico-sdk"
    click ML5 "https://github.com/wiznet-ionic/w55rp20-s2e/tree/main/libraries/FreeRTOS-Kernel"
    click RTOS "https://github.com/wiznet-ionic/w55rp20-s2e/blob/main/port/app/FreeRTOS-Kernel/inc/FreeRTOSConfig.h"

    %% Styles
    classDef hardware fill:#dddddd,stroke:#999,stroke-width:1px
    classDef hal fill:#cce5ff,stroke:#3399ff,stroke-width:1px
    classDef middleware fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef rtos fill:#f5c6cb,stroke:#c82333,stroke-width:1px
    classDef app fill:#ffeeba,stroke:#e0a800,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
