Home

Welcome to the documentation of the Node-RED package node-red-contrib-chronos. This package comes with time-based scheduling, repeating, queueing, routing, filtering and manipulating nodes. Times can be expressed as user specified times or calculated based on the sun or moon position. There are predefined sun and moon positions but it is also possible to specify own custom sun positions based on the solar zenith angle.

Nodes

The fundamental design of this package is that each node has a specific, limited scope for which it is responsible and there is as few as possible overlap or combination. So in node-red-contrib-chronos, you won't find this "Swiss army knife node" that is capable of everything, providing all functionality in a single entity. Instead, the guiding principle is to connect multiple nodes together - for instance, a scheduler node and a time filter node - in order to realize a certain use case.

The following nodes are available, please click on the link to get further help.

Configuration Node

Flow Nodes

• Scheduler Node
  Schedules the transmission of messages or setting of global/flow variables at specific times.
  
• State Node
  Maintains a state whose value is changed at specific times under consideration of specific conditions.
  
• Repeat Node
  Repeats each message passing through the node based on a configurable interval.
  
• Delay Node
  Delays each message passing through the node for a configurable amount of time or until a specific point in time is reached.
  
• Time Switch Node
  Routes messages based on a specific time.
  
• Time Filter Node
  Filters messages based on a specific time.
  
• Time Change Node
  Modifies time values in messages or context stores.
  

Common Functions

Functionality which is common to all nodes is explained in the following chapters.

Time Input

Each of the nodes somehow deals with times or time ranges. These times can either be specified in the configuration UI of the nodes or provided by an external input like a input message, environment variable or context variable.

UI Configuration

The times can be specified in different ways depending on what is selected with the button on the left side of the time input fields. When clicking on the button, a popup menu appears and the type of input can be selected.

The provided possibilities are described in more detail in the following table.

Selection	Description
time of day	This input type provides the possibility to directly enter the time in either 12 or 24 hour format with or without seconds.
sun position	The sun position input allows the selection of a solar zenith position from a list of predefined definitions. The time is calculated based on the selected sun position.
moon position	The moon position input is similar to the sun position input but calculates the time based on the selected position of the moon.
custom sun position	This input type allows to specify one of the user-defined sun positions which can be defined in a configuration node. The entered name must match the name of the sun position for either the rising or the setting sun.

The sun positions are described in the following table:

Sun Position	Keyword [1]	Description
Astronomical Dawn	nightEnd	The night ends and the astronomical morning twilight starts.
Nautical Dawn	nauticalDawn	The astronomical morning twilight ends and the nautical morning twilight starts.
Civil Dawn	dawn	The nautical morning twilight ends and the civil morning twilight starts.
Sunrise (start)	sunrise	The civil morning twilight ends and the top edge of the sun appears at the horizon.
Sunrise (end)	sunriseEnd	The bottom edge of the sun touches the horizon and the morning golden hour starts.
Golden Hour (end)	goldenHourEnd	The morning golden hour ends.
Solar Noon	solarNoon	The sun is at its highest position.
Golden Hour (start)	goldenHour	The evening golden hour starts.
Sunset (start)	sunsetStart	The evening golden hour ends and the bottom edge of the sun touches the horizon.
Sunset (end)	sunset	The sun disappears below the horizon and the civil evening twilight starts.
Civil Dusk	dusk	The civil evening twilight ends and the nautical evening twilight starts.
Nautical Dusk	nauticalDusk	The nautical evening twilight ends and the astronomical evening twilight starts.
Astronomical Dusk	night	The astronomical evening twilight ends and the night starts.
Nadir	nadir	The darkest moment in the night when the sun is at its lowest position.

The moon positions are described in the following table:

Sun Position	Keyword [1]	Description
Moonrise	rise	The moon rises.
Moonset	set	The moon sets.

^{_{Illustration based on "Twilight Subcategories" by TWCarlson - Own work, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=21159109}}

External Input

When providing the times via an external input, there is a basic, an extended, a structured and a duration format supported. Which format is supported where depends on the node and the area where the external input is used.

The basic format provides the following possibilities:

Type	Range	Description
Number	0 ≤ n < 86.400.000	Number of milliseconds elapsed since midnight (local time).
Number	n ≥ 86.400.000	Number of milliseconds elapsed since the UNIX epoch (universal time).
String	n/a	Either a local time in 12 or 24 hour format without date, a region-specific [2] local date and time or an ISO 8601 date and time.

Examples

Timestamp as milliseconds since the UNIX epoch (UTC-only):

1712503200000

Timestamp as milliseconds since midnight local time (time-only):

55200000

String containing time only in 12 hour format:

"3:20 pm"

String containing time only in 24 hour format:

"15:20"

String containing region-specific date and time (Germany):

"07.04.2024 15:20"

String containing region-specific date and time (US):

"04/07/2024 3:20 pm"

String containing ISO 8601 format (space-separated):

"2024-04-07 15:20"

String containing ISO 8601 format ('T'-separated):

"2024-04-07T15:20"

String containing ISO 8601 format ('T'-separated, with time zone):

"2024-04-07T15:20+02:00"

