piclockctl

#!/usr/bin/env python3
"""Send a one-off display command to the running PiClock service.

Usage: piclockctl on|off|bright|dim|brightness N

  on            show the time again
  off           blank the display (the clock keeps running)
  bright        full brightness (level 15)
  dim           dimmest lit level (level 0)
  brightness N  any HT16K33 level, 0-15

Commands behave like Siri commands: they stick until the day/night schedule's
next on/off edge. Requires membership in the 'clockctl' group (or root):

    sudo usermod -aG clockctl $USER    # then log out/in

The socket path defaults to the one the systemd unit sets; a PICLOCK_CTL_SOCKET
environment variable overrides it (dev runs against a non-default socket).
"""
import os
import socket
import sys

SOCKET_PATH = os.environ.get("PICLOCK_CTL_SOCKET", "/run/piclock/ctl.sock")

# bright/dim are client-side conveniences; the wire protocol (piclock/ctl.py) only
# knows on/off/brightness.
ALIASES = {"bright": "brightness 15", "dim": "brightness 0"}


def main() -> int:
    args = [a.lower() for a in sys.argv[1:]]
    if len(args) == 1 and args[0] in ("on", "off", *ALIASES):
        message = ALIASES.get(args[0], args[0])
    elif len(args) == 2 and args[0] == "brightness" and args[1].isdigit() and int(args[1]) <= 15:
        message = f"brightness {int(args[1])}"
    else:
        print(__doc__.strip(), file=sys.stderr)
        return 2

    sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
    try:
        sock.sendto(message.encode(), SOCKET_PATH)
    except FileNotFoundError:
        print(f"{SOCKET_PATH}: no socket — is piclock running?", file=sys.stderr)
        return 1
    except ConnectionRefusedError:
        print(f"{SOCKET_PATH}: nothing listening — is piclock running?", file=sys.stderr)
        return 1
    except PermissionError:
        print(
            f"{SOCKET_PATH}: permission denied — add yourself to the 'clockctl' "
            "group (sudo usermod -aG clockctl $USER, then log out/in)",
            file=sys.stderr,
        )
        return 1
    finally:
        sock.close()
    return 0


if __name__ == "__main__":
    sys.exit(main())