Команды сервера

Общая информация

Клиентские библиотеки

API

HTTP/JSON

Сервер

`PING`

Команда PING используется для проверки активности соединения между клиентом и сервером устройств.

Назначение

Проверка того, что соединение с сервером активно и отвечает на запросы.

Пример использования

// Запрос
{
  "cmd": "PING",
  "data": {}
}

// Ответ
{
  "cmd": "PING__SUCCESS",
  "data": {}
}

`LOGIN`

Команда LOGIN используется для авторизации устройства на сервере по уникальному идентификатору (UUID). После успешной авторизации устройство считается онлайн, создаётся сессия подключения, и соединение помечается как аутентифицированное.

Назначение

Проверка существования и активности устройства по UUID.
Запрет повторной авторизации, если устройство уже онлайн.
Создание новой сессии с фиксацией IP-адреса и времени подключения.
Установка статуса устройства в «онлайн» и регистрация соединения на сервере.

Возможные ошибки

Код ошибки	Описание
`SERVER_STOPPED`	Сервер находится в процессе остановки и не принимает новые подключения.
`MISSING_UUID`	Поле `uuid` отсутствует в запросе.
`INVALID_UUID_FIELD`	Поле `uuid` не является строкой.
`INVALID_UUID_FORMAT`	Указанное значение `uuid` имеет некорректный формат (например, не соответствует ожидаемому формату хеша).
`DEVICE_NOT_FOUND`	Устройство с таким UUID не найдено или неактивно (`is_active=False`).
`DEVICE_ALREADY_ONLINE`	Устройство с таким UUID уже авторизовано и находится в онлайн-статусе.

Пример использования

Запрос

{
  "cmd": "LOGIN",
  "data": {
    "uuid": "a1b2c3d4e5f678901234567890abcdef12345678"
  }
}

Успешный ответ

{
  "cmd": "LOGIN__SUCCESS",
  "data": {}
}

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

{
  "cmd": "LOGIN__ERROR",
  "data": {
    "message": "Device is already online",
    "code": "DEVICE_ALREADY_ONLINE"
  }
}

`SET_SUPPORTED_COMMANDS`

Команда SET_SUPPORTED_COMMANDS позволяет устройству сообщить серверу список команд, которые оно поддерживает. Сервер обновляет метаданные команд: добавляет новые, обновляет существующие и помечает как удалённые те, что больше не передаются.

Назначение

Синхронизация списка поддерживаемых команд устройства с сервером.
Автоматическое управление актуальностью команд: старые команды (не переданные в текущем запросе) помечаются как удалённые.
Хранение описания и спецификации параметров для каждой команды.

Возможные ошибки

Код ошибки	Описание
`INVALID_COMMANDS_FORMAT`	Поле `commands` отсутствует, не является объектом или содержит некорректные данные (например, имя команды — не строка, описание — не строка, `param_specs` — не объект).
`UNEXPECTED_ERROR`	Произошла непредвиденная ошибка при обработке команд (например, сбой базы данных).

Пример использования

Запрос

{
  "cmd": "SET_SUPPORTED_COMMANDS",
  "data": {
    "commands": {
      "REBOOT": {
        "description": "Перезагружает устройство",
        "param_specs": {}
      },
      "SET_VOLUME": {
        "description": "Устанавливает громкость",
        "param_specs": {
          "level": {
            "type": "integer",
            "min": 0,
            "max": 100
          }
        }
      }
    }
  }
}

Успешный ответ

{
  "cmd": "SET_SUPPORTED_COMMANDS__SUCCESS",
  "data": {}
}

Пример ошибки (некорректный формат)

{
  "cmd": "SET_SUPPORTED_COMMANDS__ERROR",
  "data": {
    "message": "Each command must have a string name, string description, and dict param_specs",
    "code": "INVALID_COMMANDS_FORMAT"
  }
}

`SET_EXECUTION_RESULT`

Команда SET_EXECUTION_RESULT используется устройством для отправки результата выполнения ранее запланированной команды. Результат (включая выходные данные и, при необходимости, сообщение об ошибке) сохраняется на сервере по уникальному ключу выполнения (execution_key).

Назначение

Передача результата выполнения команды с устройства на сервер.
Поддержка как успешных, так и неуспешных исходов выполнения.

Возможные ошибки

Код ошибки	Описание
`INVALID_EXECUTION_KEY`	Параметр `execution_key` отсутствует, не является строкой или пустой.
`INVALID_OUTPUT_TYPE`	Поле `output` передано, но не является объектом (ожидается `dict`).
`INVALID_ERROR_TYPE`	Поле `error` передано, но не является строкой.

Пример использования

Запрос (успешное выполнение)

{
  "cmd": "SET_EXECUTION_RESULT",
  "data": {
    "execution_key": "exec_12345abc",
    "output": {
      "status": "success",
      "volume": 75
    }
  }
}

Запрос (ошибка выполнения команды)

{
  "cmd": "SET_EXECUTION_RESULT",
  "data": {
    "execution_key": "exec_12345abc",
    "output": {
      "your_extra_data": {}
   },
    "error": "Текст ошибки"
  }
}

Успешный ответ

{
  "cmd": "SET_EXECUTION_RESULT__SUCCESS",
  "data": {}
}

Пример ошибки (некорректный execution_key)

{
  "cmd": "SET_EXECUTION_RESULT__ERROR",
  "data": {
    "message": "Execution key must be a non-empty string",
    "code": "INVALID_EXECUTION_KEY"
  }
}

`EXECUTE_ON`

Для инициации выполнения команды на другом устройстве.

Команда в разработке