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
- **Motion Sensors** - Various locations
- **NUT (Network UPS Tools)** - UPS monitoring (added 2025-12-21)

### 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
```

## Automations

TODO: Document key automations

## TODO

- [ ] Set static IP (currently DHCP at .210, should be .110)
- [ ] Add API token to this document
- [ ] Document installed integrations
- [ ] Document automations
- [ ] Set up Traefik reverse proxy (ha.htsn.io)