add new docs

2025-12-11 09:04:27 +05:00 · 2021-08-03 11:23:53 +03:00
parent 54f1ebeda3
commit 912440c079
10 changed files with 616 additions and 0 deletions
--- a/docs/yaml.md
+++ b/docs/yaml.md
@@ -0,0 +1,217 @@
+С помощью yaml-конфигурации можно кастомизировать ваши устройства.
+
+## Основное
+Конфиг записывается стандартным образом в файл `configuration.yaml`, начинаем с 
+указания названия интеграции:
+```yaml hl_lines="1"
+mega:
+  megaid1:
+    10:
+      domain: switch
+      invert: true
+  megaid2:
+    14:
+      hex_to_float: true
+```
+Далее каждый новый контроллер добавляется с помощью указания его id, который вы
+придумали при установке интеграции
+```yaml hl_lines="2 6"
+mega:
+  megaid1:
+    10:
+      domain: switch
+      invert: true
+  megaid2:
+    14:
+      hex_to_float: true
+```
+
+Далее конфигурируются порты:
+```yaml hl_lines="3 4 5 7 8"
+mega:
+  megaid1:
+    10:
+      domain: switch
+      invert: true
+  megaid2:
+    14:
+      hex_to_float: true
+```
+
+## Параметры устройств
+В зависимости от типа порта доступны разные параметры. Все параметры опциональные, в скобках приведены типы и дефолтные 
+значения.
+### Стандартный набор параметров
+Все устройства вне зависимости от типа
+!!! note ""
+    - **skip** (bool, false): пропустить или нет. Если true - устройство будет исключено из списка
+    - **name** (str): имя, используется в интерфейсе
+### Реле
+!!! note ""
+    - **domain** (str, light): тип устройства. Можно выбрать light или switch
+    - **invert** (bool, false): инвертировать или нет.
+### ds2413
+Те же параметры, что у реле, но записываются иначе:
+```yaml
+10:
+  c6c439000000_a:  #c6c439000000 - это адрес ds2413, a-первый канал
+    # параметры
+  c6c439000000_b:  #b-второй канал
+```
+### Диммеры
+!!! note ""
+    - **smooth** (float, 0): программное плавное диммирование. Это поле отвечает за кол-во секунд, за которое яркость
+    диммера набирает от 0 до 100%
+    - **limits** (list[int, int], [0, 255]), *начиная с версии 1.1.0*: границы диммирования в абсолютных единицах контроллера. При диммировании 1%
+    будет равен левой границе, 100% - правой.
+[Подробнее про плавное диммирование](smooth.md)
+### MegaD-16R-XT, MegaD-16PWM
+Порты расширителей MegaD-16R-XT, MegaD-16PWM конфигурируются аналогично обычным реле и диммерам, но адресация порта 
+выглядит так:
+```yaml
+33e1:  # 33-основной порт, на котором сидит расширитель, e1-дополнительный порт расширителя
+  # стандартный конфиг порта
+33e2:
+```
+### RGB+W {: #rgb}
+Для настройки rgb(w) лент существует специальный раздел `led` в настройках каждого контроллера:
+```yaml hl_lines="3"
+mega:
+  megaid1:
+    led:
+      ledid1:  # id, который вы придумываете сами
+        # конфиг
+```
+Далее интеграция имеет поддержку двух типов лент
+#### На диммерах
+Интеграция может превратить любые 3 (или 4) диммера (актуально для мосфетов на pwm-расширителе или моноблоке)
+в rgb(w) контроллер с интерфейсом выбора цвета. Конфиг для такого типа ленты будет выглядеть так:
+!!! note ""
+    - **ports** (list\[str\]): список номеров портов, из которых составлять ленту, все порты должны быть типа PWM.
+    Порядок цветов строго \[R, G, B, W\]. W указывается опционально
+    - **white_sep** (bool, true): яркостью белого можно управлять в двух режимах - синхронно с яркостью RGB, либо 
+    отдельно, по умолчанию стоит отдельно (true)
+    - **smooth** (float, 1): скорость диммирования, от 0 до 100% за <smooth> секунд.
+Пример:
+```yaml
+some_led1:
+  ports: [10, 12, 15, 16]
+  white_sep: true
+  smooth: 2
+```
+#### Адресные ленты на WS281X
+Подробно про поддержку контроллера таких лент рассказано в [инструкции](https://www.ab-log.ru/smart-house/ethernet/megad-2561#ws).
+Интеграция не привносит ничего нового - только помогает "пробросить" такие ленты в интерфейс HA.
+Конфиг таких лент выглядит так:
+!!! note ""
+    - **ws28xx** (bool, false): обязательное поле, необходимо установить true.
+    - **port** (int): номер порта, на котором настроена лента.
+    - **order** (str, "rgb"): последовательность каналов, допускаются любые комбинации букв r,g,b: rbg, bgr и тд
+    - **chip** (int, 100): кол-во чипов в ленте, по умолчанию 100, если их меньше емеет смысл указать правильное кол-во 
+    для увеличения скорости плавного диммирования
+    - **smooth** (float, 1): скорость диммирования, от 0 до 100% за <smooth> секунд.
+Пример:
+```yaml
+some_led2:
+  ws28xx: true
+  port: 36
+  order: bgr
+  smooth: 2
+```
+### Бинарные сенсоры {: #binary}
+Или по-другому цифровые входы. Как правило используются для выключателей, кнопок, датчиков движения и тд.
+!!! note ""
+    - **response_template** (str): шаблон ответа на команды сервера. По-умолчанию d. 
+    Про формат ответа подробно описано [тут](https://www.ab-log.ru/smart-house/ethernet/megad-2561#conf-in-act). 
+    В шаблоне можно использовать параметры, которые передает контроллер (m, click, pt, mdid, mega_id).
+    Про отладку шаблонов подробнее [тут](http.md#temp-debug)
+
+!!! note "на меге"
+    Для корректной работы binary_sensor имеет смысл использовать режим P&R в настройках порта меги
+Бинарные сенсоры так же отвечают за события типа *mega.binary*, [об этом подробнее в разделе события](events.md)
+
+Примеры шаблонов ответа:
+```yaml
+4:
+  response_template: "5:2" # простейший пример без шаблона. Каждый раз когда будет приходить сообщение на этот порт, 
+                         # будем менять состояние на противоположное
+5:
+  # пример с использованием шаблона, порт 1 будет выключен если он сейчас включен и включен с последней сохраненной 
+  # яркостью если он сейчас выключен     
+  response_template: >-
+    {% if is_state('light.some_port_1', 'on') %}
+    1:0
+    {% else %}
+    1:{{state_attr('light.some_port_1', 'brightness')}}
+    {% endif %}
+6:
+  # в шаблон так же передаются все параметры, которые передает контроллер (pt, cnt, m, click)
+  # эти параметры можно использовать в условиях или непосредственно в шаблоне в виде {{pt}}
+  response_template: >-
+    {% if m==2 %}1:0{% else %}d{% endif %}
+```
+
+
+### Датчики  {: #sensors }
+Любой датчик будь то i2c или аналоговый или 1-wire
+!!! note ""
+    - **unit_of_measurement** (str): единицы измерения, [список доступных](https://developers.home-assistant.io/docs/core/entity/sensor#available-device-classes)
+    - **value_template** (str): шаблон для конвертации, например `{{(value|float)/100}}`
+    - **device_class** (str): класс устройства, [список доступных](https://developers.home-assistant.io/docs/core/entity/sensor#available-device-classes)
+    - **hex_to_float** (bool, false): если ваш датчик возвращает float запакованный в HEX, интеграция его распакует (перед применением темплейта)
+При этом есть так же особенности адресации, так для сенсора на одном порте с одним значением:
+```yaml
+36:
+  # конфиг
+```
+#### DHT11/22
+На этих сенсорах два значения, одно для температуры, второе для влажности, поэтому для них применяется
+особый вид адресации:
+```yaml
+35:
+  name:
+    hum: "влажность"
+    temp: "температура"
+  # и так далее для любого параметра сенсоров
+```
+Логика так себе ) Но так повелось в первых версиях.
+#### 1W-BUS
+Для датчиков установленных в шину 1-wire адресация кастомизации такая:
+```yaml
+35:
+  addr:  # адрес датчика, по-умолчанию entity_id будет состоять из адреса и типа
+    # конфиг
+```
+#### i2c {: #i2c}
+Для сенсоров i2c адресация конфига такая:
+```yaml
+36:
+  htu21d_humidity:  # entity_id сенсора без приставки sensor., видно в интерфейсе HA
+    # конфиг
+```
+[Подробнее про i2c](i2c.md)
+## Параметры контроллера
+Некоторые параметры применяются для всего контроллера (одна мега)
+### def_response
+Шаблон ответа сервера по умолчанию. Если этот параметр указан, то настройка "d по умолчанию" 
+в UI игнорируется.
+
+Пример:
+```yaml
+mega:
+  megaid1:
+    def_response: >-
+      {% if m in [0, 1] %}d{% endif %}
+```
+
+## Параметры интеграции
+### allow_hosts {: #allow_hosts }
+Отвечает за список хостов, с которых интеграция "слушает" сообщения. По умолчанию, в этот список
+входят все настроенные меги, а так же все запросы с локального хоста.
+
+Иногда, в целях отладки, требуется расширить этот список, что можно сделать следующим оьразом:
+```yaml
+mega:
+  allow_hosts:
+    - 192.168.1.20 
+```