Um artigo do XDA da semana passada contava uma casa inteligente que desabou em uma noite. O proprietário arrumou os nomes de seus dispositivos, clicou em salvar, e cada automação que fazia referência aos IDs antigos ficou em silêncio. As luzes pararam de reagir ao movimento. A rotina matinal pulou metade de seus passos. O painel de controle se encheu de sinais de exclamação vermelhos. Nada no Home Assistant os alertou antes da mudança; nada reverteu isso depois.
Essa história é comum o suficiente para que a nomeação de entidades do Home Assistant mereça seu próprio conjunto de ferramentas, não apenas uma renomeação em uma tarde chuvosa. Os sete aplicativos de desktop abaixo cobrem tudo que você precisa antes de tocar um único ID: refatorações de teste, linting YAML, busca entre arquivos, aliases que mantêm o nome amigável separado da chave de máquina, fluxos de renomeação de Zigbee e Z-Wave que se sincronizam com as entidades, e controle de versão para que erros sejam reversíveis em segundos.
O que procurar em uma configuração de nomeação de entidades
- Refatoração de teste. Uma renomeação deve previsualizaar cada automação, script, cena, painel de controle e referência de plano antes de confirmar nada.
- Linting YAML. Indentação quebrada ou um
entity_id:suspenso deve falhar no seu editor, não na sua rotina matinal. - Busca de ID de entidade em automações, scripts e cenas. Um atalho para encontrar cada lugar onde
light.living_room_lampaparece, incluindo dentro de modelos. - Suporte a alias. Nomes amigáveis devem ser livres para mudar sem tocar no ID da entidade subjacente no qual as automações dependem.
- Renomeação de dispositivos Zigbee e Z-Wave que se sincroniza com as entidades. Renomear um dispositivo na UI do ZHA ou Z-Wave JS deve se propagar para cada entidade que esse dispositivo expõe, não deixar órfãos.
- Configuração controlada por versão. Git ou equivalente para que um refator ruim esteja a um
git revertde curado.
Comparação rápida
| Aplicativo | Melhor para | Trata referências de renomeação | Custo |
|---|---|---|---|
| Home Assistant | O diálogo de renomeação principal | Sim, nativo | Gratuito |
| Studio Code Server | Edição e busca de YAML | Sim, via busca em arquivos | Gratuito |
| HACS | Instalando o resto desta lista | Não, pré-requisito | Gratuito |
| ESPHome | Hardware DIY, única fonte de verdade | Sim, em tempo de compilação | Gratuito |
| Node-RED | Automações visuais complexas | Parcial, por fluxo | Gratuito |
| Automation Editor | Edição de automação única em UI | Sim, nativo | Gratuito |
| Custom Brand Icons | Auditoria visual de convenções de nomenclatura | Não, detecta desvios visualmente | Gratuito |
Os aplicativos
1. Home Assistant
Baixar: Home Assistant
Comece aqui, porque o núcleo melhorou muito nisto. Desde a versão 2023.4, o diálogo de configurações de entidade traz uma ferramenta “Entity ID rename” que busca automações, scripts, cenas, painéis de controle e planos para referências ao ID antigo e oferece atualizá-los em uma única passagem. Ele é executado como uma prévia primeiro, listando cada correspondência com seu arquivo e linha, e apenas confirma quando verificado.
Essa prévia é a rede de segurança mais útil na pilha. Ela captura referências modeladas dentro de Jinja que uma busca de texto simples perderia, e identifica casos onde um ID aparece dentro de uma âncora YAML ou um arquivo de pacote que a UI não tocaria. Quando não pode resolver uma referência automaticamente (um ID de entidade construído em tempo de execução a partir de uma variável, por exemplo), ele diz assim em vez de passar silenciosamente.
O problema: ele conhece apenas as fontes que pode ver. Integrações personalizadas que armazenam IDs de entidade em seus próprios arquivos JSON, ou fluxos NodeRED salvos fora de .storage, precisam de uma segunda passagem com as ferramentas mais abaixo nesta lista.
2. Studio Code Server
Baixar: Studio Code Server
O complemento instalado por HACS que coloca um VS Code completo em uma aba do navegador, apontado diretamente para /config. O linting YAML está ativado por padrão, a extensão Home Assistant vem pré-instalada, e Ctrl+Shift+F faz uma busca em todo o projeto que respeita .gitignore.
Para nomeação de entidades, é aqui que acontece a auditoria de segunda passagem. Depois que o diálogo de renomeação principal é executado, abra o Studio Code Server, procure o ID antigo e confirme que há zero resultados. Se algum retornar, geralmente estão em arquivos que o diálogo não pode inspecionar: definições de comando shell, URLs de sensores REST ou sensores de modelo construídos com state_attr(). Corrija-os lá, confirme, recarregue.
O preenchimento automático merece sua própria menção. Digite entity_id: e ele sugere o registro em tempo real, então typos nunca sobrevivem até o tempo de execução. Renomeie um dispositivo amanhã e as sugestões serão atualizadas no próximo carregamento.
3. HACS (Home Assistant Community Store)
Baixar: HACS
Não é uma ferramenta de nomeação, mas um pré-requisito. HACS é o gerenciador de pacotes da comunidade que instala Studio Code Server, Custom Brand Icons e alguns complementos de qualidade de vida que tornam possível o resto do fluxo de trabalho. A configuração é única: ative o modo avançado em seu perfil, coloque a integração HACS por meio de um comando shell, reinicie e adicione a integração.
Dois hábitos que valem a pena adotar uma vez que HACS está em lugar. Primeiro, fixe versões em vez de seguir main em qualquer coisa que toque entidades, porque uma mudança incompatível surpreendente durante um refator de renomeação é o pior momento possível. Segundo, use a visualização de changelog integrada do HACS antes de cada atualização. Geralmente é o único lugar onde o comportamento de mudança de renomeação é chamado com antecedência.
4. ESPHome
Baixar: ESPHome
Para qualquer coisa em hardware ESP32 ou ESP8266, ESPHome é a camada de nomeação. Defina name: living-room-lamp uma vez no YAML do dispositivo e cada entidade que é gravada nessa placa (light.living_room_lamp, sensor.living_room_lamp_temperature, o que quer que seja) obtém um ID correspondente. Altere o campo name:, graveie novamente e Home Assistant verá os novos IDs na próxima inicialização.
Essa única fonte de verdade é o que evita o tipo de desvio que o artigo do XDA descrevia. O padrão antigo era: renomeie o dispositivo em Home Assistant, renomeie-o novamente em ESPHome, espere que ambos os lados concordem. O padrão atual é: renomeie-o em ESPHome, deixe Home Assistant seguir. É uma área de superfície menor para manter consistência, e os arquivos .yaml controlados por versão significam que cada renomeação é uma diferença em um repositório.
Combine-o com o diálogo de renomeação principal para a transição inicial. ESPHome cria os novos IDs na primeira inicialização; o diálogo reescreve as referências aos antigos. Duas passagens, sem órfãos.
5. Node-RED
Baixar: Node-RED
Quando automações passam por vinte ou trinta e o editor YAML começa a parecer apertado, o editor de fluxo visual do Node-RED é o próximo passo usual. IDs de entidade se tornam cidadãos de primeira classe na tela: cada nó que toca um a mostra no rótulo, e a barra lateral tem uma busca de registro em tempo real para que IDs mal digitados sejam impossíveis de salvar.
Para nomeação de entidades especificamente, a busca por fluxo do Node-RED é a ferramenta. Abra um fluxo, pressione Ctrl+F, digite o ID antigo, e cada nó que o referencia se ilumina. Renomeie em massa através dos painéis de configuração do nó, implante, pronto. Fluxos exportam como JSON, então vivem felizes no mesmo repositório git que o resto da configuração.
A compensação: Node-RED é executado ao lado do próprio mecanismo de automação do Home Assistant em vez de substituí-lo, então um refator de ID de entidade agora deve ser aplicado em dois lugares. Mantenha uma lista de verificação.
6. Automation Editor (integrado)
Baixar: Automation Editor (vem com Home Assistant)
O editor de UI padrão é frequentemente subestimado. Para edições de automação única, ele trata IDs de entidade como referências pesquisáveis: altere o seletor de entidade do gatilho e os campos de condição e ação correspondentes se atualizam na mesma gravação. Sem edição manual de YAML, sem risco de uma vírgula perdida.
Onde ganha seu lugar nesta lista é o aviso “Rename” que aparece quando você altera um dispositivo ou entidade que a automação referencia. Ele oferece a mesma prévia de atualizar-referências-em-toda-a-configuração que o diálogo principal faz, limitado à automação que você tem aberta. Para o caso comum, edite uma automação única, perceba que a entidade vinculada recebeu um ID mais amigável, aceite o renomeação, salve e continue.
Para qualquer coisa que abrange múltiplas automações, use o diálogo de renomeação principal. Este é para mudanças de arquivo único cirúrgicas.
7. Custom Brand Icons
Baixar: Custom Brand Icons
O estranho, e o que se paga mais rápido. Custom Brand Icons é uma integração HACS que permite anexar ícones de fornecedor e produto a entidades por padrão. Dê a cada entidade light.living_* o mesmo ícone de lâmpada, cada sensor.*_battery o mesmo ícone de bateria, cada switch.plug_* a mesma tomada.
O benefício de refatoração de nomeação é visual. Abra o painel de controle após uma renomeação e qualquer entidade que caiu fora do padrão (uma gralha, um alias obsoleto, um dispositivo que foi renomeado mas não o assistente vinculado) mostra o ícone padrão de fallback em vez do ícone da família. Uma renomeação incorreta aparece como um outlier visual antes de aparecer como uma automação quebrada.
Defina os padrões uma vez contra sua convenção de nomenclatura, mantenha-os em configuration.yaml, e cada renomeação futura ou corresponde ao padrão ou se anuncia.
Como escolher a pilha certa
A camada base, para cada configuração: Home Assistant mais HACS mais Studio Code Server mais git. Essa combinação fornece o diálogo de renomeação principal, a busca de segunda passagem, o canal de pacotes da comunidade para o resto e o botão desfazer.
Adicione ESPHome se alguma de suas entidades vem de hardware DIY. Ele move a fonte de verdade para esses nomes para fora da UI do Home Assistant e em YAML controlado por versão, e remove uma classe inteira de bugs de desvio.
Adicione Node-RED se você tiver mais do que algumas dúzias de automações ou se alguma delas abrange mais de três ou quatro etapas. O editor visual é mais fácil de auditar em escala, e a busca por fluxo é como você pega IDs órfãos em fluxos complexos.
Adicione Custom Brand Icons cedo em vez de tarde. Configurar os padrões antes de uma renomeação significa que o painel de controle se torna uma ferramenta de detecção de mudança, não apenas um display.
O Automation Editor está sempre disponível e vale a pena usar para edições de arquivo único. Não é uma substituição para o diálogo de renomeação principal quando uma mudança toca múltiplas automações, mas é o caminho mais rápido para a limpeza diária.
Perguntas frequentes
Renomear uma entidade no Home Assistant atualiza automaticamente cada automação que a usa?
Desde a versão 2023.4, o diálogo de renomeação de ID de entidade busca automações, scripts, cenas, painéis de controle e planos para referências e oferece atualizá-los em uma única passagem. Ele mostra uma prévia primeiro. Não pode ver referências dentro de integrações personalizadas que armazenam IDs em seus próprios arquivos ou dentro de fluxos Node-RED, então uma busca de segunda passagem no Studio Code Server ainda vale a pena executar após cada renomeação.
Qual é a diferença entre o nome amigável e o ID da entidade?
O ID da entidade (light.living_room_lamp) é a chave de máquina que automações, scripts e modelos usam para endereçar a entidade. O nome amigável (“Living room lamp”) é o rótulo que aparece em painéis de controle, assistentes de voz e notificações. Altere o nome amigável livremente; o ID da entidade permanece estável e nenhuma automação quebra. Altere o ID da entidade apenas através do diálogo de renomeação para que as referências sejam atualizadas.
Os dispositivos devem ser renomeados da UI de integração ou das configurações de entidade?
Renomeie o dispositivo da UI de integração (ZHA, Z-Wave JS, ESPHome, etc.) quando o objetivo é alterar cada entidade que esse dispositivo expõe de uma vez. Renomeie a entidade individual quando apenas uma das entidades do dispositivo precisa de um ID diferente. Ambos os fluxos agora disparam a mesma prévia de atualizar-referências, então a rede de segurança é a mesma de qualquer forma.
Como você audita uma configuração do Home Assistant para typos de ID de entidade antes de causarem interrupções?
Studio Code Server com a extensão Home Assistant é a auditoria mais rápida. Abra uma busca em todo o projeto para entity_id: e verifique tudo que não auto-completa contra o registro em tempo real. Para uma verificação com script, hassio ha check (o equivalente CLI do validador de configuração integrado) sinalizará referências a entidades que não existem, e um git diff após cada mudança torna a revisão um hábito de um comando.
É seguro renomear entidades em uma instância do Home Assistant em produção?
Mais seguro do que era, se a renomeação passar pelo diálogo de configurações de entidade ou aviso do editor de automação vinculado. Faça um backup primeiro da UI, faça a renomeação durante uma janela tranquila e recarregue a integração afetada ou reinicie o Home Assistant após a mudança. Se algo parecer errado, o repositório git que o resto desta pilha o encoraja a manter é a forma mais rápida de voltar ao estado anterior.
