- Create motion-light-control.yaml blueprint for motion-activated lighting - Includes configurable quiet hours to prevent activation during night - Supports multiple lights with brightness and transition controls - Add CLAUDE.md documentation for repository guidance 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
This is a Home Assistant Blueprints repository containing reusable automation templates for smart home systems. All blueprints are YAML configuration files that can be imported directly into Home Assistant.
|
|
|
|
## Common Development Tasks
|
|
|
|
### Testing & Validation
|
|
- **Blueprint Validation**: Use Home Assistant's built-in blueprint importer to validate YAML syntax
|
|
- **Template Testing**: Test Jinja2 templates in Home Assistant Developer Tools → Template tab
|
|
- **Live Testing**: Import blueprint into Home Assistant and create test automation to verify behavior
|
|
|
|
### Working with Blueprints
|
|
When modifying or creating blueprints:
|
|
1. Follow the standard Home Assistant blueprint schema structure
|
|
2. Always include comprehensive descriptions for user clarity
|
|
3. Provide sensible defaults for all input parameters
|
|
4. Use proper selectors for entity inputs (entity, device, area selectors)
|
|
5. Test templates for edge cases (unavailable entities, null states)
|
|
|
|
## Architecture & Code Structure
|
|
|
|
### Blueprint Components
|
|
Every blueprint follows this structure:
|
|
- **blueprint:** Metadata section with name, description, domain (always "automation")
|
|
- **input:** User-configurable parameters with selectors and defaults
|
|
- **trigger:** Event triggers (state changes, time patterns, device events)
|
|
- **condition:** Optional conditional logic
|
|
- **variables:** Template variables for complex logic
|
|
- **action:** Automation actions to execute
|
|
- **mode:** Execution mode (single, restart, queued, parallel)
|
|
|
|
### Key Patterns
|
|
|
|
#### Template Safety
|
|
Always use fallback defaults in templates:
|
|
```yaml
|
|
{{ states('sensor.temperature') | float(0) }}
|
|
{{ state_attr('device.battery', 'battery_level') | int(100) }}
|
|
```
|
|
|
|
#### Entity Expansion
|
|
Use expand() for working with entity groups:
|
|
```yaml
|
|
{% for entity_id in expand(battery_sensors) | map(attribute='entity_id') | list %}
|
|
```
|
|
|
|
#### Z-Wave Event Handling
|
|
Z-Wave central scene events follow this pattern:
|
|
```yaml
|
|
trigger:
|
|
- platform: event
|
|
event_type: zwave_js_value_notification
|
|
event_data:
|
|
command_class: 91 # Central Scene
|
|
property_key: "001" # Scene ID
|
|
```
|
|
|
|
#### Complex State Calculations
|
|
Use namespace objects for accumulating values:
|
|
```yaml
|
|
{% set ns = namespace(total=0, count=0) %}
|
|
{% for entity in entities %}
|
|
{% set ns.total = ns.total + states(entity) | float(0) %}
|
|
{% set ns.count = ns.count + 1 %}
|
|
{% endfor %}
|
|
```
|
|
|
|
## Blueprint Categories
|
|
|
|
### HVAC & Climate Control
|
|
- **hvac-failure-monitor.yaml**: Monitors HVAC performance using temperature differentials
|
|
- **fan-management.yaml**: Bathroom fan automation with light triggers
|
|
- **fan-cadence.yaml**: Periodic fan cycling with override protection
|
|
|
|
### Power & Energy
|
|
- **power-monitoring.yaml**: Detects power spikes for appliance identification
|
|
- **battery-monitor.yaml**: Multi-device battery level monitoring
|
|
|
|
### Smart Switches & Scenes
|
|
- **multi-tap-automation.yaml**: Z-Wave switch multi-tap scene control
|
|
- **multi-tap-automation-homeseer-and-zooz.yaml**: Enhanced multi-tap with HomeSeer/Zooz support
|
|
- **indication.yaml**: HomeSeer WD200+ LED indicator control
|
|
|
|
### Security & Utility
|
|
- **simulated-presence.yaml**: Random light automation for security
|
|
- **state-opposite.yaml**: Bidirectional entity state synchronization
|
|
|
|
## Important Implementation Notes
|
|
|
|
### Input Validation
|
|
- Use proper selector types (number with min/max, boolean, entity with domain filter)
|
|
- Always provide defaults to prevent undefined errors
|
|
- Use multi-select for flexibility where appropriate
|
|
|
|
### Error Handling
|
|
- Check entity availability before actions
|
|
- Use conditional sequences for optional actions
|
|
- Implement proper fallbacks for missing data
|
|
|
|
### Performance Considerations
|
|
- Use appropriate automation modes (single for exclusive, restart for updates)
|
|
- Minimize template complexity in frequently-triggered automations
|
|
- Consider using time patterns instead of constant state monitoring
|
|
|
|
### Common Issues & Solutions
|
|
- **Template errors**: Test in Developer Tools first
|
|
- **Entity unavailable**: Add availability checks in conditions
|
|
- **Z-Wave events not firing**: Verify device supports Central Scene command class
|
|
- **HVAC monitoring false positives**: Adjust temperature thresholds and time windows |