From 1bf1ef7a850a47e7499a08b47da4b628ed7ca6e5 Mon Sep 17 00:00:00 2001 From: Pavlo Dudnytskyi Date: Mon, 16 Sep 2024 08:28:13 +0200 Subject: [PATCH] More examples added to CI 2 --- .github/workflows/documentation.yaml | 12 +- .github/workflows/examples.yaml | 42 +-- README.rst | 38 +-- docs/esphome-docs/climate/haier.rst | 94 +++--- docs/examples/.base.yaml | 2 +- docs/examples/.uart.yaml | 6 + docs/examples/climate_haier.rst | 298 +++++++++++++++++ docs/examples/esphome_climate_example.yaml | 47 +++ docs/examples/usb_2_uart_boards.rst | 2 +- docs/hon_example.rst | 364 ++++++++++----------- docs/script/process_examples.py | 12 +- docs/smartair2_example.rst | 156 ++++----- docs/sniffing_serial_communication.rst | 206 ++++++------ docs/update_docs.cmd | 4 + docs/usb_2_uart_boards.rst | 20 +- 15 files changed, 826 insertions(+), 477 deletions(-) create mode 100644 docs/examples/.uart.yaml create mode 100644 docs/examples/climate_haier.rst create mode 100644 docs/examples/esphome_climate_example.yaml diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 7da7812..c34de0a 100644 --- a/.github/workflows/documentation.yaml +++ b/.github/workflows/documentation.yaml @@ -55,4 +55,14 @@ jobs: - name: Run script and save results run: python docs/script/process_examples.py docs/examples/sniffing_serial_communication.rst docs/sniffing_serial_communication.tmp - name: Compare temp file with sniffing_serial_communication.rst - run: diff -u --strip-trailing-cr docs/sniffing_serial_communication.rst docs/sniffing_serial_communication.tmp \ No newline at end of file + run: diff -u --strip-trailing-cr docs/sniffing_serial_communication.rst docs/sniffing_serial_communication.tmp + climate_haier_doc: + name: Check ESPHome climate haier + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4.1.3 + - name: Run script and save results + run: python docs/script/process_examples.py docs/examples/climate_haier.rst docs/climate_haier.tmp no_header + - name: Compare temp file with ESPHome climate haier + run: diff -u --strip-trailing-cr docs/climate_haier.tmp docs/esphome-docs/climate/haier.rst diff --git a/.github/workflows/examples.yaml b/.github/workflows/examples.yaml index 82ea2a1..a9566a5 100644 --- a/.github/workflows/examples.yaml +++ b/.github/workflows/examples.yaml @@ -8,17 +8,21 @@ on: branches: [ "master", "dev" , "experimental" ] jobs: - tests_with_base: - name: Building ${{ matrix.file }} + examples_test: + name: Building ${{ matrix.file.main }} runs-on: ubuntu-latest strategy: fail-fast: false matrix: file: - - max-hon.yaml - - max-smartair2.yaml - - min-hon.yaml - - min-smartair2.yaml + - {main: max-hon.yaml, additional: "docs/examples/.base.yaml "} + - {main: max-smartair2.yaml, additional: "docs/examples/.base.yaml"} + - {main: min-hon.yaml, additional: "docs/examples/.base.yaml"} + - {main: min-smartair2.yaml, additional: "docs/examples/.base.yaml"} + - {main: esphome_climate_example.yaml, additional: "docs/examples/.base.yaml docs/examples/.uart.yaml"} + - {main: usb_s3.yaml, additional: ""} + - {main: usb_c3u.yaml, additional: ""} + - {main: uart_sniffer.yaml, additional: ""} steps: - name: Checkout code uses: actions/checkout@v4.1.3 @@ -27,33 +31,11 @@ jobs: - name: Version esphome run: esphome version - name: Prepering test file - run: cat docs/examples/.base.yaml docs/examples/${{ matrix.file }} > ./docs/examples/__test__.yaml + run: cat ${{ matrix.file.additional }} docs/examples/${{ matrix.file.main }} > ./docs/examples/__test__.yaml - name: Preparing secrets.yaml run: | echo "wifi_ssid: test_ssid" > ./docs/examples/secrets.yaml echo "wifi_password: test_pass" >> ./docs/examples/secrets.yaml - name: Build ESPHome config run: esphome compile ./docs/examples/__test__.yaml - tests_without_base: - name: Building ${{ matrix.file }} - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - file: - - usb_s3.yaml - - usb_c3u.yaml - - uart_sniffer.yaml - steps: - - name: Checkout code - uses: actions/checkout@v4.1.3 - - name: Install esphome - run: pip3 install -U esphome - - name: Version esphome - run: esphome version - - name: Preparing secrets.yaml - run: | - echo "wifi_ssid: test_ssid" > ./docs/examples/secrets.yaml - echo "wifi_password: test_pass" >> ./docs/examples/secrets.yaml - - name: Build ESPHome config - run: esphome compile docs/examples/${{ matrix.file }} + diff --git a/README.rst b/README.rst index f4c04fc..df22a48 100644 --- a/README.rst +++ b/README.rst @@ -82,28 +82,28 @@ This component requires a `UART Bus `_ - VERTICAL - HORIZONTAL - BOTH - supported_presets: + supported_presets: - AWAY - BOOST - SLEEP - on_alarm_start: - then: - - logger.log: - level: WARN - format: "Alarm activated. Code: %d. Message: \"%s\"" - args: [ code, message] - on_alarm_end: - then: - - logger.log: - level: INFO - format: "Alarm deactivated. Code: %d. Message: \"%s\"" - args: [ code, message] - on_status_message: - then: - - logger.log: - level: INFO - format: "New status message received, size=%d, subcmd=%02X%02X" - args: [ 'data_size', 'data[0]', 'data[1]' ] + on_alarm_start: + then: + - logger.log: + level: WARN + format: "Alarm activated. Code: %d. Message: \"%s\"" + args: [ code, message] + on_alarm_end: + then: + - logger.log: + level: INFO + format: "Alarm deactivated. Code: %d. Message: \"%s\"" + args: [ code, message] + on_status_message: + then: + - logger.log: + level: INFO + format: "New status message received, size=%d, subcmd=%02X%02X" + args: [ 'data_size', 'data[0]', 'data[1]' ] Configuration variables: diff --git a/docs/esphome-docs/climate/haier.rst b/docs/esphome-docs/climate/haier.rst index 1a1f82f..a89ee52 100644 --- a/docs/esphome-docs/climate/haier.rst +++ b/docs/esphome-docs/climate/haier.rst @@ -57,53 +57,53 @@ This component requires a :ref:`UART bus ` to be setup. .. code-block:: yaml - # Example configuration entry - climate: - - platform: haier - id: haier_ac - protocol: hon - name: Haier AC - uart_id: ac_port - wifi_signal: true - display: true - visual: - min_temperature: 16 °C - max_temperature: 30 °C - temperature_step: 1 °C - supported_modes: - - 'OFF' - - HEAT_COOL - - COOL - - HEAT - - DRY - - FAN_ONLY - supported_swing_modes: - - 'OFF' - - VERTICAL - - HORIZONTAL - - BOTH - supported_presets: - - AWAY - - BOOST - - SLEEP - on_alarm_start: - then: - - logger.log: - level: WARN - format: "Alarm activated. Code: %d. Message: \"%s\"" - args: [ code, message] - on_alarm_end: - then: - - logger.log: - level: INFO - format: "Alarm deactivated. Code: %d. Message: \"%s\"" - args: [ code, message] - on_status_message: - then: - - logger.log: - level: INFO - format: "New status message received, size=%d, subcmd=%02X%02X" - args: [ 'data_size', 'data[0]', 'data[1]' ] + # Example configuration entry + climate: + - platform: haier + id: haier_ac + protocol: hon + name: Haier AC + uart_id: ac_port + wifi_signal: true + display: true + visual: + min_temperature: 16 °C + max_temperature: 30 °C + temperature_step: 1 °C + supported_modes: + - 'OFF' + - HEAT_COOL + - COOL + - HEAT + - DRY + - FAN_ONLY + supported_swing_modes: + - 'OFF' + - VERTICAL + - HORIZONTAL + - BOTH + supported_presets: + - AWAY + - BOOST + - SLEEP + on_alarm_start: + then: + - logger.log: + level: WARN + format: "Alarm activated. Code: %d. Message: \"%s\"" + args: [ code, message] + on_alarm_end: + then: + - logger.log: + level: INFO + format: "Alarm deactivated. Code: %d. Message: \"%s\"" + args: [ code, message] + on_status_message: + then: + - logger.log: + level: INFO + format: "New status message received, size=%d, subcmd=%02X%02X" + args: [ 'data_size', 'data[0]', 'data[1]' ] Configuration variables: diff --git a/docs/examples/.base.yaml b/docs/examples/.base.yaml index f15f9fb..c2d35a6 100644 --- a/docs/examples/.base.yaml +++ b/docs/examples/.base.yaml @@ -1,4 +1,4 @@ -esphome: +esphome: name: esp32-haier-example esp32: diff --git a/docs/examples/.uart.yaml b/docs/examples/.uart.yaml new file mode 100644 index 0000000..1b4da13 --- /dev/null +++ b/docs/examples/.uart.yaml @@ -0,0 +1,6 @@ + +uart: + baud_rate: 9600 + tx_pin: 17 + rx_pin: 16 + id: ac_port diff --git a/docs/examples/climate_haier.rst b/docs/examples/climate_haier.rst new file mode 100644 index 0000000..e51529b --- /dev/null +++ b/docs/examples/climate_haier.rst @@ -0,0 +1,298 @@ +Haier Climate +============= + +.. seo:: + :description: Instructions for setting up Haier climate devices. + :image: air-conditioner.svg + +This is an implementation of the ESPHome component to control HVAC on the base of the SmartAir2 and hOn Haier protocols (AC that is controlled by the hOn or SmartAir2 application). + +There are two versions of the Haier protocol: the older version uses an application called SmartAir2 while the newer version uses an application called hOn. Both protocols are compatible on the transport level but utilize different commands to control appliances. + +Older Haier models controlled by the SmartAir2 application are using the KZW-W002 module. This module can’t be reused, and you need to replace it with an ESP or RPI Pico W module. The USB connector on the board doesn’t support the USB protocol. It is a UART port that just uses a USB connector. To connect the ESP board to your AC you can cut a USB type A cable and connect wires to the climate connector. + +.. list-table:: Haier UART pinout + :header-rows: 1 + + * - Board + - USB + - Wire color + - ESP8266 + * - 5V + - VCC + - red + - 5V + * - GND + - GND + - black + - GND + * - TX + - DATA+ + - green + - RX + * - RX + - DATA- + - white + - TX + +.. figure:: images/usb_pinout.png + :align: center + :width: 70.0% + + KZW-W002 module pinout + +Newer Haier models using a module called ESP32-for-Haier. It is an ESP32 single-core board with an ESP32-S0WD chip. In some cases, you can reuse this module and flash it with ESPHome, but some new modules don’t support this. They look the same but have encryption enabled. + +**Warning!** The new generation of ESP32-Haier devices has encryption enabled, so they can only be flashed with firmware that is signed with a private key. There is no way to make them work with ESPHome, so if you try to do it, the board will get into a boot loop with the error ``rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)`` The only way to recover this board is to flash it with the original image. So before starting your experiments make a backup image. + +.. figure:: images/haier_pinout.jpg + :align: center + :width: 70.0% + + ESP32-for-Haier UART0 pinout + +Also, you can use any other ESP32, ESP8266, or an RPI pico W board. In this case, you will need to cut the original wire or make a connector yourself (the board has a JST SM04B-GHS-TB connector) + +This component requires a :ref:`UART bus ` to be setup. + +.. example_yaml:: esphome_climate_example.yaml + +Configuration variables: +------------------------ + +- **uart_id** (*Optional*, :ref:`config-id`): ID of the UART port to communicate with AC. +- **protocol** (*Optional*, string): Defines communication protocol with AC. Possible values: ``hon`` or ``smartair2``. The default value is ``smartair2``. +- **wifi_signal** (*Optional*, boolean): If ``true`` - send wifi signal level to AC. +- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. The default value is ``200ms``. +- **alternative_swing_control** (*Optional*, boolean): (supported by smartAir2 only) If ``true`` - use alternative values to control swing mode. Use only if the original control method is not working for your AC. +- **status_message_header_size** (*Optional*, int): (supported only by hOn) Define the header size of the status message. Can be used to handle some protocol variations. Use only if you are sure what you are doing. The default value: ``0``. +- **control_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the control packet. Can help with some newer models of ACs that use bigger packets. The default value: ``10``. +- **sensors_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the sensor packet of the status message. Can help with some models of ACs that have bigger sensor packet. The default value: ``22``, minimum value: ``18``. +- **control_method** (*Optional*, list): (supported only by hOn) Defines control method (should be supported by AC). Supported values: ``MONITOR_ONLY`` - no control, just monitor status, ``SET_GROUP_PARAMETERS`` - set all AC parameters with one command (default method), ``SET_SINGLE_PARAMETER`` - set each parameter individually (this method is supported by some new ceiling ACs like AD71S2SM3FA) +- **display** (*Optional*, boolean): Can be used to set the AC display off. +- **beeper** (*Optional*, boolean): Can be used to disable beeping on commands from AC. Supported only by hOn protocol. +- **supported_modes** (*Optional*, list): Can be used to disable some of AC modes. Possible values: ``'OFF'``, ``HEAT_COOL``, ``COOL``, ``HEAT``, ``DRY``, ``FAN_ONLY``. +- **supported_swing_modes** (*Optional*, list): Can be used to disable some swing modes if your AC does not support it. Possible values: ``'OFF'``, ``VERTICAL``, ``HORIZONTAL``, ``BOTH``. +- **supported_presets** (*Optional*, list): Can be used to disable some presets. Possible values for smartair2 are: ``AWAY``, ``BOOST``, ``COMFORT``. Possible values for hOn are: ``AWAY``, ``BOOST``, ``SLEEP``. ``AWAY`` preset can be enabled only in ``HEAT`` mode, it is disabled by default. +- **on_alarm_start** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC activates a new alarm. See :ref:`haier-on_alarm_start`. +- **on_alarm_end** (*Optional*, :ref:`Automation `): (supported only by hOn) Automation to perform when AC deactivates a new alarm. See :ref:`haier-on_alarm_end`. +- **on_status_message** (*Optional*, :ref:`Automation `): Automation to perform when status message received from AC. See :ref:`haier-on_status_message`. +- All other options from :ref:`Climate `. + +Automations +----------- + +.. _haier-on_alarm_start: + +``on_alarm_start`` Trigger +************************** + +This automation will be triggered when a new alarm is activated by AC. The error code of the alarm will be given in the variable ``code`` (``uint8_t``), error message in the variable ``message`` (``const char *``). Those variables can be used in :ref:`lambdas `. + +.. code-block:: yaml + + climate: + - protocol: hon + on_alarm_start: + then: + - logger.log: + level: WARN + format: "Alarm activated. Code: %d. Message: \"%s\"" + args: [ 'code', 'message' ] + +.. _haier-on_alarm_end: + +``on_alarm_end`` Trigger +************************ + +This automation will be triggered when a previously activated alarm is deactivated by AC. The error code of the alarm will be given in the variable ``code`` (``uint8_t``), error message in the variable ``message`` (``const char *``). Those variables can be used in :ref:`lambdas `. + +.. code-block:: yaml + + climate: + - protocol: hon + on_alarm_end: + then: + - logger.log: + level: INFO + format: "Alarm deactivated. Code: %d. Message: \"%s\"" + args: [ 'code', 'message' ] + +.. _haier-on_status_message: + +``on_status_message`` Trigger +***************************** + +This automation will be triggered when component receives new status packet from AC. Raw message binary (without header and checksum) will be provided in the variable ``data`` (``const char *``), message length in the variable ``data_size`` (``uint8_t``). Those variables can be used in :ref:`lambdas `. +This trigger can be used to support some features that unique for the model and not supported by others. + +.. code-block:: yaml + + climate: + - protocol: hon + on_status_message: + then: + - logger.log: + level: INFO + format: "New status message received, size=%d, subcmd=%02X%02X" + args: [ 'data_size', 'data[0]', 'data[1]' ] + +``climate.haier.power_on`` Action +********************************* + +This action turns AC power on. + +.. code-block:: yaml + + on_...: + then: + climate.haier.power_on: device_id + +``climate.haier.power_off`` Action +********************************** + +This action turns AC power off + +.. code-block:: yaml + + on_...: + then: + climate.haier.power_off: device_id + +``climate.haier.power_toggle`` Action +************************************* + +This action toggles AC power + +.. code-block:: yaml + + on_...: + then: + climate.haier.power_toggle: device_id + +``climate.haier.display_on`` Action +*********************************** + +This action turns the AC display on. + +.. code-block:: yaml + + on_...: + then: + climate.haier.display_on: device_id + +``climate.haier.display_off`` Action +************************************ + +This action turns the AC display off. + +.. code-block:: yaml + + on_...: + then: + climate.haier.display_off: device_id + +``climate.haier.health_on`` Action +********************************** + +Turn on health mode (`UV light sterilization `__). + +.. code-block:: yaml + + on_...: + then: + climate.haier.health_on: device_id + +``climate.haier.health_off`` Action +*********************************** + +Turn off health mode. + +.. code-block:: yaml + + on_...: + then: + climate.haier.health_off: device_id + +``climate.haier.beeper_on`` Action +********************************** + +(supported only by hOn) This action enables beep feedback on every command sent to AC. + +.. code-block:: yaml + + on_...: + then: + climate.haier.beeper_on: device_id + +``climate.haier.beeper_off`` Action +*********************************** + +(supported only by hOn) This action disables beep feedback on every command sent to AC (keep in mind that this will not work for IR remote commands). + +.. code-block:: yaml + + on_...: + then: + climate.haier.beeper_off: device_id + +``climate.haier.set_vertical_airflow`` Action +********************************************* + +(supported only by hOn) Set direction for vertical airflow if the vertical swing is disabled. Possible values: Health_Up, Max_Up, Up, Center, Down, Health_Down. + +.. code-block:: yaml + + on_...: + then: + - climate.haier.set_vertical_airflow: + id: device_id + vertical_airflow: Up + +``climate.haier.set_horizontal_airflow`` Action +*********************************************** + +(supported only by hOn) Set direction for horizontal airflow if the horizontal swing is disabled. Possible values: ``Max_Left``, ``Left``, ``Center``, ``Right``, ``Max_Right``. + +.. code-block:: yaml + + on_...: + then: + - climate.haier.set_horizontal_airflow: + id: device_id + vertical_airflow: Right + +``climate.haier.start_self_cleaning`` Action +******************************************** + +(supported only by hOn) Start `self-cleaning `__. + +.. code-block:: yaml + + on_...: + then: + - climate.haier.start_self_cleaning: device_id + +``climate.haier.start_steri_cleaning`` Action +********************************************* + +(supported only by hOn) Start 56°C steri-cleaning. + +.. code-block:: yaml + + on_...: + then: + - climate.haier.start_steri_cleaning: device_id + +See Also +-------- + +- `haier-esphome `__ +- :doc:`Haier Climate Sensors ` +- :doc:`Haier Climate Binary Sensors ` +- :doc:`Haier Climate Text Sensors ` +- :doc:`Haier Climate Buttons ` +- :doc:`Haier Climate Switches ` +- :doc:`/components/climate/index` +- :apiref:`haier/climate/haier_base.h` +- :ghedit:`Edit` diff --git a/docs/examples/esphome_climate_example.yaml b/docs/examples/esphome_climate_example.yaml new file mode 100644 index 0000000..8d279f6 --- /dev/null +++ b/docs/examples/esphome_climate_example.yaml @@ -0,0 +1,47 @@ +# Example configuration entry +climate: + - platform: haier + id: haier_ac + protocol: hon + name: Haier AC + uart_id: ac_port + wifi_signal: true + display: true + visual: + min_temperature: 16 °C + max_temperature: 30 °C + temperature_step: 1 °C + supported_modes: + - 'OFF' + - HEAT_COOL + - COOL + - HEAT + - DRY + - FAN_ONLY + supported_swing_modes: + - 'OFF' + - VERTICAL + - HORIZONTAL + - BOTH + supported_presets: + - AWAY + - BOOST + - SLEEP + on_alarm_start: + then: + - logger.log: + level: WARN + format: "Alarm activated. Code: %d. Message: \"%s\"" + args: [ code, message] + on_alarm_end: + then: + - logger.log: + level: INFO + format: "Alarm deactivated. Code: %d. Message: \"%s\"" + args: [ code, message] + on_status_message: + then: + - logger.log: + level: INFO + format: "New status message received, size=%d, subcmd=%02X%02X" + args: [ 'data_size', 'data[0]', 'data[1]' ] diff --git a/docs/examples/usb_2_uart_boards.rst b/docs/examples/usb_2_uart_boards.rst index c6bd202..9b78402 100644 --- a/docs/examples/usb_2_uart_boards.rst +++ b/docs/examples/usb_2_uart_boards.rst @@ -26,4 +26,4 @@ Currently, only one board with ESP32-C3 confirmed that have native USB support a **Sample ESPHome Configuration that works for this board:** -.. example_yaml:: usb_c3u.yaml \ No newline at end of file +.. example_yaml:: usb_c3u.yaml diff --git a/docs/hon_example.rst b/docs/hon_example.rst index b990c3c..e4396c4 100644 --- a/docs/hon_example.rst +++ b/docs/hon_example.rst @@ -1,182 +1,182 @@ -.. This file is automatically generated by ./docs/script/process_examples.py Python script. - Please, don't change. In case you need to make corrections or changes change - source documentation in ./doc folder or script. - -Example of climate configuration for hOn protocol -================================================= - -Configuration of your climate will depend on capabilities specific model. - -Minimal configuration will look like this: - -.. code-block:: yaml - - uart: - baud_rate: 9600 - tx_pin: 17 - rx_pin: 16 - - climate: - - platform: haier - protocol: hon - name: Haier hOn Climate - - -Maximum configuration witch will use all possible options will look like this: - -.. code-block:: yaml - - uart: - baud_rate: 9600 - tx_pin: 17 - rx_pin: 16 - id: haier_uart - - api: - services: - - service: turn_on - then: - - climate.haier.power_on: haier_ac - - service: turn_off - then: - - climate.haier.power_off: haier_ac - - climate: - - platform: haier - id: haier_ac - protocol: hon - name: Haier hOn Climate - uart_id: haier_uart - wifi_signal: true - visual: - min_temperature: 16 °C - max_temperature: 30 °C - temperature_step: - target_temperature: 1 - current_temperature: 0.5 - supported_modes: - - 'OFF' - - HEAT_COOL - - COOL - - HEAT - - DRY - - FAN_ONLY - supported_swing_modes: - - 'OFF' - - VERTICAL - - HORIZONTAL - - BOTH - supported_presets: - - BOOST - - SLEEP - on_alarm_start: - then: - - homeassistant.service: - service: logbook.log - data: - domain: climate - name: Haier hOn Climate - data_template: - message: "Alarm activated ({{ alarm_code }}): {{alarm_message}}" - variables: - alarm_message: !lambda "return message;" - alarm_code: !lambda "return code;" - - homeassistant.service: - service: notify.persistent_notification - data: - title: "Haier hOn Climate: alarm activated" - data_template: - message: "Code: {{ alarm_code }}, message: \"{{ alarm_message }}\"" - variables: - alarm_message: !lambda "return message;" - alarm_code: !lambda "return code;" - on_alarm_end: - then: - - homeassistant.service: - service: logbook.log - data: - domain: climate - name: Haier hOn Climate - data_template: - message: "Alarm deactivated ({{ alarm_code }}): {{alarm_message}}" - variables: - alarm_message: !lambda "return message;" - alarm_code: !lambda "return code;" - - button: - - platform: haier - haier_id: haier_ac - self_cleaning: - name: Haier hOn Climate start self cleaning - steri_cleaning: - name: Haier hOn Climate start 56°C steri-cleaning - - text_sensor: - - platform: haier - haier_id: haier_ac - cleaning_status: - name: Haier hOn Climate cleaning status - protocol_version: - name: Haier hOn Climate protocol version - - switch: - - platform: haier - beeper: - name: Haier hOn Climate beeper - health_mode: - name: Haier hOn Climate health mode - display: - name: Haier hOn Climate display - quiet_mode: - name: Haier hOn Climate quiet mode - - select: - - platform: haier - haier_id: haier_ac - vertical_airflow: - name: Haier hOn Climate airflow vertical - horizontal_airflow: - name: Haier hOn Climate airflow horizontal - - sensor: - - platform: haier - haier_id: haier_ac - compressor_current: - name: Haier hOn Climate Compressor Current - compressor_frequency: - name: Haier hOn Climate Compressor Frequency - expansion_valve_open_degree: - name: Haier hOn Climate Expansion Valve Open Degree - humidity: - name: Haier hOn Climate Indoor Humidity - indoor_coil_temperature: - name: Haier hOn Climate Indoor Coil Temperature - outdoor_coil_temperature: - name: Haier hOn Climate Outdoor Coil Temperature - outdoor_defrost_temperature: - name: Haier hOn Climate Outdoor Defrost Temperature - outdoor_in_air_temperature: - name: Haier hOn Climate Outdoor In Air Temperature - outdoor_out_air_temperature: - name: Haier hOn Climate Outdoor Out Air Temperature - outdoor_temperature: - name: Haier hOn Climate outdoor temperature - power: - name: Haier hOn Climate Power - - binary_sensor: - - platform: haier - haier_id: haier_ac - compressor_status: - name: Haier hOn Climate Compressor Status - defrost_status: - name: Haier hOn Climate Defrost Status - four_way_valve_status: - name: Haier hOn Climate Four-way Valve Status - indoor_electric_heating_status: - name: Haier hOn Climate Indoor Electric Heating Status - indoor_fan_status: - name: Haier hOn Climate Indoor Fan Status - outdoor_fan_status: - name: Haier hOn Climate Outdoor Fan Status - +.. This file is automatically generated by ./docs/script/process_examples.py Python script. + Please, don't change. In case you need to make corrections or changes change + source documentation in ./doc folder or script. + +Example of climate configuration for hOn protocol +================================================= + +Configuration of your climate will depend on capabilities specific model. + +Minimal configuration will look like this: + +.. code-block:: yaml + + uart: + baud_rate: 9600 + tx_pin: 17 + rx_pin: 16 + + climate: + - platform: haier + protocol: hon + name: Haier hOn Climate + + +Maximum configuration witch will use all possible options will look like this: + +.. code-block:: yaml + + uart: + baud_rate: 9600 + tx_pin: 17 + rx_pin: 16 + id: haier_uart + + api: + services: + - service: turn_on + then: + - climate.haier.power_on: haier_ac + - service: turn_off + then: + - climate.haier.power_off: haier_ac + + climate: + - platform: haier + id: haier_ac + protocol: hon + name: Haier hOn Climate + uart_id: haier_uart + wifi_signal: true + visual: + min_temperature: 16 °C + max_temperature: 30 °C + temperature_step: + target_temperature: 1 + current_temperature: 0.5 + supported_modes: + - 'OFF' + - HEAT_COOL + - COOL + - HEAT + - DRY + - FAN_ONLY + supported_swing_modes: + - 'OFF' + - VERTICAL + - HORIZONTAL + - BOTH + supported_presets: + - BOOST + - SLEEP + on_alarm_start: + then: + - homeassistant.service: + service: logbook.log + data: + domain: climate + name: Haier hOn Climate + data_template: + message: "Alarm activated ({{ alarm_code }}): {{alarm_message}}" + variables: + alarm_message: !lambda "return message;" + alarm_code: !lambda "return code;" + - homeassistant.service: + service: notify.persistent_notification + data: + title: "Haier hOn Climate: alarm activated" + data_template: + message: "Code: {{ alarm_code }}, message: \"{{ alarm_message }}\"" + variables: + alarm_message: !lambda "return message;" + alarm_code: !lambda "return code;" + on_alarm_end: + then: + - homeassistant.service: + service: logbook.log + data: + domain: climate + name: Haier hOn Climate + data_template: + message: "Alarm deactivated ({{ alarm_code }}): {{alarm_message}}" + variables: + alarm_message: !lambda "return message;" + alarm_code: !lambda "return code;" + + button: + - platform: haier + haier_id: haier_ac + self_cleaning: + name: Haier hOn Climate start self cleaning + steri_cleaning: + name: Haier hOn Climate start 56°C steri-cleaning + + text_sensor: + - platform: haier + haier_id: haier_ac + cleaning_status: + name: Haier hOn Climate cleaning status + protocol_version: + name: Haier hOn Climate protocol version + + switch: + - platform: haier + beeper: + name: Haier hOn Climate beeper + health_mode: + name: Haier hOn Climate health mode + display: + name: Haier hOn Climate display + quiet_mode: + name: Haier hOn Climate quiet mode + + select: + - platform: haier + haier_id: haier_ac + vertical_airflow: + name: Haier hOn Climate airflow vertical + horizontal_airflow: + name: Haier hOn Climate airflow horizontal + + sensor: + - platform: haier + haier_id: haier_ac + compressor_current: + name: Haier hOn Climate Compressor Current + compressor_frequency: + name: Haier hOn Climate Compressor Frequency + expansion_valve_open_degree: + name: Haier hOn Climate Expansion Valve Open Degree + humidity: + name: Haier hOn Climate Indoor Humidity + indoor_coil_temperature: + name: Haier hOn Climate Indoor Coil Temperature + outdoor_coil_temperature: + name: Haier hOn Climate Outdoor Coil Temperature + outdoor_defrost_temperature: + name: Haier hOn Climate Outdoor Defrost Temperature + outdoor_in_air_temperature: + name: Haier hOn Climate Outdoor In Air Temperature + outdoor_out_air_temperature: + name: Haier hOn Climate Outdoor Out Air Temperature + outdoor_temperature: + name: Haier hOn Climate outdoor temperature + power: + name: Haier hOn Climate Power + + binary_sensor: + - platform: haier + haier_id: haier_ac + compressor_status: + name: Haier hOn Climate Compressor Status + defrost_status: + name: Haier hOn Climate Defrost Status + four_way_valve_status: + name: Haier hOn Climate Four-way Valve Status + indoor_electric_heating_status: + name: Haier hOn Climate Indoor Electric Heating Status + indoor_fan_status: + name: Haier hOn Climate Indoor Fan Status + outdoor_fan_status: + name: Haier hOn Climate Outdoor Fan Status + diff --git a/docs/script/process_examples.py b/docs/script/process_examples.py index ea14514..391ee82 100644 --- a/docs/script/process_examples.py +++ b/docs/script/process_examples.py @@ -1,6 +1,7 @@ import sys import re import os +import codecs document_header = [ ".. This file is automatically generated by ./docs/script/process_examples.py Python script.\n", @@ -15,17 +16,18 @@ input_file = sys.argv[1] output_file = sys.argv[2] -with open(input_file, "r") as f: +with codecs.open(input_file, "r", "utf-8") as f: fpath = os.path.dirname(os.path.abspath(input_file)) - ofile = open(output_file, "w") + ofile = codecs.open(output_file, "w", "utf-8") lines = f.readlines() - ofile.writelines(document_header) + if "no_header" not in sys.argv: + ofile.writelines(document_header) for line in lines: - m = re.match(r"^.. example_yaml:: ([^\n]+)", line) + m = re.match(r"^.. example_yaml:: ([^\n\r]+)", line) if m: print("Processing example: " + m.group(1)) ofile.write(".. code-block:: yaml\n\n") - example = open(os.path.join(fpath, m.group(1)), "r") + example = codecs.open(os.path.join(fpath, m.group(1)), "r", "utf-8") for l in example.readlines(): ofile.write(" " + l) ofile.write("\n") diff --git a/docs/smartair2_example.rst b/docs/smartair2_example.rst index 6731798..e32bd05 100644 --- a/docs/smartair2_example.rst +++ b/docs/smartair2_example.rst @@ -1,78 +1,78 @@ -.. This file is automatically generated by ./docs/script/process_examples.py Python script. - Please, don't change. In case you need to make corrections or changes change - source documentation in ./doc folder or script. - -Example of climate configuration for smartair2 protocol -======================================================= - -Configuration of your climate will depend on capabilities specific model. - -Minimal configuration will look like this: - -.. code-block:: yaml - - uart: - baud_rate: 9600 - tx_pin: 17 - rx_pin: 16 - - climate: - - platform: haier - name: Haier hOn Climate - - -Maximum configuration witch will use all possible options will look like this: - -.. code-block:: yaml - - uart: - baud_rate: 9600 - tx_pin: 17 - rx_pin: 16 - id: haier_uart - - api: - services: - - service: turn_on - then: - - climate.haier.power_on: haier_ac - - service: turn_off - then: - - climate.haier.power_off: haier_ac - - climate: - - platform: haier - id: haier_ac - protocol: smartAir2 - name: Haier SmartAir2 Climate - uart_id: haier_uart - alternative_swing_control: false - wifi_signal: true - visual: - min_temperature: 16 °C - max_temperature: 30 °C - temperature_step: 1 °C - supported_modes: - - 'OFF' - - HEAT_COOL - - COOL - - HEAT - - DRY - - FAN_ONLY - supported_swing_modes: - - 'OFF' - - VERTICAL - - HORIZONTAL - - BOTH - supported_presets: - - BOOST - - COMFORT - - AWAY - - switch: - - platform: haier - health_mode: - name: Haier SmartAir2 Climate health mode - display: - name: Haier SmartAir2 Climate display - +.. This file is automatically generated by ./docs/script/process_examples.py Python script. + Please, don't change. In case you need to make corrections or changes change + source documentation in ./doc folder or script. + +Example of climate configuration for smartair2 protocol +======================================================= + +Configuration of your climate will depend on capabilities specific model. + +Minimal configuration will look like this: + +.. code-block:: yaml + + uart: + baud_rate: 9600 + tx_pin: 17 + rx_pin: 16 + + climate: + - platform: haier + name: Haier hOn Climate + + +Maximum configuration witch will use all possible options will look like this: + +.. code-block:: yaml + + uart: + baud_rate: 9600 + tx_pin: 17 + rx_pin: 16 + id: haier_uart + + api: + services: + - service: turn_on + then: + - climate.haier.power_on: haier_ac + - service: turn_off + then: + - climate.haier.power_off: haier_ac + + climate: + - platform: haier + id: haier_ac + protocol: smartAir2 + name: Haier SmartAir2 Climate + uart_id: haier_uart + alternative_swing_control: false + wifi_signal: true + visual: + min_temperature: 16 °C + max_temperature: 30 °C + temperature_step: 1 °C + supported_modes: + - 'OFF' + - HEAT_COOL + - COOL + - HEAT + - DRY + - FAN_ONLY + supported_swing_modes: + - 'OFF' + - VERTICAL + - HORIZONTAL + - BOTH + supported_presets: + - BOOST + - COMFORT + - AWAY + + switch: + - platform: haier + health_mode: + name: Haier SmartAir2 Climate health mode + display: + name: Haier SmartAir2 Climate display + diff --git a/docs/sniffing_serial_communication.rst b/docs/sniffing_serial_communication.rst index 759afb0..42bff34 100644 --- a/docs/sniffing_serial_communication.rst +++ b/docs/sniffing_serial_communication.rst @@ -1,103 +1,103 @@ -.. This file is automatically generated by ./docs/script/process_examples.py Python script. - Please, don't change. In case you need to make corrections or changes change - source documentation in ./doc folder or script. - -Sniffing Protocol for Haier Appliance Communication -==================================================== - -If your Haier appliance is not supported or lacks certain features, you may attempt to log the communication between the native dongle and the appliance to "sniff" the protocol. - -Requirements ------------- - -To achieve this, you will need to add additional wires to provide input for a device that will perform the sniffing. This device can be a computer equipped with two TTL to USB converters or an ESP32 module with the ESHome firmware. - -Concept Overview ----------------- - -Haier appliances typically have four wires to connect to the native dongle: +5V, Ground (GND), RX, and TX. For sniffing, we will need three of these wires (RX, TX, GND). The +5V wire can be used to power the ESP device if it is being used for sniffing. - -We will create two pairs from these three wires: RX and GND, and TX and GND. Each pair will connect to a separate UART port on a PC or ESP device, serving as input data. Only RX and GND will be used on the "sniffer" side, as we are merely listening, not transmitting. This setup allows us to monitor the communication between the Haier dongle and the appliance separately. - -.. note:: - Ensure that cutting wires is acceptable before proceeding. - -Using a PC with Two TTL to USB Converters ------------------------------------------ - -**Wiring Diagram:** - -.. raw:: HTML - -

