homelab-docs/HOMEASSISTANT.md

# Home Assistant

## Overview

| Setting | Value |
|---------|-------|
| VM ID | 110 |
| Host | PVE (10.10.10.120) |
| IP Address | 10.10.10.210 (DHCP - should be static) |
| Port | 8123 |
| Web UI | http://10.10.10.210:8123 |
| OS | Home Assistant OS 16.3 |
| Version | 2025.11.3 (update available: 2025.12.3) |

## API Access

Home Assistant uses Long-Lived Access Tokens for API authentication.

### Getting an API Token

1. Go to http://10.10.10.210:8123
2. Click your profile (bottom left)
3. Scroll to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Name it (e.g., "Claude Code")
6. Copy the token (only shown once!)

### API Configuration

```
API_URL: http://10.10.10.210:8123/api
API_TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwZThjZmJjMzVlNDA0NzYwOTMzMjg3MTQ5ZjkwOGU2NyIsImlhdCI6MTc2NTk5MjQ4OCwiZXhwIjoyMDgxMzUyNDg4fQ.r743tsb3E5NNlrwEEu9glkZdiI4j_3SKIT1n5PGUytY
```

### API Examples

```bash
# Set these variables
HA_URL="http://10.10.10.210:8123"
HA_TOKEN="your-token-here"

# Check API is working
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/"

# Get all states
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq

# Get specific entity state
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room" | jq

# Turn on a light
curl -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room"}' \
  "$HA_URL/api/services/light/turn_on"

# Turn off a light
curl -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room"}' \
  "$HA_URL/api/services/light/turn_off"

# Call any service
curl -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "switch.my_switch"}' \
  "$HA_URL/api/services/switch/toggle"
```

## Common Tasks

### List All Entities
```bash
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'
```

### List Entities by Domain
```bash
# All lights
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '[.[] | select(.entity_id | startswith("light."))]'

# All switches
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '[.[] | select(.entity_id | startswith("switch."))]'

# All sensors
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '[.[] | select(.entity_id | startswith("sensor."))]'
```

### Get Entity History
```bash
# Last 24 hours for an entity
curl -s -H "Authorization: Bearer $HA_TOKEN" \
  "$HA_URL/api/history/period?filter_entity_id=sensor.temperature" | jq
```

## Device Summary

**265 total entities**

| Domain | Count | Examples |
|--------|-------|----------|
| scene | 87 | Lighting scenes |
| light | 41 | Kitchen, Living room, Bedroom, Office, Cabinet, etc. |
| switch | 36 | Automations, Sonos controls, Motion sensors |
| sensor | 28 | Various sensors |
| number | 21 | Settings/controls |
| event | 17 | Event triggers |
| binary_sensor | 13 | Motion, door sensors |
| media_player | 8 | Sonos speakers (Bedroom, Living Room, Kitchen, Console) |

### Lights by Room
- **Kitchen**: Kitchen light
- **Living Room**: Living room, Living Room Lamp, TV Bias
- **Bedroom**: Bedroom, Bedside Lamp 1 & 2, Dresser
- **Office**: Office, Office Floor Lamp, Office Lamp
- **Guest Room**: Guest Bed Left, Guest Lamp Right
- **Other**: Cabinet 1 & 2, Pantry, Bathroom, Front Porch, etc.

### Sonos Speakers
- Bedroom (with surround)
- Living Room (with surround)
- Kitchen
- Console

### Motion Sensors
- Kitchen Motion
- Office Sensor

## Integrations

- **Philips Hue** - Lights
- **Sonos** - Speakers
- **Nest** - Thermostat (climate.thermostat)
- **Motion Sensors** - Various locations
- **NUT (Network UPS Tools)** - UPS monitoring (added 2025-12-21)
- **VeSync** - Levoit humidifier control (added 2026-01-14)
- **HomeKit Controller** - Homebridge bridge for Govee sensors (added 2026-01-14)
- **Oura Ring v2** - Sleep/health tracking via HACS (added 2026-01-16)
- **HACS** - Home Assistant Community Store for custom integrations

### NUT / UPS Integration

Monitors the CyberPower OR2200PFCRT2U UPS connected to PVE.

