Como renomear entidades LocalTuya no Home Assistant depois de reinstalar tudo (sem surtar)

Essa semana eu estava fazendo uns testes no Home Assistant e por uma besteira acabei reiniciando, sem validar a estrutura dos arquuivos modificados. Percebi que o Home Assistant não voltava, tentei restaurar arquivos que eu tinha, tentei restaurar inclusive backup, mas nada resolveu. Tive que reinstalar do zero.

E se você usa LocalTuya e já precisou reinstalar o Home Assistant, você sabe exatamente do que eu tô falando. Tudo volta a funcionar, mas os nomes… meu amigo… os nomes viram um inferno.

De repente sua casa inteira vira isso aqui:

switch.local_71706185e868e755df28_1
switch.local_22230844e868e7828084_1
light.local_eb0siq_1

Antes estava tudo organizado, com nomes decentes, automações legíveis, Lovelace bonito. Depois da reinstalação, parece que alguém jogou os entity_ids no liquidificador.

A primeira reação é pensar: “ok, vou renomear na mão”. A segunda reação, depois de uns 10 dispositivos, é desistir da vida.

Foi aí que resolvi fazer do jeito certo.

Não é o caminho mais simples, mas é o caminho que funciona e que você só precisa fazer uma vez.

A real do problema (sem teoria demais)

No Home Assistant existem duas coisas diferentes que muita gente mistura:

• entity_id é o identificador técnico
• friendly_name é só o nome bonitinho da interface

Mudar friendly_name é fácil. Mudar entity_id não é.

Quem manda nos entity_ids é o Entity Registry, aquele arquivo escondido em .storage/core.entity_registry. Se você não mexer ali, o Home Assistant sempre vai preferir aqueles nomes feios do LocalTuya.

E sim: customize.yaml não resolve isso sozinho. Ele ajuda, mas não conserta a raiz do problema.

O caminho que resolveu pra mim

A ideia foi simples:

• usar o ui-lovelace.yaml como fonte da verdade
• se o entity_id está no Lovelace, ele é o nome correto
• todo o resto precisa se adaptar a isso

Então eu fiz um script Python que faz basicamente três coisas:

• lê o ui-lovelace.yaml
• abre o core.entity_registry
• atualiza entity_id e name das entidades LocalTuya de uma vez só

Sem interface, sem clicar em 80 telas, sem dor.

Antes de tudo: pare o Home Assistant e faça backup

Não pula essa parte. Sério.

ha core stop

ou se for Docker:

docker stop homeassistant

Backup:

cp /config/.storage/core.entity_registry /config/.storage/core.entity_registry.backup

Agora sim da pra mexer.

O script que resolve a vida

Esse é o script principal que eu uso. Não é bonito, não é genérico, mas funciona. E funciona bem.

import json
import yaml
import re

ENTITY_REGISTRY_PATH = ".storage/core.entity_registry"
LOVELACE_PATH = "ui-lovelace.yaml"

def carregar_entity_ids_desejados():
    with open(LOVELACE_PATH, "r") as f:
        content = yaml.safe_load(f)

    encontrados = set()
    texto = json.dumps(content)

    for match in re.findall(r"(switch|light)\.[a-zA-Z0-9_]+", texto):
        encontrados.add(match)

    return sorted(encontrados)

def gerar_friendly_name(entity_id):
    nome = entity_id.split(".", 1)[1]
    nome = nome.replace("_", " ").title()
    return nome

with open(ENTITY_REGISTRY_PATH, "r") as f:
    registry = json.load(f)

entity_ids_desejados = carregar_entity_ids_desejados()

print(f"Encontrados {len(entity_ids_desejados)} entity_ids no Lovelace")

for entity in registry["data"]["entities"]:
    unique_id = entity.get("unique_id", "")
    if not unique_id.startswith("local_"):
        continue

    for desejado in entity_ids_desejados:
        dominio = desejado.split(".")[0]
        if entity["entity_id"].startswith(dominio):
            print(f"Atualizando {entity['entity_id']} -> {desejado}")
            entity["entity_id"] = desejado
            entity["name"] = gerar_friendly_name(desejado)
            entity_ids_desejados.remove(desejado)
            break

with open(ENTITY_REGISTRY_PATH, "w") as f:
    json.dump(registry, f, indent=2)

print("Entity Registry atualizado com sucesso")

O que esse script faz, em português claro:

• ele varre o Lovelace e descobre quais entity_ids você realmente usa
• ele percorre o Entity Registry atrás das entidades LocalTuya
• quando encontra uma do mesmo domínio (switch ou light), troca o entity_id
• já aproveita e seta o name com um friendly name decente
• salva tudo de volta no registry

Nada mágico. Só direto.

“Mas como ele sabe qual switch é qual?”

Ele não sabe 100%. E isso é importante entender.

Esse script assume que você já organizou seu Lovelace de forma lógica. Se tiver coisa muito fora do padrão, você ajusta depois. Ainda assim é muito melhor do que começar do zero e ter que ficar alterando via UI.

Depois disso, eu ainda gero um customize.yaml

Não é obrigatório, mas eu gosto de deixar.

with open("customize.yaml", "w") as f:
    for eid in entity_ids_desejados:
        f.write(f"{eid}:\n")
        f.write(f"  friendly_name: \"{gerar_friendly_name(eid)}\"\n\n")

É só uma camada extra de segurança.

Hora de subir tudo de novo

ha core start

ou Docker:

docker start homeassistant

Primeira subida pode demorar um pouco mais. Normal.

Quando abre a interface… tudo volta ao normal. entity_id certo, nome certo, automações funcionando, Lovelace inteiro.

Algumas coisas que aprendi apanhando

• entity_id não é detalhe estético
• Entity Registry é sagrado
• customize.yaml ajuda, mas não faz milagre
• backup antes de qualquer coisa
• script feio que funciona é melhor que solução perfeita que nunca acaba

Hoje eu guardo esses scripts como parte do config do meu Home Assistant. Se amanhã eu precisar reinstalar tudo de novo, em 5 minutos minha casa volta a falar português, não hexadecimal.

Se você chegou até aqui, provavelmente já passou raiva com isso também. Espero que te poupe algumas horas (ou alguns palavrões).

Se um dia eu esquecer como fiz, esse post também é pra mim mesmo.