Спецификация REST API для устройств умного дома на ESP

Общие положения

Транспорт: HTTP, формат данных — JSON.
Архитектура: Каждый тип устройства реализует базовые эндпоинты /about, /status, /action.
Режимы работы устройства:
- setup — устройство ожидает настройки (доступны /setup, /about, /set_token без авторизации).
- normal — устройство работает в штатном режиме (требуется токен).
- error, updating — для расширения.
Безопасность: Все запросы (кроме /about, /setup в режиме setup, /set_token в режиме setup) требуют передачи токена авторизации.

Авторизация

Для всех эндпоинтов, кроме GET /about, GET/POST /setup (в режиме setup) и POST /set_token (в режиме setup), в запросах должен присутствовать заголовок:
```
Authorization: Bearer <token>
```
Без валидного токена устройство должно возвращать ошибку 401 Unauthorized.

Пример ответа при отсутствии или неверном токене

{
  "status": "error",
  "error": "Unauthorized",
  "message": "Missing or invalid token"
}

Эндпоинты

1. `GET /about`

Отдаёт базовую информацию об устройстве.

Доступно всегда. Токен не требуется.

Пример ответа

{
  "device_name": "Relay 1",
  "device_type": "relay",
  "firmware_version": "1.0.3",
  "device_id": "ecf0a1b5c9d74f9a8e294c1f67b0a8b9",
  "server": "http://192.168.1.10",
  "status": "normal",              // normal | setup | error | updating
  "ip_address": "192.168.1.42",
  "mac_address": "A4:CF:12:9B:3F:D2",
  "uptime": 123456                 // в секундах
}

2. `GET /status`

Отдаёт текущее состояние устройства.
В режиме normal требует заголовок Authorization с валидным токеном!
В режиме setup может быть недоступен или возвращать ограниченную информацию.

Пример для реле

{
  "state": "on"
}

Пример для температурного датчика

{
  "temperature_c": 21.8,
  "humidity_percent": 45.3,
  "battery_level": 93
}

3. `POST /action`

Позволяет управлять устройством.
В режиме normal требует заголовок Authorization с валидным токеном!
В режиме setup эндпоинт недоступен.

Пример запроса для реле

{
  "action": "set_state",
  "params": {
    "state": "off"
  }
}

Пример ответа

{
  "status": "ok",
  "message": "State changed"
}

Пример ошибки

{
  "status": "error",
  "error": "IllegalActionOrParams",
  "message": "Device does not support this action or params"
}

4. `POST /set_token`

Используется для первичной инициализации устройства (в режиме setup) и для смены токена по инициативе сервера (в режиме normal).

В режиме setup: доступен без токена — сервер устанавливает токен впервые, переводит устройство в режим normal.
В режиме normal: требует заголовок Authorization с валидным токеном! — смена токена доступна только авторизованному серверу.

Важно! При установке токена устройство запоминает ip сервера и в дальнейшем может принимать авторизованные действия лишь с этого адреса.

Пример запроса

{
  "token": "QmFzZVRva2VuU2FtcGxlMTIz"
}

Пример ответа (при успешной установке токена)

{
  "status": "ok",
  "message": "Token set. Device mode: normal"
}

Пример ошибки, если устройство уже в normal-режиме и попытка установки без токена

{
  "status": "error",
  "error": "Unauthorized",
  "message": "Missing or invalid token"
}

Пример ошибки, если устройство уже provisioned (уже переведено в normal и повторно в setup режим попасть нельзя)

{
  "status": "error",
  "error": "AlreadyProvisioned",
  "message": "Device already provisioned"
}

5. `GET /setup` и `POST /setup`

Доступно только в режиме setup.
Позволяет настроить подключение к Wi-Fi через веб-интерфейс.

Описание:

Эндпоинт /setup доступен только, пока устройство находится в статусе setup (до получения токена).
При обращении через браузер на /setup открывается веб-панель для ввода параметров Wi-Fi (SSID, пароль).
После успешной настройки и подключения к сети устройство переходит к процедуре ожидания установки токена (/set_token).
После перехода в статус normal эндпоинт /setup становится недоступен (возвращает ошибку или заглушку).

Пример запроса (POST /setup):

{
  "ssid": "Home_WiFi",
  "password": "MySecretPass"
}

Пример ответа:

