0. Введение простыми словами

Шаблон — это «инструкция для хаба», как распознать ваше устройство и где брать/куда отправлять его значения. Вы заполняете «анкету» в формате JSON, а хаб сам понимает, как с ней работать.

1. Мини‑курс JSON за минуту

• JSON — это текст в фигурных скобках {} с парами "ключ": значение.
• Ключ — это строка, название поля. Оно всегда в двойных кавычках. Регистр (большие и маленькие буквы) важен.
• Значение через двоеточие после ключа. Формат: Строки в кавычках: "текст". Числа — без кавычек. Логические значения — true/false. Списки — в квадратных скобках []. Объекты — в фигурных скобках {}.
• Запятая между элементами (после значения) обязательна; после последнего элемента запятая НЕ ставится.

2. Общая идея шаблона

Вверху — кто производитель и модель, как распознать устройство (manufacturerId, modelId). Ниже — список сервисов (функций устройства), внутри каждого сервиса — характеристики (что можно читать/менять. Например, для лампы: On (вкл/выкл), Brightness (яркость)). Для каждой характеристики вы указываете link — откуда именно читать данные и куда писать.

3. Подготовка

1. Определите тип контроллера: MQTT, ModBus, ZigBee, Z‑Wave или Xiaomi.
2. Решите, какие сервисы и характеристики вам нужны. Например, для лампы используйте сервис Lightbulb - «Лампочка» и характеристики «On» (вкл/выкл) и «Brightness» (яркость), А для датчика температуры используйте сервис TemperatureSensor - «Датчик температуры» и характеристику «CurrentTemperature» (текущая температура).
3. Для MQTT заранее посмотрите топики в вашем устройстве/приложении (например, через MQTT Explorer).

4. Заполняем верхний уровень

• manufacturer, model — как на устройстве/в инструкции.
• modelId:
  • MQTT — путь топика с шаблоном (можно с «скобками» для переменных частей, например esphome/switch/(.*)/state).
  • Другие контроллеры — статичное значение модели, заданное производителем.

5. Добавляем сервисы

Сервис — это блок возможностей: «Лампочка», «Термостат», «Датчик температуры». Список типов смотрите в настройках в хабе или в редакторе в разделе «Типы сервисов». Добавляется в массив services верхнего уровня.

6. В каждый сервис добавляем характеристики

• Например, для лампы: On (вкл/выкл), Brightness (яркость).
• Для термостата: TargetTemperature (целевая температура), CurrentTemperature (текущая), CurrentHeatingCoolingState (Текущий режим термостата), TargetHeatingCoolingState (Целевой режим термостата).
• Для датчиков: CurrentTemperature (текущая температура), CurrentRelativeHumidity (текущая влажность), и т.п.
• Добавляется в массив characteristics сервиса.

7. Связываем с устройством (link)

• MQTT: укажите, какой топик читать (topicGet) и куда писать (topicSet). Если устройство говорит «ON/OFF», а хаб ждёт «true/false», используйте map или простые формулы в inFunc/outFunc.
• ModBus: адрес регистра (address), тип (function).
• ZigBee: укажите endpoint, cluster, attribute.
• Z‑Wave: укажите class и value (а для счётчиков — param).
• Xiaomi: используйте getProp для чтения и setProp для записи.
• Добавляется в массив link характеристики.

8. Добавляем опции (по желанию)

Опции — это дополнительные настройки устройства, которые нельзя или не нужно описывать как характеристики сервисов, например коды ошибок, режимы работы и другие параметры. Они задаются как характеристики, но предназначены для конфигурации. Используйте inputType (например, STATUS или BUTTON) для определения типа опции.

9. Сохраняем и тестируем

1. Скачайте JSON и загрузите на хаб. По инструкции в вики.
2. Запустите поиск в контроллере, для которого вы создали шаблон. Если всё хорошо, устройство появится в списке.
3. Откройте устройство в хабе — проверьте, что значения отображаются и управляются.
4. Если что-то не так — вернитесь и поправьте шаблон.

Частые вопросы

• Где взять список сервисов и характеристик? В хабе (Настройки) или в редакторе «Типы сервисов».
• Где взять топики для MQTT? В документации устройства или через MQTT‑клиент (например, MQTT Explorer).
• Что писать в inFunc/outFunc? Это простые функции на JavaScript. Исходное значение — в переменной value. Пример: value === "" ? 0 : 1 или JSON.parse(value).temperature для получения температуры из JSON.

Совет: Начинайте с минимального рабочего шаблона (1-2 сервиса). Затем добавляйте остальное, каждый раз валидируя.

