Skip to content

Device API

Jump to bottom Edit New page
Emil Muratov edited this page Nov 22, 2023 · 10 revisions

API управления устройством

Проект имеет унифицированный API для построения WebUI и для управления/получения информации от котнроллера использующий json в качестве интерфейса данных. Контроллер обменивается данными в пакетном режиме, данные структурируются в секции и могут отправляться частями для минимизации использования памяти. Например страница веб-интерфейса может строится из нескольких пакетов данных, описывающих структуру станицы, подгрузку внешних ресурсов и блока с голыми данными, не содержащим структуры интерфейса.

Активности

Активность - это команда на запрос или изменение состояния лампы. Активности является объектом сожержащим объект-идентификатор и объект опциональный данных. Идентификатор определяется парой {"action":"action_id"} - где action идентификатор объекта "активность", action_id - символьный идентификатор, состоящий буквенно цифровых символов и разделителя _. Разделитель носит логический характер и служит для упрощения струкрурирования схожих имен активностей. Для интерфейсов WebSocket, HTTP разделитель используется как есть, для MQTT разделитель заменяется на / и используется как разделитель топиков. Объект данных может содержать произвольную структуру в виде вложенного значение ключа "data" {"data":{}}.

WebSocket

WebSocket используется браузером для построения страничного UI и асинхронного обмена данными с контроллером для динамического обновления статуса элементов управления. URI для подключения к WebSocket http://your-device/ws. Структура и формат данных определяется функционалом фреймворка EmbUI. В целом основной фунционал в проекте создается с учетом доступности из WebUI, т.к. структура объектов используется однинаковая для всех используемых протоколов API, то поведеним любого элемента доступного через WebUI можно управлять через другие протоколы API (MQTT/HTTP) воспользовавшись построением запросов по аналогии с приведенными ниже задокументированными элементами. Для незадокументированных элементов управления имена активностей, структуру и имена параметров и объектов можно извлечь из браузера включив режим разработчика и получив соответствующие сообщения в JS-консоль.

MQTT

Обмен данными через MQTT осуществляется также как и через WebSocket - пакетами с json объектами. Для всех топиков используется общий префикс, настраиваемый в опциях подключения к MQTT серверу. По умолчанию это префикс вида EmbUI/1234567890AB/, где 1234567890AB это MAC адрес контроллера. Префикс может быть переопределен в настройках. Далее по тексту префикс будет обозначаться символом ~. Отправлять запросы в топики можно двумя способами - либо посылать запрос полной структуры в топик ~/post, запрос должен включать ключ/значение с активностью и (опционально пустой) объект данных. Либо оправлять только блок данных в топики ~/get/# и ~/set/#, тогда идентификатор активности будет сформирован из суффикса топика заменой разделителей топиков / на _. Например запрос на включение лампы можно отправить следующими способами:

  • topic: ~/set/dev/pwrswitch, body: {"data":{"dev_pwrswitch":true}}
  • topic: ~/post, body: { "action":"dev_pwrswitch", "data":{"dev_pwrswitch":true}}

Список топиков используемых в проекте:

MQTT Topic тип топика назначение
~/pub/interface публикация публикация объектов описывающих элементы WebUI. Публикуется при запросе страниц и блоков через API, либо при изменении состояния контроллера.
~/pub/value публикация публикация объектов со значениями состояния элементов интерфейса и внутренних переменных. Публикуется при изменении состояния соответсвующего объекта или как отражение запроса изменение значения через API. Т.е. сюда публикуются все значения одиночно изменяющихся элементов типа переключатели, слайдеры, поля, и пр.
~/pub/post публикация топик рефлектор - публикуются все запросы на исполнение активностей поступившие в обработчик событий контроллера как извне так и изнутри контроллера. Т.е. запросы поступившие через другой API (WS, API), запросы поступившие от различных программных компонентов для внутрисистемного общения
~/pub/etc публикация публикация прочих объектов пользовательского типа
~/eff/ctrls
(retained)		 публикация публикуется массив контролов текущего эффекта, обновляется при переключении эффекта
~/get/# подписка топик служит для получения запросов о состоянии, значении переменных и элементов интерфейса
~/set/# подписка топик служит для установки значений переменных, выполнении активностей требующих входных данных
~/post подписка топик - общая точка входа API, принимает на вход все типы объектов взаимодействия. По сути топики ~/get/# и ~/set/# являются подмножеством топика ~/post

HTTP REST

