Skip to content

# SystemController

SystemController is Reactor's own controller to publish memory and CPU usage for the host system to a single entity for access by automations and the dashboard. It also publishes the "Sun Information" entity (capability `suninfo`, canonical ID `reactor_system>sun`); see below.

The `update_interval` value is the time (in milliseconds) between updates to the system data entity. The default is 60000, which is 60 seconds (one minute), and there should be little cause to change it.

The `protect_controller_group` flag (boolean) determines whether the controller's default group exists or not. Since SystemController publishes only one entity, it's a bit of a waste to have it in a group by itself, so by default, SystemController will remove the one-member group. However, there are cases, such as on the dashboard, where having the group can aid navigation and access to the entity. To address this need when it arises, `protect_controller_group` can be set to `true`.

The `report_volumes` key may, optionally, define an array objects describing zero or more storage volumes to be monitored for available space. If not set, Reactor base directory, logs directory, and storage directory will be monitored. Monitored volumes/directories will present as additional attributes in the `reactor_system>system` entity. Each volume will have a `reactor_system.volume_<id>` attribute, where `<id>` is the identifier associated with the volume (explained shortly). Custom configuration of volumes looks like this:

    controllers:
      # other controllers and config redacted for clarity
      - id: reactor_system
        enabled: true
        implementation: SystemController
        name: Reactor System
        config:
          report_volumes:
            - id: root
              path: /
              critical: 10%
            - id: home
              path: /home
              critical: 5%

In the above example configuration, the directories (presumably mount points for volumes) `/` and `/home` are monitored, and assigned IDs `root` and `home` respectively. The `reactor_system.system` entity will have attributes `reactor_system.volume_root` and `reactor_system.volume_home`, the value of each being an array of four elements: the free space of the volume (in KB), the total space of the volume (in KB), the percentage of free space (expressed as fractional 0.0 to 1.0), and the path monitored. In addition, because each of these contains the optional `critical` key and value, additional boolean attributes `reactor_system.volume_critical_root` and `reactor_system.volume_critical_home` will be present and true if the free space of the volume is less than the configured `critical` value (which may be given as a percentage as shown, or a fixed number of KB).

## Alert Information

The alert information on the `reactor_system.system` entity provides triggerable information about system alerts:

- `alert_count` - the number of active alerts; updated whenever the alerts list changes; 0 means there are no active alerts.
- `alert_severity` - the severity of the most severe alert (0=error, 1=warning, 2=notice).
- `alert_last` - the timestamp of the most recent alert; this moves forward in time only, that is, clearing the most recent alert does not reset this value backwards to the timestamp of the then-remaining most recent alert. In effect, it does not change unless there is a new alert, making it easier to detect new alerts in conditions.
- `alerts` - the current list of active alerts (an array of objects), for use in expressions. The published object fields are `id`, `severity` (0-2), `message` (string), `timestamp` (Epoch milliseconds), `level_name` (string), `repeat` (integer). If an alert is repeated (i.e. an alert is generated with the same text and severity as an active prior alert), it is not entered in the array as a new element; the existing element will have its `timestamp` and `repeat` (counter) updated.

There are also actions available to clear all alerts (`reactor_system.clear_alerts`), or just one (by its ID, `reactor_system.clear_alert`).

## Sun Information

SystemController publishes a Sun Information (`reactor_system>sun`) entity that provides information about the current day's sunrise and sunset times, and the current sun position. The following attributes are published in the `suninfo` capability of this entity:

`sunrise, sunset`

  The time of local sunrise and sunset.

`_dawn`, `_dusk`

  The alternate dawn and dusk times, also referred to as twilight hours.

`transit`

  The time of solar noon, where the sun is at its highest point in the sky.

`day_length`

  The length of the current day in hours.

`elevation` and `azimuth`

  The `elevation` and `azimuth` establish the current position of the sun in the sky. The elevation is the angle, in degrees, above the horizon, while the azimuth is the compass angle (from North, clockwise) of the sun. This attribute is updated on the configured interval of the SystemController (default: 60 seconds, see above).

`period`

  A simple string indicating "day" or "night", where "day" is the period where the sun is above the horizon.

DEPRECATION NOTICE: `sun_angle` attribute

The `sun_angle` attribute is a simplified representation of the sun position relative to its daily min and max, but it has turned out to be not very useful, and for users more then a few degrees from the equator, it has nothing to do with reality. It is therefore deprecated and will be removed from a future release. Its replacement is `elevation`.

All times are reported in integer milliseconds since midnight, January 1, 1970 UTC (the Unix Epoch). These are compatible with all date/time functions in expressions.

In the extreme latitudes at particular times of year, the sun does not rise or set. During these periods, all `sunrise/sunset/dawn/dusk` values will be null; `sun_angle` will be null; and `daylength` will be 0 or 24 and `period` will show an unchanging night or day as conditions require. If you live in these latitudes and are creating conditions based on these values, be aware of these special conditions and values and make sure you take them into account in your logic.

Updated: 2026-Jun-22