# Hey Boo × Home Assistant — Setup Guide

How to go from mock mode to controlling your real home with Hey Boo.

---

## What we built (already live)

- **`boojee-heyboo-ha` Lambda** — HA bridge.  
  Receives a parsed intent (turn_on, set_temperature, lock, etc.), calls the HA REST API, returns a spoken response + action record.  
  Falls back to a full mock demo home when no HA creds are present.

- **Smart-home skills** (`heyboo/ha_skills.py` + `heyboo/app/ha-skills.js`)  
  Deterministic NLP parser: "turn on the living room lights" → `intent=turn_on, entity_id=light.living_room`. No AI spend required. LLM upgrade path built in.

- **Voice PWA** (`/heyboo/app/`)  
  Installable PWA. Big mic button (push-to-talk). Web Speech API STT. SpeechSynthesis TTS. Demo home state panel that updates on every command. Works on your phone right now in mock mode.

---

## Step 1 — Buy or build a Home Assistant hub

**Easiest (plug-and-play):**

- **HA Green** (~$99) — plug in Ethernet + power, done in 10 min.
- **HA Yellow** (~$130) — includes Zigbee + Matter radio for local device control.
- Raspberry Pi 4/5 (4 GB) + HA OS SD image — free if you have one already.
- Intel NUC or Beelink mini-PC — faster; runs HA + add-ons smoothly.

**Install HA OS**: https://www.home-assistant.io/installation/

---

## Step 2 — Connect your devices

Once HA boots at `http://homeassistant.local:8123`:

1. Open **Settings → Devices & Services → Add Integration**.
2. Search for your brand:
   - **Philips Hue**, **LIFX**, **Govee** — WiFi, instant setup.
   - **Zigbee** (IKEA Tradfri, Aqara, Sonoff) — needs a Zigbee coordinator (SkyConnect USB stick ~$35 or built-in on HA Yellow).
   - **Z-Wave** (Schlage/Yale locks, GE switches) — needs a Z-Wave stick.
   - **Matter** (newest standard) — HA 2024+ supports it natively.
   - **SmartThings hub devices** — use the SmartThings integration.
   - **Google Home devices** — partial (local control limited).
3. After adding integrations, devices appear in **Settings → Devices**.
4. Note the **entity IDs** (e.g. `light.living_room`, `lock.front_door`) — Hey Boo uses these.

---

## Step 3 — Create a Long-Lived Access Token

1. Log into HA at `http://<your-ha-ip>:8123`.
2. Click your profile avatar (bottom-left).
3. Scroll to **Long-Lived Access Tokens** → **Create Token**.
4. Name it `heyboo-bridge` → copy the token.

**Keep this token private — it has full HA access.**

---

## Step 4 — Store credentials in AWS Secrets Manager

```bash
# From your Muse desk or any terminal with AWS13 creds
aws secretsmanager create-secret \
  --name boojee/heyboo/homeassistant \
  --secret-string '{"base_url":"http://YOUR-HA-IP:8123","token":"YOUR-LONG-LIVED-TOKEN"}' \
  --region us-east-1
```

Or update if the secret already exists:

```bash
aws secretsmanager update-secret \
  --secret-id boojee/heyboo/homeassistant \
  --secret-string '{"base_url":"http://YOUR-HA-IP:8123","token":"YOUR-LONG-LIVED-TOKEN"}' \
  --region us-east-1
```

Once the secret is saved, **the Lambda switches out of mock mode automatically** — no redeploy needed.

**Note**: If your HA is on a private home network, the Lambda cannot reach `http://192.168.x.x:8123`.  
You have two options:
- Use **Nabu Casa** (HA Cloud, $7/mo) for a public HTTPS URL — `https://YOUR-ID.ui.nabu.casa`.
- Use **Cloudflare Tunnel** (free) to expose HA securely over HTTPS.

Either way, use the public HTTPS URL as `base_url`.

---

## Step 5 — Deploy the Lambda + API Gateway

Run from the Muse desk:

```bash
cd /home/ubuntu/muse
python ops/deploy_lambda.py boojee-heyboo-ha   # or use the standard zip+update flow
```

The Lambda is at `lambda/boojee-heyboo-ha/handler.py`.  
Deploy it to AWS13 (`121712452496`) with:

- Runtime: Python 3.12
- Handler: `handler.handler`
- Role: create a new role (or extend an existing Hey Boo role) with:
  - `AWSLambdaBasicExecutionRole`
  - `secretsmanager:GetSecretValue` scoped to `boojee/heyboo/homeassistant`
- Timeout: 15 seconds
- Memory: 256 MB

