# 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.