# Guia do MQTT — passo a passo bem fácil

**O que é isto, em uma frase:** o MQTT é um "carteiro" que entrega mensagens entre
o Nexus e os aparelhos, tudo dentro da sua rede. Ligar ele deixa o sistema mais
esperto (e prepara o terreno para câmeras inteligentes, medidores, etc.).

**Fique tranquilo:** enquanto você não terminar, **nada para de funcionar**. O MQTT
é um extra. Se desistir no meio, é só não ligar — o Nexus continua igual.

**Você vai precisar de:** o computador **servidor** (aquele onde roda o Nexus/WAMP),
uns **15 minutos**, e uma conta de **administrador** do Windows.

> Faça tudo isto **no computador servidor**. Os comandos são para **copiar e colar** —
> não precisa entender cada palavra.

---

## Passo 1 — Baixar o "carteiro" (programa Mosquitto)

1. Abra o navegador (Chrome, Edge…).
2. Digite na barra de endereço: **mosquitto.org/download** e aperte Enter.
3. Ache a parte **Windows** e clique no link do instalador **64-bit** (o arquivo
   termina em `.exe`, tipo `mosquitto-2.0.22-install-windows-x64.exe`).

✅ **Deu certo se:** você tem um arquivo `.exe` do Mosquitto na pasta Downloads.

---

## Passo 2 — Instalar (é só ir clicando)

1. Dê **dois cliques** no arquivo que baixou.
2. Se o Windows perguntar "deseja permitir?", clique **Sim**.
3. Clique **Next → Next → Install**. Pode deixar tudo como já vem.
4. No fim, clique **Finish**.

✅ **Deu certo se:** existe a pasta `C:\Program Files\Mosquitto`.

---

## Passo 3 — Abrir o "Prompt de Comando" como administrador

Você vai usar essa telinha preta nos próximos passos.

1. Clique no **Menu Iniciar** (canto inferior esquerdo).
2. Digite: **cmd**
3. Vai aparecer **"Prompt de Comando"**. Clique nele com o **botão direito** do mouse.
4. Escolha **"Executar como administrador"**. Clique **Sim** se perguntar.

✅ **Deu certo se:** abriu uma janela preta escrita `Administrador:` no topo.

---

## Passo 4 — Criar um usuário e senha (para ninguém de fora entrar)

Na janela preta, **copie e cole a linha abaixo** e aperte **Enter**.
Antes, troque a palavra `MinhaSenhaForte` por uma senha sua (sem espaços):

```
"C:\Program Files\Mosquitto\mosquitto_passwd.exe" -c -b "C:\Program Files\Mosquitto\senhas.txt" nexus MinhaSenhaForte
```

✅ **Deu certo se:** não apareceu nenhuma mensagem de erro (voltou a linha de comando).
Isso cria um usuário chamado **nexus** com a sua senha.

> **Anote o usuário `nexus` e a senha** — você vai usá-los no Passo 6.

---

## Passo 5 — Escrever o "papel de regras" do carteiro e ligá-lo

**5.1 — Abrir o Bloco de Notas como administrador:**
Menu Iniciar → digite **bloco de notas** → clique com o **botão direito** →
**Executar como administrador**.

**5.2 — Colar exatamente este texto** (troque nada; é só colar):

```
listener 1883 0.0.0.0
allow_anonymous false
password_file C:\Program Files\Mosquitto\senhas.txt
persistence true
persistence_location C:\Program Files\Mosquitto\
log_dest file C:\Program Files\Mosquitto\mosquitto.log
```

**5.3 — Salvar no lugar certo:**
- Menu **Arquivo → Salvar como…**
- Em **"Tipo"** (embaixo), troque para **"Todos os arquivos"**.
- ⚠️ Em **"Codificação"** (ao lado), escolha **ANSI**. **Não deixe UTF‑8.**
- No nome do arquivo, cole isto e clique **Salvar**:

```
C:\Program Files\Mosquitto\mosquitto.conf
```

> ### ⚠️ As três armadilhas que fazem o Mosquitto "iniciar e parar na hora"
>
> Se o serviço diz *"iniciado com êxito"* mas o `sc query mosquitto` mostra
> **STOPPED**, é uma destas — o Mosquitto leu o arquivo, não gostou, e saiu calado:
>
> 1. **Codificação UTF‑8.** O Bloco de Notas põe uma marca invisível no começo do
>    arquivo, e o Mosquitto reclama da primeira linha (`Unknown configuration
>    variable "listener"`) e **morre**. Salve como **ANSI**.
> 2. **O arquivo virou `mosquitto.conf.txt`.** Acontece quando se esquece de trocar
>    o "Tipo" para *Todos os arquivos*. Confira na pasta com o Explorer (ative
>    *Exibir → Extensões de nomes de arquivos*).
> 3. **O `senhas.txt` não existe.** Como o `.conf` diz `allow_anonymous false`, o
>    Mosquitto **exige** o arquivo de senhas; se ele não estiver lá, o serviço não
>    sobe. Refaça o Passo 4 e confirme que o arquivo apareceu na pasta.

**5.4 — Ligar (ou reiniciar) o carteiro.** Volte na janela preta (Passo 3) e cole
estas duas linhas, uma de cada vez, apertando **Enter** depois de cada:

```
net stop mosquitto
net start mosquitto
```

✅ **Deu certo se:** o comando abaixo mostrar `ESTADO : 4 RUNNING`
(o "iniciado com êxito" do `net start` **não** é garantia — ele pode subir e cair):

```
sc query mosquitto
```

> **Deu STOPPED?** Não fique no escuro: rode o Mosquitto em **primeiro plano**, que
> ele imprime o motivo real na tela:
>
> ```
> "C:\Program Files\Mosquitto\mosquitto.exe" -c "C:\Program Files\Mosquitto\mosquitto.conf" -v
> ```
>
> A primeira linha de erro diz exatamente o que corrigir (quase sempre uma das três
> armadilhas acima). Para sair, aperte **Ctrl+C**.

> Se aparecer "o serviço não foi iniciado" ou "nome não existe", cole isto e tente
> o `net start` de novo:
> ```
> "C:\Program Files\Mosquitto\mosquitto.exe" install
> ```

---

## Passo 6 — Avisar o Nexus que o carteiro existe

1. Abra o **Bloco de Notas como administrador** (igual ao Passo 5.1).
2. Menu **Arquivo → Abrir**. Em **"Tipo"**, escolha **"Todos os arquivos"**.
3. Cole este caminho na linha do nome e clique **Abrir**:

```
C:\wamp64\www\api\.env
```

4. Vá até o **final do arquivo** e adicione estas linhas (troque a senha pela sua):

```
MQTT_ENABLED=true
MQTT_HOST=127.0.0.1
MQTT_PORT=1883
MQTT_USERNAME=nexus
MQTT_PASSWORD=MinhaSenhaForte
```

5. Menu **Arquivo → Salvar**.

✅ **Deu certo se:** salvou sem erro. (Se der "acesso negado", é porque o Bloco de
Notas não foi aberto como administrador — feche e abra de novo como administrador.)

> Não tem WAMP em `C:\wamp64`? Então o `.env` está na pasta do Nexus, dentro de
> `api\.env`. Procure onde já existem linhas como `DB_HOST=` — é o arquivo certo.

---

## Passo 7 — Ligar a "ponte" do Nexus (recomendado)

A ponte faz o Nexus **receber comandos** por MQTT e aparecer como "no ar" na tela.

1. Vá na pasta `C:\wamp64\www\api\scripts`.
2. Ache o arquivo **`mqtt_bridge.bat`**. Clique com o botão direito → **Editar**.
3. Confira se as duas linhas de caminho batem com o seu servidor:
   - `set "PHP=..."` deve apontar para o `php.exe` da sua versão do PHP.
   - `set "SCRIPT=..."` deve apontar para `...\api\scripts\mqtt_bridge.php`.
   - Se estiver tudo certo, só feche.
4. Faça ela **iniciar junto com o Windows**:
   - Menu Iniciar → digite **Agendador de Tarefas** → abra.
   - No menu direito, clique **"Criar Tarefa Básica…"**.
   - Nome: **Nexus MQTT** → Avançar.
   - Quando: **"Ao iniciar o computador"** → Avançar.
   - Ação: **"Iniciar um programa"** → Avançar.
   - Em "Programa/script", clique **Procurar** e escolha o `mqtt_bridge.bat` → Avançar → **Concluir**.
