johno/home-assistant-blueprints
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Inovelli Blue Dimmer switch hardware documentation

Browse Source
This commit is contained in:
John Ogle
2025-12-21 15:51:08 -08:00
parent 40e03d0300
commit 63dec6c5ee
9 changed files with 2540 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
INOVELLI_BLUE_DIMMER_SWITCHES.md Normal file
View File

@@ -0,0 +1,121 @@
# Inovelli Blue Series Dimmer Switch - Zigbee2MQTT Reference
This directory contains technical specifications for Inovelli Blue Series Dimmer Switch (VZM31-SN) when used with Zigbee2MQTT, organized by theme for selective context loading.
## Parameter Categories
### [Dimming & Ramp Control](inovelli/dimming-and-ramp.md)
Properties controlling dimming speeds and ramp rates for both local (physical paddle) and remote (hub/automation) control.
- **Properties**: dimmingSpeed*, rampRate*
- **Use cases**: Fine-tuning dimming behavior, creating smooth lighting transitions
### [Brightness Levels](inovelli/brightness-levels.md)
Properties defining brightness limits, default levels, and multi-tap brightness targets.
- **Properties**: minimumLevel, maximumLevel, defaultLevel*, invertSwitch, brightnessLevelForDoubleTap*
- **Use cases**: Setting brightness constraints, configuring default on levels, switch inversion
### [Power & Energy Monitoring](inovelli/power-monitoring.md)
Properties for power measurement, reporting thresholds, and energy monitoring.
- **Properties**: power, energy, activePowerReports, activeEnergyReports, periodicPowerAndEnergyReports
- **Use cases**: Power consumption tracking, energy usage analytics, reporting intervals
### [LED Configuration](inovelli/led-configuration.md)
Properties controlling LED strip colors and intensity for individual LEDs and global defaults, plus LED effects.
- **Properties**: led_effect, individual_led_effect, ledColorWhen*, ledIntensityWhen*, defaultLed*
- **Use cases**: LED notifications, status indicators, custom color schemes, animated effects
### [Switch Configuration](inovelli/switch-config.md)
Properties defining switch type, operational modes, and hardware configuration.
- **Properties**: switchType, buttonDelay, smartBulbMode, outputMode, powerType, ledBarScaling
- **Use cases**: 3-way setup, smart bulb mode, non-neutral wiring, on/off mode
### [Protection & Safety](inovelli/protection-safety.md)
Properties for device protection, temperature monitoring, and access control.
- **Properties**: internalTemperature, overheat, localProtection, remoteProtection
- **Use cases**: Child locks, overheat protection, disabling physical/remote control
### [Timers & Automation](inovelli/timers-automation.md)
Properties for time-based automation features.
- **Properties**: autoTimerOff, loadLevelIndicatorTimeout, doubleTapUpToParam55, doubleTapDownToParam56
- **Use cases**: Auto-off timers, LED timeout, double-tap shortcuts
### [Advanced Features](inovelli/advanced-features.md)
Properties for advanced configuration, bindings, and special modes.
- **Properties**: fanControlMode, singleTapBehavior, auxSwitchUniqueScenes, bindingOffToOnSyncLevel
- **Use cases**: Fan control, scene control, firmware updates, custom behaviors
## Quick Property Lookup
| Property | Category |
|----------|----------|
| dimmingSpeedUpRemote, dimmingSpeedUpLocal | Dimming & Ramp |
| dimmingSpeedDownRemote, dimmingSpeedDownLocal | Dimming & Ramp |
| rampRateOffToOnRemote, rampRateOffToOnLocal | Dimming & Ramp |
| rampRateOnToOffRemote, rampRateOnToOffLocal | Dimming & Ramp |
| minimumLevel, maximumLevel | Brightness Levels |
| defaultLevelLocal, defaultLevelRemote | Brightness Levels |
| invertSwitch, stateAfterPowerRestored | Brightness Levels |
| brightnessLevelForDoubleTapUp, brightnessLevelForDoubleTapDown | Brightness Levels |
| autoTimerOff | Timers & Automation |
| loadLevelIndicatorTimeout | Timers & Automation |
| doubleTapUpToParam55, doubleTapDownToParam56 | Timers & Automation |
| power, energy | Power Monitoring |
| activePowerReports, activeEnergyReports | Power Monitoring |
| periodicPowerAndEnergyReports | Power Monitoring |
| quickStartTime, quickStartLevel | Power Monitoring |
| led_effect, individual_led_effect | LED Configuration |
| ledColorWhenOn, ledColorWhenOff | LED Configuration |
| ledIntensityWhenOn, ledIntensityWhenOff | LED Configuration |
| defaultLed1-7ColorWhenOn/Off | LED Configuration |
| defaultLed1-7IntensityWhenOn/Off | LED Configuration |
| ledBarScaling, onOffLedMode | LED Configuration |
| switchType, buttonDelay | Switch Configuration |
| smartBulbMode, outputMode | Switch Configuration |
| powerType, dimmingMode, relayClick | Switch Configuration |
| higherOutputInNonNeutral | Switch Configuration |
| internalTemperature, overheat | Protection & Safety |
| localProtection, remoteProtection | Protection & Safety |
| fanControlMode, singleTapBehavior | Advanced Features |
| auxSwitchUniqueScenes, bindingOffToOnSyncLevel | Advanced Features |
| deviceBindNumber, firmwareUpdateInProgressIndicator | Advanced Features |
| doubleTapClearNotifications, fanLedLevelType | Advanced Features |
## Zigbee2MQTT Integration
These properties are exposed by Zigbee2MQTT and can be accessed in Home Assistant as:
- **Entities**: `light.switch_name` (state, brightness)
- **Sensors**: `sensor.switch_name_power`, `sensor.switch_name_energy`
- **Numbers**: `number.switch_name_dimming_speed_up_remote`, etc.
- **Selects**: `select.switch_name_switch_type`, etc.
- **Actions**: `mqtt.publish` to set LED effects via `led_effect` and `individual_led_effect`
## Setting Properties
Properties can be set via:
1. **Home Assistant UI**: Using the exposed number/select entities
2. **Services**: Using `number.set_value` or `select.select_option`
3. **MQTT**: Publishing directly to `zigbee2mqtt/[device_name]/set`
Example MQTT publish for LED effect:
```yaml
service: mqtt.publish
data:
topic: zigbee2mqtt/bedroom_switch/set
payload: '{"led_effect": {"effect": "pulse", "color": 170, "level": 100, "duration": 255}}'
```
## Source
- Official Inovelli documentation: https://help.inovelli.com/en/articles/8189241-blue-series-dimmer-switch-parameters
- Zigbee2MQTT device definition: Model VZM31-SN
## Usage for LLM Agents
Each category file contains detailed property specifications including:
- Property name as exposed by Zigbee2MQTT
- Value range and units
- Default value
- Detailed description
- Usage notes and Home Assistant examples
Load only the category files relevant to your current task to minimize context usage.

322
inovelli/advanced-features.md Normal file
View File

