Перейти к содержанию

LoRa FS - Структура шаблонов

Описание структуры, параметров и правил для создания и редактирования LoRa-шаблонов

В шаблонах для LoRa описывается состав и формат данных, передаваемых между Node и Gateway, а также технические параметры и общая информация о шаблоне.

Шаблоны хранятся в файловой системе контроллера, выступающего в роли шлюза LoRa Gateway.

  • файлы шаблонов имеют расширение .lr
  • для доступа к файлам через веб-интерфейс используется вкладка EasyFS

Секции

Файл шаблона разделён на секции (или группы), каждая из которых содержит ряд связанных элементов описания.

LoRa-шаблоны используют синтаксис и структуру (упрощённый вариант), во многом схожую с Modbus-шаблонами.

Типы секций

В LoRa-шаблонах применяется два типа секций:

  • [main] - базовая секция, может содержать версию шаблона и другую общую информацию
  • [sensors] - секция "датчиков". Секция для описания передаваемых параметров

Секция [main]

Общие параметры шаблона. Может содержать:

  • ver - версия шаблона (актуально для шаблонов из каталога)
  • type - тип (актуально для авто-сгенерированных шаблонов)
    • type=1 - шаблоны от контроллеров Lavritech Node (применяется в файлах вида loralocalN.lr)

Секция [sensors]

Определяет формат передаваемых параметров (например, из списка метрик Node). Все возможные типы связей с системными параметрами (Sensors, GPIO, PWM) описываются через эту секцию.

В одном шаблоне может быть несколько секций этого типа.
Каждая секция описывает состав одного LoRa-пакета.

Секция может содержать следующие элементы:

  • fport - если присутствует, то устанавливает фильтр для секции по этому полю LoRa-пакета.
    • fport (число от 1 до 223) - позволяет указать виртуальный канал приёма данных
    • для авто-сгенерированных шаблонов fport назначается автоматически
    • если в шаблоне несколько секций [sensors] - fport указывать обязательно, он должен быть уникальным для каждого пакета в общей группе пакетов от Node
  • mask — список элементов, описывающий порядок и тип передаваемых значений в пакете.
    • определяет в каком порядоке и формате расшифровываются данные из пакета.
    • элементы в маске перечисляются через запятую. Каждый элемент маски соответствует одному значению.

Дополнительно

Для справки можно также использовать описание формата маски из Modbus-шаблонов.
LoRa-шаблоны частично поддерживают этот синтаксис.

Передача параметров

Здесь показан пример для передачи трёх параметров разных типов: Sensors, GPIO, PWM.
За основу взят сгенерированный шаблон из Node (маска из секции [sensors])

Пример маски: Sensor, GPIO, PWM
mask=e2t0,e1t1,e2t2
  • e2, e1, e2 - в данном случае определяет порядок и количество байт на значение.
    • Sensors может передавать как двумя, так и четырьмя байтами, в зависимости от значения
    • GPIO - занимают 1 байт
    • PWM - 2 байта
  • t - указывает тип метрики (тип значения). Здесь показаны основные типы для LoRa.
    • t0 - стандартный тип для Sensors-параметров. Таблица возможных типов метрик для Sensors-параметров указана в описании Modbus-шаблонов.
    • t1 - тип для GPIO
    • t2 - тип для PWM

Формирование маски - поле mask

В процессе применения маски данные из LoRa-пакета преобразуются в значения переменных.
К ним могут быть применены специальные правила для интерпретации (извлечения) значения из пакета, а также некоторые математические операции. В конце маски для переменной можно указать тип метрики для более удобного вывода её значения на главной странице.

Маски для чтения значений переменных из LoRa-пакета составляются по определённым правилам.
Поле mask может содержать несколько масок для переменных.
Маски для переменных перечисляются в поле mask через запятую.
При написании маски допустимо опускать число "1" (например, маски e1t0 и et0 идентичны)

Параметры

Ниже описаны параметры, которые применяются для формирования маски для переменной:

Примечание. Параметры маски выделены значками:
🔸 - обязательный параметр; 🔹 - дополнительный параметр

🔹 dX - делитель /10, /100, /1000
Описание параметра

Добавляет запятую после нужного разряда

Параметр позволяет преобразовать целое значение переменной (после извлечения из пакета) в дробное значение:

  • d1 - вывод одного знака после запятой (значение переменной / 10)
  • d2 - вывод 2-х знаков после запятой (значение переменной / 100)
  • d3 - вывод 3-х знаков после запятой (значение переменной / 1000)

Например, значение 1234 с маской e2d2 дает число 12,34

Если необходимо уменьшить точность, и совсем убрать знаки после запятой - нужно вместо параметра d использовать деление через математическое выражение. Например: для 32-разрядной переменной используем конструкцию вида: e4[/100], вместо e4d2

🔹 mX - множитель x10, x100, x1000
Описание параметра

Умножает значение переменной на множитель, кратный 10.
Значение множителя определяет X (max X=9)

  • m1 - x10
  • m2 - x100
  • m3 - x1000
  • ...

