# lch-98/weather_information_system architecture

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

- Interactive diagram: https://gitdiagram.com/lch-98/weather_information_system
- Repository: https://github.com/lch-98/weather_information_system

## Overview

##### Project Type and Purpose
- This is an embedded IoT application running on a Raspberry Pi Pico W.
- It uses FreeRTOS for task scheduling, the Pico SDK for hardware abstraction, lwIP for network, HTTP to fetch weather data, NTP to sync time, and SPI to drive an LCD.

##### High-Level Components
A. Hardware
- Raspberry Pi Pico W (MCU + Wi-Fi)
- SPI-based LCD module
B. Firmware Layers
1. FreeRTOS Kernel (lib/FreeRTOS-Kernel)
2. Pico SDK (lib/pico-sdk + pico_sdk_import.cmake)
3. Network Stack (lwIP, configured via src/http_weather/lwipopts.h)
4. Application Tasks
– HTTP Weather Task (src/http_weather/http_weather.c/h)
– NTP Sync Task (src/http_weather/ntp_sync/ntp_client.c/h)
– Display Task (src/picow_lcd/display.c/h)
5. LCD Driver (src/picow_lcd/lcd_sdk/*.c/h)
C. Host-side Tools
- python_bitmap/*.py – generate C arrays for 8×16 and 16×16 Korean fonts, PNG bitmaps

##### File-to-Component Mapping (where each file “runs”)
- src/main.cpp
- Board and RTOS initialization
- Creates and schedules three tasks: HTTP, NTP, Display
- src/http_weather/http_weather.c/h
- Executes in HTTP Weather Task
- Uses lwIP’s socket APIs to GET Weather API, calls jsmn.h to parse JSON
- src/http_weather/json/jsmn.h
- JSON parser library; runs inside HTTP Weather Task
- src/http_weather/ntp_sync/ntp_client.c/h
- Executes in NTP Sync Task
- Sends/receives UDP to NTP servers to set system clock
- src/picow_lcd/display.c/h
- Executes in Display Task
- src/picow_lcd/lcd_sdk/*.c/h
- python_bitmap/*.py

##### Interactions and Data Flow
- At startup (main.cpp): initialize hardware → start FreeRTOS scheduler
- NTP Task ↔ External NTP Server: sync RTC → store current time in shared variable
- HTTP Task ↔ Weather API: fetch JSON → parse → store weather data in shared buffer
- Shared buffers or FreeRTOS queues guard data handoff between tasks

##### Architectural Patterns and Principles
- Layered Abstraction: hardware (SPI, GPIO) → drivers (lcd_sdk) → middleware (lwIP, JSON) → application tasks
- RTOS-based concurrency: separate tasks for I/O, network, display
- Modularity: clear separation of HTTP, NTP, display code in distinct directories
- Build System: CMake orchestrates pico-sdk and FreeRTOS as submodules

##### Technical Callouts
- FreeRTOS Kernel (task scheduling, mutexes/queues)
- LWIP Http Client (socket APIs configured by lwipopts.h)
- JSMN JSON parser (header-only library)
- SPI protocol and GPIO controls (in lcd.c/h)
- NTP over UDP for accurate RTC

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build System"
        CMakeRoot["CMakeLists.txt\n(project root)"]:::infra
        CMakeSrc["src/CMakeLists.txt"]:::infra
    end

    subgraph "Platform"
        SDK["Pico SDK\nlib/pico-sdk\npico_sdk_import.cmake"]:::infra
        RTOS["FreeRTOS Kernel\nlib/FreeRTOS-Kernel"]:::infra
        LWIPConf["lwIP Config\nsrc/http_weather/lwipopts.h"]:::infra
    end

    Main["Main & RTOS Init\nsrc/main.cpp\n(initializes hardware, starts scheduler)"]:::infra

    subgraph "RTOS Tasks"
        HTTPTask["HTTP Weather Task\nsrc/http_weather/http_weather.c/h\n(runs HTTP task)"]:::tasks
        NTPT["NTP Sync Task\nsrc/http_weather/ntp_sync/ntp_client.c/h\n(runs NTP task)"]:::tasks
        DisplayTask["Display Task\nsrc/picow_lcd/display.c/h\n(runs Display task)"]:::tasks
    end

    subgraph "LCD Driver" 
        Font["Font Rendering\nsrc/picow_lcd/lcd_sdk/font.c/h"]:::drivers
        Icon["Icon Rendering\nsrc/picow_lcd/lcd_sdk/icon.c/h"]:::drivers
        LCDDrv["SPI & LCD Ops\nsrc/picow_lcd/lcd_sdk/lcd.c/h"]:::drivers
    end

    subgraph "External Services"
        WeatherAPI["Weather API\n(HTTP)"]:::external
        NTPServer["NTP Servers\n(UDP)"]:::external
    end

    Host["Bitmap Generation Tools\npython_bitmap/*.py"]:::host

    %% Connections
    CMakeRoot --> SDK
    CMakeRoot --> RTOS
    CMakeRoot --> Main
    CMakeSrc --> SDK
    CMakeSrc --> RTOS

    SDK --> Main
    RTOS --> Main
    Main --> HTTPTask
    Main --> NTPT
    Main --> DisplayTask

    HTTPTask --> LWIPConf
    HTTPTask -->|"uses JSON parser"| JSONParser
    HTTPTask -->|"GET Weather"| WeatherAPI
    WeatherAPI -->|JSON response| HTTPTask

    NTPT -->|"UDP request"| NTPServer
    NTPServer -->|"time response"| NTPT

    DisplayTask --> LCDDrv
    LCDDrv --> Font
    LCDDrv --> Icon
    DisplayTask -->|"SPI writes"| LCDDrv

    Host -->|"pre-build generate headers"| DisplayTask

    %% JSON Parser separate node
    JSONParser["JSMN JSON Parser\nsrc/http_weather/json/jsmn.h"]:::infra

    %% Click Events
    click RTOS "https://github.com/lch-98/weather_information_system/tree/main/lib/FreeRTOS-Kernel"
    click SDK "https://github.com/lch-98/weather_information_system/tree/main/lib/pico-sdk"
    click CMakeRoot "https://github.com/lch-98/weather_information_system/blob/main/CMakeLists.txt"
    click CMakeSrc "https://github.com/lch-98/weather_information_system/blob/main/src/CMakeLists.txt"
    click Main "https://github.com/lch-98/weather_information_system/blob/main/src/main.cpp"
    click HTTPTask "https://github.com/lch-98/weather_information_system/blob/main/src/http_weather/http_weather.c"
    click HTTPTask "https://github.com/lch-98/weather_information_system/blob/main/src/http_weather/http_weather.h"
    click JSONParser "https://github.com/lch-98/weather_information_system/blob/main/src/http_weather/json/jsmn.h"
    click LWIPConf "https://github.com/lch-98/weather_information_system/blob/main/src/http_weather/lwipopts.h"
    click NTPT "https://github.com/lch-98/weather_information_system/blob/main/src/http_weather/ntp_sync/ntp_client.c"
    click NTPT "https://github.com/lch-98/weather_information_system/blob/main/src/http_weather/ntp_sync/ntp_client.h"
    click DisplayTask "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/display.c"
    click DisplayTask "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/display.h"
    click Font "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/lcd_sdk/font.c"
    click Font "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/lcd_sdk/font.h"
    click Icon "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/lcd_sdk/icon.c"
    click Icon "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/lcd_sdk/icon.h"
    click LCDDrv "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/lcd_sdk/lcd.c"
    click LCDDrv "https://github.com/lch-98/weather_information_system/blob/main/src/picow_lcd/lcd_sdk/lcd.h"
    click Host "https://github.com/lch-98/weather_information_system/blob/main/python_bitmap/korean_bitmap8*16.py"

    %% Styles
    classDef tasks fill:#cce5ff,stroke:#004085,color:#004085
    classDef drivers fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef host fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef infra fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
