Коммуникационный протокол SberMobile
Протокол SberMobile используется для взаимодействия между SberMobile Server, SberMobile агентом и SberMobile IIoT Platform Clientом. Связь осуществляется по одиночному TCP-соединению, которое опционально защищается SSL/TLS шифрованием.
На протяжении коммуникационной сессии обе стороны обмениваются командами. В этой главе инициатор команд называется клиентом, а другая сторона называется сервером:
- Во взаимодействии SberMobile Server и SberMobile IIoT Platform Client, инициатором является SberMobile IIoT Platform Client
- Во взаимодействии SberMobile Server и агента SberMobile, инициатором является <SberMobile Server>
 | На данный момент существуют 2 версии протокола: 2 и 3. Все различия будут описаны далее. |
Инкапсуляция команды
Команды инкапсулируются при помощи символов <STX> (0x02) and <CR> (0x0D). Команды извлекаются из потока данных, а все остальные данные отбрасываются. Другие аспекты зависят от версии протокола.
Версия 2
Структура инкапсуляции комманды следующая:
<STX>command<CR>
Если есть два и более символов <STX> без <CR>, все данные, принадлежащие текущему потоку, отбрасываются на каждый полученный <STX>:
<STX>aaa<STX>bbb<CR> понимается как команда bbb.
Версия 3
Структура инкапсуляции комманды следующая:
<STX><L1><L2><L3><L4><T>command<CR>
После символа <STX> следует 4-байтовая символическая структура <L1><L2><L3><L4>. Это командная длина в байтах.
Далее <T> - это командный тип байта. В этой версии протокола команда может быть двух видов: Raw (0) и Compressed (1). Raw обознает, что команда отправлена в качестве первичного char массива. Compressed обозначает команду, которая отправляется сжатой в качестве ZLIB байтного массива.
Затем команда проходит в первичном или сжатом состоянии, инкапсуляция закрывается, используя символ <CR>.
 | Пример инкапсуляции команды для версии протокола №3: <STX><0><0><0><7><0>R/123/A<CR> |
