home-assistant-blueprints/inovelli/led-configuration.md

# 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