Шаблоны пишутся в формате JSON (JavaScript Object Notation): ключи и строковые значения в двойных кавычках, числа — без кавычек, массивы — в квадратных скобках, объекты — в фигурных. Не допускаются комментарии. Валидность проверяйте кнопкой «Валидировать» в редакторе.

{
  "manufacturer": "...",
  "model": "...",
  "modelId": "...",
  "services": [ { "type": "...", "characteristics": [ { "type": "...", "link": [ { /* привязка */ } ] } ] } ],
  "options": [ { "name": "...", "type": "...", "link": [ { /* привязка */ } ] } ]
}

Верхний уровень

• name (опц.): отображаемое имя устройства.
• manufacturer, model: производитель и модель.
• issue (опц.): ссылка на задачу/обсуждение по шаблону.
• manufacturerId, modelId: идентификаторы обнаружения.
  • MQTT: modelId — путь топика с regex; группы доступны как (1), (2) и т.д. в link.
  • ZigBee/Z‑Wave/ModBus/Xiaomi: modelId — статический идентификатор модели/пары значений; без топиков/regex.
• catalogId (опц.): ID в каталоге.
• status (опц.): этап готовности шаблона: Done, Test и т.п.
• init (опц.): начальные чтения/настройки (ModBus, ZigBee ZCL, Z‑Wave association).
• template (опц., ZigBee): подключение базовых подшаблонов.

services — перечень возможностей устройства

Сервис — это функциональный блок (например, лампа, термостат, датчик). Доступные типы сервисов смотрите в хабе (Настройки) или прямо в редакторе в разделе «Типы сервисов».

• name (опц.): имя сервиса.
• type: тип сервиса.
• visible (опц.): скрыть/показать сервис в интерфейсе.
• logics (опц.): встроенная логика вычисления некоторых характеристик.
• characteristics: список характеристик сервиса.

characteristics — характеристики сервиса

Характеристика — конкретная величина или состояние (вкл/выкл, температура, яркость и т.д.).

• type: тип характеристики.
• name (опц.), description (опц.), unit (опц.).
• value (опц.): начальное/фиксированное значение (например, TemperatureDisplayUnits: "CELSIUS").
• minValue, maxValue, minStep — диапазон и шаг.
• validValues (опц.): перечень допустимых значений (списком чисел или констант через запятую, например "OFF,HEAT,COOL").
• write (опц.): можно ли записывать значение (true/false).
• visible (опц.): скрыть/показать характеристику.
• link: как прочитать/записать значение через выбранный контроллер (см. ниже).
• option (опц.): пометка как дополнительной настройки.
• data (опц.): доп. параметры для логик/визуализации.

link — привязка к контроллеру

Определяет, откуда читать и куда писать значение. Набор полей зависит от контроллера (MQTT/ModBus/ZigBee/Z‑Wave/Xiaomi) — см. раздел «Поля link по типам контроллеров» ниже.

options — настройки устройства

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

• name: имя опции.
• type: тип значения (Boolean, Integer, Double, String и т.д.).
• value (опц.): начальное значение.
• values (опц.): справочник возможных значений [{ value, name, description? }].
• unit (опц.).
• inputType (опц.): как отображать/использовать опцию (например, STATUS — статусное поле, BUTTON — кнопка).
• write, visible, init (опц.).
• link: привязка к контроллеру аналогична характеристикам.

MQTT

• topicGet (чтение), topicSet (запись). Поддержка шаблонов с группами (1), (2) и т.п. из modelId.
• type: String | Integer | Double | RGB и т.д.
• Преобразования: map, outMap, inFunc, outFunc, format, delimiter, checkValue, retain (реже).
• Wiren Board: распространённый паттерн топиков /devices/(1)/controls/(2) и производные (например (2)_open_circuit), modelId вида /devices/(ensystec_leak_protect_[0-9]{1,3})/controls/(input_([1-9]0?))/meta/type.
• Тип Boolean допустим для MQTT-links: значения приводятся согласно map (напр. true/false ↔ on/off).
• Пример (из WLED):

{
  "type": "Brightness",
  "link": [{
    "type": "Integer",
    "topicGet": "wled/(1)/g",
    "topicSet": "wled/(1)",
    "inFunc": "(((parseInt(value) - 0)/(255 - 0)*100).toFixed(0))",
    "outFunc": "(((parseInt(value)/100)*(255 - 0)).toFixed(0))"
  }]
}

---

ModBus

• address, function (Coil | Discrete | Holding | Input), length (опц.), scale (опц.), pollingTime (мс).
• Поддержка init для чтения modelId/firmware и базовой инициализации.
• Пример:

{
  "type": "CurrentTemperature",
  "link": [{
    "address": 3,
    "function": "Holding",
    "scale": 0.01,
    "pollingTime": 1000
  }]
}

