Add comprehensive documentation and testing tools
- Update README with complete setup guide and all blueprint URLs - Add PACKAGE_SETUP_GUIDE with step-by-step setup instructions - Add ROOM_CONFIGURATION_GUIDE with bedroom, living room, and bathroom examples - Add HARDWARE_TESTING_CHECKLIST for validating with real Inovelli switches - Add CHANGELOG documenting v1.0.0 release - Add validation script for automated YAML testing - Add test configuration example for testing without hardware
This commit is contained in:
200
ROOM_CONFIGURATION_GUIDE.md
Normal file
200
ROOM_CONFIGURATION_GUIDE.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Room Configuration Guide
|
||||
|
||||
Complete examples of configuring different room types with the Adaptive
|
||||
Lighting Mode System.
|
||||
|
||||
## Example 1: Master Bedroom
|
||||
|
||||
**Goal**: Full control with optional AL, reading/sleep modes, weekend mode
|
||||
|
||||
**Hardware**:
|
||||
- Inovelli Blue Dimmer: `bedroom_switch` (Zigbee2MQTT name)
|
||||
- Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
|
||||
`light.bedroom_lamp_2`
|
||||
- No presence sensor (privacy)
|
||||
|
||||
**Adaptive Lighting Configuration** (in `configuration.yaml`):
|
||||
```yaml
|
||||
adaptive_lighting:
|
||||
- name: bedroom
|
||||
lights:
|
||||
- light.bedroom_ceiling
|
||||
- light.bedroom_lamp_1
|
||||
- light.bedroom_lamp_2
|
||||
interval: 90
|
||||
transition: 45
|
||||
take_over_control: true
|
||||
autoreset_control_seconds: 3600 # 1 hour gentle reset
|
||||
```
|
||||
|
||||
**Package File** (`packages/adaptive_lighting_master_bedroom.yaml`):
|
||||
|
||||
Copy from `adaptive_lighting_bedroom_template.yaml`, customize:
|
||||
- Modes: Adaptive, Reading, Relaxing, Sleep, Manual Override
|
||||
- Weekend mode enabled
|
||||
- Default mode: Adaptive
|
||||
|
||||
**Blueprint Automations** (create via UI):
|
||||
|
||||
1. **Config Button Mode Cycling**:
|
||||
- Blueprint: Inovelli Mode Cycling
|
||||
- Switch Action Event: `event.bedroom_switch_action`
|
||||
- Mode Input Select: `input_select.bedroom_lighting_mode`
|
||||
- LED Color Entity: `number.bedroom_switch_led_color_when_on`
|
||||
- Zigbee2MQTT Device Name: `bedroom_switch`
|
||||
|
||||
2. **Button Actions**:
|
||||
- Blueprint: Inovelli Button Actions
|
||||
- Switch Action Event: `event.bedroom_switch_action`
|
||||
- AL Switch: `switch.adaptive_lighting_bedroom`
|
||||
- Target Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
|
||||
`light.bedroom_lamp_2`
|
||||
- Auto-Reset: 30 minutes
|
||||
|
||||
**Testing**:
|
||||
- [ ] Press config button → mode cycles through all 5 modes
|
||||
- [ ] LED changes color for each mode
|
||||
- [ ] Double-tap up → brightness boosts
|
||||
- [ ] Weekend mode enables Friday 10pm
|
||||
- [ ] Sunrise shifts to 10am on weekend
|
||||
|
||||
## Example 2: Living Room (Common Area)
|
||||
|
||||
**Goal**: Entertainment modes (Theater, Party), presence control
|
||||
|
||||
**Hardware**:
|
||||
- Inovelli Blue Dimmer: `living_room_switch`
|
||||
- Lights: `light.living_room_ceiling`, `light.living_room_lamp_1`
|
||||
- Presence: `binary_sensor.living_room_occupancy`
|
||||
|
||||
**Package File** (`packages/adaptive_lighting_living_room.yaml`):
|
||||
|
||||
Copy from `adaptive_lighting_living_room_template.yaml`
|
||||
- Modes: Adaptive, Theater, Party, Reading
|
||||
- Auto-reset mode to Adaptive when lights turn off
|
||||
|
||||
**Blueprint Automations**:
|
||||
|
||||
1. **Config Button Mode Cycling** (same as bedroom)
|
||||
2. **Button Actions** (same as bedroom, adjust auto-reset to 15 min)
|
||||
3. **Presence Mode Reset**:
|
||||
- Occupancy Sensors: `binary_sensor.living_room_occupancy`
|
||||
- Empty Delay: 5 minutes
|
||||
- AL Switch: `switch.adaptive_lighting_living_room`
|
||||
- Mode Input Select: `input_select.living_room_lighting_mode`
|
||||
- Default Mode: `Adaptive`
|
||||
|
||||
**Testing**:
|
||||
- [ ] Enter room → lights turn on (via separate occupancy automation)
|
||||
- [ ] Press config button → cycles through 4 modes
|
||||
- [ ] Set to Theater mode, leave room → after 5 min, resets to Adaptive
|
||||
- [ ] Manual boost → leave room → manual control clears
|
||||
|
||||
## Example 3: Bathroom (Simple)
|
||||
|
||||
**Goal**: Always Adaptive, brightness boost only
|
||||
|
||||
**Hardware**:
|
||||
- Inovelli Blue Dimmer: `bathroom_switch`
|
||||
- Lights: `light.bathroom_ceiling`, `light.bathroom_vanity`
|
||||
- Presence: `binary_sensor.bathroom_occupancy`
|
||||
|
||||
**Package File** (`packages/adaptive_lighting_bathroom.yaml`):
|
||||
|
||||
Copy from `adaptive_lighting_simple_template.yaml`
|
||||
- No modes (Adaptive only)
|
||||
- No weekend mode
|
||||
- Simple reset on presence end
|
||||
|
||||
**Blueprint Automations**:
|
||||
|
||||
1. **Button Actions ONLY**:
|
||||
- Double-tap up: Boost brightness
|
||||
- Triple-tap down: Night light
|
||||
- Auto-reset: 10 minutes
|
||||
|
||||
2. **Presence Mode Reset**:
|
||||
- Reset manual control when empty 5 minutes
|
||||
- No mode reset (no input_select)
|
||||
|
||||
**Testing**:
|
||||
- [ ] Double-tap up → brightness boosts
|
||||
- [ ] Leave bathroom 5 min → manual control clears
|
||||
- [ ] Triple-tap down → night light mode
|
||||
- [ ] No config button action (not configured)
|
||||
|
||||
## Entity ID Quick Reference
|
||||
|
||||
### Finding Your Entities
|
||||
|
||||
**Inovelli Switch Entities** (via Zigbee2MQTT):
|
||||
```
|
||||
event.{device_name}_action # Button presses (event entity)
|
||||
number.{device_name}_led_color_when_on
|
||||
number.{device_name}_led_color_when_off
|
||||
number.{device_name}_led_intensity_when_on
|
||||
select.{device_name}_smart_bulb_mode
|
||||
select.{device_name}_button_delay
|
||||
```
|
||||
|
||||
**Adaptive Lighting Entities**:
|
||||
```
|
||||
switch.adaptive_lighting_{name}
|
||||
switch.adaptive_lighting_sleep_mode_{name}
|
||||
switch.adaptive_lighting_adapt_brightness_{name}
|
||||
switch.adaptive_lighting_adapt_color_{name}
|
||||
```
|
||||
|
||||
**Your Input Helpers**:
|
||||
```
|
||||
input_select.{room}_lighting_mode
|
||||
input_boolean.{room}_weekend_mode
|
||||
```
|
||||
|
||||
## Common Customizations
|
||||
|
||||
### Add a New Mode
|
||||
|
||||
1. Edit package file, add mode to `input_select`:
|
||||
```yaml
|
||||
input_select:
|
||||
bedroom_lighting_mode:
|
||||
options:
|
||||
- "Adaptive"
|
||||
- "Reading"
|
||||
- "NEW MODE HERE" # Add this
|
||||
```
|
||||
|
||||
2. Add color mapping to global package (or use existing color)
|
||||
|
||||
3. Add mode application to automation:
|
||||
```yaml
|
||||
- conditions: "{{ mode == 'NEW MODE HERE' }}"
|
||||
sequence:
|
||||
- service: adaptive_lighting.change_switch_settings
|
||||
data:
|
||||
min_brightness: 50
|
||||
max_brightness: 80
|
||||
# ... settings
|
||||
```
|
||||
|
||||
4. Reload YAML configuration
|
||||
|
||||
### Change Auto-Reset Timeout
|
||||
|
||||
Edit blueprint automation via UI:
|
||||
- Settings → Automations → [Your button action automation]
|
||||
- Click Edit
|
||||
- Adjust "Auto-Reset Timeout" slider
|
||||
- Save
|
||||
|
||||
### Disable Weekend Mode
|
||||
|
||||
Comment out weekend mode automations in package file:
|
||||
```yaml
|
||||
# - id: bedroom_weekend_mode_auto_enable
|
||||
# alias: "Bedroom: Enable Weekend Mode Friday/Saturday"
|
||||
# # ... entire automation
|
||||
```
|
||||
|
||||
Reload YAML configuration.
|
||||
Reference in New Issue
Block a user