# Integração com o controlador TP-Link Omada (Open API)

Este guia liga o Nexus ao **controlador Omada** que gerencia a rede do
condomínio. Com isso o sistema passa a **enxergar a rede** (pontos de acesso,
switches e o gateway — quem está online, quantos aparelhos conectados) e, depois,
poderá **gerar Wi‑Fi de visitante** e **controlar portas PoE / bloquear
aparelhos**.

> **Termo em uma frase:**
> - **Controlador Omada** = o "cérebro" que gerencia todos os equipamentos de
>   rede TP‑Link (roteador, switches, pontos de Wi‑Fi).
> - **Open API** = a "porta de entrada" oficial para outro sistema (o Nexus)
>   conversar com o controlador.
> - **Client ID / Secret** = o "usuário e senha" dessa porta, só para máquinas.

⏱️ Tempo: ~10 minutos. Você vai precisar de acesso de **administrador** ao
controlador Omada.

---

## Antes de começar (pré‑requisitos)

- Controlador Omada **versão 5.x** (Hardware OC200/OC300, Software Controller ou
  Cloud‑Based) com o recurso **Open API** disponível. Quase todos os atuais têm.
- Acesso de administrador à tela do controlador (pelo navegador).
- O Nexus e o controlador na **mesma rede** (o servidor do Nexus alcança o IP do
  controlador), OU o controlador na nuvem TP‑Link.

---

## Passo 1 — Criar o "App" no controlador (a porta de entrada)

1. Abra o controlador Omada no navegador e faça login como administrador.
2. No canto superior, mude para a **Global View** (visão global).
3. Vá em **Settings** (Configurações) → **Platform Integration** (Integração de
   plataforma) → **Open API**.
4. Clique em **Add New App** (Adicionar novo app), no canto superior direito.
5. Dê um nome, ex.: `Nexus`.
6. Em **Mode** (Modo), escolha **Client Credentials**.
   > É o modo "máquina‑a‑máquina" — não precisa de ninguém logando toda hora.
7. Em **Role/Privilege** (Papel/Privilégio), escolha o nível de acesso:
   - Para **só monitorar**: pode deixar **Viewer** (somente leitura).
   - Para **também controlar** (PoE, bloquear, voucher): escolha **Administrator**
     (ou um papel com permissão de edição do site).
8. Salve.

✅ **Deu certo se:** o app `Nexus` aparece na lista de apps do Open API.

---

## Passo 2 — Copiar as 4 informações que o Nexus precisa

Ainda na tela do Open API, no item do app `Nexus`:

1. Clique no **ícone de olho** para revelar o **Client Secret**.
2. Anote:
   - **Client ID**
   - **Client Secret**
3. Clique no **ícone de visualizar** (view) para revelar:
   - **Omada ID** (identificador do controlador)
   - **Interface Access Address** (o **endereço base** — algo como
     `https://172.16.0.10:8043` no local, ou um endereço `...tplinkcloud.com` na
     nuvem).

Guarde esses 4 valores. São o "usuário e senha" + endereço da porta.

✅ **Deu certo se:** você tem em mãos **Client ID**, **Client Secret**,
**Omada ID** e o **endereço base**.

---

## Passo 3 — Preencher o `.env` do Nexus

1. No servidor, abra o arquivo **`api\.env`** (na pasta do Nexus) num editor de
   texto (Bloco de Notas serve).
2. Procure o bloco **`Controlador TP-Link Omada`** (se não existir, copie do
   `api\.env.example`) e preencha assim, trocando pelos SEUS valores:

```
OMADA_ENABLED=false
OMADA_BASE_URL=https://172.16.0.10:8043
OMADA_OMADAC_ID=cole-aqui-o-omada-id
OMADA_CLIENT_ID=cole-aqui-o-client-id
OMADA_CLIENT_SECRET=cole-aqui-o-client-secret
OMADA_SITE_ID=
OMADA_VERIFY_SSL=false
```

> - Deixe `OMADA_ENABLED=false` por enquanto — a gente **testa antes** de ligar.
> - `OMADA_SITE_ID` pode ficar vazio (o Nexus usa o primeiro site, geralmente o
>   "Default").
> - `OMADA_VERIFY_SSL=false` porque o controlador local usa um certificado próprio
>   (autoassinado). Na nuvem pode deixar `true`.

3. Salve o arquivo.

✅ **Deu certo se:** o arquivo foi salvo com os 4 valores preenchidos.

---

## Passo 4 — Testar a conexão

1. Abra o **Prompt de Comando** (Menu Iniciar → digite `cmd` → Enter).
2. Cole o comando abaixo (é uma linha só) e aperte Enter:

```
C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\omada_test.php
```

> Ajuste o caminho `C:\wamp64\www` se a sua pasta do Nexus for outra. Se a
> versão do PHP mudar, ajuste `php8.3.28`.

3. Leia o resultado. Você deve ver algo como:

```
  [ OK ]  Autenticação (token de 620 caracteres).
  [ OK ]  Sites: 1
        - Default  (Default)
  [ OK ]  Dispositivos: 5
        NOME                   TIPO     ESTADO   MODELO         CLIENTES
        Gateway                gateway  online   ER605          -
        Switch Portaria        switch   online   SG2008P        3
        AP Salão               ap       online   EAP245         12
  [ OK ]  Clientes conectados (1ª página): 47
```

✅ **Deu certo se:** apareceram os **sites** e a lista de **dispositivos** da sua
rede.

