297 lines
8.7 KiB
Markdown
297 lines
8.7 KiB
Markdown
# 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
|