# matrix-pi

Backup of the Pimoroni LTP-305G LED matrix display setup running on `matrixpi`
under the `dissimulo` user. Two LTP-305G modules are wired to the I2C bus and
display the current time as a clock — hour on the left module (I2C `0x61`),
minute on the right (I2C `0x63`).

## Hardware

- Raspberry Pi (running Debian Bookworm, kernel 6.6.x)
- 2 × Pimoroni LTP-305G breakouts on I2C bus 1
  - `0x61` — hour digits
  - `0x63` — minute digits

## What's in here

| Path | Purpose |
| --- | --- |
| `systemd/` | The two systemd units that run the clock at boot |
| `deployed/` | Mirror of the on-disk script tree the units invoke (includes the local `%I` 12-hour customization to `clock.py`) |
| `vendor/ltp305-python/` | Vendored copy of the Pimoroni `ltp305` Python library (offline install fallback) |
| `vendor/breakout-garden/` | Vendored copy of Pimoroni's Breakout Garden tooling (used for I2C autodetect) |
| `config/boot-firmware-config.txt.snippet` | The `/boot/firmware/config.txt` lines that enable I2C |
| `install.sh` | Idempotent restore script |
| `docs/inventory.md` | Source-of-truth inventory of every LTP-305G-related file on the live system |

## Restoring on a fresh Pi

1. Flash Raspberry Pi OS (Bookworm or later), create user `dissimulo`.
2. Ensure I2C is enabled — either via `raspi-config` or by appending the line
   from `config/boot-firmware-config.txt.snippet` to `/boot/firmware/config.txt`
   and rebooting.
3. Wire the two LTP-305G breakouts; confirm with `i2cdetect -y 1` that they
   appear at `0x61` and `0x63`. (Install `i2c-tools` if missing.)
4. From a clone of this repo, run:

   ```
   sudo ./install.sh
   ```

   This installs the `ltp305` Python package from `vendor/`, drops the
   customized scripts into `/home/dissimulo/Pimoroni/ltp305/`, and enables both
   systemd units.

5. Verify:

   ```
   systemctl status matrix0x61.service matrix0x63.service
   ```

## Local customization vs. upstream

The deployed `clock.py` differs from the upstream Pimoroni `ltp305-python`
example by one line — the `hour` format is `%I` (12-hour) instead of `%H`
(24-hour). This is preserved in `deployed/home/dissimulo/Pimoroni/ltp305/examples/clock.py`.

## Upstream provenance

Vendored sources were captured from these commits:

- `pimoroni/ltp305-python` @ `bf859fe6cddf8cffcb12d62bad8f21e0bbb9fc42`
- `pimoroni/breakout-garden` @ `9c331458ee8c4732dbc783a6409ef53d671d321b`