**Connection:**
- Host: 10.10.10.120
- Port: 3493
- Username: upsmon
- Password: upsmon123

**Entities:**
| Entity ID | Description |
|-----------|-------------|
| `sensor.cyberpower_battery_charge` | Battery percentage |
| `sensor.cyberpower_load` | Current load % |
| `sensor.cyberpower_input_voltage` | Input voltage |
| `sensor.cyberpower_output_voltage` | Output voltage |
| `sensor.cyberpower_status` | Status (Online, On Battery, etc.) |
| `sensor.cyberpower_status_data` | Raw status (OL, OB, LB, CHRG) |

**Dashboard Card Example:**
```yaml
type: entities
title: UPS Status
entities:
  - entity: sensor.cyberpower_status
    name: Status
  - entity: sensor.cyberpower_battery_charge
    name: Battery
  - entity: sensor.cyberpower_load
    name: Load
  - entity: sensor.cyberpower_input_voltage
    name: Input Voltage
```

### VeSync / Levoit LV600S Integration

Controls the Levoit LV600S humidifier via VeSync cloud API.

**Account:** vesync@htsn.io

**Entities:**
| Entity ID | Description |
|-----------|-------------|
| `humidifier.lv600s` | Main humidifier on/off control |
| `sensor.lv600s_humidity` | Built-in humidity sensor (reads high near mist) |
| `number.lv600s_mist_level` | Mist intensity (1-9) |
| `switch.lv600s_display` | Display on/off |
| `binary_sensor.lv600s_low_water` | Low water warning |
| `binary_sensor.lv600s_water_tank_lifted` | Tank removed detection |

### Oura Ring Integration (HACS)

Monitors sleep, activity, and health metrics from Oura Ring via HACS custom integration.

**Installation:** HACS → Integrations → Oura Ring v2

**OAuth Credentials (Oura Developer Portal):**
- Client ID: `e925a2a0-7767-4390-8b80-3a385a5b3ddc`
- Client Secret: `xFSFSfUPihet1foWQRLAMUQbL9-kChqT_CjtHHpAxZs`
- Redirect URI: `https://my.home-assistant.io/redirect/oauth`

**Key Entities:**
| Entity ID | Description |
|-----------|-------------|
| `sensor.oura_ring_readiness_score` | Daily readiness (0-100) |
| `sensor.oura_ring_sleep_score` | Sleep quality (0-100) |
| `sensor.oura_ring_current_heart_rate` | Current HR (bpm) |
| `sensor.oura_ring_average_sleep_heart_rate` | Average HR during sleep |
| `sensor.oura_ring_lowest_sleep_heart_rate` | Lowest HR during sleep |
| `sensor.oura_ring_temperature_deviation` | Body temp deviation (°C) |
| `sensor.oura_ring_spo2_average` | Blood oxygen (%) |
| `sensor.oura_ring_steps` | Daily step count |
| `sensor.oura_ring_activity_score` | Activity score (0-100) |

**Troubleshooting:**
- If sensors show "unavailable", check config entry state: `setup_retry` usually means API returned no data
- Force sync the Oura app on your phone, then reload the integration
- The integration polls Oura's API periodically; data updates after ring syncs to cloud

### HomeKit Controller / Homebridge Integration

Connects to Homebridge running on Mac Mini to access BLE devices (Govee sensors).

**Homebridge Details:**
- Host: Mac Mini (localhost)
- Port: 51826
- PIN: 031-45-154
- Config: `~/.homebridge/config.json`
- Logs: `~/.homebridge/homebridge.log`
- LaunchAgent: `~/Library/LaunchAgents/com.homebridge.server.plist`

**Govee H5074 Entities:**
| Entity ID | Description |
|-----------|-------------|
| `sensor.goveeh5074_5059_humidity` | Room humidity (accurate reading) |
| `sensor.goveeh5074_5059_temperature` | Room temperature |
| `sensor.goveeh5074_5059_battery` | Sensor battery level |

**Homebridge Management:**
```bash
# Check status
launchctl list | grep homebridge

# View logs
tail -f ~/.homebridge/homebridge.log

# Restart Homebridge
launchctl stop com.homebridge.server
launchctl start com.homebridge.server

# Stop Homebridge
launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist

# Start Homebridge
launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist
```

