Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History
API supported by platform agents for mission execution.
(Under construction)

1. Introduction

The main target audience is developers that need to interface with the PA for mission execution. The first part is mainly to provide some context and thus is focused on the end-user perspective. Then the actual API (commands, events) is explained.

2. Mission Files

This section details the format and functionality of the mission files.

2.1. General structure

The mission file is used to give users the flexibility to design a mission to command/control any of the platform’s associated children instruments. Mission files are ASCII text files following the YAML format.  

Key Features:

  • 2 basic mission modes: scheduler based and event driven
  • User defined error handling for each command
  • Ability to define pre- and post-mission commands
  • Control multiple instruments simultaneously or sequentially

2.2. Mission execution modes

2.2.1. Scheduler based

These missions are to be carried out at regularly scheduled intervals as defined by the loop parameters.

Requirements:

In the schedule section the following keys must be filled out:
      startTime
      timeZone
      loop
            quantity
            value
            units

2.2.2. Event driven

These missions are to be carried out only when the scheduler based fields are empty and the mission executive receives the event defined in eventID from the device defined in parentID.

Requirements:

In the schedule section the following keys must be filled out:
      event
            parentID
            eventID

2.3. Mission File Contents

name

Select a name for the mission file.

version

Mission file version number. Do not change this value.

description

User can detail a brief description of the mission.

platform

No value.

      platformID [platform]

      Device ID of the platform.

mission

The mission section contains a list of all instrument missions that are to be carried out.

-missionThread

Define “sub missions” in the missionThread list.

instrumentID [Instrument1, Instrument2, etc]

List of 1 or more device IDs used in the mission. Be sure to enclose in brackets if specifying more than 1 instrument.

errorHandling

Start of error handling subsection

      default [retry|abort|abortMission|skip]

      Default error handling procedure for missionSequence commands.

      retry: Resend the erroneous command up to maxRetries times. Waits 5 seconds before resending commands.

      abort: Abort mission thread on error

      abortMission: Abort entire mission on error

      skip: Ignore error

      maxRetries [1-inf]

      Maximum number of times to retry a command before aborting mission thread.

schedule

Start of schedule subsection to specify how a mission commences

startTime [yyyy-mm-ddTHH:MM:SS]

Specify a date and time (ISO 8601) for the mission to start. If the start time has already elapsed a new start time is determined using the loop parameters. Used for scheduler based mission only. Leave blank for event driven missions.

timeZone

Specify the time zone that the startTime is referenced in. Time zones are listed here and are from pytz.all_timezones. If left blank, UTC is used.

loop

Start of loop subsection.  Used for scheduler based missions only.

      quantity [int]

      Specify the number of times to perform missionSequence. For infinite loops, set to -1

      value [int]

      Used in conjunction with units to specify the amount of time between loops.

      units [secs|mins|hrs|days]

      Unit of time for loop interval.

event

Start of event subsection. Used for event driven missions only.

      parentID [instrumentID]

      Specify the ID of the parent instrument whose events need to be monitored. 

      eventID [eventID]

      Specify which parentID event to monitor. The missionSequence begins when this event is captured.

preMissionSequence

Start of the pre mission sequence block. Commands listed in this block will be executed immediately after the platform receives the mission. This block is optional.

      -command [instrumentID, method(command{parameters})]

      [Optional] Specify the post mission sequence commands.

      For example: SBE37_SIM_02, execute_resource(START_AUTOSAMPLE).

      onError [retry|abort|abortMission|skip]

      [Optional] Define the error handling for each command. If retry is selected, mission will abort after maxRetries. If none is specified, default error handling is used.

missionSequence

Start of the mission sequence block. Commands listed in this block will be executed according to the mission schedule or event.

      -command [instrumentID, method(command{parameters})]

      [Optional] Specify the post mission sequence commands.

      For example: SBE37_SIM_02, execute_resource(START_AUTOSAMPLE).

      onError [retry|abort|abortMission|skip]

      [Optional] Define the error handling for each command. If retry is selected, mission will abort after maxRetries. If none is specified, default error handling is used.

postMissionSequence

Start of the post mission sequence block. Commands listed in this block will be executed at the conclusion of the mission. This block is optional.

      -command [instrumentID, method(command{parameters})]

      [Optional] Specify the post mission sequence commands.

      For example: SBE37_SIM_02, execute_resource(START_AUTOSAMPLE).

      onError [retry|abort|abortMission|skip]

      [Optional] Define the error handling for each command. If retry is selected, mission will abort after maxRetries. If none is specified, default error handling is used.

2.4. Error handling

There are many ways to handle an error that occurs when issuing a missionSequence command. As mentioned in section 2.3. Mission File Contents, there are 4 error handling options to choose from in the mission file: retry, abort, abortMission, and skip.

retry: Resend the erroneous command up to maxRetries times. Waits 5 seconds before resending commands. Mission thread will abort after maxRetries.

abort: Abort mission thread on error

abortMission: Abort entire mission on error

skip: Ignore error

When a mission thread aborts, each instrument defined in that mission thread will be placed into the INACTIVE state.

When an entire mission aborts, each instrument in each mission thread will be placed in the INACTIVE state and a "mission aborted" event will be published

**NOTE** When a mission thread is aborted, the mission execution stops where it is. The postMissionSequence is NOT carried out.  

2.5. Mission thread coordination

At the moment, it is the responsibility of the operator constructing the mission file to handle mission thread coordination. There are some very basic checks to make sure the same instrument isn't scheduled to sample at the same time in two different mission threads but it is assumed that the mission file will properly manage the instrument agent state between threads.

