Skip to content

astro-timer

Description

The astro-timer block is used to determine whether the current moment falls within the interval defined by two astronomical events. The block does not require any inputs and operates based on the device's location and time settings.

To calculate astronomical events, the block uses the location and time zone configured in the system calendar. If this data is incorrect, the sunrise, sunset, civil dawn, and civil dusk times will also be calculated incorrectly.

The start and end of the active period are defined independently. For both points, one of four astronomical events can be selected:

  • sunrise - sunrise
  • sunset - sunset
  • daylight - civil dawn
  • twilight - civil dusk

For each of these events, an additional offset in minutes can be configured. A positive value shifts the moment later, while a negative value shifts it earlier.

The block automatically determines whether the active period falls within a single day or crosses midnight. If, after applying the offsets, the start time is later than the end time, the active period covers the evening and night and ends on the next day.

The start moment is included in the active period, while the end moment is not. In practice, the state changes a few seconds after the calculated astronomical event time.

The description visible below the block shows the current state and the local time of the next change, for example active until 06:12:05 or inactive until 19:48:05.

Configuration parameters

Parameter name Value
Start event (startEvent) Required value. It defines the event that starts the active period. The allowed values are sunrise, sunset, daylight, and twilight.
Start event offset (startEventOffset) Required value. An integer number of minutes in the range from -720 to 720. A negative value means a time earlier than the selected event, while a positive value means a later time.
End event (endEvent) Required value. It defines the event that ends the active period. The allowed values are sunrise, sunset, daylight, and twilight.
End event offset (endEventOffset) Required value. An integer number of minutes in the range from -720 to 720. A negative value means a time earlier than the selected event, while a positive value means a later time.

The start event and end event cannot point to exactly the same moment. An error occurs when the same astronomical event and the same offset are selected for both parameters.

Input handling

The astro-timer block has no inputs and does not react to signals from other blocks.

Block outputs

Output number and name Output description
1. Activity output. Returns the value true when the current time falls within the configured active period. Outside this period, it returns false.
2. Inactivity output. Returns the opposite value of output no. 1, that is true when the block is outside the active period, and false when the block is active.

Both outputs are of the logical type and change simultaneously when the block state changes. If the block cannot determine a valid operating state, both outputs are set to null.

Errors visible to the user

The block can display the following error messages:

Error code Error description
Invalid start event configuration. The startEvent parameter has an invalid value. One of the supported events must be selected: sunrise, sunset, daylight, or twilight.
Invalid start event offset configuration. The startEventOffset parameter has an invalid value. An integer number of minutes in the range from -720 to 720 must be provided.
Invalid end event configuration. The endEvent parameter has an invalid value. One of the supported events must be selected: sunrise, sunset, daylight, or twilight.
Invalid end event offset configuration. The endEventOffset parameter has an invalid value. An integer number of minutes in the range from -720 to 720 must be provided.
Start time equals end time. The start time and end time point to exactly the same moment. For the block to work correctly, the event or offset of one of these parameters must be changed.
Astro timer error. The block cannot determine valid astronomical event times or the next state change. This can happen, for example, when there is a problem with the device time or location settings, or during periods of polar day or polar night.

Examples

  • For startEvent = daylight, startEventOffset = 0, endEvent = twilight, and endEventOffset = 0, output no. 1 is active from civil dawn to civil dusk.
  • For startEvent = sunset, startEventOffset = -30, endEvent = sunrise, and endEventOffset = 15, output no. 1 is active from 30 minutes before sunset until 15 minutes after sunrise on the next day.
  • For startEvent = sunrise, startEventOffset = 0, endEvent = sunrise, and endEventOffset = 0, the block reports the Start time equals end time. error.