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/advanced-features.md
+++ b/inovelli/advanced-features.md
@@ -0,0 +1,322 @@
+# 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