Bump version to 2024.12.14 [skip-versioning]

New LED mapping for US 3&4-Gang

.github/workflows/release_tag.yml

@@ -1,32 +0,0 @@
----
-name: Update Tags
-
-# yamllint disable-line rule:truthy
-on:
-  release:
-    types: [published]
-
-jobs:
-  update-tags:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@main
-        with:
-          fetch-depth: '0'
-
-      - name: Set up Git
-        run: |
-          git config --local user.email "action@github.com"
-          git config --local user.name "GitHub Action"
-
-      - name: Move and push stable tag
-        run: |
-          git tag -f stable ${{ github.event.release.tag_name }}
-          git push -f origin stable
-
-      - name: Move and push latest tag
-        run: |
-          git tag -f latest ${{ github.event.release.tag_name }}
-          git push -f origin latest
-...

.github/workflows/validate_esphome.yml

@@ -1,8 +1,7 @@
 ---
-name: Validate ESPHome
+name: Validate ESPHome (Latest)
 
-# yamllint disable-line rule:truthy
-on:
+on:  # yamllint disable-line rule:truthy
   workflow_dispatch:
 
 concurrency:
@@ -30,8 +29,6 @@ jobs:
 
   build_basic:
     name: Basic
-    needs:
-      - code_scan
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@main
@@ -39,10 +36,10 @@ jobs:
         uses: esphome/build-action@main
         with:
           yaml-file: ".test/esphome_ard_basic.yaml"
+          version: latest
 
   build_bluetooth_proxy_4:
     name: Bluetooth Proxy (IDF)
-    needs: build_basic
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@main
@@ -50,10 +47,10 @@ jobs:
         uses: esphome/build-action@main
         with:
           yaml-file: ".test/esphome_idf_bluetooth_proxy.yaml"
+          version: latest
 
   build_bluetooth_proxy_53:
     name: Bluetooth Proxy (IDF v5.3)
-    needs: build_basic
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@main
@@ -61,4 +58,5 @@ jobs:
         uses: esphome/build-action@main
         with:
           yaml-file: ".test/esphome_idf53_bluetooth_proxy.yaml"
+          version: latest
 ...

.github/workflows/validate_esphome_beta.yml

@@ -11,6 +11,8 @@ on:  # yamllint disable-line rule:truthy
       - "*.c"
       - "*.cpp"
       - "*.py"
+    branches:
+      - main
   pull_request:
     paths:
       - "*.yaml"
@@ -47,8 +49,6 @@ jobs:
 
   build_basic:
     name: Basic
-    needs:
-      - code_scan
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@main
@@ -60,7 +60,6 @@ jobs:
 
   build_bluetooth_proxy_4:
     name: Bluetooth Proxy (IDF)
-    needs: build_basic
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@main
@@ -72,7 +71,6 @@ jobs:
 
   build_bluetooth_proxy_53:
     name: Bluetooth Proxy (IDF v5.3)
-    needs: build_basic
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@main

.github/workflows/versioning.yml

@@ -1,31 +1,48 @@
-# Workflow for managing versioning, tagging, and conditional updates
+# This GitHub Actions workflow handles version bumping and tag updates.
+# It can be triggered either by:
+# 1. Pushing to main branch - automatically bumps version and updates tags
+# 2. Manual dispatch - allows independent control over stable and latest tags
+
 ---
-name: Bump Version and Tag
+
+name: Version and Tags
 
 on:  # yamllint disable-line rule:truthy
   push:
     branches:
       - main
+    paths-ignore:
+      - '**/VERSION'
+      - '**/VERSION_YAML'
+
   workflow_dispatch:
     inputs:
       update_stable:
         description: "Update stable tag?"
         required: true
-        default: "false"
+        default: false
+        type: boolean
+      update_latest:
+        description: "Update latest tag?"
+        required: true
+        default: false
+        type: boolean
 
 jobs:
-  versioning:
+  version-and-tag:
     runs-on: ubuntu-latest
-
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set up Git
         run: |
           git config user.name "GitHub Actions"
           git config user.email "actions@github.com"
 
-      - name: Bump Version
+      - name: Bump version
         run: |
           chmod +x ./versioning/bump_version.sh
           ./versioning/bump_version.sh
@@ -34,12 +51,56 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git main
-          git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git --tags
+          git push origin main
+          git push origin --tags --force
 
-      - name: Conditionally Update Stable Tag
-        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.update_stable == 'true' }}
+      - name: Update stable tag
+        if: |
+          success() && (
+            github.event_name == 'workflow_dispatch' && inputs.update_stable ||
+            github.event_name == 'push'
+          )
         run: |
-          git tag -f stable
-          git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git stable --force
+          # Verify version bump was successful
+          if [ ! -f "./versioning/VERSION" ]; then
+            echo "Error: VERSION file not found. Version bump may have failed."
+            exit 1
+          fi
+
+          # Backup existing tag
+          if git rev-parse --verify stable >/dev/null 2>&1; then
+            OLD_STABLE=$(git rev-parse stable)
+            echo "Backing up current stable tag ($OLD_STABLE)"
+          fi
+
+          # Update tag
+          NEW_VERSION=$(cat ./versioning/VERSION)
+          echo "Updating stable tag to $NEW_VERSION"
+          git tag -fa stable -m "Update stable tag"
+          git push origin stable --force
+
+      - name: Update latest tag
+        if: |
+          success() && (
+            github.event_name == 'workflow_dispatch' && inputs.update_latest ||
+            github.event_name == 'push'
+          )
+        run: |
+          # Verify version bump was successful
+          if [ ! -f "./versioning/VERSION" ]; then
+            echo "Error: VERSION file not found. Version bump may have failed."
+            exit 1
+          fi
+
+          # Backup existing tag
+          if git rev-parse --verify latest >/dev/null 2>&1; then
+            OLD_LATEST=$(git rev-parse latest)
+            echo "Backing up current latest tag ($OLD_LATEST)"
+          fi
+
+          # Update tag
+          NEW_VERSION=$(cat ./versioning/VERSION)
+          echo "Updating latest tag to $NEW_VERSION"
+          git tag -fa latest -m "Update latest tag"
+          git push origin latest --force
 ...

.test/esphome_ard_basic.yaml

@@ -1,6 +1,6 @@
 ---
 packages:
-  basic_package: !include ../TX-Ultimate-Easy-ESPHome.yaml  # Basic package
+  basic_package: !include ../ESPHome/TX-Ultimate-Easy-ESPHome_core.yaml  # Basic package
 
 esp32:
   framework:

.test/esphome_idf53_bluetooth_proxy.yaml

@@ -1,6 +1,6 @@
 ---
 packages:
-  basic_package: !include ../TX-Ultimate-Easy-ESPHome.yaml  # Core package
+  core_package: !include ../ESPHome/TX-Ultimate-Easy-ESPHome_core.yaml
   addon_bluetooth_proxy: !include ../ESPHome/TX-Ultimate-Easy-ESPHome_addon_ble_proxy.yaml
 
 esp32:

.test/esphome_idf_bluetooth_proxy.yaml

@@ -1,5 +1,5 @@
 ---
 packages:
-  basic_package: !include ../TX-Ultimate-Easy-ESPHome.yaml  # Core package
+  core_package: !include ../ESPHome/TX-Ultimate-Easy-ESPHome_core.yaml
   addon_bluetooth_proxy: !include ../ESPHome/TX-Ultimate-Easy-ESPHome_addon_ble_proxy.yaml
 ...

ESPHome/TX-Ultimate-Easy-ESPHome_addon_ble_proxy.yaml

@@ -11,6 +11,27 @@
 ##### - For normal system use, modifications to this file are NOT required.                    #####
 ####################################################################################################
 ---
+substitutions:
+  # RTTTL format: name:d=duration,o=octave,b=tempo:notes
+  # d=32 (32nd note), o=5 (octave 5), b=100 (tempo 100)
+  tone_volume_change: "scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b"  # Use "none" to disable sound
+
+api:
+  actions:
+    - action: rtttl_play
+      variables:
+        # The RTTTL string for the melody to be played.
+        # It should follow the RTTTL format, including the melody's name,
+        # default settings, and a sequence of notes.
+        tone: string
+      then:
+        - lambda: |-
+            rtttl_speaker->stop();
+            if (rtttl_speaker_gain->state > 0) {
+              ESP_LOGI("api", "Play tone: '%s'", tone.c_str());
+              rtttl_speaker->play(tone.c_str());
+            }
+
 bluetooth_proxy:
 
 esp32:
@@ -33,17 +54,54 @@ esphome:
     build_flags:
       - -D TX_ULTIMATE_EASY_ADDON_BLE_PROXY
 
-i2s_audio: !remove
-
 light:
   - id: !extend light_full
     platform: esp32_rmt_led_strip
     rgb_order: GRB
-    rmt_channel: 0
+    rmt_channel: 1
     chipset: ws2812
     type: !remove
     variant: !remove
     max_refresh_rate: 33ms
+    use_psram: true
 
 media_player: !remove
+
+number:
+  - id: rtttl_speaker_gain
+    name: Sound - Volume
+    platform: template
+    max_value: 100
+    min_value: 0
+    step: 1
+    initial_value: 100
+    unit_of_measurement: "%"
+    internal: false
+    disabled_by_default: true
+    entity_category: config
+    device_class: sound_pressure
+    restore_value: true
+    optimistic: true
+    set_action:
+      then:
+        - lambda: |-
+            rtttl_speaker->set_gain((100-(x/10.0f))/100.0f);
+            std::string tone_volume_change = "${tone_volume_change}";
+            // Play sound if tone_volume_change is not "none"
+            if (x > 0 and !tone_volume_change.empty() and tone_volume_change != "none")
+              rtttl_speaker->play(tone_volume_change);
+            rtttl_speaker->dump_config();
+
+rtttl:
+  - id: rtttl_speaker
+    speaker: mp_speaker
+
+speaker:
+  - id: mp_speaker
+    platform: i2s_audio
+    dac_type: external
+    i2s_dout_pin: GPIO15
+    i2s_audio_id: if_i2s_audio
+    i2s_comm_fmt: stand_msb
+    channel: mono
 ...

ESPHome/TX-Ultimate-Easy-ESPHome_core.yaml

@@ -27,7 +27,6 @@ substitutions:
 
 packages:
   # yamllint disable rule:colons
