Stats Monitor for Raspberry Pi Display

This project provides system monitoring stats displayed on a Raspberry Pi with an SPI display, using pibox-framebuffer service for rendering PNGs on ST7789 displays.

Inspiration:

I have a KubeSail PiBox which is still a nice Raspberry Pi enclousre, but its echo system became obelese with the retirement of the KubeSail project (PiBox docs here and this is (wayback link in case the docs also die)).

After reflashing the Pi, I couldn't find a decent of box solution for displaying stats on the enclosures ST7789 display, hence this project. I forked https://github.com/kubesail/pibox-framebuffer to wrap it into a deployable Docker container, then created this project to have a docker stack for displaying stats on the LCD.

I started from this Adafruit 1.3" Color stats example, but ended up using the pibox-framebuffer because the relying on the Python based SPI driver was causing display to flicker.

This is how the stats looks like:

Major parts of the code were vibed with Kiro based on my own "inspirational" 🙂 instructions. I still had to spend a day worth of effort to clean up after Kiro and fix docker issues that it seemed clueless to tackle.

Parts of this README.md is also generated by Kiro in case you found it a bit cheesy.

Usage

The following docker-compose stack can be used to deploy a stack wiht spi-stats and pibox-framebuffer

services:
  pibox-framebuffer:
    image: ghcr.io/cybermaak/pibox-framebuffer:latest
    container_name: pibox-framebuffer
    privileged: true
    ports:
      - "2019:2019"
    devices:
      - /dev/mem:/dev/mem
      - /dev/gpiomem:/dev/gpiomem
      - /dev/spidev0.0:/dev/spidev0.0
      - /dev/spidev0.1:/dev/spidev0.1
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:2019/health" ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

  spi-stats:
    image: ghcr.io/cybermaak/spi-stats:latest
    container_name: spi-stats
    depends_on:
      - pibox-framebuffer
    network_mode: "host"
    volumes:
      - /proc:/host/proc:ro # Mount host's /proc to /host/proc to pull host stats
      - /:/host/disk_root:ro # Mount host's root disk to get host disk stats    
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "pgrep", "-f", "python3 /app/src/stats.py" ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    environment:
      - PROCFS_PATH=/host/proc
      - DISK_ROOT=/host/disk_root

Note: You may notice that pibox-framebuffer is forwarding its port to the host and that the spi-state is using host network. This is done instead of have the two communicate on the stack network to be able to show the IP of the host vs the docker IP.

Architecture

• pibox-framebuffer: Runs as a separate Docker container from ghcr.io/cybermaak/pibox-framebuffer:latest on port 2019
• src/stats.py: Python script that collects system stats and sends them to the framebuffer service via HTTP

Quick Start

Run the Complete Stack

./run.sh

This will:

1. Pull the latest pibox-framebuffer image
2. Build and start both services using docker compose
3. Display system stats on your SPI display

Stop Services

./stop.sh

Development

Local Development

To run src/stats.py locally (useful for development):

./run-local.sh

This assumes pibox-framebuffer is already running on localhost:2019.

Build Only

To just build the stats Docker image:

./build.sh

Manual Commands

Start pibox-framebuffer only

sudo docker run -d --privileged --name pibox-framebuffer -p 2019:2019 \
  --device /dev/mem:/dev/mem \
  --device /dev/gpiomem:/dev/gpiomem \
  --device /dev/spidev0.0:/dev/spidev0.0 \
  --device /dev/spidev0.1:/dev/spidev0.1 \
  ghcr.io/cybermaak/pibox-framebuffer:latest

Run stats container only

sudo docker run --rm --network host stats:latest

Monitoring

View Logs

# View pibox-framebuffer logs
sudo docker compose logs -f pibox-framebuffer

# View stats logs
sudo docker compose logs -f stats

# View all logs
sudo docker compose logs -f