The extended format adds further possibilities to the string-based time input. You can additionally provide a sun time, a moon time or a custom sun time, optionally combined with a date. The date can be specified in either regional ^[2] or ISO 8601 format. Predefined sun and moon times have to be specified with their keywords (see section UI Configuration above), custom sun times have to be prefixed with custom: followed by a configured custom sun time rise or set name (see section Custom Sun Positions for more information).

Examples

Sun time without date:

"sunrise"

Sun time with date:

"13.04.2024 sunset"

Moon time without date:

"rise"

Moon time with date:

"04/13/2024 set"

Custom sun time without date:

"custom:blueHourDawn"

Custom sun time with date:

"2024-04-13 custom:blueHourDusk"

For both basic and extended format, if no date is specified explicitly (i.e., either a number of milliseconds since midnight or a string containing a time without a date), a date is automatically applied. Which date exactly depends on the node and could be for instance the date of the current day.

The structured format describes a time without date ^[3] but with an offset definition. This format comes in form of an object containing the following properties:

Property	Type	Description
type	String	The type of time, which can be one of "time", "sun", "moon" or "custom", see also section UI Configuration above.
value	String, Number	The time value, whose content is depending on the type of time. In case of type "time", the value may be provided as 12 or 24 hour time string or as number of milliseconds elapsed since midnight. Predefined sun and moon times have to be specified with their keywords (see section UI Configuration above), custom sun times have to be specified by their configured custom sun time rise or set name (see section Custom Sun Positions for more information).
offset	Number	The offset to the time in minutes, must be between -300 und +300.
random	Boolean	If true, the offset will be randomized between 0 and the given offset value.

Some nodes support additional time types and/or additional properties, these are described on the corresponding pages.

Examples

Sunset minus 15 minutes (randomized):

{
    "type":   "sun",
    "value":  "sunset",
    "offset": -15,
    "random": true
}

Half past ten in the evening:

{
    "type":   "time",
    "value":  "22:30",
    "offset": 0,
    "random": false
}

16:25 (provided as milliseconds elapsed since midnight):

{
    "type":   "time",
    "value":  59100000,
    "offset": 0,
    "random": false
}

Custom sun position "blueHourDawn" plus 20 minutes:

{
    "type":   "custom",
    "value":  "blueHourDawn",
    "offset": 20,
    "random": false
}

The duration format describes a duration/timespan which can be expressed in the following ways:

Type	Description
Number	Number of milliseconds of the duration.
String	Either a timespan string or an ISO 8601 duration string (see below for details).

Timespan strings have the form d.hh:mm:ss.SSS where d is the number of full days, h is the number of full hours, m is the number of full minutes, s is the number of full seconds and S is the number of fractional seconds. ISO 8601 duraton strings have the form PnYnMnDTnHnMnS where n is the amount of time corresponding to the directly following unit identifier. The unit identifiers have the following meaning:

Unit	Description
P	Period - all ISO 8601 duration strings must start with this identifier.
Y	Amount of years.
M	Amount of months.
D	Amount of days.
T	Time - indicates the beginning of the time part.
H	Amount of hours.
M	Amount of minutes.
S	Amount of seconds.

Examples

Duration of 2 days, 7 hours, 25 minutes, 54 seconds and 235 milliseconds as number of milliseconds:

199554235

Duration of 2 days, 7 hours, 25 minutes, 54 seconds and 235 milliseconds as timespan string:

"2.07:25:54.235"

Duration of 2 years, 8 months, 12 days, 4 hours, 21 minutes and 52 seconds as ISO 8601 duration string:

"P2Y8M12DT4H21M52S"

Error Handling

Any error that the user should be aware of is catchable using a catch node. Such errors include if the time for a given sun or moon positions cannot be calculated at the current date and the configured geographical location. This can happen for instance for sun position based times at very northern locations at specific seasons, when the sun is always above or below the horizon. Also if the moon never rises or sets, the moon position based time cannot be calculated. In this case, an error is emitted and when caught by a catch node, details of the error are available through a property with the name errorDetails. If the input message already contains a property called errorDetails, it is renamed to _errorDetails.

The provided error information contains the following properties:

Property	Type	Description
type	String	Time type, can be one of "time", "sun", "moon".
value	String	Depending on the type either the time or the name of the sun/moon position.
alwaysUp	Boolean	true if moon is always above the horizon, false otherwise.
alwaysDown	Boolean	true if moon is always below the horizon, false otherwise.

The properties alwaysUp and alwaysDown are only present if type is equal to "moon". In case of custom sun positions, property type is set to "sun" and value contains the custom sun position name prefixed by "__cust_".

There are also more simple errors emitted in case of invalid user input (e.g., not existing flow variable selected as base time).

---

^[1] The keywords have to be used for external input via environment variables, context variables or message properties (see section External Input for examples) and inside JSONata expressions.

^[2] Region-specific formats are only supported for the regions of the supported UI languages (currently English and German, including all English speaking and German speaking regions). Any other configured locales will fall back to US-English locale.

^[3] Some nodes, like the repeat node, support a date part as additional property.