Xiot-controller-local-api

Локальное API контроллера XIOT — входящий HTTP-интерфейс XIOT-PLC. Внешняя система в доверенной локальной сети может через него прочитать объекты и характеристики загруженного проекта или передать команду. API не создаёт новые адреса: оно использует дом, этажи, комнаты, виртуальные устройства и характеристики, которые уже есть в действующей конфигурации контроллера.

Не путайте локальное API с исходящим модулем REST API: локальное API принимает обращения внешней системы на XIOT-PLC, а исходящий модуль сам обращается к другому серверу. Обзор интеграционных модулей: Настройка драйверов.

Описанный контракт проверен по опубликованному пакету XIOT-PLC 14.1-1-1. В этой версии контроллер принимает запросы по схеме HTTP на своём IP-адресе и порту 5552.

Перед началом

• Загрузите на XIOT-PLC актуальную конфигурацию проекта и убедитесь, что нужное виртуальное устройство связано с реальным оборудованием: Привязка реальных устройств к виртуальным.
• Подключайте внешнюю систему только из доверенной локальной сети либо через защищённый VPN.
• Не пробрасывайте порт 5552 на маршрутизаторе и не публикуйте его в Интернете.
• Для первой команды выберите известное устройство с безопасной и видимой реакцией. Не начинайте проверку на замках, воротах, насосах, отоплении, защитной автоматике и другом оборудовании, неожиданное включение которого опасно.

Получение и обновление ключа

1. Откройте привязанный контроллер в XIOT-EDITOR.
2. Откройте окно Настройки контроллера.
3. Скопируйте значение поля Ключ локального API (порт 5552).

Это единый секрет контроллера: с ним можно читать данные проекта и отправлять команды доступным через API объектам. Храните ключ как пароль. Не помещайте его в вики, исходный код, скриншоты, обращения в поддержку и общие журналы.

Кнопка Обновить ключ локального API создаёт новый ключ. Старый ключ после этого перестаёт проходить авторизацию, поэтому обновите его во всех разрешённых интеграциях. Если ключ мог попасть к посторонним, обновите его сразу.

Подготовка запроса

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

• XIOT_API — базовый адрес из схемы http, IP-адреса контроллера и порта 5552;
• XIOT_API_KEY — текущий ключ локального API.

Для разовой проверки в bash или zsh значения можно ввести интерактивно, не записывая их в историю команд:

read -r -p "Базовый адрес XIOT API: " XIOT_API
read -r -s -p "Ключ XIOT API: " XIOT_API_KEY
printf '\n'

Рекомендуемый вариант авторизации — заголовок X-XIOT-API-Key:

curl --silent --show-error --max-time 10 \
  -H "X-XIOT-API-Key: ${XIOT_API_KEY}" \
  "${XIOT_API}/api/v1/remote/get/devices"

Также поддерживается заголовок Authorization: Bearer. Не передавайте ключ в адресе запроса: адрес может сохраниться в истории, журналах и системах мониторинга.

Текущая реализация использует метод HTTP GET и для чтения, и для команд изменения. Не открывайте командные адреса в браузере, не сохраняйте их в закладках и не пропускайте через кэширующие или автоматически повторяющие запросы посредники.

Получение данных

Путь	Результат
/api/v1/remote/get/home	Дом и его характеристики. Идентификатор дома в текущей реализации — 1.
/api/v1/remote/get/floors	Все этажи.
/api/v1/remote/get/floor/<id>	Один этаж с указанным идентификатором.
/api/v1/remote/get/rooms	Все комнаты с данными об этажах.
/api/v1/remote/get/room/<id>	Одна комната с указанным идентификатором.
/api/v1/remote/get/devices	Все виртуальные устройства с комнатами, этажами и характеристиками.
/api/v1/remote/get/device/<id>	Одно виртуальное устройство с указанным идентификатором.

Ответ имеет формат JSON. Объекты индексируются их идентификаторами. Для устройств возвращаются имя, тип, сведения о комнате и этаже, а также объект characteristic с текущими значениями характеристик. Набор полей и характеристики зависят от загруженного проекта.

Сначала запросите списки и возьмите идентификаторы из фактического ответа. Не угадывайте идентификатор и не переносите его из чужого примера. После изменения структуры проекта выполните обнаружение заново.

Отправка команды

Форма пути команды:

/api/v1/remote/set/<тип>/<id>/<характеристика>/<значение>

Поддержаны типы home, floor, room и device. Идентификатор и имя характеристики берите из текущего проекта и ответа API. До команды проверьте в XIOT-EDITOR или в документации виртуального устройства, что характеристика предназначена для управления. Если сегмент содержит специальные символы, его нужно корректно кодировать для URL.

Пример с заранее проверенными локальными переменными:

curl --silent --show-error --max-time 10 \
  -H "X-XIOT-API-Key: ${XIOT_API_KEY}" \
  "${XIOT_API}/api/v1/remote/set/device/${DEVICE_ID}/${CHARACTERISTIC}/${VALUE}"

