# lds133/weather_landscape architecture

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

- Interactive diagram: https://gitdiagram.com/lds133/weather_landscape
- Repository: https://github.com/lds133/weather_landscape

## Overview

##### Project Type and Purpose
- This project is a hybrid full-stack system that combines image generation (using Python and Pillow) with an embedded hardware component (ESP32 controlling an E-Ink display).
- Its purpose is to retrieve weather data from OpenWeather, encode weather conditions as landscape imagery, and then display the weather information in a calming, intuitive visual format.

##### Main Components
A. Weather Image Generation (Python Application)
- p_weather Module: Includes components (like draw_weather.py, openweathermap.py, and sprites) that:
- Query weather data from the OpenWeather API.
- Process the data and map weather parameters to specific visual elements in the landscape.
- Use a template and sprite images to compose the final BMP image.
- run_test.py: For testing the image generation.
- run_server.py: Likely serving the image generation functionality in a continuous server mode.
- requirements.txt & environment scripts (makevenv.bat/sh): Define the environment and dependencies.

B. Hardware Integration (ESP32 Module)
- esp32 Directory: Contains MicroPython code targeted for the ESP32 board.
- The board subdirectory includes files like boot.py, main.py, and various utility modules (wifi.py, eink.py, led.py, etc.) that manage:
▫ Board-specific configurations.
▫ E-Ink display control.
▫ Peripheral interfaces such as WiFi and LED controls.
- The “esp32/pic” folder with test bitmap files is used for hardware testing.
- README.md within the ESP32 folder provides additional hardware-focused instructions.

C. External Dependencies and Data Flow
- OpenWeather API: An external service providing weather forecast data.
- Pillow Library: Used for image processing and drawing.
- The final BMP image is distributed to the E-Ink display via the ESP32. Data is exchanged between the weather image generator and the hardware component – either by serving an image via run_server.py or by storing the file on disk for ESP32 retrieval.

##### Component Relationships and Data Flow
- The p_weather image generation logic processes this data using Pillow and sprite assets to create the BMP image; this is tested by run_test.py and/or served by run_server.py.
- A connection is established (or in planned design, to be established) between this generation layer and the ESP32 hardware. The ESP32 code (in esp32/board) then retrieves the image – either through a direct network call to the local server or via file transfer – and displays it on the connected 2.9-inch E-Ink screen.
- Configuration values, like API keys and geographic coordinates, are maintained in secrets.py.

##### Architectural Patterns and Technologies
- Modular Design: Separation of concerns between image generation and hardware display.
- Client-Server Pattern: The image generator can run as a server (using run_server.py) and may serve images to the ESP32 device.
- Use of MicroPython on the ESP32 for lightweight, embedded control.
- Utilization of third-party libraries, such as Pillow, for handling image processing.

- Software back-end and image processing
- Hardware and embedded systems.
b. Label Components Clearly:
- Under the Software section, include components like:
▫ Weather Image Generator (with modules p_weather, run_test.py, run_server.py)
▫ External Weather Data (OpenWeather API)
- Under the Hardware section, detail:
▫ ESP32 Microcontroller (with its board-specific MicroPython scripts: boot.py, main.py, etc.)
▫ E-Ink Display Module
- Image processing flow from p_weather through to the output BMP file.
e. Build/Deployment Tools:
- Environment preparation (makevenv scripts, requirements.txt) and testing steps (run_test.py) as peripheral elements in the design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    OWA["OpenWeather API"]:::external

    %% Software Image Generation Subgraph
    subgraph "Software Image Generation"
        direction TB
        PWeather["p_weather Module"]:::software
        RunTest["Image Generation Test Script (run_test.py)"]:::software
        RunServer["Image Generation Server (run_server.py)"]:::software
        AssetRepo["Asset Repository (Static Images)"]:::software
        EnvSetup["Env & Dependency Setup"]:::software
        Secrets["Secrets/Configuration"]:::software
        BMP["Generated BMP Image"]:::software
    end

    %% Hardware Integration Subgraph
    subgraph "Hardware Integration"
        direction TB
        ESP32["ESP32 Microcontroller (esp32/board)"]:::hardware
        EInk["E-Ink Display Module"]:::hardware
        ESP32Assets["ESP32 Testing Assets"]:::support
        ESP32Doc["ESP32 Hardware Documentation"]:::support
    end

    %% Data Flow Connections
    OWA -->|"providesData"| PWeather
    PWeather -->|"processesData"| BMP
    PWeather -->|"supportsTesting"| RunTest
    PWeather -->|"operatesAsServer"| RunServer
    PWeather -->|"utilizesAssets"| AssetRepo
    EnvSetup -.-> PWeather
    Secrets -.-> PWeather

    BMP -->|"deliversImage"| ESP32
    ESP32 -->|"drivesDisplay"| EInk
    ESP32 ---|"includes"| ESP32Assets
    ESP32 ---|"documentedBy"| ESP32Doc

    %% Click Events
    click PWeather "https://github.com/lds133/weather_landscape/tree/main/p_weather/"
    click RunTest "https://github.com/lds133/weather_landscape/blob/main/run_test.py"
    click RunServer "https://github.com/lds133/weather_landscape/blob/main/run_server.py"
    click AssetRepo "https://github.com/lds133/weather_landscape/tree/main/pic/"
    click EnvSetup "https://github.com/lds133/weather_landscape/blob/main/requirements.txt"
    click Secrets "https://github.com/lds133/weather_landscape/blob/main/secrets.py.example"
    click ESP32 "https://github.com/lds133/weather_landscape/tree/main/esp32/board/"
    click ESP32Assets "https://github.com/lds133/weather_landscape/tree/main/esp32/pic/"
    click ESP32Doc "https://github.com/lds133/weather_landscape/blob/main/esp32/README.md"

    %% Styles
    classDef external fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef software fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef hardware fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef support fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
