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/led-configuration.md
+++ b/inovelli/led-configuration.md
@@ -0,0 +1,428 @@
+# LED Configuration Properties
+
+Properties controlling the LED strip on the switch, including colors, intensity levels, animated effects, and display modes. The switch has 7 individual LEDs plus global defaults.
+
+## LED Effects
+
+### led_effect
+
+Composite property to control LED effects for the entire LED bar.
+
+- **Type**: Composite (requires MQTT publish)
+- **Description**: Controls animation effects for all LEDs on the bar
+- **Access**: Set via MQTT publish to `zigbee2mqtt/[device_name]/set`
+- **Properties**:
+  - `effect`: Animation effect type
+  - `color`: Color value (0-255, hue-based)
+  - `level`: Brightness (0-100%)
+  - `duration`: How long the effect lasts
+- **Effect values**:
+  - `off` - Turn off LED effect
+  - `solid` - Solid color
+  - `fast_blink` - Fast blinking
+  - `slow_blink` - Slow blinking
+  - `pulse` - Pulsing effect
+  - `chase` - Chase/running pattern
+  - `open_close` - Open/close animation
+  - `small_to_big` - Small to big animation
+  - `aurora` - Aurora effect
+  - `slow_falling` - Slow falling effect
+  - `medium_falling` - Medium falling effect
+  - `fast_falling` - Fast falling effect
+  - `slow_rising` - Slow rising effect
+  - `medium_rising` - Medium rising effect
+  - `fast_rising` - Fast rising effect
+  - `medium_blink` - Medium blink
+  - `slow_chase` - Slow chase
+  - `fast_chase` - Fast chase
+  - `fast_siren` - Fast siren
+  - `slow_siren` - Slow siren
+  - `clear_effect` - Clear/stop current effect
+- **Duration encoding**:
+  - `1-60` = Seconds
+  - `61-120` = Minutes (value - 60)
+  - `121-254` = Hours (value - 120)
+  - `255` = Indefinitely
+
+**Example usage:**
+```yaml
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "pulse", "color": 170, "level": 100, "duration": 255}}'
+```
+
+### individual_led_effect
+
+Composite property to control effects for a single LED.
+
+- **Type**: Composite (requires MQTT publish)
+- **Description**: Controls animation effects for one specific LED
+- **Access**: Set via MQTT publish to `zigbee2mqtt/[device_name]/set`
+- **Properties**:
+  - `led`: LED number (1-7, 1=bottom, 7=top)
+  - `effect`: Animation effect type
+  - `color`: Color value (0-255)
+  - `level`: Brightness (0-100%)
+  - `duration`: How long the effect lasts
+- **LED numbering**: 1 (bottom) through 7 (top)
+- **Effect values**:
+  - `off` - Turn off LED effect
+  - `solid` - Solid color
+  - `fast_blink` - Fast blinking
+  - `slow_blink` - Slow blinking
+  - `pulse` - Pulsing effect
+  - `chase` - Chase pattern
+  - `falling` - Falling effect
+  - `rising` - Rising effect
+  - `aurora` - Aurora effect
+  - `clear_effect` - Clear/stop effect
+- **Duration encoding**: Same as led_effect
+
+**Example usage:**
+```yaml
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"individual_led_effect": {"led": "4", "effect": "fast_blink", "color": 0, "level": 100, "duration": 30}}'
+```
+
+## Global LED Properties
+
+### ledColorWhenOn
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 170 (Blue)
+- **Description**: Default LED strip color when switch is on. Applies to all LEDs unless individually configured.
+- **Home Assistant Entity**: `number.[device_name]_led_color_when_on`
+- **Color wheel mapping**: 0-255 representing hue (0-360° mapped to 0-255)
+- **Preset colors**:
+  - `0` = Red
+  - `21` = Orange
+  - `42` = Yellow
+  - `85` = Green
+  - `127` = Cyan
+  - `170` = Blue
+  - `212` = Violet
+  - `234` = Pink
+  - `255` = White
+
+### ledColorWhenOff
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 170 (Blue)
+- **Description**: Default LED strip color when switch is off.
+- **Home Assistant Entity**: `number.[device_name]_led_color_when_off`
+- **Preset colors**: Same as ledColorWhenOn
+
+### ledIntensityWhenOn
+
+- **Type**: Number
+- **Range**: 0-100
+- **Default**: 33 (33%)
+- **Description**: Default LED strip brightness when switch is on.
+- **Home Assistant Entity**: `number.[device_name]_led_intensity_when_on`
+- **Special values**:
+  - `0` = LEDs off (no indicator when on)
+  - `1-100` = Brightness percentage
+- **Common values**:
+  - Night mode: `5-10`
+  - Default: `33`
+  - Maximum visibility: `100`
+
+### ledIntensityWhenOff
+
+- **Type**: Number
+- **Range**: 0-100
+- **Default**: 1 (1%)
+- **Description**: Default LED strip brightness when switch is off.
+- **Home Assistant Entity**: `number.[device_name]_led_intensity_when_off`
+- **Common values**:
+  - Nightlight: `1-5`
+  - Locator: `10-20`
+  - Off (stealth): `0`
+
+## Individual LED Properties
+
+Each of the 7 LEDs can be individually configured with color and intensity for both on and off states. LED #1 is the bottom, LED #7 is the top.
+
+### LED #1 (Bottom)
+
+- **Color When On**: `number.[device_name]_default_led1_color_when_on` (0-255, 255=sync with global)
+- **Color When Off**: `number.[device_name]_default_led1_color_when_off` (0-255, 255=sync with global)
+- **Intensity When On**: `number.[device_name]_default_led1_intensity_when_on` (0-101, 101=sync)
+- **Intensity When Off**: `number.[device_name]_default_led1_intensity_when_off` (0-101, 101=sync)
+
+### LED #2
+
+- **Color When On**: `number.[device_name]_default_led2_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led2_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led2_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led2_intensity_when_off`
+
+### LED #3
+
+- **Color When On**: `number.[device_name]_default_led3_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led3_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led3_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led3_intensity_when_off`
+
+### LED #4 (Middle)
+
+- **Color When On**: `number.[device_name]_default_led4_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led4_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led4_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led4_intensity_when_off`
+
+### LED #5
+
+- **Color When On**: `number.[device_name]_default_led5_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led5_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led5_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led5_intensity_when_off`
+
+### LED #6
+
+- **Color When On**: `number.[device_name]_default_led6_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led6_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led6_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led6_intensity_when_off`
+
+### LED #7 (Top)
+
+- **Color When On**: `number.[device_name]_default_led7_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led7_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led7_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led7_intensity_when_off`
+
+**Note**: Individual LED color set to `255` or intensity set to `101` means "follow global default"
+
+## 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
+  - Preference for single LED indicator
+  - Reduce LED brightness/distraction
+
+## Configuration Patterns
+
+### Standard Blue Indicator
+
+```yaml
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_on
+data:
+  value: 170  # Blue
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_off
+data:
+  value: 170  # Blue
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_on
+data:
+  value: 33
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_off
+data:
+  value: 1
+```
+
+### Green On / Red Off
+
+```yaml
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_on
+data:
+  value: 85  # Green
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_off
+data:
+  value: 0  # Red
+
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_led_intensity_when_on
+    - number.bedroom_switch_led_intensity_when_off
+data:
+  value: 40
+```
+
+### Stealth Mode
+
+```yaml
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_led_intensity_when_on
+    - number.bedroom_switch_led_intensity_when_off
+data:
+  value: 0
+```
+
+### Nightlight Mode
+
+```yaml
+# Soft pink when off, dark when on
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_off
+data:
+  value: 234  # Pink
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_off
+data:
+  value: 5
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_on
+data:
+  value: 0
+```
+
+### Rainbow Bar (Individual LEDs)
+
+```yaml
+# Set each LED to a different color
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_default_led1_color_when_on
+data:
+  value: 0  # Red
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led2_color_when_on
+data:
+  value: 42  # Yellow
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led3_color_when_on
+data:
+  value: 85  # Green
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led4_color_when_on
+data:
+  value: 127  # Cyan
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led5_color_when_on
+data:
+  value: 170  # Blue
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led6_color_when_on
+data:
+  value: 212  # Violet
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led7_color_when_on
+data:
+  value: 234  # Pink
+```
+
+### Notification Alert (Pulse Red)
+
+```yaml
+# 30 second red pulse on all LEDs
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "pulse", "color": 0, "level": 100, "duration": 30}}'
+```
+
+### Status Indicator (Middle LED Blink)
+
+```yaml
+# Blink middle LED (LED 4) blue for 1 minute
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"individual_led_effect": {"led": "4", "effect": "fast_blink", "color": 170, "level": 100, "duration": 60}}'
+```
+
+### Doorbell Notification (Fast Chase)
+
+```yaml
+# Fast chase effect in cyan for 10 seconds
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "fast_chase", "color": 127, "level": 100, "duration": 10}}'
+```
+
+### Clear All Effects
+
+```yaml
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "clear_effect"}}'
+```
+
+## LED Color Palette
+
+Quick reference for common colors (hue-based, 0-255):
+- `0` - Red
+- `21` - Orange
+- `42` - Yellow
+- `64` - Yellow-Green
+- `85` - Green
+- `106` - Cyan-Green
+- `127` - Cyan
+- `148` - Blue-Cyan
+- `170` - Blue (default)
+- `191` - Blue-Violet
+- `212` - Violet
+- `223` - Magenta
+- `234` - Pink
+- `244` - Pink-Red
+- `255` - White
+
+## Notes
+
+- Individual LED properties override global defaults
+- Setting individual LED color to `255` makes it follow global color
+- Setting individual LED intensity to `101` makes it follow global intensity
+- LED effects from `led_effect` and `individual_led_effect` are temporary
+- Effects automatically clear after duration expires or when `clear_effect` is sent
+- Property changes take effect immediately without requiring switch reboot
+- Use MQTT publish for LED effects; they cannot be set via Home Assistant number/select entities