99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
# 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.
|