Сокет
Прикладной протокол обмена поверх WebSockets (RFC 6455). Контроллер подключается по ip-адресу сервера системы, заданному при конфигурации. Возможно использование защищеного канала WSS (WebSockets over SSL/TLS).
Далее по тексту, под сервером понимается некий “сервер системы” - ПО верхнего уровня. До тех пор, пока контроллеру не будет задан IP-адрес этого сервера, подключение инициировать должен сам сервер (либо работа через WEB-браузер (с поддержкой WebSockets)). После задания IP-адреса сервера (либо через браузер, либо непосредственно самим сервером), контроллер будет подключаться к серверу сам.
При подключении к контроллеру в поле target запроса необходимо добавить путь ‘/tcp’, либо ‘/api/ws’ (пример формирования сокета на JS ‘ws://10.1.89.181:80/tcp’ , либо ‘ws://10.1.89.181:80/api/ws’). Установка соединения по HTTP (для HTTPS аналогично) будет выглядеть так:
GET /tcp HTTP/1.1
Host: 10.0.150.136
Origin: 10.0.150.136
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: 0M//4Wm9N3ngPpr7q6O3FQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
User-Agent: Python/3.10 websockets/10.3
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Sec-WebSocket-Accept: gt5pkLN0d02eA+OSekZqAZvRrFc=
Connection: upgrade
Date: Tue, 09 Jul 2024 12:45:32 GMT
Server: lighttpd/1.4.69
Протокол
Протокол использует формат обмена данных JSON (RFC 7159). Протокол оперирует объектами такими, как “исполнительное устройство” и т.п. посредством следующих методов:
get — запрос сервером данных объекта;
get_count — запрос сервером количества данных объекта (не для всех объектов);
set — запись сервером данных объекта (в энергонезависимую память);
control — управление объектом;
answer — ответ серверу get, set;
result — ответ серверу control;
event — асинхронная передача данных серверу.
Структура кадров (target = ‘/tcp’)
Запрос может содержать дополнительные параметры (необязательные), расширяющие ответ устройства.
{
"get" : "object",
"object" : {
"parametr_request_1" : 0,
"parametr_request_1" : "any_string",
"parametr_request_3" : false
}
}
Установка параметров конфигурации объекта. Параметры сразу применяются и сохраняются в энергонезависимой памяти.
{
"set" : "object",
"object" : {
"parametr_object_1" : 0,
"parametr_object_2" : "card",
"parametr_object_3" : false,
"parametr_object_4" : 268435455
}
}
Управление объектом (не все объекты поддерживают команды управления).
{
"control":"object",
"object":{
"action":"open_once",
"time":10,
"number":0,
"direction":0
}
}
Ответ ведущему устройству на команды get и set содержит параметры объекта, сохранённые в энергонезависимой памяти.
{
"answer":{"object":"ok","set":"own"},
"object":{
"parametr_object_1" : 0,
"parametr_object_2" : "card",
"parametr_object_3" : false,
"parametr_object_4" : 268435455
}
}
Ответ ведущему устройству на команды get и set при возникновении ошибки обработки запроса.
{
"answer":{"object":"error","set":"own","error":"Password incorrect","error_code":1},
"object":{
"parametr_object_1" : 0,
"parametr_object_2" : "card",
"parametr_object_3" : false,
"parametr_object_4" : 268435455
}
}
Ответ ведущему устройству на команду control содержит параметры запроса.
{
"result":{"object":"ok","control":"own"},
"object":{
"action":"open_once",
"time":10,
"number":0,
"direction":0
}
}
Ответ ведущему устройству на команду control при возникновении ошибки обработки запроса.
{
"result":{"object":"error","control":"own","error":"Password incorrect","error_code":1},
"object":{
"action":"open_once",
"time":10,
"number":0,
"direction":0
}
}
Асинхронное событие от устройства.
{
"event":{
"parametr_event_1" : 0,
"parametr_event_2" : "open",
"parametr_event_3" : true,
"parametr_event_4" : 268435455
}
}
{
"event":"object"
"object":{
"parametr_event_1" : 0,
"parametr_event_2" : "open",
"parametr_event_3" : true,
"parametr_event_4" : 268435455
}
}
В ответах контроллера answer на запрос set присутствует дополнительный параметр - set:own (для ответов сокету, с которого пришёл запрос) {set:foreign} (в остальные сокеты, если широковещательные ответы не запрещены). При ошибке обработки запроса в answer помещается дополнительное поле с текстовым описанием ошибки (error), и не обязательные параметр с кодом ошибки (error_code).
В ответах контроллера result на запрос control присутствует дополнительный параметр - control:own (для ответов сокету, с которого пришёл запрос) {control:foreign} (в остальные сокеты, если широковещательные ответы не запрещены). При ошибке обработки запроса в result помещается дополнительное поле с текстовым описанием ошибки (error), и не обязательные параметр с кодом ошибки (error_code).
Структура кадров (target = ‘/api/ws’)
Запрос может содержать дополнительные параметры (необязательные), расширяющие ответ устройства.
{
"get" : "object",
"uuid" : "c401f2de-3150-43be-975a-fc06fa1ca3f1",
"payload" : {
"parametr_request_1" : 0,
"parametr_request_1" : "any_string",
"parametr_request_3" : false
}
}
Установка параметров конфигурации объекта. Параметры сразу применяются и сохраняются в энергонезависимой памяти.
{
"set" : "object",
"uuid" : "c401f2de-3150-43be-975a-fc06fa1ca3f1",
"payload" : {
"parametr_object_1" : 0,
"parametr_object_2" : "card",
"parametr_object_3" : false,
"parametr_object_4" : 268435455
}
}
Управление объектом (не все объекты поддерживают команды управления).
{
"control":"object",
"uuid" : "c401f2de-3150-43be-975a-fc06fa1ca3f1",
"payload":{
"action":"open_once",
"time":10,
"number":0,
"direction":0
}
}
Ответ ведущему устройству на команды get и set содержит параметры объекта, сохранённые в энергонезависимой памяти. Если ответ на get состоит из нескольких объектов, то в каждом объекте ответа добавляется счётчик count (например, ответ на запрос событий (поля set там, кстати, не будет, т.к. ответ на этот запрос не широковещательный))
{
"answer":{"object":"ok","set":"own","count":0},
"uuid" : "c401f2de-3150-43be-975a-fc06fa1ca3f1",
"payload":{
"parametr_object_1" : 0,
"parametr_object_2" : "card",
"parametr_object_3" : false,
"parametr_object_4" : 268435455
}
}
Ответ ведущему устройству на команды get и set при возникновении ошибки обработки запроса.
{
"answer":{"object":"error","set":"own","error":"Password incorrect","error_code":1},
"uuid" : "c401f2de-3150-43be-975a-fc06fa1ca3f1",
"payload":{
"parametr_object_1" : 0,
"parametr_object_2" : "card",
"parametr_object_3" : false,
"parametr_object_4" : 268435455
}
}
Ответ ведущему устройству на команду control содержит параметры запроса.
{
"result":{"object":"ok","control":"own"},
"uuid" : "c401f2de-3150-43be-975a-fc06fa1ca3f1",
"payload":{
"action":"open_once",
"time":10,
"number":0,
"direction":0
}
}
Ответ ведущему устройству на команду control при возникновении ошибки обработки запроса.
{
"result":{"object":"error","control":"own","error":"Password incorrect","error_code":1},
"uuid" : "c401f2de-3150-43be-975a-fc06fa1ca3f1",
"payload":{
"action":"open_once",
"time":10,
"number":0,
"direction":0
}
}
Асинхронное событие от устройства.
{
"event":{
"parametr_event_1" : 0,
"parametr_event_2" : "open",
"parametr_event_3" : true,
"parametr_event_4" : 268435455
}
}
{
"event":"object"
"object":{
"parametr_event_1" : 0,
"parametr_event_2" : "open",
"parametr_event_3" : true,
"parametr_event_4" : 268435455
}
}
Описание параметров кадров аналогично предыдущему (для target = ‘/tcp’).
Отличия:
- 'object' => 'payload'
- Уникальный идентификатор транзакции 'uuid', строка вида 'c401f2de-3150-43be-975a-fc06fa1ca3f1'
- Счётчик объектов ответа `count`