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

MQTT топики, REST API, поведение устройства, маппинг датчиков.
Mermaid диаграммы: flow подключения, обработка сообщений, FSM устройства.

README.md

@@ -0,0 +1,37 @@
+# ponics-protocol
+
+Единый источник истины для коммуникации между **ponics.online** (сервер) и **WegaBox** (ESP32 устройство).
+
+## Репозитории
+
+| Репо | Описание |
+|------|----------|
+| [web-calc](https://gitea.progl.su/progl/web-calc) | Django backend + frontend (ponics.online) |
+| [wega-box](https://gitea.progl.su/progl/wega-box) | Прошивка ESP32 |
+| **ponics-protocol** (этот репо) | Спецификация протокола |
+
+## Документация
+
+- [MQTT.md](MQTT.md) — Топики, payload схемы, flow диаграммы
+- [REST_API.md](REST_API.md) — HTTP API эндпоинты
+- [DEVICE_BEHAVIOR.md](DEVICE_BEHAVIOR.md) — Конечный автомат устройства
+- [SENSORS.md](SENSORS.md) — Поля датчиков, маппинг имён
+
+## Быстрый старт
+
+```
+Device UID = token устройства (UUID формат)
+MQTT Broker = ponics.online:1883
+Аутентификация = username/password (в настройках устройства)
+```
+
+### Ключевые топики
+
+```
+{UID}/data-timescale/{METRIC}  ← устройство шлёт данные датчиков
+{UID}/status                   ← устройство шлёт "connected"
+{UID}/cmd/reboot               → сервер перезагружает устройство
+{UID}/set/pump/{id}/run        → сервер запускает помпу (мс)
+{UID}/set/pump/{id}/dispense   → сервер наливает граммы
+{UID}/set/preferences/all      → сервер синхронизирует настройки
+```