Общее описание

Документ описывает упрощенный протокол взаимодействия вычислительных устройств, предназначенный главным образом для взаимодействия между устройствами со слабыми ресурсами между собой с использованием любых каналов связи, способных передавать текстовую информацию (COM, TCP/IP и т. д.). В рамках протокола предполагается коммуникация между устройствами по принципу точка-точка, одно из устройств считается управляющим, другое управляемым, однако различия между ними не велики. Так же в рамках описания форматов сообщений указываются передающее и принимающее устройства (передающее устройство инициирует процесс обмена сообщениями, при этом им может быть как управляющее, так и управляемое устройство в зависимости от ситуации). Управляемое устройство может быть хабом, при этом оно объединяет несколько других устройств.

Описание протокола

1. Каждое устройство имеет уникальный 128-битный идентификатор (Uuid).

2. Устройства взаимодействуют путем двухстороннего обмена сообщениями. Каждое сообщение — строка байт, причем в протоколе в качестве разделителей и зарезервированных элементов используются строки ascii-символов. Сообщения разделяются байтом с десятичным кодом 10 (символ перевода строки, "\n" в языке С).

3. Сообщения состоят из нескольких элементов, первый из которых называется заголовком, остальные аргументами. Элементы сообщения разделяются байтом с десятичным кодом 124 (символ "|").
   Пример сообщения:
   info|Argument 1|Argument 2|Argument 3\n