{
  "status": "ok",
  "message": "Wi-Fi configured. Connecting..."
}

Пример ошибки при попытке доступа к `/setup` вне режима `setup`:

{
  "status": "error",
  "error": "NotAvailable",
  "message": "Setup mode is not active"
}

6. `POST /reboot`

Физическая перезагрузка устройства.
Доступно только в режиме normal. Требует заголовок Authorization с валидным токеном!

Пример ответа

{
  "status": "ok",
  "message": "Device will reboot now"
}

7. `POST /reset`

Сброс всех настроек к заводским, переход в режим setup.
Доступно только в режиме normal. Требует заголовок Authorization с валидным токеном!

Пример запроса

{}

Пример ответа

{
  "status": "ok",
  "message": "Device reset to factory settings. Entering setup mode."
}

7. `POST /set_device_name`

Установка нового имени девайса. Максимум 32 байта. Доступно только в режиме normal. Требует заголовок Authorization с валидным токеном!

Пример запроса

{"device_name": "Relay Name"}

Пример ответа

{
  "status": "ok",
  "message": "Device name updated"
}

`GET /channels_schema`

Возвращает текущую конфигурацию каналов. Это содержимое из памяти устройства, оно делиться по 4 байта на канал. Байты отвечают за:

1. GPIO пин канала
1. GPIO пин индикатора (LED), или номер светодиода, если используется адресная LED лента
1. GPIO пин обратной связи
1. Резервный байт общего назначения, например для реле это флаг инвертирования канала. А для кнопок этот байт не используйется.

Доступ:

В режиме normal требует Authorization.
В режиме setup доступен без токена.
В режимах error и updating может быть недоступен.

Пример ответа

  {
    "status": "ok",
    "schema": [
      4,255,255,1,
      5,255,255,0,
      255,255,255,0,
      255,255,255,0,
      255,255,255,0,
      255,255,255,0,
      255,255,255,0,
      255,255,255,0
    ]
  }

Пояснение примера:

Канал 0:

pin = 4
indicator = 255 (не используется)
feedback = 255 (не используется)
flags = 1 (инвертирован) Канал 1:
pin = 5
flags = 0 (обычный) Остальные каналы не задействованы (255 = SH_PIN_UNUSED)

9. `POST /set_channels_schema`

Позволяет задать конфигурацию всех каналов целиком. При удачном обновлении будет совершена перезагрузка устройства.

Доступ:

В режиме setup — без токена.
В режиме normal — с Authorization.
В режимах error, updating — недоступен.

Пример запроса

  {
    "schema": [
      4,255,255,1,
      5,255,255,0,
      6,255,255,0,
      7,255,255,0,
      255,255,255,0,
      255,255,255,0,
      255,255,255,0,
      255,255,255,0
    ]
  }

Пример ответа

  {
    "status": "ok",
    "message": "Channels schema updated"
  }

Спецификация REST API для устройств умного дома на ESP

Общие положения

Авторизация

Пример ответа при отсутствии или неверном токене

Эндпоинты

1. GET /about

Пример ответа

2. GET /status

Пример для реле

Пример для температурного датчика

3. POST /action

Пример запроса для реле

Пример ответа

Пример ошибки

4. POST /set_token

Пример запроса

Пример ответа (при успешной установке токена)

Пример ошибки, если устройство уже в normal-режиме и попытка установки без токена

Пример ошибки, если устройство уже provisioned (уже переведено в normal и повторно в setup режим попасть нельзя)

5. GET /setup и POST /setup

Описание:

Пример запроса (POST /setup):

Пример ответа:

Пример ошибки при попытке доступа к /setup вне режима setup:

6. POST /reboot

Пример ответа

7. POST /reset

Пример запроса

Пример ответа

7. POST /set_device_name

Пример запроса

Пример ответа

GET /channels_schema

Пример ответа

Пояснение примера:

9. POST /set_channels_schema

Пример запроса

Пример ответа

Рекомендации

1. `GET /about`

2. `GET /status`

3. `POST /action`

4. `POST /set_token`

5. `GET /setup` и `POST /setup`

Пример ошибки при попытке доступа к `/setup` вне режима `setup`:

6. `POST /reboot`

7. `POST /reset`

7. `POST /set_device_name`

`GET /channels_schema`

9. `POST /set_channels_schema`