Add Inovelli Blue Dimmer switch hardware documentation

2025-12-21 15:51:08 -08:00
parent 40e03d0300
commit 63dec6c5ee
9 changed files with 2540 additions and 0 deletions
--- a/inovelli/switch-config.md
+++ b/inovelli/switch-config.md
@@ -0,0 +1,296 @@
+# 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