Home Assistant: Device Control Platform
Home Assistant serves as the device automation foundation of HALO, running as a containerized service on Nexus and providing comprehensive control over smart home devices, scenes, automations, and sensors. As the industry-standard open-source home automation platform, it brings mature and battle-tested device integration to the ecosystem, handling all physical device interactions while Apollo, Omnia, and n8n workflows provide higher-level orchestration and intelligence.
With support for thousands of device types and brands, Home Assistant acts as the universal translator between HALO’s high-level automation logic and the diverse landscape of smart home protocols. It normalizes the differences between Zigbee sensors, Wi-Fi cameras, Z-Wave locks, and cloud-based services, presenting a consistent interface that other HALO components can rely on.
Purpose and Scope
Home Assistant’s role within HALO is to manage all device-level interactions—discovering devices, maintaining connections, exposing current states, and executing control commands. It handles the complexity of different communication protocols (Zigbee, Z-Wave, MQTT, HTTP) so that higher-level systems like Apollo and Omnia can work with devices through a unified API.
The platform excels at state-based automation, where device states trigger actions or conditions enable different behaviors. While n8n handles complex multi-system workflows and Apollo provides intelligent reasoning, Home Assistant focuses on reliable, low-latency device control and state tracking.
Beyond simple device control, Home Assistant provides scene management (coordinated multi-device states), script execution (reusable action sequences), and helper entities (input booleans, numbers, selects) that enable sophisticated automation logic.
Architecture and Integration
Deployment Model
Home Assistant runs as a containerized service on Nexus within the Docker infrastructure. All configuration files are stored in the HALO monorepo for version control and consistency:
halo/
└── configs/home-assistant/
├── configuration.yaml # Main configuration
├── automations.yaml # Automation definitions
├── scenes.yaml # Scene definitions
├── scripts.yaml # Reusable scripts
├── customize.yaml # Entity customizations
└── integrations/ # Integration configs
├── zigbee2mqtt.yaml
├── cameras.yaml
└── sensors.yaml
This approach keeps configuration version-controlled in the monorepo while running Home Assistant as a standard Docker container on Nexus, accessible through Traefik at https://halo.local/ha.
Communication Patterns
HALO components interact with Home Assistant through multiple channels:
REST API: HTTP-based interface for device control and state queries. This is the primary interface for Omnia widgets and Apollo tool calling. The API provides endpoints for calling services, querying states, and retrieving configuration. Accessible through Traefik at https://halo.local/ha/api.
WebSocket API: Real-time bidirectional communication for state updates and event streaming. Omnia widgets can subscribe to state changes and receive immediate updates when devices change, ensuring the UI always reflects current status.
MQTT: Lightweight messaging for device integration and event publishing. Home Assistant publishes device states to MQTT topics on the Mosquitto broker running on Nexus, enabling reactive automation in n8n and Node-RED.
Home Assistant CLI: Command-line management interface for configuration checks, service calls, and troubleshooting.
Integration with HALO Systems
Omnia Integration
Omnia widgets leverage Home Assistant to display and control devices:
State Display Widgets: Show current temperature, humidity, motion sensor status, door/window states, and other sensor readings. WebSocket subscriptions ensure instant updates when values change.
Control Widgets: Provide buttons, sliders, and toggles for controlling lights (brightness, color), switches, climate systems, locks, and covers. User interactions trigger REST API calls to execute the desired actions.
Historical Data: Display sensor graphs and historical trends using Home Assistant’s recorder component data.
Automation Status: Show which automations are enabled/disabled and provide controls to trigger or toggle them.
Example widget implementations might include a light control panel, climate dashboard, security status display, or energy monitoring visualization.
Apollo Integration
Apollo uses tool calling to interact with Home Assistant naturally through network API calls:
Device Queries: When asked “What’s the temperature upstairs?”, Apollo calls the tool to query Home Assistant’s REST API at https://halo.local/ha/api for sensor.upstairs_temperature and returns a natural language response with context.
Device Control: Requests like “Turn off all the lights” translate to service calls to Home Assistant’s API targeting appropriate entity groups, with confirmation of successful execution.
Scene Activation: Commands like “Set the house to bedtime mode” trigger scene activation through the API while explaining what changes are being made.
Automation Inspection: Apollo can examine automation definitions through the API and explain why certain automations triggered or what conditions prevented them from running.
This natural language interface makes device control accessible without memorizing entity IDs or service names.
n8n Workflow Integration
n8n workflows orchestrate complex multi-system operations involving Home Assistant through API calls:
State Change Triggers: Workflows can react to device state changes published to MQTT by Home Assistant (motion detected, door opened, temperature crossed threshold) and execute multi-step responses.
Service Calls: Workflows call Home Assistant services through its REST API as part of larger automation sequences that might also involve sending notifications, updating databases, or calling external APIs.
Data Queries: Workflows can retrieve current states, historical data, or configuration information through the API to make intelligent automation decisions.
Coordinated Actions: Morning routines, security responses, and energy optimization workflows orchestrate Home Assistant devices alongside other HALO systems through coordinated API calls.
Device Integrations
Current Integrations
Zigbee2MQTT: All Zigbee devices connect through the Zigbee2MQTT bridge, which exposes them to Home Assistant via MQTT discovery. This includes sensors (temperature, motion, contact, humidity), lights, switches, and other Zigbee-compatible devices. The Sonoff Zigbee 3.0 USB Dongle Plus serves as the coordinator.
Reolink Cameras: Doorbell and camera integrations provide motion notifications, camera control, and integration with automation triggers. While Frigate handles video processing, Home Assistant receives camera events for automation purposes.
MQTT Devices: Custom IoT devices and integrations publish their state to MQTT topics, which Home Assistant discovers and exposes as entities.
Planned Integrations
Future device integrations on the roadmap include:
- Z-Wave Devices: Smart locks, garage door controllers, and other Z-Wave devices using a USB Z-Wave controller
- Energy Monitoring: Smart plugs and whole-home energy meters for tracking consumption patterns
- Voice Assistants: Local speech recognition using Piper (text-to-speech) and Whisper (speech-to-text) for voice control
- Weather Stations: Local weather data collection for accurate automation triggers
- Presence Detection: Room-level presence using ESPresense or room-assistant for more granular automation
Automation Examples
Time-Based Automations
Time-based automations trigger at specific times or relative to sunrise/sunset:
# Morning routine - gradual lighting
automation:
- alias: "Morning Lights Fade In"
trigger:
- platform: time
at: "06:30:00"
condition:
- condition: state
entity_id: input_boolean.weekday_routine
state: "on"
action:
- service: light.turn_on
target:
entity_id: light.bedroom_lights
data:
brightness_pct: 1
- delay: "00:00:01"
- service: light.turn_on
target:
entity_id: light.bedroom_lights
data:
brightness_pct: 100
transition: 900 # 15-minute gradual fade
This creates a sunrise simulation effect, starting dim and brightening over 15 minutes.
State-Based Automations
State-based automations react to device state changes:
# Automatically turn off lights when no motion
automation:
- alias: "Auto-off Living Room Lights"
trigger:
- platform: state
entity_id: binary_sensor.living_room_motion
to: "off"
for:
minutes: 10
action:
- service: light.turn_off
target:
entity_id: light.living_room_lights
data:
transition: 3
This implements occupancy-based lighting, turning off lights 10 minutes after the last motion detection.
Event-Based Automations
Event-based automations respond to specific events:
# Security notification on door sensor
automation:
- alias: "Front Door Alert"
trigger:
- platform: state
entity_id: binary_sensor.front_door
to: "on"
condition:
- condition: state
entity_id: alarm_control_panel.home
state: "armed_away"
action:
- service: notify.mobile_app
data:
message: "Front door opened while away!"
title: "Security Alert"
data:
priority: high
This sends high-priority notifications when security-relevant events occur in unexpected contexts.
Scenes and Scripts
Scene Management
Scenes capture coordinated device states that can be activated together:
# Evening relaxation scene
scene:
- name: "Evening Relax"
entities:
light.living_room_lights:
state: on
brightness: 128
color_temp: 400 # Warm white
light.kitchen_lights:
state: off
media_player.living_room_tv:
state: on
source: "Netflix"
climate.downstairs:
temperature: 70
Activating this scene with scene.turn_on sets all devices to their defined states simultaneously.
Reusable Scripts
Scripts define reusable action sequences with parameters:
# Notification script with configurable message
script:
notify_household:
sequence:
- service: notify.mobile_app_phone1
data:
message: ""
title: ""
- service: notify.mobile_app_phone2
data:
message: ""
title: ""
fields:
message:
description: "Message to send"
example: "Laundry is done"
title:
description: "Notification title"
example: "Home Alert"
This script can be called from automations or other scripts with custom messages, reducing duplication.
Configuration Management
Configuration Files
All Home Assistant configuration is version-controlled in the monorepo:
# configuration.yaml - main configuration
homeassistant:
name: HALO
latitude: !secret home_latitude
longitude: !secret home_longitude
unit_system: imperial
time_zone: America/New_York
# Load split configurations
automation: !include automations.yaml
scene: !include scenes.yaml
script: !include scripts.yaml
customize: !include customize.yaml
# Core integrations
mqtt:
broker: mosquitto.local
discovery: true
recorder:
db_url: !secret recorder_db_url
purge_keep_days: 30
logger:
default: info
logs:
homeassistant.components.mqtt: debug
Secrets Management
Sensitive values are stored in secrets.yaml, which is excluded from version control:
# secrets.yaml (example - not committed to git)
home_latitude: 40.7128
home_longitude: -74.0060
api_key_weather: abc123def456
mqtt_password: secure_password_here
recorder_db_url: postgresql://user:pass@postgres/homeassistant
This pattern keeps credentials out of version control while maintaining configuration portability.
Security and Access Control
Network Security
Home Assistant runs as a container on Nexus within the isolated Docker network infrastructure. API access flows through Traefik reverse proxy with TLS encryption. External access, when needed, is controlled through Traefik’s authentication middleware and access control policies.
Authentication
User accounts support role-based access control, with different permissions for administrators, regular users, and guests. Long-lived access tokens enable service-to-service communication (Apollo, n8n, Omnia) without exposing user credentials. Multi-factor authentication can be enabled for sensitive operations.
Audit Logging
All device control actions are logged with timestamp, user, and entity information. State change history is retained in the recorder database for forensic analysis. Integration with HALO-wide log aggregation provides centralized audit capabilities.
Testing and Development
Configuration Validation
Home Assistant provides built-in validation tools:
# Check configuration before restart
ha core check
# Reload automations without restart
ha core reload automations
# Reload scripts
ha core reload scripts
These commands enable iterative development without full system restarts.
Developer Tools
The Home Assistant web interface includes developer tools:
Services: Test service calls with custom parameters before incorporating them into automations
Templates: Interactive template editor for testing Jinja2 expressions used in automations
States: Browse all entity states and attributes in real-time
Events: Monitor the event bus to understand automation triggers
These tools accelerate development and troubleshooting.
Example Integrations
Omnia Light Control Widget
JavaScript code in an Omnia widget can toggle lights:
async function toggleLight(entityId) {
const response = await fetch(
"http://homeassistant.local:8123/api/services/light/toggle",
{
method: "POST",
headers: {
Authorization: `Bearer ${HA_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
entity_id: entityId,
}),
}
);
return response.json();
}
n8n Temperature Monitor Workflow
An n8n workflow monitors temperature and adjusts climate control:
Trigger: Schedule (every 5 minutes)
↓
HTTP Request: GET /api/states/sensor.living_room_temperature
↓
Switch: temperature > 78°F
↓
HTTP Request: POST /api/services/climate/set_temperature
Body: { entity_id: "climate.main_ac", temperature: 72 }
Apollo Tool Definition
Python code in Apollo defines Home Assistant tools:
@tool
def get_device_state(entity_id: str) -> dict:
"""Get the current state of a Home Assistant device."""
response = requests.get(
f"{HA_URL}/api/states/{entity_id}",
headers={"Authorization": f"Bearer {HA_TOKEN}"}
)
return response.json()
@tool
def call_service(domain: str, service: str, entity_id: str, **kwargs) -> dict:
"""Call a Home Assistant service."""
response = requests.post(
f"{HA_URL}/api/services/{domain}/{service}",
headers={"Authorization": f"Bearer {HA_TOKEN}"},
json={"entity_id": entity_id, **kwargs}
)
return response.json()
Roadmap and Future Development
Future enhancements to Home Assistant integration include:
Local Voice Control: Deploy the Home Assistant voice stack (Piper for TTS, Whisper for STT) enabling voice commands processed entirely on-premises
Advanced Presence Detection: Room-level presence tracking using ESPresense or similar solutions for more granular automation triggers
Energy Optimization: Integration with utility APIs for time-of-use rate tracking, enabling cost-aware automation decisions
Automated Backups: Regular configuration backups to the HALO Archive with automated testing of restore procedures
Dashboard Templates: Pre-configured Lovelace dashboards for common use cases that can be imported into Omnia widgets
Enhanced Integration Testing: Automated tests for critical automations to catch configuration errors before deployment
Monorepo Integration
Home Assistant configuration is part of the HALO monorepo structure:
- Configuration Location:
configs/home-assistant/stores all YAML files - Container Deployment:
nexus/compose/home-assistant.ymldefines the Docker container - API Access: Available at
https://halo.local/ha(proxied through Traefik) - Integration Points: Called by Apollo tools, n8n workflows, and Omnia widgets
- Data Flow: Devices → Home Assistant → MQTT/API → HALO workflows → Actions
This organization keeps configuration versioned alongside the rest of HALO while running Home Assistant as a containerized service on Nexus with proper network isolation and ingress control.
Related Documentation
For device inventory and details, see Home Assistant Devices.
For integration with other HALO systems, see Nexus Overview, Apollo, and Frigate.
For workflow automation patterns, see n8n Workflows.