# 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)
- **VeSync** - Levoit humidifier control (added 2026-01-14)
- **HomeKit Controller** - Homebridge bridge for Govee sensors (added 2026-01-14)

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

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

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