Home Assistant Hub

SKILL.md

---
name: home-assistant-hub
description: Home Assistant real-time monitoring, alert rules, voice notifications on Echo, and Telegram delivery via WebSocket + polling. Use when: HA monitoring, smart home automation, temperature alerts, door/garage sensors, TTS announcements, battery alerts.
homepage: https://github.com/openclaw/openclaw
metadata:
  {
    "openclaw":
      {
        "emoji": "🏡",
        "requires": { "bins": ["node"] },
      },
  }
---

# ⚠️ Privacy & Security Note

**This skill sends data to external services.** Alert messages (occupancy, sensor states, routines) are transmitted via Telegram and/or Echo devices. Do not include sensitive personal information in alert templates.

All secrets (`ha_token`, `telegram_bot_token`, `telegram_chat_id`) are stored in `config/hub.json` which is gitignored by `.gitignore`. Never share or commit this file.

# Home Assistant Hub

Real-time Home Assistant monitoring, alert rules, TTS voice notifications on Echo devices, and Telegram delivery for OpenClaw.

## Quick Start

```bash
# Setup (interactive)
node scripts/ha-hub.js setup

# Test connection
node scripts/ha-hub.js test

# Start monitoring
node scripts/ha-hub.js start

# Check status
node scripts/ha-hub.js status

# Stop monitoring
node scripts/ha-hub.js stop
```

## Alert Rules

### Add rule interactively
```bash
node scripts/ha-hub.js add-rule
```

### Add rules via JSON
```bash
node scripts/ha-hub.js add-rules << 'EOF'
[
  {
    "name": "Garage aperto",
    "entity_id": "binary_sensor.garage_door",
    "condition": "state",
    "value": "on",
    "cooldown": 300,
    "title": "Garage",
    "template": "Il garage è aperto!"
  },
  {
    "name": "Batteria bassa",
    "entity_id": "sensor.battery_level",
    "condition": "below",
    "value": "20",
    "cooldown": 600,
    "title": "🪫 Batteria",
    "template": "Batteria al {{state}}% — serve attenzione"
  }
]
EOF
```

### List rules
```bash
node scripts/ha-hub.js rules
```

### Rule conditions
- `state` — state equals value
- `not_state` — state not equals value  
- `above` — numeric state above value
- `below` — numeric state below value
- `changed` — always trigger on change

## Voice Notifications (TTS)

Send voice announcements to Echo devices:

```bash
# All Echo devices (configured in hub.json)
node scripts/ha-hub.js tts "La cena è pronta" all

# Single device (when configured individually)
node scripts/ha-hub.js tts "Ciao" echo_pop
node scripts/ha-hub.js tts "Attenzione" echo_show
```

Echo device IDs are configured in `config/hub.json` under `echo_devices`:
```json
"echo_devices": {
  "all_devices_announce_id": "your_announce_group_device_id",
  "echo_pop_device_id": "",
  "echo_show_device_id": ""
}
```

## Telegram Integration

Notifications are delivered to Telegram when configured:

```bash
# Restart telegram-deliver after changing hub.json
node scripts/telegram-deliver.js start
node scripts/telegram-deliver.js status
node scripts/telegram-deliver.js stop
```

Telegram settings in `hub.json`:
```json
"telegram_bot_token": "your_bot_token",
"telegram_chat_id": "your_chat_id",
"notification_channel": "telegram"
```

## On-Demand Commands

```bash
# HA info
node scripts/ha-cmd.js info

# All states
node scripts/ha-cmd.js state

# Specific entity
node scripts/ha-cmd.js state get light.living_room

# Filter by domain
node scripts/ha-cmd.js state list light

# Call service
node scripts/ha-cmd.js call light.turn_on entity_id=light.living_room

# Scenes, persons, areas
node scripts/ha-cmd.js scenes
node scripts/ha-cmd.js persons
node scripts/ha-cmd.js areas
```

## Architecture

```
skills/home-assistant-hub/
├── SKILL.md              ← this file
├── config/
│   ├── hub.json          ← runtime config (secrets)
│   └── hub.example.json  ← template (commit to repo)
├── scripts/
│   ├── ha-hub.js         ← WebSocket + polling hub + TTS
│   ├── telegram-deliver.js ← Telegram notification delivery
│   └── ha-cmd.js         ← on-demand commands
├── delivered/            ← delivered notification history
├── logs/                 ← daily rotation logs
├── references/
│   └── setup.md          ← detailed setup guide
├── start.sh              ← quick start script
└── .gitignore
```

## Hub Config (`config/hub.json`)

Use `hub.example.json` as a template:

```bash
cp config/hub.example.json config/hub.json
# Edit hub.json with your credentials
```

```json
{
  "ha_url": "http://homeassistant.local:8123",
  "ha_token": "your-long-lived-token",
  "poll_interval": 10,
  "rules": [...],
  "notification_channel": "telegram",
  "quiet_hours": { "enabled": false, "start": "23:00", "end": "07:00" },
  "on_demand": { "enabled": true, "port": 9123 },
  "telegram_bot_token": "...",
  "telegram_chat_id": "...",
  "echo_devices": {
    "all_devices_announce_id": "",
    "echo_pop_device_id": "",
    "echo_show_device_id": ""
  }
}
```

## Notification Flow

1. Hub detects state change matching a rule
2. Writes notification JSON to `notifications/`
3. `telegram-deliver` picks up and sends to Telegram
4. If `tts_echo` is enabled in config, also sends voice notification to Echo
5. Quiet hours suppress during configured window (e.g., 22:00–08:00)

## Troubleshooting

- Connection fails → check token in HA (Profile → Long-Lived Access Tokens)
- No alerts → verify entity IDs with `node scripts/ha-cmd.js state`
- WS fails → polling fallback activates automatically
- Duplicate alerts → increase `cooldown` in rule config
- TTS not working → verify Echo device_id in hub.json via HA developer tools
- Telegram not delivering → check bot_token and chat_id in hub.json

## Quiet Hours

Disable alerts during sleep in `config/hub.json`:

```json
"quiet_hours": {
  "enabled": true,
  "start": "22:00",
  "end": "08:00"
}
```

Rules during quiet hours are silently suppressed.