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,78 @@
+# Sensors & Field Mapping
+
+## Основные поля (live data)
+
+Эти поля публикуются в `{UID}/data-timescale/{FIELD}` и доступны через `/api/box/{id}/live/`.
+
+| API поле | MQTT имена (синонимы) | Единица | Описание |
+|----------|----------------------|---------|----------|
+| `ph` | `ph`, `wpH`, `pH` | 0–14 | pH раствора (откалиброванный) |
+| `ec` | `ec`, `wEC`, `EC` | мСм/см | EC раствора (откалиброванный) |
+| `tankTemp` | `temp_cal`, `wNTC`, `waterTemp` | °C | Температура воды (NTC, откалиброванная) |
+| `rootTemp` | `rootTemp`, `RootTemp` | °C | Температура субстрата (DS18B20) |
+| `airTemp` | `airTemp`, `AirTemp` | °C | Температура воздуха (BME280) |
+| `airHumidity` | `airHumidity`, `AirHum` | % | Влажность воздуха (BME280) |
+| `waterLevel` | `calc_dist`, `Dist`, `wLevel` | % или см | Уровень воды (HC-SR04) |
+| `light` | `calc_pr`, `PR` | % | Освещённость (фоторезистор) |
+
+## Системные поля
+
+| MQTT поле | Единица | Описание |
+|-----------|---------|----------|
+| `RSSI` | dBm | Уровень WiFi сигнала |
+| `uptime` | мс | Аптайм устройства |
+| `CPUTemp` | °C | Температура процессора ESP32 |
+| `freeHeap` | байт | Свободная RAM |
+| `MixerWeight` | г | Вес в миксере (HX711) |
+| `readGPIO` | 0–65535 | Битовая маска GPIO MCP23017 |
+
+## Сырые / отладочные поля
+
+| MQTT поле | Описание |
+|-----------|----------|
+| `NTC` | Сырое значение АЦП NTC |
+| `pHmV` | pH в милливольтах |
+| `pHraw` | Сырое значение АЦП pH |
+| `ec_no_termo` | EC без температурной компенсации |
+| `AirPress` | Атмосферное давление (гПа) |
+| `Vcc` | Напряжение питания (мВ) |
+| `hall` | Датчик Холла ESP32 |
+| `CO2` | CO2 (ppm) |
+| `tVOC` | Летучие вещества |
+| `PumpA_SUM`, `PumpB_SUM` | Суммарный объём помп |
+
+## Калибровка
+
+### pH
+
+```
+Точки: (px1, py1), (px2, py2), (px3, py3)
+ADC → pH = кусочно-линейная интерполяция
+Корректировка: pH_final = pH + pHlKorr
+```
+
+### EC
+
+```
+Точки калибровки: ec1 (1.41 мСм/см), ec2 (12.88 мСм/см)
+Соответствующие ADC значения: ex1, ex2
+Температурная компенсация: EC_25 = EC_T / (1 + kt * (T - 25))
+Корректировка: ecKorr (множитель, default = 1.0)
+```
+
+### Температура воды (NTC)
+
+```
+Тип: NTC3950 (ntcType)
+B-коэффициент: ntcB = 3950
+R1 = 10000 Ом
+Корректировка: ntcValKorr (offset °C, default = 0.0)
+```
+
+### Уровень воды (HC-SR04)
+
+```
+maxLLevel → maxLRaw (100% → ADC значение)
+minLLevel → minLRaw (0% → ADC значение)
+Линейная интерполяция
+```