cal/claude-home
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CLAUDE: Add comprehensive home automation planning documents

Browse Source 
- Add Home Assistant deployment guide with container architecture
- Document platform analysis comparing Home Assistant, OpenHAB, and Node-RED
- Add voice automation architecture with local/cloud hybrid approach
- Include implementation details for Rhasspy + Home Assistant integration
- Provide step-by-step deployment guides and configuration templates
- Document privacy-focused voice processing with local wake word detection

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cal Corum 2025-08-10 16:21:28 -05:00
parent df81d475ef
commit bd49e9d61d
4 changed files with 1661 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
.claude/plans/home-assistant-deployment-guide.md Normal file
View File

@ -0,0 +1,185 @@
# Home Assistant Deployment Architecture
## Recommended Deployment: Podman Container on Proxmox
### Why Podman Container vs Home Assistant OS?
- **Flexibility:** Full control over host system, easier customization
- **Integration:** Better integration with existing Proxmox infrastructure
- **Backup:** Standard container backup/restore workflows
- **Resources:** More efficient resource usage
- **Updates:** Granular update control
- **GPU Support:** Already proven working with your Tdarr setup
### Container Architecture
```bash
# Core Home Assistant container
podman run -d --name homeassistant \
--restart=unless-stopped \
-p 8123:8123 \
-v /path/to/config:/config \
-v /etc/localtime:/etc/localtime:ro \
--device /dev/ttyUSB0:/dev/ttyUSB0 \ # If you add Zigbee/Z-Wave
--network=host \
ghcr.io/home-assistant/home-assistant:stable
```
### Supporting Services Architecture
```yaml
# docker-compose.yml for full stack
version: '3.8'
services:
homeassistant:
container_name: homeassistant
image: ghcr.io/home-assistant/home-assistant:stable
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
privileged: true
network_mode: host
# Optional: Local database instead of SQLite
postgres:
container_name: ha-postgres
image: postgres:15
environment:
POSTGRES_DB: homeassistant
POSTGRES_USER: homeassistant
POSTGRES_PASSWORD: your-secure-password
volumes:
- ./postgres-data:/var/lib/postgresql/data
restart: unless-stopped
ports:
- "5432:5432"
# Optional: MQTT broker for device communication
mosquitto:
container_name: ha-mosquitto
image: eclipse-mosquitto:latest
restart: unless-stopped
ports:
- "1883:1883"
- "9001:9001"
volumes:
- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
- ./mosquitto/log:/mosquitto/log
# Optional: Node-RED for visual automation development
node-red:
container_name: ha-node-red
image: nodered/node-red:latest
restart: unless-stopped
ports:
- "1880:1880"
volumes:
- ./node-red-data:/data
```
## Migration Strategy
### Phase 1: Parallel Setup (Recommended)
1. **Deploy HA alongside Apple Home** (don't disturb current setup)
2. **Start with 1-2 test devices** (re-pair a couple of sensors)
3. **Build basic automations** to validate functionality
4. **Test for 1-2 weeks** to ensure stability
### Phase 2: Gradual Migration
1. **Re-pair devices in groups** (sensors first, then bulbs, etc.)
2. **Migrate automations one by one**
3. **Keep Apple Home as backup** until confident
### Phase 3: Full Cutover
1. **Remove devices from Apple Home**
2. **Decommission Apple TV hub role** (keep as media device)
3. **Full automation implementation**
## Device Integration Strategy
### Matter Devices (Your Current Setup)
- **Direct Integration:** HA's Matter support is mature as of 2024
- **No Hub Required:** HA can be the Matter controller
- **Thread Network:** Can share Thread network between platforms during migration
### Philips Hue Bridge
- **Option 1:** Keep bridge, integrate via Hue integration (easier)
- **Option 2:** Direct Zigbee control (requires Zigbee coordinator)
- **Recommendation:** Keep bridge initially, migrate later if needed
### Future Expansion Options
- **Zigbee:** Add Zigbee coordinator for non-Matter devices
- **Z-Wave:** Add Z-Wave stick for legacy devices
- **WiFi Devices:** Direct integration via HA's vast library
- **Custom Integrations:** HACS (Home Assistant Community Store)
## Automation Examples You Can Build
### Complex Scheduling
```yaml
# Advanced morning routine with conditions
automation:
- alias: "Smart Morning Routine"
trigger:
- platform: time
at: "06:30:00"
condition:
- condition: state
entity_id: binary_sensor.workday
state: 'on'
- condition: state
entity_id: person.your_name
state: 'home'
action:
- service: light.turn_on
target:
entity_id: light.bedroom_lights
data:
brightness_pct: 30
color_temp: 400
- delay: "00:15:00"
- service: light.turn_on
data:
brightness_pct: 80
```
### Presence Detection
```yaml
# Multi-factor presence with phone + door sensors
automation:
- alias: "Arrival Detection"
trigger:
- platform: state
entity_id: person.your_name
to: 'home'
- platform: state
entity_id: binary_sensor.front_door
to: 'on'
condition:
- condition: state
entity_id: person.your_name
state: 'home'
action:
- service: scene.turn_on
target:
entity_id: scene.arrival_lights
- service: climate.set_temperature
target:
entity_id: climate.main_thermostat
data:
temperature: 72
```
## Resource Requirements
### Minimum Specs
- **CPU:** 2 cores
- **RAM:** 2GB
- **Storage:** 20GB
- **Network:** Gigabit recommended for media streaming integration
### Your Proxmox Environment
- Should handle HA easily alongside existing containers
- Consider dedicating specific resources if running many integrations
- Network mode: host recommended for device discovery

94
.claude/plans/home-automation-platform-analysis.md Normal file
View File

@ -0,0 +1,94 @@
# Home Automation Platform Analysis
## Current Setup Analysis
- **Strengths:** Matter compliance, local Apple TV hub, established device ecosystem (10+ sensors, bulbs, Hue bridge)
- **Limitations:** Automation complexity ceiling, no external integrations, limited scheduling options
- **Infrastructure:** Proxmox host, Docker/Podman capability, network-local preference
## Platform Comparison
### 1. Home Assistant (Recommended)
**Pros:**
- Exceptional automation engine with complex logic, scheduling, and templating
- Best-in-class local operation (no cloud required)
- Massive device integration library (2000+ integrations)
- Matter support has matured significantly since 2024
- Strong community and documentation
- Supports both container and OS deployment
**Cons:**
- Initial setup learning curve (but much improved)
- Device re-pairing required
- Ongoing configuration maintenance
**Best For:** Users wanting maximum automation flexibility and local control
### 2. Node-RED + Apple Home (Hybrid)
**Pros:**
- Keep existing device pairings intact
- Visual flow-based automation programming
- Can integrate with Apple Home via HomeKit Controller
- Good for complex orchestrations
- Local operation possible
**Cons:**
- Limited by Apple Home's device exposure limitations
- Requires running alongside Apple Home ecosystem
- Less device integration options than HA
- May hit Apple Home API rate limits on complex automations
**Best For:** Users wanting advanced automations without disrupting existing setup
### 3. Home Assistant + Apple Home Bridge (Best of Both)
**Pros:**
- Keep Apple Home interface for family while gaining HA automation power
- All devices managed in HA, exposed to Apple Home selectively
- Maximum automation capabilities + familiar interface
- Local operation maintained
**Cons:**
- Most complex initial setup
- Device re-pairing required
- Two systems to maintain
## Architecture Recommendations
### Option A: Full Home Assistant Migration
1. Deploy HA in Proxmox container/VM
2. Re-pair all devices to HA directly
3. Build automations in HA
4. Use HA mobile app + dashboards
### Option B: HA + HomeKit Bridge Hybrid
1. Deploy HA in Proxmox container/VM
2. Re-pair devices to HA
3. Use HomeKit Controller integration to expose selected devices/automations back to Apple Home
4. Family continues using Apple Home interface, you get HA automation power
### Option C: Node-RED Overlay (Conservative)
1. Deploy Node-RED in container
2. Keep all devices paired to Apple Home
3. Use Node-RED HomeKit Controller to read Apple Home state
4. Build complex automations in Node-RED
5. Control devices through Apple Home APIs
## Technical Considerations
### Deployment Method: Podman Container (Recommended)
- More flexible than Home Assistant OS
- Easier backup/restore
- Better resource control in Proxmox
- GPU passthrough compatibility you already have
### Matter Device Strategy
- Modern Home Assistant has excellent Matter support
- Re-pairing is straightforward with Matter devices
- Thread network can be shared between platforms
## Next Steps Recommendation
Start with **Option A (Full HA Migration)** because:
1. Your technical comfort level makes setup manageable
2. Device re-pairing is acceptable to you
3. Local-only operation is priority
4. You want maximum automation flexibility
5. Container deployment aligns with your infrastructure

200
.claude/plans/voice-automation-architecture.md Normal file
View File

@ -0,0 +1,200 @@
# Voice-Controlled Automation Architecture
## Vision: Speech → Claude Code → Home Assistant Pipeline
### High-Level Flow
```
[Microphone] → [STT Engine] → [Command Parser] → [Claude Code API] → [Home Assistant] → [Actions]
```
## Component Architecture
### 1. Speech-to-Text (STT) Engine - Local Options
**Whisper (OpenAI) - Recommended**
- Excellent accuracy, runs locally
- Multiple model sizes (tiny to large)
- GPU acceleration available
- Container deployment: `openai/whisper`
**Alternative: Vosk**
- Lighter weight, faster response
- Good for command recognition
- Multiple language models available
### 2. Voice Activity Detection (VAD)
**Wake Word Detection**
- Porcupine (Picovoice) - local wake word detection
- Custom wake phrases: "Hey Claude", "Computer", etc.
- Always-listening with privacy protection
**Push-to-Talk Alternative**
- Hardware button integration
- Mobile app trigger
- Keyboard shortcut
### 3. Command Processing Pipeline
**Natural Language Parser**
- Claude Code interprets spoken commands
- Converts to Home Assistant service calls
- Handles context and ambiguity
**Command Categories:**
- Direct device control: "Turn off living room lights"
- Scene activation: "Set movie mode"
- Status queries: "What's the temperature upstairs?"
- Complex automations: "Start my morning routine"
### 4. Claude Code Integration
**API Bridge Service**
- Local service accepting STT output
- Formats requests to Claude Code API
- Maintains conversation context
- Returns structured HA commands
**Command Translation Examples:**
```
Speech: "Turn down the bedroom lights"
Claude: Interprets as light.turn_on service call
HA Command: {"service": "light.turn_on", "target": "light.bedroom", "brightness_pct": 30}
```
### 5. Home Assistant Integration
**RESTful API Integration**
- Direct API calls to HA instance
- WebSocket connection for real-time updates
- Authentication via long-lived access tokens
**Voice Response Integration**
- HA TTS service for confirmations
- Status announcements
- Error handling feedback
## Deployment Architecture
### Container Stack Addition
```yaml
# Add to existing HA docker-compose.yml
# STT Service
whisper-api:
container_name: ha-whisper
image: onerahmet/openai-whisper-asr-webservice:latest
ports:
- "9000:9000"
environment:
- ASR_MODEL=base # or small, medium, large
volumes:
- ./whisper-models:/root/.cache/whisper
deploy:
resources:
reservations:
devices:
- driver: nvidia # Optional GPU acceleration
count: 1
capabilities: [gpu]
# Voice Processing Bridge
voice-bridge:
container_name: ha-voice-bridge
build: ./voice-bridge # Custom service
ports:
- "8080:8080"
environment:
- CLAUDE_API_KEY=${CLAUDE_API_KEY}
- HA_URL=http://homeassistant:8123
- HA_TOKEN=${HA_TOKEN}
- WHISPER_URL=http://whisper-api:9000
volumes:
- ./voice-bridge-config:/config
depends_on:
- homeassistant
- whisper-api
```
### Hardware Requirements
**Microphone Setup:**
- USB microphone or audio interface
- Raspberry Pi with mic for remote rooms
- Existing smart speakers (if hackable)
**Processing Power:**
- Whisper base model: ~1GB RAM, CPU sufficient
- Whisper large model: ~2GB RAM, GPU recommended
- Your Proxmox setup can easily handle this
## Privacy & Security Considerations
### Local-First Design
- All STT processing on local hardware
- No cloud APIs for voice recognition
- Claude Code API calls only for command interpretation
- HA commands never leave local network
### Security Architecture
```
Internet ← [Firewall] ← [Claude API calls only] ← [Voice Bridge] ← [Local STT] ← [Microphone]
↓
[Home Assistant] ← [Local Network Only]
```
### Data Flow
1. **Audio capture** - stays local
2. **STT processing** - stays local
3. **Text command** - sent to Claude Code API (text only)
4. **HA commands** - executed locally
5. **No audio data** ever leaves your network
## Implementation Phases
### Phase 1: Core STT Integration
- Deploy Whisper container
- Basic speech-to-text testing
- Integration with HA via simple commands
### Phase 2: Claude Code Bridge
- Build voice-bridge service
- Integrate Claude Code API for command interpretation
- Basic natural language processing
### Phase 3: Advanced Features
- Wake word detection
- Multi-room microphone setup
- Context-aware conversations
- Voice response integration
### Phase 4: Optimization
- GPU acceleration for STT
- Custom wake words
- Conversation memory
- Advanced natural language understanding
## Example Use Cases
### Simple Commands
- "Turn off all lights"
- "Set temperature to 72 degrees"
- "Activate movie scene"
### Complex Requests
- "Turn on the lights in rooms where people are detected"
- "Start my bedtime routine in 10 minutes"
- "If it's going to rain tomorrow, close the garage door"
### Status Queries
- "What's the status of the security system?"
- "Are all the doors locked?"
- "Show me energy usage this month"
## Integration with Existing Plans
This voice system would layer on top of your planned HA deployment:
- **No changes** to core HA architecture
- **Additional containers** for voice processing
- **API integration** rather than HA core modifications
- **Gradual rollout** after HA migration is stable
The voice system becomes another automation trigger alongside:
- Time-based automations
- Sensor-based automations
- Manual app/dashboard controls
- **Voice commands via Claude Code**

1182
.claude/plans/voice-automation-implementation-details.md Normal file
View File

File diff suppressed because it is too large Load Diff