UPnP/IGD (Roteador)

A integração UPnP/IGD usa o protocolo Internet Gateway Device sobre UPnP para coletar estatísticas do seu roteador: status da conexão WAN, IP público, bytes e pacotes enviados/recebidos, velocidade de download/upload e uptime da conexão. Baseia-se na mesma abordagem do componente upnp do Home Assistant e funciona com a grande maioria dos roteadores domésticos modernos que expõem UPnP ou NAT-PMP.

Roda apenas em um edge local (home). O protocolo SSDP (239.255.255.250:1900) é multicast UDP e as chamadas SOAP vão direto ao roteador na LAN — não funciona por VPN sem bridge multicast.

O UPnP/IGD precisa estar habilitado no seu roteador. Em marcas de consumo (TP-Link, D-Link, ASUS, Mikrotik, Intelbras, Huawei etc.) a opção costuma estar em Advanced → NAT Forwarding → UPnP, Network → UPnP ou Firewall → UPnP. Sem isso, nenhum dispositivo é detectado.

Configurar

Habilite UPnP no roteador

Entre na interface do seu roteador e ligue UPnP ou NAT-PMP. Em alguns firmwares a opção também aparece como “Media server” / “Serviço IGD”.

Adicione a integração

Vá em Configurações → Integrações → Adicionar → UPnP/IGD (Roteador) e selecione um edge local.

Escolha o roteador

O Portal faz um M-SEARCH SSDP (janela de ~3s) e lista todos os InternetGatewayDevice que responderam, com fabricante, modelo e um resumo do que cada um expõe:

WAN — status da conexão, IP externo, uptime da WAN.
Tráfego — contadores de bytes e pacotes RX/TX.

Selecione o seu e confirme.

Pronto

O Portal consulta o description.xml do roteador, derruba o conjunto certo de sensores (ignora o que o device não expõe) e começa a fazer polling a cada 30 segundos.

Se nenhum roteador for encontrado, o flow aborta com uma mensagem clara. Nesse caso, verifique:

Se o UPnP/IGD está mesmo habilitado no roteador (ver aviso acima).
Se o edge está na mesma LAN do roteador (não atrás de outro NAT, VLAN diferente, ou dentro de um container sem rede host).
Se o firewall do edge não está bloqueando saída UDP para 239.255.255.250:1900.

Entidades

As entidades geradas dependem do que o seu roteador anuncia. A relação completa possível:

Com `WANIPConnection` ou `WANPPPConnection`

Entidade	Plataforma	Descrição
`<nome> WAN Status`	`sensor`	Estado textual da WAN: `Connected`, `Disconnected`, `Connecting`, `Unknown`.
`<nome> WAN Connected`	`binary_sensor`	`on` se `WAN Status == Connected`. `device_class: connectivity`. Ideal para automações do tipo “notificar quando a internet cair”.
`<nome> IP Externo`	`sensor`	IP público reportado pelo roteador.
`<nome> WAN Uptime`	`sensor`	Tempo desde o último handshake da WAN, em segundos (`device_class: duration`).

Com `WANCommonInterfaceConfig`

Entidade	Plataforma	Descrição
`<nome> Bytes Recebidos`	`sensor`	Total RX corrigido para rollover (unsigned 32-bit soma 2^32 quando o contador decresce). `state_class: total_increasing`. Atributo `raw` guarda o valor cru.
`<nome> Bytes Enviados`	`sensor`	Total TX idem.
`<nome> Pacotes Recebidos`	`sensor`	Total de pacotes RX corrigido para rollover.
`<nome> Pacotes Enviados`	`sensor`	Total de pacotes TX idem.
`<nome> Velocidade Download`	`sensor`	Taxa calculada entre polls, em KiB/s. `device_class: data_rate`.
`<nome> Velocidade Upload`	`sensor`	Idem para TX.
`<nome> Pacotes Download/s`	`sensor`	Pacotes RX por segundo.
`<nome> Pacotes Upload/s`	`sensor`	Pacotes TX por segundo.

Como funciona a correção de rollover

Os contadores do IGD são unsigned 32-bit (2^32 ≈ 4,29 GB), definidos na RFC do protocolo. Em um link gigabit, o contador de bytes dá rollover em menos de 40 segundos de pico. O runtime mantém um valor “corrigido” acumulado em memória: a cada poll compara o valor cru atual com o anterior; se o cru caiu, assume um rollover e soma 2^32 ao delta antes de somar ao corrigido. Isso mantém os sensores Bytes Recebidos / Bytes Enviados monotônicos para a UI, enquanto o atributo raw mantém o valor cru para debugging. A velocidade de download/upload é derivada do delta por segundo e não acumula, então o rollover é tratado naturalmente ali.

Se você notar spikes gigantes nos sensores de velocidade, provavelmente seu roteador tem o contador zoado (reinicia aleatoriamente, por exemplo). A mitigação típica é reduzir o uso dos sensores de velocidade e consumir só os totais; na próxima versão expondo um sensor “sem correção” como no HA.

Automação de exemplo

# Notificar quando a WAN cair por mais de 2 minutos
- alias: "Internet caiu"
  trigger:
    - platform: state
      entity_id: binary_sensor.meu_roteador_wan_connected
      to: "off"
      for: "00:02:00"
  action:
    - service: notify.mobile_app
      data:
        message: "Internet caiu há 2 minutos."

Limitações atuais

Somente leitura. Comandos como “abrir porta” (AddPortMapping) ou “renovar lease” ainda não estão expostos.
Sem fallback de URL manual — a integração depende de SSDP achar o roteador. Se seu router não responde ao M-SEARCH mesmo com UPnP ligado, abra uma issue com o modelo e versão de firmware.
Autenticação Device Protection (DPS) não é suportada; a maioria dos roteadores domésticos não a exige na LAN.
Discovery automático (anúncio proativo) ainda não implementado — você precisa acionar a adição manualmente.

​UPnP/IGD (Roteador)

​Configurar

​Entidades

​Com WANIPConnection ou WANPPPConnection

​Com WANCommonInterfaceConfig

​Como funciona a correção de rollover

​Automação de exemplo

​Limitações atuais

UPnP/IGD (Roteador)

Configurar

Entidades

Com `WANIPConnection` ou `WANPPPConnection`

Com `WANCommonInterfaceConfig`

Como funciona a correção de rollover

Automação de exemplo

Limitações atuais