Forem: Jasper

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.