Compare commits

...
Author SHA1 Message Date
Artur Pragacz cdcce4943c [template] Let a template switch set its wizard role 2026-11-17 08:20:37 +01:00
7 changed files with 151 additions and 12 deletions

No files matched your search

+3 -2
View File
@@ -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 <component>.<name>), so a client can recognise it. The user cannot change it,
// and no two entities of a wizard share one.
// (always <component>.<name>), 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,
+11 -7
View File
@@ -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)
# <component>.<name>, 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 <component>.<name> and is not set by the user.
is built. The role is <component>.<name>; 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 <component>.<name>, 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
+33
View File
@@ -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.<name>."""
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.<wizard_role>, 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
@@ -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,
)
+3 -2
View File
@@ -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"
)
]
@@ -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
@@ -0,0 +1,72 @@
"""A template switch can name its wizard role, which is sent as template.<name>."""
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))