Skip to content

API

У платы и облака разные адреса, пользователи и ключи. Пользовательский Bearer для локальной платы не подходит облаку; ключ heartbeat платы не является токеном входа пользователя.

Плата

Базовый адрес — http://<ip-платы>/api/v1. Вход:

curl -X POST http://<ip-платы>/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"1234"}'

Используйте access_token как Authorization: Bearer <token>. Обычный токен живёт один час, remember=true — 30 дней. Примеры запросов: API-рецепты.

Ресурс Путь относительно /api/v1
Версия, возможности и лимиты /system/info
Устройства /devices
Задачи /tasks
Плагины /sensors, /triggers, /conditions, /actions
Сеть /network
Облако /cloud, /cloud/status
Лог в RAM /log
Резервирование, если включён модуль /backup
OTA одного файла /ota

Доступность модулей и плагинов зависит от сборки. Лимиты задач — в /system/info → tasks; не фиксируйте их на стороне клиента по старой версии.

Облако

Кабинет и пользовательское API работают через https://cloud.kavlev.ru. Вход по email-коду выдаёт пользовательские access/refresh токены. Точные схемы и пути текущей версии доступны в Swagger и OpenAPI JSON.

Назначение Путь
Авторизация /api/v1/auth/...
Проекты /api/v1/projects
Платы проекта /api/v1/projects/{pid}/devices
Группы и их состав /api/v1/projects/{pid}/groups/...
Участники и приглашения /api/v1/projects/{pid}/members, /invites
Интеграции пользователя /api/v1/integrations/...
Прошивки и конструктор /api/v1/firmwares/...

При регистрации платы облако выдаёт api_key именно этой платы. Он используется как секрет HMAC, а не открытый ключ проекта для всех устройств.

Heartbeat

Плата обращается к API для устройств http://cloud.kavlev.ru:8081: POST /api/v1/devices/{uuid}/heartbeat. Заголовки:

Заголовок Значение
X-Device-Uuid UUID платы
X-Device-Ts Unix timestamp в секундах
X-Device-Sig Подпись запроса в lowercase hex

Подписываются точные байты тела, а не повторно сериализованный объект:

body_hash = sha256(raw_body).hexdigest()
message = f"{method.upper()}\n{path_with_query}\n{timestamp}\n{body_hash}".encode()
signature = hmac_sha256(device_api_key, message).hexdigest()

Сервер проверяет окно timestamp ±60 секунд. Тело содержит версию, IP, uptime, интервал, state.devices, краткий список задач и applied_command_ids. Новая прошивка также передаёт случайный response_nonce из 32 hex-символов.

Ответ содержит server_ts и pending_commands. Заголовок X-Cloud-Response-Sig проверяется новой прошивкой до применения команд:

response_hash = sha256(raw_response_body).hexdigest()
message = f"heartbeat-response-v1\n{request_signature}\n{response_hash}".encode()
response_signature = hmac_sha256(device_api_key, message).hexdigest()

Nonce входит в подпись запроса и связывает ответ с текущим обменом. Ответ без корректной подписи новая прошивка отклоняет. При выпуске сначала обновляют облако, потом плату; старые прошивки игнорируют заголовок и отдельно требуют обновления. HMAC даёт подлинность/целостность, но HTTP не шифруется.

Команды и границы гарантий

set_relay принимает {device_id, state} для конкретного реле. Команды всей платы требуют прав администратора. OTA-команды несут адрес образа, размер и SHA256; формат определяет API текущего облака, это не универсальный {firmware_id}.

Успешная постановка команды в очередь не означает выполнения. Плата подтверждает команды последующим heartbeat; проверяйте state и фактическое состояние нагрузки. Дедупликация на плате хранится в runtime и не гарантирует идемпотентность после перезагрузки. При потере heartbeat-ответа polling-команда может не дойти до платы; автоматическое повторение не гарантирует однократного выполнения.

Запись файлов использует временные файлы и переименование, но это не гарантия сохранности при любом обрыве питания. Не заменяйте этим резервную копию.

Метаданные плагинов

Категории /sensors, /triggers, /conditions, /actions возвращают plugins с именем, предоставляемыми типами и UI manifest (ui_raw). Точный набор и поля зависят от категории и сборки. UI не должен предлагать плагин, отсутствующий в этом ответе. Структура manifest: архитектура плагинов.

Каталог конструктора — отдельный GET /api/v1/firmwares/build/catalog в облаке. Он описывает возможности исходников, из которых ещё предстоит собрать вариант, и включает SHA. Подробнее: Выбор и сборка прошивки.