@@ -0,0 +1,322 @@
# Advanced Features Properties
Properties for fan control modes, special operational modes, firmware updates, and advanced configuration via Zigbee2MQTT.
## Fan Control Mode
The switch can be configured to control ceiling fans with multi-tap or cycle modes.
### fanControlMode
- **Type**: Select
- **Values**: "Disabled", "Multi Tap", "Cycle"
- **Default**: "Disabled"
- **Description**: Which mode to use when binding EP3 (config button) to another device (like a fan module). Controls how the switch sends fan speed commands.
- **Home Assistant Entity**: `select.[device_name]_fan_control_mode`
- **Use cases**:
- Control ceiling fan from dimmer switch
- Multi-speed fan control
- Coordinate light + fan control
- **Modes**:
- "Disabled": No fan control
- "Multi Tap": Different tap counts = different speeds
- "Cycle": Each tap cycles through speeds
### lowLevelForFanControlMode
- **Type**: Number
- **Range**: 2-254
- **Default**: 33
- **Description**: Level to send to device bound to EP3 when set to low.
- **Home Assistant Entity**: `number.[device_name]_low_level_for_fan_control_mode`
- **Requires**: fanControlMode != "Disabled"
### mediumLevelForFanControlMode
- **Type**: Number
- **Range**: 2-254
- **Default**: 66
- **Description**: Level to send to device bound to EP3 when set to medium.
- **Home Assistant Entity**: `number.[device_name]_medium_level_for_fan_control_mode`
- **Requires**: fanControlMode != "Disabled"
### highLevelForFanControlMode
- **Type**: Number
- **Range**: 2-254
- **Default**: 100
- **Description**: Level to send to device bound to EP3 when set to high.
- **Home Assistant Entity**: `number.[device_name]_high_level_for_fan_control_mode`
- **Requires**: fanControlMode != "Disabled"
### ledColorForFanControlMode
- **Type**: Number
- **Range**: 0-255
- **Default**: 170 (Blue)
- **Description**: LED color used to display fan control mode.
- **Home Assistant Entity**: `number.[device_name]_led_color_for_fan_control_mode`
- **Preset colors**:
- `0` = Red
- `21` = Orange
- `42` = Yellow
- `85` = Green
- `127` = Cyan
- `170` = Blue
- `212` = Violet
- `234` = Pink
- `255` = White
### fanLedLevelType
- **Type**: Number
- **Range**: 0-10
- **Default**: 0
- **Description**: Level display of the LED Strip for fan control.
- **Home Assistant Entity**: `number.[device_name]_fan_led_level_type`
- **Presets**:
- `0` = Limitless (like VZM31)
- `10` = Adaptive LED
## Single Tap Behavior
### singleTapBehavior
- **Type**: Select
- **Values**: "Old Behavior", "New Behavior", "Down Always Off"
- **Default**: "Old Behavior"
- **Description**: Behavior of single tapping the on or off button.
- **Home Assistant Entity**: `select.[device_name]_single_tap_behavior`
- **Modes**:
- "Old Behavior": Traditional on/off operation
- "New Behavior": Cycles through brightness levels
- "Down Always Off": Up cycles levels, down always turns off
- **Use cases**:
- Customize paddle tap behavior
- Multi-level control without holding
- Quick access to preset levels
## Advanced Configuration
### auxSwitchUniqueScenes
- **Type**: Select
- **Values**: "Disabled", "Enabled"
- **Default**: "Disabled"
- **Description**: Have unique scene numbers for scenes activated with the aux switch.
- **Home Assistant Entity**: `select.[device_name]_aux_switch_unique_scenes`
- **Use cases**:
- Different automations per switch location in 3-way setup
- Location-aware scene triggers
- Advanced multi-point control systems
- **Requires**: switchType = "3-Way Aux Switch"
### bindingOffToOnSyncLevel
- **Type**: Select
- **Values**: "Disabled", "Enabled"
- **Default**: "Disabled"
- **Description**: Send Move_To_Level using Default Level with Off/On to bound devices.
- **Home Assistant Entity**: `select.[device_name]_binding_off_to_on_sync_level`
- **Use cases**:
- Synchronized dimming across Zigbee-bound devices
- Match brightness on associated lights
- Group control coordination
- **Note**: Applies when switch binds to other Zigbee devices
### deviceBindNumber
- **Type**: Sensor (read-only)
- **Description**: The number of devices currently bound (excluding gateways) and counts one group as two devices.
- **Home Assistant Entity**: `sensor.[device_name]_device_bind_number`
- **Read-only**: Cannot be changed, reflects current binding status
- **Use cases**:
- Diagnostic information
- Verify Zigbee binding configuration
- Troubleshoot multi-device coordination
### firmwareUpdateInProgressIndicator
- **Type**: Select
- **Values**: "Disabled", "Enabled"
- **Default**: "Enabled"
- **Description**: Display progress on LED bar during firmware update.
- **Home Assistant Entity**: `select.[device_name]_firmware_update_in_progress_indicator`
- **Use cases**:
- Visual feedback during OTA firmware update
- Indicate update in progress
- Disable for discrete updates
- **Behavior when "Enabled"**:
- LED bar shows update progress
- Progress indication during OTA update
- Provides visual confirmation
### doubleTapClearNotifications
- **Type**: Select
- **Values**: "Enabled (Default)", "Disabled"
- **Default**: "Enabled (Default)"
- **Description**: Double-Tap the Config button to clear notifications.
- **Home Assistant Entity**: `select.[device_name]_double_tap_clear_notifications`
- **Use cases**:
- Quick notification dismissal
- Manual control over persistent LED effects
- User convenience for notification management
## Configuration Patterns
### Fan Control Setup (Multi Tap)
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_fan_control_mode
data:
option: "Multi Tap"
# Set fan speed levels
service: number.set_value
target:
entity_id: number.bedroom_switch_low_level_for_fan_control_mode
data:
value: 33 # Low speed
service: number.set_value
target:
entity_id: number.bedroom_switch_medium_level_for_fan_control_mode
data:
value: 66 # Medium speed
service: number.set_value
target:
entity_id: number.bedroom_switch_high_level_for_fan_control_mode
data:
value: 100 # High speed
# Set LED color for fan mode
service: number.set_value
target:
entity_id: number.bedroom_switch_led_color_for_fan_control_mode
data:
value: 85 # Green
```
### Cycling Single Tap Behavior
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_single_tap_behavior
data:
option: "New Behavior" # Cycles through levels
```
### Location-Aware 3-Way Scenes
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_aux_switch_unique_scenes
data:
option: "Enabled"
# Now bedroom and hallway switches send different scene IDs
# Create separate automations for each location
```
### Synchronized Binding
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_binding_off_to_on_sync_level
data:
option: "Enabled" # Bound devices match this switch's level
```
### Visual Firmware Updates
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_firmware_update_in_progress_indicator
data:
option: "Enabled" # Show progress on LED bar
```
### Config Button Notification Clear
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_double_tap_clear_notifications
data:
option: "Enabled (Default)" # Double-tap config to clear
```
## Fan Control Workflow
### Multi-Tap Mode
With fanControlMode = "Multi Tap":
- Single tap config: Off
- Double tap config: Low speed
- Triple tap config: Medium speed
- Quadruple tap config: High speed
### Cycle Mode
With fanControlMode = "Cycle":
- Each config button tap cycles: Off → Low → Medium → High → Off
### Automation Integration
```yaml
automation:
- alias: "Fan Control via Config Button"
trigger:
- platform: state
entity_id: sensor.bedroom_switch_action
action:
- choose:
- conditions:
- condition: state
entity_id: sensor.bedroom_switch_action
state: "config_double"
sequence:
- service: fan.set_percentage
target:
entity_id: fan.bedroom_fan
data:
percentage: 33 # Low
- conditions:
- condition: state
entity_id: sensor.bedroom_switch_action
state: "config_triple"
sequence:
- service: fan.set_percentage
target:
entity_id: fan.bedroom_fan
data:
percentage: 66 # Medium
- conditions:
- condition: state
entity_id: sensor.bedroom_switch_action
state: "config_quadruple"
sequence:
- service: fan.set_percentage
target:
entity_id: fan.bedroom_fan
data:
percentage: 100 # High
```
## Important Notes
- Fan control modes are designed for Zigbee binding to fan controllers
- Single tap behavior affects all paddle taps (up and down)
- auxSwitchUniqueScenes requires 3-way aux switch configuration
- deviceBindNumber is informational only (read-only)
- firmwareUpdateInProgressIndicator only affects visual feedback, not update function
- LED effects set via led_effect/individual_led_effect can be cleared with config button double-tap
- Fan control LED color helps distinguish between light and fan control modes
- Bindings are managed at the Zigbee level, not via these properties
- Properties exposed via Zigbee2MQTT; Z-Wave-specific features are not applicable

236
inovelli/brightness-levels.md Normal file
View File