4. Se deu certo, volte no `api\.env`, mude para **`OMADA_ENABLED=true`** e salve.
   **Me avise** que eu ligo o monitoramento da rede na **Central** e no **Mural**,
   e sigo para o **voucher de Wi‑Fi** e o **controle (PoE/bloqueio)**.

---

## Deu problema?

**"Faltam credenciais…"**
→ Algum campo do `.env` está vazio. Confira os 4 valores do Passo 2.

**"Autenticação: … falha ao obter token"**
→ Verifique o **endereço base** (host e porta certos?), o **Omada ID** e se o app
está no modo **Client Credentials**. Teste abrir o endereço base no navegador do
servidor — tem que responder (mesmo que dê aviso de certificado).

**"falha de comunicação"**
→ O servidor do Nexus não está alcançando o controlador. Confirme que estão na
mesma rede e que o firewall do Windows não bloqueia a porta (ex.: 8043).

**Autenticou, mas "Dispositivos: falha"**
→ O caminho de dispositivos pode variar na sua versão do controlador. Rode o
comando abaixo para ver o retorno cru e me mande o resultado:

```
C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\omada_test.php GET /sites/Default/devices
```

**Quero explorar outros dados da API**
→ Use o modo exploração, trocando o caminho:

```
C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\omada_test.php GET /sites
```

---

## O que vem depois (quando a conexão estiver validada)

1. **Monitoramento (JÁ PRONTO)** — depois de `OMADA_ENABLED=true`, os aparelhos
   entram **sozinhos**: o worker **`auto_omada`** (instalado pelo
   `install_workers.bat`) sincroniza a lista a cada ~10 min — **adiciona** o
   aparelho novo, **remove** o que você tirou do controlador (sem alarme falso) e
   **reativa** o que voltar. Ele casa por **MAC**, então **trocar o IP dos
   aparelhos não afeta em nada** (só o IP do *controlador*, `172.16.1.28`, precisa
   ser fixo — deixe uma reserva de DHCP pra ele).

   Se quiser forçar a sincronização na hora (opcional):

   ```
   C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\omada_import.php
   ```

   Cada AP/switch/gateway vira um "dispositivo" (somente leitura) e aparece na
   **Central** e na tela **Sistemas** do **Mural**, com **alerta** quando um cair
   (o worker `auto_poll` cuida do online/offline).

2. **A tela Rede (JÁ PRONTA)** — em **Monitoramento → Rede** você vê:

   - **Aparelhos de rede**: quais estão **online/offline** (os offline aparecem
     primeiro), modelo, IP, quantos clientes cada um atende, **CPU e memória**,
     tempo ligado e **tráfego**.
   - **Clientes conectados**: nome, IP, MAC, fabricante, Wi‑Fi × cabo, força do
     sinal, tempo on‑line e **tráfego**.
   - **Top consumo**: quem mais consumiu banda, em barras.
   - **Top aplicações (DPI)**: ver o passo 3.

3. **DPI / Application Control (top aplicações) — só precisa estar LIGADO no Omada**

   O caminho já está no Nexus (foi confirmado numa captura da própria interface do
   seu controlador). A única coisa que falta é o **DPI estar ligado**:

   No Omada, entre em **Settings → Network Security** (ou **Insight**, dependendo da
   versão) e ligue o **Application Analytics / DPI**.

   > ⚠️ O DPI costuma exigir um **gateway Omada** (roteador) no site — só com AP e
   > switch normalmente não há como inspecionar as aplicações.

   Para conferir se está funcionando, rode no servidor:

   ```
   C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\omada_diag.php dpi
   ```

   ✅ **Deu certo se…** aparecer `>>> DPI FUNCIONANDO` seguido do nome da primeira
   aplicação. O card **Top aplicações** em *Monitoramento → Rede* já estará cheio.

   ❌ Se aparecer `O caminho do DPI RESPONDE, mas veio VAZIO`, é o DPI desligado no
   controlador — volte no passo acima.

   ❌ Se der **falha de permissão**, o App do Open API precisa poder **ler o
   dashboard** (Settings → Platform Integration → Open API).

4. **Fotos dos aparelhos (EAPs, switches, gateway)**

   O Nexus vem com um acervo de fotos, mas ele **não cobre todos os modelos**. Para
   pegar a foto **certa de cada aparelho**, baixe direto do seu controlador (ele tem
   todas):

   ```
   C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\omada_icons.php
   ```

   ✅ **Deu certo se…** aparecer uma linha `OK` para cada modelo e, no fim,
   `faltando : 0`. Recarregue **Monitoramento → Rede** e as fotos estarão lá.

   Se sobrar algum modelo em `faltando`, o script explica como descobrir o nome do
   arquivo no controlador e cadastrá-lo (a TP-Link nomeia algumas fotos de um jeito que
   não dá para adivinhar — o `EAP620 HD`, por exemplo, é `hd620.png`).

   > **O aparelho sem foto não fica quebrado:** ele mostra um ícone genérico do tipo
   > (AP, switch, gateway). Isso é de propósito — **é melhor um ícone genérico do que a
   > foto de outro produto**, que faria você conferir o parque errado.

   Rode este comando de novo sempre que **adicionar um modelo novo** à rede.

> **A integração é SÓ LEITURA, de propósito.** O Nexus **nunca escreve** no
> controlador: ligar/desligar PoE, mexer em SSID, bloquear cliente e gerar voucher
> ficam **no Omada**. (Foi uma decisão de produto — e a Open API deste controlador
> nem expõe boa parte disso.)

Tudo isso é **opcional** e tem **interruptor** em **Configurações → Módulos**
(módulo *Rede TP‑Link Omada*): se desligar, o Nexus funciona normalmente sem a
Omada.