4. Для экранирования служебных символов в сообщении используется байт с десятичным кодом 92 (символ обратной косой черты "\"). Экранирование символов производится по следующим правилам:

   1. Символ "\" экранируется им же. В сообщении — "\\".

   2. Символ "|" экранируется как "\|".

   3. Символ перевода строки заменяется экранированной буквой "n" (десятичный код 110). В сообщении — "\n".

   4. Символ с кодом 0 заменяется на экранированный "0" (десятичный код 48). В сообщении — "\0".

   5. Произвольный байт данных может быть записан как \xHH, где HH — шестнадцатеричный код символа в нижнем или верхнем регистре. Пример — "\x2f". Если шестнадцатеричный код не распознан, символ игнорируется.

   6. Символ с кодом 0 служит для сигнализации о том, что управляемое устройство перезагрузилось и его состояние было сброшено.

Базовые сообщения

1. Информационное сообщение. Заголовок — info. Предназначено для передачи информации, не требующей специальной обработки (например, отладочная информация) и предназначенной для передачи ее человеку (разработчику или оператору). Сообщение не требует ответа от принимающего устройства. Аргументы сообщения — текстовые строки, содержащие информацию, предназначенную для прочтения человеком.

2. Сообщение готовности к работе. Заголовок — ready. Может использоваться устройством для уведомления другого устройства о готовности к работе, например, после окончания загрузки устройства. Аргументы отсутствуют.

3. Запрос идентификации устройства. Заголовок — identify. Аргументы отсутствуют. Принимающее устройство должно в течении 5 секунд вернуть ответное сообщение с заголовком deviceinfo со следующими аргументами:
   1. Уникальный идентификатор устройства в виде текстового шестнадцатеричного представления UUID "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" или "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx".
   2. Человеко-читаемое название (не должно быть в формате UUID).

4. Запрос идентификации устройства-хаба. Заголовок — identify. Аргументы отсутствуют. Принимающее устройство должно в течении 5 секунд вернуть ответное сообщение с заголовком deviceinfo со следующими аргументами:
   1. Специальный идентификатор "#hub".
   2. Уникальный идентификатор устройства в виде текстового шестнадцатеричного представления UUID "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" или "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx".
   3. Человеко-читаемое название.

5. Перечисление подключенных к хабу устройств. Заголовок — identify_hub. В ответ хаб сразу возвращает ok либо err (если устройство не является хабом). Позже устройства, подключенные к хабу, передают сообщения deviceinfo.

6. Сообщение синхронизации. Заголовок — sync. Предназначено для проверки состояния канала связи между устройствами. В ответ на это сообщение управляемое устройство должно в течении 5 секунд вернуть сообщение syncr.

7. Команда. Заголовок — call. Первый аргумент — идентификатор вызова, второй — название команды (любое кроме зарезервированных, описанных в разделе "Зарезервированные названия команд"). Остальные аргументы сообщения — аргументы команды. Если устройство не может выполнить команду в течение 5 секунд, необходимо регулярно передавать сообщение syncс с аргументом-идентификатором вызова. Принимающее устройство по окончании выполнения должно вернуть сообщение с заголовком ok в случае успешного завершения или err в случае неудачи, первый аргумент этих сообщений — идентификатор вызова, далее — возвращаемые значения (для сообщения ok) или описание ошибки (для сообщения err).

8. Сообщение синхронизации команды. Заголовок — syncс. Если управляемое устройство не может выполнить команду быстрее 10 секунд, оно должно регулярно посылать сообщение syncc. Если в течение 10 секунд сообщение не пришло, команда считается невыполненной.

9. Измерение в текстовом виде. Заголовок — meas. Аргументы сообщения: название датчика и значение в текстовом виде, каждое число в отдельном аргументе сообщения. (см. "Форматы данных датчиков")

10. Измерения в бинарном виде. Заголовок — measb. Аргументы сообщения: название датчика, далее значение в бинарном виде, все передаваемые числа (включая временную метку) упакованы в один аргумент сообщения без разделителей. Порядок байт — от младшего к старшему. (см. "Форматы данных датчиков").

11. Измерения, закодированные в base64. Заголовок — measb64. Аргументы сообщения: название датчика, далее значение в текстовом виде, все передаваемые числа (включая временную метку) упакованы в один аргумент сообщения без разделителей, закодированный в base64. Порядок байт числа — от младшего к старшему. (см. "Форматы данных датчиков").

12. Сообщение об изменении состояния устройства. Сообщение — statechanged. Передается устройством, когда происходит изменение его состояния. Аргументы:
    1. Название команды или "#" (см. "Состояние устройства").
    2. Номер аргумента команды (начиная с 1) или название дополнительного параметра устройства.
    3. Новое значение.

13. Широковещательный запрос на поиск устройства (для сетей ptp, поддерживающих широковещательные запросы, например, UDP запрос в локальной IP сети). Заголовок — find_device. Аргумент — имя или идентификатор устройства, возможны дополнительные аргументы, если это необходимо для идентификации сервера. Устройство с указанным именем или адресом, принявшее сообщение, может идентифицировать сервер (по аргументам или, например, адресу отправителя в IP сети) и подключиться к нему.

Отправка сообщений устройству, находящемуся за хабом, происходит аналогично отправке сообщений самому устройству, но к каждому сообщению добавляется в начало два аргумента: специальный идентификатор "#hub" и идентификатор целевого устройства в виде текстового шестнадцатеричного представления UUID "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx". Аналогичным образом приходят ответные сообщения: заголовок "#hub", идентификатор отправителя, дальше само сообщение. Для отправки сообщения всем устройствам за хабом используется идентификатор "#broadcast".

Нотификационные сообщения от хаба:

1. Появление устройства за хабом. Заголовок — device_identified (после заголовка #hub и идентификатора отправителя. Аргумент — название устройства.
   Пример:
   #hub|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx|device_identified|test1\n

2. Отключение устройства от хаба. Заголовок — device_lost.
   Пример:
   #hub|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx|device_lost\n

Зарезервированные названия команд

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

Формат описания датчиков (xml или json)

Описание датчиков представляет собой xml или json документ, которому соответствует список датчиков с атрибутами. Для каждого датчика указывается имя, отображаемое название, тип, единицы измерения (строка, например "оС", "м/с2" и т.д.) и дополнительные атрибуты. Имя сенсора уникально в пределах устройства. Тип датчика описывает формат передаваемых устройством данных и способ представления в сообщении. Форматы передаваемых значений описаны ниже в разделе "Форматы данных датчиков". Описание датчиков передается между устройствами в xml или json формате, соответствующие схемы приложены в отдельных файлах sensors.xsd, sensors_simplified.xsd, sensors.json-schema, sensors_simplified.json-schema.

Примеры:

<sensors>
<sensor name="temperature" title="Temperature in celsius from 1st and 2nd thermometers" type="s_f32_d2" unit="оС">
<attributes min="-50" max="50"/>
</sensor>
<sensor><!--sensor definition--></sensor>
</sensors>

{"sensors" : [
{
"name" : "temperature",
"title" : " Temperature in celsius",
"type" : "s_f32",
"unit" : "оС",
"attributes" :
{
"min" : "-50",
"max" : "50"
}
},
{
//sensor definition
}
]}

Форматы данных датчиков

В различных форматах могут использоваться метки локального и глобального времени. Локальное время — время, измеряемое на устройстве от какой-то фиксированной точки (но не известной), например — от момента включения устройства. Глобальное время — количество миллисекунд, прошедшее с 01.01.1970г. В бинарном виде временная метка — всегда 64-битное целое число со знаком. Использование глобального времени возможно при наличии на устройстве часов реального времени. Временная метка всегда передается в начале измерения.

Строка формата датчика представляет собой набор ключей, разделенных символом "_". Ключ представляет собой набор символов, которые объединены в группы. Из каждой группы может присутствовать только один ключ.

Ключи, описывающие тип чисел в измерениях

Ключ, описывающий размерность отсчета:

Ключи, описывающие количество значений в одном измерении:

Ключи, описывающие временную метку измерения:

Примеры (название датчика — всегда test):

Формат описания интерфейса

Элементы управления устройством объединены в группы, содержащие сами элементы управления и дочерние группы. В группе может быть задано горизонтальное или вертикальное размещение элементов. Если не задано — по умолчанию по вертикали.

Для каждого элемента управления задается команда, пересылаемая устройству, человеко-читаемое название элемента, список параметров и дополнительные атрибуты. Параметры команды добавляются в порядке следования в описании.

Если параметры для элемента управления не заданы, отображается кнопка, при нажатии отправляется команда без параметров. Если задан один параметр, генерируется один элемент UI в зависимости от типа параметра, при взаимодействии с которым отправляется команда, и кнопка только при необходимости, например, для поля ввода. Если параметры заданы, но присутствует атрибут "force_button" со значением "1", генерируется набор элементов UI согласно заданному размещению, соответствующих типам параметров, и кнопка, при нажатии на которую отправляется команда. Если атрибут "force_button" отсутствует, команда генерируется автоматически при изменении состояния элементов UI. Каждый параметр команды имеет набор атрибутов, различающихся в зависимости от типа. Если присутствует атрибут "button_text", он задает текст на кнопке.

Описание элементов управления передается между устройствами в xml или json формате, соответствующие схемы приложены в отдельных файлах controls.xsd, controls_simplified.xsd, controls.json-schema, controls_simplified.json-schema.

Примеры:

<controls>
<group title="$title" layout="v|h">
<group title="$title" layout="v|h">
<control title="$title" command="$cmd" layout="v|h">
<param title="$title" type="$type">
<attributes key1="$value1" key2="$value2"/>
</param>
<param><!--param definition--></param>
</control>
<control title="$title" command="$cmd" layout="v|h" force_button="1" button_text="Some text">
<!-- control definition-->
</control>
</group>
<control><!--command definition--></control>
<group><!--group definition--></group>
</group>
</controls>

{"controls" : {
"element_type" : "group",
"title" : "$title",
"layout" : "v|h",
"elements" :
[
{
"element_type" : "group"
//group definition
},
{
"element_type" : "control",
"title" : "$title",
"layout" : "v|h",
"command" : "$command",
"button_text": "Some text",
"params" : [
{
"title" : "$title",
"type" : "$type",
"constraints" :
{
"$key1" : "$value1",
"$key2" : "$value2"
}
}
]
}

]
}}

Типы параметра и возможные атрибуты

Состояние устройства

Состояние управляющего интерфейса устройства описывает текущие значения параметров команд устройства и значения дополнительных параметров, не связанных с интерфейсом управления. При изменении состояния устройство оповещает об этом подключенного клиента при помощи специального сообщения "statechanged". Аргументы сообщения сгруппированы по 3. Первым аргументом в группе идет команда, параметр которой изменился, или "#", если изменился дополнительный параметр, не связанный ни с какой командой. В первом случае вторым аргументом в группе идет номер аргумента команды (начиная с 1), во втором — название дополнительного параметра. Третий аргумент в группе — значение параметра. При запросе всего состояния устройства при помощи зарезервированной команды "#state" возвращается все состояние устройства в одном сообщении с заголовком "ok" и аргументами, сгруппированными по 3 по аналогии с сообщением "statechanged".