Scheduler

The Scheduler component provides the capability to run particular actions onboard your robot periodically according to a predefined schedule. These jobs will run even while the robot is operating offline.

Note

The Scheduler component needs Agent version 1.7+

Configuration

To use the Scheduler component, your agent will need a section in its agent-settings.json file which enables the scheduler component, as shown below. For more information on how to configure the agent components, see Agent Configuration.

...
"components": [
...
{
    "enabled": true,
    "id": "scheduler",
    "settings": {
        "logLevel": 6,
        "jobs": [
            {
                "enabled": true,
                "name": "job1",
                "schedule": "0 8-18 * * MON-FRI",
                "skippable": true,
                "type": "service",
                "uri": "/rocos/agent/test"
            }
        ]
    }
},
...
]

From the example settings shown above, you can see that the Scheduler component can be configured using various parameters, please see the table below for a description of each field as well as other fields that are not shown that provide extended capabilities.


Name	Description	Default
`enabled`	Whether to enable the scheduler component.	`false`
`id`	The identifier for the component. Must be set to the default value.	`"scheduler"`
`name`	How this instance of the scheduler component should be named. It will default to the same value as the `id` field but can be changed if needed.	`"scheduler"`
`logLevel`	The logging verbosity: 1 - very quiet, 6 - very talkative.	`4`
`jobs`	A list of jobs to run.	`nil`

The jobs configuration field in the main settings above can contain a list of jobs that can each run on their own defined schedule. To see what configuration options are available for each job, please see the tables below.

General Job Configuration Fields


Name	Description	Default
`enabled`	Whether to enable this job.	`false`
`name`	The name to assign to this job to make it easily distinguishable.
`schedule`	Specifies when the associated job should run. Please see the section below on how to define the schedule specification.
`skippable`	Whether this job can be skipped if a previous invocation is still running.	`true`
`type`	The type of this job. The type can be one of `"service"`, `"command"`, or `"control"`.
`uri`	The URI for the service, command, or control to call with any specified data. Please see the type specific configuration options below for what data can be defined for each job type.

Service Job Configuration Fields

The fields defined below are specific to jobs with their type set to service.


Name	Description	Default
`request`	A JSON dictionary appropriate for the URI that will be called.	`{}`
`meta`	Any additional meta data to be sent along with the request data.	`{}`

Command Job Configuration Fields

The fields defined below are specific to jobs with their type set to command.


Name	Description	Default
`params`	A JSON dictionary appropriate for the URI that will be called.	`{}`

Control Job Configuration Fields

The fields defined below are specific to jobs with their type set to control.


Name	Description	Default
payload	A JSON dictionary appropriate for the URI that will be called.	`{}`

Published Data

The scheduler component will periodically publish data to various topics that can be subscribed to. The following topics will have data published to them every 60 seconds.

/scheduler/<jobName>/nextTime
- The data published to this topic is an integer that represents the next time the specified job will run in nanoseconds.
/scheduler/<jobName>/prevTime
- The data published to this topic is an integer that represents the last time the specified job ran in nanoseconds.
/scheduler/<jobName>/prevStatus
- The data published to this topic is a boolean that represents the result status of the last invocation of the specified job.

The following topic is only published when a job runs.

/scheduler/<jobName>/status
- The data published to this topic is a boolean that represents the result status of the most recent invocation of the specified job.

Schedule Specification

The schedule field that is required for each job is using a syntax known as the cron specification.

The format of this field requires 5 sub-fields to be defined each separated by a space character as shown below.

MINUTE HOUR DAY-OF-MONTH MONTH DAY-OF-WEEK

Each field has various options that can be used to define its value.


Field	Allowed Values	Special Characters
Minute	0-59	`* - , /`
Hour	0-23	`* - , /`
Day of Month	1-31	`* - , /`
Month	1-12	`* - , /`
Day of Week	0-6	`* - , /`

The special character column defines various special characters that can be used when defining a sub-field of the cron specification.

The star * character when specified for a particular sub-field means that the job will run for each allowed value of that sub-field. For example if you use the * character in the minute sub-field, the job will run every minute according to the other sub-fields. Essentially this is just a shorthand for using the range operator with the start value set to the first allowed value and the end value set to the last allowed value.
The hyphen - character is used to define a range of values. For example, to run a job between the hours of 8am and 5pm, a range can be defined in the hour field as follows 8-17. An important note is that a range is inclusive of both end points. This means that the job will run (using the example in this paragraph) at every hour starting from 8am through to and including 5pm.
The comma , character is used to define a list of values. For example, to run a job at the start midnight and midday, the following specification can be used for the hour field 0,12.
The forward slash / character is used to define what stepping to use for a range. The normal stepping when not defined is to step by 1 through the values of a sub-field. For example, to define a job to run every 2 hours starting at 8am and finishing at 5pm, we can define the hour sub-field as 8-17/2. Please note that if you run a job with this sub-field definition you will see that the last time the job runs is at 4pm since 9 hours (8-17) does not divide evenly into 2 hour blocks.

The Month field can also be defined using shorthand names for each month.


- JAN (1) - FEB (2) - MAR (3)	- APR (4) - MAY (5) - JUN (6)	- JUL (7) - AUG (8) - SEP (9)	- OCT (10) - NOV (11) - DEC (12)

Similarly, the Day-of-Week field can also be specified using shorthand names.


- SUN (0) - MON (1)	- TUE (2) - WED (3)	- THU (4) - FRI (5)	- SAT (6)

Along with the standard format specification as outlined above, there are some non-standard formats that are also supported, these are shown below.


Entry	Description	Equivalent To
`@yearly, @annually`	Runs once a year at midnight on 1 January.	`0 0 1 1 *`
`@monthly`	Runs once a month at midnight on the first day of the month.	`0 0 1 * *`
`@weekly`	Runs once a week at midnight on Sunday morning.	`0 0 * * 0`
`@daily, @midnight`	Runs once a day at midnight.	`0 0 * * *`
`@hourly`	Runs once an hour at the beginning of the hour.	`0 * * * *`
`@every <duration>`	Runs once per duration. The duration is defined according to the following specification: https://pkg.go.dev/time#ParseDuration.

Time Zone Handling

By default all jobs will run using local time zone on the machine. This can be changed for each job by prepending the following to the schedule specification.

CRON_TZ=America/New_York 0 0 * * *

Using the example above would mean that the job will run each day at midnight in the time zone for New York, America.

For a full list of time zone names, please see the IANA time zone database. One such list can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

More Information

You can find more information about the cron specification at the links below.

Configuration​

General Job Configuration Fields​

Service Job Configuration Fields​

Command Job Configuration Fields​

Control Job Configuration Fields​

Published Data​

Schedule Specification​

Time Zone Handling​

More Information​