MAX7219 Raspberry Pi Clock

Русская версия: README.ru.md

32x8 LED-matrix clock for Raspberry Pi (MAX7219 + SPI) with CPU temperature, date ticker, auto-brightness and lightweight animations.

Features

• Right-aligned HH:MM clock with custom blinking colon
• CPU temperature widget (°C) on the left
• English ASCII date ticker (scrolling line)
• Day/night auto brightness by time window
• Seconds progress bar
• Optional hour sparkle + minute swipe animations
• Runtime configuration via environment variables

Hardware

• Raspberry Pi (with SPI enabled)
• MAX7219 32x8 LED matrix (4 cascaded 8x8 blocks)
• SPI wiring (default SPI0 CE0)

Software requirements

• Python 3.10+
• luma.led_matrix

Install deps:

pip install -r requirements.txt

Quick start

python3 led_clock.py

Main environment variables

Time and text

• LED_TIME_FMT (default: %H:%M)
• LED_FONT (1 = TINY, 2 = SINCLAIR)
• LED_BLINK_COLON (0/1)
• LED_COLON_VGAP (default: 2)
• LED_TIME_ALIGN (right or center, default: right)

Temperature widget

• LED_DRAW_TEMP (0/1)
• LED_TEMP_SHOW_C (0/1)

CPU/Outdoor temperature cycling

• LED_TEMP_CYCLE_ENABLE (0/1)
• LED_TEMP_CYCLE_ITEMS (e.g. cpu,outdoor)
• LED_TEMP_CYCLE_EVERY (seconds, default 10)

Outdoor weather (Open-Meteo, no API key)

• LED_WEATHER_ENABLE (0/1)
• LED_WEATHER_PROVIDER (open-meteo)
• LED_WEATHER_LAT / LED_WEATHER_LON (required for outdoor temp)
• LED_WEATHER_REFRESH (seconds, default 1800)
• LED_WEATHER_TIMEOUT (seconds, default 4)

Date ticker

• LED_TICKER_EVERY (sec, default 60)
• LED_TICKER_SPEED (default 0.07)
• LED_TICKER_GAP (default 16)
• LED_TICKER_WITH_YEAR (0/1)
• LED_TICKER_FONT (1/2)

Brightness

• LED_AUTO_DIM (0/1)
• LED_BRIGHTNESS_DAY (0..255, default 12)
• LED_BRIGHTNESS_NIGHT (0..255, default 3)
• LED_NIGHT_FROM (default 22:30)
• LED_NIGHT_TO (default 07:00)

Visuals

• LED_SECONDS_BAR (0/1)
• LED_SECONDS_BAR_DOTTED (0/1)
• LED_SPARKLE_ON_HOUR (0/1)
• LED_SPARKLE_DURATION (default 0.45)
• LED_SPARKLE_DENSITY (default 0.15)
• LED_SPARKLE_FPS (default 20)
• LED_MINUTE_SWIPE (0/1)
• LED_MINUTE_SWIPE_PX (default 8)
• LED_MINUTE_SWIPE_DELAY (default 0.03)

Hardware

• LED_SPI_PORT (default 0)
• LED_SPI_DEVICE (default 0)
• LED_BUS_HZ (default 16000000)
• LED_CASCADED (default 4)
• LED_ORIENTATION (default -90)
• LED_ROTATE (default 0)

Display modes and quick switching

To keep code clean and follow configuration-as-data pattern, display behavior is grouped into profiles:

• config/profiles/clock.env — minimal clock
• config/profiles/status.env — balanced status mode
• config/profiles/info.env — info carousel (custom page set)
• config/profiles/tempclock.env — temperature + clock (no ticker)
• config/profiles/weather.env — CPU/outdoor temperature cycling

Switch mode quickly:

chmod +x scripts/mode.sh
./scripts/mode.sh clock
./scripts/mode.sh status
./scripts/mode.sh info
./scripts/mode.sh tempclock
./scripts/mode.sh weather

The script updates /etc/default/led-clock and restarts service.

info mode is configurable via:

• LED_INFO_PAGES=time,temp,cpu,load,ram,ip,date,uptime
• LED_INFO_ROTATE_SEC=6
• LED_INFO_ENABLE=1

Autostart with systemd

Files in repo:

• deploy/systemd/led-clock.service
• deploy/systemd/led-clock.env.example
• scripts/install-systemd.sh

Install on Raspberry Pi:

chmod +x scripts/install-systemd.sh
./scripts/install-systemd.sh

Service checks:

sudo systemctl status led-clock.service
tail -f /var/log/led-clock.log
sudo journalctl -u led-clock.service -f

Environment config is stored in /etc/default/led-clock. Logrotate config is installed to /etc/logrotate.d/led-clock.

Notes

• The script handles SIGINT/SIGTERM and clears display on shutdown.
• CPU temp reads from /sys/class/thermal/thermal_zone0/temp, then falls back to vcgencmd.

Project status

Work in progress. Interface and defaults may still change.