Automation Registry

V10.0.1

There are two ways of creating automations. You can either use the IAutomationRegistry interface or write individual automations. This page covers the former. See Automation Types for documentation on writing individual automations.

Use the IAutomationRegistry when you want to reuse automations for multiple places in your home or quickly create simple automations using either builder or the factory.

See here for an example of setting up a registry.

IAutomationRegistry

The IAutomationRegistry has one method, which accepts a single parameter of type IRegistrar

public interface IAutomationRegistry
{
    void Register(IRegistrar reg);
}

At startup, the framework will look for all implementations and call the Register method exactly once. Only one implementation is required, but you could have multiple if you want to structure your code by area or other strategy. By injecting an IAutomationFactory and/or an IAutomationBuilder into your registry, you can create automations as described below.

Alternatively, you can write your own IAutomation, IConditionalAutomation, or IDelayableAutomation implementations and construct them in your registry. See Tutorial for more information on creating automations from scratch.

IRegistrar

The registrar has several methods for registering your automations with overloads for registering single or multiple automations.

public interface IRegistrar
{
    void Register(params IAutomation[] automations);
    void RegisterDelayed(params IDelayableAutomation[] automations);
    bool TryRegister(params IAutomationBase[] automations);
    bool TryRegister(params Func<IAutomationBase>[] activators);
}

See Automation Types for an in depth description of each. 

Note: It is a best practice to use the bool TryRegister(params Func<IAutomationBase>[] activators) method. During startup, each of the Func will be called one by one. If any throw an exception, instead of raising the exception immediately, the error will be added to an initialization error collection and report them if there are any. This way, an exception being thrown by one automation does not cause other automations to not be registered.

All automations created with either the factory or the builder can be registered with these methods.

IAutomationFactory interface

The IAutomationFactory, has 3 methods for constructing automations based on the 3 main types of automations. It also has a methods for creating prebuilt automations for controlling lights based on motion sensors, and several for sun based automations.

public interface IAutomationFactory
{
    IHaServices Services { get; }

    SimpleAutomation SimpleAutomation(
        IEnumerable<string> triggerEntities,
        Func<HaEntityStateChange, CancellationToken, Task> execute,
        EventTiming eventTimings = EventTiming.PostStartup);

    ConditionalAutomation ConditionalAutomation(
        IEnumerable<string> triggerEntities,
        Func<HaEntityStateChange, CancellationToken, Task<bool>> continuesToBeTrue,
        TimeSpan @for,
        Func<CancellationToken, Task> execute);

    SchedulableAutomation CreateScheduled(
        IEnumerable<string> triggerIds, 
        GetNextEventFromEntityState getNextEvent,
        Func<CancellationToken, Task> execution,
        bool shouldExecutePastEvents = false,
        bool shouldExecuteOnError = false,
        EventTiming timngs = EventTiming.PostStartup
    );

    ConditionalAutomation EntityAutoOff(string entity_id, TimeSpan timeToLeaveOn);
    ConditionalAutomation EntityAutoOff(string entity_id, int minutes);
    LightOnMotionAutomation LightOnMotion(string motionId, string lightId);
    LightOnMotionAutomation LightOnMotion(IEnumerable<string> motionId, IEnumerable<string> lightId);
    LightOffOnNoMotion LightOffOnNoMotion(string motionId, string lightId, TimeSpan duration);
    LightOffOnNoMotion LightOffOnNoMotion(IEnumerable<string> motionIds, IEnumerable<string> lightIds, TimeSpan duration);
    SunDawnAutomation SunDawnAutomation(Func<CancellationToken, Task> execution, TimeSpan? offset = null, EventTiming timings = SunAutomation.DEFAULT_SUN_EVENT_TIMINGS, bool executePast = true);
    SunRiseAutomation SunRiseAutomation(Func<CancellationToken, Task> execution, TimeSpan? offset = null, EventTiming timings = SunAutomation.DEFAULT_SUN_EVENT_TIMINGS, bool executePast = true);
    SunNoonAutomation SunNoonAutomation(Func<CancellationToken, Task> execution, TimeSpan? offset = null, EventTiming timings = SunAutomation.DEFAULT_SUN_EVENT_TIMINGS, bool executePast = true);
    SunDuskAutomation SunDuskAutomation(Func<CancellationToken, Task> execution, TimeSpan? offset = null, EventTiming timings = SunAutomation.DEFAULT_SUN_EVENT_TIMINGS, bool executePast = true);
    SunSetAutomation SunSetAutomation(Func<CancellationToken, Task> execution, TimeSpan? offset = null, EventTiming timings = SunAutomation.DEFAULT_SUN_EVENT_TIMINGS, bool executePast = true);
    SunMidnightAutomation SunMidnightAutomation(Func<CancellationToken, Task> execution, TimeSpan? offset = null, EventTiming timings = SunAutomation.DEFAULT_SUN_EVENT_TIMINGS, bool executePast = true);
}

You can also write extension methods of the Automation Factory and call them in your registry. The interface includes a reference to IHaServices for your convenience.

IAutomationBuilder interface

See Automation Builder for details.