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. Подробнее: Выбор и сборка прошивки.