home-assistant-blueprints/inovelli/advanced-features.md

# 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