# HomeKit Bridge / Siri routine wrappers

Home Assistant is the automation source of truth for house routines. Apple Home and HomePods should use thin wrapper scenes that toggle Home Assistant script accessories.

## Current scope

We currently only need the common voice routines:

| Siri phrase / Apple Home scene | HomeKit accessory action |
| ------------------------------ | ------------------------ |
| `Good Night`                   | `HA Good Night = On`     |
| `Good Morning`                 | `HA Good Morning = On`   |

Matter devices can still be controlled directly by Siri/Apple Home when they are simple device commands.

## HA-side config

The HomeKit Bridge is declared in `modules/services/hass/default.nix`:

- Bridge advertises the NUC LAN IP: `192.168.1.222`
- Bridge TCP port: `21063`
- NixOS firewall allows TCP `21063`
- HomeKit exposes only two HA script entities as switch-like accessories:
  - `HA Good Night` → `script.goodnight`
  - `HA Good Morning` → `script.good_morning`

Keep this list intentionally small so Apple Home stays uncluttered and the HomeKit Bridge is only used for HA-backed routines that Siri cannot perform directly.

The script implementations live under `_domains/sleep/default.nix`.

## Pairing/reset workflow

Do not force a deterministic HomeKit PIN. Use the PIN/QR generated by Home Assistant.

If pairing needs to be reset:

1. In Home Assistant, go to **Settings → Devices & services → HomeKit Bridge**.
2. Remove the existing HomeKit Bridge entry if it is stale or paired to the wrong Apple Home.
3. Restart/redeploy Home Assistant:
   ```sh
   hey nuc
   ```
4. In Home Assistant, open **Settings → Devices & services → HomeKit Bridge** and use the generated PIN/QR.
5. On the iPhone, temporarily disable Tailscale/VPN/exit-node routing and join normal home Wi-Fi.
6. In Apple Home, switch to **Moni’s Dream House**.
7. Add accessory → **More Options…** → select **Home Assistant Bridge**.
8. Enter the generated Home Assistant PIN or scan the QR code.

If Apple Home can discover the bridge but hangs on **Connecting…**, verify:

```sh
ssh nuc 'sudo ss -ltnp | grep 21063'
nc -vz 192.168.1.222 21063
```

The first command should show Home Assistant listening on port `21063`; the second should succeed from a LAN machine.

## Apple Home scene setup

After pairing the bridge into **Moni’s Dream House**, create Apple Home scenes as wrappers only:

1. **Good Night** scene
   - Only action: turn `HA Good Night` on
2. **Good Morning** scene
   - Only action: turn `HA Good Morning` on

Do not put direct light/device actions in these Apple Home scenes. Keep the actual routine in Home Assistant.

Expected flow:

```text
HomePod Siri → Apple Home scene → HA script accessory → Home Assistant routine
```