- -To capture the data, you will need to use terminal applications such as Termite, HTerm, CoolTerm, etc. The port configuration should be set as follows: - -- Baud rate: 9600 -- Data bits: 8 -- Stop bits: 1 -- Parity: None - -Using an ESP Module -------------------- - -The approach is similar, but instead of a PC, we will use an ESP device with two UART ports (one for each direction). - -**Wiring Diagram:** - -.. raw:: HTML - -

- -**Sample Configuration for ESP32 Sniffer Board:** - -.. code-block:: yaml - - substitutions: - device_name: "Dual UART Sniffer for Haier Project" - device_id: uart_sniffer - - esphome: - name: ${device_id} - comment: ${device_name} - - esp32: - board: esp32dev - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - api: - reboot_timeout: 0s - - ota: - - platform: esphome - - web_server: - - logger: - tx_buffer_size: 4096 - baud_rate: 0 - level: DEBUG - - uart: - - id: esp_board - rx_pin: GPIO3 - baud_rate: 9600 - debug: - direction: RX - dummy_receiver: true - sequence: - - lambda: UARTDebug::log_hex(uart::UART_DIRECTION_RX, bytes, ' '); - - id: haier_appliance - rx_pin: GPIO16 - baud_rate: 9600 - debug: - direction: RX - dummy_receiver: true - sequence: - - lambda: UARTDebug::log_hex(uart::UART_DIRECTION_TX, bytes, ' '); - - -This configuration will enable you to capture and analyze the communication between the Haier dongle and the appliance effectively. +.. This file is automatically generated by ./docs/script/process_examples.py Python script. + Please, don't change. In case you need to make corrections or changes change + source documentation in ./doc folder or script. + +Sniffing Protocol for Haier Appliance Communication +==================================================== + +If your Haier appliance is not supported or lacks certain features, you may attempt to log the communication between the native dongle and the appliance to "sniff" the protocol. + +Requirements +------------ + +To achieve this, you will need to add additional wires to provide input for a device that will perform the sniffing. This device can be a computer equipped with two TTL to USB converters or an ESP32 module with the ESHome firmware. + +Concept Overview +---------------- + +Haier appliances typically have four wires to connect to the native dongle: +5V, Ground (GND), RX, and TX. For sniffing, we will need three of these wires (RX, TX, GND). The +5V wire can be used to power the ESP device if it is being used for sniffing. + +We will create two pairs from these three wires: RX and GND, and TX and GND. Each pair will connect to a separate UART port on a PC or ESP device, serving as input data. Only RX and GND will be used on the "sniffer" side, as we are merely listening, not transmitting. This setup allows us to monitor the communication between the Haier dongle and the appliance separately. + +.. note:: + Ensure that cutting wires is acceptable before proceeding. + +Using a PC with Two TTL to USB Converters +----------------------------------------- + +**Wiring Diagram:** + +.. raw:: HTML + +

