yearly-timer
Description
The yearly-timer block is used to create a yearly time schedule. It operates according to the device's local time configured in the main system calendar, and its input can enable or disable the schedule.
The block defines one active yearly interval: a start date and time, and an end date and time. The block is active when the current local time falls within this interval and the calendar is enabled.
The yearly interval may cross New Year. For example, an interval from 01.12 10:00 to 15.01 15:00 is active from December 1 10:00:00, through the end of the year, until January 15 15:00:59.
The final minute of the interval is included in the active period, and the state changes after that minute ends. February 29 cannot be configured as the start or end date. If the real year is a leap year, February 29 is handled as a normal day between February 28 and March 1.
The default configuration covers the whole year: from 01.01 00:00 to 31.12 23:59.
The block has an associated vlogic device available in the mobile application. The mobile application can enable or disable the calendar, edit the yearly interval, and show the current work status. A change to the enabled state made in the mobile application is not persistent: it remains in effect until the next valid change from the input or the application, or until the project is reloaded. This device is not available from the web application.
Configuration parameters
| Parameter name | Value |
|---|---|
Name (name) |
Optional name visible in the mobile application. |
Settings version (json_settings_version) |
Configuration version number used when synchronizing settings with the mobile application. |
Start month (startMonth) |
Start month of the interval, from 1 to 12. |
Start day (startDay) |
Start day of the month. The date must exist in a non-leap year. |
Start time (startHour) |
Start time in the HH:MM format, from 00:00 to 23:59. |
End month (endMonth) |
End month of the interval, from 1 to 12. |
End day (endDay) |
End day of the month. The date must exist in a non-leap year. |
End time (endHour) |
End time in the HH:MM format, from 00:00 to 23:59. |
The start moment and end moment must be different. Configuring the same start date and time as the end date and time causes a configuration error.
Input handling
The yearly-timer block has one input that controls the schedule's current enabled state.
If the input is not connected, the schedule starts enabled when the project starts. If at least one source is connected to the input, the schedule starts disabled. A valid initial value sent by a source can immediately change this state. If the connected sources do not send any value, the schedule remains disabled.
The input accepts only strict Boolean values: true enables the schedule and false disables it. Numeric values, text, null, and the set and reset commands sent from the command block are ignored. Sending a value equal to the current state again has no effect.
Multiple sources can be connected to the input. The block does not combine their states — the last valid Boolean value received takes effect. A change made in the mobile application follows the same rule, so the last valid change from the input or the application determines the current state. After the project is reloaded, the state is determined again only by whether the input is connected.
Block outputs
| Output number and name | Output description |
|---|---|
1. praca |
Returns true when the current local time falls within the configured yearly interval and the calendar is enabled. Otherwise it returns false. |
2. przerwa |
Returns the opposite value of output no. 1. |
3. czy kalendarz jest włączony |
Returns the schedule's current effective enabled state. |
When the calendar is disabled, the praca output returns false, the przerwa output returns true, and the czy kalendarz jest włączony output returns false.
Errors visible to the user
The block can display the following error messages:
| Error code | Error description |
|---|---|
Missing json_settings_version configuration. |
The settings version number is missing. |
Invalid json_settings_version configuration. |
The settings version number has an invalid value. |
Invalid start date configuration. |
The start date is invalid, for example because it contains a non-existent day of the month or February 29. |
Invalid start time configuration. |
The start time is invalid. It must use the HH:MM format, from 00:00 to 23:59. |
Invalid end date configuration. |
The end date is invalid, for example because it contains a non-existent day of the month or February 29. |
Invalid end time configuration. |
The end time is invalid. It must use the HH:MM format, from 00:00 to 23:59. |
Start date and time equals end date and time. |
The start moment and end moment are identical. |
Examples
- The interval
01.04 08:30-30.09 17:45activates thepracaoutput from April 108:30:00until September 3017:45:59. - The interval
01.12 10:00-15.01 15:00crosses New Year and activates thepracaoutput from December 110:00:00until January 1515:00:59. - The interval
01.01 00:00-31.12 23:59keepspraca = truefor the whole year, including the real February 29 in a leap year. - With no input connection, the schedule starts enabled.
- When the input is connected, the schedule starts disabled and remains disabled if the source sends no value.
- The true value enables the schedule, and false disables it.
- A numeric value, text,
null, and thesetandresetcommands do not change the schedule state. - If two sources send true and then false, the last value takes effect, so the schedule remains disabled.
- A change made in the mobile application remains in effect until the next valid change from the input or the application, or until the project is reloaded.
- When the schedule is disabled,
praca = falseandprzerwa = trueregardless of the configured yearly interval.