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,101 @@
+# Device Behavior
+
+## Конечный автомат устройства
+
+```mermaid
+stateDiagram-v2
+    [*] --> Booting: Включение питания
+    Booting --> WiFiConnect: Инициализация
+    WiFiConnect --> MQTTConnect: WiFi OK
+    WiFiConnect --> WiFiConnect: Retry (30s)
+    MQTTConnect --> Connected: MQTT OK
+    MQTTConnect --> MQTTConnect: Retry (10s)
+
+    Connected --> Publishing: Таймер сбора данных
+    Publishing --> Connected: Данные отправлены
+
+    Connected --> ExecutingCmd: Получена команда
+    ExecutingCmd --> Connected: Команда выполнена
+
+    Connected --> Disconnected: Потеря связи
+    Disconnected --> MQTTConnect: Reconnect
+
+    Connected --> [*]: Команда reboot / WDT reset
+```
+
+---
+
+## Последовательность запуска
+
+1. **Boot** — инициализация I2C, SPI, OneWire периферии
+2. **WiFi** — подключение, получение IP
+3. **MQTT connect** — handshake с брокером
+4. **Publish `{UID}/status = "connected"`** — уведомление сервера
+5. **Получить preferences** — сервер отвечает `{UID}/set/preferences/all`
+6. **Применить калибровку** — записать коэффициенты в память
+7. **Запуск основного цикла** — периодический сбор и публикация данных
+
+---
+
+## Периодичность публикации данных
+
+| Датчик | Интервал |
+|--------|----------|
+| pH, EC, Temp | ~10 сек |
+| AirTemp, AirHum | ~30 сек |
+| RSSI, uptime | ~60 сек |
+| MixerWeight | ~5 сек (если mixer_enabled) |
+| readGPIO | при изменении |
+
+---
+
+## Обработка команд
+
+Все команды **fire-and-forget** — ответ не отправляется.
+
+### `cmd/reboot`
+1. Завершить активные операции помп (стоп)
+2. `ESP.restart()`
+
+### `cmd/gpio/{pin}`
+1. Проверить pin ∈ [0, 15]
+2. MCP23017 → setPin(pin, state)
+
+### `set/pump/{id}/run`
+1. Проверить id ∈ [1, 8], time ∈ [1, 60000]
+2. Включить помпу
+3. Запустить таймер
+4. По истечении времени — выключить
+
+### `set/pump/{id}/dispense`
+1. Проверить id ∈ [1, 8], grams ∈ [0.1, 1000]
+2. Рассчитать время через `ml/sec` калибровку помпы
+3. Включить → таймер → выключить
+4. Обновить счётчик `total_dispensed`
+
+### `cmd/pump/{id}/stop`
+1. Немедленно выключить помпу
+2. Сбросить таймер
+
+### `set/preferences/all`
+1. Разобрать JSON
+2. Обновить только пришедшие поля в NVS / RAM
+3. Применить новые коэффициенты калибровки без перезагрузки
+
+---
+
+## Reconnect логика
+
+- WiFi: авто-реконнект встроенный в ESP-IDF
+- MQTT: переподключение каждые 10 секунд
+- При восстановлении MQTT: снова публикует `{UID}/status = "connected"`
+- Сервер снова отправляет preferences (идемпотентно)
+
+---
+
+## OTA обновления
+
+URL прошивки: `preferences.updateUrl`  
+По умолчанию: `https://ponics.online/static/wegabox/esp32-local/firmware.bin`
+
+Триггер обновления: команда (TBD) или автоматически при запуске если новая версия.