+ +To capture the data, you will need to use terminal applications such as Termite, HTerm, CoolTerm, etc. The port configuration should be set as follows: + +- Baud rate: 9600 +- Data bits: 8 +- Stop bits: 1 +- Parity: None + +Using an ESP Module +------------------- + +The approach is similar, but instead of a PC, we will use an ESP device with two UART ports (one for each direction). + +**Wiring Diagram:** + +.. raw:: HTML + +

+ +**Sample Configuration for ESP32 Sniffer Board:** + +.. code-block:: yaml + + substitutions: + device_name: "Dual UART Sniffer for Haier Project" + device_id: uart_sniffer + + esphome: + name: ${device_id} + comment: ${device_name} + + esp32: + board: esp32dev + + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + + api: + reboot_timeout: 0s + + ota: + - platform: esphome + + web_server: + + logger: + tx_buffer_size: 4096 + baud_rate: 0 + level: DEBUG + + uart: + - id: esp_board + rx_pin: GPIO3 + baud_rate: 9600 + debug: + direction: RX + dummy_receiver: true + sequence: + - lambda: UARTDebug::log_hex(uart::UART_DIRECTION_RX, bytes, ' '); + - id: haier_appliance + rx_pin: GPIO16 + baud_rate: 9600 + debug: + direction: RX + dummy_receiver: true + sequence: + - lambda: UARTDebug::log_hex(uart::UART_DIRECTION_TX, bytes, ' '); + + +This configuration will enable you to capture and analyze the communication between the Haier dongle and the appliance effectively. diff --git a/docs/update_docs.cmd b/docs/update_docs.cmd index 2f6b00e..9a56112 100644 --- a/docs/update_docs.cmd +++ b/docs/update_docs.cmd @@ -2,6 +2,10 @@ SET base_path=%~dp0 cd %base_path%.. echo =============================================================================================================== +echo Updaiting ESPHome haier climate doc +echo =============================================================================================================== +python %base_path%script/process_examples.py %base_path%examples/climate_haier.rst %base_path%esphome-docs/climate/haier.rst no_header +echo =============================================================================================================== echo Updaiting README.rst echo =============================================================================================================== python %base_path%script/make_doc.py README.rst diff --git a/docs/usb_2_uart_boards.rst b/docs/usb_2_uart_boards.rst index 0a37be2..f40164a 100644 --- a/docs/usb_2_uart_boards.rst +++ b/docs/usb_2_uart_boards.rst @@ -1,7 +1,7 @@ -.. This file is automatically generated by ./docs/script/process_examples.py Python script. - Please, don't change. In case you need to make corrections or changes change - source documentation in ./doc folder or script. - +.. This file is automatically generated by ./docs/script/process_examples.py Python script. + Please, don't change. In case you need to make corrections or changes change + source documentation in ./doc folder or script. + List of confirmed board that supports that have native USB support and can communicate using UART protocol ========================================================================================================== @@ -19,8 +19,8 @@ Currently, the following boards have native USB support and can communicate usin **Sample ESPHome Configuration that works for all this boards:** -.. code-block:: yaml - +.. code-block:: yaml + esphome: name: haier platformio_options: @@ -46,7 +46,7 @@ Currently, the following boards have native USB support and can communicate usin climate: - platform: haier name: Haier AC - + ESP32-C3 based boards --------------------- @@ -57,8 +57,8 @@ Currently, only one board with ESP32-C3 confirmed that have native USB support a **Sample ESPHome Configuration that works for this board:** -.. code-block:: yaml - +.. code-block:: yaml + esphome: name: haier platformio_options: @@ -84,4 +84,4 @@ Currently, only one board with ESP32-C3 confirmed that have native USB support a climate: - platform: haier name: Haier AC - +