mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-08-19 17:39:06 +00:00

Files

T

ChuckandClaude Opus 5 8927a1b6b1 perf(memory): size the cache to the board and stop reinstalling deps

On a 1GB Pi 3B+ the display process settles around 600MB RSS of 905MB
total. When the remaining headroom runs out the failure is not a clean
crash: fork() starts returning ENOMEM, so sshd accepts connections and
closes them before its banner, timer jobs stop running, and the panel
goes dark, while already-resident processes keep serving normally. The
board looks healthy from outside and cannot be logged into. Only a power
cycle clears it.

Three contributing causes:

- MemoryCache had a fixed 1000-entry ceiling. Entries are parsed API
  payloads of tens of KB, so one ceiling cannot serve both a 512MB Zero
  2 W and an 8GB Pi 5. Now scaled from MemTotal (150 entries at <=1GB,
  1500 at >=8GB), overridable with LEDMATRIX_CACHE_MAX_ENTRIES.

- requirements_are_satisfied() returned False for any requirement with
  extras, so a plugin depending on python-socketio[client] re-ran pip on
  every single start: ~8s, a network dependency, and a 100-200MB spike
  at the least convenient moment. During a restart loop it repeats for
  each restart. Extras are now resolved one level deep against installed
  metadata, keeping the conservative "anything unverifiable falls
  through to pip" contract.

- ledmatrix.service had no memory ceiling. MemoryMax=85% expressed as a
  percentage so one unit file suits every board. Note this needs the
  memory cgroup controller, which Pi firmware disables by default;
  first_time_install.sh now adds cgroup_enable=memory to cmdline.txt,
  and the unit file documents how to verify it took effect.

first_time_install.sh also enables persistent journald storage (capped
at 64M). Default storage is volatile, so every reboot destroys the logs
that would explain why the board rebooted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-18 19:13:30 -04:00

ledmatrix-web.service

fix(systemd): wait for network connectivity before starting services (#335 )

2026-05-15 15:47:35 -04:00

ledmatrix-wifi-monitor.service

fix(service): survive corrupt health cache and clean exits

2026-08-18 19:04:57 -04:00

ledmatrix.service

perf(memory): size the cache to the board and stop reinstalling deps

2026-08-18 19:13:30 -04:00

README.md

docs: refresh and correct stale documentation across repo (#306 )

2026-04-07 21:04:25 -04:00

README.md

Systemd Service Files

This directory contains systemd service unit files for LEDMatrix services.

Service Files

ledmatrix.service - Main LED Matrix display service
- Runs the display controller (run.py)
- Starts automatically on boot
- Runs as root for hardware access
ledmatrix-web.service - Web interface service
- Runs the web interface conditionally based on config
- Starts automatically on boot if web_display_autostart is enabled
- Uses scripts/utils/start_web_conditionally.py
ledmatrix-wifi-monitor.service - WiFi monitor daemon service
- Monitors WiFi/Ethernet connectivity
- Automatically enables/disables access point mode
- Uses scripts/utils/wifi_monitor_daemon.py

Installation

These service files are installed by the installation scripts in scripts/install/:

install_service.sh installs ledmatrix.service
install_web_service.sh installs ledmatrix-web.service
install_wifi_monitor.sh installs ledmatrix-wifi-monitor.service

Manual Installation

Important: the unit files in this directory contain __PROJECT_ROOT_DIR__ placeholders that the install scripts replace with the actual project directory at install time. Do not copy them directly to /etc/systemd/system/ — the service will fail to start with WorkingDirectory=__PROJECT_ROOT_DIR__ errors.

Always install via the helper script:
sudo ./scripts/install/install_service.sh
If you really need to do it by hand, substitute the placeholder first:
PROJECT_ROOT="$(pwd)"
sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT|g" systemd/ledmatrix.service \
  | sudo tee /etc/systemd/system/ledmatrix.service > /dev/null
sudo systemctl daemon-reload
sudo systemctl enable ledmatrix.service
sudo systemctl start ledmatrix.service

Service Management

# Check status
sudo systemctl status ledmatrix.service

# Start/stop/restart
sudo systemctl start ledmatrix.service
sudo systemctl stop ledmatrix.service
sudo systemctl restart ledmatrix.service

# Enable/disable autostart
sudo systemctl enable ledmatrix.service
sudo systemctl disable ledmatrix.service

# View logs
journalctl -u ledmatrix.service -f