Custom/Database/Bindings

---

Общие сведения

Биндинги позволяют связывать сторонние MQTT-топики и их данные с устройством HOMEd Custom. Биндинги описываются как JSON-обект, ключами которого являются имена описываемых свойств. Структура описания биндингов выглядит так:

{
  ...
  "real": true,
  "exposes": ["switch", "temperature"],
  "bindings":
  {
    "status":
    {
       "inTopic": "switch/status/topic",
       "inPattern": "{{ on if json.switch == true else off }}",
       "outTopic": "switch/command/topic",
       "outPattern": "{\"switch\":{{ true if value == on else false }}}"
    },
    "temperature":
    {
       "inTopic": "temperature/status/topic",
       "inPattern": "{{ json.temperature }}"
    }
  }
  ...
}

Биндинги работают только в случае, когда в настройках устройства включен параметр real.

Параметры биндингов

inTopic

MQTT-топик, в который устройство публикует состояние описываемого свойства. Является обязательным в случае, если отсутствует параметр outTopic.

inPattern

Шаблон для получения состояния описываемого свойства из топика inTopic. В случае отсутствия этого параметра, данные будут использованы без изменений. Подробнее в разделе шаблоны.

outTopic

MQTT-топик, который необходимо опубликовать для изменения состояния описываемого свойства. Является обязательным в случае, если отсутствует параметр inTopic.

outPattern

Шаблон для передечи состояния описываемого свойства в топик outTopic. В случае отсутствия этого параметра данные будут опубликованы без изменений. Подробнее в разделе шаблоны.

Шаблоны

Шаблон это простая строка, которая может содержать части текста, обернутые двойными фигурными скобками {{ ... }}. Эти части теста будут автоматически заменяться на значение, зависящее от набора элементов шаблона.

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

json

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

Получение параметра pressure:

{{ json.pressure }}

Получение параметра из объекта, вложенного в массив:

{{ json.values[2].status }}

Получение параметра c ключом, содержащим пробелы:

{{ 'json.some key with spaces' }}

value

Этот элемент шаблона применим к случаям, когда устройство публикует свое состояние "как есть" или необходимо передать на устройство значение свойства, вложив его некую текстовую конструкцию, например, в JSON-объект. Пример использования элемента:

{\"setStatus\":\"{{ value }}\"}

format

Этот элемент шаблона позволяет преобразовывать данные из одного формата в другой. На данный момент поддерживаются следующие функции:

• fromHex - преобразование HEX-строки в список чисел (актуально для работы с цветом)
• toHex - преобразование списка чисел в HEX-строку (актуально для работы с цветом)
• time - преобразование меток времени Unix Time в строку

Примеры использования элемента:

{{ format.fromHex(12FE0A) }}  # 18,254,10
{{ format.toHex(10,20,30) }}  # 0A141E
{{ format.time() }}           # текущая метка времени Unix Time, например: 1745411772
{{ format.time(hh:mm:ss) }}   # текущее время (с учетом часового пояса), например: 03:36:18

В случае, если описание элемента содержит пробелы, оно должно быть обернут в одинарные кавычки, например:

{{ 'format.time(dd:MM:yyyy, hh:mm|458802300)' }}  # 16.07.1984, 09:05 (для UTC+03:00)

if/else

Этот элемент шаблона является условным, его итоговое значение зависит от результатов сравнения других элементов. Поддерживаются следующие условные операторы:

• is defined (левая часть выражения не является пустой)
• is undefined (левая часть выражения является пустой)
• == (левая часть выражения равна правой части)
• != (левая часть выражения не равна правой части)
• > (левая часть выражения больше правой части)
• >= (левая часть выражения больше или равна правой части)
• < (левая часть выражения меньше правой части)
• <= (левая часть выражения меньше или равна правой части)

Условные операторы >, >=, < и <= применимы только к числовым значениям, в противном случае результат может оказаться непредсказуемым.

Примеры использования:

{{ json.value if json.value is defined else NULL }}
{{ on if json.status == true else off }}
{{ false if value <= 20 else true }}

В случае, если сравниваемые или итоговые значения содержат пробелы, они должны быть обернуты в одинарные кавычки:

{{ 'some value' if json.value == 'few words string' else 'other result' }}

Данный элемент так же может быть рекурсивным, что позволяет проверить несколько условий сразу:

{{ 1 if value == 2 else 3 if value != 4 else 5 }}

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

Помимо описанных выше элементов, в шаблонах так же могут быть применены математические выражения. В этом случае соответсвующая часть текста будет заменена числовым результатом вычислений. Например:

{{ value * 4.815162342 }}
{{ ( value + 2 ) / 10 }}
{{ round( json.voltage ) }}

Список досутпных функций можно посмотреть здесь.

Комбинирование элеметнов

В некоторых случаях, когда необходимо совместное использование нескольких элементов в одном шаблоне, каждый элемент должен быть обернут в собственные двойные фигурные скобки. Это правило касается, в первую очередь, использования математических выражений и других элементов внутри шаблонов format и if/else. Например:

{{ format.time(hh:mm|{{ value }}) }}
{{ true if {{ value * 10 }} < 50 else false }}
{{ json.number * {{ 10 if json.number > 20 else 100 }} }}

Экранирование

В случае, когда нужно использовать элементы шаблона в качестве простого текста, их необходимо экранировать двумя обратными слэшами, например:

{{ json.value if json.value is defined else '\\json.value is undefined' }}