Ответ обработчика на принятую команду:

{"set":"ok"}

Этот ответ означает, что обработчик нашёл объект и характеристику и вызвал внутреннюю команду XIOT. Он не подтверждает физическое выполнение оборудованием. Если обработчик не нашёл объект или характеристику либо не смог вызвать команду, обычно возвращается:

{"set":"error"}

Оба ответа могут прийти с кодом HTTP 200, поэтому проверяйте и код, и JSON, и фактический результат.

Безопасная проверка

1. Выполните /api/v1/remote/get/devices и найдите нужное устройство по фактическому ответу.
2. Сверьте его идентификатор, характеристику управления и допустимое значение с текущим проектом.
3. Выберите безопасную нагрузку с видимой реакцией и запишите исходное состояние.
4. Отправьте одну команду. Не настраивайте автоматические повторы при неопределённом результате.
5. Проверьте физическую реакцию оборудования, затем повторно запросите /api/v1/remote/get/device/<id> и сравните состояние.
6. Если значение было изменено только для теста, верните исходное состояние и ещё раз проверьте оборудование.

Ответ API без физической реакции не считается успешной приёмкой всей цепочки. Если адрес состояния не отражает реальность, сначала исправьте привязку устройства.

Коды и ответы

Наблюдение	Что оно означает
HTTP 401 и {"error":"unauthorized"}	Ключ отсутствует или не совпадает с текущим ключом контроллера.
HTTP 200 и непустой JSON объекта	Запрос чтения обработан; содержимое всё равно нужно проверить.
HTTP 200 и {}	Объект не найден, путь не распознан либо в текущей конфигурации нет данных. Код 200 сам по себе не доказывает правильность пути.
HTTP 200 и {"set":"ok"}	Внутренняя команда вызвана; физический результат ещё нужно проверить.
HTTP 200 и {"set":"error"}	Команда не принята обработчиком; проверьте полный путь, тип, идентификатор и характеристику.
Нет HTTP-ответа	Проверьте питание и доступность контроллера, его текущий IP-адрес, маршрут, локальный межсетевой экран и порт 5552.

Не рассчитывайте на отдельный код 404 для каждого неверного пути: текущий обработчик может вернуть пустой JSON с кодом 200.

Безопасность сети

• API слушает порт 5552 на сетевых интерфейсах контроллера и рассчитан на доверенный контур.
• Встроенный интерфейс использует обычный HTTP без TLS. В недоверенной сети можно перехватить и ключ, и команды.
• Разрешайте соединение только нужным узлам локальной сети. Для удалённого доступа используйте администрируемый VPN с ограничением маршрутов и источников.
• Не открывайте порт 5552 в Интернет, даже если используется сложный ключ.
• Не передавайте ключ в строке запроса. Не записывайте полные заголовки авторизации в журналы.
• При увольнении подрядчика, компрометации компьютера или публикации конфигурации обновите ключ и удалите старое значение из всех хранилищ и журналов, где это возможно.

После изменения проекта

Локальное API работает с конфигурацией, фактически загруженной на XIOT-PLC. Команда Загрузить конфигурацию на контроллер сначала сохраняет проект локально и после успешной записи отправляет сохранённую конфигурацию на XIOT-PLC. Облачное сохранение и публикацию приложения проверяют отдельно: успешная загрузка на PLC их не подтверждает. Отдельное сохранение без загрузки не изменяет набор объектов API на контроллере.

После добавления, удаления или повторного создания объектов заново запросите списки, проверьте идентификаторы и выполните безопасную приёмку интеграции. Не считайте старые идентификаторы бессрочным контрактом.

Если запрос не работает

1. Убедитесь, что XIOT-PLC включён и доступен по его текущему IP-адресу из той же доверенной сети.
2. Проверьте, что используется порт 5552, а ключ передан ровно в одном поддерживаемом заголовке.
3. При ошибке 401 заново скопируйте текущий ключ; после обновления ключа старое значение уже не подходит.
4. При пустом ответе сначала проверьте полный путь и получите актуальные идентификаторы списочным запросом.
5. При {"set":"error"} сверьте объект и направление характеристики в проекте.
6. Если получено {"set":"ok"}, но оборудование не отреагировало, проверьте адрес управления, адрес состояния, драйвер и физическое оборудование. Полезны Системные события в журнале XIOT-PLC и Механизм работы тегов в XIOT.

Если причина не найдена, обратитесь на страницу Связь с поддержкой. Передавайте время проверки, версию XIOT-PLC и обезличенный путь запроса; не отправляйте ключ и полные заголовки авторизации.

Следующие шаги

• Настройка драйверов — исходящие интеграционные модули и протоколы.
• Привязка реальных устройств к виртуальным — связь команды API с физическим оборудованием.
• Механизм работы тегов в XIOT — адреса управления и состояния.