Documentation updated

.github/workflows/documentation.yaml

@@ -36,3 +36,13 @@ jobs:
       run: python docs/script/process_examples.py docs/examples/smartair2_example.rst docs/smartair2_example.tmp
     - name: Compare temp file with smartair2_example.rst
       run: diff -u --strip-trailing-cr docs/smartair2_example.rst docs/smartair2_example.tmp
+  usb_2_uart_boards:
+    name: Check usb_2_uart_boards
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/[email protected]
+    - name: Run script and save results
+      run: python docs/script/process_examples.py docs/examples/usb_2_uart_boards.rst docs/usb_2_uart_boards.tmp
+    - name: Compare temp file with usb_2_uart_boards.rst
+      run: diff -u --strip-trailing-cr docs/usb_2_uart_boards.rst docs/usb_2_uart_boards.tmp

.github/workflows/examples.yaml

@@ -8,7 +8,7 @@ on:
     branches: [ "master", "dev" , "experimental" ]
 
 jobs:
-  tests:
+  tests_with_base:
     name: Building ${{ matrix.file }}
     runs-on: ubuntu-latest
     strategy:
@@ -19,8 +19,6 @@ jobs:
           - docs/examples/max-smartair2.yaml
           - docs/examples/min-hon.yaml
           - docs/examples/min-smartair2.yaml
-
-
     steps:
       - name: Checkout code
         uses: actions/[email protected]
@@ -29,6 +27,32 @@ jobs:
       - name: Version esphome
         run: esphome version
       - name: Prepering test file
-        run: cat docs/examples/.base.yaml ${{ matrix.file }} > __test__.yaml
+        run: cat docs/examples/.base.yaml ${{ matrix.file }} > ./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:
+          - docs/examples/usb_s3.yaml
+          - docs/examples/usb_c3u.yaml
+    steps:
+      - name: Checkout code
+        uses: actions/[email protected]
+      - 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 __test__.yaml
+        run: esphome compile ${{ matrix.file }}

docs/examples/.base.yaml

@@ -8,12 +8,12 @@ logger:
   level: DEBUG
 
 wifi:
-  ssid: test_ssid
-  password: test_pass
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
 
 external_components:
   source:
     type: local
-    path: ./components
+    path: ../../components
   components: [ haier ]
 

docs/examples/usb_2_uart_boards.rst

@@ -0,0 +1,29 @@
+List of confirmed board that supports that have native USB support and can communicate using UART protocol
+==========================================================================================================
+
+Here you can find a list of confirmed boards that have native USB support and can communicate using UART protocol with sample configuration for each case. Thease configurations not compleate and should be considered as a starting point for integrating your Haier AC.
+
+
+ESP32-S3 based boards
+---------------------
+
+Currently, the following boards have native USB support and can communicate using UART protocol:
+
+- `M5Stack AtomS3U <https://shop.m5stack.com/products/atoms3u>`_ 
+- `Lilygo T-Dongle S3 <https://www.lilygo.cc/products/t-dongle-s3?variant=42455191519413>`_ 
+- `M5Stamp ESP32S3 Module <https://shop.m5stack.com/products/m5stamp-esp32s3-module>`_ with USB-C to USB-A male adapter.  
+
+**Sample ESPHome Configuration that works for all this boards:**
+
+.. example_yaml:: usb_s3.yaml
+
+ESP32-C3 based boards
+---------------------
+
+Currently, only one board with ESP32-C3 confirmed that have native USB support and can communicate using UART protocol:
+
+- `M5Stamp C3U (white color) <https://shop.m5stack.com/products/m5stamp-c3u-mate-with-pin-headers>`_ with USB-C to USB-A male adapter. **But be careful: M5Stamp C3 board (black color, without U at the end) have a dedicated chip for USB and can't be used for UART communication!** 
+
+**Sample ESPHome Configuration that works for this board:**
+
+.. example_yaml:: usb_c3u.yaml

docs/examples/usb_c3u.yaml

@@ -0,0 +1,25 @@
+esphome:
+  name: haier
+  platformio_options:
+    board_build.flash_mode: dio
+
+esp32:
+  board: esp32-c3-devkitm-1
+  framework:
+    type: arduino
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+uart:
+  baud_rate: 9600
+  tx_pin: 18
+  rx_pin: 19
+
+logger:
+  level: WARN
+
+climate:
+  - platform: haier
+    name: Haier AC

docs/examples/usb_s3.yaml

@@ -0,0 +1,25 @@
+esphome:
+  name: haier
+  platformio_options:
+    board_build.flash_mode: dio
+
+esp32:
+  board: esp32-s3-devkitc-1
+  framework:
+    type: arduino
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+
+uart:
+  baud_rate: 9600
+  tx_pin: 19
+  rx_pin: 20
+
+logger:
+  level: WARN
+
+climate:
+  - platform: haier
+    name: Haier AC

