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

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

Конфигурационный файл сервера

Настройки сервера хранятся в конфигурационном ini-файле /etc/wliotproxyd.ini. При установке в конфигурационном файле присутствует описание всех параметров. Дополнительно используется файл /var/lib/wliotproxyd/devices.ini, но его ручное редактирование не обязательно.

Доступные каналы для управления IoT сервером

1. Локальный UNIX-сокет "/tmp/wliotproxyd"

2. Tcp порт 4083 с поддержкой ssl шифрования. При подключении по tcp обязательна аутентификация с ключем, указанным в файле.

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

Протокол взаимодействия между устройствами на шине практически полностью основан на протоколе взаимодействия между устройствами по принципу "точка-точка" (далее — протокол PTP). Для организации взаимодействия устройств на шине дополнительно вводятся следующие правила:

1. Аргументы каждого сообщения-команды от клиента к серверу начинаются с идентификаторы вызова — числа, которое сервер также указывает в начале аргументов ответного сообщения, в том числе в сообщениях ok, err и cmdata. В сообщениях, не предполагающих ответа, таких как info или уведомления от сервера клиенту, идентификатор вызова не указывается.

Базовые типы сообщений

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

2. Сообщение с данными для клиента (или от клиента). Заголовок — cmdata. Первый аргумент всегда — идентификатор вызова, в описании конкретных команд опущен. Предназначено для передачи данных между клиентом и сервером при обработке команд.

Команды серверу

Общее

1. Команда аутентификации. Заголовок — authentificate. Параметр — ключ аутентификации. Команда необходима для подключения к удаленному серверу по tcp.

2. Идентификация сервера. Заголовок — identify. Сервер возвращает уникальный идентификатор в формате UUID и свое имя.

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

1. Перечисление всех имеющихся в системе TTY устройств. Заголовок — list_tty. Аргументы отсутствуют. Список устройств передается на клиент сообщениями cmdata, содержащими следующие аргументы: имя порта, серийный номер, производитель, usb vendor id (число), usb product id (число). Если устройство идентифицировано, дополнительно передаются два аргумента — идентификатор и имя устройства.

2. Идентификация TTY устройства. Заголовок — indentify_tty. Аргумент — имя порта. В случае успешной идентификации клиенту в ответ возвращаются идентификатор устройства и имя устройства (в ответном ok сообщении).

3. Идентификация TCP устройства. Заголовок — indentify_tcp. Аргумент — IP адрес или имя хоста. В случае успешной идентификации клиенту в ответ возвращаются идентификатор устройства и имя устройства (в ответном ok сообщении).

4. Перечисление идентифицированных устройств. Заголовок — list_identified. Аргументы отсутствуют. На клиент передаются сообщения cmdata со следующими аргументами: идентификатор устройства, имя устройства, тип соединения (tty, tcp и т. д.), порт или сетевой адрес устройства.

5. Перечисление датчиков устройства. Заголовок — list_sensors. Агрумент — идентификатор или имя устройства. Список портов передается на клиент в ответном ok сообщении, содержащим аргумент — xml описание сенсоров.

6. Запрос описания интерфейса управления. Заголовок — list_controls. Агрумент — идентификатор или имя устройства. Описание интерфейса управления передается на клиент в ответном ok сообщении, содержащим аргумент — xml описание интерфейса управления.

7. Отправка команды устройству. Заголовок — exec_command. Аргументы — идентификатор или имя устройства, команда, далее аргументы команды. В случае ожидания возвращаемого значения на клиент в аргументах сообщения ok будут переданы аргументы, возвращенные устройством.

8. Управление конфигурацией устройств. Заголовок — devices_config. Содержит вложенные команды. Управление конфигурацией устройств подробно описано ниже. Конфигурация устройств определяет, какие устройства сервер будет обнаруживать и идентифицировать самостоятельно при запуске.

9. Запрос идентификатора устройства. Заголовок — device_id. Аргумент — идентификатор или имя устройства. Сервер ищет устройство в списке идентифицированных устройств или в базе хранилищ и возвращает его идентификатор. Если устройство не найдено или найдено несколько с одинаковым именем, возвращается ошибка. Эта команда позволяет получить

