LightStack Home Assistant Integration

A Home Assistant custom component for LightStack - a priority-based alert management system for Inovelli LED switches.

What is LightStack?

LightStack is a priority-based alert management system designed specifically for Inovelli smart switches with LED notification bars. It solves a common problem: when multiple alerts are active, only one LED state can be displayed at a time.

The Problem:

Without LightStack:
  alert 1 fires   -> switch displays alert 1
  alert 2 fires   -> switch displays alert 2
  alert 2 clears  -> switch shows "all clear" (WRONG! alert 1 is still active)

The Solution:

With LightStack:
  alert 1 fires   -> switch displays alert 1
  alert 2 fires   -> switch displays alert 2 (if higher priority)
  alert 2 clears  -> switch displays alert 1 (correctly shows remaining alert)

LightStack provides:

• Centralized alert state tracking across all your automations
• Priority-based display (5 levels: Critical, High, Medium, Low, Info)
• Full LED customization per alert (color, effect, brightness, duration)
• Real-time updates via WebSocket
• Web UI for managing alerts and viewing history

For more information about LightStack, including installation and configuration, visit the LightStack repository.

Features

• Real-time Updates: Uses WebSocket for instant push notifications - no polling required
• Current Alert Sensor: Shows the highest priority active alert with LED color/effect attributes
• Alert Status Binary Sensor: Simple on/off indicator when any alert is active
• Clear All Button: One-click button to clear all active alerts
• Services: Full control via Home Assistant services for automations

Platforms

Platform	Description
sensor	Shows the current (highest priority) active alert name with LED attributes
binary_sensor	Indicates if any alert is currently active (on) or all clear (off)
button	Clear all active alerts with a single press

Services

Service	Description
lightstack.trigger_alert	Trigger an alert by key, with optional priority override
lightstack.clear_alert	Clear a specific alert by key
lightstack.clear_all_alerts	Clear all active alerts

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Go to "Integrations"
3. Click the three dots in the top right corner
4. Select "Custom repositories"
5. Add https://github.com/sjafferali/lightstack-homeassistant as an Integration
6. Click "Install"
7. Restart Home Assistant

Manual Installation

1. Copy the custom_components/lightstack directory to your Home Assistant's custom_components directory
2. Restart Home Assistant

After installation:

1. Go to Settings -> Devices & Services
2. Click "+ Add Integration"
3. Search for "LightStack"
4. Enter your LightStack server host and port

Configuration

The integration is configured through the UI:

Field	Description	Default
Host	Hostname or IP of your LightStack server	localhost
Port	WebSocket API port	8080

Sensor Attributes

The Current Alert sensor provides these attributes for use in automations:

Attribute	Description
is_all_clear	Boolean indicating if all alerts are cleared
active_count	Number of currently active alerts
alert_key	Unique identifier of the current alert
effective_priority	Priority level (1-5) of the current alert
priority_name	Human-readable priority (Critical, High, Medium, Low, Info)
led_color	Inovelli LED color value (0-255)
led_color_name	Human-readable color name (Red, Blue, Green, etc.)
led_effect	LED effect code (solid, pulse, chase, aurora, etc.)
led_effect_name	Human-readable effect name (Solid, Pulse, Chase, etc.)
led_brightness	LED brightness level (0-100)
led_duration	LED duration value (encoded, see below)
led_duration_name	Human-readable duration (e.g., "5 Minutes", "Indefinitely")
last_triggered	Timestamp when the alert was last triggered
description	Alert description if configured

LED Effects

All supported Inovelli Blue series LED effects:

Effect Code	Display Name
off	Off
solid	Solid
fast_blink	Fast Blink
slow_blink	Slow Blink
pulse	Pulse
chase	Chase
open_close	Open/Close
small_to_big	Small to Big
aurora	Aurora
slow_falling	Slow Falling
medium_falling	Medium Falling
fast_falling	Fast Falling
slow_rising	Slow Rising
medium_rising	Medium Rising
fast_rising	Fast Rising
medium_blink	Medium Blink
slow_chase	Slow Chase
fast_chase	Fast Chase
fast_siren	Fast Siren
slow_siren	Slow Siren
clear_effect	Clear Effect