@@ -0,0 +1,236 @@
# Brightness Levels Properties
Properties controlling brightness limits, default levels when turning on, power restore behavior, and multi-tap brightness shortcuts.
## minimumLevel
- **Type**: Number
- **Range**: 1-254
- **Default**: 1 (lowest possible)
- **Description**: The minimum brightness level the switch can dim to. Prevents dimming below a threshold where lights flicker or turn off.
- **Home Assistant Entity**: `number.[device_name]_minimum_level`
- **Use cases**:
- Prevent LED bulb flickering at low levels
- Set nightlight minimum brightness
- Ensure lights never go completely dark when dimming
- **Common values**:
- LED bulbs: 10-20 (prevents flickering)
- Incandescent: 1-5 (can dim lower)
- Smart bulbs: 1 (handle dimming internally)
## maximumLevel
- **Type**: Number
- **Range**: 2-255
- **Default**: 255 (full brightness)
- **Description**: The maximum brightness level the switch can reach. Limits top-end brightness.
- **Home Assistant Entity**: `number.[device_name]_maximum_level`
- **Use cases**:
- Limit max brightness to extend bulb life
- Reduce energy consumption
- Create softer ambient lighting maximum
- Protect sensitive loads
- **Common values**:
- Full brightness: 255
- Energy saving: 200-230
- Ambient lighting: 150-180
## invertSwitch
- **Type**: Select
- **Values**: "Yes", "No"
- **Default**: "No" (normal orientation)
- **Description**: Inverts paddle operation (up becomes down, down becomes up).
- **Home Assistant Entity**: `select.[device_name]_invert_switch`
- **Use cases**:
- Match 3-way switch orientation
- Accommodate non-standard wiring
- User preference for reversed operation
## defaultLevelLocal
- **Type**: Number
- **Range**: 0-255
- **Default**: 255 (last level or max)
- **Description**: Brightness level when turned on via physical paddle.
- **Home Assistant Entity**: `number.[device_name]_default_level_local`
- **Special values**:
- `0-254` = Specific brightness level
- `255` = Return to the level that it was on before it was turned off (smart resume)
- **Use cases**:
- Always turn on to comfortable level (e.g., 128 for 50%)
- Predictable brightness for specific room uses
- Override smart resume for consistent behavior
## defaultLevelRemote
- **Type**: Number
- **Range**: 0-255
- **Default**: 255 (last level or max)
- **Description**: Brightness level when turned on via hub commands (automations/app).
- **Home Assistant Entity**: `number.[device_name]_default_level_remote`
- **Special values**:
- `0-254` = Specific brightness level
- `255` = Return to the level that it was on before it was turned off (smart resume)
- **Use cases**:
- Automations that need predictable brightness
- Different default for voice/app control vs physical
- Scene activation with specific levels
## stateAfterPowerRestored
- **Type**: Number
- **Range**: 0-255
- **Default**: 255 (previous state)
- **Description**: The state the switch should return to when power is restored after power failure.
- **Home Assistant Entity**: `number.[device_name]_state_after_power_restored`
- **Special values**:
- `0` = off
- `1-254` = Specific brightness level (and turn on)
- `255` = Return to previous state before power loss
- **Use cases**:
- Always off after power restore (set to 0)
- Emergency lighting (set to specific brightness)
- Smart restore to previous state (set to 255)
## brightnessLevelForDoubleTapUp
- **Type**: Number
- **Range**: 2-255
- **Default**: 254 (near maximum)
- **Description**: Set this level on double-tap UP (if enabled by doubleTapUpToParam55).
- **Home Assistant Entity**: `number.[device_name]_brightness_level_for_double_tap_up`
- **Special values**:
- `2-254` = Specific brightness level
- `255` = Send ON command
- **Use cases**:
- Quick full-bright shortcut
- Task lighting preset
- Scene activation brightness
- **Prerequisites**: Requires doubleTapUpToParam55 = "Enabled"
## brightnessLevelForDoubleTapDown
- **Type**: Number
- **Range**: 0-255
- **Default**: 0
- **Description**: Set this level on double-tap DOWN (if enabled by doubleTapDownToParam56).
- **Home Assistant Entity**: `number.[device_name]_brightness_level_for_double_tap_down`
- **Special values**:
- `0` = Send OFF command
- `1-254` = Specific brightness level
- `255` = Send OFF command
- **Use cases**:
- Quick nightlight mode
- Turn off shortcut
- Low-light scene activation
- **Prerequisites**: Requires doubleTapDownToParam56 = "Enabled"
## Configuration Patterns
### Smart Resume (Memory)
All settings return to previous state/level:
```yaml
service: number.set_value
target:
entity_id:
- number.bedroom_switch_default_level_local
- number.bedroom_switch_default_level_remote
- number.bedroom_switch_state_after_power_restored
data:
value: 255 # Remember previous level
```
### Predictable Lighting
Always turn on to 50% brightness:
```yaml
service: number.set_value
target:
entity_id:
- number.bedroom_switch_default_level_local
- number.bedroom_switch_default_level_remote
- number.bedroom_switch_state_after_power_restored
data:
value: 128 # 50% brightness
```
### LED Bulb Optimization
Prevent low-level flicker with memory:
```yaml
# Prevent flicker
service: number.set_value
target:
entity_id: number.bedroom_switch_minimum_level
data:
value: 15
# Full range at top
service: number.set_value
target:
entity_id: number.bedroom_switch_maximum_level
data:
value: 255
# Smart resume
service: number.set_value
target:
entity_id:
- number.bedroom_switch_default_level_local
- number.bedroom_switch_default_level_remote
data:
value: 255
```
### Task + Ambient Presets
Three brightness presets via paddle control:
```yaml
# Comfortable ambient for single press
service: number.set_value
target:
entity_id: number.bedroom_switch_default_level_local
data:
value: 180
# Full bright for tasks (double-tap up)
service: number.set_value
target:
entity_id: number.bedroom_switch_brightness_level_for_double_tap_up
data:
value: 254
# Enable double-tap up
service: select.select_option
target:
entity_id: select.bedroom_switch_double_tap_up_to_param55
data:
option: "Enabled"
# Nightlight mode (double-tap down)
service: number.set_value
target:
entity_id: number.bedroom_switch_brightness_level_for_double_tap_down
data:
value: 30
# Enable double-tap down
service: select.select_option
target:
entity_id: select.bedroom_switch_double_tap_down_to_param56
data:
option: "Enabled"
```
### Inverted Switch
For upside-down installation:
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_invert_switch
data:
option: "Yes"
```

219
inovelli/dimming-and-ramp.md Normal file
View File

@@ -0,0 +1,219 @@
# Dimming & Ramp Control Properties
Properties controlling how the switch dims lights and transitions between brightness levels. Each property has separate settings for "Remote" (commands from Home Assistant hub/automations) and "Local" (physical paddle presses).
## dimmingSpeedUpRemote
- **Type**: Number
- **Range**: 0-127
- **Default**: 25
- **Unit**: 100ms increments (e.g., 25 = 2.5 seconds)
- **Description**: Changes the speed that the light dims up when controlled from the hub. A setting of 0 turns the light immediately to the target level. Increasing the value slows down the transition speed.
- **Home Assistant Entity**: `number.[device_name]_dimming_speed_up_remote`
- **Special values**:
- `0` = Instant dimming (no transition)
- `1-127` = Duration in 100ms increments
- **Use cases**: Smooth transitions for automations, gradual wake-up lighting
## dimmingSpeedUpLocal
- **Type**: Number
- **Range**: 0-127
- **Default**: 127 (sync with dimmingSpeedUpRemote)
- **Unit**: 100ms increments
- **Description**: Changes the speed that the light dims up when controlled at the switch. A setting of 0 turns the light immediately to the target level. Setting to 127 keeps it in sync with dimmingSpeedUpRemote.
- **Home Assistant Entity**: `number.[device_name]_dimming_speed_up_local`
- **Special values**:
- `0` = Instant dimming
- `1-126` = Duration in 100ms increments
- `127` = Sync with dimmingSpeedUpRemote
- **Use cases**: Customize local dimming to be faster or slower than remote control
## rampRateOffToOnRemote
- **Type**: Number
- **Range**: 0-127
- **Default**: 127 (sync with dimmingSpeedUpRemote)
- **Unit**: 100ms increments
- **Description**: Changes the speed that the light turns on when controlled from the hub. A setting of 0 turns the light immediately on.
- **Home Assistant Entity**: `number.[device_name]_ramp_rate_off_to_on_remote`
- **Special values**:
- `0` = Instant on
- `1-126` = Duration in 100ms increments
- `127` = Sync with dimmingSpeedUpRemote
- **Use cases**: Gentle wake-up lighting, dramatic scene transitions
## rampRateOffToOnLocal
- **Type**: Number
- **Range**: 0-127
- **Default**: 127 (sync with dimmingSpeedUpRemote)
- **Unit**: 100ms increments
- **Description**: Changes the speed that the light turns on when controlled at the switch. A setting of 0 turns the light immediately on.
- **Home Assistant Entity**: `number.[device_name]_ramp_rate_off_to_on_local`
- **Special values**:
- `0` = Instant on
- `1-126` = Duration in 100ms increments
- `127` = Sync with dimmingSpeedUpRemote
- **Use cases**: Different on-ramp behavior for manual vs automated control
## dimmingSpeedDownRemote
- **Type**: Number
- **Range**: 0-127
- **Default**: 127 (sync with dimmingSpeedUpRemote)
- **Unit**: 100ms increments
- **Description**: Changes the speed that the light dims down when controlled from the hub. A setting of 0 turns the light immediately to the target level.
- **Home Assistant Entity**: `number.[device_name]_dimming_speed_down_remote`
- **Special values**:
- `0` = Instant dimming
- `1-126` = Duration in 100ms increments
- `127` = Sync with dimmingSpeedUpRemote
- **Use cases**: Asymmetric dimming (e.g., fast up, slow down for sunset effect)
## dimmingSpeedDownLocal
- **Type**: Number
- **Range**: 0-127
- **Default**: 127 (sync with dimmingSpeedUpLocal)
- **Unit**: 100ms increments
- **Description**: Changes the speed that the light dims down when controlled at the switch. A setting of 0 turns the light immediately to the target level.
- **Home Assistant Entity**: `number.[device_name]_dimming_speed_down_local`
- **Special values**:
- `0` = Instant dimming
- `1-126` = Duration in 100ms increments
- `127` = Sync with dimmingSpeedUpLocal
- **Use cases**: Match or differentiate from remote down-dimming behavior
## rampRateOnToOffRemote
- **Type**: Number
- **Range**: 0-127
- **Default**: 127 (sync with rampRateOffToOnRemote)
- **Unit**: 100ms increments
- **Description**: Changes the speed that the light turns off when controlled from the hub. A setting of 0 (instant) turns the light immediately off.
- **Home Assistant Entity**: `number.[device_name]_ramp_rate_on_to_off_remote`
- **Special values**:
- `0` = Instant off
- `1-126` = Duration in 100ms increments
- `127` = Sync with rampRateOffToOnRemote
- **Use cases**: Gradual fade to black, bedtime dimming routines
## rampRateOnToOffLocal
- **Type**: Number
- **Range**: 0-127
- **Default**: 127 (sync with rampRateOffToOnLocal)
- **Unit**: 100ms increments
- **Description**: Changes the speed that the light turns off when controlled at the switch. A setting of 0 (instant) turns the light immediately off.
- **Home Assistant Entity**: `number.[device_name]_ramp_rate_on_to_off_local`
- **Special values**:
- `0` = Instant off
- `1-126` = Duration in 100ms increments
- `127` = Sync with rampRateOffToOnLocal
- **Use cases**: Theater-style fade out, energy-saving gradual shutoff
## Configuration Patterns
### Synchronized Dimming
Set all local parameters to `127` to use the remote parameters as the master speed control for all dimming operations.
```yaml
# All in sync with dimmingSpeedUpRemote
service: number.set_value
target:
entity_id: number.bedroom_switch_dimming_speed_up_remote
data:
value: 25 # 2.5 seconds
# Set all local to sync
service: number.set_value
target:
entity_id:
- number.bedroom_switch_dimming_speed_up_local
- number.bedroom_switch_ramp_rate_off_to_on_local
- number.bedroom_switch_dimming_speed_down_local
- number.bedroom_switch_ramp_rate_on_to_off_local
data:
value: 127 # Sync with remote
```
### Instant Local, Smooth Remote
- Local: `0` (instant control)
- Remote: `50` (5-second smooth transitions)
```yaml
# Set remote for smooth transitions
service: number.set_value
target:
entity_id:
- number.bedroom_switch_dimming_speed_up_remote
- number.bedroom_switch_ramp_rate_off_to_on_remote
- number.bedroom_switch_dimming_speed_down_remote
- number.bedroom_switch_ramp_rate_on_to_off_remote
data:
value: 50
# Set local for instant response
service: number.set_value
target:
entity_id:
- number.bedroom_switch_dimming_speed_up_local
- number.bedroom_switch_ramp_rate_off_to_on_local
- number.bedroom_switch_dimming_speed_down_local
- number.bedroom_switch_ramp_rate_on_to_off_local
data:
value: 0
```
### Asymmetric Dimming
- Dim up quickly: `10` (1 second)
- Dim down slowly: `100` (10 seconds)
- Creates dynamic lighting feel
```yaml
# Quick dim up
service: number.set_value
target:
entity_id:
- number.bedroom_switch_dimming_speed_up_remote
- number.bedroom_switch_dimming_speed_up_local
data:
value: 10
# Slow dim down
service: number.set_value
target:
entity_id:
- number.bedroom_switch_dimming_speed_down_remote
- number.bedroom_switch_dimming_speed_down_local
data:
value: 100
```
### Scene-Based Transitions
- Off→On ramp: `30` (3 seconds - gentle fade in)
- On→Off ramp: `100` (10 seconds - slow fade out)
- Dimming speed: `20` (2 seconds - responsive)
```yaml
service: number.set_value
target:
entity_id: number.bedroom_switch_ramp_rate_off_to_on_remote
data:
value: 30
service: number.set_value
target:
entity_id: number.bedroom_switch_ramp_rate_on_to_off_remote
data:
value: 100
service: number.set_value
target:
entity_id:
- number.bedroom_switch_dimming_speed_up_remote
- number.bedroom_switch_dimming_speed_down_remote
data:
value: 20
```

428
inovelli/led-configuration.md Normal file
View File

@@ -0,0 +1,428 @@
# LED Configuration Properties
Properties controlling the LED strip on the switch, including colors, intensity levels, animated effects, and display modes. The switch has 7 individual LEDs plus global defaults.
## LED Effects
### led_effect
Composite property to control LED effects for the entire LED bar.
- **Type**: Composite (requires MQTT publish)
- **Description**: Controls animation effects for all LEDs on the bar
- **Access**: Set via MQTT publish to `zigbee2mqtt/[device_name]/set`
- **Properties**:
- `effect`: Animation effect type
- `color`: Color value (0-255, hue-based)
- `level`: Brightness (0-100%)
- `duration`: How long the effect lasts
- **Effect values**:
- `off` - Turn off LED effect
- `solid` - Solid color
- `fast_blink` - Fast blinking
- `slow_blink` - Slow blinking
- `pulse` - Pulsing effect
- `chase` - Chase/running pattern
- `open_close` - Open/close animation
- `small_to_big` - Small to big animation
- `aurora` - Aurora effect
- `slow_falling` - Slow falling effect
- `medium_falling` - Medium falling effect
- `fast_falling` - Fast falling effect
- `slow_rising` - Slow rising effect
- `medium_rising` - Medium rising effect
- `fast_rising` - Fast rising effect
- `medium_blink` - Medium blink
- `slow_chase` - Slow chase
- `fast_chase` - Fast chase
- `fast_siren` - Fast siren
- `slow_siren` - Slow siren
- `clear_effect` - Clear/stop current effect
- **Duration encoding**:
- `1-60` = Seconds
- `61-120` = Minutes (value - 60)
- `121-254` = Hours (value - 120)
- `255` = Indefinitely
**Example usage:**
```yaml
service: mqtt.publish
data:
topic: zigbee2mqtt/bedroom_switch/set
payload: '{"led_effect": {"effect": "pulse", "color": 170, "level": 100, "duration": 255}}'
```
### individual_led_effect
Composite property to control effects for a single LED.
- **Type**: Composite (requires MQTT publish)
- **Description**: Controls animation effects for one specific LED
- **Access**: Set via MQTT publish to `zigbee2mqtt/[device_name]/set`
- **Properties**:
- `led`: LED number (1-7, 1=bottom, 7=top)
- `effect`: Animation effect type
- `color`: Color value (0-255)
- `level`: Brightness (0-100%)
- `duration`: How long the effect lasts
- **LED numbering**: 1 (bottom) through 7 (top)
- **Effect values**:
- `off` - Turn off LED effect
- `solid` - Solid color
- `fast_blink` - Fast blinking
- `slow_blink` - Slow blinking
- `pulse` - Pulsing effect
- `chase` - Chase pattern
- `falling` - Falling effect
- `rising` - Rising effect
- `aurora` - Aurora effect
- `clear_effect` - Clear/stop effect
- **Duration encoding**: Same as led_effect
**Example usage:**
```yaml
service: mqtt.publish
data:
topic: zigbee2mqtt/bedroom_switch/set
payload: '{"individual_led_effect": {"led": "4", "effect": "fast_blink", "color": 0, "level": 100, "duration": 30}}'
```
## Global LED Properties
### ledColorWhenOn
- **Type**: Number
- **Range**: 0-255
- **Default**: 170 (Blue)
- **Description**: Default LED strip color when switch is on. Applies to all LEDs unless individually configured.
- **Home Assistant Entity**: `number.[device_name]_led_color_when_on`
- **Color wheel mapping**: 0-255 representing hue (0-360° mapped to 0-255)
- **Preset colors**:
- `0` = Red
- `21` = Orange
- `42` = Yellow
- `85` = Green
- `127` = Cyan
- `170` = Blue
- `212` = Violet
- `234` = Pink
- `255` = White
### ledColorWhenOff
- **Type**: Number
- **Range**: 0-255
- **Default**: 170 (Blue)
- **Description**: Default LED strip color when switch is off.
- **Home Assistant Entity**: `number.[device_name]_led_color_when_off`
- **Preset colors**: Same as ledColorWhenOn
### ledIntensityWhenOn
- **Type**: Number
- **Range**: 0-100
- **Default**: 33 (33%)
- **Description**: Default LED strip brightness when switch is on.
- **Home Assistant Entity**: `number.[device_name]_led_intensity_when_on`
- **Special values**:
- `0` = LEDs off (no indicator when on)
- `1-100` = Brightness percentage
- **Common values**:
- Night mode: `5-10`
- Default: `33`
- Maximum visibility: `100`
### ledIntensityWhenOff
- **Type**: Number
- **Range**: 0-100
- **Default**: 1 (1%)
- **Description**: Default LED strip brightness when switch is off.
- **Home Assistant Entity**: `number.[device_name]_led_intensity_when_off`
- **Common values**:
- Nightlight: `1-5`
- Locator: `10-20`
- Off (stealth): `0`
## Individual LED Properties
Each of the 7 LEDs can be individually configured with color and intensity for both on and off states. LED #1 is the bottom, LED #7 is the top.
### LED #1 (Bottom)
- **Color When On**: `number.[device_name]_default_led1_color_when_on` (0-255, 255=sync with global)
- **Color When Off**: `number.[device_name]_default_led1_color_when_off` (0-255, 255=sync with global)
- **Intensity When On**: `number.[device_name]_default_led1_intensity_when_on` (0-101, 101=sync)
- **Intensity When Off**: `number.[device_name]_default_led1_intensity_when_off` (0-101, 101=sync)
### LED #2
- **Color When On**: `number.[device_name]_default_led2_color_when_on`
- **Color When Off**: `number.[device_name]_default_led2_color_when_off`
- **Intensity When On**: `number.[device_name]_default_led2_intensity_when_on`
- **Intensity When Off**: `number.[device_name]_default_led2_intensity_when_off`
### LED #3
- **Color When On**: `number.[device_name]_default_led3_color_when_on`
- **Color When Off**: `number.[device_name]_default_led3_color_when_off`
- **Intensity When On**: `number.[device_name]_default_led3_intensity_when_on`
- **Intensity When Off**: `number.[device_name]_default_led3_intensity_when_off`
### LED #4 (Middle)
- **Color When On**: `number.[device_name]_default_led4_color_when_on`
- **Color When Off**: `number.[device_name]_default_led4_color_when_off`
- **Intensity When On**: `number.[device_name]_default_led4_intensity_when_on`
- **Intensity When Off**: `number.[device_name]_default_led4_intensity_when_off`
### LED #5
- **Color When On**: `number.[device_name]_default_led5_color_when_on`
- **Color When Off**: `number.[device_name]_default_led5_color_when_off`
- **Intensity When On**: `number.[device_name]_default_led5_intensity_when_on`
- **Intensity When Off**: `number.[device_name]_default_led5_intensity_when_off`
### LED #6
- **Color When On**: `number.[device_name]_default_led6_color_when_on`
- **Color When Off**: `number.[device_name]_default_led6_color_when_off`
- **Intensity When On**: `number.[device_name]_default_led6_intensity_when_on`
- **Intensity When Off**: `number.[device_name]_default_led6_intensity_when_off`
### LED #7 (Top)
- **Color When On**: `number.[device_name]_default_led7_color_when_on`
- **Color When Off**: `number.[device_name]_default_led7_color_when_off`
- **Intensity When On**: `number.[device_name]_default_led7_intensity_when_on`
- **Intensity When Off**: `number.[device_name]_default_led7_intensity_when_off`
**Note**: Individual LED color set to `255` or intensity set to `101` means "follow global default"
## LED Display Modes
### ledBarScaling
- **Type**: Select
- **Values**: "Gen3 method (VZM-style)", "Gen2 method (LZW-style)"
- **Default**: "Gen3 method (VZM-style)"
- **Description**: Controls how LED bar represents dimmer level.
- **Home Assistant Entity**: `select.[device_name]_led_bar_scaling`
- **Use cases**: Match behavior of older Inovelli switches for consistency
### onOffLedMode
- **Type**: Select
- **Values**: "All", "One"
- **Default**: "All"
- **Description**: When in On/Off mode, use full LED bar or just one LED.
- **Home Assistant Entity**: `select.[device_name]_on_off_led_mode`
- **Use cases**:
- Match Gen 2 Red/Black series appearance
- Preference for single LED indicator
- Reduce LED brightness/distraction
## Configuration Patterns
### Standard Blue Indicator
```yaml
service: number.set_value
target:
entity_id: number.bedroom_switch_led_color_when_on
data:
value: 170 # Blue
service: number.set_value
target:
entity_id: number.bedroom_switch_led_color_when_off
data:
value: 170 # Blue
service: number.set_value
target:
entity_id: number.bedroom_switch_led_intensity_when_on
data:
value: 33
service: number.set_value
target:
entity_id: number.bedroom_switch_led_intensity_when_off
data:
value: 1
```
### Green On / Red Off
```yaml
service: number.set_value
target:
entity_id: number.bedroom_switch_led_color_when_on
data:
value: 85 # Green
service: number.set_value
target:
entity_id: number.bedroom_switch_led_color_when_off
data:
value: 0 # Red
service: number.set_value
target:
entity_id:
- number.bedroom_switch_led_intensity_when_on
- number.bedroom_switch_led_intensity_when_off
data:
value: 40
```
### Stealth Mode
```yaml
service: number.set_value
target:
entity_id:
- number.bedroom_switch_led_intensity_when_on
- number.bedroom_switch_led_intensity_when_off
data:
value: 0
```
### Nightlight Mode
```yaml
# Soft pink when off, dark when on
service: number.set_value
target:
entity_id: number.bedroom_switch_led_color_when_off
data:
value: 234 # Pink
service: number.set_value
target:
entity_id: number.bedroom_switch_led_intensity_when_off
data:
value: 5
service: number.set_value
target:
entity_id: number.bedroom_switch_led_intensity_when_on
data:
value: 0
```
### Rainbow Bar (Individual LEDs)
```yaml
# Set each LED to a different color
service: number.set_value
target:
entity_id:
- number.bedroom_switch_default_led1_color_when_on
data:
value: 0 # Red
service: number.set_value
target:
entity_id: number.bedroom_switch_default_led2_color_when_on
data:
value: 42 # Yellow
service: number.set_value
target:
entity_id: number.bedroom_switch_default_led3_color_when_on
data:
value: 85 # Green
service: number.set_value
target:
entity_id: number.bedroom_switch_default_led4_color_when_on
data:
value: 127 # Cyan
service: number.set_value
target:
entity_id: number.bedroom_switch_default_led5_color_when_on
data:
value: 170 # Blue
service: number.set_value
target:
entity_id: number.bedroom_switch_default_led6_color_when_on
data:
value: 212 # Violet
service: number.set_value
target:
entity_id: number.bedroom_switch_default_led7_color_when_on
data:
value: 234 # Pink
```
### Notification Alert (Pulse Red)
```yaml
# 30 second red pulse on all LEDs
service: mqtt.publish
data:
topic: zigbee2mqtt/bedroom_switch/set
payload: '{"led_effect": {"effect": "pulse", "color": 0, "level": 100, "duration": 30}}'
```
### Status Indicator (Middle LED Blink)
```yaml
# Blink middle LED (LED 4) blue for 1 minute
service: mqtt.publish
data:
topic: zigbee2mqtt/bedroom_switch/set
payload: '{"individual_led_effect": {"led": "4", "effect": "fast_blink", "color": 170, "level": 100, "duration": 60}}'
```
### Doorbell Notification (Fast Chase)
```yaml
# Fast chase effect in cyan for 10 seconds
service: mqtt.publish
data:
topic: zigbee2mqtt/bedroom_switch/set
payload: '{"led_effect": {"effect": "fast_chase", "color": 127, "level": 100, "duration": 10}}'
```
### Clear All Effects
```yaml
service: mqtt.publish
data:
topic: zigbee2mqtt/bedroom_switch/set
payload: '{"led_effect": {"effect": "clear_effect"}}'
```
## LED Color Palette
Quick reference for common colors (hue-based, 0-255):
- `0` - Red
- `21` - Orange
- `42` - Yellow
- `64` - Yellow-Green
- `85` - Green
- `106` - Cyan-Green
- `127` - Cyan
- `148` - Blue-Cyan
- `170` - Blue (default)
- `191` - Blue-Violet
- `212` - Violet
- `223` - Magenta
- `234` - Pink
- `244` - Pink-Red
- `255` - White
## Notes
- Individual LED properties override global defaults
- Setting individual LED color to `255` makes it follow global color
- Setting individual LED intensity to `101` makes it follow global intensity
- LED effects from `led_effect` and `individual_led_effect` are temporary
- Effects automatically clear after duration expires or when `clear_effect` is sent
- Property changes take effect immediately without requiring switch reboot
- Use MQTT publish for LED effects; they cannot be set via Home Assistant number/select entities

364
inovelli/power-monitoring.md Normal file
View File

@@ -0,0 +1,364 @@
# Power & Energy Monitoring Properties
Properties for power consumption measurement, energy usage tracking, and reporting thresholds via Zigbee2MQTT.
## Sensor Properties (Read-Only)
### power
- **Type**: Sensor (read-only)
- **Unit**: Watts (W)
- **Description**: Instantaneous measured power consumption of the connected load.
- **Home Assistant Entity**: `sensor.[device_name]_power`
- **Updates**: Based on activePowerReports threshold or periodicPowerAndEnergyReports interval
- **Use cases**:
- Real-time power monitoring
- Detect when lights turn on/off
- Track power consumption changes
- Trigger automations based on power usage
### energy
- **Type**: Sensor (read-only)
- **Unit**: Kilowatt-hours (kWh)
- **Description**: Cumulative energy consumption over time.
- **Home Assistant Entity**: `sensor.[device_name]_energy`
- **Updates**: Based on activeEnergyReports threshold or periodicPowerAndEnergyReports interval
- **Use cases**:
- Long-term energy tracking
- Billing/cost calculations
- Energy usage analytics
- Historical consumption trends
## Reporting Configuration
### activePowerReports
- **Type**: Number
- **Range**: 0-100
- **Default**: 10 (10% change)
- **Description**: Percent power level change that will result in a new power report being sent. 0 = Disabled.
- **Home Assistant Entity**: `number.[device_name]_active_power_reports`
- **Special values**:
- `0` = Disabled (no automatic power reports based on change)
- `1-100` = Percentage change threshold
- **Use cases**:
- Real-time power monitoring
- Detect significant power changes
- Trigger automations based on power delta
- **Common values**:
- Sensitive monitoring: `5` (5% change)
- Default: `10` (10% change)
- Reduce network traffic: `20` (20% change)
- **Network impact**: Lower values generate more Zigbee traffic
### periodicPowerAndEnergyReports
- **Type**: Number
- **Range**: 0-32767
- **Default**: 3600 seconds (1 hour)
- **Description**: Time period between consecutive power & energy reports being sent (in seconds). The timer is reset after each report is sent.
- **Home Assistant Entity**: `number.[device_name]_periodic_power_and_energy_reports`
- **Units**: Seconds
- **Special values**:
- `0` = Disabled (no periodic reports)
- `1-32767` = Report interval in seconds
- **Use cases**:
- Regular energy usage logging
- Dashboard updates
- Long-term consumption tracking
- Backup reporting if active reports miss changes
- **Common values**:
- Frequent updates: `300` (5 minutes)
- Default: `3600` (1 hour)
- Reduce traffic: `7200` (2 hours)
- Daily: `86400` (24 hours)
- **Note**: Works alongside activePowerReports and activeEnergyReports (not instead of)
### activeEnergyReports
- **Type**: Number
- **Range**: 0-32767
- **Default**: 10 (0.10 kWh)
- **Description**: Energy level change which will result in sending a new energy report. 0 = disabled, 1-32767 = 0.01kWh-327.67kWh.
- **Home Assistant Entity**: `number.[device_name]_active_energy_reports`
- **Units**: 0.01 kWh (value of 10 = 0.10 kWh = 100 Wh)
- **Special values**:
- `0` = Disabled (no automatic energy reports based on accumulation)
- `1-32767` = Threshold in 0.01 kWh increments
- **Use cases**:
- Track cumulative energy consumption
- Billing/cost calculations
- Energy usage analytics
- Trigger automations at energy milestones
- **Common values**:
- Sensitive: `1` (0.01 kWh = 10 Wh)
- Default: `10` (0.10 kWh = 100 Wh)
- Reduce traffic: `100` (1.0 kWh)
- **Example**: Default of 10 means report every 100 Wh (0.1 kWh) consumed
## Performance Tuning
### quickStartTime
- **Type**: Number
- **Range**: 0-60
- **Default**: 0 (disabled)
- **Description**: Duration of full power output while lamp transitions from Off to On. In 60th of second. 0 = disable, 1 = 1/60s, 60 = 1s.
- **Home Assistant Entity**: `number.[device_name]_quick_start_time`
- **Units**: 1/60th of a second
- **Use cases**:
- Help LED bulbs start reliably
- Overcome LED driver inrush requirements
- Prevent flickering on startup
- **Common values**:
- Disabled: `0`
- Short boost: `10` (0.17 seconds)
- Default boost: `20` (0.33 seconds)
- Long boost: `60` (1 second)
### quickStartLevel
- **Type**: Number
- **Range**: 1-254
- **Default**: 254 (near full power)
- **Description**: Level of power output during Quick Start Light time (quickStartTime).
- **Home Assistant Entity**: `number.[device_name]_quick_start_level`
- **Use cases**:
- Ensure LED bulbs receive enough initial power to start
- Match bulb requirements for startup
- **Requires**: quickStartTime > 0
### higherOutputInNonNeutral
- **Type**: Select
- **Values**: "Disabled (default)", "Enabled"
- **Default**: "Disabled (default)"
- **Description**: Increase output level in non-neutral mode to help bulbs start and operate properly.
- **Home Assistant Entity**: `select.[device_name]_higher_output_in_non_neutral`
- **Use cases**:
- Non-neutral installations with LED bulbs
- Improve dimming range in non-neutral mode
- Help bulbs work better without neutral wire
- **Note**: Only applies to non-neutral wiring configurations
## Power Type Detection
### powerType
- **Type**: Sensor (read-only)
- **Values**: "Non Neutral", "Neutral"
- **Description**: Detected power wiring type.
- **Home Assistant Entity**: `sensor.[device_name]_power_type`
- **Read-only**: Cannot be changed by user, automatically detected
- **Use cases**:
- Diagnostic information
- Verify wiring configuration
- Troubleshooting installation issues
- **Note**: Automatically detected by switch hardware
## Configuration Patterns
### Real-Time Power Monitoring
```yaml
# Sensitive power change detection
service: number.set_value
target:
entity_id: number.bedroom_switch_active_power_reports
data:
value: 5 # Report on 5% power change
# Frequent periodic backup
service: number.set_value
target:
entity_id: number.bedroom_switch_periodic_power_and_energy_reports
data:
value: 300 # Every 5 minutes
# Disable energy threshold reports (focus on power)
service: number.set_value
target:
entity_id: number.bedroom_switch_active_energy_reports
data:
value: 0 # Disabled
```
### Energy Usage Tracking
```yaml
# Less sensitive power reports
service: number.set_value
target:
entity_id: number.bedroom_switch_active_power_reports
data:
value: 20 # Report on 20% change
# Hourly periodic reports
service: number.set_value
target:
entity_id: number.bedroom_switch_periodic_power_and_energy_reports
data:
value: 3600 # Every hour
# Energy threshold reporting
service: number.set_value
target:
entity_id: number.bedroom_switch_active_energy_reports
data:
value: 10 # Report every 0.1 kWh
```
### Low Network Traffic
```yaml
# High power change threshold
service: number.set_value
target:
entity_id: number.bedroom_switch_active_power_reports
data:
value: 25 # 25% change
# 2-hour periodic reports
service: number.set_value
target:
entity_id: number.bedroom_switch_periodic_power_and_energy_reports
data:
value: 7200
# High energy threshold
service: number.set_value
target:
entity_id: number.bedroom_switch_active_energy_reports
data:
value: 100 # Every 1 kWh
```
### LED Bulb Quick Start
```yaml
# Enable quick start with 1/3 second boost
service: number.set_value
target:
entity_id: number.bedroom_switch_quick_start_time
data:
value: 20 # 20/60 = 0.33 seconds
# Full power during quick start
service: number.set_value
target:
entity_id: number.bedroom_switch_quick_start_level
data:
value: 254 # Near maximum
```
### Non-Neutral Optimization
```yaml
# Enable higher output for non-neutral
service: select.select_option
target:
entity_id: select.bedroom_switch_higher_output_in_non_neutral
data:
option: "Enabled"
# May also need quick start
service: number.set_value
target:
entity_id: number.bedroom_switch_quick_start_time
data:
value: 30 # 0.5 seconds
```
### Disable All Monitoring
```yaml
# Turn off all automatic reporting
service: number.set_value
target:
entity_id:
- number.bedroom_switch_active_power_reports
- number.bedroom_switch_periodic_power_and_energy_reports
- number.bedroom_switch_active_energy_reports
data:
value: 0
```
## Reporting Behavior
The switch can send reports via three independent mechanisms:
1. **Active Power Reports**: Sent when power changes by threshold percentage
2. **Active Energy Reports**: Sent when accumulated energy reaches threshold
3. **Periodic Reports**: Sent at regular time intervals
All three work independently and can be used together for comprehensive monitoring.
## Home Assistant Integration Example
### Power-Based Automation
```yaml
automation:
- alias: "Detect Light On"
trigger:
- platform: numeric_state
entity_id: sensor.bedroom_switch_power
above: 5 # 5W threshold
action:
- service: notify.mobile_app
data:
message: "Bedroom light turned on ({{ states('sensor.bedroom_switch_power') }}W)"
- alias: "Detect Light Off"
trigger:
- platform: numeric_state
entity_id: sensor.bedroom_switch_power
below: 1 # Less than 1W
for:
seconds: 5
action:
- service: notify.mobile_app
data:
message: "Bedroom light turned off"
```
### Energy Cost Tracking
```yaml
automation:
- alias: "Daily Energy Report"
trigger:
- platform: time
at: "23:59:00"
action:
- service: notify.mobile_app
data:
message: >
Bedroom light energy today: {{ states('sensor.bedroom_switch_energy') }} kWh
Estimated cost: ${{ (states('sensor.bedroom_switch_energy') | float * 0.12) | round(2) }}
```
## Example Calculations
### Power Threshold
activePowerReports = `20` → Report when power changes by 20%
- Load at 40W, dims to 35W: Change is 12.5%, no report
- Load at 40W, dims to 30W: Change is 25%, report sent
### Energy Threshold
activeEnergyReports = `50` → Report every 0.5 kWh (500 Wh)
- 100W bulb for 5 hours: 500 Wh consumed → Report sent
### Periodic Reporting
periodicPowerAndEnergyReports = `1800` → Report every 30 minutes
- Regardless of power/energy changes, status sent every 30min
## Important Notes
- All reporting properties work independently
- Power and energy sensors update based on configured thresholds
- quickStartTime/Level only applies to the transition from off to on
- higherOutputInNonNeutral only helps in non-neutral wiring setups
- Sensors are read-only; only configuration properties can be set
- Lower reporting thresholds increase Zigbee network traffic
- Power readings may have ~1W accuracy tolerance

213
inovelli/protection-safety.md Normal file
View File

@@ -0,0 +1,213 @@
# Protection & Safety Properties
Properties for device protection, temperature monitoring, access control, and overheat safety features via Zigbee2MQTT.
## Temperature Monitoring (Read-Only)
### internalTemperature
- **Type**: Sensor (read-only)
- **Range**: 0-127°C
- **Unit**: Degrees Celsius (°C)
- **Description**: The temperature measured by the temperature sensor inside the chip, in degrees Celsius.
- **Home Assistant Entity**: `sensor.[device_name]_internal_temperature`
- **Read-only**: Cannot be changed by user, reports actual temperature
- **Use cases**:
- Monitor switch health
- Detect overheating conditions
- Trigger cooling automations
- Diagnostic information
- **Normal range**: Typically 30-50°C during operation
- **Warning signs**:
- Above 60°C: High temperature, check ventilation
- Above 70°C: Overheat protection may activate
### overheat
- **Type**: Sensor (read-only)
- **Values**: "No Alert", "Overheated"
- **Description**: Indicates if the internal chipset is currently in an overheated state.
- **Home Assistant Entity**: `sensor.[device_name]_overheat`
- **Read-only**: Cannot be changed by user, reports protection status
- **Use cases**:
- Safety monitoring
- Alert when switch is overheating
- Diagnostic for load issues
- Automation triggers for problems
- **Behavior when "Overheated"**:
- Switch may reduce output or shut off load
- LED may indicate error state
- Switch protects itself from damage
- **Recovery**: Automatically resets when temperature drops to safe level
- **Causes**:
- Excessive load (too many bulbs/watts)
- Poor ventilation (box too small, insulation)
- High ambient temperature
- Short circuit or wiring issues
## Access Control
### localProtection
- **Type**: Select
- **Values**: "Disabled", "Enabled"
- **Default**: "Disabled"
- **Description**: Ability to control switch from the wall. When enabled, disables physical paddle control.
- **Home Assistant Entity**: `select.[device_name]_local_protection`
- **Use cases**:
- Child safety locks
- Prevent accidental changes
- Commercial applications
- Force automation-only control
- **Behavior when "Enabled"**:
- Paddle presses do nothing
- Zigbee commands still work
- Switch can only be controlled via hub/automations
- LED effects still respond to paddle (visual feedback)
- **Override**: Can be disabled via Zigbee command from hub
- **Note**: Does not affect config button or air-gap switch
### remoteProtection
- **Type**: Sensor (read-only via Zigbee2MQTT)
- **Values**: "Disabled", "Enabled"
- **Default**: "Disabled"
- **Description**: Ability to control switch from the hub.
- **Home Assistant Entity**: `sensor.[device_name]_remote_protection`
- **Read-only via Zigbee2MQTT**: Status can be read but not changed remotely
- **Use cases**:
- Prevent automation interference
- Local control only mode
- Troubleshooting automation issues
- **Behavior when "Enabled"**:
- Paddle works normally
- Zigbee on/off/dim commands ignored
- Configuration commands may still be accepted
- Switch operates as manual-only dimmer
## Configuration Patterns
### Standard Operation (No Protection)
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_local_protection
data:
option: "Disabled"
```
### Child Lock (Paddle Disabled)
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_local_protection
data:
option: "Enabled"
```
### Temperature Monitoring Automation
```yaml
automation:
- alias: "Inovelli Overheat Alert"
trigger:
- platform: numeric_state
entity_id: sensor.bedroom_switch_internal_temperature
above: 60
action:
- service: notify.mobile_app
data:
message: "Bedroom switch overheating: {{ states('sensor.bedroom_switch_internal_temperature') }}°C"
- alias: "Inovelli Overheat Protection Triggered"
trigger:
- platform: state
entity_id: sensor.bedroom_switch_overheat
to: "Overheated"
action:
- service: notify.mobile_app
data:
message: "ALERT: Bedroom switch overheat protection activated!"
title: "Switch Overheat"
- service: light.turn_off
entity_id: light.bedroom_switch
```
## Safety Considerations
### Overheat Protection
The switch has built-in thermal protection that cannot be disabled:
- Monitors internal temperature continuously
- Automatically reduces output if too hot
- Protects switch from permanent damage
- Resets automatically when cooled
### Common Causes of Overheating
1. **Overloaded circuit**: Too many bulbs/high wattage
2. **Poor ventilation**: Tight gang box, spray foam insulation
3. **Non-neutral wiring**: Generates more heat
4. **Ambient temperature**: Hot attic/outdoor locations
5. **Electrical issues**: Poor connections, high resistance
### Prevention
- Don't exceed rated wattage (typically 150W LED, 300W incandescent)
- Ensure adequate box size and ventilation
- Use fan/cooling for hot environments
- Regular temperature monitoring via automations
- Quality bulbs that don't overdraw current
### Emergency Procedures
If overheat protection triggers:
1. Check overheat sensor status
2. Read internalTemperature value
3. Turn off load via Zigbee if possible
4. Allow switch to cool (15-30 minutes)
5. Investigate cause before restoring power
6. Reduce load or improve ventilation
## Protection Use Cases
### Vacation Mode Child Lock
```yaml
# Before leaving, disable paddle
service: select.select_option
target:
entity_id: select.bedroom_switch_local_protection
data:
option: "Enabled"
# Configure automations for lighting schedule
```
### Critical Lighting Protection
```yaml
# For always-on circuits (security, safety)
service: select.select_option
target:
entity_id: select.bedroom_switch_local_protection
data:
option: "Enabled"
```
### Commercial Installation
```yaml
# Public spaces - prevent tampering
service: select.select_option
target:
entity_id: select.bedroom_switch_local_protection
data:
option: "Enabled"
```
## Important Notes
- localProtection can be changed remotely via Zigbee2MQTT
- remoteProtection is read-only via Zigbee2MQTT
- Physical config button can reset protections if needed
- Air-gap switch always works regardless of protection settings
- Overheat protection is hardware-based and cannot be disabled
- Temperature monitoring via internalTemperature sensor
- Local + Remote protection together creates fully locked state (not recommended)
- Temperature readings update based on reporting configuration

296
inovelli/switch-config.md Normal file
View File

@@ -0,0 +1,296 @@
# Switch Configuration Properties
Properties defining switch type, operational modes, hardware configuration, and timing behavior for Zigbee2MQTT integration.
## Switch Type & Wiring
### switchType
- **Type**: Select
- **Values**: "Single Pole", "3-Way Dumb Switch", "3-Way Aux Switch", "Single-Pole Full Sine Wave"
- **Default**: "Single Pole"
- **Description**: Configures the physical switch wiring type and companion switch behavior.
- **Home Assistant Entity**: `select.[device_name]_switch_type`
- **Use cases**:
- Single location: "Single Pole"
- Multi-location with dumb 3-way: "3-Way Dumb Switch"
- Multi-location with Aux switch: "3-Way Aux Switch"
- Ceiling fan control: "Single-Pole Full Sine Wave"
- **Important**: Must match actual wiring configuration
### powerType
- **Type**: Sensor (read-only)
- **Values**: "Non Neutral", "Neutral"
- **Description**: Detected power wiring type.
- **Home Assistant Entity**: `sensor.[device_name]_power_type`
- **Read-only**: Automatically detected by switch hardware
- **Use cases**:
- Diagnostic information
- Verify wiring configuration
- Troubleshooting installation issues
### dimmingMode
- **Type**: Sensor (read-only)
- **Values**: "Leading edge", "Trailing edge"
- **Default**: "Trailing edge"
- **Description**: Dimming method used for load control. Can only be changed at the switch.
- **Home Assistant Entity**: `sensor.[device_name]_dimming_mode`
- **Read-only via Zigbee2MQTT**: Must be configured at the physical switch
- **Use cases**:
- LED bulbs: "Trailing edge"
- Incandescent: "Leading edge"
- Troubleshooting flicker/buzz issues
- **Note**: Trailing edge only available on neutral single-pole and neutral multi-way with aux switch
## Operational Modes
### outputMode
- **Type**: Select
- **Values**: "Dimmer", "On/Off"
- **Default**: "Dimmer"
- **Description**: Switches between dimmer and on/off only operation.
- **Home Assistant Entity**: `select.[device_name]_output_mode`
- **Use cases**:
- Dimming incompatible loads: "On/Off"
- Standard operation: "Dimmer"
- User preference for simple on/off: "On/Off"
- **Behavior in On/Off mode**:
- Paddle only turns on/off (no dimming)
- Commands still accept brightness levels
- No ramp rates (instant on/off)
- Simpler operation for non-dimmable loads
### smartBulbMode
- **Type**: Select
- **Values**: "Disabled", "Smart Bulb Mode"
- **Default**: "Disabled"
- **Description**: Keeps power always on to load, disables dimming. For smart bulbs that need constant power.
- **Home Assistant Entity**: `select.[device_name]_smart_bulb_mode`
- **Use cases**:
- Regular dumb bulbs: "Disabled"
- Philips Hue, LIFX, other smart bulbs: "Smart Bulb Mode"
- Smart switches in parallel with dimmer: "Smart Bulb Mode"
- **Behavior when enabled**:
- Load receives constant full power
- Switch still sends Zigbee commands
- Paddle controls scenes/automations, not load directly
- LED bar still shows "virtual" dimming level
- **Important**: Required for smart bulbs to maintain Wi-Fi/Zigbee/Z-Wave control
### relayClick
- **Type**: Select
- **Values**: "Disabled (Click Sound On)", "Enabled (Click Sound Off)"
- **Default**: "Disabled (Click Sound On)"
- **Description**: Controls audible relay click sound. In neutral on/off setups, you may disable the click sound by creating a "simulated" on/off where the switch only turns on to 100 or off to 0.
- **Home Assistant Entity**: `select.[device_name]_relay_click`
- **Use cases**:
- Silent operation (bedrooms): "Enabled" (removes click)
- Normal operation: "Disabled" (click present)
- **Note**: Only applies to neutral on/off mode configurations
## Timing & Button Behavior
### buttonDelay
- **Type**: Select
- **Values**: "0ms", "100ms", "200ms", "300ms", "400ms", "500ms", "600ms", "700ms", "800ms", "900ms"
- **Default**: "500ms"
- **Description**: Delay before switch responds to paddle press. Allows multi-tap detection.
- **Home Assistant Entity**: `select.[device_name]_button_delay`
- **Special values**:
- "0ms" = Instant response (disables multi-tap features and button press events)
- "500ms" = Default, balanced
- "700ms"-"900ms" = More forgiving multi-tap timing
- **Use cases**:
- Instant control: "0ms" (no multi-tap)
- Default multi-tap: "500ms" (good balance)
- Reliable multi-tap: "700ms" or higher
- **Trade-off**: Higher values enable easier multi-tap but slower single-press response
## LED Display Modes
### ledBarScaling
- **Type**: Select
- **Values**: "Gen3 method (VZM-style)", "Gen2 method (LZW-style)"
- **Default**: "Gen3 method (VZM-style)"
- **Description**: Controls how LED bar represents dimmer level.
- **Home Assistant Entity**: `select.[device_name]_led_bar_scaling`
- **Use cases**: Match behavior of older Inovelli switches for consistency
### onOffLedMode
- **Type**: Select
- **Values**: "All", "One"
- **Default**: "All"
- **Description**: When in On/Off mode, use full LED bar or just one LED.
- **Home Assistant Entity**: `select.[device_name]_on_off_led_mode`
- **Use cases**:
- Match Gen 2 Red/Black series appearance: "One"
- Standard bar graph: "All"
- Reduce LED brightness/distraction: "One"
## Configuration Patterns
### Standard Single-Pole Installation
```yaml
service: select.select_option
target:
entity_id:
- select.bedroom_switch_switch_type
- select.bedroom_switch_output_mode
- select.bedroom_switch_smart_bulb_mode
data:
option: "Single Pole"
service: select.select_option
target:
entity_id: select.bedroom_switch_output_mode
data:
option: "Dimmer"
service: select.select_option
target:
entity_id: select.bedroom_switch_smart_bulb_mode
data:
option: "Disabled"
```
### 3-Way with Aux Switch
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_switch_type
data:
option: "3-Way Aux Switch"
service: select.select_option
target:
entity_id: select.bedroom_switch_button_delay
data:
option: "500ms" # Allow multi-tap
```
### Smart Bulb Control
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_switch_type
data:
option: "Single Pole"
service: select.select_option
target:
entity_id: select.bedroom_switch_smart_bulb_mode
data:
option: "Smart Bulb Mode"
service: select.select_option
target:
entity_id: select.bedroom_switch_output_mode
data:
option: "Dimmer" # Virtual dimming for scenes
```
### Non-Dimmable Load
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_output_mode
data:
option: "On/Off"
```
### Silent Operation (No Relay Click)
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_relay_click
data:
option: "Enabled" # Removes click sound
```
### Multi-Tap Optimization
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_button_delay
data:
option: "700ms" # Reliable double-tap detection
# Also enable double-tap shortcuts
service: select.select_option
target:
entity_id:
- select.bedroom_switch_double_tap_up_to_param55
- select.bedroom_switch_double_tap_down_to_param56
data:
option: "Enabled"
```
### Instant Response (No Scenes)
```yaml
service: select.select_option
target:
entity_id: select.bedroom_switch_button_delay
data:
option: "0ms" # Instant, but disables button events
# Note: 0ms disables multi-tap and button press events entirely
```
## Troubleshooting Guide
### Bulb Flickers
- Check dimmingMode (can only be changed at switch, not via Zigbee2MQTT)
- Increase minimumLevel property
- Verify bulb is dimmable
- Try smartBulbMode if using smart bulbs
### Buzzing/Humming
- Try changing dimmingMode at the physical switch
- Reduce load (fewer bulbs)
- Verify bulb compatibility with dimmer
### Aux Switch Not Working
- Verify switchType = "3-Way Aux Switch"
- Check wiring: Line, Load, Traveler
- Ensure Aux switch is compatible (GE/Inovelli)
### Smart Bulbs Lose Connection
- Enable smartBulbMode = "Smart Bulb Mode"
- This keeps power constant to bulbs
### Switch Too Slow/Too Fast
- Adjust buttonDelay
- Lower = faster response, harder multi-tap
- Higher = slower response, easier multi-tap
- "0ms" disables button events entirely
### Non-Neutral Installation Issues
- Check powerType sensor to verify detection
- Ensure minimum load requirements met
- May need bypass capacitor for LED loads
- Consider higherOutputInNonNeutral option
## Important Notes
- dimmingMode can only be changed at the physical switch, not via Zigbee2MQTT
- powerType is automatically detected and read-only
- smartBulbMode is essential for any smart bulb integration
- buttonDelay of "0ms" completely disables button press events and multi-tap
- relayClick only applies to specific neutral on/off configurations
- switchType must match your actual wiring for proper operation
- LED scaling and mode options provide compatibility with older Inovelli switches