---

ZigBee

• endpoint, cluster, attribute; дополнительно встречаются manufacturerCode, zclDataType, bind, report, source, scale.
• В init возможны ZCL‑команды/чтения с массивом zcl.
• template: подключение базовых подшаблонов (см. SONOFF S60ZBTPF).

---

Z‑Wave

• class (Command Class), value (идентификатор/путь значения), param (единица/тип при чтении Meter и т.п.).
• В init используются association для настройки Lifeline и групп.
• options часто содержат параметры устройства с полями id, size, unit, values (справочники).

---

Xiaomi

• id (device id), getProp, setProp — свойства протокола MIIO. Дополнительно возможны scale и map для приведения единиц/состояний.

• map поддерживает:
  • мульти‑значения через «;»: например { "0": "0;3", "1": "1;2" } — несколько значений протокола сводятся к одному значению характеристики.
  • диапазоны через «X~Y»: например { "FILTER_OK": "31~9999999", "CHANGE_FILTER": "0~30" }.
• inFunc и outFunc — это выражения на JavaScript. Входящее значение доступно в переменной value; результатом должно быть преобразованное значение.
  • Пример inFunc: value === "" ? 0 : 1 — строка ошибки превращается в флаг.
  • Пример inFunc с JSON: JSON.parse(value).brightness.
  • Пример outFunc: JSON.stringify({brightness: value}) — упаковка для записи.

• type (обяз.), name (опц.), description (опц.), unit (опц.).
• Ограничения/формат: minValue, maxValue, minStep, validValues, write.
• option (опц.): пометка второстепенных/настраиваемых характеристик.
• visible (опц.): скрытие сервисов/характеристик от UI.
• data (опц.): дополнительные параметры для логик/визуализации (напр. { Inversed: true }).
• options (верхнего уровня): поддерживают все поля link как у характеристик, а также value (начальное), values (справочник), inputType (STATUS, BUTTON), init, visible, write.

MQTT / Wiren Board: детектор протечки и статус обрыва провода.

{
  "modelId": "/devices/(ensystec_leak_protect_[0-9]{1,3})/controls/(input_([1-9]0?))/meta/type",
  "characteristics": [
    { "type":"LeakDetected", "link":[{ "type":"Integer", "topicGet":"/devices/(1)/controls/(2)" }] },
    { "type":"StatusFault", "link":[{ "type":"Integer", "topicGet":"/devices/(1)/controls/(2)_open_circuit" }] }
  ]
}

ZigBee / SONOFF S60ZBTPF: чтение ZCL‑атрибутов с указанием manufacturerCode, включение отчётности (bind/report), привязка измерений.

Z‑Wave / Heltun HE‑HT01: init с ассоциациями, ссылки вида { class: "Meter", value: "Electric", param: "kWh" }, параметры в options с id/size.

Xiaomi / Air Purifier: getProp/setProp, картирование on/off, масштабирование температур через scale.

1. Определите тип контроллера: MQTT, ModBus, ZigBee, Z‑Wave или Xiaomi. Это видно по устройству/интеграции.
2. Найдите похожий шаблон в /sht/editor/templates/main/Templates и откройте его в редакторе.
3. Заполните верхний уровень: производитель, модель, modelId (для MQTT — путь топика с шаблоном; для остальных — статический идентификатор).
4. Опишите сервисы: добавьте один или несколько сервисов (лампа, термостат, датчик). Список типов смотрите в редакторе «Типы сервисов».
5. Добавьте характеристики в каждый сервис: состояние (On), числовые значения (температура, скорость), режимы (validValues). Если значение должно записываться — оставьте write: true (по умолчанию) и укажите диапазон.
6. Привяжите значения через link:
   • MQTT: используйте topicGet/topicSet, при необходимости — map (замена строк) и простые формулы в inFunc/outFunc.
   • ModBus: укажите address и function, при необходимости scale.
   • ZigBee: укажите endpoint, cluster, attribute.
   • Z‑Wave: укажите class и value (а для показаний энергии — param).
   • Xiaomi: используйте getProp/setProp.
7. Добавьте опции (по желанию): переключатели, списки, статусы. При необходимости задайте inputType (например, STATUS или BUTTON).
8. Сохраните и проверьте: нажмите «Исправить под требования Sprut.hub», затем «Валидировать». При ошибках — следуйте подсказкам и исправьте.
9. Скачайте JSON и загрузите на хаб. Если поведение не совпадает — скорректируйте map или диапазоны.

Советы: начинайте с минимального рабочего шаблона (1 сервис, 1‑2 характеристики). Постепенно добавляйте остальное, валидируя на каждом шаге.