Документ описывает сервер для автономного сбора данных с устройств IoT и управления этими устройствами, а также протокол взаимодействия с IoT сервером через доступные для управления каналы связи.
Настройки сервера хранятся в конфигурационном ini-файле /etc/wliotproxyd.ini. При установке в конфигурационном файле присутствует описание всех параметров. Дополнительно используется файл /var/lib/wliotproxyd/devices.ini, но его ручное редактирование не обязательно.
Локальный UNIX-сокет "/tmp/wliotproxyd"
Tcp порт 4083 с поддержкой ssl шифрования. При подключении по tcp обязательна аутентификация с ключем, указанным в файле.
Протокол взаимодействия между устройствами на шине практически полностью основан на протоколе взаимодействия с единичным устройством. Для организации взаимодействия устройств на шине дополнительно вводятся следующие правила:
Аргументы каждого сообщения-команды от клиента к серверу начинаются с идентификаторы вызова — числа, которое сервер также указывает в начале аргументов ответного сообщения, в том числе в сообщениях ok, err и cmdata. В сообщениях, не предполагающих ответа, таких как info или уведомления от сервера клиенту, идентификатор вызова не указывается.
Информационное сообщение. Заголовок — info. Предназначено для передачи информации, не требующей специальной обработки (например, отладочная информация) и предназначенной для передачи ее человеку. Аргументы сообщения — текстовые строки, содержащие информацию, предназначенную для прочтения человеком.
Сообщение с данными для клиента (или от клиента). Заголовок — cmdata. Первый аргумент всегда — идентификатор вызова, в описании конкретных команд ниже по тексту опущен. Предназначено для передачи данных между клиентом и сервером при обработке команд.
Команда аутентификации. Заголовок — authenticate. Параметры — имя пользователя и пароль. Команда необходима для подключения к удаленному серверу по tcp.
Идентификация сервера. Заголовок — identify. Сервер возвращает уникальный идентификатор в формате UUID и свое имя.
Перечисление всех имеющихся в системе TTY устройств. Заголовок — list_tty. Аргументы отсутствуют. Список устройств передается на клиент сообщениями cmdata, содержащими следующие аргументы: имя порта, серийный номер, производитель, usb vendor id (число), usb product id (число). Если устройство идентифицировано, дополнительно передаются два аргумента — идентификатор и имя устройства.
Идентификация TTY устройства. Заголовок — indentify_tty. Аргумент — имя порта. В случае успешной идентификации клиенту в ответ возвращаются идентификатор устройства, имя устройства и опционально идентификатор типа устройства (в ответном ok сообщении)
Идентификация TCP устройства. Заголовок — indentify_tcp. Аргумент — IP адрес или имя хоста. В случае успешной идентификации клиенту в ответ возвращаются идентификатор устройства, имя устройства и опционально идентификатор типа устройства (в ответном ok сообщении).
Перечисление идентифицированных устройств. Заголовок — list_identified. Аргументы отсутствуют. На клиент передаются сообщения cmdata со следующими аргументами: идентификатор устройства, имя устройства, идентификатор типа устройства, порт или сетевой адрес устройства.
Перечисление датчиков устройства. Заголовок — list_sensors. Агрумент — идентификатор или имя устройства. Список портов передается на клиент в ответном ok сообщении, содержащим аргумент — xml описание сенсоров.
Запрос описания интерфейса управления. Заголовок — list_controls. Агрумент — идентификатор или имя устройства. Описание интерфейса управления передается на клиент в ответном ok сообщении, содержащим аргумент — xml описание интерфейса управления.
Отправка команды устройству. Заголовок — exec_command. Аргументы — идентификатор или имя устройства, команда, далее аргументы команды. В случае ожидания возвращаемого значения на клиент в аргументах сообщения ok будут переданы аргументы, возвращенные устройством.
Управление конфигурацией устройств. Заголовок — devices_config. Содержит вложенные команды. Управление конфигурацией устройств подробно описано ниже. Конфигурация устройств определяет, какие устройства сервер будет обнаруживать и идентифицировать самостоятельно при запуске.
Запрос идентификатора устройства. Заголовок — device_id. Аргумент — идентификатор или имя устройства. Сервер ищет устройство в списке идентифицированных устройств или в базе хранилищ и возвращает его идентификатор. Если устройство не найдено или найдено несколько с одинаковым именем, возвращается ошибка. Эта команда позволяет получить
Управление конфигурацией устройств на сервере производится с помощью сообщения с заголовком devices_config. Аргументы сообщения содержат вложенную команду и ее собственные аргументы. Пример:
"devices_config|get_tty_by_port_name\n"
Ниже приведено описание доступных команд.
Запрос списка фильтров tty устройств по имени порта. Команда — get_tty_by_port_name. Аргументы отсутствуют. Возвращает список фильтров по имени tty порта в виде регулярных выражений UNIX, разделенных запятой. Пример:
"ttyACM*,ttyUSB0,ttyUSB2,ttyS0"
Установка списка фильтров tty устройств по имени порта. Команда — set_tty_by_port_name. Аргумент — список фильтров по имени tty порта в виде регулярных выражений UNIX, разделенных запятой.
Запрос списка фильтров tty устройств по VIP и PID USB устройства (для преобразователей USB-COM). Команда — get_tty_by_vid_pid. Аргументы отсутствуют. Возвращает список фильтров по VID и PID USB устройства, разделенных запятой. Каждый фильтр — пара VID:PID или только VID, все в нижнем регистре. Пример:
"1111:2222,3333,4444:5555"
Установка списка фильтров tty устройств по VIP и PID USB устройства. Команда — set_tty_by_vid_pid. Аргумент — список фильтров фильтров по VID и PID USB устройства, разделенных запятой.
Запрос списка адресов tcp устройств. Команда — get_tcp_by_address. Аргументы отсутствуют. Возвращает список адресов tcp устройств (IP-адрес или DNS имя хоста), разделенных запятой. Пример:
"192.168.1.1,example.com"
Установка списка адресов tcp устройств. Команда — set_tcp_by_address. Аргумент — список адресов tcp устройств (IP-адрес или DNS имя хоста), разделенных запятой.
Включение/выключение автоматического поиска устройств в локальной сети. Команда — set_detect_tcp_devices. Аргумент — true|false или 1|0. Если "true" или "1" — сервер регулярно рассылает в сеть широковещательные запросы, устройства определяют адрес сервера и подключаются к нему.
Перечисление хранилищ. Заголовок — list_storages. Аргументы отсутствуют. Список хранилищ передается на клиент сообщениями cmdata, содержащими следующие аргументы:
идентификатор устройства
имя устройства
имя датчика
тип значений датчика
атрибуты датчика в виде "key1=value1;key2=value2"
тип хранилища (continuous, auto_sessions, last_n_values,memory)
правило преобразования временной метки (dont_touch, add_gt, drop_time)
тип хранимых значений (зависит от правила преобразования временной метки)
Добавление датчика в базу. Заголовок — add_storage. Аргументы: идентификатор или имя устройства, название датчика, тип хранилища (continuous, auto_sessions, last_n_values, memory), правило преобразования временной метки (dont_touch, add_global_time, drop_time). Для хранилища типа last_n_values и memory дополнительно передается параметр N — число хранимых значений. При создании хранилища устройство с датчиком должно быть подключено и идентифицировано.
Удаление сенсора из базы. Заголовок — remove_storage. Аргументы: идентификатор или имя устройства, название датчика.
Привязка сенсора к внешнему IoT сервису. Заголовок — storage_add_data_export. Аргументы: имя или идентификатор устройства, название датчика, название сервиса. Далее идут параметры для сервиса в формате ключ:значение. Если параметры отсутствуют, привязка удаляется.
Запрос привязки сенсора к внешнему IoT сервису. Заголовок — storage_get_data_export. Аргументы: имя или идентификатор устройства, название датчика, название сервиса. Если хранилище привязано к внешнему сервису, возвращаются параметры в формате ключ:значение, в противном случае возвращается ошибка.
Запрос списка внешних сервисов, в которые экспортируются данные из хранилища. Заголовок — storage_get_data_export_list. Возвращается список названий сервисов.
Запрос списка доступных внешних сервисов для экспорта. Заголовок — available_data_export_services. Возвращается список названий сервисов.
Установка и получение атрибута хранилища. Заголовки — storage_get_attr, storage_set_attr. Аргументы: имя или идентификатор устройства, название датчика, название атрибута, значение атрибута (для set). Get возвращает значение атрибута.
Перечисление сессий для сессионного хранилища. Заголовок — session_list. Аргументы — идентификатор или имя устройства и название датчика. Список сессий передается сообщениями cmdata, содержащими два параметра — идентификатор и название сессии.
Перечисление атрибутов сессии для сессионного хранилища. Заголовок — session_list_attrs. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии. Список атрибутов сессий передается сообщениями cmdata, содержащими два параметра — ключ и значение атрибута.
Получения атрибута сессии для сессионного хранилища. Заголовок — session_get_attr. Аргументы — идентификатор или имя устройства, название датчика, идентификатор сессии и название атрибута. В ответ возвращается значение атрибута.
Установка атрибута сессии для сессионного хранилища. Заголовок — session_set_attr. Аргументы — идентификатор или имя устройства, название датчика, идентификатор сессии, название атрибута и значение атрибута. Значение атрибута опционально, если отсутствует — атрибут удаляется.
Создание новой сесии. Заголовок — session_create. Аргументы — идентификатор или имя устройства, название датчика и название сессии. В ответ возвращается идентификатор созданной сессии.
Запуск ручной сессии. Заголовок — session_start. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии. Сессия открывается на запись и начинается сбор данных.
Остановка ручной сессии. Заголовок — session_stop. Аргументы — идентификатор или имя устройства и название датчика. Останавливает открытую для записи сессию.
Удаление сессии. Заголовок — session_remove. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии.
Продолжение ручной сессии. Заголовок — session_continue. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии. Открывает для дальнейшей записи ранее созданную сессию.
Запрос идентификатора открытой для записи сессии. Заголовок — session_get_write_id. Аргументы — идентификатор или имя устройства и название датчика. Если есть открытая для записи сессия, возвращает ее идентификатор.
Перечисление списка javascript-программ. Заголовок — js_list. Возвращает список javascript-файлов на стороне сервера.
Остановка, запуск и перезапуск javascript-программы для обработки данных. Заголовки — js_start, js_stop и js_restart. Аргумент — имя файла скрипта (с расширением .js).
Запрос количества данных в локальном хранилище. Заголовок — get_samples_count. Аргументы — идентификатор или имя устройства, имя датчика, для сессионного хранилища дополнительно идентификатор сессии. Возвращается количество отсчетов в хранилище.
Запрос данных из локального хранилища. Заголовок — get_samples. Аргументы — идентификатор устройства, имя датчика, для сессионного хранилища дополнительно идентификатор сессии, начальный индекс (начинается с 0), количество отсчетов. Дополнительный аргумент — шаг (для прореживания данных, может отсутствовать). Отсчеты возвращаются в сообщениях cmdata, по одному отсчету на сообщение. Данные передаются в том же формате, как и в сообщениях от устройства (meas).
Запрос данных из локального хранилища в бинарном. Заголовок — get_samples_bin. Аргументы — идентификатор устройства, имя датчика, для сессионного хранилища дополнительно идентификатор сессии, начальный индекс (начинается с 0), количество отсчетов. Дополнительный аргумент — шаг (для прореживания данных, может отсутствовать). Отсчеты возвращаются в сообщениях cmdata, по одному отсчету на сообщение. Данные передаются в том же формате, как и в сообщениях от устройства (measb).
"Подключение" виртуального устройства. Заголовок — register_virtual_device. Аргументы — идентификатор устройства, имя устройства и опционально идентификатор типа устройства.
Подписка/отписка на данные от датчика из хранилища. Заголовки — subscribe/unsubscribe. Аргументы — идентификатор или имя устройства и название датчика. Если клиент подписан на датчик из хранилища, то появлении нового измерения в хранилище клиенту будет передано сообщение meas, содержащее идентификатор устройства, название датчика и значение в том же формате, как и от устройства.
Идентификация устройства. Заголовок — device_identified. Аргументы — идентификатор устройства, имя устройства, опционально идентификатор типа устройства.
Отключение устройства. Заголовок — device_lost. Аргумент — идентификатор устройства.
Добавление хранилища для датчика — storage_created. Агрументы:
идентификатор устройства
имя устройства
имя датчика
тип значений датчика
ограничения значений в виде "key1=value1;key2=value2"
тип хранилища (continuous, auto_sessions, last_n_values,memory)
правило преобразования временной метки (dont_touch, add_gt, drop_time)
тип хранимых значений (зависит от правила преобразования временной метки)
Удаление хранилища для датчика — storage_removed. Агрументы — идентификатор устройства и название датчика.
Изменение состояния устройства — statechanged. Аргументы аналогичны аргументам сообщения statechanged от устройства серверу (см. описание протокола взаимодействия между устройствами), но в начале добавлен идентификатор устройства.
Уведомление о необходимости перезагрузить список устройств и хранилищ. Заголовок — reload_devices_and_storages. Сообщает о необходимости перезагрузить список устройств и хранилищ на стороне клиента, например, при изменении политики доступа к устройствам.
Синхронизация виртуального устройства. Для виртуальных устройств, зарегистрированных клиентом, сервер регулярно передает сообщение vdev_sync, в ответ клиент должен в течении 4 секунд вернуть сообщение syncr. Аргумент обоих сообщений — идентификатор виртуального устройства.
Когда клиент регистрирует виртуальное устройство на сервере, необходимо передавать клиенту сообщения, предназначенные для виртуального устройства, и получать от него сообщения, "исходящие" от виртуального устройства. Для этого сообщения (такие же, как для обычных устройств), "упаковываются" в сообщение с заголовком vdev. Например, в случае выполнения команды на обычном устройстве сервер использует сообщение
call|1|command\n
и получает в ответ сообщение
ok|1\n
Для виртуального устройства сервер пошлет клиенту сообщение
vdev|{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}|call|1|command\n
и получит в ответ
vdev|{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}|ok|1\n
Если в настройках сервера включено автоматическое обнаружение устройств в IP сетях, то сервер будет регулярно рассылать широковещательное сообщение через UDP порт 4081. Заголовок сообщения — server_ready, аргументы — идентификатор и имя сервера.
|
Название сервиса |
Описание |
Параметры |
|
iotkit-agent |
Сервис для интернета вещей от Intel (https://github.com/enableiot/iotkit-agent) |
sensor_name — имя сенсора для программы iotkit-agent, под которым будут передаваться данные |
|
alterozoom |
IoT сервис Alterozoom |
email — user email in Alterozoom (use wliotproxy-alterozoom-auth util to authentificate user and get token to send data) |
|
thingspeak |
ThingSpeak service (https://thingspeak.com) |
api_key — write api key for a channel (see https://www.mathworks.com/help/thingspeak/writedata.html) |
Скрипты для обработки данных располагаются в директории "/var/lib/wliotproxyd/js_data_processing". Каждый скрипт выполняется независимо. Внутри скрипта доступна по-умолчанию стандартная математическая библиотека и набор дополнительных объектов, описанный ниже. Так же для отладки можно использовать метод Console.log().
Глобальный объект скрипта, аналог window в браузерных скриптах.
SensorsDatabase — объект, предоставляющий доступ к базе хранилищ датчиков
Devices — объект, предоставляющий доступ к списку подключенных устройств
Объект, предоставляющий доступ к базе хранилищ датчиков.
isOpened — возвращает true/false, в зависимости от того, открыта ли база или нет
listSensors — возвращает массив идентификаторов хранилищ StorageId (объект с ключами "deviceId" и "sensorName", deviceId — идентификатор устройства, строка в формате UUID, sensorName — название датчика на устройстве, строка).
existingStorage — возвращает объект Storage, предоставляющий доступ к хранилищу данных для датчика.
Параметры
StorageId id — идентификатор хранилища
createStorage — создает хранилище для данных с датчика (можно использовать для сохранения результатов обработки в базу данных датчиков) и возвращает объект Storage или null в случае ошибки
Параметры:
Объект, описывающий создаваемое хранилище. Должен содержать следующие свойства:
String deviceId — идентификатор устройства (строка в формате UUID)
String sensorName — название датчика
String storeMode — режим хранения данных ("continuous", "manual_sessions", "memory" или "last_n_values")
String tsRule — правило преобразования временной метки ("dont_touch", "add_global_time" или "drop_time"), по-умолчанию add_global_time
Number N — количество отсчетов для режима "last_n_values"
opened — выдается при открытии базы хранилищ
closed — выдается при закрытии базы хранилищ
storageCreated — выдается при создании нового хранилища
Параметры
StorageId id — идентификатор хранилища
storageRemoved — выдается при удалении хранилища
Параметры
StorageId id — идентификатор хранилища
Объект, предоставляющий доступ к управлению устройствами.
devices — возвращает массив идентификаторов подключенных устройств (строки в формате UUID)
device — возвращает объект Device, предоставляющий доступ к подключенному устройству
Параметры
String id — идентификатор или имя устройства (если имя не уникальное, нужно использовать идентификатор)
registerVirtualDevice — регистрирует виртуальное устройство, возвращает объект VirtualDevice, позволяющий управлять поведением устройства из скрипта
Параметры
String id — идентификатор устройства
String name — название устройства
String typeIdStr — идентификатор типа устройства (может быть null)
String sensorsStr — строка, содержащая xml или json описание списка датчиков
String contorlsStr — строка, содержащая xml или json описание интерфейса управления (опционально)
deviceIdentified — выдается при идентификации устройства
Параметры
String id — идентификатор устройства
String name — название устройства
String typeId — идентификатор типа устройства (может быть null)
deviceDisconnected — выдается при отключении устройства
Параметры
String id — идентификатор устройства
Объект, предоставляющий доступ к хранилищу данных датчика
isOpened — возвращает true, если хранилище открыто
valuesType — тип значений в хранилище (строка, см. описание протокола взаимодействия между устройствами)
deviceId — возвращает идентификатор устройства
deviceName — возвращает название устройства
sensorName — возвращает название датчика
readAttribute — возвращает значение привязанного к базе атрибута
Параметры
String key — ключ
valuesCount — возвращает количество записей в базе (измерений)
valueAt — возвращает измерение — объект SensorValue
Параметры
index — индекс записи в базе (0-based)
getStoreMode — возвращает тип самой базы, определяющий способ хранения значений в базе (continuous, manual_sessions, auto_sessions, last_n_values или memory)
newValueWritten — выдается, когда в базу записывается новое значение
Параметры
SensorValue value — записанное значение
//TODO
Объект, предоставляющий доступ к подключенным устройствам
isIdentified — возвращает true, если устройство идентифицировано
id — возвращает идентификатор устройства
name — возвращает название устройства
sendCommand — выполняет команду на устройстве и возвращает ответ устройства (объект с ключами ok (true|false) и value (список строк, возвращенных устройством))
Параметры
String cmd — команда устройству
Array args — параметры команды (массив строк)
identificationChanged — выдается, когда устройство подключается или отключается
Объект, позволяющий организовать виртуальное устройство, управляемое из скрипта. Является наследником Device.
writeInfo — генерирует сообщение info от устройства
Параметры
Array args — аргументы сообщения
writeMeasurement — генерирует сообщение от устройства, содержащее измерение
Параметры
String name — название датчика
SensorValue value — измерение (объект SensorValue)
setCommandCallback — устанавливает функцию-обработчик для команд устройству
Параметры
Function func — javascript-функция обработчик (должна принимать 2 параметра — строка-команда и массив строк — аргументы команды) и возвращать: объект с ключами done (true или false) и result (возвращаемое значение) или просто true или false
commandParamStateChanged — генерирует сообщение об изменении состояния параметра команды устройства
Параметры
String cmd — команда
Number paramIndex — номер параметра команды (начиная с 1)
value — новое значение параметра (строка или число)
additionalStateChanged — генерирует сообщение об изменении дополнительного состояния устройства
Параметры
String paramName — название параметра
value — новое значение параметра (строка или число)
syncMsgNotify — выдается, когда устройство получает от сервера сообщение синхронизации
time — временная метка (для значений без метки времени отсутствует, для локального времени устройства — число, для глобального времени — javascript тип Date)
data — массив значений (строки для строковых измерений, числа для остальных)