## Automations

### Guitar Room Humidity Control

Maintains 45-47% humidity for guitar storage (Lowden recommends 49% ±2%).

**Automations:**
| Automation | Trigger | Action |
|------------|---------|--------|
| `guitar_room_humidity_low_turn_on_humidifier` | Govee H5074 < 45% | Turn ON humidifier, set mist to 6 |
| `guitar_room_humidity_reached_turn_off_humidifier` | Govee H5074 > 47% | Turn OFF humidifier |

**Why two thresholds (hysteresis):**
- Prevents rapid on/off cycling
- 45% turn-on, 47% turn-off creates a 2% buffer
- Target range: 45-47% (conservatively below Lowden's 49% spec)

### Oura Ring Health & Sleep Automations

Uses Oura Ring biometrics for smart thermostat control and health alerts.

**Sleep/Wake Detection:**
| Automation | Trigger | Conditions | Action |
|------------|---------|------------|--------|
| `oura_sleep_detected_bedtime_mode` | HR < 55 bpm | Home, after 10pm | Thermostat → 66°F, front door light off, Telegram notify |
| `oura_wake_up_detected_morning_mode` | HR > 65 bpm | Home, 5-11am, thermostat < 68°F | Thermostat → 69°F, Telegram notify |

**Health Alerts:**
| Automation | Trigger | Action |
|------------|---------|--------|
| `oura_low_readiness_alert` | 8am daily, readiness < 70 | Telegram: suggest rest day |
| `oura_spo2_health_alert` | SpO2 < 94% | Urgent Telegram: health warning |
| `oura_fever_detection_alert` | Temp deviation > 1°C | Telegram: possible illness alert |
| `oura_sedentary_reminder` | 2pm weekdays, steps < 500 | Telegram: reminder to move |

**Sleep Comfort & Recovery:**
| Automation | Trigger | Conditions | Action |
|------------|---------|------------|--------|
| `oura_poor_sleep_recovery_mode` | 7am daily | Home, sleep score < 70 | Thermostat → 71°F (warmer for recovery) |
| `oura_sleep_temp_adjustment_too_hot` | Temp deviation > +0.5°C | Home, 10pm-6am, HR < 60 | Thermostat → 64°F |
| `oura_sleep_temp_adjustment_too_cold` | Temp deviation < -0.3°C | Home, 10pm-6am, HR < 60 | Thermostat → 68°F |

**Notification Setup:**
All notifications use `rest_command.notify_telegram` - ensure this is configured in `configuration.yaml`:
```yaml
rest_command:
  notify_telegram:
    url: "https://api.telegram.org/bot<TOKEN>/sendMessage"
    method: POST
    content_type: "application/json"
    payload: '{"chat_id": "<CHAT_ID>", "text": "{{ message }}"}'
```

## SSH Access (Terminal & SSH Add-on)

The Terminal & SSH add-on provides remote shell access to Home Assistant OS.

**Connection:**
```bash
ssh root@10.10.10.210 -p 22
```

**Authentication:** SSH key from Mac Mini (`~/.ssh/id_ed25519.pub`)

**Hostname:** `core-ssh`

**Features:**
- Direct shell access to Home Assistant OS
- Access to Home Assistant CLI (`ha` command)
- File system access for debugging

## MCP Server Integration

Home Assistant has a built-in Model Context Protocol (MCP) Server integration for AI assistant connectivity.

**Status:** Enabled (configured with "Assist" service)

**Endpoint:** `http://10.10.10.210:8123/api/mcp`

**Claude Code Configuration:** Added to `~/.cursor/mcp.json`:
```json
{
  "homeassistant": {
    "type": "http",
    "url": "http://10.10.10.210:8123/api/mcp",
    "headers": {
      "Authorization": "Bearer <HA_API_TOKEN>"
    }
  }
}
```

**Note:** The MCP server uses the Assist API to expose entities and services to AI clients.

## TODO

- [ ] Set static IP (currently DHCP at .210, should be .110)
- [x] Add API token to this document
- [x] Document installed integrations
- [x] Document automations
- [ ] Set up Traefik reverse proxy (ha.htsn.io)
- [x] Install Terminal & SSH add-on
- [x] Enable MCP Server integration