ScheduleController

ScheduleController is a simple controller that publishes, through an entity, a current active schedule period given a series of starting times. It operates similarly to thermostat schedules, where you typically have morning, day, evening, and night periods for which you can set starting times. The changing value on the entity can be used in rules to trigger scenes or other activities at specific times.

While one can use the Date/Time and other conditions in rules to achieve this effect, ScheduleController makes some logic simpler. The simple example above, with four phases or modes per day, would be fairly easy to implement without ScheduleController. However, having multiple schedules interacting, with expections for day of the week and other conditions, could quickly raise complexity to the point that writing proper-functioning rules and debugging those that don't could be daunting.

Installation

To install ScheduleController:

1. Create an ext directory for extensions if you do not already have one:

   • If you are using Reactor build 24097 or higher, create the ext directory inside your config directory.

   • Otherwise:

     Bare-metal installs: create the ext directory in your Reactor install directory (where the server directory is).

     Docker users: create the ext directory in your Reactor data directory (where the storage directory is).

2. Go into your ext directory and create a subdirectory`

3. Copy the contents of the release package (all files) into the new ScheduleController folder you just created.

4. Configure ScheduleController and restart Reactor. See below.

Configuring ScheduleController

Like most controllers, the basic preamble necessary to make Reactor aware of the controller and start it looks like this (in the contollers section of your config/reactor.yaml file:

controllers:  # don't add this line; it's shown just for guidance/indenting reference
  - id: scheduler
    name: Scheduler
    enabled: true
    implementation: ScheduleController

From there, as with most other controllers, you will add a config section that contains the configuration for the extension.

ScheduleController requires only one configuration element: entities. In this element, you will give entity IDs for the entities to be created that represent your schedules. The example below shows a sample configuration with two schedules, one for weekdays, and one for weekends.

    config:
      entities:
        weekdays:
          name: Weekday Schedule
          schedule:
            '07:00': morning
            'sunrise + 2 hours': day
            'sunset - 60 minutes': evening
            '22:30': night
        weekends:
          name: weekend Schedule
          schedule:
            '09:00': morning
            '10:30': day
            'sunset-00:30': evening
            '0:00": night

The weekdays and weekends strings will be the entity IDs of the entities created to represent the two schedules. Within these sections, a schedule element defines the periods of the schedule. Each element of schedule is a key/value pair called an edge, where the key (left of the ":") is a time specification, and the right side is a string value to be assigned to the string_sensor.value attribute at that time. In the weekday schedule above, the period starting at 7am local time will be called morning, and that string will be assigned to the string_sensor.value attribute of the entity. At two hours after sunrise, the attribute will change to day; at one hour before sunset, it will change to evening; and at 10:30pm it will change to night. The weekend schedule has similar timing.

Note that a value for the period between midnight and 7am isn't specified. ScheduleController treats the schedule as cyclical over a day, so it will automatically assume that the period from midnight to 7am is night, because the latest edge is 10:30pm — the entity will show night from 10:30pm to 7am the next day.

Time specifications can be of the following forms:

• HH:MM — Hour-minute, 24-hour time;
• HH:MM:SS — Hour-minute-second, 24-hour time;
• sunrise [offset] — Local sunrise time with optional offset;
• sunset [offset] — local sunset time with optional offset.

For edges using the sunrise and sunset time specifications, an optional offset may follow. If specified, the offset must be a + or - followed by HH:MM form, HH:MM:SS form, or an integer and units (such as the + 2 hours and - 60 minutes shown). For the integer and units form, whitespace is not significant, so +2hours would also work. The unit words hours, minutes and seconds may be used, and may be abbreviated to hrs, mins, secs respectively (the respective singulars hr, min, sec are also acceptable). Compounding is also allowed: + 1 hour 30 minutes. The offset forms -1hr30mins and -01:30 are equivalent.

Time specifications do not need to be listed in order; ScheduleController will sort them out. However, you may wish to keep them in order just for your own ease of readability.

Cautions for Sunrise/Sunset

• Because sunrise/sunset times vary daily, make sure your use plus offsets works for all times of year. For example, where I live, sunrise occurs at about 6:27am in June, and 7:41am in January, so my example sunrise + 2 hours would be 8:27am in summer and 9:41am in winter. If I had an edge to trigger at 09:00, that edge would trigger after sunrise in summer but before sunrise in winter, potentially leading to confusing state changes in the attribute value.

• The sunrise/sunset function requires use of the sun entity on the SystemController. The canonical ID of this entity is expected to be reactor_system>sun, which would be correct in default installations of Reactor based on the template configuration files. If you have changed the SystemController controller ID, the entity will have a different canonical ID, and you need to tell ScheduleController what it is by specifying sun_entity: in your config section with the new canonical ID. To find and check your system, you can use the Entities page and filter to the suninfo capability to find your SystemController's sun entity.

• Make sure your lat/long configuration is correct in your reactor.yaml file.

Updated 2024-Apr-06