5. Para não esperar reiniciar, **dê dois cliques** no `mqtt_bridge.bat` agora. Vai
   abrir uma janelinha preta que fica aberta (é ela trabalhando — pode minimizar).

✅ **Deu certo se:** na janelinha aparece algo como *"conectado ao broker; assinando…"*.

---

## Passo 8 — Testar se funcionou

**Jeito fácil (pela tela do Nexus):** abra o Nexus no navegador → menu **Central**.
Depois de ~1 minuto, deve aparecer o serviço **"Barramento MQTT (ponte)"** como
ativo/verde.

**Jeito curioso (ver as mensagens passando):** na janela preta de administrador, cole
(troque a senha) e aperte Enter:

```
"C:\Program Files\Mosquitto\mosquitto_sub.exe" -h 127.0.0.1 -u nexus -P MinhaSenhaForte -t "nexus/#" -v
```

Agora, na tela do Nexus, **ligue ou desligue um dispositivo**. Na janela preta deve
aparecer uma linha começando com `nexus/device/…`.

✅ **Apareceu a linha?** Está funcionando! Pode fechar a janela preta (aperte `Ctrl+C`).

---

## Deu algum problema? (respostas rápidas)

- **"Não conecta" / a Central não fica verde:**
  Menu Iniciar → digite **Serviços** → abra → procure **"Mosquitto Broker"** → tem que
  estar **"Em execução"**. Se não estiver, clique com o direito → **Iniciar**.
- **Erro de senha / "connection refused":** a senha do `.env` (Passo 6) tem que ser
  **exatamente** a mesma que você criou no Passo 4.
- **"Acesso negado" ao salvar o `.conf` ou o `.env`:** o Bloco de Notas precisa ter
  sido aberto **como administrador**. Feche e abra de novo do jeito certo.
- **Mudou a senha depois?** Refaça o Passo 4 (com a senha nova) e o Passo 6, e rode
  `net stop mosquitto` + `net start mosquitto`.

> **Segurança:** deixe o Mosquitto **só na sua rede local**. Nunca libere a porta
> **1883** no roteador para a internet.

---

## (Avançado, só se quiser) Ligar um aparelho direto no MQTT

Se você tem um aparelho que já fala MQTT (ex.: uma tomada com firmware **Tasmota**),
dá para o Nexus controlá-lo por MQTT:

1. No Nexus, crie o dispositivo com **driver = MQTT (Tasmota/ESPHome nativo)**.
2. Preencha os campos com os **tópicos do aparelho** (não usam o prefixo `nexus/`):

| Campo | Exemplo (Tasmota) | O que é |
|---|---|---|
| `cmd_topic` | `cmnd/tomada1/POWER` | tópico para mandar ligar/desligar (obrigatório) |
| `payload_on` | `ON` | o que envia para ligar |
| `payload_off` | `OFF` | o que envia para desligar |
| `state_topic` | `stat/tomada1/POWER` | tópico onde o aparelho diz o estado (opcional) |
| `state_on` | `ON` | valor que significa "ligado" |

Passar um aparelho para MQTT nativo é **opcional** — faça só em aparelho novo ou quando
quiser tirar da nuvem. Comparativo completo no plano
(`docs/PLANO-CEREBRO-CONDOMINIO.md`).

---

## (Para curiosos) O que o Nexus publica no carteiro

Tudo começa com `nexus/` (você pode espiar com o comando do Passo 8):

| Assunto (tópico) | Quando | O que traz |
|---|---|---|
| `nexus/status` | ponte liga/cai | se o Nexus está no ar |
| `nexus/device/{id}/state` | ao ligar/desligar algo | o novo estado do dispositivo |
| `nexus/passage` | alguém/algo passa | passagem (placa, pessoa, câmera) |
| `nexus/water/level` | leitura da caixa | nível, bomba, ação |
| `nexus/weather` | a cada 15 min | previsão do tempo (se ativada) |
| `nexus/cmd/device/{id}/set` | você/algo manda | comando `on`/`off` para um dispositivo |