hutson/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
homelab-docs/HOMEASSISTANT.md
Hutson 80b6ab43d3 Auto-sync: 20260120-145048
2026-01-20 14:50:49 -05:00

11 KiB
Raw Permalink Blame History

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

# 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

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'

List Entities by Domain

# 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

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

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:

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

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:

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:

{
  "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)
  • Add API token to this document
  • Document installed integrations
  • Document automations
  • Set up Traefik reverse proxy (ha.htsn.io)
  • Install Terminal & SSH add-on
  • Enable MCP Server integration
Reference in New Issue View Git Blame Copy Permalink