🔹 i - параметр указывает, что число имеет знак

🔹 f - float переменная
Описание параметра

Вывод значений с плавающей запятой из LoRa-пакета

Используются подпараметры fa и fb в зависимости от порядка байт в пакете.
Дополнительно можно указать количество знаков после запятой, по умолчанию 2.

🔹 l - модификатор типа: приводит 32 bit переменную к 16 bit e4l
Описание параметра

e4l - выражение такого вида служит для приведения 32-разрядных значений к 16 разрядам.
При этом старшая часть числа (старшие 16 бит) будет отброшена!

Внутреннее пространство переменных прошивки является 32-битным, но есть несколько опций, которые не имеют возможности полноценной работы с 32-битными значениями. Например переменные в опции "Термостат" и передаваемые метрики в опции "Lora" часто используют 16-битные значения. Модификатор "l" может быть полезен, когда нужно адаптировать данные из LoRa-пакета под использование в подобных случаях.

Модификатор l может указываться также после делителя d.
Примеры идентичных масок с использованием модификатора: e4d2l, e4ld2

🔹 tX - указывает тип переменной (тип метрики)
Список типов метрик
  • t0 - неизвестный датчик c положительными (+) целыми значениями - 16 или 32 bit (uint16_t, uint32_t)
  • t1 - тип для GPIO (дискретные значения 0/1)
  • t2 - тип для PWM (числовые значения)
  • t3 - температура (Temperature), °C (поддерживаются отрицательные значения)
  • t4 - относительная влажность (Humidity), %RH
  • t5 - давление (Pressure), mmHg
  • t6 - значение счётчика (Counter)
  • t7 - освещённость (Light), люкс (лк, lux)
  • t8 - концентрация CO2, ppm (миллионная доля)
  • t9 - напряжение (Voltage), В (V)
  • t10 - ток (Current), A (поддерживаются отрицательные значения)
  • t11 - мощность (Power), Вт (W), (Ватт)
  • t12 - энергия (потребление электроэнергии), кВт*ч (Energy) (киловатт-час)
  • t14 - неизвестный датчик c знаковыми (+/-) целыми значениями - 16 или 32 bit со знаком (int16_t, int32_t)
  • t16 - уровень сигнала (RSSI), Дб (db) (поддерживаются отрицательные значения)
  • t17 - заряд батареи (Battery), %
  • t18 - вес (Weight)
  • t19 - угол (Angle)
  • t20 - плодородие (Fertility)
  • t21 - расстояние (Distance)
  • t22 - радиация (Radiation)
  • t24 - частота (Frequency), Гц (Hz)
  • t25 - PMS1.0 (наличие частиц размером 0.3–1 мкм), мкг/м3 (mkg/m3)
  • t26 - PMS2.5 (наличие частиц размером 1–2.5 мкм), мкг/м3 (mkg/m3)
  • t27 - PMS10 (наличие частиц размером 2.5-10 мкм), мкг/м3 (mkg/m3)
  • t29 - качество воздуха (концентрация VOC), ppb (миллиардная доля)

Тип указывается в конце маски для переменной, пример: e2d2t7 - освещенность

🔹 sX - пропуск X байт
Описание параметра

Иногда в LoRa-пакете необходимы не все данные.
Чтобы пропустить часть байт применяется параметр s с указанием количества байт для пропуска (X).

Внимание! sX не сработает, если пропускаемых байт не существует в пакете!
В этом случае нужно будет создать новую секцию [sensors] с другим fport для обработки другого пакета.

Математические выражения
Пример маски с дополнительными вычислениями
// обычная маска: mask=e2t0,e2t0

// добавляем умножение на коэффициент 1,6 для первой переменной
mask=e2t0[*16/10],e2t0

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

Математические выражения позволяют применять нестандартные множители и смещения - то есть осуществлять пересчёт или корректировку изначальных значений переменных.

В поле mask возможно применение различных выражений для каждой из переменных по-отдельности.

Список доступных операций:

  • + - сложение
  • - - вычитание
  • * - умножение
  • / - деление
  • % - получение остатка от деления
  • & - наложение битовой маски
Порядок выполнения операций

Математические операции будут производиться последовательно слева-направо.

Рассмотрим выполнение операций на примере:
e2t0[*16/10-45/4]

Операции происходят в следующей последовательности:

  • *16
  • /10
  • -45
  • /4
Примеры чтения значения одного бита из байта LoRa-пакета

В LoRa-пакетах часто встречаются байты статуса, где каждый бит имеет своё назначение.

Байт состоит из 8-ми бит (с порядковыми номерами от 0 до 7).
Бит 0 - младший. Бит 7 - старший.

Ниже показаны примеры, как при помощи операций битовой маски и деления отфильтровать значение и прочитать только нужный бит из байта.

  • бит 0 - mask=e1t0[&1]
  • бит 1 - mask=e1t0[&2/2]
  • бит 2 - mask=e1t0[&4/4]
  • бит 3 - mask=e1t0[&8/8]
  • бит 4 - mask=e1t0[&16/16]
  • бит 5 - mask=e1t0[&32/32]
  • бит 6 - mask=e1t0[&64/64]
  • бит 7 - mask=e1t0[&128/128]

