Ambilight per Plasma 6: demone Adalight + plasmoide con slider

- backend/ambicapture.py: cattura Wayland via ScreenCast portal + PipeWire
- backend/ambilightd.py: demone, 47 zone sul bordo superiore, luminosita/contrasto/
  saturazione/banda, invio Adalight su seriale, servizio D-Bus org.enne2.Ambilight
- backend/ambilight-ctl: CLI JSON per il plasmoide
- backend/ambilight.service: avvio automatico (systemd --user)
- package/org.enne2.ambilight: applet vassoio con popup e slider
- install.sh / uninstall.sh senza root

README.md

@@ -0,0 +1,88 @@
+# ambilight-plasmoid
+
+Ambilight per KDE Plasma 6: cattura il bordo superiore dello schermo su **Wayland**
+(portal ScreenCast + PipeWire), calcola il colore medio di 47 zone e pilota una
+striscia **WS2812B** collegata a un **ESP8266 (Wemos D1 mini)** con firmware
+**Adalight** via seriale. Il controllo sta in un **plasmoide nel vassoio di sistema**,
+con popup per luminosità, contrasto, saturazione e banda campionata.
+
+```
+schermo ──portal──▶ ambilightd ──Adalight/seriale──▶ ESP8266 ──▶ striscia
+                        ▲
+                        │ D-Bus org.enne2.Ambilight
+                        │
+                ambilight-ctl  ◀── plasmoide (Plasma 6, QML)
+```
+
+## Componenti
+
+| File | Ruolo |
+|---|---|
+| `backend/ambicapture.py` | negoziazione ScreenCast portal + pipeline GStreamer (`pipewiresrc`) |
+| `backend/ambilightd.py` | demone: cattura, calcolo zone, luminosità/contrasto/saturazione, invio Adalight, servizio D-Bus |
+| `backend/ambilight-ctl` | CLI che parla col demone e stampa JSON (usata dal plasmoide) |
+| `backend/ambilight.service` | unit `systemd --user` (avvio automatico al login) |
+| `package/org.enne2.ambilight/` | plasmoide Plasma 6 (icona nel vassoio + popup con slider) |
+| `install.sh` / `uninstall.sh` | installazione e rimozione, senza root |
+
+## Hardware
+
+- ESP8266 Wemos D1 mini (clone), firmware **Adalight-FastLED** con `PIN_DATA 5` (= D1/GPIO5),
+  `Num_Leds` = dimensione buffer (256): il numero reale di LED lo decide il software che invia i frame.
+- Striscia WS2812B **47 LED** sul solo bordo superiore.
+- Cablaggio: `D1 → 470 Ω → DIN`, alimentatore 5 V separato (~60 mA/LED), **massa comune**,
+  1000 µF sull'alimentazione; level shifter 74AHCT125 se il filo dati è lungo.
+
+## Installazione
+
+```sh
+./install.sh          # backend + servizio utente + plasmoide
+```
+
+Al primo avvio il desktop chiede il permesso di **condividere lo schermo**: va concesso
+una volta (viene memorizzato in `~/.cache/ambilight/restore_token`).
+
+Il plasmoide appare nel vassoio come **Ambilight** (icona TV); clic per il popup.
+
+## Uso da terminale
+
+```sh
+ambilight-ctl state                     # JSON con tutto lo stato
+ambilight-ctl start | stop | toggle
+ambilight-ctl set brightness 0.8         # brightness|contrast|saturation|band|reverse|leds
+ambilight-ctl get fps
+systemctl --user status ambilight.service
+```
+
+## Configurazione
+
+`~/.config/ambilight/config.json` (scritto dal demone a ogni modifica):
+
+| chiave | range | default | note |
+|---|---|---|---|
+| `brightness` | 0.05 – 2.0 | 1.0 | moltiplicatore |
+| `contrast` | 0.5 – 2.0 | 1.0 | pivot sul grigio 128 |
+| `saturation` | 0.0 – 2.0 | 1.0 | 0 = bianco e nero |
+| `band` | 0.02 – 0.5 | 0.12 | frazione di altezza campionata |
+| `reverse` | bool | true | LED 0 sul lato destro (verificato a schermo) |
+| `leds` | 1 – 256 | 47 | LED della striscia |
+| `port`, `baud` | – | `/dev/ttyUSB0`, 115200 | seriale |
+| `side` | top/bottom | top | bordo campionato |
+| `auto_start` | bool | true | streaming attivo all'avvio del demone |
+
+## Prestazioni misurate
+
+- 47 LED, Adalight a 115200: ~**78 fps** (limite teorico della seriale per 147 byte/frame).
+- Cattura: portal + PipeWire, pipeline ridotta a `47×4 × 72` px RGB → costo CPU trascurabile.
+
+## Note
+
+- Il firmware Adalight manda `Ada\n` una volta al secondo quando non riceve frame: è
+  l'heartbeat del protocollo, non un errore.
+- Il demone tiene la seriale in esclusiva: Prismatik (o altri programmi Adalight) vanno chiusi.
+- `ModemManager` su Fedora può contendere `/dev/ttyUSB0`: se la porta risulta occupata
+  serve una regola udev con `ID_MM_DEVICE_IGNORE`.
+
+## Licenza
+
+GPL-3.0-or-later (come i componenti KDE con cui interagisce).