ActuatorScheduleRequest

Requesting Schedule Changes

For information on responses see AcutatorAgent responses to a schedule or cancel requests.

For 2.0 Agents using the pubsub interface: The actuator agent expects all messages to be JSON and will parse them accordingly. Use publish_json to send messages where possible.

3.0 agents using pubsub for scheduling and setting point values should publish python objects like normal.

Scheduling a Task

An agent can request a task schedule by publishing to the "devices/actuators/schedule/request" topic with the following header:

#python
{
    'type': 'NEW_SCHEDULE',
    'requesterID': <Agent ID>, #The name of the requesting agent.
    'taskID': <unique task ID>, #The desired task ID for this task. It must be unique among all other scheduled tasks.
    'priority': <task priority>, #The desired task priority, must be 'HIGH', 'LOW', or 'LOW_PREEMPT'
}

with the following message:

#python
[
    ["campus/building/device1", #First time slot.
     "2013-12-06 16:00:00",     #Start of time slot.
     "2013-12-06 16:20:00"],    #End of time slot.
    ["campus/building/device1", #Second time slot.
     "2013-12-06 18:00:00",     #Start of time slot.
     "2013-12-06 18:20:00"],    #End of time slot.
    ["campus/building/device2", #Third time slot.
     "2013-12-06 16:00:00",     #Start of time slot.
     "2013-12-06 16:20:00"],    #End of time slot.
    #etc...
]

Points on Task Scheduling

• Everything in the header is required.
• Task id and requester id (agentid) should be a non empty value of type string
• A Task schedule must have at least one time slot.
• The start and end times are parsed with dateutil's date/time parser. The default string representation of a python datetime object will parse without issue.
• Two Tasks are considered conflicted if at least one time slot on a device from one task overlaps the time slot of the other on the same device.
• The end time of one time slot can be the same as the start time of another time slot for the same device. This will not be considered a conflict. For example, time_slot1(device0, time1, time2) and time_slot2(device0,time2, time3) are not considered a conflict
• A request must not conflict with itself.
• If something goes wrong see this failure string list for an explanation of the error.

Task Priorities

HIGH::  This Task cannot be preempted under any circumstance. This task may preempt other conflicting preemptable Tasks.

LOW::  This Task cannot be preempted once it has started. A Task is considered started once the earliest time slot on any device has been reached. This Task may not preempt other Tasks.

LOW_PREEMPT:: This Task may be preempted at any time. If the Task is preempted once it has begun running any current time slots will be given a grace period (configurable in the ActuatorAgent configuration file, defaults to 60 seconds) before being revoked. This Task may not preempt other Tasks.

Canceling a Task

A task may be canceled by publishing to the "devices/actuators/schedule/request" topic with the following header:

#python
{
    'type': 'CANCEL_SCHEDULE',
    'requesterID': <Agent ID>, #The name of the requesting agent.
    'taskID': <unique task ID>, #The desired task ID for this task. It must be unique among all other scheduled tasks.
}

Points on Task Canceling

• The requesterID and taskID must match the original values from the original request header.
• After a Tasks time has passed there is no need to cancel it. Doing so will result in a "TASK_ID_DOES_NOT_EXIST" error.
• If something goes wrong see this failure string list for an explanation of the error.