homelab-docs/AUTOMATION-WELCOME-HOME.md

# Welcome Home Automation

## Overview

Automatically turns on lights when you arrive home after sunset, creating a warm welcome.

## Status

- **Created:** 2026-01-14
- **State:** Active (enabled)
- **Entity ID:** `automation.welcome_home`
- **Last Triggered:** Never (newly created)

## How It Works

### Trigger
- Activates when **person.hutson** enters **zone.home** (100m radius)
- GPS tracking via device_tracker.honor (Honor phone)

### Conditions
The automation only runs when it's dark:
- After sunset (with 30-minute early start) **OR**
- Before sunrise

This prevents lights from turning on during daytime arrivals.

### Actions
When triggered, the following lights turn on:

| Light | Brightness | Purpose |
|-------|------------|---------|
| **Living Room** | 75% | Main ambient lighting |
| **Living Room Lamp** | 60% | Softer accent light |
| **Kitchen** | 80% | Task lighting for entry |

## Climate Control Note

No climate/heating entities were found in your Home Assistant setup. To add heating control in the future:
1. Integrate your thermostat/HVAC with Home Assistant
2. Add a climate action to this automation (see customization below)

## Customization

### Adjust Trigger Distance

The home zone has a 100m radius. To change this:

```yaml
# In Home Assistant UI: Settings → Areas → Zones → Home
# Or via API:
curl -X PUT \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 35.6542655, "longitude": -78.7417665, "radius": 150}' \
  "http://10.10.10.210:8123/api/config/zone/zone.home"
```

### Add More Lights

To add additional lights (e.g., Office, Front Porch):

```bash
HA_TOKEN="your-token-here"

# Get current config
curl -s -H "Authorization: Bearer $HA_TOKEN" \
  "http://10.10.10.210:8123/api/config/automation/config/welcome_home" > automation.json

# Edit automation.json to add more light actions
# Then update:
curl -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @automation.json \
  "http://10.10.10.210:8123/api/config/automation/config/welcome_home"
```

### Add Climate Control (when available)

Add this action to the automation:

```json
{
  "service": "climate.set_temperature",
  "target": {
    "entity_id": "climate.thermostat"
  },
  "data": {
    "temperature": 72,
    "hvac_mode": "heat"
  }
}
```

### Use a Scene Instead

To activate a predefined scene instead of individual lights:

```json
{
  "service": "scene.turn_on",
  "target": {
    "entity_id": "scene.living_room_relax"
  }
}
```

Available scenes include:
- `scene.living_room_relax`
- `scene.living_room_dimmed`
- `scene.all_nightlight`

## Testing

### Manual Trigger
```bash
HA_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwZThjZmJjMzVlNDA0NzYwOTMzMjg3MTQ5ZjkwOGU2NyIsImlhdCI6MTc2NTk5MjQ4OCwiZXhwIjoyMDgxMzUyNDg4fQ.r743tsb3E5NNlrwEEu9glkZdiI4j_3SKIT1n5PGUytY"

curl -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "automation.welcome_home"}' \
  "http://10.10.10.210:8123/api/services/automation/trigger"
```

### Check Last Triggered
```bash
curl -s -H "Authorization: Bearer $HA_TOKEN" \
  "http://10.10.10.210:8123/api/states/automation.welcome_home" | \
  python3 -c "import json, sys; print(json.load(sys.stdin)['attributes']['last_triggered'])"
```

## Disable/Enable

### Disable
```bash
curl -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "automation.welcome_home"}' \
  "http://10.10.10.210:8123/api/services/automation/turn_off"
```

### Enable
```bash
curl -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "automation.welcome_home"}' \
  "http://10.10.10.210:8123/api/services/automation/turn_on"
```

## Monitoring

### View in Home Assistant UI
1. Go to http://10.10.10.210:8123
2. Settings → Automations & Scenes → Automations
3. Find "Welcome Home"

### Check Automation State
The automation is currently: **ON**

### Troubleshooting

If the automation doesn't trigger:
1. Check person.hutson GPS accuracy (should be < 50m)
2. Verify zone.home coordinates match your actual home location
3. Check automation was triggered during dark hours
4. Review Home Assistant logs for errors

## Related Documentation

- [Home Assistant API](./HOMEASSISTANT.md)
- [Personal Assistant Integration](../personal-assistant/CLAUDE.md)
- [Smart Home Control](../personal-assistant/docs/services-matrix.md)

## Future Enhancements

Potential improvements:
- Add motion sensor override (don't trigger if motion already detected)
- Integrate with calendar (different scenes for work vs personal time)
- Add climate control when thermostat is integrated
- Create "leaving home" automation to turn off lights
- Add notification to phone when automation triggers
- Adjust brightness based on time of day
- Add office lights during work hours

---
*Created: 2026-01-14*  
*Last Updated: 2026-01-14*