Fado Custom Integration

A Home Assistant custom integration that provides smooth light
fading for brightness, colors, and color temperatures, with
automatic brightness restoration, autoconfiguration via the UI,
and support for native transitions.

Table of Contents

• Compatibility
• Features
• Installation
• How it works
  • Smooth Fading
  • Automatic Brightness Restoration
  • Manual interventions
  • Non-Dimmable Lights
  • Hybrid color/color temperature fading
• State Transitions
• Usage: fado.fade_lights
• Usage: fado.exclude_lights / fado.include_lights
• Autoconfiguration Panel
• Troubleshooting
• Development
• License

Compatibility

• Home Assistant: 2024.1.0 or newer
• Python: 3.13 or newer

Features

• Fade lights smoothly to any brightness level (0-100%) over a
  specified transition period, with easing
• Fade colors smoothly using HS, RGB, RGBW, RGBWW, XY, or color
  temperature (Kelvin)
• Hybrid transitions between color modes (e.g., color temperature
  to saturated color)
• Target lights by entity, device, area, floor, or label, or
  light groups
• Optionally specify starting values with the from: parameter
  for precise control
• Mostly drop-in replacement for the light.turn_on action
• Capability-aware: skips lights that don't support requested
  color modes
• Uses native transitions (where available) to smooth out each
  step for flicker-free fading
• Plays nicely with manual adjustments from the wall switch
• Setting brightness to 1% automatically sets the minimum real
  brightness supported by the light
• Autoconfiguration UI to determine optimal configuration for
  individual lights
• Exclude/include lights from fades and brightness restoration
  via actions or the configuration panel
• Automatic restoration of original (pre-fade) brightness when
  turning light on

Installation

HACS (Recommended)

Fado is available in the default HACS repository.

Or install by searching in HACS:

1. Open HACS in your Home Assistant instance
2. Search for "Fado"
3. Click "Download"
4. Restart Home Assistant

Manual Installation

1. Copy the custom_components/fado folder to your Home
   Assistant installation:

   <config_directory>/custom_components/fado/

2. Restart Home Assistant

Adding the integration

After installation and restart, add the integration via the
Home Assistant UI:

1. Go to Settings → Devices & services
2. Click + Add Integration
3. Search for "Fado"
4. Click to add it

Once configured, the Fado actions will be available in
Settings > Developer Tools → Actions.

Before anything, you should open the
Autoconfiguration Panel in the
Home Assistant sidebar and autoconfigure your lights.

How it works

The principle in action is that fades (usually executed by
automations) should be gradual and smooth, while manual actions
by the user (using the switch or the app to turn the light on or
off or to change the brightness or color), should be immediate,
otherwise the user may think that something has gone wrong.

Additionally, Fado tries to do the right thing. The API should
be straightforward and simple to use, while still allowing for
maximum flexibility.

You don't need to understand all of the details explained below
to use Fado. They are provided for interest only.

Smooth Fading

In Settings > Developer tools > Actions, or when
configuring an Action in an automation, use the
fado.fade_lights action to:

• select one or more target lights
• provide a target brightness (where zero means turn the
  light off), and/or a color or color temperature,
• specify a transition time, i.e. how long the fade should
  last,
• optionally specify an easing curve which by default tries
  to make the fade smoother during the lower brightness phase.
• optionally specify a from starting point in case you don't
  want to start from the current state of the light.

See Usage: fado.fade_lights for
parameter specifications.

Fade resolution

Fado resolves the targets list to a list of unique light
entities and dispatches a fade action for each entity, so the
fade for each light begins from the state that that light is
currently in.

It uses the transition time,
minimum delay setting, and the distance
between the beginning and end states (e.g. start- and
end-brightness, or start- and end-color) to calculate the
optimal number of steps and the size of each step that the fade
should use.

If the light doesn't support the specified change (for instance
changing color temperature on a light that only supports
brightness), or if the light is already in the final state, then
no fade is executed.

Fade execution

If there is an existing fade in progress then Fado cancels it
and waits for it to be cleaned up before starting the new fade.

If the light is currently on then Fado stores the current
brightness level as the original brightness. This is used for
automatic brightness restoration.

If a from parameter is specified, then it immediately sets the
light to the specified from state, after which the fade loop
begins.

