Справочник 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
}