Standardize component on API

Blackymas · Oct 15, 2024 · d7d708a · d7d708a
1 parent e6ddd56
commit d7d708a
Show file tree

Hide file tree

Showing 20 changed files with 219 additions and 209 deletions.
diff --git a/ReleaseNotes.md b/ReleaseNotes.md
@@ -1,7 +1,8 @@
 # v4.4 - Automatic TFT Update
 
 ## General
-This release introduces the option to automatically update the TFT when an older version is detected, simplifying the update process and ensuring your panel always runs the latest display firmware.
+This release introduces the option to automatically update the TFT when an older version is detected,
+simplifying the update process and ensuring your panel always runs the latest display firmware.
 
 ## Breaking Changes and Guidance
 
@@ -14,13 +15,20 @@ Moving forward, update all three components (Blueprint, ESPHome, and TFT) togeth
 ### Users using the "Display as a light" customization must remove it
 This is now part of the core system.
 
-### Action `components_visibility` is deprecated
+### Several changes in the API
+Now all actions will use a common way of transferring information to ESPHome, with the main goal to make it easier to use,
+but also trying to reduce the communication between ESPHome and Nextion, preventing buffer overflows and slowness on the interface.
+We highly recommend visiting our [API documentation](docs/api.md) for the latest syntax for the different actions.
+
+In addition to this standardization, there are some noteworth changes to the API:
+
+#### Action `components_visibility` is deprecated
 It was replaced by [`component_visibility` action](docs/api.md#component-visibility-action-component_visibility).
 
-### Action `icon` now requires page name as a parameter
+#### Action `icon` now requires page name as a parameter
 More info at [API doc - Icon action](docs/api.md#icon-action-icon).
 
-### Actions `init_global`, `init_hardware`, `init_page_home` and `hw_button_state` are deprecated
+#### Actions `init_global`, `init_hardware`, `init_page_home` and `hw_button_state` are deprecated
 It was replaced by a few `set_` var actions during the boot or automation reloaded.
 
 ### Sensor `blueprint_status` was removed
@@ -96,13 +104,15 @@ The boot process was totally rebuilt.
 ### Updated References from `service` to `action` for Compatibility with New Standards
 - **Criticality:** Enhancement
 - **Affected Components:** Blueprint, ESPHome
-- **Description:** Updated all references from `service` to `action` to comply with Home Assistant v2024.8.0 and ESPHome v2024.8.0 standards, ensuring full compatibility with the latest versions.
+- **Description:** Updated all references from `service` to `action` to comply with Home Assistant v2024.8.0 and ESPHome v2024.8.0 standards,
+  ensuring full compatibility with the latest versions.
 
 ### Reduced Logging to Enhance Focus on Critical Information
 - **Criticality:** Enhancement, Breaking Change
 - **Affected Components:** ESPHome, Blueprint
 - **Description:** Logging has been streamlined to focus on the most critical information, reducing noise and improving the clarity of logs.
-  While this change enhances readability and allows users to quickly identify important messages, it may alter the behavior of existing troubleshooting processes that relied on more verbose logs.
+  While this change enhances readability and allows users to quickly identify important messages,
+  it may alter the behavior of existing troubleshooting processes that relied on more verbose logs.
 
 > [!WARNING]
 > Users who depend on detailed logs for debugging may need to adjust their troubleshooting strategies or temporarily adjust log levels as needed.
diff --git a/docs/api.md b/docs/api.md
@@ -76,7 +76,7 @@ It's particularly useful for reflecting changes in device states or user interac
 
 **Parameters:**
 - `page` (string): The page identifier where the button is located.
-- `component_id` (string): The button's unique identifier.
+- `component` (string): The button's unique identifier.
 - `state` (bool): The state of the button, which can affect its background picture and other visual elements.
 - `icon` (string): Icon codepoint from [HASwitchPlate Material Design Icons](https://htmlpreview.github.io/?https://github.com/jobr99/Generate-HASP-Fonts/blob/master/cheatsheet.html).
 Example: "\uE6E8" for `mdi:lightbulb-on-outline`.
@@ -90,7 +90,7 @@ Example: "\uE6E8" for `mdi:lightbulb-on-outline`.
 action: esphome.<your_panel_name>_button
 data:
   page: "buttonpage01"
-  component_id: "button08"
+  component: "button08"
   state: true
   icon: "\uE6E8"           # Example for mdi:lightbulb-on-outline
   icon_color: [255, 0, 0]  # Red
@@ -131,20 +131,20 @@ This action is ideal for creating visually dynamic interfaces, allowing elements
 events, or user actions, such as indicating status changes or highlighting specific UI components.
 
 **Parameters:**
-- `component_id` (string): Identifier of the component whose color will be updated. It is essential that this matches the component's ID in your display layout to ensure the correct element is targeted.
+- `component` (string): Identifier of the component whose color will be updated. It is essential that this matches the component's ID in your display layout to ensure the correct element is targeted.
 - `color` (int[]): The new color for the component, specified as an RGB array (e.g., `[255, 0, 0]` for red).
 
 **Home Assistant Example:**
 ```yaml
 action: esphome.<your_panel_name>_component_color
 data:
-  component_id: "home.time"
+  component: "home.time"
   color: [255, 0, 0]  # Changes the component's color to red
 ```
 > [!NOTE]
 > Replace `<your_panel_name>` with your specific panel name as configured in Home Assistant to ensure correct action execution.
 >
-> Ensure the `component_id` and color parameters accurately target and define the new color for the component.
+> Ensure the `component` and color parameters accurately target and define the new color for the component.
 
 ### Component Text Action: `component_text`
 Updates the text of a specified component on the display, enabling dynamic text content updates.
@@ -153,20 +153,20 @@ Updates the text of a specified component on the display, enabling dynamic text
 Ideal for user interfaces that require real-time text updates, such as status messages, labels, or any text-based information display.
 
 **Parameters:**
-- `component_id` (string): Identifier of the component whose text will be updated. Ensure this matches the component's ID in your display layout.
+- `component` (string): Identifier of the component whose text will be updated. Ensure this matches the component's ID in your display layout.
 - `txt` (string): The new text content to display. This can include static text or dynamic information passed at runtime.
 
 **Home Assistant Example:**
 ```yaml
 action: esphome.<your_panel_name>_component_text
 data:
-  component_id: "home.time"
+  component: "home.time"
   txt: "12:34"
 ```
 > [!NOTE]
 > Replace `<your_panel_name>` with your specific panel name as configured in Home Assistant to ensure correct action execution.
 >
-> Make sure the `component_id` corresponds to the correct component on your display for the text update to work as intended.
+> Make sure the `component` corresponds to the correct component on your display for the text update to work as intended.
 
 ### Component Value Action: `component_val`
 Updates the value of a specified component on the display, enabling dynamic value updates.
@@ -175,20 +175,20 @@ Updates the value of a specified component on the display, enabling dynamic valu
 Ideal for interfaces requiring real-time updates of numerical values, such as counters, temperature readings, or any numeric indicators.
 
 **Parameters:**
-- `component_id` (string): Identifier of the component whose value will be updated. It's crucial this matches the component's ID in your display layout accurately.
+- `component` (string): Identifier of the component whose value will be updated. It's crucial this matches the component's ID in your display layout accurately.
 - `val` (int): The new integer value to be set for the component. This can represent various data types, depending on the component's purpose (e.g., temperature, humidity levels).
 
 **Home Assistant Example:**
 ```yaml
 action: esphome.<your_panel_name>_component_val
 data:
-  component_id: "cover.coverslider"
+  component: "cover.coverslider"
   val: 25
 ```
 > [!NOTE]
 > Replace `<your_panel_name>` with your specific panel name as configured in Home Assistant to ensure correct action execution.
 >
-> Ensure the `component_id` accurately matches the component on your display to successfully update its value.
+> Ensure the `component` accurately matches the component on your display to successfully update its value.
 
 ### Component Visibility Action: `component_visibility`
 Hides or shows a component on the display, allowing for dynamic interface changes.
@@ -198,15 +198,15 @@ This action is ideal for creating interactive user interfaces that adapt by hidi
 
 **Parameters:**
 - `page` (string): Identifies the page where the component belongs to.
-- `component_id` (string): Identifiers of the components to be hidden/shown. It is crucial that this matches the component's ID in your display layout to ensure the correct element is hidden/shown.
+- `component` (string): Identifiers of the components to be hidden/shown. It is crucial that this matches the component's ID in your display layout to ensure the correct element is hidden/shown.
 - `show` (bool): Set to true to show the component, or false to hide it.
 
 **Home Assistant Example:**
 ```yaml
 action: esphome.<your_panel_name>_component_hide
 data:
   page: home
-  component_id: "date" # Hides the date display on Home page
+  component: "date" # Hides the date display on Home page
   show: false
 ```
 <!-- markdownlint-disable MD028 -->
@@ -256,7 +256,7 @@ This action is ideal for dynamically updating icons on your Panel, allowing for
 
 **Parameters:**
 - `page` (string): Identifies the page where the component belongs to.
-- `component_id` (string): Identifier of the chip or button component. Refer to "[Screen components](#screen-components)" for more details.
+- `component` (string): Identifier of the chip or button component. Refer to "[Screen components](#screen-components)" for more details.
 - `icon` (string): Icon codepoint from [HASwitchPlate Material Design Icons](https://htmlpreview.github.io/?https://github.com/jobr99/Generate-HASP-Fonts/blob/master/cheatsheet.html).
 Example: "\uE6E8" for `mdi:lightbulb-on-outline`.
 - `icon_color` (int[]): RGB color array for the icon. Example: `[0, 255, 0]` for green.
@@ -267,7 +267,7 @@ Example: "\uE6E8" for `mdi:lightbulb-on-outline`.
 action: esphome.<your_panel_name>_icon
 data:
   page: home
-  component_id: "chip03"
+  component: "chip03"
   icon: "\uE6E8"           # Example for mdi:lightbulb-on-outline
   icon_color: [0, 255, 0]  # Green
   visible: true
@@ -593,7 +593,7 @@ Updates an entity to display specific values, allowing for dynamic updates of ic
 This action is intended for entities that need to display information dynamically, such as sensor readings or state values, with customized icons, names, and color coding for both icon and value.
 
 **Parameters:**
-- `component_id` (string): Identifier of the entity being updated. For details on entity identifiers, refer to "[Screen components](#screen-components)".
+- `component` (string): Identifier of the entity being updated. For details on entity identifiers, refer to "[Screen components](#screen-components)".
 - `icon` (string): Icon codepoint from [HASwitchPlate Material Design Icons](https://htmlpreview.github.io/?https://github.com/jobr99/Generate-HASP-Fonts/blob/master/cheatsheet.html).
 Indicates the icon displayed next to the value.
 - `icon_color` (int[]): RGB color array for the icon, allowing for custom icon colors.
@@ -605,7 +605,7 @@ Indicates the icon displayed next to the value.
 ```yaml
 action: esphome.<your_panel_name>_value
 data:
-  component_id: "sensor.temperature"
+  component: "sensor.temperature"
   icon: "\uE6E8"           # Example for mdi:thermometer
   icon_color: [255, 0, 0]  # Red
   name: "Temperature"

diff --git a/esphome/nspanel_esphome_addon_upload_tft.yaml b/esphome/nspanel_esphome_addon_upload_tft.yaml
@@ -194,21 +194,21 @@ script:
             - script.execute:
                 id: set_component_visibility
                 page: confirm
-                component_id: bclose
+                component: bclose
                 show: false
             - script.execute:
                 id: set_component_visibility
                 page: confirm
-                component_id: bt_accept
+                component: bt_accept
                 show: false
             - script.execute:
                 id: set_component_visibility
                 page: confirm
-                component_id: bt_clear
+                component: bt_clear
                 show: false
       - script.execute:
           id: set_component_text
-          component_id: confirm.title
+          component: confirm.title
           text: Upload TFT
 
   - id: report_upload_progress

diff --git a/esphome/nspanel_esphome_core_base.yaml b/esphome/nspanel_esphome_core_base.yaml
@@ -135,7 +135,7 @@ ota:
             then:
               - script.execute:
                   id: set_component_value
-                  component_id: progress
+                  component: progress
                   val: 0
               - script.execute:
                   id: boot_log
@@ -157,7 +157,7 @@ ota:
             then:
               - script.execute:
                   id: set_component_value
-                  component_id: progress
+                  component: progress
                   val: 100
               - script.execute:
                   id: boot_log

diff --git a/esphome/nspanel_esphome_core_boot.yaml b/esphome/nspanel_esphome_core_boot.yaml
@@ -126,7 +126,7 @@ script:
           then:
             - script.execute:
                 id: set_component_value
-                component_id: progress
+                component: progress
                 val: !lambda return get_boot_progress_percentage();
 
   - id: boot_progress_dump
@@ -220,7 +220,7 @@ script:
           val: !lambda return int(display_dim_brightness->state);
       - script.execute:
           id: set_component_value
-          component_id: settings.dimslider
+          component: settings.dimslider
           val: !lambda return int(display_dim_brightness->state);
       - script.execute:
           id: set_variable_value
@@ -232,7 +232,7 @@ script:
           val: !lambda return int(display_brightness->state);
       - script.execute:
           id: set_component_value
-          component_id: settings.brightslider
+          component: settings.brightslider
           val: !lambda return int(display_brightness->state);
       - script.execute:
           id: set_brightness

diff --git a/esphome/nspanel_esphome_core_datetime.yaml b/esphome/nspanel_esphome_core_datetime.yaml
@@ -106,8 +106,8 @@ script:
   - id: !extend set_component_font_color  # Defined by nspanel_esphome_core_hw_display.yaml
     then:
       - lambda: |-
-          if (component_id == "home.date") id(home_date_color) = color;
-          else if (component_id == "home.time") id(home_time_color) = color;
+          if (component == "home.date") id(home_date_color) = color;
+          else if (component == "home.time") id(home_time_color) = color;
 
   - id: set_timezone
     mode: restart

diff --git a/esphome/nspanel_esphome_core_hw_buttons.yaml b/esphome/nspanel_esphome_core_hw_buttons.yaml
@@ -209,8 +209,8 @@ script:
   - id: !extend set_component_font_color  # Defined by nspanel_esphome_core_hw_display.yaml
     then:
       - lambda: |-
-          if (component_id == "button_bar_color_on") id(buttons_color_on) = color;
-          else if (component_id == "button_bar_color_off") id(buttons_color_off) = color;
+          if (component == "button_bar_color_on") id(buttons_color_on) = color;
+          else if (component == "button_bar_color_off") id(buttons_color_off) = color;
 
   - id: !extend set_var_int  # Defined by nspanel_esphome_core_base.yaml
     then: