Intelbras Guardian API + Integração Home Assistant

Integração completa para controlar sistemas de alarme Intelbras Guardian via Home Assistant.

Opções de Instalação

Opção 1: Add-on do Home Assistant (Recomendado para usuários do Supervisor)

Se você usa Home Assistant OS ou Supervised, pode instalar a API como add-on:

1. Clique no botão acima ou adicione o repositório manualmente:

   • Configurações → Add-ons → Loja de Add-ons → ⋮ (canto superior direito) → Repositórios
   • Adicione: https://github.com/bobaoapae/guardian-api-intelbras

2. Encontre "Intelbras Guardian API" na loja de add-ons e clique em Instalar

3. Inicie o add-on e acesse a Web UI em http://[SEU_IP_HA]:8000

4. Instale a integração do Home Assistant (veja abaixo)

Opção 2: Script de Instalação Automática (Recomendado para Docker)

Para usuários de Docker ou Home Assistant Container, use o script de instalação interativo:

# Baixar e executar o instalador
curl -sSL https://raw.githubusercontent.com/bobaoapae/guardian-api-intelbras/main/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh

O script irá:

• Verificar pré-requisitos (Docker, Docker Compose)
• Detectar automaticamente seu Home Assistant
• Configurar diretórios e volumes
• Instalar a API e integração do HA
• Iniciar os serviços

Outras opções do script:

./install.sh --help       # Ver todas as opções
./install.sh -y           # Instalação não-interativa (aceita padrões)
./install.sh --update     # Atualizar instalação existente
./install.sh --uninstall  # Remover completamente

Opção 3: Docker Compose Manual

Para instalação manual via Docker, veja Instalação via Docker abaixo.

Opção 4: Python Manual

Para desenvolvimento ou configurações personalizadas, veja a seção Desenvolvimento.

---

Arquitetura

Este projeto implementa uma arquitetura em 3 camadas:

┌─────────────────────────────────────────────────────────────────┐
│                  HOME ASSISTANT (Integração HACS)               │
│                                                                 │
│  - Config Flow (host:porta manual)                              │
│  - Coordinator (polling 1s ISECNet, ~30s Cloud API)             │
│  - SSE listener para eventos em tempo real                      │
│  - Entidades:                                                   │
│    - alarm_control_panel (por partição + alarme unificado)      │
│    - binary_sensor (zonas + bateria de sensores wireless)       │
│    - sensor (último evento + sinal wireless)                    │
│    - switch (choque/alarme do eletrificador)                    │
│    - button (desligar sirene)                                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP REST + SSE
┌───────────────────────────▼─────────────────────────────────────┐
│                  FASTAPI MIDDLEWARE (Container)                 │
│                                                                 │
│  - Autenticação OAuth 2.0 com Intelbras Cloud                   │
│  - Refresh automático de token                                  │
│  - Protocolo ISECNet (comunicação direta com a central)         │
│  - Connection pooling com keep-alive (idle timeout 5min)        │
│  - Reconexão automática em falha de conexão                     │
│  - Cache e gerenciamento de estado persistente                  │
│  - Detecção de indisponibilidade (connection_unavailable)       │
│  - Gerenciamento de nomes amigáveis das zonas                   │
│  - Armazenamento de senha do dispositivo para auto-sync         │
│  - Web UI para testes e gerenciamento                           │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTPS + ISECNet (TCP)
┌───────────────────────────▼─────────────────────────────────────┐
│  INFRAESTRUTURA INTELBRAS                                       │
│                                                                 │
│  ┌─────────────────────┐    ┌─────────────────────────────────┐│
│  │  API Cloud          │    │  Servidores ISECNet             ││
│  │  api-guardian...    │    │  V2: amt8000:9009/80            ││
│  │  :8443              │    │  V1: amt:9015                   ││
│  └──────────┬──────────┘    └─────────────┬───────────────────┘│
│             │                             │                     │
│             └──────────────┬──────────────┘                     │
│                            │                                    │
│  ┌─────────────────────────▼───────────────────────────────────┐│
│  │            CENTRAL DE ALARME (AMT, ANM, etc)                ││
│  │                                                             ││
│  │  - Partições (áreas que podem ser armadas independentemente)││
│  │  - Zonas (sensores: portas, janelas, movimento, etc)        ││
│  │  - Sensores wireless (bateria, sinal, tamper)               ││
│  │  - Protocolo ISECNet V1/V2 para comunicação                 ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Como Funciona

Fluxo de Comunicação

1. Autenticação: Usuário faz login com credenciais da conta Intelbras. FastAPI obtém tokens OAuth 2.0 do Intelbras Cloud.

2. Descoberta de Dispositivos: FastAPI consulta a API do Intelbras Cloud para listar centrais de alarme registradas com suas partições e zonas.

3. Status em Tempo Real (Protocolo ISECNet):

   • FastAPI conecta aos servidores ISECNet da Intelbras (Cloud V2/V1 ou IP Receiver)
   • Mantém conexão TCP persistente com connection pooling (idle timeout 5min)
   • Polling a cada 1s para status em tempo real: armado/desarmado, zonas, alarmes
   • Reconexão automática em caso de falha de conexão
   • Quando a conexão cai, retorna último estado conhecido com flag connection_unavailable
   • Entidades no HA ficam "Indisponível" até a conexão ser restabelecida

4. Comandos de Armar/Desarmar:

   • Home Assistant envia comando para FastAPI
   • FastAPI envia comando ISECNet via conexão persistente para a central
   • Central executa o comando e retorna resultado
   • Status é atualizado imediatamente (estado otimista + confirmação)

5. Monitoramento de Zonas:

   • ISECNet fornece status em tempo real das zonas (aberta/fechada)
   • Painéis smart (AMT 2018 E SMART): bateria, sinal e tamper de sensores wireless
   • Nomes amigáveis podem ser atribuídos às zonas via FastAPI
   • Sensores binários no Home Assistant refletem o estado das zonas

6. Eventos em Tempo Real (SSE):

   • Listener SSE para receber eventos do alarme instantaneamente
   • Eventos disparados como intelbras_guardian_alarm_event no HA
   • Permite automações reativas (ex: notificar ao disparar alarme)

Protocolo ISECNet

ISECNet é o protocolo proprietário da Intelbras para comunicação direta com centrais de alarme:

• Versão 2 (V2): Servidor amt8000.intelbras.com.br portas 9009/80 - recursos estendidos
• Versão 1 (V1): Servidor amt.intelbras.com.br porta 9015 - fallback para painéis legados
• IP Receiver: Conexão direta via receptor IP local (alternativa ao cloud)

O protocolo usa:

• Conexão TCP persistente com connection pooling por dispositivo
• Fallback automático V2 → V1 com cache de protocolo por dispositivo
• Reconexão automática quando a conexão é perdida
• Formato de pacote binário com validação CRC
• Autenticação baseada em senha por dispositivo
• Criptografia XOR para dados sensíveis

Dispositivos Suportados

Modelo	Protocolo	Partições	Notas
AMT 8000 / Lite / Pro	V2 Cloud	16
AMT 9000	V2 Cloud	8
AMT 2018 E SMART	V1 Cloud / IP Receiver	2	Sensores wireless (bateria, sinal, tamper)
AMT 1000 SMART	V1 Cloud / IP Receiver	0	Sensores wireless
AMT 2018 E EG / E3G	V1 Cloud / IP Receiver	2
AMT 2016 E3G	V1 Cloud / IP Receiver	2
AMT 2118 EG	V1 Cloud / IP Receiver	2
AMT 4010 Smart	V1 Cloud / IP Receiver	4
AMT 1016 NET	V1 Cloud / IP Receiver	4
ANM 24 NET / G2	V1 Cloud / IP Receiver	0
ELC 6012 NET / IND	V2 Cloud	—	Eletrificador (choque + alarme)

Funcionalidades

Painel de Controle de Alarme

