Windfree poller application & jenkins pipeline

README.md

@@ -0,0 +1,98 @@
+# SmartThings WindFree poller
+
+Kis erőforrásigényű, Python 3.11-es daemon egy SmartThings-eszköz teljes
+állapotának ötpercenkénti lekérésére és Redpanda Connect felé továbbítására.
+Nincs közvetlen külső runtime függősége.
+
+## Hitelesítés
+
+Tartós futtatáshoz OAuth-integráció szükséges. Az első engedélyezést külső,
+böngészős folyamatban kell elvégezni; az abból kapott tokeneket a daemon
+automatikusan frissíti. Rövid teszthez `access_token` (PAT) is megadható, de a
+daemon működése ne függjön kézzel cserélendő tokentől.
+
+A PAT külön fájlból is olvasható az `access_token_file` beállítással. A fájl
+legyen csak a service user számára olvasható (`0600`). A PAT scope-jai nem adnak
+refresh tokent; refresh token csak OAuth authorization-code flow során keletkezik.
+
+## Repository szerkezete
+
+```text
+deploy/             systemd unitok a DS1 telepítéséhez
+redpanda-connect/   a hozzá tartozó ingest pipeline mintája
+src/                Python csomag
+tests/              standard library unit tesztek
+Jenkinsfile         Python 3.11 CI pipeline Kubernetes agenten
+```
+
+A repository nem tartalmaz virtuális környezetet, build artifactot, futásidejű
+konfigurációt vagy tokent. Ezeket a `.gitignore` is kizárja.
+
+A szükséges jogosultság legalább az engedélyezett eszköz állapotának olvasása.
+A titkokat ne írd a TOML-ba; használd a systemd environment fájlt:
+
+```text
+SMARTTHINGS_CLIENT_ID=...
+SMARTTHINGS_CLIENT_SECRET=...
+SMARTTHINGS_REFRESH_TOKEN=...
+```
+
+## Telepítés Raspberry Pi OS-en
+
+```bash
+sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin smartthings-poller
+sudo mkdir -p /opt/smartthings-windfree /etc/smartthings-windfree
+sudo cp -r pyproject.toml src /opt/smartthings-windfree/
+sudo python3.11 -m venv /opt/smartthings-windfree/venv
+sudo /opt/smartthings-windfree/venv/bin/pip install /opt/smartthings-windfree
+sudo cp config.example.toml /etc/smartthings-windfree/config.toml
+sudo cp deploy/smartthings-windfree.service /etc/systemd/system/
+sudo chmod 600 /etc/smartthings-windfree/config.toml /etc/smartthings-windfree/secrets
+sudo systemctl daemon-reload
+sudo systemctl enable --now smartthings-windfree
+```
+
+Egyszeri próba: `smartthings-windfree-poller --config config.toml --once`.
+
+## Mezők és események
+
+A SmartThings `GET /v1/devices/{deviceId}/status` válaszában minden érték a
+`components.<component>.<capability>.<attribute>` útvonalon található. Minden
+`[[fields]]` blokk egy kimeneti mezőt ír le. Az opcionális `equals` logikai
+értékké alakítja az összehasonlítást; ez alkalmas például a `windFree` módra.
+A Samsung modellek capability-kiosztása eltérhet, ezért először ellenőrizd a
+saját eszköz teljes status-válaszát, majd igazítsd a TOML-t.
+
+Az esemény `info/ok`, ha minden konfigurált mező megvan. Ha akár egy hiányzik,
+`warning/no_data`, és a `missing_fields` felsorolja őket. SmartThings HTTP- vagy
+API-hibánál `error/error`, az `error.api_response` pedig változtatás nélkül
+tartalmazza a dekódolt API-választ. A Redpanda Connect elérhetetlensége helyben
+naplózott hiba; nincs lemezspool, így a daemon kicsi és egyszerű marad.
+
+## Redpanda Connect és teszt
+
+A `redpanda-connect/windfree-ingest.yaml` validál, ingest időt ad hozzá, az
+eszközazonosítót Kafka-kulcsként használja, majd az eseményt a
+`smartthings.device-status.v1` topicba írja. A broker, topic és TLS environment
+változókkal állítható. Ha a klaszter SASL-t kér, egészítsd ki az outputot a
+telepítésedhez tartozó Redpanda Connect `sasl` blokkal; az alapkonfiguráció nem
+kényszerít üres felhasználóneves hitelesítést.
+
+```bash
+python3.11 -m unittest discover -s tests -v
+```
+
+A Jenkins pipeline ugyanezeket a teszteket futtatja Python 3.11-en. Ha a
+repositoryban még nincs unit teszt, a teszt stage sikeresen, kihagyottként fut
+le. Sikeres ellenőrzés után rootless BuildKit készít ARM64 container image-et,
+majd commit hash és `latest` taggel feltölti ide:
+
+```text
+repo.attilabito.com/apps/windfree-poller
+```
+
+A `Jenkinsfile.deploy` egy külön, kizárólag kézzel indítható job definíciója.
+A célgép előre engedélyezett listából választható; jelenleg csak a
+`raspberry-pi-4b` szerepel benne. A Raspberry Pi-n a Dockernek, a runtime
+konfigurációnak és a `/var/lib/smartthings-windfree` útvonalnak a telepítés
+előtt rendelkezésre kell állnia.