HTTP API представляет собой подмножество WS/MQTT, используются json объекты той же структуры. Точка входа для HTTP API http://your-device/api. Точка принимает запросы типа HTTP POST с телом запроса в виде json-объекта. Ответом является json-объект, объект может быть пустым. Ввиду ограничений как самого протокола HTTP 1.1 так и библиотеки AsyncWebServer через HTTP невозможна передача нескольких пакетов с данными на один запрос. Напр. запрос на некий блок интефейса через WS может сгеренировать разные пакеты - один со структурой webui элементов, и другой со значениями этих элементов. В рамках одной транзакции "запрос-ответ" HTTP это невозможно, поэтому HTTP API ограничен ответом одного объекта, обычно это данные и объекты типа value.

Пример отправки HTTP-запросов с помощью утилит curl или PostMan :

Включить лампу: curl -X POST http://mylamp/api -H 'Content-Type: application/json' -d '{"action":"dev_pwrswitch", "data":{"dev_pwrswitch":true}}'

Ответ: [{"dev_pwrswitch":true}]

Получить текущую яркость лампы: curl -X POST http://mylamp/api -H 'Content-Type: application/json' -d '{"action":"dev_brightness"}'

Ответ: [{"dev_brightness":7},{"dev_brtscale":20},{"dev_lcurve":2}]

Note

Ответ означает что текущая яркость лампы 7 из 20, действует кривая коррекции 2 ("cie1931")

Прочие HTTP точки

  • /config.json - скачать системный конфиг лампы с файловой системы
  • /display.json - скачать конфиг настройки лед ленты/панели с файловой системы (подробнее)
  • /update - форма/URI HTTP OTA для обновления прошивки

Перечень активностей доступных через API

Активности управления режимом устройства

Активность dev_pwrswitch (тип: get/set)
Назначение включение/выключение устройства
Запрос / MQTT Topic WS/HTTP: {"action":"dev_pwrswitch", "data":{}}
MQTT: ~/get/dev/pwrswitch, ~/set/dev/pwrswitch
Параметры запроса get: "data":{}
set: "data":{"dev_pwrswitch":true} or false
Ответ [{"dev_pwrswitch":true}]
Примечание для mqtt ответ публикуется в топик ~/pub/value

Активность dev_brightness тип: get/set
Назначение Управление яркостью устройства
Запрос / MQTT Topic WS/HTTP: {"action":"dev_brightness", "data":{}}
MQTT: ~/get/dev/brightness, ~/set/dev/brightness
Параметры запроса get: "data":{}
set: "data":{"dev_brightness":<value>, "nofade":true}
где <value> целое в диапазоне 0 - максимум установленной шкалы яркости (по-молчанию: 20)
"nofade" опциональный параметр отключающий плавное изменение яркости
Ответ [{"dev_brightness":0},{"dev_brtscale":20},{"dev_lcurve":2}]
ответ содержит 3 значения:
dev_brightness - яркость
dev_brtscale - шкала яркости
dev_lcurve - кривая коррекции яркости
Примечание для mqtt ответ публикуется в топик ~/pub/value

Активность dev_lcurve тип: get/set
Назначение Установки кривой люма коррекци яркости
Запрос / MQTT Topic WS/HTTP: {"action":"dev_luma", "data":{}}
MQTT: ~/get/dev/lcurve, ~/set/dev/lcurve
Параметры запроса get: "data":{}
set: "data":{"dev_lcurve":<value>}
где <value> целое
0 - "binary"
1 - "linear"
2 - "cie1931"
3 - "exponent"
4 - "sine"
5 - "square"
Ответ совпадает с ответом на активность dev_brightness
Примечание для mqtt ответ публикуется в топик ~/pub/value

Активности управления эффектами