For each step in the fade loop, Fado determines the next
brightness and color/color temp values, sets them, and records
how long it took. If the elapsed time is less than the
minimum delay, then it sleeps for the
remaining time before continuing with the next step. This means
that the total transition time will be at least as long as the
specified transition time. (It may, however, be longer if Home
Assistant or the network or the light itself is responding
slowly.)

If the light supports
native transitions then a short
transition time is used to apply a fade step to use the
light's hardware to make the fade smoother.

Fado stores the details of each fade step that is issued because
it expects to see a matching state change event which it will
recognise as its own and so knows to ignore it.

Automatic Brightness Restoration

When you fade a light down to off and then manually turn it back
on, the light turns on at the last brightness set by the fade
loop, which might be 1%. This is unlikely to be what you want.
Instead, the integration automatically restores the light to its
original brightness level before the fade started.

Example: Automatic Brightness Restoration

1. Light is at 80% brightness.
2. This value is stored as the original brightness.
3. You fade it to 0% (off) over 5 seconds.
4. Later, you turn the light on manually.
5. The light turns on at the last brightness the hardware is
   aware of, e.g. 1%.
6. Fado automatically restores the brightness to the
   original brightness value of 80%.

However, brightness restoration isn't always wanted. Imagine the
user turns on the light from an off state and simultaneously
changes the brightness, for instance by holding down the dimmer
switch to fade the brightness up until the switch is released.
In order to distinguish between this case and the previous case,
Fado also stores the brightness at the moment the light was
turned off.

Example: Turn on and simultaneously change brightness

1. Light is at 80% brightness.
2. You turn the light off.
3. Fado stores the brightness before turning the light off as
   previous brightness.
4. You turn the light on and hold the dimmer switch to change
   the brightness.
5. Fado compares the current brightness to the
   previous brightness.
6. If they are the same then it assumes the user has just turned
   the light on and it should restore the original brightness.
7. If they are different then it assumes the user has also
   changed the brightness, and it stores the new brightness as
   original brightness.

Manual interventions

During the fade loop, if Fado sees any event that it doesn't
expect, that means there has been a manual intervention (e.g.
the user uses the switch or app to switch the light on or off,
or to change the brightness or color). In this case Fado cancels
the running fade and waits for any in-flight steps to finish.
These in-flight steps might overwrite the user's intended
change, so once the in-flight events have been cleared, Fado
restores the intended state.

Example 1:

1. Light is at 80% brightness.
2. This value is stored as the original brightness.
3. You fade it to 0% (off) over 5 seconds.
4. When the fade reaches 30%, you turn the light off manually
   with the switch.
5. The fade is cancelled but an in-flight step turns the light
   back on at 25%.
6. Fado waits until the 25% event has been seen and no further
   events are expected.
7. Then it restores your intended state by turning the light
   off.
8. The stored original brightness remains at 80%

Example 2:

1. Light is at 80% brightness.
2. This value is stored as the original brightness.
3. You fade it to 0% (off) over 5 seconds.
4. When the fade reaches 30%, you turn the light off manually,
   and then back on again.
5. The light turns off then comes back on at 30%.
6. The fade is cancelled but an in-flight step turns the
   brightness to 25%.
7. Fado waits until the 25% event has been seen and no further
   events are expected.
8. Then it ignores the previous off state and restores your
   final intended state by turning the light on at the
   stored original brightness of 80%.

Non-Dimmable Lights

Lights that do not support brightness will turn off when
brightness is set to 0, or turn on when brightness is greater
than 0.

Hybrid color/color temperature fading

