homeassistant 2025.8.2__py3-none-any.whl → 2025.9.0__py3-none-any.whl

homeassistant/components/knx/storage/knx_selector.py

@@ -6,11 +6,103 @@ from typing import Any
 
 import voluptuous as vol
 
-from ..validation import ga_validator, maybe_ga_validator
+from ..validation import ga_validator, maybe_ga_validator, sync_state_validator
 from .const import CONF_DPT, CONF_GA_PASSIVE, CONF_GA_STATE, CONF_GA_WRITE
+from .util import dpt_string_to_dict
 
 
-class GroupSelect(vol.Any):
+class AllSerializeFirst(vol.All):
+    """Use the first validated value for serialization.
+
+    This is a version of vol.All with custom error handling to
+    show proper invalid markers for sub-schema items in the UI.
+    """
+
+
+class KNXSelectorBase:
+    """Base class for KNX selectors supporting optional nested schemas."""
+
+    schema: vol.Schema | vol.Any | vol.All
+    selector_type: str
+    # mark if self.schema should be serialized to `schema` key
+    serialize_subschema: bool = False
+
+    def __call__(self, data: Any) -> Any:
+        """Validate the passed data."""
+        return self.schema(data)
+
+    def serialize(self) -> dict[str, Any]:
+        """Serialize the selector to a dictionary."""
+        # don't use "name", "default", "optional" or "required" in base output
+        # as it will be overwritten by the parent keys attributes
+        # "schema" will be overwritten by knx serializer if `self.serialize_subschema` is True
+        raise NotImplementedError("Subclasses must implement this method.")
+
+
+class KNXSectionFlat(KNXSelectorBase):
+    """Generate a schema-neutral section with title and description for the following siblings."""
+
+    selector_type = "knx_section_flat"
+    schema = vol.Schema(None)
+
+    def __init__(
+        self,
+        collapsible: bool = False,
+    ) -> None:
+        """Initialize the section."""
+        self.collapsible = collapsible
+
+    def serialize(self) -> dict[str, Any]:
+        """Serialize the selector to a dictionary."""
+        return {
+            "type": self.selector_type,
+            "collapsible": self.collapsible,
+        }
+
+
+class KNXSection(KNXSelectorBase):
+    """Configuration groups similar to DataEntryFlow sections but with more options."""
+
+    selector_type = "knx_section"
+    serialize_subschema = True
+
+    def __init__(
+        self,
+        schema: dict[str | vol.Marker, vol.Schemable],
+        collapsible: bool = True,
+    ) -> None:
+        """Initialize the section."""
+        self.collapsible = collapsible
+        self.schema = vol.Schema(schema)
+
+    def serialize(self) -> dict[str, Any]:
+        """Serialize the section to a dictionary."""
+        return {
+            "type": self.selector_type,
+            "collapsible": self.collapsible,
+        }
+
+
+class GroupSelectOption(KNXSelectorBase):
+    """Schema for group select options."""
+
+    selector_type = "knx_group_select_option"
+    serialize_subschema: bool = True
+
+    def __init__(self, schema: vol.Schemable, translation_key: str) -> None:
+        """Initialize the group select option schema."""
+        self.translation_key = translation_key
+        self.schema = vol.Schema(schema)
+
+    def serialize(self) -> dict[str, Any]:
+        """Serialize the group select option to a dictionary."""
+        return {
+            "type": self.selector_type,
+            "translation_key": self.translation_key,
+        }
+
+
+class GroupSelectSchema(vol.Any):
     """Use the first validated value.
 
     This is a version of vol.Any with custom error handling to
@@ -35,10 +127,33 @@ class GroupSelect(vol.Any):
         raise vol.AnyInvalid(self.msg or "no valid value found", path=path)
 
 
-class GASelector:
+class GroupSelect(KNXSelectorBase):
+    """Selector for group select options."""
+
+    selector_type = "knx_group_select"
+    serialize_subschema = True
+
+    def __init__(
+        self,
+        *options: GroupSelectOption,
+        collapsible: bool = True,
+    ) -> None:
+        """Initialize the group select selector."""
+        self.collapsible = collapsible
+        self.schema = GroupSelectSchema(*options)
+
+    def serialize(self) -> dict[str, Any]:
+        """Serialize the group select to a dictionary."""
+        return {
+            "type": self.selector_type,
+            "collapsible": self.collapsible,
+        }
+
+
+class GASelector(KNXSelectorBase):
     """Selector for a KNX group address structure."""
 
-    schema: vol.Schema
+    selector_type = "knx_group_address"
 
     def __init__(
         self,
@@ -48,6 +163,7 @@ class GASelector:
         write_required: bool = False,
         state_required: bool = False,
         dpt: type[Enum] | None = None,
+        valid_dpt: str | Iterable[str] | None = None,
     ) -> None:
         """Initialize the group address selector."""
         self.write = write
@@ -56,12 +172,35 @@ class GASelector:
         self.write_required = write_required
         self.state_required = state_required
         self.dpt = dpt
+        # valid_dpt is used in frontend to filter dropdown menu - no validation is done
+        self.valid_dpt = (valid_dpt,) if isinstance(valid_dpt, str) else valid_dpt
 
         self.schema = self.build_schema()
 
-    def __call__(self, data: Any) -> Any:
-        """Validate the passed data."""
-        return self.schema(data)
+    def serialize(self) -> dict[str, Any]:
+        """Serialize the selector to a dictionary."""
+
+        options: dict[str, Any] = {
+            "write": {"required": self.write_required} if self.write else False,
+            "state": {"required": self.state_required} if self.state else False,
+            "passive": self.passive,
+        }
+        if self.dpt is not None:
+            options["dptSelect"] = [
+                {
+                    "value": item.value,
+                    "translation_key": item.value.replace(".", "_"),
+                    "dpt": dpt_string_to_dict(item.value),  # used for filtering GAs
+                }
+                for item in self.dpt
+            ]
+        if self.valid_dpt is not None:
+            options["validDPTs"] = [dpt_string_to_dict(dpt) for dpt in self.valid_dpt]
+
+        return {
+            "type": self.selector_type,
+            "options": options,
+        }
 
     def build_schema(self) -> vol.Schema:
         """Create the schema based on configuration."""
@@ -118,3 +257,27 @@ class GASelector:
             schema[vol.Required(CONF_DPT)] = vol.In({item.value for item in self.dpt})
         else:
             schema[vol.Remove(CONF_DPT)] = object
+
+
+class SyncStateSelector(KNXSelectorBase):
+    """Selector for knx sync state validation."""
+
+    schema = vol.Schema(sync_state_validator)
+    selector_type = "knx_sync_state"
+
+    def __init__(self, allow_false: bool = False) -> None:
+        """Initialize the sync state validator."""
+        self.allow_false = allow_false
+
+    def serialize(self) -> dict[str, Any]:
+        """Serialize the selector to a dictionary."""
+        return {
+            "type": self.selector_type,
+            "allow_false": self.allow_false,
+        }
+
+    def __call__(self, data: Any) -> Any:
+        """Validate the passed data."""
+        if not self.allow_false and not data:
+            raise vol.Invalid(f"Sync state cannot be {data}")
+        return self.schema(data)

homeassistant/components/knx/storage/serialize.py

@@ -0,0 +1,47 @@
+"""Custom serializer for KNX schemas."""
+
+from typing import Any, cast
+
+import voluptuous as vol
+from voluptuous_serialize import UNSUPPORTED, UnsupportedType, convert
+
+from homeassistant.const import Platform
+from homeassistant.helpers import selector
+
+from .entity_store_schema import KNX_SCHEMA_FOR_PLATFORM
+from .knx_selector import AllSerializeFirst, GroupSelectSchema, KNXSelectorBase
+
+
+def knx_serializer(
+    schema: vol.Schema,
+) -> dict[str, Any] | list[dict[str, Any]] | UnsupportedType:
+    """Serialize KNX schema."""
+    if isinstance(schema, GroupSelectSchema):
+        return [
+            cast(
+                dict[str, Any],  # GroupSelectOption converts to a dict with subschema
+                convert(option, custom_serializer=knx_serializer),
+            )
+            for option in schema.validators
+        ]
+    if isinstance(schema, KNXSelectorBase):
+        result = schema.serialize()
+        if schema.serialize_subschema:
+            result["schema"] = convert(schema.schema, custom_serializer=knx_serializer)
+        return result
+    if isinstance(schema, AllSerializeFirst):
+        return convert(schema.validators[0], custom_serializer=knx_serializer)
+
+    if isinstance(schema, selector.Selector):
+        return schema.serialize() | {"type": "ha_selector"}
+
+    return UNSUPPORTED
+
+
+def get_serialized_schema(
+    platform: Platform,
+) -> dict[str, Any] | list[dict[str, Any]] | None:
+    """Get the schema for a specific platform."""
+    if knx_schema := KNX_SCHEMA_FOR_PLATFORM.get(platform):
+        return convert(knx_schema, custom_serializer=knx_serializer)
+    return None

homeassistant/components/knx/storage/util.py

@@ -3,11 +3,29 @@
 from functools import partial
 from typing import Any
 
+from xknx.typing import DPTMainSubDict
+
 from homeassistant.helpers.typing import ConfigType
 
 from .const import CONF_DPT, CONF_GA_PASSIVE, CONF_GA_STATE, CONF_GA_WRITE
 
 
+def dpt_string_to_dict(dpt: str) -> DPTMainSubDict:
+    """Convert a DPT string to a typed dictionary with main and sub components.
+
+    Examples:
+        >>> dpt_string_to_dict("1.010")
+        {'main': 1, 'sub': 10}
+        >>> dpt_string_to_dict("5")
+        {'main': 5, 'sub': None}
+    """
+    dpt_num = dpt.split(".")
+    return DPTMainSubDict(
+        main=int(dpt_num[0]),
+        sub=int(dpt_num[1]) if len(dpt_num) > 1 else None,
+    )
+
+
 def nested_get(dic: ConfigType, *keys: str, default: Any | None = None) -> Any:
     """Get the value from a nested dictionary."""
     for key in keys:

homeassistant/components/knx/strings.json

@@ -339,5 +339,275 @@
       "name": "[%key:common::action::reload%]",
       "description": "Reloads the KNX integration."
     }
+  },
+  "config_panel": {
+    "entities": {
+      "create": {
+        "type_selection": {
+          "title": "Select entity type",
+          "header": "Create KNX entity"
+        },
+        "header": "Create new entity",
+        "_": {
+          "entity": {
+            "title": "Entity configuration",
+            "description": "Home Assistant specific settings.",
+            "name_title": "Device and entity name",
+            "name_description": "Define how the entity should be named in Home Assistant.",
+            "device_description": "A device allows to group multiple entities. Select the device this entity belongs to or create a new one.",
+            "entity_label": "Entity name",
+            "entity_description": "Optional if a device is selected, otherwise required. If the entity is assigned to a device, the device name is used as prefix.",
+            "entity_category_title": "Entity category",
+            "entity_category_description": "Classification of a non-primary entity. Leave empty for standard behaviour."
+          },
+          "knx": {
+            "title": "KNX configuration",
+            "knx_group_address": {
+              "dpt": "Datapoint type",
+              "send_address": "Send address",
+              "state_address": "State address",
+              "passive_addresses": "Passive addresses",
+              "valid_dpts": "Valid DPTs"
+            },
+            "sync_state": {
+              "title": "State updater",
+              "description": "Actively request state updates from KNX bus for state addresses.",
+              "strategy": "Strategy",
+              "options": {
+                "true": "Use integration default",
+                "false": "Never",
+                "init": "Once when connection established",
+                "expire": "Expire after last value update",
+                "every": "Scheduled every"
+              }
+            }
+          }
+        },
+        "binary_sensor": {
+          "description": "Read-only entity for binary datapoints. Window or door states etc.",
+          "knx": {
+            "section_binary_sensor": {
+              "title": "Binary sensor",
+              "description": "DPT 1 group addresses representing binary states."
+            },
+            "invert": {
+              "label": "Invert",
+              "description": "Invert payload before processing."
+            },
+            "section_advanced_options": {
+              "title": "State properties",
+              "description": "Properties of the binary sensor state."
+            },
+            "ignore_internal_state": {
+              "label": "Force update",
+              "description": "Write each update to the state machine, even if the data is the same."
+            },
+            "context_timeout": {
+              "label": "Context timeout",
+              "description": "The time in seconds between multiple identical telegram payloads would count towards an internal counter. This can be used to automate on multi-clicks of a button. `0` to disable this feature."
+            },
+            "reset_after": {
+              "label": "Reset after",
+              "description": "Reset back to “off” state after specified seconds."
+            }
+          }
+        },
+        "cover": {
+          "description": "The KNX cover platform is used as an interface to shutter actuators.",
+          "knx": {
+            "section_binary_control": {
+              "title": "Open/Close control",
+              "description": "DPT 1 group addresses triggering full movement."
+            },
+            "ga_up_down": {
+              "label": "Open/Close"
+            },
+            "invert_updown": {
+              "label": "Invert",
+              "description": "Default is UP (0) to open a cover and DOWN (1) to close a cover. Enable this to invert the open/close commands from/to your KNX actuator."
+            },
+            "section_stop_control": {
+              "title": "Stop",
+              "description": "DPT 1 group addresses for stopping movement."
+            },
+            "ga_stop": {
+              "label": "Stop"
+            },
+            "ga_step": {
+              "label": "Stepwise move"
+            },
+            "section_position_control": {
+              "title": "Position",
+              "description": "DPT 5 group addresses for cover position."
+            },
+            "ga_position_set": {
+              "label": "Set position"
+            },
+            "ga_position_state": {
+              "label": "Current position"
+            },
+            "invert_position": {
+              "label": "Invert",
+              "description": "Invert payload before processing. Enable if KNX reports 0% as fully closed."
+            },
+            "section_tilt_control": {
+              "title": "Tilt",
+              "description": "DPT 5 group addresses for slat tilt angle."
+            },
+            "ga_angle": {
+              "label": "Tilt angle"
+            },
+            "invert_angle": {
+              "label": "[%key:component::knx::config_panel::entities::create::cover::knx::invert_position::label%]",
+              "description": "[%key:component::knx::config_panel::entities::create::cover::knx::invert_position::description%]"
+            },
+            "section_travel_time": {
+              "title": "Travel time",
+              "description": "Used to calculate intermediate positions of the cover while traveling."
+            },
+            "travelling_time_up": {
+              "label": "Travel time for opening",
+              "description": "Time the cover needs to fully open in seconds."
+            },
+            "travelling_time_down": {
+              "label": "Travel time for closing",
+              "description": "Time the cover needs to fully close in seconds."
+            }
+          }
+        },
+        "light": {
+          "description": "The KNX light platform is used as an interface to dimming actuators, LED controllers, DALI gateways and similar.",
+          "knx": {
+            "section_switch": {
+              "title": "Switch",
+              "description": "Turn the light on/off."
+            },
+            "ga_switch": {
+              "label": "Switch"
+            },
+            "section_brightness": {
+              "title": "Brightness",
+              "description": "Control the brightness of the light."
+            },
+            "ga_brightness": {
+              "label": "Brightness"
+            },
+            "section_color_temp": {
+              "title": "Color temperature",
+              "description": "Control the color temperature of the light."
+            },
+            "ga_color_temp": {
+              "label": "Color temperature",
+              "options": {
+                "5_001": "Percent",
+                "7_600": "Kelvin",
+                "9": "2-byte floating point"
+              }
+            },
+            "color_temp_min": {
+              "label": "Warmest possible color temperature"
+            },
+            "color_temp_max": {
+              "label": "Coldest possible color temperature"
+            },
+            "color": {
+              "title": "Color",
+              "description": "Control the color of the light.",
+              "options": {
+                "single_address": {
+                  "label": "Single address",
+                  "description": "RGB, RGBW or XYY color controlled by a single group address."
+                },
+                "individual_addresses": {
+                  "label": "Individual addresses",
+                  "description": "RGB(W) using individual state and brightness group addresses."
+                },
+                "hsv_addresses": {
+                  "label": "HSV",
+                  "description": "Hue, saturation and brightness using individual group addresses."
+                }
+              },
+              "ga_color": {
+                "label": "Color",
+                "options": {
+                  "232_600": "RGB",
+                  "242_600": "XYY",
+                  "251_600": "RGBW"
+                }
+              },
+              "section_red": {
+                "title": "Red",
+                "description": "Controls the light's red color component. Brightness group address is required."
+              },
+              "ga_red_switch": {
+                "label": "Red switch"
+              },
+              "ga_red_brightness": {
+                "label": "Red brightness"
+              },
+              "section_green": {
+                "title": "Green",
+                "description": "Controls the light's green color component. Brightness group address is required."
+              },
+              "ga_green_switch": {
+                "label": "Green switch"
+              },
+              "ga_green_brightness": {
+                "label": "Green brightness"
+              },
+              "section_blue": {
+                "title": "Blue",
+                "description": "Controls the light's blue color component. Brightness group address is required."
+              },
+              "ga_blue_switch": {
+                "label": "Blue switch"
+              },
+              "ga_blue_brightness": {
+                "label": "Blue brightness"
+              },
+              "section_white": {
+                "title": "White",
+                "description": "Controls the light's white color component. Brightness group address is required."
+              },
+              "ga_white_switch": {
+                "label": "White switch"
+              },
+              "ga_white_brightness": {
+                "label": "White brightness"
+              },
+              "ga_hue": {
+                "label": "Hue",
+                "description": "Controls the light's hue."
+              },
+              "ga_saturation": {
+                "label": "Saturation",
+                "description": "Controls the light's saturation."
+              }
+            }
+          }
+        },
+        "switch": {
+          "description": "The KNX switch platform is used as an interface to switching actuators.",
+          "knx": {
+            "section_switch": {
+              "title": "Switching",
+              "description": "DPT 1 group addresses controlling the switch function."
+            },
+            "ga_switch": {
+              "label": "Switch",
+              "description": "Group address to switch the device on/off."
+            },
+            "invert": {
+              "label": "Invert",
+              "description": "Invert payloads before processing or sending."
+            },
+            "respond_to_read": {
+              "label": "Respond to read",
+              "description": "Respond to GroupValueRead telegrams received to the configured send address."
+            }
+          }
+        }
+      }
+    }
   }
 }

homeassistant/components/knx/translations/bg.json

@@ -32,6 +32,83 @@
             }
         }
     },
+    "config_panel": {
+        "entities": {
+            "create": {
+                "_": {
+                    "entity": {
+                        "entity_category_title": "\u041a\u0430\u0442\u0435\u0433\u043e\u0440\u0438\u044f \u043d\u0430 \u043e\u0431\u0435\u043a\u0442\u0430",
+                        "entity_label": "\u0418\u043c\u0435 \u043d\u0430 \u043e\u0431\u0435\u043a\u0442\u0430"
+                    },
+                    "knx": {
+                        "sync_state": {
+                            "options": {
+                                "false": "\u041d\u0438\u043a\u043e\u0433\u0430"
+                            }
+                        }
+                    }
+                },
+                "cover": {
+                    "knx": {
+                        "section_position_control": {
+                            "title": "\u041f\u043e\u0437\u0438\u0446\u0438\u044f"
+                        }
+                    }
+                },
+                "header": "\u0421\u044a\u0437\u0434\u0430\u0432\u0430\u043d\u0435 \u043d\u0430 \u043d\u043e\u0432 \u043e\u0431\u0435\u043a\u0442",
+                "light": {
+                    "knx": {
+                        "color": {
+                            "ga_color": {
+                                "label": "\u0426\u0432\u044f\u0442",
+                                "options": {
+                                    "232_600": "RGB",
+                                    "242_600": "XYY",
+                                    "251_600": "RGBW"
+                                }
+                            },
+                            "options": {
+                                "hsv_addresses": {
+                                    "label": "HSV"
+                                }
+                            },
+                            "section_blue": {
+                                "title": "\u0421\u0438\u043d\u044c\u043e"
+                            },
+                            "section_green": {
+                                "title": "\u0417\u0435\u043b\u0435\u043d\u043e"
+                            },
+                            "section_red": {
+                                "title": "\u0427\u0435\u0440\u0432\u0435\u043d\u043e"
+                            },
+                            "section_white": {
+                                "title": "\u0411\u044f\u043b\u043e"
+                            },
+                            "title": "\u0426\u0432\u044f\u0442"
+                        },
+                        "ga_brightness": {
+                            "label": "\u042f\u0440\u043a\u043e\u0441\u0442"
+                        },
+                        "ga_color_temp": {
+                            "label": "\u0426\u0432\u0435\u0442\u043d\u0430 \u0442\u0435\u043c\u043f\u0435\u0440\u0430\u0442\u0443\u0440\u0430",
+                            "options": {
+                                "7_600": "\u041a\u0435\u043b\u0432\u0438\u043d"
+                            }
+                        },
+                        "section_brightness": {
+                            "title": "\u042f\u0440\u043a\u043e\u0441\u0442"
+                        },
+                        "section_color_temp": {
+                            "title": "\u0426\u0432\u0435\u0442\u043d\u0430 \u0442\u0435\u043c\u043f\u0435\u0440\u0430\u0442\u0443\u0440\u0430"
+                        }
+                    }
+                },
+                "type_selection": {
+                    "title": "\u0418\u0437\u0431\u0435\u0440\u0435\u0442\u0435 \u0442\u0438\u043f \u043e\u0431\u0435\u043a\u0442"
+                }
+            }
+        }
+    },
     "entity": {
         "climate": {
             "knx_climate": {