# rei-vilo/pdls_basic architecture

> Architecture diagram of the GitHub repository rei-vilo/pdls_basic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rei-vilo/pdls_basic
- Repository: https://github.com/rei-vilo/pdls_basic

## Overview

This repository is an Arduino C++ library suite for driving Pervasive Displays e-paper hardware. The architecture is centered on a small public API that sketches call, with the actual work split across graphics/text helpers, display-model tables, and hardware-specific screen control code.

#### Top-level architecture

The repo has three major parts:

1. **`src/` library code**
   - The reusable runtime used by Arduino sketches.
   - This is the core architecture.

2. **`examples/`**
   - A large set of board- and feature-specific Arduino sketches.
   - These are not just demos; they also show the intended integration patterns for different hardware families.

3. **Repository automation and docs**
   - GitHub Actions workflows for CI/linting and stale issue handling.
   - README, coverage notes, and license files.
   - These support the library but do not affect runtime behavior.

#### Core runtime subsystems

##### 1) Public façade: `PDLS_Basic.h`
This is the main entry point for users of the library. It provides the API surface that sketches include, hiding the internal split between buffer management, drawing primitives, font handling, and screen control.

Architecturally, this header acts as the boundary between user sketches and the rest of the library.

##### 2) Display hardware abstraction: `Screen_EPD.*` and `Screen_EPD_Table.h`
This is the hardware-facing subsystem.

- `Screen_EPD.h/.cpp` appears to encapsulate the actual e-paper display session lifecycle and low-level display operations.
- `Screen_EPD_Table.h` likely contains the device/model lookup tables that map screen identifiers to geometry, capabilities, timings, and update behavior.

This layer is where the library differentiates between:
- iTC monochrome screens,
- iTC touch-capable screens,
- black-white-red-yellow color screens,
- different extension boards and kit generations.

The abstraction boundary here is important: the rest of the library works in terms of screen capabilities, while this layer knows about the specific panel/board combinations.

##### 3) Graphics and screen buffer: `hV_Screen_Buffer.*`
This subsystem is responsible for keeping a drawable representation of the screen content before it is pushed to the physical panel.

Typical responsibilities in this layer:
- pixel-level or region-level drawing,
- buffering for efficient refresh,
- managing the data that will eventually be sent to the display controller.

This buffer layer is what makes higher-level primitives possible without every feature drawing directly to hardware.

##### 4) GUI and drawing primitives: `hV_GUI.*`
This subsystem provides higher-level widget-like drawing features on top of the buffer and screen abstractions.

From the README, the suite includes “Graphics routines” and “GUI,” so this layer likely covers:
- shapes,
- lines,
- forms,
- grid/layout helpers,
- UI composition.

The `examples/Common/Common_Forms`, `Common_Grid`, and `Touch_GUI` sketches show that the library is intended to support both general drawing and simple interactive screen layouts.

##### 5) Text and font system: `hV_Font.*`, `hV_Font_Terminal.*`, `Terminal*.h`
This subsystem handles text rendering.

Files in this area indicate:
- a generic font interface,
- terminal-style bitmap fonts,
- several font sizes:
  - `Terminal6x8e.h`
  - `Terminal8x12e.h`
  - `Terminal12x16e.h`
  - `Terminal16x24e.h`

The README also says the suite provides:
- “Four extended fonts with double-sized variants”
- direct UTF-8 text support in release 10, removing the need for `utf2iso()`

So text rendering is a significant subsystem, not just a convenience utility. It sits between the high-level GUI/text API and the underlying screen buffer.

##### 6) Color utilities: `hV_Colours565.*`
This subsystem provides color encoding helpers for the supported display color modes.

Given the file naming, it likely works with 16-bit 5-6-5 RGB color values and maps them into the panel’s supported palette/film-specific rendering constraints.

This is especially relevant for the black-white-red-yellow displays, where logical color support is constrained by the physical screen capabilities.

##### 7) Documentation helpers: `hV_Documentation.h`
This looks like a support header for documentation comments or compile-time documentation hooks. It is not a runtime subsystem, but it helps keep the library API documented in a consistent way.

#### Hardware and data flow

The central data flow is:

1. **Arduino sketch / example**
   - Calls the public API from `PDLS_Basic.h`.

2. **Rendering and composition layers**
   - Text, graphics, and GUI functions build content into the screen buffer.
   - Font and color helpers convert user-level content into display-ready representation.

3. **Screen model selection**
   - `Screen_EPD_Table.h` and `Screen_EPD.*` determine the correct behavior for the connected screen and extension board.

4. **Hardware I/O**
   - The library uses Arduino core services, specifically `SPI` and `Wire`, to communicate with the hardware.
   - The physical e-paper controller and optional touch hardware sit beyond this boundary.

