> ## Documentation Index > Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt > Use this file to discover all available pages before exploring further. # UPnP/IGD (Roteador) > Monitore o roteador por UPnP/IGD: status WAN, IP externo, tráfego e uptime # UPnP/IGD (Roteador) A integração **UPnP/IGD** usa o protocolo [Internet Gateway Device](https://en.wikipedia.org/wiki/Internet_Gateway_Device_Protocol) sobre [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play) 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](https://www.home-assistant.io/integrations/upnp) e funciona com a grande maioria dos roteadores domésticos modernos que expõem UPnP ou NAT-PMP. > [!NOTE] > > 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. > [!WARNING] > > **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 **1. 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". **2. Adicione a integração** Vá em **Configurações → Integrações → Adicionar → UPnP/IGD (Roteador)** e selecione um edge local. **3. 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. **4. 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: 1. Se o UPnP/IGD está mesmo habilitado no roteador (ver aviso acima). 2. 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). 3. 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 | | - | - | - | | ` WAN Status` | `sensor` | Estado textual da WAN: `Connected`, `Disconnected`, `Connecting`, `Unknown`. | | ` WAN Connected` | `binary_sensor` | `on` se `WAN Status == Connected`. `device_class: connectivity`. Ideal para automações do tipo "notificar quando a internet cair". | | ` IP Externo` | `sensor` | IP público reportado pelo roteador. | | ` WAN Uptime` | `sensor` | Tempo desde o último handshake da WAN, em segundos (`device_class: duration`). | ### Com `WANCommonInterfaceConfig` | Entidade | Plataforma | Descrição | | - | - | - | | ` 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. | | ` Bytes Enviados` | `sensor` | Total TX idem. | | ` Pacotes Recebidos` | `sensor` | Total de pacotes RX corrigido para rollover. | | ` Pacotes Enviados` | `sensor` | Total de pacotes TX idem. | | ` Velocidade Download` | `sensor` | Taxa calculada entre polls, em KiB/s. `device_class: data_rate`. | | ` Velocidade Upload` | `sensor` | Idem para TX. | | ` Pacotes Download/s` | `sensor` | Pacotes RX por segundo. | | ` 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. > [!NOTE] > > 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 ```yaml theme={null} # 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.