Colors and color temperatures overlap, but are not the same
thing. Color temperatures consist of limited shades of white
light, while colors can cover any color in the rainbow (but
typically don't display white light accurately).

Fading from one color to another is straightforward, as is
fading from one color temperature to another. Fado supports
hybrid fading as well, for instance fading from a color to a
color temperature or from a color temperature to a color. It
does this by dividing the fade into two phases, where the color
phase takes 70% of the transition time, and the color
temperature phase takes 30% of the transition time.

Fading from color to color temperature

• the color phase fades from the starting color to the closest
  color in the supported color temperature range
• the color temperature phase switches from color to color
  temperature at the crossover point and continues the fade to
  the target color temperature

Fading from color temperature to color

• the color temperature phase fades from the starting color
  temperature to the last supported color temperature closest to
  the target color
• the color phase switches from color temperature to color at
  the crossover point and continues the fade to the target color

Fading to color temperature where unsupported

If the user specifies a color temperature but the light only
supports RGB colors, then a best effort is made to use
hue-saturation to approximate the specified color temperature.

State Transitions

Fade state transitions

This table details how the fade is executed depending on the
initial state of the light and the target state. If the
from parameter is
used, the specified values are used as the initial state.

Manual change state transitions

This table details the changes applied when Fado detects a
manual event (i.e. an event from the switch or the app):

Fado uses the previous brightness to distinguish between
turning a light on, and turning a light on while simultaneously
changing the brightness level:

Usage: fado.fade_lights

Fades one or more lights to a target brightness and/or color
over a transition period.

Parameters

target (required):

Specify which lights to fade using any combination of:

• entity_id: One or more light entities
  (e.g., light.bedroom)

• device_id: One or more device IDs

• area_id: One or more area IDs (e.g., living_room)

• floor_id: One or more floor IDs

• label_id: One or more label IDs

  Light groups are automatically expanded to their individual
  lights. Duplicate entities are automatically deduplicated.

Transition (optional, default: 3):

How long the fade should take in seconds (supports decimals,
e.g., 0.5 for 500ms)

Brightness parameters (optional):

Either brightness_pct (0-100) or brightness (0-255).
A value of zero means off

Color or color temperature parameters (optional):

Only one target color or color temperature parameter allowed.

Either:

• color_temp_kelvin: Target color temperature in Kelvin
  (1000-40000)

or one of:

• hs_color: Target color as [hue, saturation] where hue
  is 0-360 and saturation is 0-100
• rgb_color: Target color as [red, green, blue]
  (0-255 each)
• rgbw_color: Target color as
  [red, green, blue, white] (0-255 each)
• rgbww_color: Target color as
  [red, green, blue, cold_white, warm_white] (0-255 each)
• xy_color: Target color as [x, y] (0-1 each)

The color parameters are converted to hue-saturation which are
used internally, while the color_temp_kelvin parameter is
converted to color_temp_mireds internally.

Starting values (optional from: block):

You can specify starting values to override the current light
state:

• from.brightness_pct: Starting brightness percentage
• from.color_temp_kelvin: Starting color temperature
• from.hs_color, from.rgb_color, etc.: Starting
  color (same formats as target colors)

Easing curves (optional, default Auto):

Changing the brightness from 100 to 101 is a 1% change, but
changing from 1 to 2 is a 100% change. This means that
brightness changes are more jarring the lower the brightness
level. Fado tries to make fading smoother by supporting easing
curves:

• auto (default): Uses ease_in_quad when start
  brightness is less than end brightness, and ease_out_quad
  when end brightness is less than start brightness
• linear: Fades in a straight line
• ease_in_quad: Starts slow
• ease_in_cubic: Starts slower
• ease_out_quad: Ends slow
• ease_out_cubic: Ends slower
• ease_in_out_sine: Smooth S curve

Examples:

Basic fade:

action: fado.fade_lights
target:
  entity_id: light.bedroom
data:
  brightness_pct: 50
  transition: 5

Fade multiple lights using different targets:

action: fado.fade_lights
target:
  entity_id:
    - light.bedroom_wall
    - light.living_room_ceiling
    - light.outside_lights # light group
  area_id:
    - kitchen
  floor_id:
    - upstairs

data:
  brightness_pct: 80
  transition: 10

Fade color temperature (warm to cool white) with specified starting point:

action: fado.fade_lights
target:
  entity_id: light.bedroom
data:
  color_temp_kelvin: 6500
  transition: 30
  from:
    color_temp_kelvin: 2700

Fade to a specific color:

action: fado.fade_lights
target:
  entity_id: light.accent
data:
  hs_color: [240, 100] # Blue
  brightness_pct: 80
  transition: 5

Automation Example

automation:
  - alias: "Sunset fade"
    trigger:
      - platform: sun
        event: sunset
        offset: "-00:30:00"
    action:
      - action: fado.fade_lights
        target:
          area_id: living_room
        data:
          brightness_pct: 20
          transition: 1800 # 30 minutes

Usage: fado.exclude_lights / fado.include_lights

Excludes one or more lights from Fado. Excluded lights are
ignored by fade operations and state tracking.

Parameters

target (required):

Specify which lights to include or exclude using any
combination of:

• entity_id: One or more light entities
  (e.g., light.bedroom)
• device_id: One or more device IDs
• area_id: One or more area IDs (e.g., living_room)
• floor_id: One or more floor IDs
• label_id: One or more label IDs

Light groups are automatically expanded to their individual
lights. Duplicate entities are automatically deduplicated.

Examples

Exclude lights

action: fado.exclude_lights
target:
  entity_id: light.bedroom

Include lights by area

action: fado.include_lights
target:
  area_id:
    - kitchen
    - livingroom

Autoconfiguration Panel

After installation, Fado appears in your Home Assistant
sidebar. Click it to access the configuration panel where you
can autoconfigure each light for the smoothest fades with the
minimum of overhead.

Run auto-configure to automatically measure optimal step
timing, support for native transitions, and minimum real
brightness for each light

Settings

Minimum delay

Autoconfiguration measures how long it takes for a light to
apply changes to brightness and to report back its new state to
Home Assistant. This minimum delay is the amount of time (in
milliseconds) that Fado will wait between each fade step.

The lower this number, the smoother the fade can be but the more
events Home Assistant needs to process. However, there is no
point in sending more frequent updates than the light can
handle. While you can configure this setting manually, it is not
recommended to set it to a lower value than that determined by
autoconfiguration.

Accepts 50ms - 2000ms and defaults to the
global minimum delay. The minimum delay
for an individual light cannot be set lower than the global
minimum delay.

Minimum brightness

Home Assistant allows setting a brightness value anywhere from 1
to 255, but internally lights often use a different scale, for
instance 1 to 100. For these lights, setting a brightness value
of 1 might result in the light being turned off instead.

Autoconfigure determines the minimum brightness value where
light is still emitted. With Fado, setting a brightness
percentage or brightness value lower than this setting will
instead apply the minimum real brightness.

Native transitions

Some lights support native transitions, that is the light
hardware knows how to fade between two brightness levels. This
is triggered by passing a time value to the transition
parameter of light.turn_on. However, even if the light claims
to support transitions, in reality this may not be the case.
Also, the amount of time the transition takes may be very
different from the time passed to the transition parameter.

Autoconfiguration tests this out to determine (a) whether native
transitions are actually supported, and (b) how this affects the
minimum step delay.

By setting native transitions manually to Disable, Fado will
disable native transitions when autoconfiguring the minimum step
delay, and when applying fades to a light.

Exclude

Checking the Exclude checkbox next to a light will prevent
Fado from fading a light and also from autorestoring the
original brightness level.

Global minimum delay

This is the absolute minimum delay for all lights. No light may
have a custom minimum delay setting below this
value. It defaults to 100ms and has a minimum value of 50ms.

Log level

See Troubleshooting

Download diagnostics

The Download diagnostics link will download a JSON file
containing all of the data used by Fado for debugging purposes.
Important when submitting bug reports.

Disabling the sidebar panel

By default, Fado adds a Fado Light Fader entry to the Home
Assistant sidebar, visible to all users. If you prefer to control
who can access the Fado UI, you can disable the sidebar panel and
use a custom dashboard
instead.

To disable the sidebar panel:

1. Go to Settings → Devices & Services → Fado → Configure
2. Uncheck Show sidebar panel
3. Click Submit

The sidebar entry will be removed immediately. The Fado card and
dashboard strategy remain available for use in any Lovelace
dashboard.

Custom Autoconfiguration dashboard

Fado provides a custom Lovelace card (custom:fado-card) and a
dashboard strategy (custom:fado) that give you the same
autoconfiguration UI as the sidebar panel, but with full control
over dashboard visibility and placement.

Adding the Fado card to an existing dashboard

You can add the Fado card to any Lovelace dashboard:

1. Edit your dashboard and click Add Card
2. Search for Fado Light Fader in the card picker
3. Add the card

Or add it manually in YAML mode:

type: custom:fado-card

For best results, use the card in a Panel view (single card
filling the full page).

Creating a dedicated Fado dashboard

To create a standalone Fado dashboard using the built-in strategy:

1. Go to Settings → Dashboards → Add Dashboard
2. Set the URL to something like lovelace-fado
3. Configure visibility (e.g. admin only, or specific users)
4. Open the dashboard and switch to raw configuration editor
   (Edit Dashboard → Raw configuration editor)
5. Replace the contents with:

strategy:
  type: custom:fado

This creates a full-page dashboard with the Fado card. You can
then control which users see it via the dashboard visibility
settings.

Notifications

When Fado detects lights that haven't been autoconfigured yet,
it shows a persistent notification to prompt you to configure
them.

You can control this behaviour in Settings → Devices &
Services → Fado → Configure:

• Enable notifications — Uncheck to disable unconfigured
  light notifications entirely.
• Dashboard URL — When the sidebar panel is disabled,
  notification links point to this URL (e.g.
  /lovelace-fado/0). Leave blank to omit the link from
  notifications.

Troubleshooting

Enable logging via UI

Go to the
Autoconfiguration Panel by
clicking Fado in the Home Assistant sidebar, and adjust the
Log level verbosity setting:

For most troubleshooting, info level is sufficient and easier
to follow.

This log level setting is persisted across restarts.

Known Problems

Different lights behave differently, and these differences can
create problems.

Rounding

The values set by Fado are not necessarily what the light
reports back. For instance, Fado sets a brightness of 50% but
the light reports a brightness of 51%. Fado uses rounding to
try to match these values regardless.

Missing and extra events

A light may compress several actions into a single event, so
while applying a fade step the user turns the light off. This
manual intervention may be ignored by the light and so the fade
loop continues. Alternatively, maybe the light-off event is
reported and the fade step never generates an event.

When using native transitions, the light
may emit state update events which are mid-range, e.g. a fade
step is intended to move the light from brightness 50 to
brightness 65, but the light may also report an intermediate
brightness state of 55. Intermediate steps are recognised but
are not removed from the list of expected states as the light
should later report a final state which matches the 50->65
change.

Fado maintains an expected-events list internally. These events
are pruned after 3 seconds so that, even if things do
occassionally go wrong, within 3 seconds the light should be
functioning normally again.

Reporting Issues

If you encounter a bug, please
open an issue
with:

• Your Home Assistant version
• The integration version
• Debug logs showing the problem
• Diagnostic data (available from the
  Autoconfiguration Panel)
• Steps to reproduce

Development

Running Tests

The integration includes a comprehensive test suite with 668
tests covering config flow, action handling, fade execution,
color fading, manual interruption detection, and brightness
restoration.

Prerequisites

Install the test dependencies:

pip install pytest pytest-asyncio pytest-cov pytest-homeassistant-custom-component syrupy

Note: Do not use pip install -e . (editable install) as
it conflicts with
pytest-homeassistant-custom-component's custom component
discovery mechanism.

Running Tests

Run all tests:

pytest tests/ -v

Run tests with coverage report:

pytest tests/ --cov=custom_components.fado --cov-report=term-missing -v

Run a specific test file:

pytest tests/test_fade_execution.py -v

Test Coverage

The test suite achieves 100% code coverage and includes tests
for:

• Config flow (test_config_flow.py): User setup, import
  flow, options validation
• Integration setup (test_init.py): Action registration,
  storage loading, unload cleanup
• Action handling (test_actions.py): Entity ID formats,
  group expansion, default parameters
• Fade execution (test_fade_execution.py): Fade up/down,
  turn off at 0%, non-dimmable lights
• Color parameters (test_color_params.py): Color
  conversions, validation, from: parameter
• Capability filtering (test_capability_filtering.py):
  Light capability detection, unsupported mode handling
• Step generation (test_step_generation.py): Hue
  interpolation, hybrid transitions
• Planckian locus (test_planckian_locus.py): Color
  temperature to HS conversions
• Manual interruption (test_manual_interruption.py):
  Brightness/color change detection, fade cancellation
• Brightness restoration
  (test_brightness_restoration.py): Restore on turn-on,
  storage persistence
• Exclude/include actions (test_exclude_action.py):
  Action registration, flag persistence, fade filtering, panel
  notification
• Event waiting (test_event_waiting.py):
  Condition-based event waiting, stale value pruning

Continuous Integration

Tests run automatically on push and pull requests via GitHub
Actions. The workflow tests against Python 3.13.

License

MIT License - feel free to modify and redistribute