• Armar/desarmar partições individuais ou via alarme unificado
• Modos de arme: Ausente (total) e Em Casa (stay/perímetro)
• Alarme unificado com mapeamento configurável de partições por modo (Home/Away)
• Detecção de estado disparado (com timeout automático de 10 min para estados stale)
• Status em tempo real via ISECNet (polling 1s)
• Estado otimista para feedback imediato na UI
• Detecção de indisponibilidade: entidades ficam "Unavailable" quando a conexão com a central cai

Sensores de Zona (Sensores Binários)

• Status em tempo real aberto/fechado
• Nomes amigáveis personalizáveis
• Classe de dispositivo baseada no tipo de zona (porta, janela, movimento, fumaça, etc.)
• Atributo de status de bypass
• Sensores wireless (painéis smart): bateria baixa (binary_sensor)

Sensores Wireless (Painéis Smart)

• Sinal wireless: intensidade do sinal (0-10) por zona wireless
• Bateria baixa: alerta quando bateria do sensor está fraca
• Tamper: detecção de violação do sensor
• Sensores adicionados dinamicamente quando painel smart é detectado

Controle de Eletrificador (Switches)

• Switch de Choque: Habilitar/desabilitar choque elétrico
• Switch de Alarme: Armar/desarmar alarme da cerca

Bypass de Zonas Abertas + Notificação Actionable

• Ao tentar armar com zonas abertas, envia notificação no celular (mobile_app)
• Botão "Ignorar Zonas e Armar" na notificação para bypass automático + re-arme
• Bypass via protocolo ISECNet (V1: bitmask de todas as zonas, V2: por zona individual)
• Contexto expira em 5 minutos (tenta armar direto sem bypass se expirado)
• Notificação dismissada automaticamente após arme bem-sucedido
• persistent_notification como fallback quando não há mobile_app

Botão Desligar Sirene

• Desliga a sirene da central sem alterar o estado de arme

Sensor de Evento

• Informação do último evento
• Atributos do histórico de eventos
• Eventos em tempo real via SSE (Server-Sent Events)

Início Rápido

Pré-requisitos

• Docker e Docker Compose
• Home Assistant 2023.x ou posterior
• Sistema de alarme Intelbras Guardian com acesso à nuvem
• Conta Intelbras (email + senha)
• Senha do dispositivo (programada na central de alarme)

1. Instalar Middleware FastAPI

# Clonar o repositório
git clone https://github.com/bobaoapae/guardian-api-intelbras.git
cd guardian-api-intelbras

# Configurar ambiente
cd intelbras-guardian-api
cp .env.example .env
# Edite .env e adicione a URL do seu Home Assistant em CORS_ORIGINS

# Iniciar o container
cd ../docker
docker-compose up -d

# Verificar se está rodando
curl http://localhost:8000/api/v1/health

2. Acessar Web UI

Abra http://localhost:8000 no navegador para:

• Testar login com suas credenciais Intelbras
• Ver dispositivos e seus status
• Salvar senhas dos dispositivos para auto-sync
• Configurar nomes amigáveis das zonas
• Testar comandos de armar/desarmar

3. Instalar Integração do Home Assistant

Opção A: Via HACS (Recomendado)

1. Abra o HACS no Home Assistant
2. Clique nos 3 pontos (canto superior direito) → Repositórios personalizados
3. Adicione a URL do repositório: https://github.com/bobaoapae/guardian-api-intelbras
4. Categoria: Integração
5. Clique em Adicionar → encontre "Intelbras Guardian" → Instalar
6. Reinicie o Home Assistant

Opção B: Via install.sh (Docker)

O script install.sh já copia a integração automaticamente para o diretório custom_components do HA.

Opção C: Cópia manual (Docker)

# Descobrir o caminho do volume de configuração do HA
docker inspect homeassistant --format '{{range .Mounts}}{{if eq .Destination "/config"}}{{.Source}}{{end}}{{end}}'

# Copiar integração
mkdir -p /home/usuario/homeassistant/custom_components
cp -r custom_components/intelbras_guardian \
      /home/usuario/homeassistant/custom_components/

# Reiniciar Home Assistant
docker restart homeassistant

Para Home Assistant OS/Supervised:

Use o Add-on (Opção 1) que já inclui a API integrada.

4. Configurar Integração