-  core_api:          !include TX-Ultimate-Easy-ESPHome_core_api.yaml
   core_hw_buttons:   !include TX-Ultimate-Easy-ESPHome_core_hw_buttons.yaml
   core_hw_leds:      !include TX-Ultimate-Easy-ESPHome_core_hw_leds.yaml
   core_hw_relays:    !include TX-Ultimate-Easy-ESPHome_core_hw_relays.yaml
@@ -36,6 +35,12 @@ packages:
   core_hw_vibration: !include TX-Ultimate-Easy-ESPHome_core_hw_vibration.yaml
   # yamllint enable rule:colons
 
+api:
+  id: api_server
+  on_client_connected:
+    then:
+      - script.execute: publish_device_info
+
 button:
   - id: bt_restart
     name: Restart
@@ -74,21 +79,35 @@ improv_serial:
   id: serial_improv
 
 logger:
-  level: INFO
+  level: DEBUG
 
 ota:
   platform: esphome
 
 psram:
+  mode: octal
+  speed: 40MHz
 
 script:
+  - id: api_send_ha_event_boot
+    mode: queued
+    parameters:
+      type: string
+    then:
+      - homeassistant.event:
+          event: esphome.tx_ultimate_easy
+          data:
+            device_name: !lambda return tx_device_name->state.c_str();
+            firmware: ${version}
+            domain: boot
+            type: !lambda return type.c_str();
+
   - id: boot_done
     mode: restart
     then:
       - script.execute:
-          id: send_event_to_ha
-          component: boot
-          event: done
+          id: api_send_ha_event_boot
+          type: done
 
   - id: boot_initialize
     mode: restart
@@ -98,9 +117,8 @@ script:
       #   - HW Relays
       #   - HW Touch
       - script.execute:
-          id: send_event_to_ha
-          component: boot
-          event: start
+          id: api_send_ha_event_boot
+          type: start
 
   - id: boot_sequence
     mode: restart
@@ -144,6 +162,9 @@ select:
     entity_category: config
     disabled_by_default: false
     icon: mdi:dip-switch
+    on_value:
+      then:
+        - lambda: tx_ultimate->set_gang_count(static_cast<uint8_t>(i)+1);
 
 text_sensor:
   - id: tx_fw_version

ESPHome/TX-Ultimate-Easy-ESPHome_core_api.yaml

@@ -1,41 +0,0 @@
-####################################################################################################
-#####                              TX Ultimate Easy for ESPHome                                #####
-#####                  Repository: https://github.com/edwardtfn/TX-Ultimate-Easy               #####
-####################################################################################################
-##### Purpose: ESPHome Core - API                                                              #####
-####################################################################################################
-##### Author: edwardtfn - https://github.com/edwardtfn - https://buymeacoffee.com/edwardfirmo  #####
-####################################################################################################
-##### NOTE:                                                                                    #####
-##### - Make changes ONLY if absolutely necessary and you have the required knowledge.         #####
-##### - For normal system use, modifications to this file are NOT required.                    #####
-####################################################################################################
----
-api:
-  id: api_server
-  on_client_connected:
-    then:
-      - script.execute: publish_device_info
-
-script:
-  - id: !extend button_action
-    then:
-      - script.execute:
-          id: send_event_to_ha
-          component: !lambda return component.c_str();
-          event: !lambda return event.c_str();
-
-  - id: send_event_to_ha
-    mode: queued
-    parameters:
-      component: string
-      event: string
-    then:
-      - homeassistant.event:
-          event: esphome.tx_ultimate_easy
-          data:
-            device_name: !lambda return tx_device_name->state.c_str();
-            firmware: ${version}
-            component: !lambda return component.c_str();
-            event: !lambda return event.c_str();
-...

ESPHome/TX-Ultimate-Easy-ESPHome_core_hw_buttons.yaml

@@ -20,111 +20,59 @@ substitutions:
   BUTTON_3_ACTION_TEXT: "Relay 3 (toggle)"
   BUTTON_4_ACTION_TEXT: "Relay 4 (toggle)"
 
-binary_sensor:
-  - id: bs_button_1
-    name: Button 1
-    icon: mdi:gesture-tap-box
-    internal: false
-    platform: template
-    on_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_1
-            event: click
-    on_double_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_1
-            event: double_click
-    on_multi_click:
-      - timing: &long_click-timing
-          - ON for at least 0.8s
-        invalid_cooldown: ${invalid_cooldown}
-        then:
-          - script.execute:
-              id: button_action
-              component: bs_button_1
-              event: long_click
+  BUTTON_CLICK_MIN_LENGTH: '50'    # The minimum duration the click should last, in msec
+  BUTTON_CLICK_MAX_LENGTH: '350'   # The maximum duration the click should last, in msec
+  BUTTON_MULTI_CLICK_DELAY: '250'  # The time to wait for another click, in msec
+  BUTTON_PRESS_TIMEOUT: '10000'    # Ignore if button is pressed for longer than this time, in msec
+  BUTTON_LONG_PRESS_DELAY: '800'   # The time to wait to consider a long press, in msec
 
-  - id: bs_button_2
+  # Button numbers constants
+  BUTTON_1_ID: '1'
+  BUTTON_2_ID: '2'
+  BUTTON_3_ID: '3'
+  BUTTON_4_ID: '4'
+
+binary_sensor:
+  - &binary_sensor_button_base
+    id: bs_button_2
     name: Button 2
     icon: mdi:gesture-tap-box
-    internal: true
     platform: template
-    on_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_2
-            event: click
-    on_double_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_2
-            event: double_click
-    on_multi_click:
-      - timing: *long_click-timing
-        invalid_cooldown: ${invalid_cooldown}
-        then:
-          - script.execute:
-              id: button_action
-              component: bs_button_2
-              event: long_click
+    internal: true
 
   - id: bs_button_3
     name: Button 3
-    icon: mdi:gesture-tap-box
-    internal: true
-    platform: template
-    on_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_3
-            event: click
-    on_double_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_3
-            event: double_click
-    on_multi_click:
-      - timing: *long_click-timing
-        invalid_cooldown: ${invalid_cooldown}
-        then:
-          - script.execute:
-              id: button_action
-              component: bs_button_3
-              event: long_click
+    <<: *binary_sensor_button_base
 
   - id: bs_button_4
     name: Button 4
-    icon: mdi:gesture-tap-box
-    internal: true
-    platform: template
-    on_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_4
-            event: click
-    on_double_click:
-      then:
-        - script.execute:
-            id: button_action
-            component: bs_button_4
-            event: double_click
-    on_multi_click:
-      - timing: *long_click-timing
-        invalid_cooldown: ${invalid_cooldown}
-        then:
-          - script.execute:
-              id: button_action
-              component: bs_button_4
-              event: long_click
+    <<: *binary_sensor_button_base
+
+  - id: bs_button_1
+    name: Button 1
+    internal: false
+    <<: *binary_sensor_button_base
+
+globals:
+  - id: button_press_button
+    type: uint8_t
+    restore_value: false
+    initial_value: '0'
+
+  - id: button_press_position
+    type: uint8_t
+    restore_value: false
+    initial_value: '0'
+
+  - id: button_press_start_time
+    type: uint32_t
+    restore_value: false
+    initial_value: '0'
+
+  - id: click_counter
+    type: uint8_t
+    restore_value: false
+    initial_value: '0'
 
 script:
   - id: !extend boot_initialize
@@ -160,11 +108,89 @@ script:
   - id: button_action
     mode: parallel
     parameters:
-      component: string
-      event: string
-    then:  # There's nothing here so far
-    # Extended by:
-    #   - core_api
+      button: uint8_t
+      action: string
+      count: uint8_t
+    then:
+      - homeassistant.event:
+          event: esphome.tx_ultimate_easy
+          data:
+            device_name: !lambda return tx_device_name->state.c_str();
+            firmware: ${version}
+            domain: touch
+            type: button
+            action: !lambda return action.c_str();
+            button_id: !lambda return button;
+            count: !lambda return count;
+            position: !lambda return id(button_press_position);
+      - lambda: |-
+          ESP_LOGI("core_hw_buttons", "Button %" PRIu8 " action: '%s'", button, action.c_str());
+          if (action == "click") {
+            switch (button) {
+              case ${BUTTON_1_ID}:
+                bs_button_1_click_event->publish_state(true);
+                break;
+              case ${BUTTON_2_ID}:
+                bs_button_2_click_event->publish_state(true);
+                break;
+              case ${BUTTON_3_ID}:
+                bs_button_3_click_event->publish_state(true);
+                break;
+              case ${BUTTON_4_ID}:
+                bs_button_4_click_event->publish_state(true);
+                break;
+            }
+          } else if (action == "double_click") {
+            switch (button) {
+              case ${BUTTON_1_ID}:
+                bs_button_1_double_click_event->publish_state(true);
+                break;
+              case ${BUTTON_2_ID}:
+                bs_button_2_double_click_event->publish_state(true);
+                break;
+              case ${BUTTON_3_ID}:
+                bs_button_3_double_click_event->publish_state(true);
+                break;
+              case ${BUTTON_4_ID}:
+                bs_button_4_double_click_event->publish_state(true);
+                break;
+            }
+          } else if (action == "long_press") {
+            switch (button) {
+              case ${BUTTON_1_ID}:
+                bs_button_1_long_press_event->publish_state(true);
+                break;
+              case ${BUTTON_2_ID}:
+                bs_button_2_long_press_event->publish_state(true);
+                break;
+              case ${BUTTON_3_ID}:
+                bs_button_3_long_press_event->publish_state(true);
+                break;
+              case ${BUTTON_4_ID}:
+                bs_button_4_long_press_event->publish_state(true);
+                break;
+            }
+          }
+          id(button_press_button) = 0;
+          id(button_press_position) = 0;
+          id(button_press_start_time) = 0;
+          id(click_counter) = 0;
+          buttons_release->execute();
+
+  - id: button_click_event
+    mode: restart
+    parameters:
+      button: uint8_t
+      click_count: uint8_t
+    then:
+      - delay:
+          milliseconds: ${BUTTON_MULTI_CLICK_DELAY}
+      - lambda: |-
+          std::string event_name;
+          if (click_count == 1) event_name = "click";
+          else if (click_count == 2) event_name = "double_click";
+          else event_name = "multiple_click";
+          button_action->execute(button, event_name.c_str(), click_count);
 
   - id: buttons_release
     mode: restart
@@ -187,42 +213,65 @@ script:
     then:
       - script.execute:
           id: touch_on_press_buttons
-          touch_x: !lambda return touch_x;
+          button: !lambda return button;
+          position: !lambda return position;
 
   - id: touch_on_press_buttons
     mode: restart
     parameters:
