mega_hacs/docs/yaml.md

С помощью 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%
    - **range** (list[int, int], [0, 255]), *начиная с версии 1.1.0*: границы диммирования в абсолютных единицах 0..255. При диммировании 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, интеграция его распакует (перед применением темплейта)
    - **filter_high** (float, none): верхняя граница значений, выше нее значения будут считаться ошибочными и отбрасываться. [Доступно так же глобальное значение](#filter_high)
    - **filter_low** (float, none): нижняя граница значений, ниже нее значения будут считаться ошибочными и отбрасываться. [Доступно так же глобальное значение](#filter_low)
    - **filter_values** ([float], none): список значений, которые считаются ошибочными. [Доступно так же глобальное значение](#filter_values)
    - **filter_scale** (float, none): значение отклонения от текущего значения, которое будет считаться выбросом и отфильтруется, например если
    установить 1, то это означает, что при росте показателя сенсора на 100% и больше или падении на 100% и больше, такое значение не будет отображаться.
    [Доступно так же глобальное значение](#filter_scale)
    - **fill_na** (str, last): чем заполнять пропуски, по-умолчанию last, что означает последнее значение, можно так же поставить none-тогда будут пропуски (разрывы на графике).

При этом есть так же особенности адресации, так для сенсора на одном порте с одним значением:
```yaml
36:
  # конфиг
```
#### DHT11/22
На этих сенсорах два значения, одно для температуры, второе для влажности, поэтому для них применяется
особый вид адресации:
```yaml
35:
  name:
    hum: "влажность"
    temp: "температура"
  # и так далее для любого параметра сенсоров
```
Логика так себе ) Но так повелось в первых версиях.
#### 1W-BUS
Для датчиков установленных в шину 1-wire адресация кастомизации такая:
```yaml
35:
  addr:  # адрес датчика, по-умолчанию entity_id будет состоять из адреса и типа
    # конфиг
```
#### i2c {: #i2c}
Для сенсоров i2c нужно так же указать id сенсора, который можно посмотреть в атрибутах объекта на [странице разработчика](https://my.home-assistant.io/redirect/developer_states/).
```yaml
36:
  htu21d_humidity:  # i2c_id
    # конфиг
```
[Подробнее про 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
```

### filter_high {: #filter_high}
Верхняя граница значений датчиков по-умолчанию, выше нее значения будут считаться ошибочными и отбрасываться

### filter_low {: #filter_low}
Нижняя граница значений датчиков по-умолчанию, ниже нее значения будут считаться ошибочными и отбрасываться

### filter_values {: #filter_values }
Список значений, которые считаются ошибочными, настройка по-умолчанию для всех датчиков. Удобно, если у вас много 
  однотипных датчиков

```yaml
mega:
  filter_values: [-82, - 150]
```
### filter_scale {: #filter_scale }
Значение отклонения от текущего значения, которое будет считаться выбросом и отфильтруется, например если
установить 1, то это означает, что при росте показателя сенсора на 100% и больше или падении на 100% и больше, такое значение не будет отображаться.
```yaml
mega:
  filter_scale: 1  # 100%
```