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 calledReactive.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 callingWhenTrueFor
orLimitTrueDuration
directly on an Entity rather than on anIObservable<bool>
, bothLastChanged
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 callToBooleanObservable
(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 theIHostBuilder
for example. -
Reactive.Booleans
implements an alias for theAnd
method calledAndOp
. This was created to avoid namespace conflicts with theAnd
method in reactive joins. - NetDaemon provides a
SubscribeSafe
method which prevents exceptions from unsubscribing from the observable. I plan to extendNetDaemon.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.
Top comments (0)