341
inovelli/timers-automation.md Normal file
View File

@@ -0,0 +1,341 @@
# Timers & Automation Properties
Properties for time-based features including auto-off timers, LED timeouts, multi-tap shortcuts, and button press events via Zigbee2MQTT.
## Auto-Off Timer
### autoTimerOff
- **Type**: Number
- **Range**: 0-32767
- **Default**: 0 (disabled)
- **Unit**: Seconds
- **Description**: Automatically turns the switch off after this many seconds. When the switch is turned on a timer is started. When the timer expires, the switch is turned off. 0 = Auto off is disabled.
- **Home Assistant Entity**: `number.[device_name]_auto_timer_off`
- **Special values**:
- `0` = Disabled (no auto-off)
- `1-32767` = Time in seconds before auto-off
- **Use cases**:
- Bathroom fan auto-off
- Closet lights safety shutoff
- Energy saving for forgotten lights
- Timed task lighting
- **Common values**:
- 3 minutes: `180`
- 5 minutes: `300`
- 15 minutes: `900`
- 30 minutes: `1800`
- 1 hour: `3600`
- 2 hours: `7200`
- **Behavior**:
- Timer starts when load is turned on
- Resets if manually turned off then on again
- Works for both local (paddle) and remote (hub) activation
- Switch turns off automatically when timer expires
- **Maximum**: ~9 hours (32767 seconds)
## LED Indicator Timeout
### loadLevelIndicatorTimeout
- **Type**: Select
- **Values**: "Stay Off", "1 Second", "2 Seconds", "3 Seconds", "4 Seconds", "5 Seconds", "6 Seconds", "7 Seconds", "8 Seconds", "9 Seconds", "10 Seconds", "Stay On"
- **Default**: "3 Seconds"
- **Description**: Shows the level that the load is at for x number of seconds after the load is adjusted and then returns to the Default LED state. 0 = Stay Off, 1-10 = seconds, 11 = Stay On.
- **Home Assistant Entity**: `select.[device_name]_load_level_indicator_timeout`
- **Use cases**:
- Show brightness level briefly after adjustment
- Return to default LED color/intensity after timeout
- Visual feedback for dimming changes
- **Behavior**:
- When brightness is adjusted
- LED bar shows actual load level
- After timeout, returns to configured LED state (ledColorWhen*, ledIntensityWhen*)
## Multi-Tap Shortcuts
### doubleTapUpToParam55
- **Type**: Select
- **Values**: "Disabled", "Enabled"
- **Default**: "Disabled"
- **Description**: Enable or Disable setting level to brightnessLevelForDoubleTapUp on double-tap UP.
- **Home Assistant Entity**: `select.[device_name]_double_tap_up_to_param55`
- **Use cases**:
- Quick full-bright shortcut
- Task lighting activation
- Scene trigger for bright preset
- **Prerequisites**:
- Requires buttonDelay > "0ms" for multi-tap detection
- Target level set in brightnessLevelForDoubleTapUp
- **Behavior**:
- Works from any current brightness or off state
- Jumps directly to brightnessLevelForDoubleTapUp level
- Can be used to trigger automations via action events
### doubleTapDownToParam56
- **Type**: Select
- **Values**: "Disabled", "Enabled"
- **Default**: "Disabled"
- **Description**: Enable or Disable setting level to brightnessLevelForDoubleTapDown on double-tap DOWN.
- **Home Assistant Entity**: `select.[device_name]_double_tap_down_to_param56`
- **Use cases**:
- Quick dim/nightlight mode
- Quick off shortcut
- Scene trigger for dim preset
- **Prerequisites**:
- Requires buttonDelay > "0ms" for multi-tap detection
- Target level set in brightnessLevelForDoubleTapDown
- **Behavior**:
- Works from any current brightness
- Jumps directly to brightnessLevelForDoubleTapDown level
- If brightnessLevelForDoubleTapDown = 0, turns off
- Can be used to trigger automations via action events
## Button Press Events
### action
- **Type**: Sensor (read-only, event-based)
- **Description**: Triggered action (e.g. a button click). Events are published to this entity when paddle/config button is pressed.
- **Home Assistant Entity**: `event.[device_name]_action`
- **Event values**:
- `down_single`, `up_single`, `config_single` - Single tap
- `down_release`, `up_release`, `config_release` - Button released
- `down_held`, `up_held`, `config_held` - Button held
- `down_double`, `up_double`, `config_double` - Double tap
- `down_triple`, `up_triple`, `config_triple` - Triple tap
- `down_quadruple`, `up_quadruple`, `config_quadruple` - Quadruple tap
- `down_quintuple`, `up_quintuple`, `config_quintuple` - Quintuple tap
- **Use cases**:
- Trigger Home Assistant automations based on button presses
- Multi-tap scene control
- Advanced automation logic
- **Prerequisites**: buttonDelay > "0ms" (setting to "0ms" disables button events)
## Configuration Patterns
### Bathroom Fan Auto-Off (15 minutes)
```yaml
service: number.set_value
target:
entity_id: number.bathroom_fan_auto_timer_off
data:
value: 900 # 15 minutes
```
### Closet Light Safety (5 minutes)
```yaml
service: number.set_value
target:
entity_id: number.closet_light_auto_timer_off
data:
value: 300 # 5 minutes
```
### Quick Brightness Shortcuts
```yaml
# Enable button delay for multi-tap detection
service: select.select_option
target:
entity_id: select.bedroom_switch_button_delay
data:
option: "500ms"
# Enable double-tap up
service: select.select_option
target:
entity_id: select.bedroom_switch_double_tap_up_to_param55
data:
option: "Enabled"
# Set bright level for double-tap up
service: number.set_value
target:
entity_id: number.bedroom_switch_brightness_level_for_double_tap_up
data:
value: 254 # Nearly full brightness
# Enable double-tap down
service: select.select_option
target:
entity_id: select.bedroom_switch_double_tap_down_to_param56
data:
option: "Enabled"
# Set nightlight level for double-tap down
service: number.set_value
target:
entity_id: number.bedroom_switch_brightness_level_for_double_tap_down
data:
value: 20 # Dim nightlight
```
### LED Level Indicator Timing
```yaml
# Show level for 5 seconds after adjustment
service: select.select_option
target:
entity_id: select.bedroom_switch_load_level_indicator_timeout
data:
option: "5 Seconds"
```
## Button Press Automation Examples
### Double-Tap Scene Trigger
```yaml
automation:
- alias: "Bedroom Double-Tap Up - Movie Mode"
trigger:
- platform: state
entity_id: sensor.bedroom_switch_action
to: "up_double"
action:
- service: scene.turn_on
target:
entity_id: scene.movie_mode
- alias: "Bedroom Double-Tap Down - Nighttime"
trigger:
- platform: state
entity_id: sensor.bedroom_switch_action
to: "down_double"
action:
- service: scene.turn_on
target:
entity_id: scene.nighttime
```
### Triple-Tap for All Lights
```yaml
automation:
- alias: "Kitchen Triple-Tap Up - All Lights On"
trigger:
- platform: state
entity_id: sensor.kitchen_switch_action
to: "up_triple"
action:
- service: light.turn_on
target:
entity_id: all
- alias: "Kitchen Triple-Tap Down - All Lights Off"
trigger:
- platform: state
entity_id: sensor.kitchen_switch_action
to: "down_triple"
action:
- service: light.turn_off
target:
entity_id: all
```
### Config Button Custom Action
```yaml
automation:
- alias: "Config Button - Toggle Guest Mode"
trigger:
- platform: state
entity_id: sensor.bedroom_switch_action
to: "config_double"
action:
- service: input_boolean.toggle
target:
entity_id: input_boolean.guest_mode
```
### Held Button for Scenes
```yaml
automation:
- alias: "Up Held - Gradually Brighten"
trigger:
- platform: state
entity_id: sensor.bedroom_switch_action
to: "up_held"
action:
- service: light.turn_on
target:
entity_id: light.bedroom_switch
data:
brightness_pct: 100
transition: 10
- alias: "Down Held - Gradually Dim"
trigger:
- platform: state
entity_id: sensor.bedroom_switch_action
to: "down_held"
action:
- service: light.turn_on
target:
entity_id: light.bedroom_switch
data:
brightness_pct: 1
transition: 10
```
## Auto-Off Timer Examples
### Common Applications
**Bathroom Exhaust Fan**
```yaml
# 15 minutes
service: number.set_value
target:
entity_id: number.bathroom_fan_auto_timer_off
data:
value: 900
```
**Laundry Room**
```yaml
# 1 hour
service: number.set_value
target:
entity_id: number.laundry_room_auto_timer_off
data:
value: 3600
```
**Garage Workshop**
```yaml
# 2 hours
service: number.set_value
target:
entity_id: number.garage_auto_timer_off
data:
value: 7200
```
**Pantry/Closet**
```yaml
# 3 minutes
service: number.set_value
target:
entity_id: number.pantry_auto_timer_off
data:
value: 180
```
## Important Notes
- autoTimerOff works independently of other features
- loadLevelIndicatorTimeout only affects load level display, not LED effects
- Multi-tap features require buttonDelay > "0ms" for detection
- Setting buttonDelay to "0ms" disables ALL button events (action sensor)
- Double-tap can both change brightness AND trigger automations via action events
- action sensor events can trigger automations for any tap pattern
- Auto-off timer resets on each manual on/off cycle
- Button events are published to the action sensor for Home Assistant automations
- Use action events for complex scene control and multi-location logic