Управление конфигурацией устройств

Управление конфигурацией устройств на сервере производится с помощью сообщения с заголовком devices_config. Аргументы сообщения содержат вложенную команду и ее собственные аргументы. Пример:

"devices_config|get_tty_by_port_name\n"

Ниже приведено описание доступных команд.

1. Запрос списка фильтров tty устройств по имени порта. Команда — get_tty_by_port_name. Аргументы отсутствуют. Возвращает список фильтров по имени tty порта в виде регулярных выражений UNIX, разделенных запятой. Пример:
   "ttyACM*,ttyUSB0,ttyUSB2,ttyS0"

2. Установка списка фильтров tty устройств по имени порта. Команда — set_tty_by_port_name. Аргумент — список фильтров по имени tty порта в виде регулярных выражений UNIX, разделенных запятой.

3. Запрос списка фильтров tty устройств по VIP и PID USB устройства (для преобразователей USB-COM). Команда — get_tty_by_vid_pid. Аргументы отсутствуют. Возвращает список фильтров по VID и PID USB устройства, разделенных запятой. Каждый фильтр — пара VID:PID или только VID, все в нижнем регистре. Пример:
   "1111:2222,3333,4444:5555"

4. Установка списка фильтров tty устройств по VIP и PID USB устройства. Команда — set_tty_by_vid_pid. Аргумент — список фильтров фильтров по VID и PID USB устройства, разделенных запятой.

5. Запрос списка адресов tcp устройств. Команда — get_tcp_by_address. Аргументы отсутствуют. Возвращает список адресов tcp устройств (IP-адрес или DNS имя хоста), разделенных запятой. Пример:
   "192.168.1.1,example.com"

6. Установка списка адресов tcp устройств. Команда — set_tcp_by_address. Аргумент — список адресов tcp устройств (IP-адрес или DNS имя хоста), разделенных запятой.

7. Включение/выключение автоматического поиска устройств в локальной сети. Команда — set_detect_tcp_devices. Аргумент — true|false или 1|0. Если "true" или "1" — сервер регулярно рассылает в сеть широковещательные запросы, устройства определяют адрес сервера и подключаются к нему.

Управление хранилищами для данных сенсоров

1. Перечисление хранилищ. Заголовок — list_storages. Аргументы отсутствуют. Список хранилищ передается на клиент сообщениями cmdata, содержащими следующие аргументы:

   1. идентификатор устройства

   2. имя устройства

   3. имя датчика

   4. тип значений датчика

   5. атрибуты датчика в виде "key1=value1;key2=value2"

   6. тип хранилища (continuous, auto_sessions, last_n_values,memory)

   7. правило преобразования временной метки (dont_touch, add_gt, drop_time)

   8. тип хранимых значений (зависит от правила преобразования временной метки)

2. Добавление датчика в базу. Заголовок — add_storage. Аргументы: идентификатор или имя устройства, название датчика, тип хранилища (continuous, auto_sessions, last_n_values, memory), правило преобразования временной метки (dont_touch, add_global_time, drop_time). Для хранилища типа last_n_values и memory дополнительно передается параметр N — число хранимых значений. При создании хранилища устройство с датчиком должно быть подключено и идентифицировано.

3. Удаление сенсора из базы. Заголовок — remove_storage. Аргументы: идентификатор или имя устройства, название датчика.

4. Привязка сенсора к внешнему IoT сервису. Заголовок — bind_storage. Аргументы: имя или идентификатор устройства, название датчика, название сервиса. Далее идут параметры для сервиса в формате ключ:значение. Если параметры отсутствуют, привязка удалается.

5. Перечисление сессий для сессионного хранилища. Заголовок — session_list. Аргументы — идентификатор или имя устройства и название датчика. Список сессий передается сообщениями cmdata, содержащими два параметра — идентификатор и название сессии.

6. Перечисление атрибутов сессии для сессионного хранилища. Заголовок — session_list_attrs. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии. Список атрибутов сессий передается сообщениями cmdata, содержащими два параметра — ключ и значение атрибута.

7. Получения атрибута сессии для сессионного хранилища. Заголовок — session_get_attr. Аргументы — идентификатор или имя устройства, название датчика, идентификатор сессии и название атрибута. В ответ возвращается значение атрибута.

