initial commit

README.md

@@ -0,0 +1,90 @@
+# led-controller
+
+A daemon that automatically turns RGB LEDs on and off based on display state. When your monitor sleeps or you lock your screen, LEDs turn off. When you wake or unlock, they turn back on.
+
+Controls two types of lights:
+- **Computer RGB** via [OpenRGB](https://openrgb.org/) CLI (motherboard, RAM, GPU, peripherals)
+- **External LEDs** via CH341 USB serial relay (LED strips, desk lights, etc.)
+
+## Requirements
+
+- Linux with D-Bus (GNOME, KDE, XFCE, etc.)
+- Go 1.21+
+- [OpenRGB](https://openrgb.org/) installed (for PC RGB control)
+- CH341 USB relay module on `/dev/ttyUSB0` (for external LED control)
+
+## Build & Install
+
+```bash
+make build
+make install           # binary + config to ~/.config/led-controller/
+make install-service   # enable systemd user service
+```
+
+## Usage
+
+### Daemon (automatic)
+
+```bash
+# Start via systemd
+systemctl --user start led-controller
+
+# Or run directly
+./led-controller daemon
+```
+
+The daemon turns LEDs on at startup, then listens for D-Bus signals to toggle them:
+- **Screen lock/blank** → LEDs off
+- **Screen unlock/unblank** → LEDs on
+- **System suspend** → LEDs off
+- **System wake** → LEDs on
+
+### Manual toggle
+
+```bash
+./led-controller on
+./led-controller off
+```
+
+## Configuration
+
+Config file: `~/.config/led-controller/config.toml`
+
+```toml
+[openrgb]
+enabled = true
+
+[relay]
+enabled = true
+device = "/dev/ttyUSB0"
+baud = 9600
+channel = 1
+
+[monitor]
+# "screensaver" - screen lock/blank events only
+# "logind"      - system suspend/resume only
+# "all"         - both (default)
+method = "all"
+```
+
+## Permissions
+
+The USB relay device requires read/write access. Add your user to the `dialout` group:
+
+```bash
+sudo usermod -aG dialout $USER
+```
+
+Log out and back in for the group change to take effect.
+
+## Architecture
+
+```
+main.go              Daemon entry point, signal handling, event loop
+config/              TOML config loader
+monitor/             D-Bus listener (screensaver + logind signals)
+controller/
+  controller.go      Orchestrates OpenRGB + relay
+  openrgb/           OpenRGB CLI wrapper
+  relay/             CH341 serial relay protocol (0xA0 command format)
+```