documentation update

2025-12-06 11:36:55 +03:00 · 2021-11-17 17:40:13 +03:00
parent c9f6dadd73
commit e7d1be632f
7 changed files with 227 additions and 346 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Кастомный компонент для ESPHome для управления кондиционером по wifi <!--[![GitHub release](https://img.shields.io/github/v/release/GrKoR/esphome_aux_ac_component)](https://github.com/GrKoR/esphome_aux_ac_component/releases/) [![Телеграм](https://img.shields.io/badge/Telegram-2CA5E0?style=flat&logo=telegram&logoColor=white)](https://t.me/aux_ac) -->

-Readme in english [is here](README-EN.md#esphome-aux-air-conditioner-custom-component-aux_ac). 
+English readme [is here](README-EN.md#esphome-aux-air-conditioner-custom-component-aux_ac). 

 Управляет кондиционерами на базе AUX по wifi.<br />
 По тексту ниже для компонента используется сокращение `aux_ac`.
@@ -22,11 +22,11 @@ AUX - это один из нескольких OEM-производителей


 ### Список совместимых (протестированных) кондиционеров ###
-[Список протестированных кондиционеров](docs/AC_TESTED.md) включает те модели, на которых `aux_ac` был запущен автором компонента или пользователями. Этот список постоянно пополняется, преимущественно по обратной связи от пользователей [в чате Телеграм](https://t.me/aux_ac).<br />
+[Список протестированных кондиционеров](docs/AC_TESTED.md) размещен в отдельном файле и включает те модели, на которых `aux_ac` был запущен автором компонента или пользователями. Этот список постоянно пополняется, преимущественно по обратной связи от пользователей [в чате Телеграм](https://t.me/aux_ac).<br />
 
 ### Если кондиционер в списке отсутствует ###
 Если производитель вашего кондиционера есть в списке выше, то стоит изучить вопрос. Возможно, вам тоже подойдет `aux_ac` для управления по wifi.<br />
-Если в инструкции пользователя вашего кондиционера что-то написано про возможность управления по wifi (особенно с помощью мобильного приложения ACFreedom), то есть весьма существенные шансы, что `aux_ac` сможет управлять и вашим кондиционером. Но будьте осмотрительны: ваш кондиционер никем не тестировался и важно четко понимать, что вы делаете. Иначе можете поломать кондиционер.<br />
+Если в инструкции пользователя вашего кондиционера что-то написано про возможность управления по wifi (особенно с помощью мобильного приложения ACFreedom), то есть весьма существенные шансы, что `aux_ac` сможет управлять и вашим кондиционером. Но будьте осмотрительны: ваш кондиционер никем не тестировался и важно четко понимать, что вы делаете. Иначе можете наломать дров.<br />
 Если вы не уверены в своих силах, лучше дождитесь, пока другие более опытные пользователи протестируют вашу модель кондиционера (правда, это может не случиться никогда). Или приходите с вопросами [в телеграм-чат](https://t.me/aux_ac). Возможно, там вам помогут.

 Если вы протестировали ваш кондиционер и он работает, напишите мне, пожалуйста. Я внесу вашу модель в список протестированных. Возможно, это упростит кому-то жизнь =)<br />
@@ -38,7 +38,7 @@ AUX - это один из нескольких OEM-производителей
 ### Прошивка: интеграция aux_ac в вашу конфигурацию ESPHome ###
 Для использования требуется [ESPHome](https://esphome.io) версией не ниже 1.18.0. Именно в этой версии появились `external_components`. Но лучше использовать версию 1.20.4 или старше, так как до этой версии массированно исправлялись ошибки в механизме подключения внешних компонентов.<br />

-## Установка
+## Установка ##
 1. Подключите компонент.
 За подробностями можно заглянуть в [официальную документацию ESPHome](https://esphome.io/components/external_components.html?highlight=external).
 ```yaml
@@ -72,25 +72,32 @@ logger:
 ```

 ## Настройка компонента ##
+Минимальная конфигурация:
+```yaml
+climate:
+  - platform: aux_ac
+    name: "AC Name"
+```

+Полная конфигурация:
 ```yaml
 climate:
  - platform: aux_ac
    name: "AC Name"
    id: aux_id
    uart_id: ac_uart_bus
-    period: 7s            # период опроса состояния сплита, по дефолту 7 сек
-    show_action: true     # надо ли показывать текущий режим работы: при HEAT_COOL mode сплит может греть (HEAT), охлаждать (COOL) или бездействовать (IDLE)
-    indoor_temperature:   # сенсор, показывающий температуру воздуха на внутреннем блоке кондиционера; имеет все те же параметры, как и любой сенсор ESPHome
+    period: 7s
+    show_action: true
+    indoor_temperature:
      name: AC Indoor Temperature
      id: ac_indoor_temp
-      internal: true    # сенсор установлен как внутренний по дефолту (не попадёт в Home Assistant)
+      internal: true
    visual:
      min_temperature: 16
      max_temperature: 32
      temperature_step: 0.5
    supported_modes:
-      - HEAT_COOL   # не AUTO, так как только нагревает и остужает. В доках на ESPHome говорится, что AUTO - это если у устройства есть календарь и какие-то установки по расписанию.
+      - HEAT_COOL
      - COOL
      - HEAT
      - DRY
@@ -111,91 +118,43 @@ climate:
      - BOTH
 ```

+## Параметры компонента: ##
+- **name** (**Обязательный**, строка): Имя кондиционера. Как минимум один из параметров `id` или `name` должен быть указан!
+- **id** (*Опциональный*, [ID](https://esphome.io/guides/configuration-types.html#config-id)): Укажите идентификатор кондиционера чтобы обращаться к нему из кода. Как минимум один из параметров `id` или `name` должен быть указан!
+- **uart_id** (*Опциональный*, [ID](https://esphome.io/guides/configuration-types.html#config-id)): Укажите ID [шины UART](https://esphome.io/components/uart.html), к которой подключен кондиционер. Если сконфигурирована одна шина, то компонент подключит её автоматически. Если шин несколько, то лучше указать вручную.
+- **period** (*Опциональный*, [время](https://esphome.io/guides/configuration-types.html#config-time)): Период между запросами статуса кондиционера. По умолчанию ``7s``. `Aux_ac` получает новое состояние кондиционера только после регулярного запроса, потому что сам кондиционер об изменении параметров своеё работы не уведомляет. Поэтому нужно запрашивать его, вдруг пользователь установил иной режим работы с помощью ИК-пульта.
+- **show_action** (*Опциональный*, логическое): Показывать ли текущую задачу кондиционера (экспериментальная функция). Например, в режиме HEAT-COOL кондиционер может выполнять одну из следующих задач:
+  - НАГРЕВ: нагревает воздух в комнате;
+  - ПРОСТОЙ: кондиционер работает в режиме вентилятора для перемешивания воздуха в комнате, поскольку целевая температура уже достигнута;
+  - ОХЛАЖДЕНИЕ: кондиционер охлаждает воздух в комнате.
+  Аналогично будут отображаться действия кондиционера и для режимов ОТОПЛЕНИЕ и ОХЛАЖДЕНИЕ. Единственная разница будет в количестве действий: ПРОСТОЙ+НАГРЕВ для режима отопления и ПРОСТОЙ+ОХЛАЖДЕНИЕ для режима охлаждения комнаты.
+- **indoor_temperature** (*Опциональный*): Параметры создаваемого датчика температуры воздуха, если такой датчик нужен
+  - **name** (**Обязательный**, строка): Имя датчика температуры.
+  - **id** (*Опциональный*, [ID](https://esphome.io/guides/configuration-types.html#config-id)): Можно указать свой ID для датчика для использования в лямбдах.
+  - **internal** (*Опциональный*, логическое): Пометить данный датчик как внутренний. Внутренний датчик не будет передаваться во фронтэнд (такой как Home Assistant). В противоположность стандартному поведению [сенсоров](https://esphome.io/components/sensor/index.html#base-sensor-configuration) этот параметр для датчика в кондиционере **всегда выставлен в true** за исключением случаев, когда пользователь не установил его в `false`. То есть по умолчанию значение сенсора не будет передаваться во фронтенд даже если указано `name` для сенсора.
+  - Все остальные параметры [сенсора](https://esphome.io/components/sensor/index.html#base-sensor-configuration) ESPHome.
+- **supported_modes** (*Опциональный*, список): Список поддерживаемых режимов работы. Возможные значения: ``HEAT_COOL``, ``COOL``, ``HEAT``, ``DRY``, ``FAN_ONLY``. Обратите внимание: некоторые производители кондиционеров указывают на пульте режим AUTO, хотя по факту этот режим не работает по расписанию и только лишь поддерживает целевую температуру. Такой режим в ESPHome называется HEAT_COOL. По умолчанию список содержит только значение ``FAN_ONLY``.
+- **custom_fan_modes** (*Опциональный*, список): Список поддерживаемых дополнительных режимов вентилятора. Возможные значения: ``MUTE``, ``TURBO``. По умолчанию никакие дополнительные режимы не установлены.
+- **supported_presets** (*Опциональный*, список): Список поддерживаемых базовых функций кондиционера. Возможные значения: ``SLEEP``. По умолчанию никакие базовые функции не установлены.
+- **custom_presets** (*Опциональный*, список): Список поддерживаемых дополнительных функций кондиционера. Возможные значения: ``CLEAN``, ``FEEL``, ``HEALTH``, ``ANTIFUNGUS``. Обратите внимание: функции ``FEEL``, ``HEALTH`` и ``ANTIFUNGUS`` пока не в компоненте реализованы. По умолчанию никакие дополнительные функции не установлены.
+- **supported_swing_modes** (*Опциональный*, список): Список поддерживаемых режимов качания шторки. Возможные значения: ``VERTICAL``, ``HORIZONTAL``, ``BOTH``. По умолчанию устанавливается, что качание шторки кондиционером не поддерживается.
+- Все остальные параметры [климатического устройства](https://esphome.io/components/climate/index.html#base-climate-configuration) ESPHome.
+
+
 ## Простейший пример ##
 Исходный код простейшего примера можно найти в файле [aux_ac_simple.yaml](https://github.com/GrKoR/esphome_aux_ac_component/blob/master/examples/simple/aux_ac_simple.yaml).

-Все настройки в нем тривиальны и подробно описаны [в официальной документации на ESPHome](https://esphome.io/index.html) и дополнены [в разделе об интеграции компонента](https://github.com/GrKoR/esphome_aux_ac_component#%D0%BF%D1%80%D0%BE%D1%88%D0%B8%D0%B2%D0%BA%D0%B0-%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D1%8F-aux_ac-%D0%B2-%D0%B2%D0%B0%D1%88%D1%83-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D1%8E-esphome) в ваш девайс.<br />
-Просто скопируйте yaml-файл примера и `aux_ac_custom_component.h` в локальную папку у себя на компьютере, пропишите настройки вашей сети WiFi и откомпилируйте YAML с использованием ESPHome. 
+Все настройки в нем тривиальны и подробно описаны [в официальной документации на ESPHome](https://esphome.io/index.html) и дополнены в разделе о настройке компонента выше.<br />
+Просто скопируйте yaml-файл примера в локальную папку у себя на компьютере, пропишите настройки вашей сети WiFi и откомпилируйте YAML с использованием ESPHome. 


 ## Продвинутый пример ##
 Все исходники продвинутого примера лежат [в соответствующей папке](https://github.com/GrKoR/esphome_aux_ac_component/tree/master/examples/advanced).

-В это примере мы конфигурируем два относительно одинаковых кондиционера на работу с `aux_ac`.<br />
+В этом примере мы конфигурируем два относительно одинаковых кондиционера на работу с `aux_ac`.<br />
 Вводные: представим, что у нас есть два кондея, расположенных в кухне и в гостиной. Эти кондиционеры могут и не быть одного бренда. Главное, чтобы они были совместимы с `aux_ac`.<br />  
 Поскольку мы ленивы, мы пропишем все общие настройки обоих кондиционеров в общем конфигурационном файле `ac_common.yaml`.<br />
 А все параметры, специфичные для каждого конкретного устройства, вынесем в отдельные файлы. Это файлы `ac_kitchen.yaml` и `ac_livingroom.yaml`. В них мы установим значения для подстановок `devicename` и `upper_devicename`, чтобы у устройств в сети были корректные имена самого компонента и его сенсоров. И здесь же мы указываем уникальные для каждого устройства IP-адреса, спрятанные в `secrets.yaml`.<br />
 Кстати да! **Не забудьте** присвоить корректные значения `wifi_ip_kitchen`, `wifi_ota_ip_kitchen`, `wifi_ip_livingroom` и `wifi_ota_ip_livingroom` в файле `secrets.yaml` наряду с остальной "секретной" информацией (например пароли, токены и т.п.). Файл `secrets.yaml` по понятным причинам на гитхаб не выложен.

-Если попытаться компилировать файл `ac_common.yaml`, то ESPHome выдаст ошибку. Для корректной прошивки необходимо компилировать `ac_kitchen.yaml` или `ac_livingroom.yaml`.
- 
-## Дополнительная функциональность ##
-Компонент `aux_ac` предоставляет три дополнительных сенсора: два значения температуры и один номер версии прошивки.
-
-### Комнатная температура ###
-Этот сенсор отдает значения комнатной температуры воздуха с внутреннего блока кондиционера. Если значение этого датчика вам нужно, пропишите подобную конфигурацию сенсора в вашем YAML-файле:
-```yaml
-sensor:
-  - platform: custom
-    lambda: |-
-      extern AirCon acAirCon;
-      if (!acAirCon.get_initialized()) acAirCon.initAC(id(ac_uart_bus));
-      App.register_component(&acAirCon);
-      return {acAirCon.sensor_ambient_temperature};
-    sensors:
-    - name: AC ambient temperature
-      unit_of_measurement: "°C"
-      accuracy_decimals: 1
-```
- 
-### Уличная температура ###
-К сожалению, пока этот сенсор показывает погоду на Марсе =) Значение, обрабатываемое `aux_ac` для нужд этого сенсора точно как-то связано с уличной температурой, но полностью расшифровка значения не известна. Есть предположение, что это температура испарителя во внешнем блоке, потому что при переключении кондиционера с обогрева на охлаждение или обратно эта температура стремительно меняется. А при выключенном кондиционере в течение суток меняется похожим на уличную температуру образом. Однако всё это при теплой погоде на улице. При отрицательной температуре показывает одно и то же значение. По крайней мере при температурах в диапазоне -25..-19 градусов Цельсия.<br />
-В общем, для расшифровки надо собрать больше статистики и коллективно подумать в чатике.
-
-Если несмотря на сказанное вам нужно это значение в ESPHome, пропишите следующий сенсор в конфигурации:
-```yaml
-sensor:
-  - platform: custom
-    lambda: |-
-      extern AirCon acAirCon;
-      if (!acAirCon.get_initialized()) acAirCon.initAC(id(ac_uart_bus));
-      App.register_component(&acAirCon);
-      return {acAirCon.sensor_outdoor_temperature};
-    sensors:
-    - name: AC outdoor temperature
-      unit_of_measurement: "°C"
-      accuracy_decimals: 1
-```
- 
-### Обе температуры одновременно ###
-Возможно прописать конфигурацию обоих сенсоров в одном определении:
-```yaml
-sensor:
-  - platform: custom
-    lambda: |-
-      extern AirCon acAirCon;
-      if (!acAirCon.get_initialized()) acAirCon.initAC(id(ac_uart_bus));
-      App.register_component(&acAirCon);
-      return {acAirCon.sensor_outdoor_temperature, acAirCon.sensor_ambient_temperature};
-    sensors:
-    - name: AC outdoor temperature
-      unit_of_measurement: "°C"
-      accuracy_decimals: 1
-    - name: AC ambient temperature
-      unit_of_measurement: "°C"
-      accuracy_decimals: 1
-```
- 
-### Версия прошивки ###
-Компонент `aux_ac` предоставляет информацию о своей версии в виде текстового сенсора. Соответствующая конфигурация показана ниже:
-```yaml
-text_sensor:
- platform: custom
-  lambda: |-
-    auto aircon_firmware_version = new AirConFirmwareVersion();
-    App.register_component(aircon_firmware_version);
-    return {aircon_firmware_version};
-  text_sensors:
-    name: AC firmware version
-    icon: "mdi:chip"
-```
+Если попытаться компилировать файл `ac_common.yaml`, то ESPHome выдаст ошибку. Для корректной прошивки необходимо компилировать `ac_kitchen.yaml` или `ac_livingroom.yaml`.