# jona-walpert/piclock architecture

> Architecture diagram of the GitHub repository jona-walpert/piclock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jona-walpert/piclock
- Repository: https://github.com/jona-walpert/piclock

## Overview

PiClock is a Raspberry Pi e-paper clock. Its main workflow schedules minute and midnight updates, renders clock or day-banner images, and refreshes the selected display; periodic time synchronization and power optimization support that loop. The README also documents Waveshare V2/V3/V4 panels, a mock driver, anti-ghosting cleans, and systemd autostart. Source excerpts show the main orchestration and driver stack; power-management internals and some display behavior were not sampled, so their detailed connections are omitted.

Main entry points: [`main.py`](https://github.com/jona-walpert/piclock/blob/main/main.py) (Clock loop), [`display.py`](https://github.com/jona-walpert/piclock/blob/main/display.py) (Display manager), [`drivers/driver_waveshare.py`](https://github.com/jona-walpert/piclock/blob/main/drivers/driver_waveshare.py) (Waveshare adapter), [`time_sync.py`](https://github.com/jona-walpert/piclock/blob/main/time_sync.py) (Time synchronizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Clock runtime"]
  node_systemd["systemd service<br/>[piclock.service]"]
  node_main["Clock loop<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_display["Display rendering"]
  node_display_manager["Display manager<br/>[display.py]"]
  node_clock_render["Clock and banner<br/>[display.py]"]
  node_refresh["Refresh and cleaning<br/>[display.py]"]
end

subgraph group_drivers["Display drivers"]
  node_driver_factory["Driver factory<br/>[__init__.py]"]
  node_driver_interface["Driver interface<br/>[base.py]"]
  node_waveshare_adapter["Waveshare adapter"]
  node_mock_driver["Mock display<br/>[mock.py]"]
  node_panel_v2["Waveshare V2<br/>[epd2in13_V2.py]"]
  node_panel_v3["Waveshare V3<br/>[epd2in13_V3.py]"]
  node_panel_v4["Waveshare V4<br/>[epd2in13_V4.py]"]
  node_hardware_io["GPIO and SPI<br/>[epdconfig.py]"]
end

subgraph group_support["Time and power"]
  node_time_sync["Time synchronizer<br/>[time_sync.py]"]
  node_power_manager["Power manager<br/>[power.py]"]
end

node_ntp(("NTP servers"))
node_timesyncd["systemd-timesyncd"]
node_hardware["E-paper panel"]

node_systemd -->|"starts"| node_main
node_main -->|"initializes and updates"| node_display_manager
node_main -->|"starts and checks"| node_time_sync
node_main -->|"invokes"| node_power_manager
node_main -->|"reads settings"| node_config
node_display_manager -->|"reads settings"| node_config
node_display_manager -->|"selects driver"| node_driver_factory
node_display_manager -->|"renders images"| node_clock_render
node_display_manager -->|"performs refreshes"| node_refresh
node_refresh -.->|"uses driver"| node_driver_interface
node_driver_factory -->|"selects mock"| node_mock_driver
node_driver_factory -->|"selects Waveshare"| node_waveshare_adapter
node_waveshare_adapter -->|"implements"| node_driver_interface
node_mock_driver -->|"implements"| node_driver_interface
node_waveshare_adapter -->|"loads revision"| node_panel_v2
node_waveshare_adapter -->|"loads revision"| node_panel_v3
node_waveshare_adapter -->|"loads revision"| node_panel_v4
node_panel_v2 -->|"uses GPIO/SPI"| node_hardware_io
node_panel_v3 -->|"uses GPIO/SPI"| node_hardware_io
node_panel_v4 -->|"uses GPIO/SPI"| node_hardware_io
node_hardware_io -.->|"controls"| node_hardware
node_time_sync -->|"reads settings"| node_config
node_time_sync -->|"queries"| node_ntp
node_time_sync -->|"requests resync"| node_timesyncd
node_power_manager -->|"reads settings"| node_config

click node_systemd "https://github.com/jona-walpert/piclock/blob/main/piclock.service"
click node_main "https://github.com/jona-walpert/piclock/blob/main/main.py"
click node_config "https://github.com/jona-walpert/piclock/blob/main/config.py"
click node_display_manager "https://github.com/jona-walpert/piclock/blob/main/display.py"
click node_clock_render "https://github.com/jona-walpert/piclock/blob/main/display.py"
click node_refresh "https://github.com/jona-walpert/piclock/blob/main/display.py"
click node_driver_factory "https://github.com/jona-walpert/piclock/blob/main/drivers/__init__.py"
click node_driver_interface "https://github.com/jona-walpert/piclock/blob/main/drivers/base.py"
click node_waveshare_adapter "https://github.com/jona-walpert/piclock/blob/main/drivers/driver_waveshare.py"
click node_mock_driver "https://github.com/jona-walpert/piclock/blob/main/drivers/mock.py"
click node_panel_v2 "https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epd2in13_V2.py"
click node_panel_v3 "https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epd2in13_V3.py"
click node_panel_v4 "https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epd2in13_V4.py"
click node_hardware_io "https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epdconfig.py"
click node_time_sync "https://github.com/jona-walpert/piclock/blob/main/time_sync.py"
click node_power_manager "https://github.com/jona-walpert/piclock/blob/main/power.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_systemd,node_main,node_config toneBlue
class node_display_manager,node_clock_render,node_refresh toneAmber
class node_driver_factory,node_driver_interface,node_waveshare_adapter,node_mock_driver,node_panel_v2,node_panel_v3,node_panel_v4,node_hardware_io,node_ntp toneMint
class node_time_sync,node_power_manager toneRose
class node_timesyncd,node_hardware toneIndigo
```

## Components

### Clock runtime

- [systemd service](https://github.com/jona-walpert/piclock/blob/main/piclock.service): `piclock.service`
- [Clock loop](https://github.com/jona-walpert/piclock/blob/main/main.py): `main.py`
- [Configuration](https://github.com/jona-walpert/piclock/blob/main/config.py): `config.py`

### Display rendering

- [Display manager](https://github.com/jona-walpert/piclock/blob/main/display.py): `display.py`
- [Clock and banner](https://github.com/jona-walpert/piclock/blob/main/display.py): `display.py`
- [Refresh and cleaning](https://github.com/jona-walpert/piclock/blob/main/display.py): `display.py`

### Display drivers

- [Driver factory](https://github.com/jona-walpert/piclock/blob/main/drivers/__init__.py): `drivers/__init__.py`
- [Driver interface](https://github.com/jona-walpert/piclock/blob/main/drivers/base.py): `drivers/base.py`
- [Waveshare adapter](https://github.com/jona-walpert/piclock/blob/main/drivers/driver_waveshare.py): `drivers/driver_waveshare.py`
- [Mock display](https://github.com/jona-walpert/piclock/blob/main/drivers/mock.py): `drivers/mock.py`
- [Waveshare V2](https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epd2in13_V2.py): `drivers/waveshare/epd2in13_V2.py`
- [Waveshare V3](https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epd2in13_V3.py): `drivers/waveshare/epd2in13_V3.py`
- [Waveshare V4](https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epd2in13_V4.py): `drivers/waveshare/epd2in13_V4.py`
- [GPIO and SPI](https://github.com/jona-walpert/piclock/blob/main/drivers/waveshare/epdconfig.py): `drivers/waveshare/epdconfig.py`

### Time and power

- [Time synchronizer](https://github.com/jona-walpert/piclock/blob/main/time_sync.py): `time_sync.py`
- [Power manager](https://github.com/jona-walpert/piclock/blob/main/power.py): `power.py`

### Other components

- **NTP servers**
- **systemd-timesyncd**
- **E-paper panel**

## Connections

- systemd service → Clock loop: starts (evidence: `README.md`)
- Clock loop → Display manager: initializes and updates (evidence: `main.py`)
- Clock loop → Time synchronizer: starts and checks (evidence: `main.py`)
- Clock loop → Power manager: invokes (evidence: `main.py`)
- Clock loop → Configuration: reads settings (evidence: `main.py`)
- Display manager → Configuration: reads settings (evidence: `display.py`)
- Display manager → Driver factory: selects driver (evidence: `display.py`)
- Display manager → Clock and banner: renders images (evidence: `display.py`)
- Display manager → Refresh and cleaning: performs refreshes (evidence: `display.py`)
- Refresh and cleaning → Driver interface: uses driver
- Driver factory → Mock display: selects mock (evidence: `drivers/__init__.py`)
- Driver factory → Waveshare adapter: selects Waveshare (evidence: `drivers/__init__.py`)
- Waveshare adapter → Driver interface: implements (evidence: `drivers/driver_waveshare.py`)
- Mock display → Driver interface: implements (evidence: `drivers/mock.py`)
- Waveshare adapter → Waveshare V2: loads revision (evidence: `drivers/driver_waveshare.py`)
- Waveshare adapter → Waveshare V3: loads revision (evidence: `drivers/driver_waveshare.py`)
- Waveshare adapter → Waveshare V4: loads revision (evidence: `drivers/driver_waveshare.py`)
- Waveshare V2 → GPIO and SPI: uses GPIO/SPI (evidence: `drivers/waveshare/epd2in13_V2.py`)
- Waveshare V3 → GPIO and SPI: uses GPIO/SPI (evidence: `drivers/waveshare/epd2in13_V3.py`)
- Waveshare V4 → GPIO and SPI: uses GPIO/SPI (evidence: `drivers/waveshare/epd2in13_V4.py`)
- GPIO and SPI → E-paper panel: controls
- Time synchronizer → Configuration: reads settings (evidence: `time_sync.py`)
- Time synchronizer → NTP servers: queries (evidence: `time_sync.py`)
- Time synchronizer → systemd-timesyncd: requests resync (evidence: `time_sync.py`)
- Power manager → Configuration: reads settings (evidence: `power.py`)
