gru/gree-controller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.15.6

Browse Source
This commit is contained in:
Mateusz Gruszczyński
2026-09-18 11:21:48 +02:00
parent 3ffb02595e
commit 8d96ad2d38
29 changed files with 758 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+46 -17
View File
@@ -1,6 +1,6 @@
# GREE Controller API reference
HTTP and WebSocket API for GREE Controller **0.15.4**.
HTTP and WebSocket API for GREE Controller **0.15.6**.
[← Main documentation](../README.md)
@@ -132,7 +132,8 @@ Common statuses:
| Method | Endpoint | Description |
| --- | --- | --- |
| POST | `/api/discovery` | Discover/bind GREE devices. |
| POST | `/api/discovery/scan` | Scan for local GREE devices without adding them. |
| POST | `/api/discovery/add` | Add and bind selected scan results. |
| GET | `/api/devices` | List devices. |
| POST | `/api/devices` | Add a device manually. |
| GET | `/api/devices/{id}` | Read a device. |
@@ -240,7 +241,7 @@ Response:
{
"status": "ok",
"name": "gree-controller",
"version": "0.15.4",
"version": "0.15.6",
"uptime_seconds": 1234,
"control_ready": true,
"time": "2026-08-30T06:54:00Z"
@@ -303,7 +304,7 @@ Returns the initial Web UI snapshot:
"control_plan": {"generated_at": "2026-09-04T08:00:00Z", "zones": [], "rules": []},
"control_plan_revision": 42,
"system": {
"version": "0.15.4",
"version": "0.15.6",
"uptime_seconds": 1234,
"auth_required": false,
"control_ready": true,
@@ -374,9 +375,9 @@ A device response contains:
| `communication_failures` | integer | Consecutive/recorded communication failure counter. |
| `created_at`, `updated_at` | ISO-8601 | Resource timestamps. |
### `POST /api/discovery`
### `POST /api/discovery/scan`
Request body, all fields optional:
Scans without adding or binding anything. Request body fields are optional:
```json
{
@@ -387,23 +388,51 @@ Request body, all fields optional:
}
```
Rules:
`protocol_version` accepts `0` (auto/both), `1` (AES-ECB only) or `2` (AES-GCM only). Explicit V1/V2 selection rejects replies from the other protocol generation before decryption. The UDP scan packet itself is common to both generations.
- `timeout_ms`: effective range `500..30000` ms.
- `protocol_version`: `0` auto/both, `1` AES-ECB only, `2` AES-GCM only.
- `passes`: `1..10`.
- Missing values use runtime GREE settings.
Successful discovery merges known devices, tries binding devices that do not have a key, persists results and returns:
The response contains candidates with MAC, IP, detected protocol and an `already_added` flag:
```json
{
"count": 1,
"devices": [],
"new_device_ids": ["gree-aabbccddeeff"]
"devices": [
{
"name": "GREE EEFF",
"mac": "AABBCCDDEEFF",
"ip": "192.168.50.30",
"port": 7000,
"protocol_version": 1,
"model": "GREE",
"firmware": "",
"already_added": false
}
]
}
```
### `POST /api/discovery/add`
Add only selected candidates returned by `/api/discovery/scan`:
```json
{
"devices": [
{
"name": "Living room",
"mac": "AABBCCDDEEFF",
"ip": "192.168.50.30",
"port": 7000,
"protocol_version": 1,
"model": "GREE",
"firmware": "",
"already_added": false
}
]
}
```
Each selected candidate is bound strictly with its detected `protocol_version`. Existing MAC addresses are skipped.
### `GET /api/devices`
Returns `Device[]`.
@@ -1599,10 +1628,10 @@ BASE='http://127.0.0.1:8787'
AUTH='Authorization: Bearer APP_TOKEN'
```
Discover devices:
Scan local devices:
```bash
curl -X POST "$BASE/api/discovery" -H "$AUTH" -H 'Content-Type: application/json' \
curl -X POST "$BASE/api/discovery/scan" -H "$AUTH" -H 'Content-Type: application/json' \
-d '{"protocol_version":0,"passes":3}'
```