-      touch_x: uint8_t
+      button: uint8_t
+      position: uint8_t
     then:
       - lambda: |-
-          auto model_index = sl_tx_model_gang->active_index();
-          if (model_index.has_value()) {
-            uint8_t model_idx = model_index.value() + 1;
-            switch (model_idx) {
-              case 1:  // 1 Gang
-                bs_button_1->publish_state(true);
-                break;
-              case 2:  // 2 Gang
-                if (touch_x <= 5) bs_button_1->publish_state(true);
-                else bs_button_2->publish_state(true);
-                break;
-              case 3:  // 3 Gang
-                if (touch_x <= 3) bs_button_1->publish_state(true);
-                else if (touch_x <= 7) bs_button_2->publish_state(true);
-                else bs_button_3->publish_state(true);
-                break;
-              case 4:  // 4 Gang
-                if (touch_x <= 2) bs_button_1->publish_state(true);
-                else if (touch_x <= 5) bs_button_2->publish_state(true);
-                else if (touch_x <= 8) bs_button_3->publish_state(true);
-                else bs_button_4->publish_state(true);
-                break;
-            }
+          id(button_press_start_time) = millis();
+          id(button_press_button) = button;
+          // Update counters
+          if (id(button_press_position) == position) {
+            id(click_counter)++;
+          } else {
+            id(click_counter) = 1;
+            id(button_press_position) = position;
+          }
+          // Update binary sensor
+          switch (button) {
+            case 1:
+              bs_button_1->publish_state(true);
+              break;
+            case 2:
+              bs_button_2->publish_state(true);
+              break;
+            case 3:
+              bs_button_3->publish_state(true);
+              break;
+            case 4:
+              bs_button_4->publish_state(true);
+              break;
           }
 
   - id: !extend touch_on_release
     then:
-      - script.execute: buttons_release
+      - lambda: |-
+          uint32_t current_time = millis();
+          buttons_release->execute();
+          if (id(button_press_start_time) > 0 and
+              id(button_press_start_time) < current_time) {
+            uint32_t press_duration  = current_time - id(button_press_start_time);
+            // Handle overflow (optional, since it's unlikely to happen here)
+            ESP_LOGI("core_hw_buttons", "Button press duration: %" PRIu32 " ms", press_duration);
+            if (press_duration < ${BUTTON_CLICK_MIN_LENGTH}) {
+              ESP_LOGW("core_hw_buttons", "Ignoring button press (too short)");
+            } else if (press_duration >= ${BUTTON_CLICK_MIN_LENGTH} and
+                        press_duration <= ${BUTTON_CLICK_MAX_LENGTH}) { // Short/normal click
+              button_click_event->execute(id(button_press_button), id(click_counter));
+            } else if (press_duration >= ${BUTTON_LONG_PRESS_DELAY} and press_duration <= ${BUTTON_PRESS_TIMEOUT}) {
+              button_action->execute(id(button_press_button), "long_press", 1);
+            } else if (press_duration > ${BUTTON_PRESS_TIMEOUT}) { // Timeout or invalid
+              ESP_LOGW("core_hw_buttons", "Button press cancelled or timed out after ${BUTTON_PRESS_TIMEOUT} ms");
+            }
+          } else {
+            ESP_LOGW("core_hw_buttons", "Press event timestamp not recorded yet");
+          }
+          id(button_press_start_time) = 0;
 
   - id: !extend touch_swipe_left
     then:

ESPHome/TX-Ultimate-Easy-ESPHome_core_hw_leds.yaml

@@ -25,6 +25,11 @@ substitutions:
   LIGHT_TRANSITION_TURN_OFF: '0'  # Transition time in msec
   LIGHT_BRIGHTNESS_TURN_ON: '0'   # Brightness (1 to 100%, 0 to not set it)
 
+  LIGHT_FULL_RESTORE_MODE: RESTORE_DEFAULT_OFF
+  LIGHT_SIDES_RESTORE_MODE: RESTORE_DEFAULT_OFF
+  LIGHT_INDIVIDUAL_RESTORE_MODE: RESTORE_DEFAULT_OFF
+  LIGHT_RELAYS_RESTORE_MODE: RESTORE_DEFAULT_OFF
+
 globals:
   - id: gb_lights_1
     type: std::vector<light::LightState*>
@@ -44,6 +49,7 @@ light:
     # method: esp32_rmt
     num_leds: 32
     pin: GPIO13
+    restore_mode: ${LIGHT_FULL_RESTORE_MODE}
 
   # Those lights are available based on the model selections
   - &light_partition_with_effects
@@ -52,6 +58,7 @@ light:
     platform: partition
     default_transition_length: ${default_transition_length}
     internal: true
+    restore_mode: ${LIGHT_SIDES_RESTORE_MODE}
     effects:
       - addressable_rainbow:
           name: "Rainbow"
@@ -184,6 +191,7 @@ light:
     platform: partition
     disabled_by_default: true
     default_transition_length: ${default_transition_length}
+    restore_mode: ${LIGHT_INDIVIDUAL_RESTORE_MODE}
     segments:
       - id: light_full
         from: 0
@@ -417,6 +425,7 @@ light:
     platform: partition
     internal: true
     default_transition_length: ${default_transition_length}
+    restore_mode: ${LIGHT_RELAYS_RESTORE_MODE}
     segments:
       - id: light_full
         from: 9
@@ -635,8 +644,8 @@ light:
     <<: *light_partition_relays
     segments:
       - id: light_full
-        from: 17
-        to: 18
+        from: 16
+        to: 17
   - id: light_us_rl_3_3_right
     name: Light - Relay 3 of 3 (right)
     <<: *light_partition_relays
@@ -649,8 +658,8 @@ light:
     <<: *light_partition_relays
     segments:
       - id: light_full
-        from: 12
-        to: 12
+        from: 23
+        to: 24
   - id: light_us_rl_1_4_right
     name: Light - Relay 1 of 4 (right)
     <<: *light_partition_relays
@@ -658,48 +667,51 @@ light:
       - id: light_full
         from: 31
         to: 31
+      - id: light_full
+        from: 0
+        to: 0
   - id: light_us_rl_2_4_left
     name: Light - Relay 2 of 4 (left)
     <<: *light_partition_relays
     segments:
       - id: light_full
-        from: 24
-        to: 24
+        from: 21
+        to: 22
   - id: light_us_rl_2_4_right
     name: Light - Relay 2 of 4 (right)
     <<: *light_partition_relays
     segments:
       - id: light_full
-        from: 2
+        from: 1
         to: 2
   - id: light_us_rl_3_4_left
     name: Light - Relay 3 of 4 (left)
     <<: *light_partition_relays
     segments:
       - id: light_full
-        from: 21
-        to: 21
+        from: 17
+        to: 18
   - id: light_us_rl_3_4_right
     name: Light - Relay 3 of 4 (right)
     <<: *light_partition_relays
     segments:
       - id: light_full
-        from: 4
-        to: 4
+        from: 5
+        to: 6
   - id: light_us_rl_4_4_left
     name: Light - Relay 4 of 4 (left)
     <<: *light_partition_relays
     segments:
       - id: light_full
-        from: 19
-        to: 19
+        from: 15
+        to: 16
   - id: light_us_rl_4_4_right
     name: Light - Relay 4 of 4 (right)
     <<: *light_partition_relays
     segments:
       - id: light_full
         from: 7
-        to: 7
+        to: 8
 
 script:
   - id: !extend boot_initialize
@@ -795,12 +807,12 @@ script:
             case 1:
               if (light_index >= id(gb_lights_1).size()) {
                 ESP_LOGE("core_hw_leds", "Invalid set with %s light for Relay %" PRIu8,
-                                          light_mode_group_1.c_str(), light_index);
+                                          light_mode_group_1.c_str(), light_index+1);
                 return;
               }
               if (state and !id(gb_lights_1)[light_index]->current_values.is_on()) {
                 ESP_LOGI("core_hw_leds", "Turn-on %s light for Relay %" PRIu8,
-                                          light_mode_group_1.c_str(), light_index);
+                                          light_mode_group_1.c_str(), light_index+1);
                 auto call = id(gb_lights_1)[light_index]->turn_on();
                 if (LIGHT_TRANSITION_TURN_ON > 0)
                   call.set_transition_length(LIGHT_TRANSITION_TURN_ON);  // in ms
@@ -809,7 +821,7 @@ script:
                 call.perform();
               } else if (!state and id(gb_lights_1)[light_index]->current_values.is_on()) {
                 ESP_LOGI("core_hw_leds", "Turn-off %s light for Relay %" PRIu8,
-                                          light_mode_group_1.c_str(), light_index);
+                                          light_mode_group_1.c_str(), light_index+1);
                 auto call = id(gb_lights_1)[light_index]->turn_off();
                 if (LIGHT_TRANSITION_TURN_OFF > 0)
                   call.set_transition_length(LIGHT_TRANSITION_TURN_OFF);  // in ms
@@ -819,12 +831,12 @@ script:
             case 2:
               if (light_index >= id(gb_lights_2).size()) {
                 ESP_LOGE("core_hw_leds", "Invalid set with %s light for Relay %" PRIu8,
-                                          light_mode_group_2.c_str(), light_index);
+                                          light_mode_group_2.c_str(), light_index+1);
                 return;
               }
               if (state and !id(gb_lights_2)[light_index]->current_values.is_on()) {
                 ESP_LOGI("core_hw_leds", "Turn-on %s light for Relay %" PRIu8,
-                                          light_mode_group_2.c_str(), light_index);
+                                          light_mode_group_2.c_str(), light_index+1);
                 auto call = id(gb_lights_2)[light_index]->turn_on();
                 if (LIGHT_TRANSITION_TURN_ON > 0)
                   call.set_transition_length(LIGHT_TRANSITION_TURN_ON);  // in ms
@@ -833,7 +845,7 @@ script:
                 call.perform();
               } else if (!state and id(gb_lights_2)[light_index]->current_values.is_on()) {
                 ESP_LOGI("core_hw_leds", "Turn-off %s light for Relay %" PRIu8,
-                                          light_mode_group_2.c_str(), light_index);
+                                          light_mode_group_2.c_str(), light_index+1);
                 auto call = id(gb_lights_2)[light_index]->turn_off();
                 if (LIGHT_TRANSITION_TURN_OFF > 0)
                   call.set_transition_length(LIGHT_TRANSITION_TURN_OFF);  // in ms

ESPHome/TX-Ultimate-Easy-ESPHome_core_hw_relays.yaml

