Scheduling Operations

Motif includes a scheduler which can be used to schedule most major functions in
the UI. This includes

starting and stopping of recording

configuration of camera parameters

turning on/off IO outputs

copying or exporting of data

Scheduling allows executing a certain operation as a defined time. This allows
for example, to schedule recordings and their subsequent copy
to storage to occur at specific times. If your Motif system is configured with
Input/Output/DAQ support, then you can also schedule stimulus
changes.

Scheduled operations are created using the REST API. This
means you need to write a small script which uses the API
to add scheduled tasks. This script can be written in a number of languages,
although Python is shown here. The script can be executed either on your
computer, or by Motif, on the Motif system, using the
experiment scripts feature.

Programming The Scheduler

An identifier
this can be seen in the screenshots above as 'toggle_red' or 'toggle_green'

An expression which tells them when they should runCron expressions are used to
describe scheduled operations. Cron can be confusing - you can test and design
cron expressions online using the following site (note: neither support monotonic expressions)
* https://www.freeformatter.com/cron-expression-generator-quartz.html
* https://cronexpressiondescriptor.azurewebsites.net/

Which API function they should call

Example: Recording Control

Start Recording
To schedule a 30 minute recording as configured above to be executed every-hour-on-the-hour
between 9am and 4pm, make the following API call

Example: Configure Camera

Example: Flash LEDs

Cron Syntax

Each cron trigger is specified with a combination of six (or 7) white-space
separated fields that dictate when the event should occur. In order, the fields
specify trigger times for the second, minute, hour, day of the month,
month, day of the week, and the year (optional)

If the hour, minute, and month of a given time period are valid values as
specified in the trigger and either the day of the month or the day of the
week is a valid value, the trigger fires.

Ranges and Wild-cards

Ranges specify a starting and ending time period. It includes all values from
the starting value to and including the ending value.

Wild-cards ("*") in a field represents all valid values.

The following cron expression is triggered every day at noon from June through
September:

012*6-9**

If the day of the week field is a wild card, but the day of the month is an
explicit range, the day of the week will be ignored and the trigger will only
be activated on the specified days of the month. If the day of the month is a
wild card, the same principal applies.

This expression is triggered every week day at 4:00 PM: 0 16 * * 1-5 *

This one is triggered the first nine days of the month: 0 16 1-9 * * *

This one is triggered every day for the first week, but only on Saturdays
thereafter: 0 16 1-7 * 6 *

Steps

Steps are specified with a "/" and number following a range or wild-card. When
iterating through a range with a step, the specified number of values will be
skipped each time. 1-10/2 is the functional equivalent to 1,3,5,7,9.

The following cron expression is triggered on the first day of every quarter
(Jan., Apr., ... Oct.) at midnight:

001*/2**

Monotonic Triggers

In typical cron implementations, setting the hour field to "*/9" would mean
cause it to match the hours 00:XX, 09:XX and 18:XX. The following day, pattern
would begin again starting from 00:XX making it impossible to easily define an
event that occurs every 9 hours. Monotonic triggers are a solution to
this problem; "%" in any field except the day of the week can be used to denote
expressions that should happen every N-intervals.

Monotonic expressions in the year, month and day field use calendar values. For
example, using "%15" in the day field with an epoch set to January 1st, 2017
would cause the days to match on January 1st, 16th and the 31st regardless of
the time zone.

As per default, monotonic expressions match always with 0, one can also
specify an offset. For example, the expression

Recording Relative Operations

Often one needs to schedule events not in the conventional cron sense - relative
to the date and time of the day, but instead wants to schedule operations relative
to when a recording was started. If a task is scheduled
with camera_relative=True then dates are interpreted differently.
For example the expression