# lucagoc/pypixelcolor architecture

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

- Interactive diagram: https://gitdiagram.com/lucagoc/pypixelcolor
- Repository: https://github.com/lucagoc/pypixelcolor

## Overview

pypixelcolor is a Python library and CLI for controlling iPixel LED matrices over Bluetooth LE. The main workflow discovers or selects a device, opens a session, builds a command-specific payload or send plan, and transmits it with acknowledgement handling. The graph also preserves documented image, text, display-setting, clock, and automation capabilities, plus the WebSocket interface. Several command and transport details are represented by their source directories because their implementations were not excerpted; edges are limited to relationships shown in excerpts, the source index, or README.

Main entry points: [`src/pypixelcolor/lib/transport/send_plan.py`](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/transport/send_plan.py) (Send plan), [`src/pypixelcolor/lib/device_session.py`](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/device_session.py) (Device session), [`src/pypixelcolor/commands/__init__.py`](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/__init__.py) (Command registry), [`src/pypixelcolor/cli.py`](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_library["Python client<br/>[client.py]"]
  node_websocket["WebSocket server<br/>[websocket.py]"]
end

subgraph group_connection["Device connection"]
  node_scanner["BLE scanner<br/>[scanner.py]"]
  node_session["Device session<br/>[device_session.py]"]
  node_deviceinfo["Device info<br/>[device_info.py]"]
end

subgraph group_commands["Display commands"]
  node_registry["Command registry<br/>[__init__.py]"]
  node_settings["Settings and controls"]
  node_schedule["Schedule and timer<br/>[set_schedule.py]"]
  node_image["Image and GIF<br/>[send_image.py]"]
end

subgraph group_transport["BLE transport"]
  node_plan["Send plan<br/>[send_plan.py]"]
  node_acks["ACK manager<br/>[ack_manager.py]"]
  node_result["Command result<br/>[command_result.py]"]
end

subgraph group_text["Text rendering"]
  node_text["Text command<br/>[__init__.py]"]
  node_textmodels["Text models<br/>[models.py]"]
  node_textencoding["Text encoding<br/>[encoding.py]"]
  node_textimage["Text image processing"]
  node_emoji["Emoji assets<br/>[emoji_manager.py]"]
end

node_user(("User or script"))
node_device(("iPixel matrix"))

node_user -->|"runs commands"| node_cli
node_user -->|"scripts device"| node_library
node_cli -->|"scans devices"| node_scanner
node_cli -->|"opens session"| node_session
node_cli -->|"dispatches commands"| node_registry
node_library -->|"uses session"| node_session
node_library -->|"discovers devices"| node_scanner
node_websocket -->|"uses session"| node_session
node_websocket -->|"dispatches commands"| node_registry
node_scanner -->|"discovers"| node_device
node_session -->|"fetches info"| node_deviceinfo
node_session -->|"executes plan"| node_plan
node_session -->|"registers notifications"| node_acks
node_session -->|"connects BLE"| node_device
node_registry -->|"routes controls"| node_settings
node_registry -->|"routes schedule"| node_schedule
node_registry -->|"routes images"| node_image
node_registry -->|"routes text"| node_text
node_settings -->|"builds plans"| node_plan
node_schedule -->|"builds plan"| node_plan
node_image -->|"builds plan"| node_plan
node_text -->|"builds plan"| node_plan
node_text -->|"uses models"| node_textmodels
node_text -->|"encodes text"| node_textencoding
node_textencoding -->|"renders glyphs"| node_textimage
node_textimage -->|"loads emoji"| node_emoji
node_plan -->|"waits for ACK"| node_acks
node_plan -->|"writes BLE data"| node_device
node_plan -->|"returns result"| node_result

click node_cli "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/cli.py"
click node_library "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/client.py"
click node_websocket "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/websocket.py"
click node_scanner "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/scanner.py"
click node_session "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/device_session.py"
click node_deviceinfo "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/device_info.py"
click node_registry "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/__init__.py"
click node_settings "https://github.com/lucagoc/pypixelcolor/tree/main/src/pypixelcolor/commands"
click node_schedule "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/set_schedule.py"
click node_image "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_image.py"
click node_text "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/__init__.py"
click node_textmodels "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/models.py"
click node_textencoding "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/encoding.py"
click node_textimage "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/image_processing.py"
click node_emoji "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/emoji_manager.py"
click node_plan "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/transport/send_plan.py"
click node_acks "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/transport/ack_manager.py"
click node_result "https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/command_result.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_cli,node_library,node_websocket,node_user toneBlue
class node_scanner,node_session,node_deviceinfo toneAmber
class node_registry,node_settings,node_schedule,node_image toneMint
class node_plan,node_acks,node_result toneRose
class node_text,node_textmodels,node_textencoding,node_textimage,node_emoji,node_device toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/cli.py): `src/pypixelcolor/cli.py`
- [Python client](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/client.py): `src/pypixelcolor/client.py`
- [WebSocket server](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/websocket.py): `src/pypixelcolor/websocket.py`