@@ -11,54 +11,11 @@
 ##### - For normal system use, modifications to this file are NOT required.                    #####
 ####################################################################################################
 ---
-binary_sensor:
-  - id: !extend bs_button_1
-    on_click:
-      then:
-        - if:
-            condition:
-              - lambda: return sl_button_1_action->active_index().has_value();
-              - lambda: return sl_button_1_action->active_index().value() == 1;
-              - and: &button_click_no_other_click
-                  - lambda: return not bs_multi_touch->state;
-                  - lambda: return not bs_swipe_left->state;
-                  - lambda: return not bs_swipe_down->state;
-                  - lambda: return not bs_swipe_right->state;
-            then:
-              - switch.toggle: sw_relay_1
-
-  - id: !extend bs_button_2
-    on_click:
-      then:
-        - if:
-            condition:
-              - lambda: return sl_button_2_action->active_index().has_value();
-              - lambda: return sl_button_2_action->active_index().value() == 1;
-              - and: *button_click_no_other_click
-            then:
-              - switch.toggle: sw_relay_2
-
-  - id: !extend bs_button_3
-    on_click:
-      then:
-        - if:
-            condition:
-              - lambda: return sl_button_3_action->active_index().has_value();
-              - lambda: return sl_button_3_action->active_index().value() == 1;
-              - and: *button_click_no_other_click
-            then:
-              - switch.toggle: sw_relay_3
-
-  - id: !extend bs_button_4
-    on_click:
-      then:
-        - if:
-            condition:
-              - lambda: return sl_button_4_action->active_index().has_value();
-              - lambda: return sl_button_4_action->active_index().value() == 1;
-              - and: *button_click_no_other_click
-            then:
-              - switch.toggle: sw_relay_4
+substitutions:
+  RELAY_MODE_TEXT_SWITCH: "Switch"
+  RELAY_MODE_TEXT_LIGHT: "Light"
+  RELAY_MODE_TEXT_NOT_USED: "Not in use"
+  RELAY_RESTORE_MODE: RESTORE_DEFAULT_OFF
 
 globals:
   - id: boot_initialization_relays
@@ -68,24 +25,83 @@ globals:
 
 light:
   # These lights are used for the physical relays to be shown as lights
-  - &light_binary_base
-    id: light_output_1
+  - id: light_output_1
     name: Light output 1
     output: output_relay_1
     platform: binary
     internal: true
+    restore_mode: ${RELAY_RESTORE_MODE}
+    on_turn_on:
+      then:
+        - if:
+            condition:
+              - switch.is_off: sw_relay_1
+            then:
+              - switch.turn_on: sw_relay_1
+    on_turn_off:
+      then:
+        - if:
+            condition:
+              - switch.is_on: sw_relay_1
+            then:
+              - switch.turn_off: sw_relay_1
   - id: light_output_2
     name: Light output 2
     output: output_relay_2
-    <<: *light_binary_base
+    platform: binary
+    internal: true
+    on_turn_on:
+      then:
+        - if:
+            condition:
+              - switch.is_off: sw_relay_2
+            then:
+              - switch.turn_on: sw_relay_2
+    on_turn_off:
+      then:
+        - if:
+            condition:
+              - switch.is_on: sw_relay_2
+            then:
+              - switch.turn_off: sw_relay_2
   - id: light_output_3
     name: Light output 3
     output: output_relay_3
-    <<: *light_binary_base
+    platform: binary
+    internal: true
+    on_turn_on:
+      then:
+        - if:
+            condition:
+              - switch.is_off: sw_relay_3
+            then:
+              - switch.turn_on: sw_relay_3
+    on_turn_off:
+      then:
+        - if:
+            condition:
+              - switch.is_on: sw_relay_3
+            then:
+              - switch.turn_off: sw_relay_3
   - id: light_output_4
     name: Light output 4
     output: output_relay_4
-    <<: *light_binary_base
+    platform: binary
+    internal: true
+    on_turn_on:
+      then:
+        - if:
+            condition:
+              - switch.is_off: sw_relay_4
+            then:
+              - switch.turn_on: sw_relay_4
+    on_turn_off:
+      then:
+        - if:
+            condition:
+              - switch.is_on: sw_relay_4
+            then:
+              - switch.turn_off: sw_relay_4
 
 output:
   - id: output_relay_1
@@ -159,6 +175,74 @@ script:
           }
           id(boot_initialization_relays) = true;
 
+  - id: !extend button_click_event
+    then:
+      - lambda: |-
+          // Handle only single clicks
+          if (click_count != 1)
+            return;
+
+          // Ignore if other touch events are active
+          if (bs_multi_touch->state ||
+              bs_swipe_left->state ||
+              bs_swipe_down->state ||
+              bs_swipe_right->state) {
+            return;
+          }
+
+          // Toggle relay if corresponding button action is enabled
+          ESP_LOGVV("core_hw_relays", "Toggle relays: (${BUTTON_ACTION_NONE_TEXT})");
+          ESP_LOGVV("core_hw_relays", "  Relay 1: %s (%s)",
+                    YESNO(sl_button_1_action->state != "${BUTTON_ACTION_NONE_TEXT}"),
+                    sl_button_1_action->state.c_str());
+          ESP_LOGVV("core_hw_relays", "  Relay 2: %s (%s)",
+                    YESNO(sl_button_2_action->state != "${BUTTON_ACTION_NONE_TEXT}"),
+                    sl_button_2_action->state.c_str());
+          ESP_LOGVV("core_hw_relays", "  Relay 3: %s (%s)",
+                    YESNO(sl_button_3_action->state != "${BUTTON_ACTION_NONE_TEXT}"),
+                    sl_button_3_action->state.c_str());
+          ESP_LOGVV("core_hw_relays", "  Relay 4: %s (%s)",
+                    YESNO(sl_button_4_action->state != "${BUTTON_ACTION_NONE_TEXT}"),
+                    sl_button_4_action->state.c_str());
+          switch (button) {
+            case ${BUTTON_1_ID}:
+              if (sl_button_1_action->state != "${BUTTON_ACTION_NONE_TEXT}") {
+                ESP_LOGV("core_hw_relays", "Toggle relay 1: (%s)", sl_button_1_action->state.c_str());
+                sw_relay_1->toggle();
+              } else {
+                ESP_LOGV("core_hw_relays", "Ignoring toggle for relay 1: action is '%s'",
+                          sl_button_1_action->state.c_str());
+              }
+              break;
+            case ${BUTTON_2_ID}:
+              if (sl_button_2_action->state != "${BUTTON_ACTION_NONE_TEXT}") {
+                ESP_LOGV("core_hw_relays", "Toggle relay 2: (%s)", sl_button_2_action->state.c_str());
+                sw_relay_2->toggle();
+              } else {
+                ESP_LOGV("core_hw_relays", "Ignoring toggle for relay 2: action is '%s'",
+                          sl_button_2_action->state.c_str());
+              }
+              break;
+            case ${BUTTON_3_ID}:
+              if (sl_button_3_action->state != "${BUTTON_ACTION_NONE_TEXT}") {
+                ESP_LOGV("core_hw_relays", "Toggle relay 3: (%s)", sl_button_3_action->state.c_str());
+                sw_relay_3->toggle();
+              } else {
+                ESP_LOGV("core_hw_relays", "Ignoring toggle for relay 3: action is '%s'",
+                          sl_button_3_action->state.c_str());
+              }
+              break;
+            case ${BUTTON_4_ID}:
+              if (sl_button_4_action->state != "${BUTTON_ACTION_NONE_TEXT}") {
+                ESP_LOGV("core_hw_relays", "Toggle relay 4: (%s)", sl_button_4_action->state.c_str());
+                sw_relay_4->toggle();
+              } else {
+                ESP_LOGV("core_hw_relays", "Ignoring toggle for relay 4: action is '%s'",
+                          sl_button_4_action->state.c_str());
+              }
+              break;
+          }
+
   - id: show_relay_status
     mode: restart
     then:
@@ -236,12 +320,13 @@ script:
 select:
   - &relay_select_mode_base
     id: sl_relay_1_mode
-    name: Relay 1 mode
+    name: Relay 1 display mode
     platform: template
     options:
-      - "Relay"
-      - "Light"
-      - "Not in use"
+      - "${RELAY_MODE_TEXT_SWITCH}"
+      - "${RELAY_MODE_TEXT_LIGHT}"
+      - "${RELAY_MODE_TEXT_NOT_USED}"
+    initial_option: "${RELAY_MODE_TEXT_SWITCH}"
     optimistic: true
     restore_value: true
     internal: true
@@ -250,44 +335,107 @@ select:
     icon: mdi:dip-switch
 
   - id: sl_relay_2_mode
-    name: Relay 2 mode
+    name: Relay 2 display mode
     <<: *relay_select_mode_base
 
   - id: sl_relay_3_mode
-    name: Relay 3 mode
+    name: Relay 3 display mode
     <<: *relay_select_mode_base
 
   - id: sl_relay_4_mode
-    name: Relay 4 mode
+    name: Relay 4 display mode
     <<: *relay_select_mode_base
 
 switch:
-  - &relay_switch_base
-    id: sw_relay_1
+  - id: sw_relay_1
     name: Relay 1
-    platform: output
     output: output_relay_1
-    restore_mode: RESTORE_DEFAULT_OFF
+    platform: output
+    restore_mode: ${RELAY_RESTORE_MODE}
     internal: true
     on_turn_on:
       then:
         - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_off: light_output_1
+            then:
+              light.turn_on: light_output_1
     on_turn_off:
       then:
         - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_on: light_output_1
+            then:
+              - light.turn_off: light_output_1
 
   - id: sw_relay_2
     name: Relay 2
     output: output_relay_2
-    <<: *relay_switch_base
+    platform: output
+    restore_mode: ${RELAY_RESTORE_MODE}
+    internal: true
+    on_turn_on:
+      then:
+        - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_off: light_output_2
+            then:
+              light.turn_on: light_output_2
+    on_turn_off:
+      then:
+        - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_on: light_output_2
+            then:
+              - light.turn_off: light_output_2
 
   - id: sw_relay_3
     name: Relay 3
     output: output_relay_3
-    <<: *relay_switch_base
+    platform: output
+    restore_mode: ${RELAY_RESTORE_MODE}
+    internal: true
+    on_turn_on:
+      then:
+        - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_off: light_output_3
+            then:
+              - light.turn_on: light_output_3
+    on_turn_off:
+      then:
+        - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_on: light_output_3
+            then:
+              - light.turn_off: light_output_3
 
   - id: sw_relay_4
     name: Relay 4
     output: output_relay_4
