diff --git a/esphome/components/api/api.proto b/esphome/components/api/api.proto index e33d7df2d1c..437a5c00cd7 100644 --- a/esphome/components/api/api.proto +++ b/esphome/components/api/api.proto @@ -486,8 +486,9 @@ message DeviceWizardRequest { // a client matches an entity by platform, device_id and key together. A client that does // not know platform ignores it, so the version stays 1. // Its role, when set, is a stable name that the device's firmware gives the entity -// (always .), so a client can recognise it. The user cannot change it, -// and no two entities of a wizard share one. +// (always .), so a client can recognise it. It is fixed when the firmware +// is built, by the component or by the device's configuration, and no two entities of a +// wizard share one. // // An input is filled in by the user with the id of a Home Assistant entity. It either // stands for one entity of the device's homeassistant platform (sensor, binary_sensor, diff --git a/esphome/components/api/wizard.py b/esphome/components/api/wizard.py index 58e79fbe3a4..0427c61e57c 100644 --- a/esphome/components/api/wizard.py +++ b/esphome/components/api/wizard.py @@ -73,8 +73,10 @@ WIZARD_DESCRIPTION_MAX_LENGTH = 255 WIZARD_FILTER_MAX_LENGTH = 63 WIZARD_SUPPORTED_FEATURE_MAX_LENGTH = 127 WIZARD_ROLE_MAX_LENGTH = 63 +_WIZARD_ROLE_PART = "[a-z0-9_]+" +WIZARD_ROLE_NAME_PATTERN = re.compile(_WIZARD_ROLE_PART) # ., so roles of different components never clash -_WIZARD_ROLE_PATTERN = re.compile(r"[a-z0-9_]+\.[a-z0-9_]+") +_WIZARD_ROLE_PATTERN = re.compile(rf"{_WIZARD_ROLE_PART}\.{_WIZARD_ROLE_PART}") @dataclass @@ -93,7 +95,7 @@ def register_entity_role(entity_id: ID, role: str) -> None: """Give an entity a role, a stable name that Home Assistant recognises it by on a wizard page. For a component to call while its config is validated, so the role is known before the wizard - is built. The role is . and is not set by the user. + is built. The role is .; the component picks the name or takes it from its config. The wizard only sends it when the entity is on one of its pages. """ if len(role) > WIZARD_ROLE_MAX_LENGTH or not _WIZARD_ROLE_PATTERN.fullmatch(role): @@ -440,8 +442,9 @@ def _validate_unique_wizard_roles(wizard: ConfigType) -> None: continue if (other := seen.get(role)) is not None and other != entity_id: raise cv.Invalid( - f"Wizard entities '{other}' and '{entity_id}' both have the role '{role}', " - "so only one of them can be in the wizard", + f"Wizard entities '{other}' and '{entity_id}' both have the role '{role}'. " + "Keep only one of them in the wizard, or change the role of one " + "if its configuration sets it", path=[CONF_WIZARD], ) seen[role] = entity_id @@ -527,9 +530,10 @@ def wizard_document(wizard: ConfigType, config: fv.FinalValidateConfig) -> Confi and device, so a client matches an entity by platform, device_id and key together. A client that does not know platform ignores it, so the version stays 1. - An entity role is a stable name, always ., that the component of the entity - gives it with register_entity_role, so Home Assistant can recognise the entity. The user - cannot set or change it, and no two entities of a wizard share one. A client that does not - know role ignores it, so the version stays 1. + gives it with register_entity_role, so Home Assistant can recognise the entity. The name + is fixed by the component or, where it has an option for it, by the configuration. No two + entities of a wizard share a role. A client that does not know role ignores it, so the + version stays 1. - An input key is the FNV-1 hash of the ESPHome id of the input, or of the linked entity. A linked entity must not set entity_id, as that is a static entry kept apart from the ones the wizard sets. - multiple means the user may pick several entities. The client sends them in one diff --git a/esphome/components/template/__init__.py b/esphome/components/template/__init__.py index 542e78809c7..b018bfbd74c 100644 --- a/esphome/components/template/__init__.py +++ b/esphome/components/template/__init__.py @@ -1,5 +1,38 @@ import esphome.codegen as cg +from esphome.components.api import wizard +import esphome.config_validation as cv +from esphome.const import CONF_ID +from esphome.types import ConfigType DOMAIN = "template" +CONF_WIZARD_ROLE = "wizard_role" + template_ns = cg.esphome_ns.namespace("template_") + +_WIZARD_ROLE_NAME_MAX_LENGTH = wizard.WIZARD_ROLE_MAX_LENGTH - len(DOMAIN) - 1 + + +def _wizard_role_name(value: str) -> str: + """Validate the name of a wizard role; the role itself is template..""" + if ( + not wizard.WIZARD_ROLE_NAME_PATTERN.fullmatch(value) + or len(value) > _WIZARD_ROLE_NAME_MAX_LENGTH + ): + raise cv.Invalid( + f"A wizard role is 1 to {_WIZARD_ROLE_NAME_MAX_LENGTH} lowercase letters, " + "digits and underscores" + ) + return value + + +WIZARD_ROLE_SCHEMA = cv.Schema( + {cv.Optional(CONF_WIZARD_ROLE): cv.All(cv.string_strict, _wizard_role_name)} +) + + +def register_wizard_role(config: ConfigType) -> ConfigType: + """Give the entity the wizard role template., when it sets one.""" + if (name := config.get(CONF_WIZARD_ROLE)) is not None: + wizard.register_entity_role(config[CONF_ID], f"{DOMAIN}.{name}") + return config diff --git a/esphome/components/template/switch/__init__.py b/esphome/components/template/switch/__init__.py index f8e509faf36..6694a9dd0c8 100644 --- a/esphome/components/template/switch/__init__.py +++ b/esphome/components/template/switch/__init__.py @@ -13,7 +13,7 @@ from esphome.const import ( CONF_TURN_ON_ACTION, ) -from .. import template_ns +from .. import WIZARD_ROLE_SCHEMA, register_wizard_role, template_ns TemplateSwitch = template_ns.class_("TemplateSwitch", switch.Switch, cg.Component) @@ -50,8 +50,10 @@ CONFIG_SCHEMA = cv.All( ), } ) + .extend(WIZARD_ROLE_SCHEMA) .extend(cv.COMPONENT_SCHEMA), validate, + register_wizard_role, ) diff --git a/tests/component_tests/api/test_wizard.py b/tests/component_tests/api/test_wizard.py index 8d50cdd5f54..6d1510cc0f2 100644 --- a/tests/component_tests/api/test_wizard.py +++ b/tests/component_tests/api/test_wizard.py @@ -1297,8 +1297,9 @@ def test_two_entities_with_the_same_role_are_rejected(tmp_path: Path) -> None: assert config_errors(path) == [ ( - "Wizard entities 'sw' and 'sw2' both have the role 'example.enable', " - "so only one of them can be in the wizard" + "Wizard entities 'sw' and 'sw2' both have the role 'example.enable'. " + "Keep only one of them in the wizard, or change the role of one " + "if its configuration sets it" ) ] diff --git a/tests/component_tests/template/config/switch_wizard_role.yaml b/tests/component_tests/template/config/switch_wizard_role.yaml new file mode 100644 index 00000000000..439defcc4e8 --- /dev/null +++ b/tests/component_tests/template/config/switch_wizard_role.yaml @@ -0,0 +1,26 @@ +esphome: + name: test + +esp32: + board: esp32dev + +wifi: + ap: + +api: + wizard: + pages: + - entities: + - id: bluetooth_switch + - id: plain_switch + +switch: + - platform: template + id: bluetooth_switch + name: Bluetooth + optimistic: true + wizard_role: bluetooth_enabled + - platform: template + id: plain_switch + name: Plain + optimistic: true diff --git a/tests/component_tests/template/test_template_wizard_role.py b/tests/component_tests/template/test_template_wizard_role.py new file mode 100644 index 00000000000..a8f5e1d0149 --- /dev/null +++ b/tests/component_tests/template/test_template_wizard_role.py @@ -0,0 +1,72 @@ +"""A template switch can name its wizard role, which is sent as template..""" + +from collections.abc import Callable +import json +from pathlib import Path +import re + +import pytest + +from esphome import config_validation as cv +from esphome.components.api import wizard +from esphome.components.template import CONF_WIZARD_ROLE +from esphome.components.template.switch import CONFIG_SCHEMA +from esphome.const import CONF_ID, CONF_NAME, CONF_OPTIMISTIC, PlatformFramework +from esphome.helpers import zstd_module +from esphome.types import ConfigType +from tests.component_tests.types import SetCoreConfigCallable + +MAX_LENGTH = wizard.WIZARD_ROLE_MAX_LENGTH - len("template.") + + +def _switch_config(role: str) -> ConfigType: + return { + CONF_ID: "bluetooth_switch", + CONF_NAME: "Bluetooth", + CONF_OPTIMISTIC: True, + CONF_WIZARD_ROLE: role, + } + + +def test_role_is_sent_in_the_wizard( + generate_main: Callable[[str | Path], str], + component_config_path: Callable[[str], Path], +) -> None: + main_cpp = generate_main(component_config_path("switch_wizard_role.yaml")) + + match = re.search( + r"const uint8_t esphome::api::API_WIZARD_DATA\[\] PROGMEM = \{([^}]*)\};", + main_cpp, + ) + assert match is not None + blob = bytes(int(byte) for byte in match.group(1).split(", ")) + document = json.loads(zstd_module().decompress(blob)) + assert [entity.get("role") for entity in document["pages"][0]["entities"]] == [ + "template.bluetooth_enabled", + None, + ] + + +@pytest.mark.parametrize( + "role", + [ + "", + "Bluetooth", + "template.bluetooth", + "bluetooth enabled", + "a" * (MAX_LENGTH + 1), + ], +) +def test_invalid_role_names_are_rejected( + set_core_config: SetCoreConfigCallable, role: str +) -> None: + set_core_config(PlatformFramework.ESP32_IDF) + + with pytest.raises(cv.Invalid, match=f"A wizard role is 1 to {MAX_LENGTH} "): + CONFIG_SCHEMA(_switch_config(role)) + + +def test_longest_role_name_is_accepted(set_core_config: SetCoreConfigCallable) -> None: + set_core_config(PlatformFramework.ESP32_IDF) + + CONFIG_SCHEMA(_switch_config("a" * MAX_LENGTH))