A safe practice is to use a separate mission thread for each instrument. This also allows the user to  

2.6. Example Missions

The following example missions use the RSN platform node simulator with the SBE37_SIM_## CTD simulator instruments.

Sample scheduled mission to sample CTD
Event driven mission
Mission with multiple threads
Example HDCamera mission (based on API found here)
Example mission using Shallow Water Profiler events

3. Platform Agent mission executive

This section explains the platform agent API for mission execution.

3.1. Mission states and commands

The following are the platform agent states and commands associated with mission execution and termination:

In PlatformAgentState PlatformAgentEvent(s) accepted
COMMAND RUN_MISSION
STREAMING RUN_MISSION
MISSION_COMMAND RUN_MISSION
ABORT_MISSION
MISSION_STREAMING RUN_MISSION
ABORT_MISSION

The arguments and action performed by these commands are as follows: (see section below for more details about the various events published by the mission executive)

RUN_MISSION(mission_id, mission_yaml):

Starts the execution of the given plan, where the arguments are the mission ID and the YAML string of the mission plan itself. A "mission start" event is immediately published. Then, once all associated mission threads are started, a "mission started" event is published. Upon normal or abnormal completion of the mission execution, a corresponding event is published (eg., "mission ended"), and, if no other mission plans are executing, the platform agent's FSM automatically returns to the state where the mission was started (COMMAND or STREAMING). Other relevant events are published as explained below.

FSM effect: Whenever a mission execution is in progress, the FSM will be in the MISSION_COMMAND or MISSION_STREAMING state if the initial state prior to the first RUN_MISSION command was COMMAND or STREAMING respectively. Note in particular that multiple mission plan can be running concurrently.

ABORT_MISSION(mission_id):

Terminates the execution of the mission by the given ID by immediately stopping its main mission sequence and then putting each associated instrument into the INACTIVE state. A "mission abort" event is immediately published prior to the termination, and a "mission aborted" event is published once the abort sequence is completed.

FSM effect: If there are no remaining missions executing, then the FSM returns to the state prior to the first RUN_MISSION command.

3.2. Platform/Instrument agent coordination

3.2.1 Exclusive access

Prior to the execution of a given mission plan, the parent platform requests exclusive access to the instrument agents involved in the plan. This exclusive access is provided by the CIAD COI OV Org Management Service. Once the execution of the mission plan completes (normally or abnormally), such exclusive access is released.

3.2.2 Agent states

The execution of mission plans may be transitioning a platform agent's instruments through various states without the parent platform being directly involved. So, for those platform commands that involve corresponding processing in its child instruments, the parent platform needs to check the state of each child instrument before determining that the command needs to be issued against it. For more details, see Instrument command dispatch from platform agent.

3.3. Events published by mission executive

There is a base class DeviceMissionEvent for mission related events, and a subclass MissionLifecycleEvent for events associated with the progression of mission execution.

ion-definitions event.yml

TODO make the mission events a subclass of ResourceAgentEvent:
  • "we should put mission events as a child of Agent Events because origin should be the platform agent resource_id"
  • "subclass of the current event hierarchy…resource agent event hierarchy…that way if someone subscribes to a platforms events, they'll get these too"
Brief event name Brief event description Object published(*)  (description field described in next column) description field
"mission start" mission is about to start execution MissionLifecycleEvent(sub_type="STARTING", execution_status=OK)  
"mission started" mission has started MissionLifecycleEvent(sub_type="STARTED", execution_status=OK)  
"mission abort" mission abort sequence has started MissionLifecycleEvent(sub_type="STOPPING", execution_status=ABORTED)  
"mission aborted" mission has been aborted MissionLifecycleEvent(sub_type="STOPPED", execution_status=ABORTED)  
"mission ended" mission has exited normally MissionLifecycleEvent(sub_type="STOPPED", execution_status=OK)  
"mission failed" mission has exited due to some exception MissionLifecycleEvent(sub_type="STOPPED", execution_status=FAILED) Includes a brief description of the problem
"thread started" thread has started MissionLifecycleEvent(mission_thread_id=Y, sub_type="STARTED", execution_status=OK)  
"thread ended" thread has exited normally MissionLifecycleEvent(mission_thread_id=Y, sub_type="STOPPED", execution_status=OK)  
"thread failed" thread has exited due to some exception MissionLifecycleEvent(mission_thread_id=Y, sub_type="STOPPED", execution_status=FAILED) Includes a brief description of the problem
"missionSequence started" missionSequence has started 
MissionLifecycleEvent(mission_thread_id=Y, sub_type="STARTED", execution_status=OK) For scheduler based missions: "MissionSequence starting..." 
For event driven mission: "Event <event_name> received! MissionSequence starting..."
"missionSequence ended" missionSequence has exited normally  

MissionLifecycleEvent(mission_thread_id=Y, sub_type="STOPPED", execution_status=OK) For scheduler based missions: "MissionSequence loop n of num_loops complete. Next start at yyyy-mm-dd HH:MM:SS"
For event driven missions: "MissionSequence complete. Waiting for <event_name>"

(*) For brevity, some common attributes included but not shown in the table are:

  • origin: resource ID of platform agent.
  • origin_type: "PlatformDevice".
  • mission_id: resource ID of mission plan.

As corresponding sequences may take significant time to complete, the STARTING and STOPPING events ("mission start", "mission abort") will allow interested parties to take some immediate action, for example to update a UI.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.