8. Установка атрибута сессии для сессионного хранилища. Заголовок — session_set_attr. Аргументы — идентификатор или имя устройства, название датчика, идентификатор сессии, название атрибута и значение атрибута. Значение атрибута опционально, если отсутствует — атрибут удаляется.

9. Создание новой сесии. Заголовок — session_create. Аргументы — идентификатор или имя устройства, название датчика и название сессии. В ответ возвращается идентификатор созданной сессии.

10. Запуск ручной сессии. Заголовок — session_start. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии. Сессия открывается на запись и начинается сбор данных.

11. Остановка ручной сессии. Заголовок — session_stop. Аргументы — идентификатор или имя устройства и название датчика. Останавливает открытую для записи сессию.

12. Удаление сессии. Заголовок — session_remove. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии.

13. Продолжение ручной сессии. Заголовок — session_continue. Аргументы — идентификатор или имя устройства, название датчика и идентификатор сессии. Открывает для дальнейшей записи ранее созданную сессию.

14. Запрос идентификатора открытой для записи сессии. Заголовок — session_get_write_id. Аргументы — идентификатор или имя устройства и название датчика. Если есть открытая для записи сессия, возвращает ее идентификатор.

Обработка данных

1. Перечисление списка javascript-программ. Заголовок — js_list. Возвращает список javascript-файлов на стороне сервера.

2. Остановка, запуск и перезапуск javascript-программы для обработки данных. Заголовки — js_start, js_stop и js_restart. Аргумент — имя файла скрипта (с расширением .js).

3. Запрос количества данных в локальном хранилище. Заголовок — get_samples_count. Аргументы — идентификатор или имя устройства, имя датчика, для сессионного хранилища дополнительно идентификатор сессии. Возвращается количество отсчетов в хранилище.

4. Запрос данных из локального хранилища. Заголовок — get_samples. Аргументы — идентификатор устройства, имя датчика, для сессионного хранилища дополнительно идентификатор сессии, начальный индекс (начинается с 0), количество отсчетов. Дополнительный аргумент — шаг (для прореживания данных, может отсутствовать). Отсчеты возвращаются в сообщениях cmdata, по одному отсчету на сообщение. Данные передаются в том же формате, как и в сообщениях от устройства (meas).

5. "Подключение" виртуального устройства. Заголовок — register_virtual_device. Аргументы — идентификатор устройства, имя устройства, описание сенсоров в формате xml или json.

6. Передача данных от виртуального устройства. Заголовок — vdev_meas. Первый аргумент — идентификатор устройства, второй — название датчика, дальше — данные как для сообщения meas от устройства.

7. Подписка/отписка на данные от датчика из хранилища. Заголовки — subscribe/unsubscribe. Аргументы — идентификатор или имя устройства и название датчика. Если клиент подписан на датчик из хранилища, то появлении нового измерения в хранилище клиенту будет передано сообщение meas, содержащее идентификатор устройства, название датчика и значение в том же формате, как и от устройства.

Уведомления от сервера клиенту

1. Идентификация устройства. Заголовок — device_identified. Аргументы — идентификатор и имя устройства.

2. Отключение устройства. Заголовок — device_lost. Аргумент — идентификатор устройства.

3. Добавление хранилища для датчика — storage_created. Агрументы:

   1. идентификатор устройства

   2. имя устройства

   3. имя датчика

   4. тип значений датчика

   5. ограничения значений в виде "key1=value1;key2=value2"

   6. тип хранилища (continuous, auto_sessions, last_n_values,memory)

   7. правило преобразования временной метки (dont_touch, add_gt, drop_time)

   8. тип хранимых значений (зависит от правила преобразования временной метки)

4. Удаление хранилища для датчика — storage_removed. Агрументы — идентификатор устройства и название датчика.

5. Изменение состояния устройства — statechanged. Аргументы аналогичны аргументам сообщения statechanged от устройства серверу (см. описание протокола взаимодействия между устройствами), но в начале добавлен идентификатор устройства.