### Device connection

- [BLE scanner](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/scanner.py): `src/pypixelcolor/scanner.py`
- [Device session](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/device_session.py): `src/pypixelcolor/lib/device_session.py`
- [Device info](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/device_info.py): `src/pypixelcolor/lib/device_info.py`

### Display commands

- [Command registry](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/__init__.py): `src/pypixelcolor/commands/__init__.py`
- [Settings and controls](https://github.com/lucagoc/pypixelcolor/tree/main/src/pypixelcolor/commands): `src/pypixelcolor/commands`
- [Schedule and timer](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/set_schedule.py): `src/pypixelcolor/commands/set_schedule.py`
- [Image and GIF](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_image.py): `src/pypixelcolor/commands/send_image.py`

### BLE transport

- [Send plan](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/transport/send_plan.py): `src/pypixelcolor/lib/transport/send_plan.py`
- [ACK manager](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/transport/ack_manager.py): `src/pypixelcolor/lib/transport/ack_manager.py`
- [Command result](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/command_result.py): `src/pypixelcolor/lib/command_result.py`

### Text rendering

- [Text command](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/__init__.py): `src/pypixelcolor/commands/send_text/__init__.py`
- [Text models](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/models.py): `src/pypixelcolor/commands/send_text/models.py`
- [Text encoding](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/encoding.py): `src/pypixelcolor/commands/send_text/encoding.py`
- [Text image processing](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/commands/send_text/image_processing.py): `src/pypixelcolor/commands/send_text/image_processing.py`
- [Emoji assets](https://github.com/lucagoc/pypixelcolor/blob/main/src/pypixelcolor/lib/emoji_manager.py): `src/pypixelcolor/lib/emoji_manager.py`

### Other components

- **User or script**
- **iPixel matrix**

## Connections

- User or script → CLI: runs commands
- User or script → Python client: scripts device
- CLI → BLE scanner: scans devices (evidence: `src/pypixelcolor/cli.py`)
- CLI → Device session: opens session (evidence: `src/pypixelcolor/cli.py`)
- CLI → Command registry: dispatches commands (evidence: `src/pypixelcolor/commands/__init__.py`)
- Python client → Device session: uses session (evidence: `src/pypixelcolor/client.py`)
- Python client → BLE scanner: discovers devices (evidence: `src/pypixelcolor/client.py`)
- WebSocket server → Device session: uses session (evidence: `src/pypixelcolor/websocket.py`)
- WebSocket server → Command registry: dispatches commands (evidence: `src/pypixelcolor/websocket.py`)
- BLE scanner → iPixel matrix: discovers
- Device session → Device info: fetches info (evidence: `src/pypixelcolor/lib/device_session.py`)
- Device session → Send plan: executes plan (evidence: `src/pypixelcolor/lib/device_session.py`)
- Device session → ACK manager: registers notifications (evidence: `src/pypixelcolor/lib/device_session.py`)
- Device session → iPixel matrix: connects BLE (evidence: `src/pypixelcolor/lib/device_session.py`)
- Command registry → Settings and controls: routes controls (evidence: `src/pypixelcolor/commands/__init__.py`)
- Command registry → Schedule and timer: routes schedule (evidence: `src/pypixelcolor/commands/__init__.py`)
- Command registry → Image and GIF: routes images (evidence: `src/pypixelcolor/commands/__init__.py`)
- Command registry → Text command: routes text (evidence: `src/pypixelcolor/commands/__init__.py`)
- Settings and controls → Send plan: builds plans (evidence: `src/pypixelcolor/commands/set_schedule.py`)
- Schedule and timer → Send plan: builds plan (evidence: `src/pypixelcolor/commands/set_schedule.py`)
- Image and GIF → Send plan: builds plan (evidence: `src/pypixelcolor/commands/send_image.py`)
- Text command → Send plan: builds plan (evidence: `src/pypixelcolor/commands/send_text/__init__.py`)
- Text command → Text models: uses models (evidence: `src/pypixelcolor/commands/send_text/__init__.py`)
- Text command → Text encoding: encodes text (evidence: `src/pypixelcolor/commands/send_text/__init__.py`)
- Text encoding → Text image processing: renders glyphs (evidence: `src/pypixelcolor/commands/send_text/encoding.py`)
- Text image processing → Emoji assets: loads emoji (evidence: `src/pypixelcolor/commands/send_text/image_processing.py`)
- Send plan → ACK manager: waits for ACK (evidence: `src/pypixelcolor/lib/transport/send_plan.py`)
- Send plan → iPixel matrix: writes BLE data (evidence: `src/pypixelcolor/lib/transport/send_plan.py`)
- Send plan → Command result: returns result (evidence: `src/pypixelcolor/lib/transport/send_plan.py`)