Integração local para os módulos cabeados da ControlArt, configurados pelo mdConfig: o relé (10 saídas a relé, 12 entradas digitais) e o dimmer (canais com nível de 0 a 255, 12 entradas digitais). Fala direto com cada módulo por TCP na rede local: sem nuvem, sem Node-RED, sem outro Home Assistant no meio.
English summary below.
Cada módulo vira um dispositivo com:
| Entidade | Quantas | Para quê |
|---|---|---|
light |
10 no relé, uma por canal no dimmer | As saídas. Liga e desliga (com brilho, no dimmer), e o estado vem sempre do módulo |
event |
uma por tecla de keypad | Dispara um evento a cada toque, para usar em automações |
binary_sensor |
uma por entrada de interruptor | A posição da alavanca (diagnóstico, desligada por padrão) |
binary_sensor |
1 | Se o módulo está respondendo |
sensor |
1 | O endereço IP do módulo (diagnóstico), visível mesmo com ele fora do ar |
button |
2 | "Acender tudo" e "Apagar tudo": o módulo inteiro com um comando só |
O card do dispositivo mostra o firmware e o MAC inteiro, como o mdConfig e a etiqueta da caixa (por exemplo 3.027 e 00:60:37:aa:bb:cc). O módulo só informa os três últimos bytes do MAC; os três primeiros, 00-60-37, são iguais em todo módulo ControlArt.
A página da integração também oferece Baixar diagnóstico: as últimas linhas trocadas com cada módulo, o firmware e o MAC que ele informa, e quantas vezes a conexão caiu. Serve para suporte a distância, sem terminal na rede da instalação.
Os interruptores e keypads da parede continuam funcionando como sempre: quem aciona as saídas é o módulo. O Home Assistant enxerga tudo o que acontece e manda comandos junto, sem um cancelar o outro.
O botão abre este repositório direto no Marketplace, que vem dentro do Home Assistant desde o 2026.11, em Configurações → Marketplace (ele substituiu o HACS; num Home Assistant mais antigo, o mesmo botão abre o HACS, onde o botão é Baixar). Clique em Instalar e reinicie o Home Assistant.
Ele funciona pelo my.home-assistant.io, que só sabe chegar na sua instância depois que você informa o endereço dela uma vez, em Configurações → Sistema → Rede → URL do Home Assistant. Até lá, ele pergunta.
Fazendo à mão
- Configurações → Marketplace e procure ControlArt: ela está no catálogo, não há link a adicionar.
- Abra o repositório e clique em Instalar.
- Reinicie o Home Assistant.
Num Home Assistant anterior ao 2026.11: HACS → menu ⋮ → Repositórios personalizados, URL https://github.com/self-labs/controlart, categoria Integração → Adicionar, depois Baixar e reinicie.
Copie a pasta custom_components/controlart para dentro de config/custom_components/ e reinicie.
O botão abre o cadastro direto. Sem ele: Configurações → Dispositivos e serviços → Adicionar integração → ControlArt.
- A integração procura os módulos na rede do Home Assistant: tenta a porta 4998 em cada endereço e pergunta a quem atender. Leva alguns segundos.
- Escolher um módulo encontrado na rede: cada um aparece com o tipo e o IP em que respondeu, como
Relé - 192.168.1.22. As saídas o módulo já informou, e o MAC inteiro fica no card do dispositivo depois do cadastro. - Dê um nome e marque quais entradas são teclas de keypad (pulsadores). As demais são tratadas como interruptores comuns.
Se nenhum módulo responder, ou se você escolher Informar o IP, o cadastro pede o IP e a porta (4998, salvo se você mudou no mdConfig). Um aparelho com MAC 00:60:37 que a busca viu na rede mas que não respondeu já vem preenchido.
Cada busca deixa uma linha em Configurações → Sistema → Logs (procure por ControlArt: busca): quantos endereços percorreu, os módulos que achou, os aparelhos 00:60:37 que viu na rede e quem atendeu sem responder como módulo. É o primeiro lugar a olhar quando um módulo não aparece.
Na integração, Configurar → Procurar módulos na rede faz a mesma busca do cadastro e lista os módulos que ainda não estão cadastrados. Adicionar pelo IP continua lá, para um módulo em outra porta ou outra rede.
Configurar → Busca automática liga a busca ao iniciar e a cada hora. Vem desligada: a integração só percorre a rede quando você pede. Ligada, cada módulo que a busca achar e que ainda não estiver cadastrado aparece em Dispositivos e serviços como Descoberto, um card por módulo com o tipo e o IP (Dimmer - 192.168.1.23): Configurar, nome e teclas. O formulário do card mostra o MAC inteiro, para conferir com a etiqueta. Ignorar num card vale só para aquele módulo. Ligue quando o Home Assistant não mostrar os cards sozinho (abaixo): num roteador Deco, por exemplo, o navegador DHCP do HA não listou nenhum módulo.
O Home Assistant também mostra o card sozinho, sem nenhuma busca, quando fica sabendo do MAC do módulo: o manifest pede ao HA os aparelhos com o início de MAC 00-60-37. Isso acontece de dois jeitos:
- Com a integração UniFi Network no Home Assistant, numa rede UniFi: ela informa ao HA o IP e o MAC de cada aparelho da rede a cada início, e o card de cada módulo aparece logo depois de instalar o ControlArt e reiniciar. É o caminho para não precisar apertar nada.
- Quando o módulo pede IP ao roteador, ao ligar, se estiver com DHCP no mdConfig.
Esse início de MAC é do fabricante do chip e outro aparelho pode ter, por isso a integração pergunta na porta 4998 antes de mostrar o card.
O nome das saídas começa como "Saída 1", "Saída 2"… Renomeie no próprio Home Assistant e ponha cada uma na sua área; a integração não mexe no que você ajustou.
Um IP fixo para cada módulo (reserva no roteador ou IP estático no mdConfig) continua recomendado. Se o IP de um módulo cadastrado mudar, ele fica indisponível até o cadastro ser corrigido: sozinho, quando o Home Assistant vê o módulo pedir o IP novo ou, com a Busca automática ligada, na próxima busca; à mão, em Configurar → Editar um módulo.
- Tecla de keypad numa automação: use o gatilho de estado na entidade
event. Cada toque muda o estado para o horário do toque. Filtrenot_to: [unknown, unavailable]para não disparar quando o Home Assistant reinicia. Dois toques seguidos na mesma tecla precisam de pouco mais de 1 s entre eles para virar dois eventos. - Interruptor comum numa automação: a posição da alavanca não diz se a luz está acesa. O módulo inverte a saída a cada movimento, então as duas coisas se desencontram. Dispare em qualquer mudança do sensor da entrada e use
toggle. - Cenas do keypad: o módulo executa a cena programada no mdConfig quando a tecla é apertada na parede. Não existe comando para disparar essa cena remotamente. Para acioná-la pelo Home Assistant, reproduza-a num script.
- Dimmer aceso sem brilho escolhido (botão, voz, "acender a sala"): o canal volta ao último nível em que ficou aceso desde que o Home Assistant iniciou; se nunca acendeu, vai ao máximo. Os degraus de uma transição não contam: apagar devagar e acender de novo volta ao nível de antes.
- Transição no dimmer (
transitionemlight.turn_onelight.turn_off): a integração faz a rampa, um nível de cada vez, com pelo menos 0,2 s entre os degraus. O serviço volta na hora; um comando novo no mesmo canal cancela a rampa. - Comando que o módulo não confirma vira erro no Home Assistant em vez de passar em silêncio. Um módulo que para de responder derruba a conexão e as entidades ficam indisponíveis até ele voltar.
- Script que acende várias luzes em sequência: ponha
continue_on_error: truenas ações de luz. Sem isso, um comando não confirmado interrompe o resto do script.
- Motores e cortinas configurados no módulo são ignorados: o comando de motor não é conhecido. As linhas de configuração de motor que o módulo manda aparecem no diagnóstico.
- A integração não altera a programação do módulo; isso continua sendo feito no mdConfig.
- A busca só percorre as redes marcadas em Configurações → Sistema → Rede, de 254 a 1024 endereços por rede (numa rede maior, ou com máscara menor que /24, como um IP fixo gravado com /32, só os 254 vizinhos do Home Assistant), e só na porta 4998. Um Home Assistant em Docker precisa de
network_mode: hostpara enxergar a rede da casa. Módulo em outra VLAN ou em outra porta entra pelo IP. - O número de série da caixa não aparece no card: nenhum comando conhecido do módulo devolve o serial.
O protocolo, com as armadilhas que apareceram pelo caminho, está descrito em docs/protocolo.md.
Os testes rodam sem o Home Assistant instalado, só com a biblioteca padrão: python -m unittest discover -s tests.
As versões seguem o calendário (AAAA.M.R: ano, mês e a revisão dentro do mês), não o versionamento semântico. O que mudou em cada uma está no CHANGELOG.md. O Marketplace oferece cada versão nova como atualização, em Configurações → Atualizações.
Inspirado na integração tompsonpecini/controlart, de Tompson Pecini, de onde este projeto partiu (licença MIT, mantida em LICENSE). Os comandos de firmware, MAC e "tudo aceso/apagado" vieram do driver Hubitat hhorigian/hubitat_Controlart_Relays.
O ícone e o logo da integração são a marca da ControlArt, tirados do site dela, e servem só para identificar o fabricante dos módulos. Este projeto não é da ControlArt nem tem o apoio dela.
Local-push Home Assistant integration for ControlArt wired modules: the relay module (10 relay outputs, 12 digital inputs) and the dimmer module (channels with a 0 to 255 level, 12 digital inputs). Each module becomes a device with one light entity per output (with brightness on the dimmer), one event entity per keypad push button, one diagnostic binary_sensor per switch input, a connectivity sensor, a diagnostic IP sensor, and "All on" / "All off" buttons for the whole module. The device card shows the module firmware and its full MAC, and Download diagnostics returns the last lines exchanged with each module. Setup searches the Home Assistant network for modules on port 4998 and lists the ones that answer, so only a name and the keypad inputs are asked. Configure → Search the network for modules runs the same search on demand. The network is only searched when you ask: an optional Automatic search (Configure, off by default) repeats it at startup and every hour, so new modules show up as discovered cards and a configured module whose IP changed is followed, for networks where Home Assistant's DHCP discovery does not see the modules. Home Assistant's own DHCP discovery (MAC prefix 00:60:37) also shows a card when a module requests an address at power-up. Modules on another port or network are added by IP. Wall switches and keypads keep working through the module itself; Home Assistant follows every change and can switch outputs alongside them.
Install with the button above, which opens the Marketplace (Settings → Marketplace, search ControlArt; on Home Assistant older than 2026.11 it opens HACS, where you add https://github.com/self-labs/controlart as a custom repository, type Integration), restart, then use the setup button to pick the first module from the search. Versions are CalVer (YYYY.M.R), listed in CHANGELOG.md.
Inspired by tompsonpecini/controlart by Tompson Pecini, where this project started (MIT).
Not affiliated with ControlArt. Use at your own risk.