# pi-top/pi-toppulse architecture

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

- Interactive diagram: https://gitdiagram.com/pi-top/pi-toppulse
- Repository: https://github.com/pi-top/pi-toppulse

## Overview

pi-topPULSE is a Python library and hardware interface for a Raspberry Pi add-on combining a 7×7 LED matrix, microphone, and speaker. A user script uses the library to configure the device, display LED output, or capture audio into a WAV file; the operating system handles speaker playback. The graph also includes documented automatic device initialization and Alexa integration. Source excerpts show configuration, LED, and microphone behavior; initialization-manager and playback details are included only as README-documented capabilities.

Main entry points: [`library/ptpulse/configuration.py`](https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/configuration.py) (Device configuration), [`library/ptpulse/ledmatrix.py`](https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/ledmatrix.py) (LED matrix), [`library/ptpulse/microphone.py`](https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/microphone.py) (Microphone capture), [`examples`](https://github.com/pi-top/pi-toppulse/tree/master/examples) (Usage examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Device setup"]
  node_config["Device configuration<br/>[configuration.py]"]
  node_i2c[("I²C controller")]
  node_hostconfig["Host interface setup"]
end

subgraph group_io["Hardware I/O"]
  node_led["LED matrix<br/>[ledmatrix.py]"]
  node_ledstate["Pixel state and correction<br/>[ledmatrix.py]"]
  node_serial["UART device"]
  node_mic["Microphone capture<br/>[microphone.py]"]
  node_wav["WAV recording file"]
end

subgraph group_ecosystem["Platform capabilities"]
  node_manager["Automatic initialization"]
  node_os["Operating-system audio"]
  node_examples["Usage examples"]
  node_alexa["Alexa integration"]
end

node_user(("Python user"))

node_user -->|"configures device"| node_config
node_user -->|"sets display"| node_led
node_user -->|"records audio"| node_mic
node_config -->|"reads and writes"| node_i2c
node_config -->|"configures interfaces"| node_hostconfig
node_led -->|"checks device state"| node_config
node_led -->|"updates pixels"| node_ledstate
node_led -->|"writes display data"| node_serial
node_mic -->|"checks state and rate"| node_config
node_mic -->|"reads audio data"| node_serial
node_mic -->|"writes recording"| node_wav
node_manager -.->|"initializes device"| node_config
node_os -.->|"plays audio"| node_user
node_examples -->|"demonstrates usage"| node_user
node_alexa -.->|"uses audio"| node_os

click node_config "https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/configuration.py"
click node_led "https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/ledmatrix.py"
click node_ledstate "https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/ledmatrix.py"
click node_mic "https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/microphone.py"
click node_examples "https://github.com/pi-top/pi-toppulse/tree/master/examples"

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_config,node_i2c,node_hostconfig,node_user toneBlue
class node_led,node_ledstate,node_serial,node_mic,node_wav toneAmber
class node_manager,node_os,node_examples,node_alexa toneMint
```

## Components

### Device setup

- [Device configuration](https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/configuration.py): `library/ptpulse/configuration.py`
- **I²C controller**
- **Host interface setup**

### Hardware I/O

- [LED matrix](https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/ledmatrix.py): `library/ptpulse/ledmatrix.py`
- [Pixel state and correction](https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/ledmatrix.py): `library/ptpulse/ledmatrix.py`
- **UART device**
- [Microphone capture](https://github.com/pi-top/pi-toppulse/blob/master/library/ptpulse/microphone.py): `library/ptpulse/microphone.py`
- **WAV recording file**

### Platform capabilities

- **Automatic initialization**
- **Operating-system audio**
- [Usage examples](https://github.com/pi-top/pi-toppulse/tree/master/examples): `examples`
- **Alexa integration**

### Other components

- **Python user**

## Connections

- Python user → Device configuration: configures device (evidence: `README.md`)
- Python user → LED matrix: sets display (evidence: `README.md`)
- Python user → Microphone capture: records audio (evidence: `README.md`)
- Device configuration → I²C controller: reads and writes (evidence: `library/ptpulse/configuration.py`)
- Device configuration → Host interface setup: configures interfaces (evidence: `library/ptpulse/configuration.py`)
- LED matrix → Device configuration: checks device state (evidence: `library/ptpulse/ledmatrix.py`)
- LED matrix → Pixel state and correction: updates pixels (evidence: `library/ptpulse/ledmatrix.py`)
- LED matrix → UART device: writes display data (evidence: `library/ptpulse/ledmatrix.py`)
- Microphone capture → Device configuration: checks state and rate (evidence: `library/ptpulse/microphone.py`)
- Microphone capture → UART device: reads audio data (evidence: `library/ptpulse/microphone.py`)
- Microphone capture → WAV recording file: writes recording (evidence: `library/ptpulse/microphone.py`)
- Automatic initialization → Device configuration: initializes device (evidence: `README.md`)
- Operating-system audio → Python user: plays audio (evidence: `README.md`)
- Usage examples → Python user: demonstrates usage (evidence: `README.md`)
- Alexa integration → Operating-system audio: uses audio (evidence: `README.md`)
