# 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