# ale-giustina/e-ink-buddy architecture

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

- Interactive diagram: https://gitdiagram.com/ale-giustina/e-ink-buddy
- Repository: https://github.com/ale-giustina/e-ink-buddy

## Overview

##### Project Type and Purpose
- This is an embedded IoT firmware project (PlatformIO) for a microcontroller that fetches real-time transport and weather data, parses it, and renders it on an e-ink display.
- Key objectives:
- Fetch bus arrival times from the Trentino transport API
- Fetch multiple modes of weather data (24h, 5d, precipitation) from Open-Meteo
- Parse JSON responses
- Render text and graphs on an e-ink display
- Manage timing, Wi-Fi connectivity, and user input (buttons)

##### File Structure
- Top-level files:
- platformio.ini → build and deployment config
- Sample_calls/ → JSON examples for testing
- / directory: headers for each module:
- tr_api.h, weather.h → transport & weather fetch & parse
- graphics.h → drawing routines for e-ink
- helpers.h → utility functions (JSON helpers, debug)
- secrets_example.h → Wi-Fi credentials template
- src/ directory: implementation of each module and main.cpp
- lib/ and test/ directories for external libraries and tests

##### README for Additional Insights
- Defines main modules (tr_api, weather, graphics, helpers)
- Mentions timing/scheduler, resilient Wi-Fi error handling, and task manager
- Specifies features like state switching via buttons and buffer optimizations

##### Main Components
a. Hardware Layer
- Microcontroller (e.g., ESP32/ESP8266)
- E-ink Display (SPI interface)
- Button Inputs
- Wi-Fi Radio
b. Software Modules (on MCU)
- Task Scheduler / Timing Module (NTP sync)
- Wi-Fi & HTTP Client
- Transport API Module
- Weather API Module
- JSON Parser & Data Structures
- Graphics Renderer Module
- Helpers / Utility Module
- State Machine (handles button events and display modes)
c. External Services
- NTP Server (time synchronization)
- Trentino Transport REST API
- Open-Meteo Weather REST API

##### Relationships and Data Flows
- Scheduler triggers periodic tasks:
- NTP sync → sets system clock
- Transport fetch → HTTP GET → JSON → parse → store data
- Weather fetch → HTTP GET → JSON → parse → store data
- State Machine reads button events → selects display mode
- Graphics Renderer pulls parsed data → issues SPI drawing commands to e-ink
- Helpers provide logging/debugging hooks and common utilities
- Wi-Fi module underpins all external HTTP calls; error handler manages retries

##### Architectural Patterns and Design Principles
- Separation of concerns: networking vs. parsing vs. rendering
- Modular design: each API in its own module (tr_api, weather)
- Single-responsibility modules: helpers are generic utilities, graphics is purely rendering
- Task-driven loop or lightweight scheduler for periodic operations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        NTP["NTP Server"]:::external
        TrAPI_EXT["Trentino Transport API"]:::external
        OWM["Open-Meteo Weather API"]:::external
    end

    %% Firmware Software
    subgraph "Firmware Software"
        TS["Task Scheduler / Timing Module"]:::software
        SM["State Machine"]:::software
        WFC["Wi-Fi & HTTP Client"]:::software
        TAPI["Transport API Module"]:::software
        WAPI["Weather API Module"]:::software
        JSONP["JSON Parser & Data Structures"]:::software
        GR["Graphics Renderer Module"]:::software
        HS["Helpers / Utility Module"]:::software
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        MCU["Microcontroller (ESP32/ESP8266)"]:::hardware
        EPD["E-Ink Display (SPI)"]:::hardware
        BTN["Button Inputs"]:::hardware
        WIFI_RAD["Wi-Fi Radio"]:::hardware
    end

    %% Resources
    subgraph "Project Resources"
        PI["PlatformIO Build & Deployment Config"]:::software
        SC["Sample JSON Calls for Testing"]:::software
    end

    %% Connections
    TS -->|NTP sync| NTP
    TS -->|trigger fetch| TAPI
    TS -->|trigger fetch| WAPI
    TAPI -->|HTTP GET| WFC
    WAPI -->|HTTP GET| WFC
    WFC -->|requests| TrAPI_EXT
    WFC -->|requests| OWM
    TrAPI_EXT -->|response JSON| WFC
    OWM -->|response JSON| WFC
    WFC -->|raw JSON| TAPI
    WFC -->|raw JSON| WAPI
    TAPI -->|parsed data| JSONP
    WAPI -->|parsed data| JSONP
    JSONP -->|data structures| GR
    SM -->|select mode| GR
    BTN -->|events| SM
    GR -->|SPI commands| EPD
    WFC -->|radio interface| WIFI_RAD

    %% Modules use Helpers
    TAPI -->|utils| HS
    WAPI -->|utils| HS
    JSONP -->|utils| HS
    GR -->|utils| HS
    TS -->|logging| HS
    SM -->|logging| HS

    %% MCU hosts modules
    MCU --> TS
    MCU --> SM
    MCU --> WFC
    MCU --> TAPI
    MCU --> WAPI
    MCU --> JSONP
    MCU --> GR
    MCU --> HS

    %% Project resources links
    PI
    SC

    %% Click Events
    click TS "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/main.cpp"
    click SM "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/main.cpp"
    click TAPI "https://github.com/ale-giustina/e-ink-buddy/blob/main/include/tr_api.h"
    click TAPI "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/tr_api.cpp"
    click WAPI "https://github.com/ale-giustina/e-ink-buddy/blob/main/include/weather.h"
    click WAPI "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/weather.cpp"
    click WFC "https://github.com/ale-giustina/e-ink-buddy/blob/main/include/tr_api.h"
    click WFC "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/tr_api.cpp"
    click WFC "https://github.com/ale-giustina/e-ink-buddy/blob/main/include/weather.h"
    click WFC "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/weather.cpp"
    click JSONP "https://github.com/ale-giustina/e-ink-buddy/blob/main/include/helpers.h"
    click JSONP "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/helpers.cpp"
    click GR "https://github.com/ale-giustina/e-ink-buddy/blob/main/include/graphics.h"
    click GR "https://github.com/ale-giustina/e-ink-buddy/blob/main/src/graphics.cpp"
    click HS "https://github.com/ale-giustina/e-ink-buddy/blob/main/include/secrets_example.h"
    click PI "https://github.com/ale-giustina/e-ink-buddy/blob/main/platformio.ini"
    click SC "https://github.com/ale-giustina/e-ink-buddy/tree/main/Sample_calls/"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000;
    classDef software fill:#90EE90,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
```