5. **Physical output**
   - The e-paper panel updates according to the selected mode:
     - normal update,
     - fast update,
     - touch-enabled workflows where applicable.

In other words, the architecture is layered: sketches do not talk directly to SPI registers or panel timing logic; they go through the library’s drawing and screen abstractions.

#### Important architectural boundaries

##### User code vs. library core
All sketches in `examples/` are consumers of the library. They demonstrate usage but are separate from the reusable runtime.

##### Graphics/text vs. hardware control
A key boundary exists between:
- content generation and layout, and
- screen-specific update mechanics.

That separation is what makes the same API usable across EXT3, EXT4, monochrome, color, and touch variants.

##### Board-specific features vs. common features
The example tree reflects this split:
- `examples/Common` covers general features like colours, fonts, forms, grids, text, orientation, persistent storage, and “WhoAmI”.
- `examples/BWRY` covers black-white-red-yellow color panels.
- `examples/EXT4` covers the newer extension kit and its special capabilities such as accelerometer, screen sizes, weather, and WS2813C LED integration.
- `examples/EXT4_Matter` covers Matter-enabled hardware integration.
- `examples/Touch` covers touch input and interactive UI.
- `examples/Wide` covers wide-temperature/fast-update display behavior.

This organization suggests the library is designed as one common core with feature adaptation by hardware family.

#### Subsystem mapping from examples

The examples reveal which features are first-class concerns in the library:

- **Common**
  - shared graphics/text/orientation/persistence features
  - generic “WhoAmI” identification and capability queries

- **BWRY**
  - black-white-red-yellow panel handling
  - palette and contrast behavior
  - hardware identification

- **EXT4**
  - next-generation extension board support
  - larger font usage, screen size handling, sensors, weather, LED control

- **EXT4_Matter**
  - integration with Arduino Nano Matter / Matter platform
  - RGB and weather examples
  - board-specific raw LED driver helpers (`rawWS2813C.cpp/h`) suggesting direct peripheral control not handled by the generic API

- **Touch**
  - touch-driven drawing and GUI interaction
  - game/UI examples such as TicTacToe

- **Wide**
  - fast-speed and wide-temperature screen operation
  - performance-oriented examples showing partial/full refresh behavior and orientation changes

#### External dependencies and runtime environment

These matter because they define the execution boundary:

- **Arduino ecosystem**
  - The library is meant for Arduino IDE / Arduino CLI.
  - It depends on the Arduino SDK and idioms.

- **Hardware interfaces**
  - `SPI` for display communication.
  - `Wire` for I2C-related peripherals such as touch or sensors.

- **Physical devices**
  - Pervasive Displays EPD panels
  - EXT3 / EXT3.1 / EXT4 extension boards
  - EXT3-Touch board
  - EXT4-to-Nano adapter boards
  - Matter-capable Nano Matter hardware in the EXT4_Matter examples

#### What the architecture is optimized for

This library is not a general-purpose graphics engine. It is optimized for:
- e-paper constraints,
- board/panel model variation,
- low-refresh, partial-refresh, and fast-update use cases,
- compact Arduino deployment,
- reusable drawing and text primitives across multiple Pervasive Displays products.

The presence of tables, buffer management, and specialized examples strongly suggests the core design principle is:  
**“one high-level API, many display and board variants behind it.”**

#### Practical diagram guidance

If you are drawing an architecture diagram for this repo, the most accurate shape is:

- **At the top:** Arduino application sketches and examples.
- **In the middle:** the PDLS_Basic public API, split into:
  - graphics/GUI,
  - text/fonts,
  - colour utilities,
  - buffer management.
- **Below that:** hardware abstraction and screen tables.
- **At the bottom:** Arduino SPI/Wire and the actual Pervasive Displays panels/boards/touch peripherals.
- **Off to the side:** examples grouped by hardware family and feature area, plus CI/documentation automation.

That structure reflects the repo’s real purpose: a hardware-oriented rendering library with a clean public façade and many board-specific execution paths behind it.

