# 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