From a368ad860af5f8d26539da250a02b71ec3d11c63 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 10 Sep 2026 08:26:16 -0500 Subject: [PATCH] Document set_internal() limitations inline --- esphome/core/entity_base.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/esphome/core/entity_base.h b/esphome/core/entity_base.h index cf2e0e4d30..f408ac3937 100644 --- a/esphome/core/entity_base.h +++ b/esphome/core/entity_base.h @@ -91,6 +91,16 @@ class EntityBase { // Set whether this Entity should be hidden outside ESPHome. 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_CONNECTION. 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. + // - The guard is coarse: a call from a priority below AFTER_CONNECTION (an on_boot with a low + // priority, or a setup() at LATE) still passes, but MQTT has already cached the flag and the + // API camera listener is already registered, so those consumers keep the old value. + // - Un-hiding an entity declared 'internal: true' in YAML skips the duplicate name check that + // codegen runs for exposed entities, so a name collision can surface at runtime. Entities with + // only an 'id:' are forced internal and use the id as their name. + // - Zigbee codegen skips YAML internal entities entirely, so un-hiding cannot add them to Zigbee. void set_internal(bool internal); // Check if this object is declared to be disabled by default.