Then create an **HTTP API Gateway** (not REST API — HTTP is faster and cheaper):
- Route: `POST /ha`
- Integration: Lambda proxy
- CORS: NONE (Lambda owns CORS headers)
- Auto-deploy: yes

Copy the invoke URL and update `HA_BRIDGE_URL` in `heyboo/app/index.html`.

---

## Step 6 — Update the PWA endpoint

In `heyboo/app/index.html`, find:

```js
var HA_BRIDGE_URL = 'https://ha.heyboo.boojee.estate/ha';
```

Replace with your actual API Gateway URL:

```js
var HA_BRIDGE_URL = 'https://XXXXX.execute-api.us-east-1.amazonaws.com/ha';
```

Then deploy the updated PWA to S3:

```bash
aws s3 cp heyboo/app/ s3://boojee-estate-site-prod/heyboo/app/ --recursive
aws cloudfront create-invalidation --distribution-id E2U2K78XFOZ24E --paths "/heyboo/app/*"
```

---

## Step 7 (optional) — Custom "Hey Boo" wake word

### On your phone (easiest):
Use the PWA at `/heyboo/app/` — tap the mic button, then speak. Works immediately.

### Always-listening satellite (hands-free, recommended for home use):

**Option A — Home Assistant Voice Preview Edition** (~$59 USB dongle):
- Plug into HA host USB port.
- Go to **Settings → Add-ons → Wyoming Satellite** (or use the built-in voice assistant).
- Set the conversation agent to **a custom agent** pointing at the Hey Boo bridge.
- Set the wake word to "Hey Boo" via openWakeWord add-on.

**Option B — ESPHome satellite** (DIY, ~$15):
- Flash any ESP32-S3-based board (e.g. M5Stack Atom Echo, $13).
- Use the ESPHome voice satellite blueprint: https://voice.home-assistant.io/satellite/
- Configure `wake_word: hey_boo` (requires openWakeWord model — see below).

**Option C — Raspberry Pi Zero 2W** (~$18) with:
- USB mic + 3.5mm speaker.
- Run `pvporcupine` Python package listening for a custom "hey boo" wake word.
- On detection, POST audio to Hey Boo bridge → speak the response via `espeak` or `piper-tts`.

### openWakeWord for "Hey Boo":
- Pre-trained "Hey Jarvis" or "Alexa" models work as a stand-in for testing.
- To train a custom "hey boo" model: https://github.com/dscripka/openWakeWord#training-new-models
  (needs ~30 minutes of audio data — record yourself saying "hey boo" 100 times).

---

## Step 8 (optional) — Wire HA Assist to Hey Boo brain

If you want HA's built-in Assist (the microphone button in the HA app) to route through Hey Boo instead of the local LLM:

1. In HA: **Settings → Voice assistants → Add assistant**.
2. Set **Conversation agent** to an HTTP webhook pointing at:
   - `https://YOUR-GATEWAY.execute-api.us-east-1.amazonaws.com/heyboo` (the Hey Boo intent handler)
3. Set **Wake word** engine to openWakeWord, word = "hey boo".
4. Set **TTS** to Amazon Polly via a custom TTS integration (or use HA's built-in `tts.cloud_say`).

---

## Upgrade paths

- **Smarter brain**: Swap `ha_skills.py` keyword parser for a Claude Haiku call for ambiguous commands (e.g. "make it cozy in here" → activate `scene.relax`). The Lambda architecture is already wired for this — just add a Bedrock call as a fallback when `confidence == 'low'`.

- **More entity types**: Add `switch`, `media_player`, `vacuum`, `cover` to the bridge `_VALID_INTENTS` and mock state.

- **Multi-room**: The room alias table in `ha_skills.py` / `ha-skills.js` covers 12 rooms. Add any custom room names by appending to `ROOM_ALIASES`.

---

## Security checklist

- HA token is stored in Secrets Manager — never in code, environment variables, or client-side JS.
- The Lambda returns CORS headers scoped to `https://boojee.estate` only.
- Secrets Manager IAM policy is scoped to the single secret ARN (`boojee/heyboo/homeassistant`).
- HA itself should be behind HTTPS (Nabu Casa or Cloudflare Tunnel) — never expose port 8123 directly to the internet.
- The bridge Lambda does NOT expose entity listing to unauthenticated callers in production — add Cognito auth on the API Gateway when you scale beyond personal use.

---

## What works right now (no setup required)

Load `/heyboo/app/` on your phone.

- Tap the gold mic button and say "turn on the living room lights".
- Or type any command in the text box.
- The demo home state panel updates live showing the simulated result.
- Hey Boo speaks the response back.

**All 8 demo home devices respond to commands in mock mode.**  
Connect real HA (Steps 1–6) and the exact same commands control your actual home.