From b0bd1189912fd6030649d7a3b653b10145fa40fd Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 10 Sep 2026 08:54:55 -0500 Subject: [PATCH] Recommend the YAML internal key over set_internal() --- esphome/core/entity_base.h | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/esphome/core/entity_base.h b/esphome/core/entity_base.h index 76457ac275..01a1ef7111 100644 --- a/esphome/core/entity_base.h +++ b/esphome/core/entity_base.h @@ -88,10 +88,11 @@ class EntityBase { // Get whether this Entity should be hidden outside ESPHome bool is_internal() const { return this->flags_.internal; } - // Set whether this Entity should be hidden outside ESPHome. Kept for existing projects that - // decide the flag at boot; new designs should use the 'internal:' YAML key. Must be called before - // MQTT and the API read the flag: from on_boot at the default priority, or a setup() that runs - // above setup_priority::AFTER_WIFI. Calls after setup finishes are ignored and log an error. + // Set whether this Entity should be hidden outside ESPHome. Prefer the 'internal:' YAML key + // whenever possible: it is guaranteed and has none of the limitations below. Use this only when + // the decision can only be made at boot. Must be called before MQTT and the API read the flag: + // from on_boot at the default priority, or a setup() that runs above setup_priority::AFTER_WIFI. + // Calls after setup finishes are ignored and log an error. // // Known limitations, all by design and not going to be fixed: // - No consumer is notified of a change, so the flag can only be decided once per boot.