first commit

2026-08-23 21:34:07 +02:00
commit 1d3dcba1a9
62 changed files with 12456 additions and 0 deletions
@@ -0,0 +1,112 @@
+# API examples
+
+`TOKEN` is optional when `GREE_CONTROLLER_APP_TOKEN` is empty.
+
+```bash
+AUTH='Authorization: Bearer TOKEN'
+BASE='http://127.0.0.1:8787'
+```
+
+
+## Home Assistant access tokens
+
+Create and revoke integration tokens from the controller Web UI under **Settings -> Home Assistant integration access**. The clear-text secret is returned only once and the SQLite database stores only its SHA-256 hash.
+
+Administrator endpoints:
+
+```text
+GET    /api/access-tokens
+POST   /api/access-tokens
+DELETE /api/access-tokens/{id}
+```
+
+The Home Assistant custom integration uses a restricted API surface:
+
+```text
+GET    /api/integrations/home-assistant/devices
+POST   /api/integrations/home-assistant/devices/{id}/command
+```
+
+These two endpoints always require `Authorization: Bearer <generated-token>` (or the administrator `GREE_CONTROLLER_APP_TOKEN`). A generated HA token cannot update settings, run discovery, delete devices, manage tokens, or use the controller WebSocket.
+
+## Discovery
+
+```bash
+curl -X POST "$BASE/api/discovery" -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"timeout_ms":3000,"broadcast":"255.255.255.255:7000"}'
+```
+
+## Device command
+
+```json
+{
+  "power": true,
+  "mode": "cool",
+  "target_temperature": 22.0,
+  "fan_speed": 3,
+  "swing_vertical": true,
+  "quiet": false,
+  "turbo": false,
+  "light": true
+}
+```
+
+Supported modes: `auto`, `cool`, `dry`, `fan`, `heat`. Fan speed: `0..5`.
+
+## Zone
+
+```json
+{
+  "name": "Living room",
+  "device_id": "gree-aabbccddeeff",
+  "enabled": true,
+  "mode": "cool",
+  "setpoint": 23.0,
+  "hysteresis": 0.6,
+  "min_on_seconds": 180,
+  "min_off_seconds": 180,
+  "sensor_source": "combined",
+  "ha_entity_id": "sensor.living_room_temperature",
+  "external_sensor_weight": 0.4,
+  "max_sensor_difference": 3.0
+}
+```
+
+`sensor_source` supports:
+
+- `device` — GREE indoor sensor only,
+- `combined` — GREE + this zone's HA room sensor,
+- `home_assistant` — this zone's HA room sensor, with GREE fallback.
+
+For `combined` and `home_assistant`, set a per-zone `ha_entity_id`. `external_sensor_weight` is `0.0..1.0`. If a combined sensor pair differs by more than `max_sensor_difference`, the controller falls back to GREE. The returned zone object includes `device_temperature`, `external_temperature`, `current_temperature`, and `control_temperature_source`.
+
+## Schedule
+
+Weekdays use ISO numbers: Monday `1`, Sunday `7`.
+
+```json
+{
+  "zone_id": "UUID",
+  "name": "Night",
+  "enabled": true,
+  "weekdays": [1,2,3,4,5,6,7],
+  "start_time": "22:00",
+  "end_time": "06:00",
+  "setpoint": 24.0
+}
+```
+
+## WebSocket
+
+Connect to `ws://HOST:8787/ws?token=TOKEN`. The first message uses event type `bootstrap`; later events include `device.updated`, `zone.updated`, `settings.updated` and `log.created`.
+
+## Localization assets
+
+Localization endpoints are public because the login dialog also needs translations. Language packs are embedded in the Rust binary at build time.
+
+```bash
+curl "$BASE/lang/index.json"
+curl "$BASE/lang/en.json"
+```
+
+`GET /lang/index.json` returns the automatically generated language catalog. `GET /lang/<code>.json` returns the corresponding language pack. Add a valid `lang/<code>.json` file and rebuild to expose a new language.