docs/faq.rst

@@ -33,39 +33,7 @@ Compatibility and Support
 
 However, ESP modules equipped with the ESP32-S3 chip have native USB support and can potentially communicate using UART protocol if the USB Type-A connector is directly connected to the ESP pins without an intermediary chip. This setup allows for creating an ESPHome configuration that utilizes the same pins for UART communication.
 
-Currently, the `M5Stack AtomS3U <https://shop.m5stack.com/products/atoms3u>`_ and `Lilygo T-Dongle S3 <https://www.lilygo.cc/products/t-dongle-s3?variant=42455191519413>`_ confirmed board that supports this configuration, though there may be others.
-
-**Sample ESPHome Configuration that works for both M5Stack AtomS3U and Lilygo T-Dongle S3:**
-
-.. code-block:: yaml
-
-    esphome:
-      name: haier
-      platformio_options:
-        board_build.flash_mode: dio
-
-    esp32:
-      board: esp32-s3-devkitc-1
-      framework:
-        type: arduino
-
-    wifi:
-      ssid: !secret wifi_ssid
-      password: !secret wifi_password
-
-    uart:
-      baud_rate: 9600
-      tx_pin: 19
-      rx_pin: 20
-
-    logger:
-      level: WARN
-
-    climate:
-      - platform: haier
-        name: Haier AC
-    
-This configuration is a starting point for integrating your Haier AC with an ESP32-S3 based board.
+Here you can find `list of confirmed board that supports that have native USB support and can communicate using UART protocol <./usb_2_uart_boards.rst>`_ with sample configuration for each case.
 
 Troubleshooting
 ---------------
@@ -77,7 +45,7 @@ Troubleshooting
 
 - **Configuration Issues:** There might be issues with your ESPHome configuration.
 - **Hardware Problems:** The problem could lie with the ESP module or other hardware components.
-- **Wiring Issues:** Incorrect wiring or problems with the pins could be causing communication failures.
+- **Wiring Issues:** Incorrect wiring or problems with the pins could be causing communication failures. Most common mistake is to swap RX and TX pins.
 - **Protocol Mismatch:** The AC might use a different protocol for communication or may not support serial communication at all.
 
 **Troubleshooting Steps:**

docs/usb_2_uart_boards.rst

@@ -0,0 +1,87 @@
+.. 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
+==========================================================================================================
+
+Here you can find a list of confirmed boards that have native USB support and can communicate using UART protocol with sample configuration for each case. Thease configurations not compleate and should be considered as a starting point for integrating your Haier AC.
+
+
+ESP32-S3 based boards
+---------------------
+
+Currently, the following boards have native USB support and can communicate using UART protocol:
+
+- `M5Stack AtomS3U <https://shop.m5stack.com/products/atoms3u>`_ 
+- `Lilygo T-Dongle S3 <https://www.lilygo.cc/products/t-dongle-s3?variant=42455191519413>`_ 
+- `M5Stamp ESP32S3 Module <https://shop.m5stack.com/products/m5stamp-esp32s3-module>`_ with USB-C to USB-A male adapter.  
+
+**Sample ESPHome Configuration that works for all this boards:**
+
+.. code-block:: yaml
+
+    esphome:
+      name: haier
+      platformio_options:
+        board_build.flash_mode: dio
+    
+    esp32:
+      board: esp32-s3-devkitc-1
+      framework:
+        type: arduino
+    
+    wifi:
+      ssid: !secret wifi_ssid
+      password: !secret wifi_password
+    
+    uart:
+      baud_rate: 9600
+      tx_pin: 19
+      rx_pin: 20
+    
+    logger:
+      level: WARN
+    
+    climate:
+      - platform: haier
+        name: Haier AC
+
+
+ESP32-C3 based boards
+---------------------
+
+Currently, only one board with ESP32-C3 confirmed that have native USB support and can communicate using UART protocol:
+
+- `M5Stamp C3U (white color) <https://shop.m5stack.com/products/m5stamp-c3u-mate-with-pin-headers>`_ with USB-C to USB-A male adapter. **But be careful: M5Stamp C3 board (black color, without U at the end) have a dedicated chip for USB and can't be used for UART communication!** 
+
+**Sample ESPHome Configuration that works for this board:**
+
+.. code-block:: yaml
+
+    esphome:
+      name: haier
+      platformio_options:
+        board_build.flash_mode: dio
+    
+    esp32:
+      board: esp32-c3-devkitm-1
+      framework:
+        type: arduino
+    
+    wifi:
+      ssid: !secret wifi_ssid
+      password: !secret wifi_password
+    
+    uart:
+      baud_rate: 9600
+      tx_pin: 18
+      rx_pin: 19
+    
+    logger:
+      level: WARN
+    
+    climate:
+      - platform: haier
+        name: Haier AC
+