mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-10-17 20:39:13 +00:00

Files

T

ChuckBuildsandClaude Opus 5 94f70eab31 fix(install): render the systemd units from their templates, not from heredocs

The installers carried their own inline copies of units that also exist as
templates under systemd/, and the copies drifted.

install_service.sh renders ledmatrix.service from the template correctly, then
wrote ledmatrix-web.service from a heredoc that predated it -- missing
Wants=network-online.target, RestartSec=10, SyslogIdentifier, CacheDirectory,
CacheDirectoryMode and Environment=USE_THREADING=1. install_web_service.sh had
a third copy, and install_wifi_monitor.sh a fourth, that one already differing
from its template (syslog where the template says journal).

startup_validator.py compares the installed unit against the template, so a
rig installed this way warned on every boot -- and the remedy the warning
names, "re-run scripts/install/install_service.sh", reinstalled the same stale
copy. The warning could never clear. Reproduced on a live rig running exactly
that unit.

All three installers now render systemd/*.service through the same placeholder
substitution. The template gains a __USER__ placeholder rather than hardcoding
User=root, because the web interface runs as whoever installed it.

That last point was a second, independent cause of a permanent warning: the
validator substituted a fixed "root", so any non-root install reported drift
forever. It now reads User= from the installed unit -- an install-time
decision, not something the template dictates -- and compares everything else
strictly. first_time_install.sh already reads the installed User= the same way.

Tests cover a non-root web unit not warning, a genuinely changed directive in
that unit still warning, the User= fallback, and a grep-based guard that no
installer under scripts/install/ contains an inline unit body. That guard is
what found the install_wifi_monitor.sh copy.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9

2026-09-09 18:17:35 -04:00

ledmatrix-dns-fix.service

feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge (#538 )

2026-09-08 08:34:52 -04:00

ledmatrix-mqtt-bridge.service

feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge (#538 )

2026-09-08 08:34:52 -04:00

ledmatrix-web.service

fix(install): render the systemd units from their templates, not from heredocs

2026-09-09 18:17:35 -04:00

ledmatrix-wifi-monitor.service

fix: keep low-memory boards reachable under load (#464 )

2026-08-19 12:28:22 -04:00

ledmatrix.service

harden: cap malloc arenas, warn on unit drift, and grant the portal's sudo commands (#476 )

2026-08-21 14:29:45 -04:00

README.md

feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge (#538 )

2026-09-08 08:34:52 -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
ledmatrix-dns-fix.service - DNS single-request fix (optional)
- Re-applies options single-request to the resolver on every boot, because whatever manages resolv.conf regenerates it and drops the option again
- Works around glibc's parallel A/AAAA lookup stalling ~5s per name on routers that answer only the A query, which makes any plugin calling an external API slow or (for Starlark apps, which have a render timeout) fail outright
- Uses scripts/utils/apply_dns_single_request.sh
- Install only if external API calls are timing out; it is not part of a normal install
ledmatrix-mqtt-bridge.service - Home Assistant MQTT bridge (optional)
- Exposes the display to Home Assistant over MQTT Discovery: force a mode, stop on-demand, toggle power, set brightness
- Uses integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py, which drives the web API rather than the display directly
- Needs integrations/mqtt_bridge/bridge_config.json; see that directory's README

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
install_dns_fix.sh installs ledmatrix-dns-fix.service (opt-in, not run by the normal installer)
install_mqtt_bridge.sh installs ledmatrix-mqtt-bridge.service (opt-in)

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