🧩 Раздел 8

Справочник API

Всё, чем можно поговорить с системой.

Два разных интерфейса

В системе два независимых API.

📟

API устройства

Живёт на микроконтроллере.

http://<ip>/api/v1

🖥️

API сервера

Живёт на VPS.

https://spe4naz.online/api/v1

API устройства

Все ответы — обычный JSON.

Метод и путь Что возвращает
GET / Подсказка о доступности API
GET /sensors Текущие значения метрик
GET /modules Список модулей
GET /status Состояние системы
GET /data Состояние, показания и модули
GET /sd/info Информация о карте
GET /sensors/history История показаний
GET /logs Журнал событий
POST /command Команда устройству

Показания

GET /api/v1/sensors
{
  "timestamp": 128374,
  "modules": {
    "BME680_0x76": {
      "temperature": 21.40,
      "humidity": 44.20,
      "pressure": 1013.10,
      "gas_resistance": 41200.00
    }
  }
}

Состояние

GET /api/v1/status
{
  "type": "status_update",
  "device_id": "esp32c3_001",
  "device_name": "Main Controller",
  "device_type": "esp32c3",
  "uptime": 128374,
  "free_heap": 214000,
  "wifi_connected": true,
  "ip": "192.168.1.50",
  "time_synced": true,
  "rssi": -58,
  "chip_temp": 42.3,
  "firmware": "1.3.6",
  "led": "online",
  "sd": {
    "status": "ok",
    "mounted": true,
    "card_detected": true,
    "type": "SDHC",
    "total_bytes": 62494670848,
    "used_bytes": 5120000000,
    "free_bytes": 57374670848,
    "used_pct": 8
  }
}

Поле led показывает состояние индикатора.

Карта памяти

GET /api/v1/sd/info

Статус, свободное место и процент заполнения.

{
  "status": "ok",
  "mounted": true,
  "card_detected": true,
  "type": "SDHC",
  "total_bytes": 62494670848,
  "used_bytes": 5120000000,
  "free_bytes": 57374670848,
  "used_pct": 8
}

Тот же блок есть в /status.

Всё сразу

GET /api/v1/data

Один запрос вместо трёх.

{
  "ok": true,
  "status": { "device_id": "esp32c6_001", "firmware": "1.3.6", "ip": "192.168.1.50" },
  "sensors": { "timestamp": 128374, "modules": { "BME680_0x76": { "temperature": 21.4 } } },
  "modules": [ { "id": "BME680_0x76", "driver": "BME680" } ]
}

Поиск в локальной сети

Устройство отвечает на UDP-запрос и по mDNS.

$ echo -n AERIS_DISCOVER_V1 | nc -u -b 192.168.1.255 8266
{"id":"esp32c6_001","name":"Main Controller C6","type":"esp32c6",
 "fw":"1.3.6","ip":"192.168.1.50","port":80,"uptime":128}

Приложение находит устройство само.

История

Параметр По умолчанию Смысл
type любой Ключ метрики
since 0 Отбор по времени
limit 1000 Сколько точек

История читается с SD-карты.

🔢

За просмотр не больше 4096 строк.

Команды устройству

; по MQTT в топик iot/<id>/commands; либо по USB строкой CMD:команда. Не все команды доступны везде — колонка «Транспорт» показывает, где именно." data-en-html="A command can be sent three ways: with POST to /api/v1/command and a JSON body that must contain command; over WebSocket as {"type":"command","command":"..."}; over MQTT to iot/<id>/commands; or over USB as CMD:command. Not every command is available everywhere — the “Transport” column shows where.">Команда отправляется по HTTP, MQTT или USB.

Команда Поля Действие Транспорт
restart — Перезагрузка HTTP/WS · MQTT · USB
read_sensor — Форс-чтение HTTP/WS · MQTT
rescan — Пересканировать шину HTTP/WS · MQTT
mqtt_enable
mqtt_disable
— Включить или выключить MQTT HTTP/WS · MQTT · USB
ota force Обновление по воздуху HTTP/WS · MQTT · USB
ota_rollback — Откат прошивки HTTP/WS · MQTT · USB
relay
relay:on|off|toggle
state Управление реле HTTP/WS · MQTT
wifi_set ssid
password
Сменить сеть HTTP/WS · MQTT · USB
wifi_clear — Сбросить сеть USB
wifi_reconfigure — Перенастроить сеть MQTT
curl -X POST http://192.168.1.50/api/v1/command \
     -H 'Content-Type: application/json' \
     -d '{"command":"ota","force":true}'

Ошибки команд возвращаются с машинным кодом.

WebSocket устройства

Тот же порт, путь /ws.

Направление Тип Когда приходит
Устройство → клиент status_update При подключении
Устройство → клиент modules_update При подключении и после rescan
Устройство → клиент sensor_update Каждый цикл чтения
Устройство → клиент logs При подключении
Устройство → клиент history В ответ на запрос
Устройство → клиент ack Подтверждение команды
Устройство → клиент error Ошибка команды
Клиент → устройство request_sensors
request_status
request_history
request_logs
command
Запрос состояния или команда
📏

Кадры длиннее 2 КБ отбрасываются.

API сигнального сервера

Тот же префикс, другой адрес.

