# Guia do Homebridge (app Casa da Apple) — passo a passo fácil

**O que é, em uma frase:** leva os **dispositivos de automação do Nexus** (luzes,
tomadas, etc.) para o app **Casa** do iPhone/iPad, usando um programa chamado
**Homebridge**.

**Fique tranquilo:** isso é um **extra** — não mexe no funcionamento do Nexus. E os
portões só aparecem se você quiser (vêm desligados).

**Você vai precisar de:** o Nexus rodando, um **Homebridge** já instalado (num
computador/Raspberry na mesma rede), e uns **15 minutos**. Se você ainda não tem
Homebridge, instale-o primeiro (site oficial homebridge.io).

---

## Passo 1 — criar a "chave de acesso" no Nexus

1. Abra o Nexus → **Configurações → API Clients** → **Novo**.
2. Marque os escopos (permissões):
   - **`automation:read`** — ver os dispositivos e o estado.
   - **`automation:control`** — ligar/desligar.
3. Salve e **copie a chave** que aparecer.

✅ **Deu certo se:** você copiou a chave (ela só aparece **uma vez** — se perder, crie
outra).

---

## Passo 2 — instalar o plugin no Homebridge

1. Copie a pasta **`deploy/homebridge-nexus/`** (do Nexus) para o servidor do
   Homebridge.
2. No servidor do Homebridge, dentro dessa pasta, instale:

```
sudo npm install -g .
```

3. No **Homebridge Config UI X** (a tela de configuração do Homebridge), adicione a
   plataforma **"Nexus Automação"** e preencha:
   - **baseUrl:** `http://IP_DO_SERVIDOR_NEXUS/hb`
   - **apiKey:** a chave do Passo 1.
4. **Reinicie o Homebridge.**

✅ **Deu certo se:** os dispositivos do Nexus aparecem no app **Casa** da Apple.

> Detalhes e uma alternativa sem plugin (`homebridge-http-switch`) estão em
> `deploy/homebridge-nexus/README.md`.

---

## Passo 3 — testar

No servidor do Homebridge (ou em qualquer PC da rede), teste a conexão (troque a
chave e o IP):

```bash
curl -H "X-API-Key: SUA_CHAVE" http://IP_DO_SERVIDOR_NEXUS/hb/devices
```

Deve voltar uma lista de dispositivos em formato de texto (JSON).

✅ **Deu certo se:** veio a lista, e no app Casa você consegue **ligar/desligar** um
dispositivo.

---

## (Opcional, sensível) mostrar os portões no app Casa

Vem **desligado**. Só ligue se entender o risco: **qualquer pessoa com acesso à sua
Casa (Apple Home) poderá abrir o portão**.

1. Dê também o escopo **`doors:open`** ao API Client (Passo 1).
2. No plugin, marque **`exposeDoors: true`** (e ajuste `doorRelockSeconds`).

Cada portão vira uma **fechadura**: "destrancar" no app aciona o portão (um pulso) e
ele "tranca" de novo em alguns segundos. Tudo é **limitado (10/min por portão) e
registrado em auditoria**.

---

## Deu algum problema?

- **401 (chave inválida):** confira a chave e se o API Client está **ativo**.
- **403 (sem permissão):** faltou o escopo `automation:read`/`automation:control` (ou
  `doors:open` para portões).
- **Nada aparece:** teste a URL no navegador/curl (Passo 3); confira se o Homebridge e
  o Nexus estão na **mesma rede**.

---

## Detalhes (para curiosos / técnico)

- O Nexus (PHP) **não é** o servidor HomeKit — o Homebridge é. O Nexus só oferece uma
  **API de automação** que o plugin consome.
- Dois endereços equivalentes: **`/hb`** (no host do site, via `public/homebridge.php`)
  ou **`/api/v1/automation`** (na vhost da API). Auth por header `X-API-Key`.
- Endpoints: `GET /devices`, `GET /devices/{id}`, `POST /devices/{id}/set`
  (`{"on":true}`), `GET /water`, e (com `doors:open`) `GET /doors` + `POST
  /doors/{id}/open`. O estado vem do banco (worker `auto_poll`); só o `set` aciona.
- **Google Home / Alexa** entram por cima do Homebridge — veja
  `deploy/INTEGRACAO-GOOGLE-ALEXA.md`.