Main entry points: [`src/PDLS_Basic.h`](https://github.com/rei-vilo/pdls_basic/blob/main/src/PDLS_Basic.h) (PDLS Basic), [`src/hV_Screen_Buffer.h`](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Screen_Buffer.h) (Screen buffer), [`src/Screen_EPD.h`](https://github.com/rei-vilo/pdls_basic/blob/main/src/Screen_EPD.h) (Screen EPD), [`src/hV_GUI.h`](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_GUI.h) (GUI drawing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_src["Library core"]
  node_pdls_basic["PDLS Basic<br/>public API<br/>[PDLS_Basic.h]"]
  node_screen_epd["Screen EPD<br/>display control<br/>[Screen_EPD.h]"]
  node_screen_table["Model table<br/>device mapping<br/>[Screen_EPD_Table.h]"]
  node_screen_buffer[("Screen buffer<br/>frame buffer<br/>[hV_Screen_Buffer.h]")]
  node_gui["GUI drawing<br/>graphics UI<br/>[hV_GUI.h]"]
  node_font["Font core<br/>text rendering<br/>[hV_Font.h]"]
  node_font_terminal["Terminal fonts<br/>bitmap fonts<br/>[hV_Font_Terminal.h]"]
  node_terminal_fonts["Terminal sets<br/>font assets<br/>[Terminal6x8e.h]"]
  node_colours["Colours 565<br/>color utils<br/>[hV_Colours565.h]"]
  node_doc_helper["Docs helper<br/>documentation<br/>[hV_Documentation.h]"]
end

subgraph group_examples["Examples"]
  node_sketches["Arduino sketches<br/>consumer"]
  node_common_examples["Common demos<br/>example family"]
  node_bwr_examples["BWRY demos<br/>example family"]
  node_ext4_examples["EXT4 demos<br/>example family"]
  node_matter_examples["Matter demos<br/>example family"]
  node_touch_examples["Touch demos<br/>example family"]
  node_wide_examples["Wide demos<br/>example family"]
end

subgraph group_automation["Repo support"]
  node_ci_docs["CI & docs<br/>repo support"]
end

node_sketches -->|"uses"| node_pdls_basic
node_pdls_basic -->|"renders via"| node_screen_buffer
node_pdls_basic -->|"exposes"| node_gui
node_pdls_basic -->|"exposes"| node_font
node_pdls_basic -->|"exposes"| node_colours
node_screen_buffer -->|"supports"| node_gui
node_screen_buffer -->|"feeds"| node_font
node_font -->|"implements"| node_font_terminal
node_font_terminal -->|"uses assets"| node_terminal_fonts
node_gui -->|"draws to"| node_screen_buffer
node_screen_epd -->|"consults"| node_screen_table
node_screen_epd -->|"pushes"| node_screen_buffer
node_pdls_basic -->|"delegates to"| node_screen_epd
node_common_examples -->|"demonstrates"| node_pdls_basic
node_bwr_examples -->|"demonstrates"| node_pdls_basic
node_ext4_examples -->|"demonstrates"| node_pdls_basic
node_matter_examples -->|"demonstrates"| node_pdls_basic
node_touch_examples -->|"demonstrates"| node_pdls_basic
node_wide_examples -->|"demonstrates"| node_pdls_basic
node_ci_docs -.->|"supports"| node_pdls_basic

click node_pdls_basic "https://github.com/rei-vilo/pdls_basic/blob/main/src/PDLS_Basic.h"
click node_screen_epd "https://github.com/rei-vilo/pdls_basic/blob/main/src/Screen_EPD.h"
click node_screen_table "https://github.com/rei-vilo/pdls_basic/blob/main/src/Screen_EPD_Table.h"
click node_screen_buffer "https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Screen_Buffer.h"
click node_gui "https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_GUI.h"
click node_font "https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Font.h"
click node_font_terminal "https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Font_Terminal.h"
click node_terminal_fonts "https://github.com/rei-vilo/pdls_basic/blob/main/src/Terminal6x8e.h"
click node_colours "https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Colours565.h"
click node_doc_helper "https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Documentation.h"
click node_common_examples "https://github.com/rei-vilo/pdls_basic/tree/main/examples/Common"
click node_bwr_examples "https://github.com/rei-vilo/pdls_basic/tree/main/examples/BWRY"
click node_ext4_examples "https://github.com/rei-vilo/pdls_basic/tree/main/examples/EXT4"
click node_matter_examples "https://github.com/rei-vilo/pdls_basic/tree/main/examples/EXT4_Matter"
click node_touch_examples "https://github.com/rei-vilo/pdls_basic/tree/main/examples/Touch"
click node_wide_examples "https://github.com/rei-vilo/pdls_basic/tree/main/examples/Wide"

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_pdls_basic,node_screen_epd,node_screen_table,node_screen_buffer,node_gui,node_font,node_font_terminal,node_terminal_fonts,node_colours,node_doc_helper toneBlue
class node_sketches,node_common_examples,node_bwr_examples,node_ext4_examples,node_matter_examples,node_touch_examples,node_wide_examples toneAmber
class node_ci_docs toneMint
```

## Components

### Library core

Reusable Arduino runtime used by sketches.

- [PDLS Basic](https://github.com/rei-vilo/pdls_basic/blob/main/src/PDLS_Basic.h): public API · Main façade included by sketches; exposes the library surface. · `src/PDLS_Basic.h`
- [Screen EPD](https://github.com/rei-vilo/pdls_basic/blob/main/src/Screen_EPD.h): display control · Display session lifecycle and low-level e-paper operations. · `src/Screen_EPD.h`
- [Model table](https://github.com/rei-vilo/pdls_basic/blob/main/src/Screen_EPD_Table.h): device mapping · Screen and board lookup tables for geometry, capabilities, and update behavior. · `src/Screen_EPD_Table.h`
- [Screen buffer](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Screen_Buffer.h): frame buffer · Drawable screen representation and buffered refresh data. · `src/hV_Screen_Buffer.h`
- [GUI drawing](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_GUI.h): graphics UI · Higher-level drawing primitives and layout helpers built on the buffer. · `src/hV_GUI.h`
- [Font core](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Font.h): text rendering · Generic font interface and text rendering support. · `src/hV_Font.h`
- [Terminal fonts](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Font_Terminal.h): bitmap fonts · Terminal-style font implementation used by the library. · `src/hV_Font_Terminal.h`
- [Terminal sets](https://github.com/rei-vilo/pdls_basic/blob/main/src/Terminal6x8e.h): font assets · Extended terminal font variants shipped with the library. · `src/Terminal6x8e.h`
- [Colours 565](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Colours565.h): color utils · RGB 5-6-5 color helpers and palette conversion utilities. · `src/hV_Colours565.h`
- [Docs helper](https://github.com/rei-vilo/pdls_basic/blob/main/src/hV_Documentation.h): documentation · Compile-time documentation support header. · `src/hV_Documentation.h`

### Examples

Board- and feature-specific sketches showing integration patterns.

- **Arduino sketches**: consumer · User applications and example sketches that call into the library.
- [Common demos](https://github.com/rei-vilo/pdls_basic/tree/main/examples/Common): example family · Shared feature examples for colours, fonts, text, forms, grid, orientation, persistence, and identification. · `examples/Common`
- [BWRY demos](https://github.com/rei-vilo/pdls_basic/tree/main/examples/BWRY): example family · Black-white-red-yellow panel examples for palettes, contrast, colours, and device ID. · `examples/BWRY`
- [EXT4 demos](https://github.com/rei-vilo/pdls_basic/tree/main/examples/EXT4): example family · Next-generation extension board examples including sensors, weather, screen sizes, and LEDs. · `examples/EXT4`
- [Matter demos](https://github.com/rei-vilo/pdls_basic/tree/main/examples/EXT4_Matter): example family · EXT4 examples adapted for Matter-capable hardware and RGB/weather workflows. · `examples/EXT4_Matter`
- [Touch demos](https://github.com/rei-vilo/pdls_basic/tree/main/examples/Touch): example family · Touch-driven drawing, GUI, and interactive game examples. · `examples/Touch`
- [Wide demos](https://github.com/rei-vilo/pdls_basic/tree/main/examples/Wide): example family · Fast-update and wide-temperature display behavior examples. · `examples/Wide`

### Repo support

Documentation and GitHub automation.

- **CI & docs**: repo support · README, coverage notes, license, and GitHub workflow automation.

## Connections

- Arduino sketches → PDLS Basic: uses · Sketches include the public library façade.
- PDLS Basic → Screen buffer: renders via · Public API delegates drawing into the screen buffer.
- PDLS Basic → GUI drawing: exposes · Higher-level drawing and UI primitives are surfaced through the main API.
- PDLS Basic → Font core: exposes · Text rendering functions are part of the public interface.
- PDLS Basic → Colours 565: exposes · Color helpers are available to sketches.
- Screen buffer → GUI drawing: supports · GUI primitives build on buffered drawing.
- Screen buffer → Font core: feeds · Text rendering is composed into buffered output.
- Font core → Terminal fonts: implements · Terminal font subsystem provides the concrete font implementation.
- Terminal fonts → Terminal sets: uses assets · Terminal font headers provide the shipped font sets.
- GUI drawing → Screen buffer: draws to · GUI primitives write into the drawable buffer.
- Screen EPD → Model table: consults · Hardware control uses model tables to select display behavior.
- Screen EPD → Screen buffer: pushes · Buffered content is sent to the physical panel through screen control.
- PDLS Basic → Screen EPD: delegates to · Library calls eventually reach the display control layer.
- Common demos → PDLS Basic: demonstrates · Common sketches exercise the shared API surface.
- BWRY demos → PDLS Basic: demonstrates · BWRY sketches show panel-specific behavior through the same API.
- EXT4 demos → PDLS Basic: demonstrates · EXT4 sketches cover newer board and sensor integrations.
- Matter demos → PDLS Basic: demonstrates · Matter sketches exercise platform-specific integration paths.
- Touch demos → PDLS Basic: demonstrates · Touch sketches show interactive UI usage.
- Wide demos → PDLS Basic: demonstrates · Wide sketches focus on fast update and temperature behavior.
- CI & docs → PDLS Basic: supports · Repository automation and docs support the library, not runtime behavior.
