init: спецификация протокола WegaBox ↔ ponics.online

MQTT топики, REST API, поведение устройства, маппинг датчиков. Mermaid диаграммы: flow подключения, обработка сообщений, FSM устройства.
2026-05-05 11:42:57 +03:00
commit 6655dd3d7a
5 changed files with 598 additions and 0 deletions
@@ -0,0 +1,156 @@
+# REST API
+
+Base URL: `https://ponics.online/api/box/`
+
+Аутентификация: сессия Django (cookie) или токен.
+
+---
+
+## Эндпоинты
+
+### GET `/api/box/`
+Список боксов текущего пользователя.
+
+**Response:**
+```json
+[
+  {
+    "id": 23,
+    "name": "Бокс №1",
+    "token": "550e8400-e29b-41d4-a716-446655440000",
+    "online": true,
+    "last_seen": "2026-05-03T08:00:00Z"
+  }
+]
+```
+
+---
+
+### GET `/api/box/{id}/`
+Детали бокса с конфигурацией.
+
+---
+
+### GET `/api/box/{id}/live/`
+Живые данные датчиков из Redis-кеша.
+
+**Response:**
+```json
+{
+  "ph": 6.24,
+  "ec": 1.85,
+  "tankTemp": 22.5,
+  "rootTemp": 21.0,
+  "airTemp": 24.1,
+  "airHumidity": 65.0,
+  "waterLevel": 45.2,
+  "light": 80.0,
+  "online": true,
+  "last_seen": "2026-05-03T08:01:23Z"
+}
+```
+
+---
+
+### POST `/api/box/{id}/reboot/`
+Перезагрузка устройства.
+
+**Request:** `{}` (пустой body)
+
+**Response:**
+```json
+{"success": true, "message": "Команда reboot отправлена", "command": "reboot"}
+```
+
+---
+
+### POST `/api/box/{id}/gpio/`
+Управление GPIO (MCP23017).
+
+**Request:**
+```json
+{"pin": 5, "state": true}
+```
+- `pin`: 0–15
+- `state`: `true` (HIGH) / `false` (LOW)
+
+**Response:**
+```json
+{"success": true, "command": "gpio", "pin": 5, "state": true}
+```
+
+---
+
+### POST `/api/box/{id}/pump/run/`
+Запуск помпы на заданное время.
+
+**Request:**
+```json
+{"pump_id": 1, "time_ms": 5000}
+```
+- `pump_id`: 1–8
+- `time_ms`: 1–60000
+
+**Response:**
+```json
+{"success": true, "command": "pump_run", "pump_id": 1, "time_ms": 5000}
+```
+
+---
+
+### POST `/api/box/{id}/pump/dispense/`
+Налить определённое количество граммов.
+
+**Request:**
+```json
+{"pump_id": 2, "grams": 50.5}
+```
+- `pump_id`: 1–8
+- `grams`: 0.1–1000
+
+**Response:**
+```json
+{"success": true, "command": "pump_dispense", "pump_id": 2, "grams": 50.5}
+```
+
+---
+
+### POST `/api/box/{id}/pump/stop/`
+Остановить помпу.
+
+**Request:**
+```json
+{"pump_id": 1}
+```
+- `pump_id`: 1–8
+
+**Response:**
+```json
+{"success": true, "command": "pump_stop", "pump_id": 1}
+```
+
+---
+
+### POST `/api/box/{id}/preferences/`
+Обновить настройки и калибровку устройства.
+
+**Request:** JSON с любыми полями из [MQTT.md → set/preferences/all](MQTT.md#настройки-setpreferencesall)
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Настройки отправлены (3 полей)",
+  "fields": ["ecKorr", "pHlKorr", "ntcValKorr"]
+}
+```
+
+---
+
+## Коды ошибок
+
+| HTTP | Описание |
+|------|----------|
+| 400 | Неверные параметры (pin/pump_id/time вне диапазона) |
+| 503 | MQTT недоступен |
+| 404 | Бокс не найден / нет доступа |