-    <<: *relay_switch_base
+    platform: output
+    restore_mode: ${RELAY_RESTORE_MODE}
+    internal: true
+    on_turn_on:
+      then:
+        - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_off: light_output_4
+            then:
+              - light.turn_on: light_output_4
+    on_turn_off:
+      then:
+        - script.execute: show_relay_status
+        - if:
+            condition:
+              - light.is_on: light_output_4
+            then:
+              - light.turn_off: light_output_4
 ...

ESPHome/TX-Ultimate-Easy-ESPHome_core_hw_speaker.yaml

@@ -19,11 +19,11 @@ i2s_audio:
 media_player:
   - id: mp_speaker
     name: Speaker
+    internal: false
     platform: i2s_audio
     i2s_dout_pin: GPIO15
     i2s_audio_id: if_i2s_audio
-    i2s_comm_fmt: lsb
+    i2s_comm_fmt: msb  # Experimental - It was 'lsb' until v2024.12.12
     dac_type: external
     mode: mono
-    internal: false
 ...

ESPHome/TX-Ultimate-Easy-ESPHome_core_hw_touch.yaml

@@ -11,64 +11,205 @@
 ##### - For normal system use, modifications to this file are NOT required.                    #####
 ####################################################################################################
 ---
+substitutions:
+  TOUCH_POSITION_MAX_VALUE: '10'  # Maximum touch position value returned by the touch pad via uart
+
 binary_sensor:
+  - &bs_button_event_template
+    id: bs_button_event_template
+    icon: mdi:gesture-tap-box
+    internal: true
+    disabled_by_default: true
+    platform: template
+
+  - id: bs_button_1_click_event
+    name: Button 1 - Click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_1_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_2_click_event
+    name: Button 2 - Click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_2_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_3_click_event
+    name: Button 3 - Click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_3_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_4_click_event
+    name: Button 4 - Click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_4_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+
+  - id: bs_button_1_double_click_event
+    name: Button 1 - Double-click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_1_double_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_2_double_click_event
+    name: Button 2 - Double-click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_2_double_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_3_double_click_event
+    name: Button 3 - Double-click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_3_double_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_4_double_click_event
+    name: Button 4 - Double-click event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_4_double_click_event
+            state: OFF  # yamllint disable-line rule:truthy
+
+  - id: bs_button_1_long_press_event
+    name: Button 1 - Long-press event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_1_long_press_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_2_long_press_event
+    name: Button 2 - Long-press event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_2_long_press_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_3_long_press_event
+    name: Button 3 - Long-press event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_3_long_press_event
+            state: OFF  # yamllint disable-line rule:truthy
+  - id: bs_button_4_long_press_event
+    name: Button 4 - Long-press event
+    internal: false
+    <<: *bs_button_event_template
+    on_press:
+      then:
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_button_4_long_press_event
+            state: OFF  # yamllint disable-line rule:truthy
+
   - id: bs_multi_touch
-    name: Multi-touch
+    name: Multi-touch event
     icon: mdi:gesture-two-tap
     internal: false
-    platform: template
-    on_click:
+    <<: *bs_button_event_template
+    on_press:
       then:
-        - lambda: send_event_to_ha->execute("multi_touch", "multi_touch");
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_multi_touch
+            state: OFF  # yamllint disable-line rule:truthy
 
   - id: bs_swipe_left
-    name: Swipe left
+    name: Swipe left event
     icon: mdi:gesture-swipe-left
-    internal: true
-    platform: template
-    on_click:
+    <<: *bs_button_event_template
+    on_press:
       then:
-        - lambda: send_event_to_ha->execute("swipe", "left");
-
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_swipe_left
+            state: OFF  # yamllint disable-line rule:truthy
   - id: bs_swipe_right
-    name: Swipe right
+    name: Swipe right event
     icon: mdi:gesture-swipe-right
-    internal: true
-    platform: template
-    on_click:
+    <<: *bs_button_event_template
+    on_press:
       then:
-        - lambda: send_event_to_ha->execute("swipe", "right");
-
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_swipe_right
+            state: OFF  # yamllint disable-line rule:truthy
   - id: bs_swipe_up
-    name: Swipe up
+    name: Swipe up event
     icon: mdi:gesture-swipe-up
-    internal: true
-    platform: template
-    on_click:
+    <<: *bs_button_event_template
+    on_press:
       then:
-        - lambda: send_event_to_ha->execute("swipe", "up");
-
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_swipe_up
+            state: OFF  # yamllint disable-line rule:truthy
   - id: bs_swipe_down
-    name: Swipe down
+    name: Swipe down event
     icon: mdi:gesture-swipe-down
-    internal: true
-    platform: template
-    on_click:
+    <<: *bs_button_event_template
+    on_press:
       then:
-        - lambda: send_event_to_ha->execute("swipe", "down");
+        - delay: !lambda return nr_touch_duration->state;
+        - binary_sensor.template.publish:
+            id: bs_swipe_down
+            state: OFF  # yamllint disable-line rule:truthy
 
 external_components:
   - source:
       type: git
       url: https://github.com/edwardtfn/TX-Ultimate-Easy
-      ref: ${version}
+      ref: v${version}
     refresh: 1h
     components:
       - tx_ultimate_easy
 
 number:
   - id: nr_touch_duration
-    name: Touch duration
+    name: Touch event duration
     icon: mdi:timer-cog-outline
     unit_of_measurement: ms
     # mode: box
@@ -88,6 +229,12 @@ script:
       - script.execute: boot_initialize_touch
 
   - id: boot_initialize_touch
+    mode: restart
+    then:
+      - script.execute: boot_initialize_touch_format
+      - script.execute: boot_initialize_touch_gang
+
+  - id: boot_initialize_touch_format
     mode: restart
     then:
       - wait_until:
@@ -106,25 +253,56 @@ script:
           bs_swipe_up->publish_state(false);
           bs_swipe_up->set_internal(!is_model_us);
 
+  - id: boot_initialize_touch_gang
+    mode: restart
+    then:
+      - wait_until:
+          condition:
+            - lambda: return sl_tx_model_gang->active_index().has_value();
+      - lambda: |-
+          const uint8_t num_gangs = (sl_tx_model_gang->active_index().has_value()) ?
+                                    (sl_tx_model_gang->active_index().value() + 1) : 0;
+          tx_ultimate->set_gang_count(num_gangs);
+          bs_button_1_click_event->publish_state(false);
+          bs_button_2_click_event->publish_state(false);
+          bs_button_3_click_event->publish_state(false);
+          bs_button_4_click_event->publish_state(false);
+          bs_button_1_double_click_event->publish_state(false);
+          bs_button_2_double_click_event->publish_state(false);
+          bs_button_3_double_click_event->publish_state(false);
+          bs_button_4_double_click_event->publish_state(false);
+          bs_button_1_long_press_event->publish_state(false);
+          bs_button_2_long_press_event->publish_state(false);
+          bs_button_3_long_press_event->publish_state(false);
+          bs_button_4_long_press_event->publish_state(false);
+          bs_button_1_click_event->set_internal(num_gangs < 1);
+          bs_button_2_click_event->set_internal(num_gangs < 2);
+          bs_button_3_click_event->set_internal(num_gangs < 3);
+          bs_button_4_click_event->set_internal(num_gangs < 4);
+          bs_button_1_double_click_event->set_internal(num_gangs < 1);
+          bs_button_2_double_click_event->set_internal(num_gangs < 2);
+          bs_button_3_double_click_event->set_internal(num_gangs < 3);
+          bs_button_4_double_click_event->set_internal(num_gangs < 4);
+          bs_button_1_long_press_event->set_internal(num_gangs < 1);
+          bs_button_2_long_press_event->set_internal(num_gangs < 2);
+          bs_button_3_long_press_event->set_internal(num_gangs < 3);
+          bs_button_4_long_press_event->set_internal(num_gangs < 4);
+
   - id: touch_on_multi_touch_release
     mode: restart
     then:
       # Extended by:
       #   - HW Buttons
       #   - HW Vibration
-      - script.execute: touch_on_multi_touch_release_touch
-
-  - id: touch_on_multi_touch_release_touch
-    mode: restart
-    then:
-      - lambda: bs_multi_touch->publish_state(true);
-      - delay: !lambda return nr_touch_duration->state;
-      - lambda: bs_multi_touch->publish_state(false);
+      - binary_sensor.template.publish:
+          id: bs_multi_touch
+          state: OFF  # yamllint disable-line rule:truthy
 
   - id: touch_on_press
     mode: restart
     parameters:
-      touch_x: uint8_t
+      button: uint8_t
+      position: uint8_t
     then:
     # Extended by:
     #   - HW Buttons
@@ -133,60 +311,33 @@ script:
   - id: touch_on_release
     mode: restart
     then:
-      # Extended by:
-      #   - HW Buttons
-      #   - HW Vibration
-      - script.execute: touch_swipe_turn_off_binary_sensor
+    # Extended by:
+    #   - HW Buttons
+    #   - HW Vibration
 
   - id: touch_swipe_left
     mode: restart
     then:
       # Extended by:
       #   - HW Buttons
-      - script.execute: touch_swipe_left_touch
-
-  - id: touch_swipe_left_touch
-    mode: restart
-    then:
       - binary_sensor.template.publish:
           id: bs_swipe_left
           state: ON  # yamllint disable-line rule:truthy
-      - delay: !lambda return nr_touch_duration->state;
-      - script.execute: touch_swipe_turn_off_binary_sensor
+      - binary_sensor.template.publish:
+          id: bs_swipe_down
+          state: ON  # yamllint disable-line rule:truthy
 
   - id: touch_swipe_right
     mode: restart
     then:
       # Extended by:
       #   - HW Buttons
-      - script.execute: touch_swipe_right_touch
-
-  - id: touch_swipe_right_touch
-    mode: restart
-    then:
       - binary_sensor.template.publish:
           id: bs_swipe_right
           state: ON  # yamllint disable-line rule:truthy