1. Vá em Configurações → Dispositivos e Serviços → Adicionar Integração
2. Procure por "Intelbras Guardian"
3. Preencha:
   • Email: Email da sua conta Intelbras
   • Senha: Senha da sua conta Intelbras
   • Host FastAPI: IP do container FastAPI (ex: 192.168.1.100)
   • Porta FastAPI: 8000 (padrão)

5. Salvar Senha do Dispositivo

Para status em tempo real via ISECNet:

Opção A - Via Home Assistant:

• Configurações → Dispositivos e Serviços → Intelbras Guardian → Configurar → Configurar Senha do Dispositivo

Opção B - Via Web UI:

1. Abra a Web UI do FastAPI (http://localhost:8000)
2. Faça login com suas credenciais Intelbras
3. Clique em "Salvar Senha" no seu dispositivo
4. Insira a senha do dispositivo (configurada na central de alarme)
5. O status agora sincronizará automaticamente

Endpoints da API

Autenticação

• POST /api/v1/auth/login - Login com credenciais Intelbras
• POST /api/v1/auth/logout - Logout e invalidar sessão
• GET /api/v1/auth/session - Obter informações da sessão atual

Dispositivos

• GET /api/v1/devices - Listar todas as centrais de alarme
• GET /api/v1/devices/{id} - Obter detalhes do dispositivo

Controle de Alarme

• POST /api/v1/alarm/{device_id}/arm - Armar partição
• POST /api/v1/alarm/{device_id}/disarm - Desarmar partição
• POST /api/v1/alarm/{device_id}/bypass-zone - Bypass (anular) zonas
• POST /api/v1/alarm/{device_id}/siren/off - Desligar sirene
• POST /api/v1/alarm/{device_id}/status - Obter status em tempo real (requer senha)
• GET /api/v1/alarm/{device_id}/status/auto - Obter status usando senha salva

Gerenciamento de Senha

• POST /api/v1/devices/{device_id}/password - Salvar senha do dispositivo
• DELETE /api/v1/devices/{device_id}/password - Excluir senha salva

Zonas

• GET /api/v1/devices/{device_id}/zones - Obter zonas com nomes amigáveis
• PUT /api/v1/devices/{device_id}/zones/{zone_index}/friendly-name - Definir nome amigável
• DELETE /api/v1/devices/{device_id}/zones/{zone_index}/friendly-name - Excluir nome amigável

Eventos

• GET /api/v1/events - Obter histórico de eventos do alarme
• GET /api/v1/events/recent - Eventos mais recentes
• GET /api/v1/events/stream - Stream SSE de eventos em tempo real

Eletrificador

• POST /api/v1/eletrificador/{device_id}/shock/on - Habilitar choque
• POST /api/v1/eletrificador/{device_id}/shock/off - Desabilitar choque
• POST /api/v1/eletrificador/{device_id}/alarm/activate - Armar alarme
• POST /api/v1/eletrificador/{device_id}/alarm/deactivate - Desarmar alarme

Estrutura do Projeto

guardian-api-intelbras/
├── intelbras-guardian-api/           # API FastAPI + Add-on HA
│   ├── app/                          # Código da aplicação
│   │   ├── main.py                   # Ponto de entrada da aplicação
│   │   ├── core/                     # Config, exceções, segurança
│   │   ├── models/                   # Modelos Pydantic
│   │   ├── services/                 # Lógica de negócio
│   │   │   ├── guardian_client.py    # Cliente da API Intelbras Cloud
│   │   │   ├── auth_service.py       # Autenticação OAuth 2.0
│   │   │   ├── state_manager.py      # Gerenciamento de estado/cache persistente
│   │   │   ├── isecnet_protocol.py   # Protocolo ISECNet V1/V2 (baixo nível)
│   │   │   └── isecnet_client.py     # Connection pooling, keep-alive, reconexão
│   │   ├── api/v1/                   # Endpoints REST
│   │   └── static/                   # Web UI
│   ├── tests/                        # Testes
│   ├── config.yaml                   # Configuração do add-on HA
│   ├── Dockerfile                    # Build da imagem (add-on)
│   ├── build.yaml                    # Build multi-arquitetura
│   ├── run.sh                        # Script de inicialização
│   └── requirements.txt              # Dependências Python
├── docker/                           # Docker Compose Standalone
│   ├── Dockerfile                    # Build da imagem (standalone)
│   └── docker-compose.yml
├── home_assistant/                   # Integração Home Assistant
│   └── custom_components/
│       └── intelbras_guardian/
│           ├── __init__.py
│           ├── manifest.json
│           ├── config_flow.py
│           ├── coordinator.py
│           ├── api_client.py
│           ├── alarm_control_panel.py  # Partições + alarme unificado
│           ├── binary_sensor.py       # Zonas + bateria wireless
│           ├── sensor.py              # Último evento + sinal wireless
│           ├── switch.py              # Choque/alarme eletrificador
│           ├── button.py              # Desligar sirene
│           └── const.py
└── docs/                             # Documentação

Variáveis de Ambiente

FastAPI (.env)

# API Intelbras (não alterar)
INTELBRAS_API_URL=https://api-guardian.intelbras.com.br:8443
INTELBRAS_OAUTH_URL=https://api.conta.intelbras.com/auth
INTELBRAS_CLIENT_ID=xHCEFEMoQnBcIHcw8ACqbU9aZaYa

# Servidor
HOST=0.0.0.0
PORT=8000
DEBUG=false
LOG_LEVEL=INFO

# CORS (adicione a URL do seu Home Assistant)
CORS_ORIGINS=http://localhost:8123,http://homeassistant.local:8123

# Timeouts
HTTP_TIMEOUT=30
TOKEN_REFRESH_BUFFER=300
EVENT_POLL_INTERVAL=30

Considerações de Segurança

• Credenciais: Nunca faça commit de arquivos .env com credenciais
• HTTPS: Use um proxy reverso com SSL em produção
• CORS: Restrinja CORS_ORIGINS apenas a domínios confiáveis
• Senhas de Dispositivo: Armazenadas em data/sessions.json (persistidas em disco para sobreviver a reinícios). Proteja o acesso a este arquivo
• Logs: Dados sensíveis (senhas, tokens) são automaticamente filtrados dos logs

Solução de Problemas

"Não foi possível conectar ao middleware FastAPI"

• Verifique se o container FastAPI está rodando: docker ps
• Verifique a configuração de host/porta
• Verifique regras de firewall

"Credenciais inválidas"

• Verifique seu email e senha da conta Intelbras
• Tente fazer login em https://guardian.intelbras.com.br

Armar/Desarmar não funciona

• Verifique se a senha do dispositivo está salva corretamente
• Verifique se o dispositivo está online no app Intelbras
• Verifique a conexão ISECNet nos logs do FastAPI

Entidades ficam "Indisponível" no Home Assistant

• A conexão ISECNet com a central foi perdida
• Verifique se o aplicativo AMT Mobile/AMT Remoto não está aberto (bloqueia a conexão ISECNet)
• A API tenta reconectar automaticamente a cada polling cycle (1s)
• Quando a conexão é restabelecida, as entidades voltam ao normal automaticamente

Zonas mostrando status errado

• Salve a senha do dispositivo para status em tempo real via ISECNet
• Verifique se as zonas estão configuradas corretamente na central de alarme

Alarme não aparece nos Controles de Dispositivos Android

Isso é uma limitação da plataforma Android, não da integração. O Android Device Controls suporta apenas domínios específicos do Home Assistant:

• camera, climate, cover, fan, humidifier, light, lock, media_player, remote, scene, script, switch, vacuum, water_heater

O domínio alarm_control_panel não é suportado pelo Android Device Controls.

Solução recomendada: Use template switches para controlar o alarme. Eles aparecem nos Controles de Dispositivos Android e mostram o estado atual:

# configuration.yaml
template:
  - switch:
      # Switch para modo "Em Casa" (arma apenas partições selecionadas)
      - name: "Alarme Em Casa"
        unique_id: alarme_switch_home
        state: "{{ is_state('alarm_control_panel.SEU_ALARME', 'armed_home') }}"
        turn_on:
          - service: alarm_control_panel.alarm_arm_home
            target:
              entity_id: alarm_control_panel.SEU_ALARME
        turn_off:
          - service: alarm_control_panel.alarm_disarm
            target:
              entity_id: alarm_control_panel.SEU_ALARME
        icon: >-
          {% if is_state('alarm_control_panel.SEU_ALARME', 'armed_home') %}
            mdi:shield-home
          {% else %}
            mdi:shield-home-outline
          {% endif %}

      # Switch para modo "Ausente" (arma todas as partições)
      - name: "Alarme Ausente"
        unique_id: alarme_switch_away
        state: "{{ is_state('alarm_control_panel.SEU_ALARME', 'armed_away') }}"
        turn_on:
          - service: alarm_control_panel.alarm_arm_away
            target:
              entity_id: alarm_control_panel.SEU_ALARME
        turn_off:
          - service: alarm_control_panel.alarm_disarm
            target:
              entity_id: alarm_control_panel.SEU_ALARME
        icon: >-
          {% if is_state('alarm_control_panel.SEU_ALARME', 'armed_away') %}
            mdi:shield-lock
          {% else %}
            mdi:shield-off
          {% endif %}

Nota: Substitua alarm_control_panel.SEU_ALARME pela entidade do seu alarme unificado (ex: alarm_control_panel.casa).

Se não tiver o alarme unificado configurado, use a entidade da partição individual (ex: alarm_control_panel.casa_particao_a).

Os switches criados aparecerão nos Controles de Dispositivos Android (app Companion) e permitem:

• Ver o estado atual do alarme
• Armar/desarmar com um toque
• Ícones diferentes para cada estado

Alternativa com scripts (apenas ações, sem mostrar estado):

# configuration.yaml ou scripts.yaml
script:
  armar_alarme_ausente:
    alias: "Armar Alarme (Ausente)"
    sequence:
      - service: alarm_control_panel.alarm_arm_away
        target:
          entity_id: alarm_control_panel.SEU_ALARME

  armar_alarme_em_casa:
    alias: "Armar Alarme (Em Casa)"
    sequence:
      - service: alarm_control_panel.alarm_arm_home
        target:
          entity_id: alarm_control_panel.SEU_ALARME

  desarmar_alarme:
    alias: "Desarmar Alarme"
    sequence:
      - service: alarm_control_panel.alarm_disarm
        target:
          entity_id: alarm_control_panel.SEU_ALARME

Desenvolvimento

Executar FastAPI localmente

cd intelbras-guardian-api
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Swagger UI

Acesse documentação interativa da API em: http://localhost:8000/docs

Roadmap

• Funcionalidade de bypass de zona (com notificação actionable no celular)
• Sensores wireless (bateria, sinal, tamper) para painéis smart
• Eletrificador: controle de choque e alarme independentes
• Alarme unificado (múltiplas partições em uma entidade)
• Desligar sirene sem desarmar
• Eventos em tempo real via SSE
• Reconexão automática e resiliência de conexão
• Controle de PGM (saída programável) — protocolo implementado, falta endpoint API
• Notificações push via Firebase Cloud Messaging
• Suporte a ISECNet local (sem relay da nuvem)
• Integração com Google Assistant / Alexa

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Teste com seu sistema de alarme Intelbras
2. Reporte issues com logs detalhados
3. Envie pull requests com melhorias

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

Aviso Legal

ESTE SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO.

• Este projeto NÃO É afiliado, endossado ou associado à Intelbras de nenhuma forma
• O uso deste software é inteiramente por sua conta e risco
• Os autores não são responsáveis por qualquer dano, perda ou problema de segurança que possa resultar do uso deste software
• Este software interage com sistemas de segurança - uso inadequado pode comprometer sua segurança
• Sempre certifique-se de que seu sistema de alarme está devidamente configurado e testado
• Não dependa exclusivamente desta integração para aplicações críticas de segurança

Ao usar este software, você reconhece que entende e aceita estes termos.

Suporte

• Issues: https://github.com/bobaoapae/guardian-api-intelbras/issues
• Documentação: Verifique a pasta /docs

---

Feito para a comunidade Home Assistant