LED Duration Encoding

Duration values are encoded as follows:

Value Range	Unit	Example
1-60	Seconds	30 = 30 seconds
61-120	Minutes	65 = 5 minutes
121-254	Hours	132 = 12 hours
255	Indefinite	Runs until cleared

Example Automations

Trigger an alert when garage door opens

automation:
  - alias: "Alert on Garage Door Open"
    trigger:
      - platform: state
        entity_id: cover.garage_door
        to: "open"
    action:
      - service: lightstack.trigger_alert
        data:
          alert_key: "garage_door_open"
          priority: 2
          note: "Garage door opened"

Clear alert when garage door closes

automation:
  - alias: "Clear Garage Door Alert"
    trigger:
      - platform: state
        entity_id: cover.garage_door
        to: "closed"
    action:
      - service: lightstack.clear_alert
        data:
          alert_key: "garage_door_open"

Set Inovelli LED based on LightStack state (Zigbee2MQTT)

For Inovelli Blue series switches with Zigbee2MQTT:

automation:
  - alias: "Update Inovelli LED from LightStack"
    trigger:
      - platform: state
        entity_id: sensor.lightstack_current_alert
    action:
      - service: mqtt.publish
        data:
          topic: "zigbee2mqtt/Office Switch/set"
          payload_template: >
            {% set sensor = states.sensor.lightstack_current_alert %}
            {% if sensor.state == 'All Clear' %}
              {"led_effect": {"effect": "off"}}
            {% else %}
              {
                "led_effect": {
                  "effect": "{{ sensor.attributes.led_effect | default('solid') }}",
                  "color": {{ sensor.attributes.led_color | default(0) }},
                  "level": {{ sensor.attributes.led_brightness | default(100) }},
                  "duration": {{ sensor.attributes.led_duration | default(255) }}
                }
              }
            {% endif %}

Set Inovelli LED (Z-Wave)

For Z-Wave Inovelli switches:

automation:
  - alias: "Update Inovelli LED from LightStack"
    trigger:
      - platform: state
        entity_id: sensor.lightstack_current_alert
    action:
      - choose:
          - conditions:
              - condition: state
                entity_id: sensor.lightstack_current_alert
                state: "All Clear"
            sequence:
              - service: zwave_js.set_config_parameter
                target:
                  entity_id: light.inovelli_switch
                data:
                  parameter: 16
                  value: 0 # Clear notification
          - conditions:
              - condition: template
                value_template: "{{ state_attr('sensor.lightstack_current_alert', 'led_color') is not none }}"
            sequence:
              - service: zwave_js.set_config_parameter
                target:
                  entity_id: light.inovelli_switch
                data:
                  parameter: 16
                  value: >
                    {% set color = state_attr('sensor.lightstack_current_alert', 'led_color') | default(0) %}
                    {% set effect = state_attr('sensor.lightstack_current_alert', 'led_effect') %}
                    {% set effect_num = {'solid': 1, 'fast_blink': 2, 'slow_blink': 3, 'pulse': 4}.get(effect, 1) %}
                    {{ (color * 65536) + (effect_num * 256) + 255 }}

Requirements

• Home Assistant 2023.1.0 or newer
• LightStack server running and accessible

Troubleshooting

Cannot Connect

1. Verify LightStack server is running
2. Check the host and port are correct
3. Ensure there are no firewalls blocking the WebSocket connection
4. Check Home Assistant logs for detailed error messages

Entities Not Updating

The integration uses WebSocket push notifications. If entities stop updating:

1. Check if LightStack server is still running
2. Reload the integration from Settings -> Devices & Services
3. Check logs for reconnection messages

Related Projects

• LightStack - The priority-based alert management server this integration connects to

Contributing

Contributions are welcome! Please read the Contribution guidelines.

Credits

This project was generated from @oncleben31's Home Assistant Custom Component Cookiecutter template.

---