-      - delay: !lambda return nr_touch_duration->state;
-      - script.execute: touch_swipe_turn_off_binary_sensor
-
-  - id: touch_swipe_turn_off_binary_sensor
-    mode: restart
-    then:
-      - if:
-          condition:
-            binary_sensor.is_on: bs_swipe_left
-          then:
-            - binary_sensor.template.publish:
-                id: bs_swipe_left
-                state: OFF  # yamllint disable-line rule:truthy
-      - if:
-          condition:
-            binary_sensor.is_on: bs_swipe_right
-          then:
-            - binary_sensor.template.publish:
-                id: bs_swipe_right
-                state: OFF  # yamllint disable-line rule:truthy
+      - binary_sensor.template.publish:
+          id: bs_swipe_up
+          state: ON  # yamllint disable-line rule:truthy
 
 switch:
   - id: sw_touch_panel_power
@@ -203,27 +354,78 @@ tx_ultimate_easy:
   id: tx_ultimate
   uart: uart_touch
 
+  on_long_touch_release:
+    - lambda: |-
+        const uint8_t touch_position = static_cast<uint8_t>(touch.x);
+        if (touch_position > ${TOUCH_POSITION_MAX_VALUE}) {  // Check for valid range
+          ESP_LOGE("tx_ultimate_easy", "Invalid long-touch position: %" PRIu8, touch_position);
+        } else {
+          ESP_LOGI("tx_ultimate_easy", "Long-touch released at position %" PRIu8, touch_position);
+        }
+
   on_multi_touch_release:
+    - homeassistant.event:
+        event: esphome.tx_ultimate_easy
+        data:
+          device_name: !lambda return tx_device_name->state.c_str();
+          firmware: ${version}
+          domain: touch
+          type: multi_touch
+          action: release
+          position: !lambda return touch.x;
     - lambda: ESP_LOGI("tx_ultimate_easy", "Multi-touch released");
     - script.execute: touch_on_multi_touch_release
 
   on_press:
     - lambda: |-
-        ESP_LOGI("tx_ultimate_easy", "Pressed at position %" PRIu8, static_cast<uint8_t>(touch.x));
-    - script.execute:
-        id: touch_on_press
-        touch_x: !lambda return static_cast<uint8_t>(touch.x);
+        const uint8_t position = static_cast<uint8_t>(touch.x);
+        if (position > ${TOUCH_POSITION_MAX_VALUE}) {  // Check for valid range
+          ESP_LOGE("tx_ultimate_easy", "Invalid touch position: %" PRIu8, position);
+        } else {
+          ESP_LOGI("tx_ultimate_easy", "Pressed at position %" PRIu8, position);
+          touch_on_press->execute(static_cast<uint8_t>(touch.button), position);
+        }
 
   on_release:
     - lambda: ESP_LOGI("tx_ultimate_easy", "Released");
     - script.execute: touch_on_release
 
   on_swipe_left:
-    - lambda: ESP_LOGI("tx_ultimate_easy", "Swipe left");
+    - homeassistant.event:
+        event: esphome.tx_ultimate_easy
+        data:
+          device_name: !lambda return tx_device_name->state.c_str();
+          firmware: ${version}
+          domain: touch
+          type: swipe
+          action: !lambda |-
+            return sl_tx_model_format->state == "${TX_MODEL_FORMAT_US_TEXT}" ? "left" : "down";
+          swipe-direction: !lambda |-
+            return sl_tx_model_format->state == "${TX_MODEL_FORMAT_US_TEXT}" ? "left" : "down";
+          position: !lambda return touch.x;
+    - lambda: |-
+        ESP_LOGI("tx_ultimate_easy", "Swipe %s", sl_tx_model_format->state == "${TX_MODEL_FORMAT_US_TEXT}"
+                                                  ? "left"
+                                                  : "down");
     - script.execute: touch_swipe_left
 
   on_swipe_right:
-    - lambda: ESP_LOGI("tx_ultimate_easy", "Swipe right");
+    - homeassistant.event:
+        event: esphome.tx_ultimate_easy
+        data:
+          device_name: !lambda return tx_device_name->state.c_str();
+          firmware: ${version}
+          domain: touch
+          type: swipe
+          action: !lambda |-
+            return sl_tx_model_format->state == "${TX_MODEL_FORMAT_US_TEXT}" ? "right" : "up";
+          swipe-direction: !lambda |-
+            return sl_tx_model_format->state == "${TX_MODEL_FORMAT_US_TEXT}" ? "right" : "up";
+          position: !lambda return touch.x;
+    - lambda: |-
+        ESP_LOGI("tx_ultimate_easy", "Swipe %s", sl_tx_model_format->state == "${TX_MODEL_FORMAT_US_TEXT}"
+                                                  ? "right"
+                                                  : "up");
     - script.execute: touch_swipe_right
 
   on_touch_event:
@@ -233,8 +435,8 @@ tx_ultimate_easy:
         ESP_LOGD("tx_ultimate_easy", "  Position: %i", touch.x);
 
 uart:
-  id: uart_touch
-  tx_pin: GPIO19
-  rx_pin: GPIO22
-  baud_rate: 115200
+  - id: uart_touch
+    tx_pin: GPIO19
+    rx_pin: GPIO22
+    baud_rate: 115200
 ...

README.md

@@ -1,19 +1,20 @@
 # TX Ultimate Easy
 