Назначение MQTT-топиков

Для Sensors-параметров существует возможность использовать уникальные названия MQTT-топиков для метрик.
Для этого в маске в фигурных скобках нужно указать короткий текст.

Пример маски с MQTT топиками
mask=e2t0{temp},e2t0{hum},e1t1{relay} ; (1)!
  1. 🔍 Расшифровка маски:
    • e2t0{temp} - Температура, °C
      • e2 - читаем 2 байта
      • t0 - тип метрики (стандартный для Sensors)
      • temp - имя MQTT топика
    • e2t0{hum} - Влажность, %RH
      • e2 - читаем 2 байта
      • t0 - тип метрики
      • hum - имя MQTT топика
    • e1t1{relay} - Реле (GPIO)
      • e1 - читаем 1 байт
      • t1 - тип для GPIO
      • relay - имя MQTT топика

Подробная расшифровка параметров доступна по значку с вопросом в коде примера выше

Допустим, мы настроили устройство на подключение к MQTT-серверу с логином (пользователем) user

Устройство названо TEST_DEVICE (это название высвечивается на главной, можно поменять во вкладке Main).
На вкладке LoRa настраиваем шаблон для приёма данных от Node.

В итоге на MQTT сервер будут отсылаться данные в следующих топиках:

  • user/TEST_DEVICE/lora/temp - Температура
  • user/TEST_DEVICE/lora/hum - Влажность
  • user/TEST_DEVICE/lora/relay - Реле

По данным топикам можно будет считать показания датчика в соответствии с правилами преобразований из mask

Указание диапазона для PWM

По умолчанию в веб-интерфейсе слайдеры имеют диапазон значений 0-100.
В шаблоне можно указать своё значение в квадратных скобках для PWM:

Пример маски c max значением слайдера 500 для PWM
mask=e2t0,e1t1,e2t2[500]

Математические выражения

Пример маски с дополнительными вычислениями
// обычная маска: mask=e2t0,e2t0

// добавляем умножение на коэффициент 1,6 для первой переменной
mask=e2t0[*16/10],e2t0

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

Математические выражения позволяют применять нестандартные множители и смещения - то есть осуществлять пересчёт или корректировку изначальных значений переменных.

В поле mask возможно применение различных выражений для каждой из переменных по-отдельности.

Список доступных операций:

  • + - сложение
  • - - вычитание
  • * - умножение
  • / - деление
  • % - получение остатка от деления
  • & - наложение битовой маски
Порядок выполнения операций

Математические операции будут производиться последовательно слева-направо.

Рассмотрим выполнение операций на примере:
e2t0[*16/10-45/4]

Операции происходят в следующей последовательности:

  • *16
  • /10
  • -45
  • /4
Примеры чтения значения одного бита из байта LoRa-пакета

В LoRa-пакетах часто встречаются байты статуса, где каждый бит имеет своё назначение.

Байт состоит из 8-ми бит (с порядковыми номерами от 0 до 7).
Бит 0 - младший. Бит 7 - старший.

Ниже показаны примеры, как при помощи операций битовой маски и деления отфильтровать значение и прочитать только нужный бит из байта.

  • бит 0 - mask=e1t0[&1]
  • бит 1 - mask=e1t0[&2/2]
  • бит 2 - mask=e1t0[&4/4]
  • бит 3 - mask=e1t0[&8/8]
  • бит 4 - mask=e1t0[&16/16]
  • бит 5 - mask=e1t0[&32/32]
  • бит 6 - mask=e1t0[&64/64]
  • бит 7 - mask=e1t0[&128/128]

Примеры шаблонов

Допустим, на стороне Node используется такой список метрик:

метрики_node

Пример шаблона (авто-генерация от Node)
[main]
type=1

[sensors]
fport=100
mask=e2t0,e2t0,e2t0,e2t0,e2t0,e2t0,e2t0,e2t0,e2t0,e2t0,e1t1,e1t1,e1t1,e2t2,e2t2,e2t2
Пример шаблона c добавлением MQTT-топиков и max значений слайдеров
[main]
type=1

[sensors]
fport=100
mask=e2t0{d1},e2t0{d2},e2t0{d3},e2t0{c1},e2t0{c2},e2t0{c3},e2t0{c4},e2t0{c5},e2t0{c6},e2t0{d12},e1t1,e1t1,e1t1,e2t2[80],e2t2[80],e2t2[80]

Проверка на соответствие

Перед началом эксплуатации шаблона убедитесь, что состав маски в [sensors] соответствует списку метрик на Node. При расхождении маски и реальных каналов возможны некорректные значения на Gateway.

Комментарии

В шаблонах поддерживаются комментарии. Они должны начинаться с новой строки с символа //

// пример комментария, содержимое строки игнорируется