Активность eff_dynCtrl* тип: get/set
Назначение Изменение элементов управления эффектами - скорость, шкала, палитры и пр.
Запрос / MQTT Topic WS/HTTP: {"action":"eff_dynCtrl<N>", "data":{"eff_dynCtrl<N>":<value>}"}
MQTT: ~/get/eff/dynCtrl<N> ~/set/eff/dynCtrl<N>
Параметры запроса get: {}
set: {"eff_dynCtrl<N>":<value>}, где <N> - номер контрола эффекта, <value> - значение контрола (число/булеан и пр.)
Ответ кадр типа value, публикуется в топик ~/pub/value (напр. [{"eff_dynCtrl2":"30"}])
Примечание

Активность eff_ctrls тип: get
Назначение Формирует UI блок со списком всех контролов текущего эффекта
Запрос / MQTT Topic WS/HTTP: {"action":"eff_ctrls"}
MQTT: ~/get/eff/ctrls
Параметры запроса {}
Ответ WS/MQTT: объект UI элементов контролов эффектов
HTTP: {}
Примечание дополнительно публикуется в mqtt топик ~/eff/ctrls с флагом retained

Активность eff_sw_idx тип: set
Назначение Переключиться на эффект по индексу
Запрос / MQTT Topic WS/HTTP: {"action":"eff_sw_idx", "data":{"eff_sw_idx":<value>}}
MQTT: ~/set/eff/sw/idx
Параметры запроса set: {"eff_sw_idx":<value>}, где <value> целое в диапазоне 0 - 255
Ответ ответом может быть несколько различных сообщений генерируемых при смене эффекта - обновление яркости, списки контролов и т.п.
Примечание

Активность eff_sw_next тип: set
Назначение Переключиться на следующий эффект
Запрос / MQTT Topic WS/HTTP: {"action":"eff_sw_next", "data":{"eff_sw_next":null}}
MQTT: ~/set/eff/sw/next
Параметры запроса set: {"eff_sw_next":null}
Ответ совпадает с ответом на активность eff_sw_idx
Примечание

Активность eff_sw_prev тип: set
Назначение Переключиться на предыдущий эффект
Запрос / MQTT Topic WS/HTTP: {"action":"eff_sw_next", "data":{"eff_sw_next":null}}
MQTT: ~/set/eff/sw/prev
Параметры запроса set: {"eff_sw_prev":null}
Ответ совпадает с ответом на активность eff_sw_idx
Примечание

Активность eff_sw_rnd тип: set
Назначение Переключиться на случайный эффект
Запрос / MQTT Topic WS/HTTP: {"action":"eff_sw_rnd", "data":{"eff_sw_rnd":null}}
MQTT: ~/set/eff/sw/rnd
Параметры запроса set: {"eff_sw_rnd":null}
Ответ совпадает с ответом на активность eff_sw_idx
Примечание

Активности конфигурации LED ленты / HUB75

Активность display_ws2812 тип: get/set
Назначение Конфигурация параметров LED ленты/матрицы на основе адресных светодиодов
Запрос / MQTT Topic WS/HTTP: {"action":"display_ws2812"}
MQTT: ~/get/display/ws2812, ~/set/display/ws2812
Параметры запроса get: null
set: "data": { <параметры настроки матрицы> }
Ответ set: пустой ответ, либо кадр для WebUI
get: сериализованный объект текущей конфигурации матрицы
Примечание подробнее о параметрах на странице Настройка LED

Активность display_hub75 тип: get/set
Назначение Конфигурация параметров HUB75 матрицы
Запрос / MQTT Topic WS/HTTP: {"action":"display_hub75", "data":{}}
MQTT: ~/get/display/hub75, ~/set/display/hub75
Параметры запроса get: null
set: "data": { <параметры настроки матрицы> }
Ответ set: WS/MQTT/HTTP: пустой ответ, либо кадр для WebUI
get: []
Примечание подробнее о параметрах на странице Настройка LED

Активности формирования страниц/блоков WebUI

Активность ui_page_effects тип: get
Назначение Сформировать страницу управления эффектами
Запрос / MQTT Topic WS/HTTP: {"action":"ui_page_effects"}
MQTT: ~/get/ui/page/effects ~/post
Параметры запроса null
Ответ WS/MQTT: объект элементов страницы
HTTP: {}
Примечание

Активность ui_page_drawing тип: get
Назначение Сформировать страницу "Рисование"
Запрос / MQTT Topic WS/HTTP: {"action":"ui_page_drawing"}
MQTT: ~/get/ui/page/drawing ~/post
Параметры запроса null
Ответ WS/MQTT: объект элементов страницы
HTTP: {}
Примечание

Активность ui_block_switches тип: get
Назначение Сформировать блок переключателей на странице эффектов
Запрос / MQTT Topic WS/HTTP: {"action":"ui_block_switches"}
MQTT: ~/get/ui/block/switches ~/post
Параметры запроса null
Ответ WS/MQTT: объект элементов страницы
HTTP: {}
Примечание

Активность
Назначение
Запрос / MQTT Topic
Параметры запроса
Ответ
Примечание

Add a custom footer
Add a custom sidebar
Clone this wiki locally