Pular para o conteúdo principal

Home Assistant Add-on

Instalação para rodar o Toposync dentro do Home Assistant.

Para Quem É​

Use este caminho quando quiser:

  • Toposync na sidebar do Home Assistant;
  • UI e API via ingress;
  • execução supervisionada;
  • acesso automático ao Home Assistant Core API;
  • integração com câmeras e entidades do Home Assistant.

O add-on é CPU-only.

Para suporte por arquitetura, HAOS e Raspberry Pi, consulte Compatibilidade.

Pré-requisitos​

  • Home Assistant OS ou ambiente com Supervisor.
  • Usuário administrador no Home Assistant.
  • Acesso ao Add-on Store.

Instalação​

No Home Assistant:

  1. Abra Settings.
  2. Abra Add-ons.
  3. Abra Add-on Store.
  4. Abra o menu de repositórios.
  5. Adicione:
https://github.com/toposync/toposync-homeassistant-addon

Depois:

  1. Abra o add-on Toposync.
  2. Clique em Install.
  3. Clique em Start.
  4. Ative Start on boot, se quiser iniciar junto com o Home Assistant.
  5. Abra Toposync pela sidebar.

Como Rodar​

O Supervisor executa o add-on.

Use a tela do add-on para:

  • iniciar;
  • parar;
  • reiniciar;
  • ver logs;
  • atualizar.

Como Acessar​

Pela Sidebar​

Abra Toposync na sidebar do Home Assistant.

Esse é o caminho padrão. A UI e a API passam pelo ingress do Home Assistant.

Pela Rede Local​

Por padrão, o acesso direto fica desabilitado.

Para habilitar acesso direto para navegador ou app móvel, abra a seção Network do add-on e mapeie:

18756/tcp: 18756

Depois acesse:

http://homeassistant.local:18756/

ou:

http://<ip-do-home-assistant>:18756/

O acesso direto usa autenticação local do Toposync. A criação inicial de usuário local não aparece no primeiro acesso direto em modo híbrido; crie usuários locais por dentro do Toposync acessando pela sidebar.

Como Verificar​

Pela sidebar:

  • a tela inicial do Toposync deve abrir;
  • Settings deve carregar;
  • extensões de Home Assistant e câmeras devem aparecer quando instaladas.

Pela porta direta, se habilitada:

curl http://<ip-do-home-assistant>:18756/api/health

O esperado é resposta 200.

Streaming Opcional​

O HLS para web/app usa a porta direta do Toposync quando ela está mapeada:

18756/tcp

Para RTSP ou WebRTC/WHEP na rede local, mapeie somente o que for usar:

18758/tcp: 18758  # RTSP
18760/tcp: 18760  # WebRTC/WHEP signaling
18762/udp: 18762  # WebRTC media transport

Notas:

  • 18757 é a porta interna de ingress/backend.
  • 18759 é HLS direto interno/diagnóstico e não faz parte do contrato público padrão.
  • 18761 é API interna do MediaMTX e não deve ser publicada por padrão.

Como Atualizar​

No Home Assistant:

  1. Abra Settings.
  2. Abra Add-ons.
  3. Abra Toposync.
  4. Clique em Update, quando disponível.
  5. Reinicie o add-on depois da atualização.

Se a atualização não aparecer, abra o menu do Add-on Store e recarregue os repositórios.

Como Desinstalar​

No Home Assistant:

  1. Abra Settings.
  2. Abra Add-ons.
  3. Abra Toposync.
  4. Pare o add-on.
  5. Clique em Uninstall.

Os dados do Toposync ficam em /data dentro do container do add-on, gerenciado pelo Supervisor.

Troubleshooting​

O add-on não aparece​

Confira se o repositório foi adicionado exatamente assim:

https://github.com/toposync/toposync-homeassistant-addon

Depois recarregue o Add-on Store.

Falha ao construir ou atualizar​

Abra os logs do Supervisor e os logs do add-on. O erro normalmente aparece no build da imagem ou no pip install dentro do add-on.

A porta direta recusa conexão​

Confirme se 18756/tcp foi mapeada na seção Network do add-on. Declarar a porta no add-on não publica automaticamente a porta no host.

Streaming não abre fora da sidebar​

Comece com HLS pela porta 18756/tcp. Só habilite RTSP ou WebRTC se precisar desses protocolos.

Raspberry Pi está lento​

Para cargas com múltiplas câmeras, OpenCV pesado ou vision em CPU, use um processing server remoto. Consulte Compatibilidade para a recomendação de hardware.