diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index b93108b44c..6dd8bb0505 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -114,6 +114,8 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | `SIGNAL_ACCOUNT` | Bot phone number in E.164 format (e.g., `+15551234567`) | | `SIGNAL_ALLOWED_USERS` | Comma-separated E.164 phone numbers or UUIDs | | `SIGNAL_GROUP_ALLOWED_USERS` | Comma-separated group IDs, or `*` for all groups (omit to disable groups) | +| `HASS_TOKEN` | Home Assistant Long-Lived Access Token (enables HA platform + tools) | +| `HASS_URL` | Home Assistant URL (default: `http://homeassistant.local:8123`) | | `MESSAGING_CWD` | Working directory for terminal in messaging (default: `~`) | | `GATEWAY_ALLOWED_USERS` | Comma-separated user IDs allowed across all platforms | | `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlist (`true`/`false`, default: `false`) | diff --git a/website/docs/user-guide/messaging/homeassistant.md b/website/docs/user-guide/messaging/homeassistant.md index b47a229bd6..1d14d883c7 100644 --- a/website/docs/user-guide/messaging/homeassistant.md +++ b/website/docs/user-guide/messaging/homeassistant.md @@ -122,31 +122,53 @@ Set living room lights to blue at 50% brightness ## Gateway Platform: Real-Time Events -The Home Assistant gateway adapter connects via WebSocket and subscribes to `state_changed` events. When a device state changes, it's forwarded to the agent as a message. +The Home Assistant gateway adapter connects via WebSocket and subscribes to `state_changed` events. When a device state changes and matches your filters, it's forwarded to the agent as a message. ### Event Filtering -Configure which events the agent sees via platform config in the gateway: +:::warning Required Configuration +By default, **no events are forwarded**. You must configure at least one of `watch_domains`, `watch_entities`, or `watch_all` to receive events. Without filters, a warning is logged at startup and all state changes are silently dropped. +::: -```python -# In platform extra config -{ - "watch_domains": ["climate", "binary_sensor", "alarm_control_panel"], - "watch_entities": ["sensor.front_door"], - "ignore_entities": ["sensor.uptime", "sensor.cpu_usage"], - "cooldown_seconds": 30 -} +Configure which events the agent sees in `~/.hermes/config.yaml` under the Home Assistant platform's `extra` section: + +```yaml +# ~/.hermes/config.yaml +messaging: + platforms: + homeassistant: + extra: + # Watch specific domains (recommended) + watch_domains: + - climate + - binary_sensor + - alarm_control_panel + - light + + # Watch specific entities (in addition to domains) + watch_entities: + - sensor.front_door_battery + + # Ignore noisy entities + ignore_entities: + - sensor.uptime + - sensor.cpu_usage + - sensor.memory_usage + + # Per-entity cooldown (seconds) + cooldown_seconds: 30 ``` | Setting | Default | Description | |---------|---------|-------------| -| `watch_domains` | *(all)* | Only watch these entity domains | -| `watch_entities` | *(all)* | Only watch these specific entities | -| `ignore_entities` | *(none)* | Always ignore these entities | +| `watch_domains` | *(none)* | Only watch these entity domains (e.g., `climate`, `light`, `binary_sensor`) | +| `watch_entities` | *(none)* | Only watch these specific entity IDs | +| `watch_all` | `false` | Set to `true` to receive **all** state changes (not recommended for most setups) | +| `ignore_entities` | *(none)* | Always ignore these entities (applied before domain/entity filters) | | `cooldown_seconds` | `30` | Minimum seconds between events for the same entity | :::tip -Without any filters, the agent receives **all** state changes, which can be noisy. For practical use, set `watch_domains` to the domains you care about (e.g., `climate`, `binary_sensor`, `alarm_control_panel`). +Start with a focused set of domains — `climate`, `binary_sensor`, and `alarm_control_panel` cover the most useful automations. Add more as needed. Use `ignore_entities` to suppress noisy sensors like CPU temperature or uptime counters. ::: ### Event Formatting diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md index 8ff3a49e7b..97c4dbddae 100644 --- a/website/docs/user-guide/messaging/index.md +++ b/website/docs/user-guide/messaging/index.md @@ -1,38 +1,38 @@ --- sidebar_position: 1 title: "Messaging Gateway" -description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, or Email — architecture and setup overview" +description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant — architecture and setup overview" --- # Messaging Gateway -Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, or Email. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages. +Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages. ## Architecture ```text -┌─────────────────────────────────────────────────────────────────┐ -│ Hermes Gateway │ -├─────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌───────┐│ -│ │ Telegram │ │ Discord │ │ WhatsApp │ │ Slack │ │ Signal │ │ Email ││ -│ │ Adapter │ │ Adapter │ │ Adapter │ │Adapter │ │Adapter │ │Adapter││ -│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ └───┬────┘ └──┬────┘│ -│ │ │ │ │ │ │ │ -│ └─────────────┼────────────┼────────────┼──────────┼─────────┘ │ -│ │ │ -│ ┌────────▼────────┐ │ -│ │ Session Store │ │ -│ │ (per-chat) │ │ -│ └────────┬────────┘ │ -│ │ │ -│ ┌────────▼────────┐ │ -│ │ AIAgent │ │ -│ │ (run_agent) │ │ -│ └─────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────┘ +┌───────────────────────────────────────────────────────────────────────────────┐ +│ Hermes Gateway │ +├───────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌────┐│ +│ │ Telegram │ │ Discord │ │ WhatsApp │ │ Slack │ │Signal │ │ Email │ │ HA ││ +│ │ Adapter │ │ Adapter │ │ Adapter │ │Adapter│ │Adapter│ │Adapter│ │Adpt││ +│ └────┬─────┘ └────┬────┘ └────┬─────┘ └──┬────┘ └──┬────┘ └──┬────┘ └─┬──┘│ +│ │ │ │ │ │ │ │ │ +│ └─────────────┴───────────┴───────────┴─────────┴─────────┴────────┘ │ +│ │ │ +│ ┌────────▼────────┐ │ +│ │ Session Store │ │ +│ │ (per-chat) │ │ +│ └────────┬────────┘ │ +│ │ │ +│ ┌────────▼────────┐ │ +│ │ AIAgent │ │ +│ │ (run_agent) │ │ +│ └─────────────────┘ │ +│ │ +└───────────────────────────────────────────────────────────────────────────────┘ ``` Each platform adapter receives messages, routes them through a per-chat session store, and dispatches them to the AIAgent for processing. The gateway also runs the cron scheduler, ticking every 60 seconds to execute any due jobs. @@ -204,6 +204,7 @@ Each platform has its own toolset: | Slack | `hermes-slack` | Full tools including terminal | | Signal | `hermes-signal` | Full tools including terminal | | Email | `hermes-email` | Full tools including terminal | +| Home Assistant | `hermes-gateway` | Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services) | ## Next Steps @@ -213,3 +214,4 @@ Each platform has its own toolset: - [WhatsApp Setup](whatsapp.md) - [Signal Setup](signal.md) - [Email Setup](email.md) +- [Home Assistant Integration](homeassistant.md)