342 lines
9.2 KiB
Markdown
342 lines
9.2 KiB
Markdown
# 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
|