From a1db748ff6e296d1a5067f93d3f9f7d51e71779c Mon Sep 17 00:00:00 2001
From: Tina Schellander <tina.schellander@sub-net.at>
Date: Sat, 7 Feb 2026 11:44:53 +0100
Subject: [PATCH] Add project README

---
 README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dffa088
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# elgato-cli
+
+CLI tool and KDE Plasma 6 widget to control an Elgato Key Light.
+
+## Features
+
+- **CLI**: Discover, toggle, and adjust brightness/temperature from the terminal
+- **KDE Plasmoid**: System tray widget with power switch, brightness and temperature sliders
+- **Shared config**: CLI discovery saves the light IP, plasmoid picks it up automatically
+- **Resilient**: Retries and HTTP/1.0 workarounds for the light's flaky TCP stack
+
+## Installation
+
+### CLI
+
+```bash
+# With pipx (recommended, system-wide)
+pipx install /path/to/elgato-cli
+
+# Or in a venv
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+### Plasmoid
+
+```bash
+./install-plasmoid.sh
+```
+
+Then add "Elgato Key Light" to your panel or system tray.
+
+## CLI Usage
+
+```bash
+# First run: discover light on the network (mDNS)
+elgato discover
+
+# Or configure manually
+elgato --host 192.168.230.111 status
+
+# Power
+elgato on
+elgato off
+elgato toggle
+
+# Brightness (3-100)
+elgato brightness          # get
+elgato brightness 50       # set
+
+# Color temperature (143-344 mired, or Kelvin with -k)
+elgato temperature         # get
+elgato temperature 250     # set in mired
+elgato temperature 4000 -k # set in Kelvin
+
+# Device info
+elgato info
+```
+
+Global `--host` and `--port` flags override the saved config.
+
+## Plasmoid
+
+The widget communicates directly with the light's HTTP API (no CLI dependency). It reads the shared config from `~/.config/elgato-cli/config.json`, or you can set the host/port in the widget settings.
+
+Features:
+- System tray icon (changes based on light state)
+- Middle-click to toggle power
+- Brightness and temperature sliders (value sent on release)
+- 3-second polling to keep state in sync
+
+## Elgato HTTP API
+
+The light exposes a REST API on port 9123 with no authentication:
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/elgato/lights` | GET | Current state |
+| `/elgato/lights` | PUT | Set state |
+| `/elgato/accessory-info` | GET | Product info |
+| `/elgato/lights/settings` | GET | Light settings |
+
+PUT payload:
+```json
+{"numberOfLights": 1, "lights": [{"on": 1, "brightness": 50, "temperature": 200}]}
+```
+
+Temperature is in mired: `mired = 1000000 / kelvin` (143 = 7000K cool, 344 = 2900K warm).
+
+## Known Quirks
+
+The Elgato Key Light firmware has a buggy TCP stack:
+- HTTP/1.1 GET requests get connection-reset — we use HTTP/1.0 for reads
+- HTTP/1.0 PUT requests get 400 Bad Request — we use HTTP/1.1 with `Connection: close` for writes
+- Rapid connections can lock up the light (requires power cycle) — requests are retried with 1s delay
+
+## Config
+
+Stored at `~/.config/elgato-cli/config.json`:
+
+```json
+{"host": "192.168.230.111", "port": 9123, "name": "Elgato Key Light"}
+```
+
+## Dependencies
+
+- Python 3.11+
+- [click](https://click.palletsprojects.com/) - CLI framework
+- [requests](https://requests.readthedocs.io/) - HTTP (exception types only, actual requests use `http.client`)
+- [zeroconf](https://github.com/python-zeroconf/python-zeroconf) - mDNS discovery
+- KDE Plasma 6 (for the plasmoid)