DEV Community: Jasper

I Retired My Hue Bridge. Here's How I Rebuilt Everything It Did (and More) in C#

Jasper — Mon, 19 Oct 2026 13:04:18 +0000

📖 Table of Contents

Introduction
What You Lose Without the Bridge
Rebuilding It in YAML
Thinking in Layers
Building a Room, One Line at a Time
- The Hallway
- The Office
- The Attic
- The Living Room
From Alarm to Notifications
Seeing Which Layer Won
Cheat Sheet
Things to Know Before You Start
Conclusion
Libraries

🔗 You can find the full source code of the libraries on GitHub. Every room in this article is taken from my showcase repository, a trimmed-down copy of my own home automation.

Introduction

My smart home started the way many do: with a Philips Hue starter kit. I screwed in the bulbs, stuck a dimmer switch to the wall and everything just worked. The switch cycled through scenes, holding a button dimmed the lights, and the motion sensor in the hallway knew the difference between day and night.

Then I discovered Home Assistant, and with it the freedom to connect my lights to everything else in the house. At some point I took the next step and retired the Hue Bridge altogether, pairing the bulbs, switches and sensors directly to my own Zigbee network through Zigbee2MQTT. Not because Hue fell short; for most homes it's good enough. I wanted my lights to behave exactly the way I had in mind, not like the closest option in an app.

That's when I found out how much the bridge had been doing for me. All the behaviour I took for granted was gone, and rebuilding it turned out to be a lot more work than I expected, and a lot more fun. This article is about that work, about why it gets messy so quickly, and about the library I built to keep it manageable: CodeCasa.AutomationPipelines.Lights.

This is the second article in a series about patterns for NetDaemon, which lets you write Home Assistant automations as C# applications, with entities exposed as strongly typed objects and state changes as observables. The first one introduced stateful boolean observables. Every node in this article is driven by one, but you can follow along without having read it.

What You Lose Without the Bridge

Once your Hue devices talk to Home Assistant directly, a dimmer switch is no longer a dimmer switch. It's a device that emits button events. A motion sensor is a binary sensor. What you do with them is entirely up to you, which sounds great until you write down what the bridge used to do:

Pressing the on button (the Hue button on the newer switch) repeatedly cycles through scenes, as long as the presses follow each other quickly.
Holding a button dims or brightens smoothly until you let go.
The motion sensor uses different scenes for day and night, and can be told to leave a room alone when the lights are already on.
Natural light shifts colour temperature and brightness through the day in a handful of time blocks.
A whole room is addressed with one command, not one per bulb.
A bulb that was switched off at the wall comes back in the state the room is in.

And then there were the things the bridge never quite did, but that I had always wanted: turning a light off by hand should stick instead of the motion sensor turning it right back on, and a doorbell or an alarm should be able to take the lights over for a moment and give them back afterwards.

💡 Note: If you keep the Hue Bridge and use Home Assistant's Hue integration, none of this applies. The bridge keeps running its own logic. This article is about the situation where Home Assistant is the only brain left. You don't need Hue for any of it, either. Any bulb, button and motion sensor that shows up in Home Assistant has the same problem: several automations writing to one light, with nobody deciding who wins.

Rebuilding It in YAML

None of these features is hard to build on its own. Here is a motion automation with a day and night scene:

- alias: Hallway motion
  triggers:
    - trigger: state
      entity_id: binary_sensor.hallway_motion
      to: "on"
  actions:
    - choose:
        - conditions:
            - condition: state
              entity_id: sun.sun
              state: below_horizon
          sequence:
            - action: scene.turn_on
              target:
                entity_id: scene.hallway_nightlight
      default:
        - action: scene.turn_on
          target:
            entity_id: scene.hallway_bright

Add a second automation that turns the lights off two minutes after the last motion and you have a working room. But then you add the wall switch, and the first problem shows up. Someone switches the hallway to bright to find something in the cupboard, and two minutes later the motion automation turns the lights off on them. The fix is an input_boolean.hallway_manual helper that the switch automation sets and both motion automations check.

Now imagine you want the lights to turn red when the security alarm is triggered. Turning them red is one more automation. However, to make it work you now need to update every other automation:

  # inside each of the other automations:
  conditions:
    - condition: state
      entity_id: input_boolean.hallway_manual
      state: "off"
    - condition: not
      conditions:
        - condition: state
          entity_id: alarm_control_panel.home
          state: triggered

This block has to go into the motion-on automation, the motion-off automation and every button of the switch automation, because any of them would happily overwrite the red light. And when the alarm ends, what should the room look like? Whatever it would have looked like without the alarm, which no single automation knows.

There are workarounds. You can snapshot the lights with scene.create and restore them afterwards, but then you restore a moment from the past: if the sun set or everybody left during the alarm, the room comes back wrong. You can disable the other automations with automation.turn_off, but then the triggers that fired in the meantime are lost. Both work until they don't. Blueprints such as the built-in Motion-activated Light and integrations like Adaptive Lighting each solve one of these problems well. What none of them give you is a place where the pieces meet.

The underlying issue is that every automation writes to the light directly, and nothing decides who wins. Home Assistant gives you triggers, conditions and actions, but it has no built-in notion of priority between automations. So every cross-cutting concern ends up as a condition in all of them. What is missing is not another trigger. It is a model.

Thinking in Layers

Getting a motion sensor, a switch and an alarm to share one bulb without tripping over each other is a proper design problem, and the kind I enjoy most. The model I ended up with is a pipeline per light. A pipeline is an ordered list of nodes, and each node represents one concern, a layer of behaviour: motion, the switch, the alarm. A node receives the output of the node before it and then does one of two things. It either sets its own output, or it passes through what it received, which is its way of saying "I have no opinion right now". What sets this apart from an ordinary pipeline is that a node does not only react to its input. Like a NetDaemon app, every node is an automation of its own: it can watch a sensor, a button or a timer and change its output at any moment. That is why the library calls these automation pipelines.

Later nodes win over earlier ones, so the order of the list is the priority. Every pipeline starts with a default value, off, which is what the first node receives as its input. A pipeline in which every node passes through therefore turns the light off. The light is only ever driven from the end of the pipeline, and no node knows about any other node. The motion layer keeps tracking motion while the alarm is active, so when the alarm node goes back to passing through, the room is immediately in the state it should be in at that moment. Nothing needs to be restored.

There is a third thing a node can do: take what it receives and change it. LimitBrightnessWhen(night, 100) caps the brightness of every layer before it, whatever scene they picked, and leaves colour and off alone. Most of this article is about the first two, but it is good to know the option exists.

The pipeline machinery lives in a small generic library, CodeCasa.AutomationPipelines. On top of it, CodeCasa.AutomationPipelines.Lights adds a fluent API for lights, and CodeCasa.AutomationPipelines.Lights.NetDaemon adds overloads for Home Assistant entities and scenes. That last package is the one to install. Registering everything used in this article looks like this:

services
    .AddNetDaemonScheduler()   // NetDaemon's IScheduler; everything time-based uses it
    .AddLightPipelines()
    .AddLightScenes()          // only if you pass Home Assistant scene entities (The Living Room)
    .AddLightNotifications();  // only for the notification layer (From Alarm to Notifications)

Everything time-based in the library takes an IScheduler from System.Reactive. In production that's the normal clock; in tests it's a virtual one, so a five-minute timeout can be tested in a millisecond.

Building a Room, One Line at a Time

Four rooms from the showcase are enough to rebuild the list from the start of this article: the hallway, the office, the attic and the living room.

A word on the inputs first. NetDaemon generates classes such as LightEntities, SensorEntities and SceneEntities from your Home Assistant instance, so lightEntities.HallwayLight is light.hallway_light. An app is a class marked [NetDaemonApp], and NetDaemon constructs it through dependency injection, which is where every constructor parameter below comes from. Without the bridge, a switch is just a Zigbee2MQTT device publishing button events. In the showcase these are wrapped in small classes that I register alongside the apps: HallwayWallSwitch is an IObservable<Unit> that emits on every press (Unit is Rx's way of saying "something happened, no value attached"), and OfficeDimmerSwitch exposes OnOffPressed, ScenePressed, Dimming and Brightening.

Wherever the API wants a light state, it accepts one of three things: a LightParameters object (brightness 0 to 255, a colour or a colour temperature; Bright, Relax, NightLight, Concentrate and Dimmed are built-in presets you can overwrite), a Home Assistant scene entity, or a timeline. Internally everything becomes a LightTransition, parameters plus a transition time.

The Hallway

If you read part one, this is the upstairs hallway light from that article, now as a pipeline.

Motion

The hallway has a Hue motion sensor, which Zigbee2MQTT exposes as an occupancy binary sensor and an illuminance sensor. MotionSensor from CodeCasa.NetDaemon.Sensors.Composite combines the two:

public class HallwayMotionSensor(
    IScheduler scheduler,
    BinarySensorEntities binarySensorEntities,
    SensorEntities sensorEntities)
    : MotionSensor(scheduler, binarySensorEntities.HallwayMotionSensorOccupancy,
        sensorEntities.HallwayMotionSensorIlluminance);

The result is a stateful IObservable<bool>. Stateful means it emits its current value the moment you subscribe, not only on the next change, so a pipeline that starts at eleven at night immediately knows that nobody is in the hallway. It becomes true when there is movement and the room is dark, and stays true until a minute after the last movement. That one observable replaces the motion-on automation, the motion-off automation and the illuminance condition.

Day and Night

The pipeline is a single SwitchWhen. It takes the observable that activates the node and a second one that chooses between two outcomes:

var night = PeriodTimeline.Between(AstroInstants.LocalSunsets, AstroInstants.LocalSunrises).ToBooleanObservable(scheduler);

lightPipelineFactory.SetupLightPipeline(lightEntities.HallwayLight, pipeline => pipeline
    .SwitchWhen(hallwayMotionSensor, night, LightParameters.NightLight, LightParameters.Bright)
    // ...

night comes from Occurify, my library for modelling time as instants and periods. AstroInstants.LocalSunsets is the recurring sunset for the coordinates you configure once at startup, PeriodTimeline.Between turns sunsets and sunrises into night periods, and ToBooleanObservable makes that a stateful observable that is true during those periods. If you'd rather not, sun.sun as a boolean observable works too.

While the motion sensor is false the node passes through, and since there is nothing before it the pipeline falls back to its default, which is off. Because both observables are stateful, this works at startup and at the moment the sun sets while somebody is in the hallway. The choose block from the YAML version is gone. Without the day and night distinction it would simply be When(hallwayMotionSensor, LightParameters.Bright).

Bright for Five Minutes

The hallway also has a wall switch. Sometimes you want proper light for a while, to find something in the cupboard, and then you want the hallway to go back to doing its own thing. The switch gets its own node, placed after the motion node, so it wins:

    .AddInteractionNode(node => node
        .AddToggle(hallwayWallSwitch, sp => sp.CreateAutoPassThroughLightNode(LightParameters.Bright, TimeSpan.FromMinutes(5)))));

The lambda is a node factory: a function that receives the service provider and builds the node when the toggle activates, so every press gets a fresh five-minute timer.

AddToggle decides from the actual state of the light. If it's off, a press activates the node: bright, for five minutes. After that the node does not turn the light off. It starts passing through. If there is still motion, the hallway falls back to the motion scene. If not, it goes dark. If the light is already on when the switch is pressed, from motion or from an earlier press, it turns off and stays off until the motion layer changes. There's also CreateAutoOffLightNode for when the timeout should turn the light off instead.

This is also where the input_boolean.hallway_manual helper went. While the switch node is active, the motion layer keeps doing its thing underneath, but its output never reaches the light. When motion ends it passes through, which changes nothing, because the switch layer is still in charge. Nothing needs to check a flag.

💡 Note: Deciding from the actual state has one catch. Walk into the hallway at night, the motion sensor turns the light on, and half a second later you press the switch, because you wanted proper light anyway. A plain toggle would see "on" and turn the light off. AddToggle therefore has a grace window, one second by default: if the light changed within that window and this toggle was not the cause, the press is judged against the state before the change. SetGracePeriod on the toggle configurator changes the window.

AddInteractionNode does one more thing: it watches the light itself. When somebody turns it off from outside the pipeline, with the Home Assistant app for example, the node holds it off until something earlier in the pipeline changes. Turning a light off by hand sticks. With HoldExternalChanges enabled it does the same for a scene or brightness set from outside, optionally for a limited time, so your existing YAML automations and the pipeline can coexist.

Put together, the whole app is this:

[NetDaemonApp]
internal class HallwayLightsApp
{
    public HallwayLightsApp(
        LightPipelineFactory lightPipelineFactory,
        LightEntities lightEntities,
        HallwayMotionSensor hallwayMotionSensor,
        HallwayWallSwitch hallwayWallSwitch,
        IScheduler scheduler)
    {
        var night = PeriodTimeline.Between(AstroInstants.LocalSunsets, AstroInstants.LocalSunrises).ToBooleanObservable(scheduler);

        lightPipelineFactory.SetupLightPipeline(lightEntities.HallwayLight, pipeline => pipeline
            .EnableLogging("Hallway")
            .SwitchWhen(hallwayMotionSensor, night, LightParameters.NightLight, LightParameters.Bright)
            .AddInteractionNode(node => node
                .AddToggle(hallwayWallSwitch, sp => sp.CreateAutoPassThroughLightNode(LightParameters.Bright, TimeSpan.FromMinutes(5)))));
    }
}

That is the whole hallway, in one file.

The Office

The Wall Switch and the Dimmer

The office has a wall switch and a Hue dimmer switch. Its pipeline doesn't use motion; I sit still for long enough that motion would be wrong more often than right. The complete pipeline:

lightPipelineFactory.SetupLightPipeline(lightEntities.OfficeLights, pipeline => pipeline
    .UseLightGroup(lightEntities.OfficeLightsZ2m)
    .AddInteractionNode(node => node
        .AddToggle(officeWallSwitch, LightParameters.Bright)
        .AddToggle(officeDimmerSwitch.OnOffPressed, LightParameters.Bright)
        .AddCycle(officeDimmerSwitch.ScenePressed, LightParameters.Bright, LightParameters.Concentrate, LightParameters.Relax)
        .AddReactiveDimmer(officeDimmerSwitch)
        .TurnOffWhenLastPersonToAsleepOrAway()));

There is a lot of Hue behaviour in these few lines:

The two AddToggle calls make the wall switch and the on button of the dimmer toggle between off and bright.
AddCycle is the scene button. Where the bridge counts presses, this looks at the actual state of the lights on every press to decide which scene comes next, with some tolerance, because a bulb asked for 255 will happily report 254. If the state isn't recognised, the cycle starts at the first scene. LightParameters.Bright and friends are built-in scenes, plain parameter sets really; the living room below uses Home Assistant scenes instead.
AddReactiveDimmer implements hold to dim, and does a little more than the bridge did. More on that below.
TurnOffWhenLastPersonToAsleepOrAway is not from the library. It's a ten-line extension method in the showcase, built on AddNodeSource, the primitive that all of the above is sugar for. Your own concerns slot in next to the built-in ones.

Holding the Button

AddReactiveDimmer takes an IDimmer, a tiny interface with two observables, Dimming and Brightening, which OfficeDimmerSwitch implements. While one of them is true, the brightness changes by a fifth of the 0 to 255 range: once straight away, then every 400 ms. Only the brightness changes; colours stay as they are. The dimmer starts from whatever the interaction node is showing, so you dim the current scene, and it resets as soon as the interaction node switches to something else, so the next scene press shows that scene at its own brightness again.

With a single bulb that is all there is to it. With several bulbs it gets more interesting. Holding the dim button brings all bulbs down together until each reaches the minimum brightness, 2 out of 255 by default, where it waits for the others. Once all of them are at the minimum, the next step turns one bulb off, the step after that the next one, until the last bulb goes out. Holding the brighten button does the same in reverse: from a dark room, the bulbs come on at the minimum one at a time, in the opposite order, and once all of them are on they rise together to full brightness. You can dim a room down to one soft bulb in the corner without reaching for an app.

None of this is something you could have asked the bridge for. Nobody needs their lights to go out one by one, but this is the fun part of owning every step between the button and the bulb: when you have an idea of how a room should behave, you write it down.

By default the bulbs go out in the order the group lists them in Home Assistant. To choose your own order, and to change the minimum, the step size or the speed, pass DimmerOptions along with the dimmer. AsLight() wraps a Home Assistant entity as the library's ILight:

var dimmerOptions = new DimmerOptions { MinBrightness = 10 };
dimmerOptions.SetLightOrder(
    lightEntities.OfficeCeilingLight.AsLight(),
    lightEntities.OfficeWindowLight.AsLight(),
    lightEntities.OfficeDeskLight.AsLight());  // the desk lamp stays on longest

lightPipelineFactory.SetupLightPipeline(lightEntities.OfficeLights, pipeline => pipeline
    .UseLightGroup(lightEntities.OfficeLightsZ2m)
    .AddInteractionNode(node => node
        // toggles and cycle as before
        .AddReactiveDimmer(officeDimmerSwitch)
        .SetReactiveDimmerOptions(dimmerOptions)));

The order must list exactly the bulbs in the pipeline, the bulbs themselves rather than the group, or setup throws.

One Command for the Whole Room

That leaves one item on the list for the office. lightEntities.OfficeLights is a Home Assistant light group, a software list of three bulbs. The library flattens it and builds one pipeline per bulb, because scenes can give every bulb its own colour and, as you'll see later, notifications can choose which bulbs they apply to. The downside is that a scene change results in three separate Zigbee commands instead of one. That's more traffic on the network, and if one of those commands is delayed or dropped, the bulbs end up in different states. The bridge avoided this by addressing the Zigbee group. UseLightGroup, the first line of the pipeline, does the same with OfficeLightsZ2m, a group created in Zigbee2MQTT that Zigbee itself understands, so one command reaches all bulbs. The pipeline's lights must be exactly the members of that group. The library can only check this when Home Assistant lists the group's members, which it doesn't for a Zigbee2MQTT group, so keeping the two in sync is up to you.

Each bulb's output is held back for a very short window, 20 ms by default. If all members of the group ask for the same thing within that window, a single command goes to the group. If they differ, for instance because a scene gives every bulb its own colour, each bulb is driven individually. You get the single command when it's possible and the per-bulb control when it's needed. The dimmer from the previous section plays along: while all bulbs dim together from the same scene, each step is one group command; once they start going out one by one, each bulb is driven on its own.

One more bridge feature comes for free here. A bulb that is switched off at the wall misses every command sent while it was gone. When it reports available again, the pipeline re-applies its current output, so the bulb joins the room in the state it should be in. This is on by default and can be turned off with ReapplyOutputWhenAvailable(false).

💡 Note: If every bulb in a room always shows the same thing, you can skip the split and the 20 ms wait altogether by setting up the pipeline for the Zigbee2MQTT group itself: SetupLightPipeline(lightEntities.OfficeLightsZ2m, ...). The library only splits a light into bulbs when Home Assistant lists its members in an entity_id attribute, which a light group has and a Zigbee2MQTT group doesn't, so this gives you a single pipeline that drives the group entity. You give up everything that works per bulb: scenes with a colour per bulb, notifications on some of the bulbs, the dimmer's one-at-a-time behaviour, noticing that one bulb was turned off by hand, and re-applying the output to one bulb that comes back from the wall switch. Pick one of the two setups per room; two pipelines driving the same bulbs bring back the question of who wins.

The Attic

Hue's natural light can be rebuilt with an Occurify timeline. A timeline maps moments of the day to light parameters, and the pipeline interpolates between them continuously. In the attic the wall switch toggles a timeline instead of a fixed scene:

Action<ITimelineConfigurator> naturalLight = tl => tl
    .Add(AstroInstants.LocalSunrises, LightParameters.Bright)
    .Add(AstroInstants.LocalSunsets.OffsetHours(-2), LightParameters.Bright)
    .Add(AstroInstants.LocalSunsets, LightParameters.Dimmed)
    .Add(TimeZoneInstants.DailyAt(5), LightParameters.Dimmed);

lightPipelineFactory.SetupLightPipeline(lightEntities.AtticLights, pipeline => pipeline
    .UseLightGroup(lightEntities.AtticLightsZ2m)
    .AddInteractionNode(node => node
        .AddToggle(atticWallSwitch, naturalLight)));

From sunrise until two hours before sunset the attic is bright. Over the last two hours of daylight it drifts to dimmed, slowly enough that nobody notices, stays dimmed until five in the morning, and ramps back up to bright at sunrise. Between two entries the pipeline always interpolates, so holding a value means adding it twice: once where the hold starts and once where it ends. Where Hue's natural light steps through time blocks, this is one continuous ramp, and when a ramp involves colour the blend is gamma-corrected, with a gamma I tuned against my own Hue bulbs until it matched their native transition. Timelines are accepted wherever parameters are: When(motion, naturalLight) for a motion layer, or as an entry in a toggle or cycle.

The Living Room

The living room scenes were made in the Home Assistant scene editor, with a different colour per bulb, and I wanted to keep them. The NetDaemon package accepts scene entities everywhere light parameters are accepted, provided AddLightScenes() is registered:

lightPipelineFactory.SetupLightPipeline(lightEntities.LivingRoomLights, pipeline => pipeline
    .UseLightGroup(lightEntities.LivingRoomLightsZ2m)
    .AddInteractionNode(node => node
        .AddToggle(livingRoomWallSwitch,
            sceneEntities.LivingRoomAmbiance,
            sceneEntities.LivingRoomRelax,
            sceneEntities.LivingRoomBright)
        .TurnOffWhenLastPersonToAsleepOrAway())
    .AddNotifications());

A toggle with several entries is the Hue on button: the first press gives the first scene, presses within a second of each other walk through the others and wrap around, and a press after a pause turns the lights off. Unlike AddCycle, the toggle's main job is on and off; the extra scenes are only reachable by pressing again quickly. SetToggleTimeout changes the window. Each scene is read from Home Assistant once, and each bulb's pipeline picks its own part of it.

The last line, AddNotifications, is where the alarm from the YAML chapter ends up.

From Alarm to Notifications

In a pipeline, the alarm from the YAML chapter could simply be one last node, When(alarmTriggered, red), that wins over everything and knows nothing about motion, switches or timeouts.

But an alarm is just one reason to take over the lights for a while. The doorbell, the washing machine and the smoke detector are others, and none of them belong in the living room code. For this there is a separate package, CodeCasa.Notifications.Lights, registered with AddLightNotifications() as shown earlier. Every pipeline that should show notifications opts in with the line you saw in the living room:

    .AddNotifications();

Any other application can now raise a notification, without knowing which lights or pipelines exist. It shows up as the last layer of every pipeline that opted in:

In the showcase, the doorbell is the one raising notifications:

[NetDaemonApp]
internal class DoorbellLightNotifications
{
    public DoorbellLightNotifications(
        FrontDoorDoorbell frontDoorDoorbell,
        LightNotificationContext lightNotifications,
        IScheduler scheduler)
    {
        const string notificationId = nameof(DoorbellLightNotifications);

        frontDoorDoorbell.BellPressed
            .PersistTrueFor(TimeSpan.FromSeconds(30), scheduler)
            .SubscribeTrueFalse(
                () => lightNotifications.Notify(notificationId, sp => new BlinkNode(scheduler, Color.Blue, Color.White), priority: 10),
                () => lightNotifications.RemoveNotification(notificationId));
    }
}

BellPressed is a binary sensor that is only on for a moment; PersistTrueFor stretches it to thirty seconds. A notification is a node factory, so it isn't limited to a fixed colour. The alarm would be a one-liner with a higher priority:

lightNotifications.Notify("Alarm", sp => new LightParameters { Brightness = 255, RgbColor = Color.Red }.AsPipelineNode(scheduler), priority: 100);

BlinkNode is a custom node, and writing one is not much work:

public class BlinkNode : LightTransitionNode
{
    private readonly IDisposable _timer;

    public BlinkNode(IScheduler scheduler, Color firstColor, Color secondColor, TimeSpan? interval = null) : base(scheduler)
    {
        Name = "Blink";
        LightTransition[] states =
        [
            new LightParameters { Brightness = 255, RgbColor = firstColor }.AsTransition(),
            new LightParameters { Brightness = 255, RgbColor = secondColor }.AsTransition()
        ];

        Output = states[0];
        _timer = Observable.Interval(interval ?? TimeSpan.FromSeconds(1), scheduler)
            .Subscribe(tick => Output = states[(int)((tick + 1) % 2)]);
    }

    public override ValueTask DisposeAsync()
    {
        _timer.Dispose();
        return base.DisposeAsync();
    }
}

A node sets Output, or calls PassInputThrough() when it has no opinion. A node that cares about what comes from upstream overrides InputReceived; BlinkNode doesn't, so it ignores its input until it's disposed. The base class takes care of thread safety, so setting Output from a timer is fine.

💡 Note: A node that only needs services doesn't need a lambda. AddNode<TNode>() lets the library build it the same way NetDaemon builds your apps, filling in its constructor from the services you registered. It does so once, when the pipeline is set up; When<TNode>(observable) and Add<TNode>() in a toggle build a fresh node every time the layer activates. Because a group runs one pipeline per bulb, each copy can also ask for the bulb it controls, ILight, and for LightPipelineContext, which holds what the pipeline last sent to that bulb. In a lambda, the same services are a sp.GetRequiredService<ILight>() away.

When several notifications are active, the one with the highest priority is shown. When the last one is removed, every pipeline disposes its copy of the node, the notification layer passes through, and the room shows whatever the layers below have worked out in the meantime. If everybody left while the doorbell was blinking, the lights go off. If somebody picked a scene, that scene appears.

Seeing Which Layer Won

With several layers, "why is this light on?" becomes a fair question. Every pipeline can log each hop between nodes:

    .EnableLogging("Hallway")

The hallway app does this. Each line carries the light, the pipeline path, the node that produced the value and the value itself, so you can read which layer produced the final result:

[light.hallway_light] Hallway: Passing [Node 1] (Interaction node) value [temperature 4000 (255)] to pipeline output.

The lines are logged at Trace level, which is off by default, so enable it for the CodeCasa namespace when you need it. The same telemetry is available as data through AddTelemetrySubscriber, and the CodeCasa.AutomationPipelines.Lights.Mqtt package publishes a JSON snapshot of a pipeline's state over MQTT on every change, if you opt the pipeline in with PublishTelemetryToMqtt. From there, an MQTT sensor in Home Assistant can show on a dashboard which layer is driving each light.

Cheat Sheet

The list from the start of this article, plus a few things that came up along the way. Some of these did not make it into the text:

What you want	Pipeline equivalent
Button cycles through scenes	`AddCycle(trigger, scenes...)`
Button toggles on and off	`AddToggle(trigger, scene)`
Hold to dim or brighten	`AddReactiveDimmer(dimmer)` in the interaction node
Motion with day and night scenes	`SwitchWhen(motion, isNight, night, day)`
Natural light	`AddToggle(trigger, timeline)`, `When(observable, timeline)`
Whole room changes at once	`UseLightGroup(group)`
Bulb was unreachable for a moment	re-applied automatically when it comes back
Manual off sticks	`AddInteractionNode()`
Manual scene sticks too	`AddInteractionNode(new InteractionNodeOptions { HoldExternalChanges = true })`
Temporary override	`CreateAutoPassThroughLightNode`, `CreateAutoOffLightNode`
Doorbell, alarm, anything that takes the lights over	`AddNotifications()` + `LightNotificationContext.Notify(...)`
Your own concern (everyone asleep, nobody home)	`AddNodeSource(...)` in an extension method
Your own node, built by dependency injection	`AddNode<TNode>()`, `When<TNode>(observable)`, `Add<TNode>()` in a toggle
Cap brightness at night	`LimitBrightnessWhen(isNight, 100)`
Some lights in a room behave differently	`ForLights(ids, configure)` inside the pipeline

Things to Know Before You Start

This approach isn't for everyone, and I'd rather say so here than in the comments.

If YAML or the automation editor covers your needs, stay there. This needs C# and NetDaemon running next to Home Assistant.
If you still have a Hue Bridge and are happy with it, keep it. It does most of this out of the box.

This is for when you want your lights to do something no app offers, or when, like me, you enjoy building it.

And a few things to know if you do go ahead:

Restarts. When NetDaemon starts, every pipeline begins at its default, off, and applies it. Layers driven by stateful observables re-evaluate immediately, so a hallway with motion or a room under a timeline comes straight back. Anything that only exists because of a button press, a scene you cycled to or a five-minute override, is gone, and that room goes dark.
Scenes made in the scene editor are read from Home Assistant once and cached. After editing a scene, you restart your apps.
UseLightGroup requires the pipeline's lights to be exactly the members of the group. For a Zigbee2MQTT group the library can't check this, so keep the two in sync yourself.
Your existing automations keep working. To a pipeline they look like somebody changing the light by hand, so a manual off sticks and anything else is overwritten on the next upstream change, unless you enable HoldExternalChanges.
Everything runs on an IScheduler, which NetDaemon provides with AddNetDaemonScheduler(). In tests you swap in a TestScheduler and run a whole evening of motion, presses and timeouts in virtual time.

Conclusion

Moving away from the Hue Bridge showed me how much behaviour sits in a product that "just works". Rebuilding that behaviour wasn't the hard part. Keeping the pieces from getting in each other's way was.

Separating concerns into layers changed how I think about automating my home. Adding the alarm was one line, and removing it again would be one line too. Every new idea since has been a question of where in the pipeline it belongs, not which existing automations need another condition.

And it has been fun: deciding how a dimmer should behave across three bulbs, working out who should win when the doorbell rings, and then seeing the answer in my own living room. If that sounds appealing, I hope these libraries give you a head start.

Libraries

All libraries in this article are open source under the MIT license and available on NuGet:

CodeCasa.AutomationPipelines.Lights: the light pipelines
CodeCasa.AutomationPipelines.Lights.NetDaemon: overloads for NetDaemon entities and scenes
CodeCasa.Lights.NetDaemon.Scenes: reads Home Assistant scenes into light parameters
CodeCasa.Lights.Timelines: Occurify timelines as light transitions
CodeCasa.AutomationPipelines.Lights.Mqtt: pipeline telemetry over MQTT
CodeCasa.Notifications.Lights: notifications as a pipeline layer
CodeCasa.NetDaemon.Extensions.Observables: the boolean observables from part one (renamed since)
CodeCasa.NetDaemon.Sensors.Composite: the motion sensor that combines occupancy and illuminance

You can explore the full source code on GitHub. The rooms in this article live in the CodeCasa.Showcase repository, together with the dashboard and the other automations of my house.

If you find CodeCasa helpful or interesting, a ⭐️ on the repo would mean a lot!

Occurify: Fluent Time Modeling for .NET Developers

Jasper — Sat, 05 Apr 2025 12:11:19 +0000

📖 Table of Contents

Introduction
Usage
Design
- Instant
- Period
- Instant Timeline
- Period Timeline
Source Code

🔗 You can find the full source code for Occurify on GitHub.

Introduction

I’ve always found working with time in code way more complicated than it needs to be.

Whether it’s dealing with schedules, recurring events, or aligning actions across time zones, time-based logic quickly becomes messy, repetitive, and full of edge cases. I wanted a way to think about time more conceptually—to express ideas like “every sunset” or “weekdays between 9 and 5” without getting bogged down in hardcoded timestamps and brittle date math.

That’s why I built Occurify — a powerful and intuitive .NET library for defining, filtering, transforming, and scheduling time in a more human-friendly and composable way.

Occurify lets you break down time into clear building blocks: instants, periods, and timelines. It helps you reason about time the way you actually think about it—and then turns those ideas into clean, reliable code.

Whether you're working with time zones, cron expressions, solar events like sunrise and sunset, or even reactive scheduling, Occurify is designed to help you build smarter, more flexible time-driven systems.

In this article, I’ll walk you through:

How Occurify models time using instants, periods, and timelines
Defining dynamic and reusable time-based concepts (like "20 minutes after sunset")
Filtering, transforming, and composing timelines with a fluent API
Randomizing timing and filtering by patterns like weekdays or holidays
Scheduling real-world actions using ReactiveX
How the design of Occurify makes all these feats possible.

Usage

Instead of dealing with fixed timestamps, Occurify lets you think about time in a more human-friendly way. You don't need to precompute every possible event—just define the concept of an event, like "all sunsets," and let Occurify handle the rest.

As an example, let’s imagine we want to automate our lights to turn on in the evening.

Defining Timelines

Instead of manually maintaining a list of sunset times, we can simply use:

ITimeline sunsets = AstroInstants.LocalSunsets;

This timeline now represents every sunset dynamically—no need for hardcoded schedules.

Transforming Timelines

Want to schedule events 20 minutes after sunset? Just shift the timeline:

ITimeline twentyMinAfterSunset = sunsets + TimeSpan.FromMinutes(20);

Now, twentyMinAfterSunset dynamically represents every sunset, plus 20 minutes—no manual calculations needed.

Combining Timelines Into Periods

Now, let’s define a time when the lights should turn off and create a period from 20 minutes after sunset until 11 PM:

ITimeline elevenPm = TimeZoneInstants.DailyAt(hour: 23);
IPeriodTimeline lightOnPeriods = twentyMinAfterSunset.To(elevenPm);

With this, lightOnPeriods now represents all the evening periods when the lights should be on.

Filtering & Randomization

If you want the lights to turn on only on weekdays, you can filter the periods like this:

lightOnPeriods = lightOnPeriods.Within(TimeZonePeriods.Workdays());

To make the timing feel more natural, we can randomize the periods slightly by adding a variation of up to 10 minutes:

lightOnPeriods = lightOnPeriods.Randomize(TimeSpan.FromMinutes(10));

Using the Timeline

Checking if the Lights Should Be On Right Now

To check if the lights should be on at the current moment, you can simply use IsNow() on the lightOnPeriods timeline:

if (lightOnPeriods.IsNow()) {
    // Turn lights on.
}
else {
    // Turn lights off.
}

Enumerating Future (or Past) Events

You can easily enumerate future or past periods to check when the lights will go on. For example, let’s find out when the lights will turn on during the rest of the current month:

Console.WriteLine("The rest of the current month the lights will go on at:");
foreach (Period period in lightOnPeriods.EnumerateRange(DateTime.UtcNow, TimeZoneInstants.CurrentMonth().End!.Value)){
    Console.WriteLine(period.Start);
}

But due to the dynamic nature of timelines we can just as easily see when the lights will turn on in February 2050:

Console.WriteLine("In February 2050 the lights will go on at:");
foreach (Period period in lightOnPeriods.EnumeratePeriod(TimeZonePeriods.Month(2, 2050))){
    Console.WriteLine(period.Start);
}

Note that the period timeline only resolves the necessary periods when enumerated, ensuring efficiency.

Scheduling Automatic Actions

To automate actions based on the timeline, you can use ReactiveX, which provides a powerful way to handle event-driven programming. The SubscribeStartEnd method internally utilizes an IObservable, allowing you to schedule events reactively.

By default, this method even evaluates the current state of the timeline, invoking the applicable method on startup.

lightOnPeriods.SubscribeStartEnd(() => TurnLightsOn(), () => TurnLightsOff(), scheduler);

This approach allows you to focus on what matters—like defining when you want your lights to turn on—without manually handling the timing and scheduling. As a result, your code becomes more intuitive, dynamic, and use case-driven.

Curious about more use cases? Check out Occurify’s README on Github or explore the example code for more.

Design

Occurify uses 4 main concepts:

Concept	Represented by	Description
Instant	UTC `DateTime`	A single instant in time.
Period	`Period`	A period of time, defined by a start and end instant.
Instant timeline	`ITimeline`	A timeline containing instants.
Period timeline	`IPeriodTimeline`	A timeline containing periods.

Instant

An instant is represented using a DateTime with Kind set to DateTimeKind.Utc.

The valid range for an instant is from 01-01-0000 to 31-12-9999.

Period

A period is defined by two instants: a start and an end.

If the start is null, it means the period has no defined beginning (i.e., it started at the beginning of time).
If the end is null, it means the period has no defined end (i.e., it lasts indefinitely).
If both start and end are null, the period is infinite in both directions.

A period contains all instants that are greater than or equal to the start instant and smaller than the end instant:
(Start == null || instant >= Start) && (End == null || instant < End)

Key Concept: Consecutive periods (a period with the same start as the end of another) do not overlap, ensuring that each instant belongs to only one period.

Period Record:

record Period(DateTime? Start, DateTime? End) : IComparable<Period>

Different ways of creating a period:

DateTime utcNow = DateTime.UtcNow;

// Using extension methods
Period nowToOneHoursFromNow = utcNow.ToPeriodWithDuration(TimeSpan.FromHours(1));
Period nowToTwoHoursFromNow = utcNow.To(utcNow + TimeSpan.FromHours(2));
Period nowToNeverEnding = utcNow.To(null);

// Using static methods
Period nowToThreeHoursFromNow = Period.Create(utcNow, utcNow + TimeSpan.FromHours(3));

Instant Timeline

An instant timeline represents a timeline of instants.

Although an instant timeline implements IEnumerable<DateTime>, it does not necessarily represent a collection of instants. Instead, it can represent the concept of a specific timeline. For example, an instant timeline can represent the concept of "all sunsets," without having to calculate or store all sunset times in memory. Instants in the timeline are only calculated when the timeline is enumerated or iterated over.

Within Occurify, a timeline has the following properties:

Immutable: Once created, an instant timeline cannot be modified.
Deterministic: The timeline will always yield the same instants given the same parameters.
Works with UTC: All instants in an instant timeline are represented as DateTime values in UTC (DateTimeKind.Utc).

An instant timeline implements IEnumerable<DateTime>, meaning that you can enumerate through it to access all instants, starting from the earliest to the latest.

Timeline Interface:

public interface ITimeline : IEnumerable<DateTime>
{
    DateTime? GetPreviousUtcInstant(DateTime utcRelativeTo);
    DateTime? GetNextUtcInstant(DateTime utcRelativeTo);
    bool IsInstant(DateTime utcDateTime);
}

Different ways of creating an instant pipeline:

DateTime utcNow = DateTime.UtcNow;

// Using extension methods
ITimeline timeline1 = utcNow.AsTimeline();
ITimeline timeline2 = new[] { utcNow, utcNow + TimeSpan.FromHours(1) }.AsTimeline();

// Using static methods
ITimeline timeline3 = Timeline.FromInstants(utcNow, utcNow + TimeSpan.FromHours(1), utcNow, utcNow + TimeSpan.FromHours(3));
ITimeline timeline4 = Timeline.Periodic(TimeSpan.FromHours(1));

Note that timeline4 is not a timeline with concrete instants. Only when reading it, will the instants be resolved. Simular to Linq methods, filtering only wraps the timeline in a filter class. Instants will only be resolved by reading.

Period Timeline

A period timeline is defined by a start timeline and an end timeline and represents a timeline of periods.

Periods on the period timeline start at any instant on the start timeline and end by the next first instant on the end timeline. Periods cannot overlap.

Due to the nature of instant timelines, period timelines can also represent a concept, but in the form of a period. For example, a period timeline can represent a concept like "all periods between sunrise and sunset", by constructing it from an instant timeline that represents "all sunrises" and one that represents "all sunsets".

If the earliest instant on both the start and end timelines is an end instant, the first period is assumed to have always started (start = null). Simularly, if the last instant is a start instant, the last instant is assumed to never end (end = null). If a period has no start and no end, it is empty. A period timeline cannot contain an infinite period.

If there are more consecutive start instants, the earliest one defines the start of a period. In case there are consecutive end instants, the earliest one defines the end of a period.

A period timeline also implements IEnumerable<Period>. Enumerating a timeline will iterate all instants in a timeline from earliest to latest.

Period Timeline Interface:

public interface IPeriodTimeline : IEnumerable<Period>
{
    ITimeline StartTimeline { get; }
    ITimeline EndTimeline { get; }
}

Different ways of creating an period pipeline:

DateTime utcNow = DateTime.UtcNow;
Period period = utcNow.To(utcNow + TimeSpan.FromHours(2));

// Using extension methods on periods
IPeriodTimeline periodTimeline1 = period.AsPeriodTimeline();
IPeriodTimeline periodTimeline2 = new[] { period, period + TimeSpan.FromHours(2) }.AsPeriodTimeline();

// Using extension methods on instant timelines
ITimeline periodStartTimeline = Timeline.Periodic(TimeSpan.FromHours(1));
ITimeline periodEndTimeline = periodStartTimeline.OffsetMinutes(10);
IPeriodTimeline periodTimeline3 = periodStartTimeline.To(periodEndTimeline);

// Using static methods
IPeriodTimeline periodTimeline4 = PeriodTimeline.FromPeriods(period, period + TimeSpan.FromHours(2), period + TimeSpan.FromHours(4));
IPeriodTimeline periodTimeline5 = PeriodTimeline.Between(periodStartTimeline, periodEndTimeline);

Source Code

You can explore the full source code on GitHub.

If you find Occurify helpful or interesting, a ⭐️ on the repo would mean a lot!

Supercharging Home Assistant Automations: Initial States and Boolean Logic for NetDaemon Rx

Jasper — Tue, 28 Jan 2025 15:47:10 +0000

Introduction

As a software developer, I stepped into the home automation hobby relatively late (about 3 years ago). Being a .NET developer, it didn’t take me long to stumble upon NetDaemon, a great open source library using Home Assistant’s websocket API to allow .NET developers to write their automations in C#.
It was also this library that introduced me to ReactiveX for handling event streams. I immediately loved this powerful combination; allowing the fluent interface to write compact yet surprisingly readable code, something every developer likes!

Over time, as I refined my home automations, I developed patterns and libraries that significantly improved my implementations. This article is the first in a series where I’ll share these ideas, hoping to inspire other smart home enthusiasts.

In this first installment, I’ll dive into implementation patterns I use frequently when working on my smart home. These patterns not only make code more readable but also lead to more robust automations. I’ve also included two supporting libraries with useful extension methods to help you apply these patterns effectively.

If you’re a Home Assistant user looking to level up your automations, this article is for you!

State vs. State Changes: A Unified Approach

Entities in Home Assistant (and NetDaemon) can be used to get the current state of an entity — for example, whether a light is on, its brightness level, or other attributes. Automations in Home Assistant rely on triggers, which execute actions based on changes in state. Similarly, NetDaemon lets you use observables to subscribe to these updates.

Here’s a simple example from the NetDaemon documentation where a light is turned on when a binary sensor changes its state to “on”:

public ExampleAppHaContext(IHaContext ha)
{
    var entities = new Entities(ha);

    entities.BinarySensor.OfficeMotion
        .StateChanges()
        .Where(e => e.New.IsOn())
        .Subscribe(_ => entities.Light.Office.TurnOn());
}

This works well for triggers like motion sensors or switches, where actions are tied to discrete events without much concern for the current state. For example, if someone presses a switch, you turn a light on or off.

However, as I worked on my smart home, I realized that many automations rely on both the current state and state changes. Focusing solely on state changes can lead to unexpected behavior, particularly during system startups or power outages.

Take these scenarios, for instance:

Curtains should be closed between sunset and sunrise and open otherwise.
A closet light should turn on when the door is open and off when it’s closed.
The hallway light should adjust based on multiple factors, such as the sun’s position, whether people are asleep, and the bedroom door's state.

At first, you might think using state changes is enough. For example, here’s how you could automate curtains based on the sun’s elevation:

public Example(SunEntities sunEntities, CoverEntities coverEntities)
{
    const int curtainCloseSunElevation = 1;
    sunEntities.Sun
        .StateAllChanges()
        .Where(e =>
            e.New?.Attributes?.Elevation <= curtainCloseSunElevation &&
            e.Old?.Attributes?.Elevation > curtainCloseSunElevation)
        .Subscribe(s =>
        {
            coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
            coverEntities.LivingRoomBackWindowCurtain.CloseCover();
        });

    sunEntities.Sun
        .StateAllChanges()
        .Where(e =>
            e.New?.Attributes?.Elevation > curtainCloseSunElevation &&
            e.Old?.Attributes?.Elevation <= curtainCloseSunElevation)
        .Subscribe(s =>
        {
            coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
            coverEntities.LivingRoomBackWindowCurtain.OpenCover();
        });
}

This example will close the curtains when the sun goes below a certain elevation and will open them when it rises above. However, this is overlooking one important aspect of an entity: its current state. This might seem like a minor detail, as implementation using changes will cause the desired outcome to be “eventually correct”. However, this does influence the startup behavior of your smart home. Something that regularly occurs during development, but could also occur because of something external like a power outage.

Imagine a power outage occurs just before the curtains are about to close, and the system restarts after the elevation of the sun is under the threshold, the curtains will remain open all night. Something you or your family will probably even interpret as a bug.

And from a design perspective you could indeed argue that this is a bug: You want to align the state of the curtains with the state of the sun. Yet, this automation aligned the state of the curtains with changes in the state of the sun, not taking into account its current state. "Only state changes" and “current state followed by state changes” are different concepts.

Whether you want to call this a bug doesn’t really matter. You probably think this is not a big deal and already figured out this issue is easy to solve! Simply evaluate the current state of the entity upon startup and all is well.

And so, you end up with something like this:

public Example(SunEntities sunEntities, CoverEntities coverEntities)
{
    const int curtainCloseSunElevation = 1;

    // Subscribe to state changes
    sunEntities.Sun
        .StateAllChanges()
        .Where(e =>
            e.New?.Attributes?.Elevation <= curtainCloseSunElevation &&
            e.Old?.Attributes?.Elevation > curtainCloseSunElevation)
        .Subscribe(s =>
        {
            coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
            coverEntities.LivingRoomBackWindowCurtain.CloseCover();
        });

    sunEntities.Sun
        .StateAllChanges()
        .Where(e =>
            e.New?.Attributes?.Elevation > curtainCloseSunElevation &&
            e.Old?.Attributes?.Elevation <= curtainCloseSunElevation)
        .Subscribe(s =>
        {
            coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
            coverEntities.LivingRoomBackWindowCurtain.OpenCover();
        });

    // Evaluate current state
    if (sunEntities.Sun.Attributes?.Elevation <= curtainCloseSunElevation)
    {
        coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
        coverEntities.LivingRoomBackWindowCurtain.CloseCover();
    }
    else
    {
        coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
        coverEntities.LivingRoomBackWindowCurtain.OpenCover();
    }
}

Which might be cleaned up into something like this:

private const int CurtainCloseSunElevation = 1;

private readonly SunEntity _sun;
private readonly CoverEntities _coverEntities;

public Example(SunEntities sunEntities, CoverEntities coverEntities)
{
    _sun = sunEntities.Sun;
    _coverEntities = coverEntities;

    // Subscribe to state changes
    _sun
        .StateAllChanges()
        .Where(e =>
            (e.New?.Attributes?.Elevation <= CurtainCloseSunElevation &&
            e.Old?.Attributes?.Elevation > CurtainCloseSunElevation) ||
            (e.New?.Attributes?.Elevation > CurtainCloseSunElevation &&
             e.Old?.Attributes?.Elevation <= CurtainCloseSunElevation))
        .Subscribe(_ => EvaluateCurtainStates());

    // Evaluate current state
    EvaluateCurtainStates();
}

private void EvaluateCurtainStates()
{
    if (_sun.Attributes?.Elevation <= CurtainCloseSunElevation)
    {
        _coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
        _coverEntities.LivingRoomBackWindowCurtain.CloseCover();
        return;
    }

    _coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
    _coverEntities.LivingRoomBackWindowCurtain.OpenCover();
}

This code works well. It’s readable and does what it’s supposed to. However, after implementing logic using only state changes for a while, I began to appreciate the elegance of writing logic in a single, fluent line with Reactive Extensions. I wanted a way to represent both the entity's current state and its changes using observables, without sacrificing the fluency of Rx syntax.

To achieve this, I started using Prepend to add the entity’s current state to its state changes observable:

var sunState = sunEntities.Sun
    .StateAllChanges()
    .Prepend(
        new StateChange<SunEntity, EntityState<SunAttributes>>(
            sunEntities.Sun,
            null, // Initially, there is only a new state, so old is null.
            sunEntities.Sun.EntityState));

As I found myself using this structure often, I created the Stateful and StatefulAll extension methods for it. Allowing us to use the following implementation:

public Example(SunEntities sunEntities, CoverEntities coverEntities)
{
    const int curtainCloseSunElevation = 1;

    sunEntities.Sun
        .StatefulAll()
        .Where(e =>
            e.New?.Attributes?.Elevation <= curtainCloseSunElevation &&
            (e.Old == null || e.Old?.Attributes?.Elevation > curtainCloseSunElevation))
        .Subscribe(s =>
        {
            coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
            coverEntities.LivingRoomBackWindowCurtain.CloseCover();
        });

    sunEntities.Sun
        .StatefulAll()
        .Where(e =>
            e.New?.Attributes?.Elevation > curtainCloseSunElevation &&
            (e.Old == null || e.Old?.Attributes?.Elevation <= curtainCloseSunElevation))
        .Subscribe(s =>
        {
            coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
            coverEntities.LivingRoomBackWindowCurtain.OpenCover();
        });
}

Using this pattern allows us to keep writing our logic in the same clean fashion as when only subscribing to changes while still triggering on the entity’s initial state.

Note: The implementations of Stateful and StatefulAll use Observable.Defer so the most recent state is always reported upon subscribing.

💡 Note: (10 Feb 2025) After reading this article, the NetDaemon team adopted my proposal for an observable that emits the current state upon subscribing. I implemented this in NetDaemon, and it was released in version 25.5.0.

Leveraging Boolean Observables for Cleaner Code

You might notice that in the examples of the previous chapter, I implement both the open and close cases using separate statements even though they are opposites of each other.

Keeping them separate like this doesn’t make much sense from a coding perspective—it makes the implementation prone to mistakes; it is easy to overlook one of the two conditions while updating the other. Let’s improve this:

If we take a look at the functionality, all we really want is a trigger when the sun is/goes up and when the sun is/goes down. As this translates to either a true or a false we use the Select method to convert our statement into a boolean:

public Example(SunEntities sunEntities, CoverEntities coverEntities)
{
    const int curtainCloseSunElevation = 1;
    sunEntities.Sun
        .StatefulAll()
        .Select(e => e.New?.Attributes?.Elevation > curtainCloseSunElevation)
        .Subscribe(sunUp =>
        {
            if (sunUp)
            {
                coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
                coverEntities.LivingRoomBackWindowCurtain.OpenCover();
            }
            else
            {
                coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
                coverEntities.LivingRoomBackWindowCurtain.CloseCover();
            }
        });
}

The problem with this implementation, is that we don’t filter based on the old state of the sun, leaving us with duplicate triggers. Luckily ReactiveX is here to help us. Instead of checking for a specific change in the condition itself, we can utilize ReactiveX’s DistinctUntilChanged extension method to filter out any duplicate results, bringing us this implementation:

public Example(SunEntities sunEntities, CoverEntities coverEntities)
{
    const int curtainCloseSunElevation = 1;
    sunEntities.Sun
        .StatefulAll()
        .Select(e => e.New?.Attributes?.Elevation > curtainCloseSunElevation)
        .DistinctUntilChanged()
        .Subscribe(sunUp =>
        {
            if (sunUp)
            {
                coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
                coverEntities.LivingRoomBackWindowCurtain.OpenCover();
            }
            else
            {
                coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
                coverEntities.LivingRoomBackWindowCurtain.CloseCover();
            }
        });
}

As this pattern of combining a Select and DistinctUntilChanged to form a boolean observable (Observable<bool>) is so useful, we can turn it into a ToBooleanObservable extension method. And as there are now only two possible values (true or false) emitted from our observable, we can use an extension method like SubscribeTrueFalse for additional convenience and readability:

public Example(SunEntities sunEntities, CoverEntities coverEntities)
{
    const int curtainCloseSunElevation = 1;
    sunEntities.Sun
        .ToBooleanObservable(e => e.Attributes?.Elevation <= curtainCloseSunElevation)
        .SubscribeTrueFalse(
            () =>
            {
                coverEntities.LivingRoomFrontWindowCurtain.CloseCover();
                coverEntities.LivingRoomBackWindowCurtain.CloseCover();
            },
            () =>
            {
                coverEntities.LivingRoomFrontWindowCurtain.OpenCover();
                coverEntities.LivingRoomBackWindowCurtain.OpenCover();
            });
}

And there we have it—a concise, readable piece of code that does exactly what we need. It triggers the correct automation when our application starts up, and it doesn’t contain any duplicate logic.

Applying Patterns to Real-World Scenarios

Of course, the examples in the previous chapters are intentionally simple for the sake of illustration. Real-world use cases are rarely this straightforward. Often, multiple states need to be interpreted together, and there can be various possible outcomes depending on these states. While that’s true, I want to show you how these patterns shine especially in handling more complex cases.

By using the first pattern—adding the current state to the observable we are working with—we not only ensure that our automations trigger correctly from the start but also allow ourselves to leverage ReactiveX to combine, filter, and evaluate multiple observables upon startup. This becomes especially useful when dealing with more intricate conditions and behaviors.

When we introduce the second pattern, which leverages boolean observables, we can easily create helper methods for logical operators and scheduling. These methods make filtering more human-readable, resulting in a much better coding experience.

Combining these patterns makes for a coding experience that comes very close to explaining the use cases themselves.

Rather than explaining this in more detail, let’s dive into some real examples from my own smart home. These examples will showcase how these implementation patterns map directly to real-world use cases. While I’ve simplified a few of them for clarity, these are actual scenarios from my home automation setup:

Closing Bedroom Curtains (Logical Operators)

In addition to using stateful boolean observables, this example demonstrates how using IObservable<bool> allows us to apply logical operators (such as Or in this case) for clean and concise code.

const int nightTimeSunElevation = 0;
var nightTime = sunEntities.Sun
    .ToBooleanObservable(e => e.Attributes?.Elevation <= nightTimeSunElevation);

var anyoneAsleep = inputBooleanEntities.JasperAsleep.ToBooleanObservable()
    .Or(inputBooleanEntities.AnonAsleep.ToBooleanObservable());

nightTime.Or(anyoneAsleep).SubscribeTrueFalse(
    () => coverEntities.BedroomRollerShutter.CloseCover(),
    () => coverEntities.BedroomRollerShutter.OpenCover());

With this implementation, you can be confident that the curtains will close when it is nighttime or when anyone is asleep. Even if the automation starts up during nighttime, it will close the curtains if they are not already closed.

Closet Light (Scheduling)

In this example, we turn on the closet light when the door is opened, but only if no one is asleep. However, if the door is left open for too long, the light automatically turns off.

var noOneAsleep = inputBooleanEntities.JasperAsleep.ToBooleanObservable()
    .Or(inputBooleanEntities.AnonAsleep.ToBooleanObservable()).Not();

var closetDoorOpenShorterThanFiveMin = binarySensorEntities.BedroomClosetDoorSensorContact
    .ToOpenClosedObservable().LimitTrueDuration(TimeSpan.FromMinutes(5), scheduler);

noOneAsleep.And(closetDoorOpenShorterThanFiveMin).SubscribeTrueFalse(
    () => lightEntities.ClosetLight.TurnOn(),
    () => lightEntities.ClosetLight.TurnOff());

This example demonstrates the use the method alias ToOpenClosedObservable for more readable code, as well as the use of scheduling extension methods like LimitTrueDuration (from Reactive.Booleans) on IObservable<bool>.

Additionally, this example highlights the extra power of IObservable<bool> over IObservable<T>. A method like LimitTrueDuration is far simpler to implement with bool because the result we expect after the timeout is inherently clear.

Upstairs Hallway Light (Multiple Output States)

Even for more complex use cases, boolean observables continue to provide value. Consider the example where we want the upstairs hallway light to be triggered by motion. During the day, the light should turn on at full brightness; at night, it should be dimmed. We also want to dim the light during the day if anyone is taking a nap and the bedroom door is open.

In this case, we can use the CombineLatest extension method from System.Reactive.Linq to evaluate multiple states together. Since we’re using stateful observables here, we don't need to worry about startup edge cases.

const int nightTimeSunElevation = 0;
var nightTime = sunEntities.Sun
    .ToBooleanObservable(e => e.Attributes?.Elevation <= nightTimeSunElevation);

var anyoneAsleep = inputBooleanEntities.JasperAsleep.ToBooleanObservable()
    .Or(inputBooleanEntities.AnonAsleep.ToBooleanObservable());

var bedroomDoorOpen = binarySensorEntities.BedroomDoorSensorContact.ToOpenClosedObservable();

var motionSensorTriggered =
    upstairsHallwayMotionSensor.CreateMotionBrightnessDelayObservable(5,
        TimeSpan.FromMinutes(2));

nightTime.CombineLatest(anyoneAsleep, bedroomDoorOpen, motionSensorTriggered).Subscribe(tuple =>
    {
        // Unpacking the tuple into named variables for better readability.
        (bool nightTime, bool anyoneAsleep, bool bedroomDoorOpen, bool motionSensorTriggered) values = tuple;

        if (!values.motionSensorTriggered)
        {
            lightEntities.UpstairsHallwayLight.TurnOff();
            return;
        }

        var lowBrightness = values.nightTime || (values.anyoneAsleep && values.bedroomDoorOpen);
        lightEntities.UpstairsHallwayLight.TurnOn(new LightTurnOnParameters
            { Brightness = lowBrightness ? 50 : 255 });
    }
);

upstairsHallwayMotionSensor in this example is a custom class that combines the motion and brightness sensor entities of a motion sensor. The implementation of CreateMotionBrightnessDelayObservable is as follows:

public IObservable<bool> CreateMotionBrightnessDelayObservable(double brightnessThreshold, TimeSpan delayAfterNoMotion)
{
    var motionLastXTime = MotionOccupancySensor.PersistOnFor(_scheduler, delayAfterNoMotion);

    var brightnessLessThanX = MotionIlluminanceLuxSensor
        .ToBooleanObservable(s => s.State <= brightnessThreshold);

    var triggered = false;
    return motionLastXTime.CombineLatest(brightnessLessThanX, (motionTriggered, brightnessTriggered) =>
    {
        if (motionTriggered && brightnessTriggered)
        {
            triggered = true;
        }
        else if (!motionTriggered)
        {
            triggered = false;
        }

        return triggered;
    }).DistinctUntilChanged();
}

Note that while boolean observables are convenient, we can still leverage CombineLatest with observables of other types.

Christmas Tree Light Plug (Checking Entity Availability)

As a final example, I want to demonstrate RepeatWhenEntitiesBecomeAvailable<T>. This method repeats the last result of the observable it is applied to whenever one or more entities become available again. Here, it is used with a power plug for my Christmas tree, which only gets plugged in during the holidays. This implementation ensures that when the plug is powered, it turns on the lights as soon as Home Assistant reconnects.

const int nightTimeSunElevation = 0;
var nightTime = sunEntities.Sun
    .ToBooleanObservable(e => e.Attributes?.Elevation <= nightTimeSunElevation);

nightTime
    .RepeatWhenEntitiesBecomeAvailable(switchEntities.LivingRoomChristmasTreeLights)
    .SubscribeTrueFalse(
        () => switchEntities.LivingRoomChristmasTreeLights.TurnOn(),
        () => switchEntities.LivingRoomChristmasTreeLights.TurnOff());

In my opinion the logic of RepeatWhenEntitiesBecomeAvailable<T> could be applied to any automation, but if you do, it might be worth applying this kind of logic to a different layer in your application. For now I've added the method in NetDaemon.Extensions.Observables so you can easily take advantage of it.

Conclusion

While these patterns may seem like small tweaks to how we approach our implementations, the impact they can have is far-reaching. By transforming our entities into stateful event streams and leveraging boolean observables, we unlock a new level of readability and maintainability in our code.

The power of these patterns is amplified when combined with boolean logic and boolean specific scheduling, as demonstrated throughout this article. They allow us to express complex automation scenarios with clarity, making it easier to reason about and extend our automations over time.

Whether you’re a seasoned developer or just starting out with Home Assistant and NetDaemon, adopting these practices can help you write smarter, more reactive automations that scale with your smart home’s growing complexity.

Libraries

For readers who want to implement these concepts, the following libraries provide convenient extension methods and tools.

The methods discussed throughout this article are available in the NetDaemon.Extensions.Observables library on GitHub. You can also find it on NuGet.
As the boolean logic is not dependent on NetDaemon and can be applied to any implementation of IObservable<bool>, I created a separate library called Reactive.Booleans on GitHub, also available on NuGet.

Both libraries are open-source and licensed under the MIT license.

Design Decisions & Future Plans

Although scheduling is primarily managed by the Reactive.Boolean library, understanding the Entity can enhance certain scheduling methods. When calling WhenTrueFor or LimitTrueDuration directly on an Entity rather than on an IObservable<bool>, both LastChanged and the passage of time are utilized to determine whether a true value is emitted. For the sake of simplicity, the examples in this article do not demonstrate this behavior.
The NetDaemon.Extensions.Observables library now contains aliases for both on/off and open/close states. I chose these specific combinations because they are the ones I use most frequently in my automations. That said, I encourage you to create aliases in your own code to improve code readability for your specific use cases.
Given the parameterless ToBooleanObservable extension method, I considered adding boolean extension methods for entities (e.g. IObservable<bool> And(this Entity entity1, Entity entity2)). Even though this could make code even more compact, I decided against this for now as I believe it makes code less readable. I think requiring developers to first call ToBooleanObservable (or an alias) forces cleaner and more intentional code.

For example:

var frontWindowCurtainOpen = coverEntities.LivingRoomFrontWindowCurtain.ToOpenClosedObservable();
var backWindowCurtainOpen = coverEntities.LivingRoomBackWindowCurtain.ToOpenClosedObservable();

frontWindowCurtainOpen.Or(backWindowCurtainOpen)
    .SubscribeTrue(() => lightEntities.LivingRoomLights.TurnOff());

is clearer than:

coverEntities.LivingRoomFrontWindowCurtain.Or(coverEntities.LivingRoomBackWindowCurtain)
    .SubscribeTrue(() => lightEntities.LivingRoomLights.TurnOff());

In the second example, it’s less obvious whether the observable emits true or false when the curtain is open. That said, I recognize that some entity names (e.g. binarySensorEntities.BedroomClosetDoorSensorContact) are clearer, and I might revisit this decision later.

RepeatWhenEntitiesBecomeAvailable now works with two hardcoded constants (unknown, unavailable) as I didn't want to overengineer the library just for this one method. Eventually I might make these configurable, or even make a .Net Core implementation of the library allowing configuration on the IHostBuilder for example.
Reactive.Booleans implements an alias for the And method called AndOp. This was created to avoid namespace conflicts with the And method in reactive joins.
NetDaemon provides a SubscribeSafe method which prevents exceptions from unsubscribing from the observable. I plan to extend NetDaemon.Extensions.Observables to include this functionality as well.
My personal smart home solution includes many other useful extension methods for working with entities and boolean observables. Although I considered adding them to the libraries, I decided against it for now. The libraries currently align well with the content of this article, and I wanted to avoid cluttering them. In the future, I’ll likely update the libraries and mention these changes here.
For the scheduling extension methods in the Reactive.Booleans library in particular there are some additional methods I can think of and will probably add at some point. For now I included the ones I used in my automations.

Article Updates

10 Feb 2025: Added note explaining that NetDaemon adopted the idea of emitting current state in an observable.