-<!-- markdownlint-disable MD033 -->
-<a href="https://github.com/edwardtfn/TX-Ultimate-Easy/commits/main" target="_blank">![GitHub Activity][commits-shield]</a>
-<a href="LICENSE" target="_blank">![License][license-shield]</a>
-<a href="https://github.com/edwardtfn/TX-Ultimate-Easy/commits/main" target="_blank">![GitHub Last Commit][last-commit-shield]</a>
-<a href="https://esphome.io/" target="_blank">![ESPHome][esphome-shield]</a>
-<a href="https://discord.gg/Db6WJWzWuf" target="_blank">![Discord][discord-shield]</a>
-<a href="https://www.buymeacoffee.com/edwardfirmo" target="_blank">![Buy me an ice-cream][buymeacoffee-shield]</a>
-<!-- markdownlint-enable MD033 -->
+[![Version][version-shield]](https://github.com/edwardtfn/TX-Ultimate-Easy/tags)
+[![GitHub Activity][commits-shield]](https://github.com/edwardtfn/TX-Ultimate-Easy/commits/main)
+[![License][license-shield]](LICENSE)
+[![GitHub Last Commit][last-commit-shield]](https://github.com/edwardtfn/TX-Ultimate-Easy/commits/main)
+[![ESPHome][esphome-shield]](https://esphome.io/)
+[![Discord][discord-shield]](https://discord.gg/Db6WJWzWuf)
+[![Buy me an ice-cream][buymeacoffee-shield]](https://www.buymeacoffee.com/edwardfirmo)
 
 <!-- markdownlint-disable MD013 -->
 | &nbsp;![TX Ultimate Easy Logo](Assets/Logo.webp) | TX Ultimate Easy provides custom ESPHome firmware for Sonoff TX Ultimate devices. Our project focuses on user-friendly configuration through the Home Assistant UI, eliminating the need for manual YAML editing. Whether you're new to home automation or an experienced user, TX Ultimate Easy makes it simple to manage your device. |
 | --- | :-- |
 <!-- markdownlint-enable MD013 -->
 
+[version-shield]: https://img.shields.io/github/v/tag/edwardtfn/TX-Ultimate-Easy?label=version
+[version]: https://github.com/edwardtfn/TX-Ultimate-Easy/tags
 [commits-shield]: https://img.shields.io/github/commit-activity/y/edwardtfn/TX-Ultimate-Easy
 [commits]: https://github.com/edwardtfn/TX-Ultimate-Easy/commits/main
 [license-shield]: https://img.shields.io/github/license/edwardtfn/TX-Ultimate-Easy
@@ -28,14 +29,39 @@
 
 ## Integration with Home Assistant
 
-TX Ultimate Easy exposes your device's components (sensors, touch panel, relays, etc.) to Home Assistant, allowing you to:
+TX Ultimate Easy exposes your device's components (sensors, touch panel, relays, etc.) to Home Assistant,
+allowing you to:
 
 - Monitor sensor states and values
 - Control device components through the Home Assistant UI
 - Use device triggers and states in your Home Assistant automations and scripts
 - Configure device behavior through Home Assistant's service calls
 
-All automation capabilities are handled through Home Assistant's native automation system - this project focuses on providing reliable device integration rather than implementing its own automation tools.
+All automation capabilities are handled through Home Assistant's
+native automation system - this project focuses on providing reliable
+device integration rather than implementing its own automation tools.
+
+### Event-Based Automation
+
+TX Ultimate Easy uses Home Assistant's native Events system for reliable automation triggers.
+While sensors show the current state (e.g., button pressed/not pressed),
+events capture-specific actions like clicks, swipes, and long presses.
+
+For more details, please refer to our **[Events docs](docs/events.md)**.
+
+### Device Configuration
+#### Relay Modes
+- **Light Mode**: Exposes the relay as a light entity with brightness controls (if supported)
+- **Switch Mode**: Exposes the relay as a simple on/off switch entity
+
+#### Button Actions
+- **None**: Allows using button events for custom automations
+  Example: Trigger scenes or complex automations through Home Assistant
+- **Relay Toggle**: Direct control of the associated relay
+  Example: Toggle relay state with each press, independent of Home Assistant
+
+#### Automation
+All device behaviors can be customized through Home Assistant automations without relying on local device triggers.
 
 ## Key Features
 
@@ -103,6 +129,7 @@ We welcome contributions from the community! Here's how you can help:
 4. Submit a pull request targeting the `main` branch
 
 Please ensure your code follows our standards:
+
 - Passes all lint checks (YAML, C++, Markdown)
 - Includes appropriate documentation
 - Follows existing code style
@@ -111,11 +138,15 @@ Please ensure your code follows our standards:
 
 Need help? Here are your options:
 
-- **Bug Reports & Feature Requests**: Use [GitHub Issues](https://github.com/edwardtfn/TX-Ultimate-Easy/issues) for all bug reports and feature requests
-- **Community Chat**: Join our [Discord Server](https://discord.gg/Db6WJWzWuf) for discussions and community interaction
+- **Bug Reports & Feature Requests**: Use [GitHub Issues](https://github.com/edwardtfn/TX-Ultimate-Easy/issues)
+    for all bug reports and feature requests
+- **Community Chat**: Join our [Discord Server](https://discord.gg/Db6WJWzWuf)
+    for discussions and community interaction
 - **Support the Project**: Consider supporting through Buy Me a Coffee
 
-Note: For proper tracking and resolution, all bug reports and feature requests must be submitted through GitHub Issues, not Discord. The Issues page can be found at: [Issues · edwardtfn/TX-Ultimate-Easy](https://github.com/edwardtfn/TX-Ultimate-Easy/issues)
+Note: For proper tracking and resolution:
+- All bug reports and feature requests must be submitted through GitHub Issues, not Discord
+- Submit issues here: [Issues · edwardtfn/TX-Ultimate-Easy](https://github.com/edwardtfn/TX-Ultimate-Easy/issues)
 
 [![Buy Me a Coffee](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/edwardfirmo)
 

TX-Ultimate-Easy-ESPHome.yaml

@@ -16,8 +16,8 @@ wifi:
 packages:
   remote_package:
     url: https://github.com/edwardtfn/TX-Ultimate-Easy
-    ref: dev
-    refresh: 30s
+    ref: latest  # Or you can specify a version, like `ref: v2024.12.6`
+    refresh: 5min
     files:
       - ESPHome/TX-Ultimate-Easy-ESPHome_core.yaml
       # - ESPHome/TX-Ultimate-Easy-ESPHome_addon_ble_proxy.yaml  # Adds experimental BLE proxy support (limited)

components/tx_ultimate_easy/__init__.py

@@ -13,6 +13,7 @@ DEPENDENCIES = ['uart']
 CONF_TX_ULTIMATE_EASY = "tx_ultimate_easy"
 
 CONF_UART = "uart"
+CONF_GANG_COUNT = "gang_count"
 
 CONF_ON_TOUCH_EVENT = "on_touch_event"
 CONF_ON_PRESS = "on_press"
@@ -33,6 +34,7 @@ CONFIG_SCHEMA = cv.Schema({
     cv.GenerateID(): cv.declare_id(TxUltimateTouch),
 
     cv.Required(CONF_UART): cv.use_id(uart),
+    cv.Optional(CONF_GANG_COUNT, default=1): cv.int_range(min=1, max=4),
 
     cv.Optional(CONF_ON_TOUCH_EVENT): automation.validate_automation(single=True),
     cv.Optional(CONF_ON_PRESS): automation.validate_automation(single=True),
@@ -49,6 +51,9 @@ async def register_tx_ultimate_easy(var, config):
     uart_component = await cg.get_variable(config[CONF_UART])
     cg.add(var.set_uart_component(uart_component))
 
+    if CONF_GANG_COUNT in config:
+        cg.add(var.set_gang_count(config[CONF_GANG_COUNT]))
+
     if CONF_ON_TOUCH_EVENT in config:
         await automation.build_automation(
             var.get_trigger_touch_event(),

components/tx_ultimate_easy/tx_ultimate_easy.cpp

@@ -48,6 +48,35 @@ namespace esphome {
 
         void TxUltimateEasy::dump_config() {
             ESP_LOGCONFIG(TAG, "TX Ultimate Easy");
+            ESP_LOGCONFIG(TAG, "  Gang count: %" PRIu8, this->gang_count_);
+        }
+
+        bool TxUltimateEasy::set_gang_count(const uint8_t gang_count) {
+            // Hardware supports maximum of 4 touch-sensitive buttons
+            if (gang_count < 1 or gang_count > 4)
+                return false;
+            this->gang_count_ = gang_count;
+            return true;
+        }
+
+        uint8_t TxUltimateEasy::get_button_from_position(const uint8_t position) {
+            // Validate position bounds
+            if (position > TOUCH_MAX_POSITION)
+                return 0;
+
+            // Special case for single gang (only one button exists)
+            if (this->gang_count_ == 1)
+                return 1;
+
+            // Calculate button number
+            const uint8_t width = (TOUCH_MAX_POSITION + 1) / this->gang_count_;  // Width of each button region
+            if (width < 1 or width > this->gang_count_)  // Invalid width - and prevents division by zero
+                return 0;
+            const uint8_t button = std::min(
+                static_cast<uint8_t>((position / width) + 1), // Convert position to button index
+                this->gang_count_ // Clamp to max gang count
+            );
+            return button;
         }
 
         void TxUltimateEasy::send_touch_(TouchPoint tp) {
@@ -103,7 +132,8 @@ namespace esphome {
                     state == TOUCH_STATE_SWIPE_LEFT ||
                     state == TOUCH_STATE_SWIPE_RIGHT ||
                     state == TOUCH_STATE_MULTI_TOUCH) &&
-                   (uart_received_bytes[6] >= 0 || state == TOUCH_STATE_MULTI_TOUCH);
+                    // Multi-touch events may have x < 0, all other events require valid x position
+                    (uart_received_bytes[6] >= 0 || state == TOUCH_STATE_MULTI_TOUCH);
         }
 
         int TxUltimateEasy::get_touch_position_x(const std::array<int, UART_RECEIVED_BYTES_SIZE> &uart_received_bytes) {
@@ -133,6 +163,8 @@ namespace esphome {
         TouchPoint TxUltimateEasy::get_touch_point(const std::array<int, UART_RECEIVED_BYTES_SIZE> &uart_received_bytes) {
             TouchPoint tp;
             tp.x = this->get_touch_position_x(uart_received_bytes);
+            if (tp.x >= 0)
+                tp.button = this->get_button_from_position(static_cast<uint8_t>(tp.x));
             tp.state = this->get_touch_state(uart_received_bytes);
             switch (tp.state) {
                 case TOUCH_STATE_RELEASE:

components/tx_ultimate_easy/tx_ultimate_easy.h

@@ -13,6 +13,9 @@
 
 namespace esphome {
     namespace tx_ultimate_easy {
+        // Touch Max Position
+        constexpr uint8_t TOUCH_MAX_POSITION = 10;
+
         // Touch State Constants
         constexpr uint8_t TOUCH_STATE_RELEASE = 0x01;
         constexpr uint8_t TOUCH_STATE_PRESS = 0x02;
@@ -32,6 +35,7 @@ namespace esphome {
         static const char *TAG = "tx_ultimate_easy";
 
         struct TouchPoint {
+            uint8_t button = 0;
             int8_t x = -1;
             int8_t state = -1;
             std::string state_str = "Unknown";
@@ -53,6 +57,10 @@ namespace esphome {
             void loop() override;
             void dump_config() override;
 
+            uint8_t get_gang_count() { return this->gang_count_; }
+            bool set_gang_count(const uint8_t gang_count);
+            uint8_t get_button_from_position(const uint8_t position);
+
         protected:
             void send_touch_(TouchPoint tp);
             void handle_touch(const std::array<int, UART_RECEIVED_BYTES_SIZE> &bytes);
@@ -70,6 +78,8 @@ namespace esphome {
             Trigger<TouchPoint> trigger_multi_touch_release_;
             Trigger<TouchPoint> trigger_long_touch_release_;
 
+            uint8_t gang_count_ = 1;
+
         }; // class TxUltimateEasy
 
     } // namespace tx_ultimate_easy

docs/events.md

@@ -0,0 +1,236 @@
+# Updating the Event Engine in TX Ultimate Easy
+
+## Overview of the Event System
+
+The TX Ultimate Easy firmware introduces a powerful
+and flexible event system designed to handle various types of interactions,
+such as touch gestures and device states.
+This system leverages Home Assistant's native event structure,
+ensuring seamless integration and enabling users to create advanced automations.
+
+### Event Structure
+
+All events emitted by the device are categorized under the `esphome.tx_ultimate_easy` event type in Home Assistant.
+The `data` field within the event payload provides details about the specific interaction.
+Below is a detailed description of the keys used:
+
+#### Example Event Payload
+
+```yaml
+  event:
+    event_type: esphome.tx_ultimate_easy
+    data:
+      device_id: "abc123"
+      device_name: "living_room_panel"
+      firmware: "2024.12.1"
+      domain: touch
+      type: button
+      action: click
+      button_id: 2
+      count: 1
+      position: 3
+```
+
+### Key Definitions
+
+#### `device_id`
+
+- **Description**: A unique identifier for the device emitting the event.
+- **Example**: `device_id: "abc123"`
+
+#### `device_name`
+
+- **Description**: A Home Assistant-compatible version of the hostname, with blanks and invalid characters replaced by `_`.
+- **Example**: `device_name: "living_room_panel"`
+
+#### `firmware`
+
+- **Description**: The firmware version of the device, formatted as `YYYY.M.S`.
+- **Example**: `firmware: "2024.12.1"`
+
+#### `domain`
+
+- **Description**: The high-level category of the event.
+- **Examples**:
+  - `boot`
+  - `touch`
+
+#### `type`
+
+- **Description**: Specifies the subcategory within the `domain`.
+- **Examples**:
+  - For `domain: boot`: `start`, `done`
+  - For `domain: touch`: `button`, `swipe`, `multi_touch`
+
+#### `action`
+
+- **Description**: Indicates the specific action or interaction.
+- **Examples**:
+  - For `type: button`: `click`, `double-click`, `long-press`, `multiple-click`
+  - For `type: swipe`: `left`, `right`, `up`, `down`
+
+#### `button_id`
+
+- **Description**: Identifies the button involved in the event (specific to `type: button`).
+- **Example**: `button_id: 2`
+
+#### `count`
+
+- **Description**: Indicates the number of clicks or interactions (used with `action: multiple-click`).
+- **Example**: `count: 3`
+
+#### `swipe-direction`
+
+- **Description**: Specifies the direction of a swipe (used with `type: swipe`).
+- **Examples**: `left`, `right`, `up`, `down`
+
+#### `position`
+
+- **Description**: An integer from 1 to 10 indicating the touch position (available on all touch events).
+- **Example**: `position: 3`
+
+### Supported Event Types
+
+#### Boot Events
+
+```yaml
+  event:
+    device_id: "abc123"
+    device_name: "living_room_panel"
+    firmware: "2024.12.1"
+    domain: boot
+    type: start
+    action: null
+```
+
+```yaml
+  event:
+    device_id: "abc123"
+    device_name: "living_room_panel"
+    firmware: "2024.12.1"
+    domain: boot
+    type: done
+    action: null
+```
+
+#### Touch Events
+
+##### Button Event
+
+```yaml
+  event:
+    device_id: "abc123"
+    device_name: "living_room_panel"
+    firmware: "2024.12.1"
+    domain: touch
+    type: button
+    action: click
+    button_id: 1
+    count: 1
+    position: 3
+```
+
+```yaml
+  event:
+    device_id: "abc123"
+    device_name: "living_room_panel"
+    firmware: "2024.12.1"
+    domain: touch
+    type: button
+    action: multiple-click
+    button_id: 1
+    count: 5
+    position: 3
+```
+
+##### Swipe Event
+
+```yaml
+  event:
+    device_id: "abc123"
+    device_name: "living_room_panel"
+    firmware: "2024.12.1"
+    domain: touch
+    type: swipe
+    action: left
+    swipe-direction: left
+    position: 3
+```
+
+```yaml
+  event:
+    device_id: "abc123"
+    device_name: "living_room_panel"
+    firmware: "2024.12.1"
+    domain: touch
+    type: swipe
+    action: up
+    swipe-direction: up
+    position: 3
+```
+
+##### Multi-Touch Event
+
+```yaml
+  event:
+    device_id: "abc123"
+    device_name: "living_room_panel"
+    firmware: "2024.12.1"
+    domain: touch
+    type: multi_touch
+    action: release
+    position: 3
+```
+
+### Integration in Automations
+
+#### Listening to Events
+
+To utilize these events in Home Assistant, follow these steps:
+
+1. Open the **Developer Tools** in Home Assistant.
+2. Navigate to the **Events** tab.
+3. Enter `esphome.tx_ultimate_easy` in the "Event to subscribe to" field.
+4. Click "Start listening."
+5. Trigger interactions on your TX Ultimate Easy device to see the events in real-time.
+
+#### Example Automation YAML
+
+##### Automation for a Single Click
+
+```yaml
+trigger:
+  - platform: event
+    event_type: esphome.tx_ultimate_easy
+    event_data:
+      domain: touch
+      type: button
+      action: click
+      button_id: 1
+      position: 3
+action:
+  - service: light.toggle
+    target:
+      entity_id: light.living_room
+```
+
+##### Automation for a Swipe Gesture
+
+```yaml
+trigger:
+  - platform: event
+    event_type: esphome.tx_ultimate_easy
+    event_data:
+      domain: touch
+      type: swipe
+      action: left
+      swipe-direction: left
+      position: 3
+action:
+  - service: script.activate_scene
+    target:
+      entity_id: scene.relax_mode
+```
+
+This event engine provides a robust and extensible framework for handling device interactions,
+allowing users to implement highly customized automations with ease.

versioning/README.md

@@ -1,35 +1,29 @@
 # Versioning
 
 ## Overview
-This project uses a time-based versioning scheme: `year.month.sequential_number`.
-This scheme makes it easy to identify when a version was released and provides a clear order for releases within a given month.
+This project uses a time-based versioning scheme: `year.month.sequential_number`.  
+The system automates version updates and tagging to ensure consistent, conflict-free management of releases.
 
 ### Examples
-- `2024.12.01` – First release of December 2024.
-- `2024.12.02` – Second release of December 2024.
-- `2025.01.01` – First release of January 2025.
+- `2024.1.1` – First release of January 2024.
+- `2024.12.2` – Second release of December 2024.
 
-## Files
-- **`VERSION`**: Contains the current version of the project as plain text.
-- **`bump_version.sh`**: A script to increment the version based on the current date and release sequence.
-- **`README.md`**: Documentation for the versioning process.
-
-## Versioning Rules
-1. The version format is `YYYY.MM.NN`, where:
-   - `YYYY` is the current year.
-   - `MM` is the current month (two digits).
-   - `NN` is the sequential release number within the month (starting at `01`).
-2. On each new merge to the `main` branch:
-   - If the month hasn’t changed, the sequential number (`NN`) is incremented.
-   - If the month has changed, the sequential number resets to `01`.
+## How It Works
+1. **Temporary Branch Creation**: A unique branch is created for each workflow run.
+2. **Version Update**: The workflow updates the `VERSION` and `VERSION_YAML` files using the current date and release sequence.
+3. **Commit with Marker**: Changes are committed with a `[skip-versioning]` marker to prevent triggering the workflow again.
+4. **Merge into Main**: The temporary branch is merged into `main`.
+5. **Branch Cleanup**: The temporary branch is deleted after merging.
 
 ## Usage
 
-### Automatically Managed
-The versioning process is fully integrated into the workflow. Developers do not need to manually increment or manage versions.
-Simply push your changes, and the system will handle version updates and tagging automatically.
+### Automated Workflow
+The versioning process is fully automated:
+- Developers submit their changes as usual.
+- The workflow handles version updates, tagging, and integration into `main`.
+- No manual intervention is needed for versioning.
 
-### Access Version in Code
+### Accessing the Version in Code
 The version is accessible in the ESPHome YAML configuration file (`TX-Ultimate-Easy-ESPHome_core.yaml`) using the following syntax:
 
 ```yaml
@@ -37,30 +31,46 @@ substitutions:
   version: <<: !include ../versioning/VERSION
 ```
 
-This ensures the correct version is used directly in the ESPHome setup without requiring manual updates.
+This ensures the correct version is dynamically included in the ESPHome setup.
 
-## Benefits of this Versioning Approach
-1. **Clarity**: Each version is tied to a specific point in time, making it easy to track releases.
-2. **Automation**: The process is seamless and reduces manual effort.
-3. **Scalability**: Supports frequent releases while keeping the versioning system organized.
-4. **Traceability**: Git tags and the `VERSION` file ensure releases are well-documented and easily accessible.
+## Benefits
+- **Clarity**: Easily track when a release occurred with meaningful version numbers.
+- **Automation**: Eliminates manual version management.
+- **Scalability**: Supports frequent updates and concurrent workflows.
+- **Traceability**: Maintains a clear history of changes through Git tags and version files.
+
+## System Details
+
+### Version Format
+The format `year.month.sequential_number` includes:
+- `year` (YYYY): A 4-digit number representing the year.
+- `month` (M): A number from 1 to 12 (no leading zeros).
+- `sequential_number`: A positive number incremented with each release in the same month.
+
+### Validation Rules
+The `bump_version.sh` script enforces strict validation:
+- Year must be a 4-digit number.
+- Month must be 1–12 without leading zeros.
+- Sequence must be a positive number without leading zeros.
+
+If validation fails, the workflow stops and provides an error message.
+
+### GitHub Workflow
+The workflow is triggered automatically when:
+- Changes are pushed to `main`.
+- Developers trigger it manually using the `workflow_dispatch` event.
+
+The workflow avoids infinite loops by committing changes with the `[skip-versioning]` marker.
 
 ## Extending the System
-- Add more scripts to handle additional automation tasks, such as generating changelogs or notifying stakeholders of new releases.
-- Enhance the `bump_version.sh` script to support different versioning schemes if needed.
-- Integrate versioning information into your deployment pipelines to label builds with their corresponding version.
+Consider extending the system to:
+- Automatically generate release notes or changelogs.
+- Notify stakeholders when a new version is released.
+- Integrate versioning information into deployment pipelines.
 
-## Version Validation
+## FAQ
+**Q: What happens if two workflows run concurrently?**  
+A: Each workflow operates in its own temporary branch, avoiding conflicts.
 
-The versioning system enforces strict format validation:
-- Year must be a 4-digit number (YYYY)
-- Month must be a 2-digit number (01-12)
-- Sequence must be a 2-digit number (01-99)
-
-The `bump_version.sh` script includes validation checks and will fail if:
-- The version format is invalid
-- The sequence number would exceed 99 in a month
-
-### GitHub Actions Workflow Adjustment
-The GitHub Actions workflow for versioning runs only when changes are merged into the `main` branch, ensuring no premature version updates during PR creation.
-This behavior is automatically handled by the integrated workflow.
+**Q: Can I manually update the version?**  
+A: Manual updates are not needed. The workflow ensures accurate, automated versioning.

versioning/VERSION

@@ -1 +1 @@
-2024.12.01
+2024.12.14

versioning/VERSION_YAML

@@ -1 +1 @@
-version: 2024.12.01
+version: 2024.12.14

versioning/bump_version.sh

@@ -5,18 +5,20 @@ VERSION_YAML_FILE="./versioning/VERSION_YAML"
 
 # Read the current version
 if [ -f "$VERSION_FILE" ]; then
-  CURRENT_VERSION=$(cat $VERSION_FILE)
+  CURRENT_VERSION=$(cat "$VERSION_FILE")
 else
   CURRENT_VERSION="0.0.0" # Default if file doesn't exist
 fi
 
-# Extract components
-CURRENT_YEAR=$(date +%Y)
-CURRENT_MONTH=$(date +%m)
-if ! [[ "$CURRENT_VERSION" =~ ^[0-9]{4}\.[0-9]{2}\.[0-9]{2}$ ]]; then
+# Validate the current version format
+if ! [[ "$CURRENT_VERSION" =~ ^[0-9]{4}\.[0-9]{1,2}\.[0-9]+$ ]]; then
   echo "Error: Invalid version format in $VERSION_FILE"
   exit 1
 fi
+
+# Extract components
+CURRENT_YEAR=$(date +%Y)
+CURRENT_MONTH=$(date +%-m) # Avoid leading zero for the month
 CURRENT_SEQ=$(echo "$CURRENT_VERSION" | awk -F. '{print $3}')
 
 VERSION_YEAR=$(echo "$CURRENT_VERSION" | awk -F. '{print $1}')
@@ -24,17 +26,12 @@ VERSION_MONTH=$(echo "$CURRENT_VERSION" | awk -F. '{print $2}')
 
 # Determine new version
 if [[ "$CURRENT_YEAR" == "$VERSION_YEAR" && "$CURRENT_MONTH" == "$VERSION_MONTH" ]]; then
-  NEXT_SEQ=$((10#$CURRENT_SEQ + 1))
-  if [ $NEXT_SEQ -gt 99 ]; then
-    echo "Error: Sequence number would exceed 99"
-    exit 1
-  fi
-  NEW_SEQ=$(printf "%02d" $NEXT_SEQ)
+  NEXT_SEQ=$((CURRENT_SEQ + 1))
 else
-  NEW_SEQ="01" # Reset sequence for a new month
+  NEXT_SEQ=1 # Reset sequence for a new month
 fi
 
-NEW_VERSION="${CURRENT_YEAR}.${CURRENT_MONTH}.${NEW_SEQ}"
+NEW_VERSION="${CURRENT_YEAR}.${CURRENT_MONTH}.${NEXT_SEQ}"
 
 # Update the plain text VERSION file
 echo "$NEW_VERSION" > "$VERSION_FILE"
@@ -47,7 +44,7 @@ if ! git add "$VERSION_FILE" "$VERSION_YAML_FILE"; then
   echo "Error: Failed to stage version files"
   exit 1
 fi
-if ! git commit -m "Bump version to $NEW_VERSION"; then
+if ! git commit -m "Bump version to $NEW_VERSION [skip-versioning]"; then
   echo "Error: Failed to commit version bump"
   exit 1
 fi