Метод и путь Доступ Назначение
GET /health публично Состояние сервера
GET /meta публично Параметры сервера
GET /stream app / панель Живой поток
GET /sensors/latest app / панель Последние значения
GET /sensors/:device/:sensor/history app / панель История метрики
POST /devices/register device Регистрация устройства
POST /devices/heartbeat device Подтверждение присутствия
GET /devices app / панель Список устройств
GET /devices/:id app / панель Карточка устройства
PUT/PATCH /devices/:id app Переименовать устройство
DELETE /devices/:id app / панель Удаление устройства
POST /devices/:id/command app / панель Команда устройству
GET /alerts app / панель Список аварий
POST /alerts app / панель Создание аварии
PUT /alerts/:id app / панель Изменение аварии
DELETE /alerts/:id app / панель Удаление аварии
GET /rules app / панель Список правил
POST /rules app / панель Создание правила
PUT /rules/:id app / панель Изменение правила
DELETE /rules/:id app / панель Удаление правила

Тело запроса регистрации

POST /api/v1/devices/register
Authorization: Basic base64(MQTT_DEVICE_USER:<пароль>)
Content-Type: application/json

{
  "id": "esp32c3_001",
  "name": "Main Controller",
  "type": "esp32c3",
  "ip": "192.168.1.50",
  "port": 80,
  "sensors": ["temperature", "humidity", "co2"]
}

Обязательны только идентификатор и адрес.

Тело запроса аварии

POST /api/v1/alerts
{
  "device_id": "esp32c3_001",
  "sensor_type": "temperature",
  "type": "above",
  "threshold": 27.5
}

Тело запроса правила

POST /api/v1/rules
{
  "name": "Уведомить о жаре",
  "device_id": "esp32c3_001",
  "trigger": "threshold_above",
  "sensor_type": "temperature",
  "threshold": 27.5,
  "action": "notify",
  "cooldown_seconds": 300
}

Веб-панель

Панель включается паролем.

Метод и путь Назначение
POST /panel/api/auth/login Вход в панель
POST /panel/api/auth/logout Выход
GET /panel/api/session Статус сессии
GET /panel/api/system Сводка сервера
GET /panel/api/system/history Графики сервера
GET/POST /panel/api/devices Устройства
GET/PUT/DELETE /panel/api/devices/:id Операции с устройством
GET/PUT /panel/api/settings Настройки
POST /panel/api/restart Перезапуск сервера

Коды ответа и ошибки

Код Когда Поле error
401 Требуется авторизация unauthorized
404 Запись не найдена not_found
not_registered
400 Некорректный запрос invalid_json
missing_id
missing_ip
invalid_device
invalid_alert
invalid_rule
bad_alert_id
bad_device_id
bad_rule_id
429 Превышен лимит rate_limited
too_many_devices_from_ip
500 Внутренняя ошибка internal_error

. Сервер отвечает 503 mqtt_off, если команда отправлена, а MQTT-мост выключен." data-en-html="The device also answers 400 for an unknown command or a bad relay state, 409 for a busy command, 500 for a failed rollback, 405 for a wrong method and 404 for an unknown path — the last one always with the body {"error":"not_found"}. The server answers 503 mqtt_off when a command is sent while the MQTT bridge is off.">Устройство отвечает и кодами 400, 409 и 500.

🛡️

Ошибки всегда в одном формате.

Топики MQTT

Топик строится из префикса и идентификатора.

Топик Направление Содержимое
iot/<id>/sensors/<ключ> устройство → подписчик Одно значение
iot/<id>/status устройство → подписчик Состояние
iot/<id>/relay устройство → подписчик Состояние реле
iot/<id>/commands подписчик → устройство Команда устройству
iot/esp32c3_001/sensors/temperature
{
  "device_id": "esp32c3_001",
  "sensor": "temperature",
  "timestamp": 1735689600000,
  "value": 21.40,
  "unit": "C"
}

Публикация только при изменении.

🚦

До синхронизации времени метки неверны.

Формат CSV на карте

Одна строка — четыре поля.

метка_времени,ключ_метрики,значение,единица
1735689600000,temperature,21.40,C
1735689600000,humidity,44.20,%
1735689600000,co2,612.00,ppm

Файл один на сутки.

🗑️

Хранятся последние 60 файлов.

Манифест прошивки

Обновление приходит по HTTPS.

GET /fw/version-esp32-c6.json

{
  "version": "1.3.6",
  "device_type": "esp32-c6",
  "build_date": "2026-11-17T18:54:12Z",
  "sha256": "457d937a…b8845b",
  "size": 1534400,
  "file": "main_esp32-c6.bin"
}

Поле size нужно для надёжной загрузки.

Готовые примеры

Показать текущую температуру

curl -s http://192.168.1.50/api/v1/sensors \
  | grep -o '"temperature":[0-9.]*'

Подписаться на поток значений

mosquitto_sub -h spe4naz.online -p 1883 \
  -t 'iot/+/sensors/temperature' -v

Проверить состояние сервера

curl -s https://spe4naz.online/api/v1/health
{
  "ok": true,
  "version": "0.4.1",
  "uptime": 928371.4,
  "devices": { "total": 1, "online": 1, "offline": 0 },
  "alerts": 0,
  "rules": 0
}