piclock.service

[Unit]
Description=PiClock 7-segment bedroom clock
# Start once the network and the time-sync service are up. The app handles the
# brief pre-sync window itself by showing dashes, so it is fine to start early.
After=network-online.target time-sync.target
Wants=network-online.target

[Service]
Type=simple
# Dedicated unprivileged service account (see scripts/install.sh). Its only
# privilege is membership in the i2c group, which grants access to /dev/i2c-1.
# It has no sudo access and needs none.
User=clocker
Group=clocker
WorkingDirectory=/opt/piclock
ExecStart=/opt/piclock/venv/bin/python -u /opt/piclock/main.py
Restart=always
RestartSec=3

# Control socket for one-off CLI commands (piclockctl). systemd creates
# /run/piclock (owned by clocker); the app binds the socket there, mode 0660
# group clockctl, so members of that group can command the display (see
# piclock/ctl.py and scripts/install.sh, which creates the group).
RuntimeDirectory=piclock
Environment=PICLOCK_CTL_SOCKET=/run/piclock/ctl.sock

# Configuration (PICLOCK_* env overrides; see piclock/config.py).
# NOTE: systemd does not allow inline `#` comments on Environment= lines —
# the whole rest of the line is parsed as space-separated KEY=VALUE pairs.
# Keep each value on its own line and put comments on their own `#` lines.
# PICLOCK_BRIGHTNESS: 0-15; 0 = dimmest, for a dark bedroom.
Environment=PICLOCK_BRIGHTNESS=0
# PICLOCK_24H: 1 = 24-hour time, 0 = 12-hour (leading-zero hour blanked, no PM
# indicator). Flip to 1 (or comment out) to go back to 24-hour.
Environment=PICLOCK_24H=0
# PICLOCK_BLINK=1 makes the colon blink at 1 Hz (default: steady).
# Environment=PICLOCK_BLINK=1
# PICLOCK_TROUBLE_DOTS=1 inverts the two indicator dots into trouble lights:
# dark while Wi-Fi is up and NTP is fresh, lit only when something is wrong.
# Default 0 = status lights (lit while nominal).
# Environment=PICLOCK_TROUBLE_DOTS=1
# PICLOCK_WAKE_BRIGHTNESS / PICLOCK_NIGHT_BRIGHTNESS: 0-15 levels the optional
# day/night schedule applies at its wake and dim edges (defaults: 15 = full,
# 0 = dimmest lit level).
# Environment=PICLOCK_WAKE_BRIGHTNESS=15
# Environment=PICLOCK_NIGHT_BRIGHTNESS=0
#
# The optional day/night schedule and HomeKit integration are each enabled
# out-of-band by a systemd drop-in installed via `sudo scripts/install.sh
# --schedule` / `--homekit` (see systemd/piclock-schedule.conf and
# systemd/piclock-homekit.conf, plus SOFTWARE_RUNBOOK.md §4-5), so this base
# unit stays free of both.

# Hardening. The app only reads its own files, runs `timedatectl` over the
# system bus, and talks to /dev/i2c-1 (preserved via the i2c group).
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ProtectControlGroups=true
ProtectKernelTunables=true
ProtectKernelModules=true

[Install]
WantedBy=multi-user.target