From f306a02b2b85b9e4dababd40856ff996018236ae Mon Sep 17 00:00:00 2001
From: progl <progl@progl.su>
Date: Thu, 7 May 2026 16:44:28 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BA=D1=80=D0=B8=D1=82=D0=B8=D1=87?=
 =?UTF-8?q?=D0=B5=D1=81=D0=BA=D0=B8=D0=B5=20=D1=83=D1=82=D0=BE=D1=87=D0=BD?=
 =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D1=8F=20=D0=BF=D0=BE=20status=3Dconnected=20?=
 =?UTF-8?q?=D0=B8=20=D1=82=D0=B8=D0=BF=D0=B8=D1=87=D0=BD=D1=8B=D0=B5=20?=
 =?UTF-8?q?=D0=BE=D1=88=D0=B8=D0=B1=D0=BA=D0=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DEVICE_BEHAVIOR.md | 27 +++++++++++++++++++++++++++
 MQTT.md            |  5 +++++
 2 files changed, 32 insertions(+)

diff --git a/DEVICE_BEHAVIOR.md b/DEVICE_BEHAVIOR.md
index c7950f1..3016f25 100644
--- a/DEVICE_BEHAVIOR.md
+++ b/DEVICE_BEHAVIOR.md
@@ -108,6 +108,33 @@ stateDiagram-v2
 - MQTT: экспоненциальный backoff (1s → 2s → 4s → ... → max 60s)
 - При восстановлении: публикует `{UID}/status = "connected"` → сервер снова шлёт preferences
 
+> **Важно**: Публикация `status = "connected"` должна происходить в колбэке подключения MQTT,  
+> а не только при первом старте. Иначе после реконнекта устройство не получит настройки с сервера.
+
+---
+
+## Типичные ошибки реализации
+
+### 1. Неверный payload в `{UID}/status`
+```
+❌ "online", "Online", "connected\n", "1"
+✅ "connected"
+```
+Сервер проверяет точное совпадение байт. Неверный payload → `push_box_settings` не вызывается →  
+устройство работает без калибровок из БД до следующей перезагрузки.
+
+### 2. `status` публикуется только при первом старте
+При реконнекте MQTT (после обрыва WiFi, перезапуска брокера) нужно снова опубликовать  
+`{UID}/status = "connected"`. Иначе после восстановления связи настройки не придут.
+
+### 3. Pump ID отсчёт
+API использует 1-based индексацию (1–8). Прошивка внутренне хранит 0-based, но  
+MQTT-команды и HTTP API принимают 1-based. Проверять валидацию: `id ∈ [1, 8]`.
+
+### 4. HTTP API требует `Accept: application/json`
+При обращении к ponics.online API без этого заголовка сервер может вернуть 302 (редирект  
+на страницу логина) вместо JSON. Клиенты должны явно указывать `Accept: application/json`.
+
 ---
 
 ## Home Assistant интеграция (отдельный канал)
diff --git a/MQTT.md b/MQTT.md
index ea6b441..54aab77 100644
--- a/MQTT.md
+++ b/MQTT.md
@@ -92,6 +92,11 @@ sequenceDiagram
 Payload: строка `"connected"` — устройство подключилось к брокеру.  
 Триггер: сервер отправляет настройки (`set/preferences/all`).
 
+> ⚠️ **КРИТИЧНО**: Payload должен быть **точно** `"connected"` (строчные буквы, без пробелов/null).  
+> Любое другое значение (`"online"`, `"Connected"`, `"1"`) **не вызовет** `push_box_settings`.  
+> Публиковать нужно **при каждом подключении к брокеру** (первый старт + реконнект после обрыва).  
+> Источник: `message_processor.py` → `if msg.payload == b"connected": push_box_settings(box)`
+
 ### `{UID}/status/sensors`
 
 Ответ на `{UID}/cmd/status/sensors`. Поля зависят от подключённых датчиков.