6. Обработка команды виртуальному устройству — vdev_command. Первый аргумент — идентификатор вызова, второй — команда, далее параметры команды. Клиент должен вернуть ответное сообщение vdev_ok или vdev_err с тем же идентификатором вызова.

Широковещательные уведомления устройствам

Если в настройках сервера включено автоматическое обнаружение устройств в IP сетях, то сервер будет регулярно рассылать широковещательное сообщение через UDP порт 4081. Заголовок сообщения — server_ready, аргументы — идентификатор и имя сервера.

Поддерживаемые внешние IoT сервисы

Обработка данных на языке javascript

Скрипты для обработки данных располагаются в директории "/var/lib/wliotproxyd/js_data_processing". Каждый скрипт выполняется независимо. Внутри скрипта доступна по-умолчанию стандартная математическая библиотека и набор дополнительных объектов, описанный ниже. Так же для отладки можно использовать метод Console.log().

Объект script

Глобальный объект скрипта, аналог window в браузерных скриптах.

Свойства:

• SensorsDatabase — объект, предоставляющий доступ к базе хранилищ датчиков

• Devices — объект, предоставляющий доступ к списку подключенных устройств

Объект script.SensorsDatabase

Объект, предоставляющий доступ к базе хранилищ датчиков.

Методы

• 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 — идентификатор хранилища

Объект script.Devices

Объект, предоставляющий доступ к управлению устройствами.

Методы

• devices — возвращает массив идентификаторов подключенных устройств (строки в формате UUID)

• device — возвращает объект Device, предоставляющий доступ к подключенному устройству
  Параметры

  • String id — идентификатор или имя устройства (если имя не уникальное, нужно использовать идентификатор)

• registerVirtualDevice — регистрирует виртуальное устройство, возвращает объект VirtualDevice, позволяющий управлять поведением устройства из скрипта
  Параметры

  • String id — идентификатор устройства

  • String name — название устройства

  • String sensorsXml — строка, содержащая xml-описание списка датчиков

  • String contorlsXml — строка, содержащая xml-описание интерфейса управления (опционально)

Сигналы

• deviceIdentified — выдается при идентификации устройства
  Параметры

  • String id — идентификатор устройства

  • String name — название устройства

• deviceDisconnected — выдается при отключении устройства
  Параметры

  • String id — идентификатор устройства

Объект Storage

Объект, предоставляющий доступ к хранилищу данных датчика

Методы

• 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

Объект Device

Объект, предоставляющий доступ к подключенным устройствам

Методы

• isIdentified — возвращает true, если устройство идентифицировано

• id — возвращает идентификатор устройства

• name — возвращает название устройства

• sendCommand — выполняет команду на устройстве и возвращает ответ устройства (объект с ключами ok (true|false) и value (список строк, возвращенных устройством))
  Параметры

  • String cmd — команда устройству

  • Array args — параметры команды (массив строк)

Сигналы

• identificationChanged — выдается, когда устройство подключается или отключается

Объект VirtualDevice

Объект, позволяющий организовать виртуальное устройство, управляемое из скрипта. Является наследником Device.

Методы

• writeMsgFromDevice — генерирует сообщение от устройства серверу
  Параметры

  • title — заголовок сообщения

  • args — аргументы сообщения (массив строк)

• writeInfo — генерирует сообщение info от устройства
  Параметры

  • args — аргументы сообщения

• writeMeasurement — генерирует сообщение от устройства, содержащее измерение
  Параметры

  • name — название датчика

  • value — измерение (объект SensorValue)

• setCommandCallback — устанавливает функцию-обработчик для команд устройству
  Параметры

  • Function func — javascript-функция обработчик (должна принимать 2 параметра — строка-команда и массив строк — аргументы команды)

• reconnect — переподсоединение устройства

Сигналы

• syncMsgNotify — выдается, когда устройство получает от сервера сообщение синхронизации

Объект SensorValue

Свойства

• type — тип значения (строка, см. описание протокола взаимодействия между устройствами)

• time — временная метка (для значений без метки времени отсутствует, для локального времени устройства — число, для глобального времени — javascript тип Date)

• count — количество значений в пакете для пакетных измерений, если отсутствует — 1 по-умолчанию

• data — массив значений (строки для строковых измерений, числа для остальных)