176 lines
5.7 KiB
Markdown
176 lines
5.7 KiB
Markdown
# 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":6000,"broadcast":"255.255.255.255:7000","protocol_version":0,"passes":3}'
|
|
```
|
|
|
|
`protocol_version` is `0` for auto/both, `1` for AES-ECB only, and `2` for AES-GCM only. `passes` is `1..10`. Auto is recommended when different GREE Wi-Fi module generations share the network.
|
|
|
|
## 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`. Physical GREE Celsius setpoints are normalized to whole degrees in the `8..30°C` range.
|
|
|
|
## Smart thermostat / house control
|
|
|
|
The controller separates the seasonal house mode from per-zone profiles. Normal operation uses setpoint modulation: units remain powered while the controller moves the device target between an active and satisfied setpoint. `off` is the explicit hard-off house mode.
|
|
|
|
```bash
|
|
curl -X POST "$BASE/api/house/control" -H "$AUTH" -H 'Content-Type: application/json' \
|
|
-d '{"mode":"cool"}'
|
|
|
|
curl -X POST "$BASE/api/house/preset" -H "$AUTH" -H 'Content-Type: application/json' \
|
|
-d '{"preset":"sleep"}'
|
|
```
|
|
|
|
House modes: `cool`, `heat`, `off`. House presets: `auto`, `comfort`, `sleep`, `away`. A non-`auto` house preset creates temporary per-zone overrides that expire at each zone's next schedule boundary.
|
|
|
|
A zone stores separate profile temperatures for both seasons:
|
|
|
|
```json
|
|
{
|
|
"name": "Paweł",
|
|
"device_id": "gree-aabbccddeeff",
|
|
"enabled": true,
|
|
"mode": "cool",
|
|
"inherit_house_mode": true,
|
|
"setpoint": 23.0,
|
|
"cool_comfort_setpoint": 23.0,
|
|
"cool_sleep_setpoint": 24.5,
|
|
"cool_away_setpoint": 27.0,
|
|
"heat_comfort_setpoint": 21.0,
|
|
"heat_sleep_setpoint": 19.0,
|
|
"heat_away_setpoint": 17.0,
|
|
"hysteresis": 0.6,
|
|
"min_adjust_seconds": 120,
|
|
"standby_offset_c": 2.0,
|
|
"smart_fan": true,
|
|
"sensor_source": "combined",
|
|
"ha_entity_id": "sensor.pawel_temperature",
|
|
"external_sensor_weight": 0.4,
|
|
"max_sensor_difference": 3.0
|
|
}
|
|
```
|
|
|
|
Quick control does not directly fight the schedule engine:
|
|
|
|
```bash
|
|
# Sleep now until the next schedule boundary
|
|
curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
|
|
-d '{"preset":"sleep"}'
|
|
|
|
# Return to automatic schedule
|
|
curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
|
|
-d '{"preset":"auto"}'
|
|
|
|
# Temporary custom room target
|
|
curl -X POST "$BASE/api/zones/ZONE_ID/control" -H "$AUTH" -H 'Content-Type: application/json' \
|
|
-d '{"setpoint":22.5}'
|
|
```
|
|
|
|
`mode` on the quick zone endpoint accepts `house`, `cool`, or `heat`. Global `off` always wins over local zone mode overrides.
|
|
|
|
### Ready-made schedule templates
|
|
|
|
Templates generate normal schedule records and replace the current schedules for the selected zone. Every generated entry remains editable.
|
|
|
|
```bash
|
|
curl -X POST "$BASE/api/zones/ZONE_ID/schedule-template" -H "$AUTH" -H 'Content-Type: application/json' \
|
|
-d '{"template":"child"}'
|
|
```
|
|
|
|
Templates: `family`, `child`, `bedroom`, `workday`, `always`.
|
|
|
|
Schedules use a profile (`comfort`, `sleep`, `away`) or a custom temperature:
|
|
|
|
```json
|
|
{
|
|
"zone_id": "UUID",
|
|
"name": "Sleep",
|
|
"enabled": true,
|
|
"weekdays": [1,2,3,4,5,6,7],
|
|
"start_time": "20:30",
|
|
"end_time": "06:30",
|
|
"preset": "sleep",
|
|
"setpoint": 24.0
|
|
}
|
|
```
|
|
|
|
For non-`custom` schedules, `setpoint` is only a compatibility value; the actual target comes from the zone's seasonal profile.
|
|
|
|
### Home Assistant outdoor assist and local HTTPS
|
|
|
|
Runtime settings can specify `home_assistant.outdoor_entity_id` and `outdoor_assist_enabled`. Outdoor temperature never replaces the zone room temperature. It is only used to make active setpoints/fan speed slightly more assertive in extreme weather.
|
|
|
|
For trusted local Home Assistant servers with self-signed/invalid HTTPS certificates, set:
|
|
|
|
```json
|
|
{
|
|
"home_assistant": {
|
|
"url": "https://10.87.65.2",
|
|
"allow_invalid_tls": true
|
|
}
|
|
}
|
|
```
|
|
|
|
This setting is opt-in and applies only to the controller's outbound Home Assistant sensor client.
|
|
|
|
## 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.
|