Структура команды
Каждая команда состоит из нескольких частей, разделенных символами 0x17 (“Разделитель команд”). Символ разделителя команд в данном руководстве представлен символом /. Например:
<STX>aaa/bbb/ccc<CR>
содержит три части: aaa, bbb и ccc.
Зарезервировано три символа, которые не могут появляться внутри команды:
Код символа | Имя символа |
0x02 | STX |
0x0D | CR |
0x17 | ETB |
Для каждой команды характерна следующая структура:
<STX>command_code/command_parameters…<CR>
command_code - это отдельный символ, один из:
| Команда “Message” |
| Команда “Reply” |
command_parameters - это один или несколько параметров, относящихся к коду команды, разделённые символом /.
Команды
Команда "message”
Структура этой команды следующая (с этого момента, первый символ <STX> и оконечный <CR> не указываются):
M/message_ID/message_code/message_parameters…
message_ID уникальный для текущей сессии.
message_code - это символ, указывающий на тип сообщения. Доступные коды сообщения:
| сообщение “Start” |
| сообщение “Operation” |
| сообщение “Event” |
message_parameters - это один или более параметров, характерных для кода сообщения, разделяемого символом /.
Команда "reply"
R/reply_ID/reply_code/reply_parameters...
reply_ID должен соответствовать ID сообщения, на которое отвечает.
Параметр reply_code - это признак, который указывает на тип ответа. Доступные коды ответа:
| Успешно (далее может следовать необязательный параметр |
| Отклонено |
| Ошибка (далее может следовать один или два параметра: сообщение об ошибке и/ или кодированная строка подробного описания ошибки) |
| Учетная запись пользователя в настоящее время заблокирована из-за нарушения ограничений системы безопасности |
| Операция запрещена, так как сервер нахоится в режиме обслуживания |
Сообщения
Сообщение “start”
M/message_ID/S/protocol_version
Формат данного сообщения в дальнейшем не изменяется. Его должен отправлять клиент, как самую первую команду во время обмена данными с сервером. Сервер возвращает ошибку, если какое-либо другое сообщение отправляется раньше, чем было отправлено сообщение Start.
protocol_version - это целое число, указывающее на версию протокола взаимодействия, поддерживаемого клиентом. Текущая версия 3.
Сервер отвечает на команду Start командой Reply. Если версия протокола, заданная клиентом, поддерживается сервером, код ответа - Success, в ином случае он отвегается. См. описание команды Ответ.
Сообщение “operation”
M/message_ID/O/operation/context_name/entity[/data_table]
Команда Operation приказывает серверу выполнить операцию на заданном контексте.
Operation - это свойство, определяющее операцию, которая должна быть выполнена. context_name - это имя контекста, для которого выполняется запрашиваемая операция. entity - это параметр операции. Это может быть имя переменной, если операция - “Set Variable”, или имя функции, если операция - “Call Function”.
Список доступных кодов операций:
| Получить переменную |
| Установить переменную |
| Вызвать функцию |
| Добавить слушателя события |
| Удалить слушателя события |
data_table - это необязательный параметр, содержащий, характерные для операции данные. См. приложение кодирование таблиц данных .
Сообщение “event”
M//E/context_name/event_name/event_level/event_ID/event_listener_ID/data_table
Это сообщение отправляется клиенту, когда событие , именуемое event_name, происходит в context_name и этот клиент был ранее добавлен как слушатель данного события. Оно не требует ответа от клиента. Если событие постоянно, поле event_ID содержит его уникальный ID. event_listener_ID - это целое число, которое указывает на объект слушателя на стороне клиента. data_table содержит данные, специфичные для события.
Примечание: Событие "event" имеет пустой параметр message_ID.
Операции
Операция “получить переменную”
M/message_id/O/G/context _name/variable_name
Эта операция возвращает variable_name из context_name.
Если переменная обнаружена, и не возникает ошибка, ответ на эту команду будет содержать таблицу данных со значением запрашиваемой переменной:
R/reply_id/A/data_table
Операция “установить переменную”
M/message_id/O/S/context _name/variable_name/data_table
Эта операция устанавливает для variable_name , принадлежащему context_name, значение, содержащееся в data_table.
Если значение переменной было успешно изменено, сервер ответит:
R/reply_id/A
Операция “вызвать функцию”
M/message_id/O/C/context _name/function_name/data_table
Эта операция вызывает function_name из context_name с data_table в качестве входного параметра.
Если не возникает ошибок, ответ содержит таблицу данных, возвращаемую функцией:
R/reply_id/A/data_table
Операция “добавить слушателя события”
M/message_id/O/L/context _name/event_name/event_listener_ID
Эта операция регистрирует слушателя с заданным целым числом - идентификатором event_listener_ID для event_name в context_name. Когда происходит событие, клиент получает сообщение “Event” (E) с кодом event_listener_ID.
Опциональный параметр filter_text позволяет заранее отфильтровать события, основанные не представленном выражении фильтра. Это выражение будет расситываться для каждого подходящего события, и если результатом будет false, событие не отправится клиенту.
Среда вычисления выражения фильтра: | |
Отсутствует. | |
Таблица данных, содержащая специфичные для события данные. | |
0 | |
Только стандартные переменные. | |
При успешном добавлении слушателя события, сервер отвечает:
R/reply_id/A
Операция "удалить слушателя события"
M/message_id/O/R/context _name/event_name/event_listener_ID
Эта операция удаляет слушателя с заданным event_listener_ID , принадлежащим event_name, в context_name.
При успешном удалении слушателя события, сервер отвечает:
R/reply_id/A
Кодирование таблиц данных
Все значения данных, полученных или отправленных в рамках данного протокола, представлены в таблицах данных. Каждая таблица данных зашифрована в строку, которую следует вставить в команду. См. кодирование таблиц данных.