class DJIMissionControl

@interface DJIMissionControl : NSObject <DJIMissionControlTimelineElementFeedback>

Header:	DJIMissionControl.h
Inherits From:	`NSObject`

Description:

Mission Control handles execution of missions. Either single missions can be run through dedicated mission operators, or a series of missions and actions can be run serially using the Timeline.

Mission operators look after execution of a single mission. A mission operator has APIs to control the mission (e.g. start, stop, pause etc.) and provides mission state through listeners.

Mission Control's Timeline is made up of a series of Timeline elements which can be Waypoint missions, Hotpoint missions (through the Hotpoint action DJIHotpointAction) or objects that follow the DJIMissionControlTimelineElement protocol. DJIMissionAction is a Timeline element, with DJIAircraftYawAction and DJIGimbalAttitudeAction subclasses being examples of specific actions. If a mission is being executed in a Timeline, the mission operator can still be used to get state information of the mission as well as change mission execution parameters.

Timeline elements can also have triggers (DJIMissionTrigger) associated with them. Triggers are separate objects that are run in parallel with a Timeline element. The trigger object is used to initiate actions if a set of criteria are met. For example, a trigger could be used to monitor battery level, and then initiate an action once a threshold is passed. Mission Control's Timeline is only supported by aircrafts. Handheld devices (e.g. OSMO) do not support this feature.

The listening mechanism for Mission Control is block based. To listen to an event, a listener object and a block to execute when the event occurs is passed to Mission Control. The listener object is only used by Mission Control to keep track of whether it should execute the listener block or not. Mission Control would not execute the listener block if the listener object was removed from the listener pool.

Mission Control is accessed from missionControl in DJISDKManager.

Class Members:

Mission Operators

Waypoint Mission

method

waypointMissionOperator

method waypointMissionOperator

- (DJIWaypointMissionOperator *)waypointMissionOperator

Header:

DJIMissionControl.h

Description:

Returns the operator for waypoint missions.

Return:

DJIWaypointMissionOperator *

A Waypoint mission operator object.

Hotpoint Mission

method

hotpointMissionOperator

method hotpointMissionOperator

- (DJIHotpointMissionOperator *)hotpointMissionOperator

Header:

DJIMissionControl.h

Description:

Returns the operator for Hotpoint missions.

Return:

DJIHotpointMissionOperator *

A Hotpoint mission operator object.

Follow Me Mission

method

followMeMissionOperator

method followMeMissionOperator

- (DJIFollowMeMissionOperator *)followMeMissionOperator

Header:

DJIMissionControl.h

Description:

Returns the operator for Follow Me missions.

Return:

DJIFollowMeMissionOperator *

A Follow Me mission operator object.

ActiveTrack Mission

method

activeTrackMissionOperator

method activeTrackMissionOperator

- (DJIActiveTrackMissionOperator *)activeTrackMissionOperator

Header:

DJIMissionControl.h

Description:

Returns the operator for ActiveTrack missions.

Return:

DJIActiveTrackMissionOperator *

An ActiveTrack mission operator object.

Tap Fly Mission

method

tapFlyMissionOperator

method tapFlyMissionOperator

- (DJITapFlyMissionOperator *)tapFlyMissionOperator

Header:

DJIMissionControl.h

Description:

Returns the operator for TapFly missions.

Return:

DJITapFlyMissionOperator *

A TapFly mission operator object.

Panorama Mission

method

panoramaMissionOperator

method panoramaMissionOperator

- (DJIPanoramaMissionOperator *)panoramaMissionOperator

Header:

DJIMissionControl.h

Description:

Returns the operator for Panorama missions.

Return:

DJIPanoramaMissionOperator *

A Panorama mission operator object.

Intelligent Hotpoint Mission

method

intelligentHotpointMissionOperator

method intelligentHotpointMissionOperator

- (DJIIntelligentHotpointMissionOperator *)intelligentHotpointMissionOperator

Header:

DJIMissionControl.h

Description:

Returns the operator for Intelligent Hotpoint missions.

Return:

DJIIntelligentHotpointMissionOperator *

An Intelligent Hotpoint mission operator object.

Timeline

Setup

method

scheduleElement

method scheduleElement

- (NSError * _Nullable)scheduleElement:(id <DJIMissionControlTimelineElement>)element

Header:

DJIMissionControl.h

Description:

Adds an element to the end of the Timeline.

Input Parameters:

id <DJIMissionControlTimelineElement> element A DJIMissionControlTimelineElement element.

Return:

NSError * _Nullable

The first error if one occurred.

method

scheduleElements

method scheduleElements

- (NSError * _Nullable)scheduleElements:(NSArray <id <DJIMissionControlTimelineElement>> *)elements

Header:

DJIMissionControl.h

Description:

Adds an array of elements to the end of the Timeline.

Input Parameters:

NSArray <id <DJIMissionControlTimelineElement>> * elements An array of DJIMissionControlTimelineElement elements.

Return:

NSError * _Nullable

The first error if one occurred. <code>userInfo</code> will hold a dictionary with two keys: @"element" -> holding the elemnt involved in the error and @"index" -> the index in the array for the element.

method

scheduleElement:atIndex

method scheduleElement:atIndex

- (NSError * _Nullable)scheduleElement:(id <DJIMissionControlTimelineElement>)element atIndex:(NSUInteger)index

Header:

DJIMissionControl.h

Description:

Insert an element into the Timeline at an index.

Input Parameters:

id <DJIMissionControlTimelineElement> element	A `DJIMissionControlTimelineElement` element
NSUInteger index	The element index to insert the new element before.

Return:

NSError * _Nullable

The first error if one occurred.

method

unscheduleElement

method unscheduleElement

- (void)unscheduleElement:(id <DJIMissionControlTimelineElement>)element

Header:

DJIMissionControl.h

Description:

Remove element from the Timeline. If the same element was used more than once in the Timeline, then the first one will be removed.

Input Parameters:

id <DJIMissionControlTimelineElement> element A DJIMissionControlTimelineElement element that is already in the Timeline.

method

unscheduleElementAtIndex

method unscheduleElementAtIndex

- (void)unscheduleElementAtIndex:(NSUInteger)index

Header:

DJIMissionControl.h

Description:

Removes the Element at an index in the Timeline.

Input Parameters:

NSUInteger index

Index of element to remove.

method

scheduledElementAtIndex

method scheduledElementAtIndex

- (nullable id)scheduledElementAtIndex:(NSUInteger)index

Header:

DJIMissionControl.h

Description:

Returns the element at a given index in the Timeline.

Input Parameters:

NSUInteger index

An element index in the Timeline.

Return:

nullable id Either a mission, an element or nil if nothing was at the given index.

method

scheduledElementsCount

method scheduledElementsCount

- (NSUInteger)scheduledElementsCount

Header:

DJIMissionControl.h

Description:

Returns the number of elements within the Timeline.

Return:

NSUInteger

Element count.

method

indexOfScheduledElement

method indexOfScheduledElement

- (NSUInteger)indexOfScheduledElement:(id <DJIMissionControlTimelineElement>)element

Header:

DJIMissionControl.h

Description:

Gets the index of an element among the scheduled elements.

Input Parameters:

id <DJIMissionControlTimelineElement> element

The element whose index is to be returned.

Return:

NSUInteger

The index of an element.

method

unscheduleEverything

method unscheduleEverything

- (void)unscheduleEverything

Header:

DJIMissionControl.h

Description:

Clears the Timeline, removing all elements.

Schedule Trigger

method

scheduleTriggers

method scheduleTriggers

- (void)scheduleTriggers:(NSArray <DJIMissionTrigger *> *)triggers

Header:

DJIMissionControl.h

Description:

Adds triggers to be living along the whole timeline.

Input Parameters:

NSArray <DJIMissionTrigger *> * triggers An object of DJIMissionTrigger.

method

unscheduleTriggers

method unscheduleTriggers

- (void)unscheduleTriggers:(NSArray <DJIMissionTrigger *> *)triggers

Header:

DJIMissionControl.h

Description:

Clears all the triggers living along the whole timeline.

Input Parameters:

NSArray <DJIMissionTrigger *> * triggers An object of DJIMissionTrigger.

method

scheduledTriggersCount

method scheduledTriggersCount

- (NSUInteger)scheduledTriggersCount

Header:

DJIMissionControl.h

Description:

Return the triggers' count living along the whole timeline.

Return:

NSUInteger

An NSUInteger value of scheduled Triggers Count.

Control

method

startTimeline

method startTimeline

- (void)startTimeline

Header:

DJIMissionControl.h

Description:

Start Timeline execution from the current element index currentTimelineMarker.

method

pauseTimeline

method pauseTimeline

- (void)pauseTimeline

Header:

DJIMissionControl.h

Description:

Pause execution of the Timeline, and current element (if pausible). If the current element is not pausible then this method will do nothing.

method

resumeTimeline

method resumeTimeline

- (void)resumeTimeline

Header:

DJIMissionControl.h

Description:

Resume element and Timeline execution.

method

stopTimeline

method stopTimeline

- (void)stopTimeline

Header:

DJIMissionControl.h

Description:

Stops the execution of the Timeline, resets the marker index to 0.

State

property

isTimelineRunning

property isTimelineRunning

@property (nonatomic, readonly) BOOL isTimelineRunning

Header:

DJIMissionControl.h

Description:

YES if the Timeline is running.

property

currentTimelineMarker

property currentTimelineMarker

@property (nonatomic) NSUInteger currentTimelineMarker

Header:

DJIMissionControl.h

Description:

The current element index in the Timeline that is being executed. This value can be set only when a Timeline is stopped (not executing or paused).

property

isTimelinePaused

property isTimelinePaused

@property (nonatomic, readonly) BOOL isTimelinePaused

Header:

DJIMissionControl.h

Description:

YES if Timeline is paused.

property

runningElement

property runningElement

@property (readonly, nonatomic, nullable) id <DJIMissionControlTimelineElement> runningElement

Header:

DJIMissionControl.h

Description:

The current element that is running in the Timeline. If the Timeline is not running, then this is nil.

Description:

Adds a listener to all Timeline events.

Input Parameters:

id listener	A listener object.
DJIMissionControlTimelineEventBlock eventBlock	A block to be called for each Timeline event

method

removeListener

method removeListener

- (void)removeListener:(id)listener

Header:

DJIMissionControl.h

Description:

Removes the listener from the Timeline events listeners pool.

Input Parameters:

id listener

A previously added listener object.

method

removeAllListeners

method removeAllListeners

- (void)removeAllListeners

Header:

DJIMissionControl.h

Description:

Removes all listeners from the Timeline events listeners pool.

Timeline Element

protocol

DJIMissionControlTimelineElement

protocol DJIMissionControlTimelineElement

@protocol DJIMissionControlTimelineElement <NSObject>

Header:	DJIMissionControl.h
Inherits From:	`NSObject`

Description:

Required behavior of elements that run in a Timeline.

In addition to implementing this behavior, a Timeline element must communicate with Mission Control to let it know its state. Mission Control will wait for updates from the Timeline element before it itself progresses. Refer to DJIMissionControlTimelineElementFeedback for the methods Mission Control exposes for the Timeline element to use to communicate.

Protocol Methods:

Triggers

method

triggers

method triggers

@optional
- (NSArray <DJIMissionTrigger *> *)triggers

Header:

DJIMissionControl.h

Description:

If implemented, Mission Control loads and activates the triggers for the duration that the Timeline element is executing.

Return:

NSArray <DJIMissionTrigger *> * An array of DJIMissionTrigger object.

Element Can be Paused

method

isPausable

method isPausable

@required
- (BOOL)isPausable

Header:

DJIMissionControl.h

Description:

YES if the element can be paused. If NO, then when the Timeline is asked to pause when this element is running, nothing will happen.

Return:

BOOL	`YES` if the element can be paused.

Validation

method

checkValidity

method checkValidity

@required
- (NSError *_Nullable)checkValidity

Header:

DJIMissionControl.h

Description:

Returns an error if there is a configuration or parameter error in the element. Returns nil if there is no issue.

Return:

NSError *_Nullable

An NSError object.

Control

method

willRun

method willRun

@optional
- (void)willRun

Header:

DJIMissionControl.h

Description:

If Implemented, this is called by Mission Control right before running the element.

method

run

method run

@required
- (void)run

Header:

DJIMissionControl.h

Description:

Starts execution of Timeline element. Missions adopting this behavior are being run with their respective operators.

method

pauseRun

method pauseRun

@optional
- (void)pauseRun

Header:

DJIMissionControl.h

Description:

Pauses the execution of the element. Must be implemented if isPausable returns YES.

method

resumeRun

method resumeRun

@optional
- (void)resumeRun

Header:

DJIMissionControl.h

Description:

Resumes the execution of the element. Must be implemented if isPausable returns YES.

method

stopRun

method stopRun

@required
- (void)stopRun

Header:

DJIMissionControl.h

Description:

Stops execution of the element.

method

didRun

method didRun

@optional
- (void)didRun

Header:

DJIMissionControl.h

Description:

Called after element execution, regardless of whether or not it was successful.

Timeline Event

typedef block

DJIMissionControlTimelineEventBlock

typedef block DJIMissionControlTimelineEventBlock

typedef void (^DJIMissionControlTimelineEventBlock)(DJIMissionControlTimelineEvent event, id <DJIMissionControlTimelineElement> _Nullable element, NSError *_Nullable error, id _Nullable info)

Header:

DJIMissionControl.h

Description:

Block used to process Timeline events.

Input Parameters:

id <DJIMissionControlTimelineElement> _Nullable element	The Timeline element associated with the event, or `nil` if the event is global to the whole Timeline (e.g. start, finish the Timeline).
DJIMissionControlTimelineEvent event	Event.
NSError *_Nullable error	The optional error if the event was error-related.
id _Nullable info	An optional object containing additional information.

enum

DJIMissionControlTimelineEvent

enum DJIMissionControlTimelineEvent

typedef NS_ENUM(NSInteger, DJIMissionControlTimelineEvent)

Header:

DJIMissionControl.h

Description:

Events that can initiate a call to the Mission Control listener.

Enum Members:

DJIMissionControlTimelineEventUnknown	Unknown event type. This is a default value if no other event is matching.
DJIMissionControlTimelineEventStarted	Timeline successfully started.
DJIMissionControlTimelineEventStartError	Timeline failed to start.
DJIMissionControlTimelineEventProgressed	Timeline element progressed.
DJIMissionControlTimelineEventPaused	Timeline successfully paused.
DJIMissionControlTimelineEventPauseError	Timeline failed to be paused.
DJIMissionControlTimelineEventResumed	Timeline successfully resumed.
DJIMissionControlTimelineEventResumeError	Timeline failed to resume.
DJIMissionControlTimelineEventStopped	Timeline Stopped successfully.
DJIMissionControlTimelineEventStopError	Timeline failed to stop and is still continuing in its previous state.
DJIMissionControlTimelineEventFinished	Timeline completed its execution normally.

protocol

DJIMissionControlTimelineElementFeedback

protocol DJIMissionControlTimelineElementFeedback

@protocol DJIMissionControlTimelineElementFeedback <NSObject>

Header:	DJIMissionControl.h
Inherits From:	`NSObject`

Description:

This protocol defines how the timeline element may contact mission control to notify it of its own execution. This protocol is not intended to be implemented by any other object and the use of a protocol is primarily organizational.

Protocol Methods:

Protocol Method

State

method

elementDidStartRunning

method elementDidStartRunning

required
- (void)elementDidStartRunning:(id <DJIMissionControlTimelineElement>)element

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of their successful start.

Input Parameters:

id <DJIMissionControlTimelineElement> element

A previously scheduled element. Should also be the element running.

method

element:failedStartingWithError

method element:failedStartingWithError

required
- (void)element:(id <DJIMissionControlTimelineElement>)element failedStartingWithError:(NSError *)error

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of a failure preventing to start.

Input Parameters:

id <DJIMissionControlTimelineElement> element	A previously scheduled element. Should also be the element running.
NSError * error	A valid error object.

method

element:progressedWithError

method element:progressedWithError

required
- (void)element:(id <DJIMissionControlTimelineElement>)element progressedWithError:(NSError * _Nullable)error

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of a progress in the execution. Additional information may be pulled by mission control depending on the element. Calling this method with an error means the element is still running and the error did not cause it to stop.

Input Parameters:

id <DJIMissionControlTimelineElement> element	A previously scheduled element. Should also be the element running.
NSError * _Nullable error	An optional error if something went wrong.

method

elementDidPause

method elementDidPause

required
- (void)elementDidPause:(id <DJIMissionControlTimelineElement>)element

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of a successful pausing.

Input Parameters:

id <DJIMissionControlTimelineElement> element

A previously scheduled element. Should also be the element running.

method

element:failedPausingWithError

method element:failedPausingWithError

required
- (void)element:(id <DJIMissionControlTimelineElement>)element failedPausingWithError:(NSError *)error

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of a failure to pause. The element is expected to be still running.

Input Parameters:

id <DJIMissionControlTimelineElement> element	A previously scheduled element. Should also be the element running.
NSError * error	A valid error object.

method

elementDidResume

method elementDidResume

required
- (void)elementDidResume:(id <DJIMissionControlTimelineElement>)element

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of a successful resuming of a previously paused element.

Input Parameters:

id <DJIMissionControlTimelineElement> element

A previously scheduled element. Should also be the element running.

method

element:failedResumingWithError

method element:failedResumingWithError

required
- (void)element:(id <DJIMissionControlTimelineElement>)element failedResumingWithError:(NSError *)error

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of a failure to resume. The element is expected to be still paused.

Input Parameters:

id <DJIMissionControlTimelineElement> element	A previously scheduled element. Should also be the element running.
NSError * error	A valid error object.

method

element:didFinishRunningWithError

method element:didFinishRunningWithError

required
- (void)element:(id <DJIMissionControlTimelineElement>)element didFinishRunningWithError:(NSError * _Nullable)error

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of the end of the execution of it.

Input Parameters:

id <DJIMissionControlTimelineElement> element	A previously scheduled element. Should also be the element running.
NSError * _Nullable error	An optional error if the execution end was the result of it.

method

elementDidStopRunning

method elementDidStopRunning

required
- (void)elementDidStopRunning:(id <DJIMissionControlTimelineElement>)element

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of their successful manual stop.

Input Parameters:

id <DJIMissionControlTimelineElement> element

A previously scheduled element. Should also be the element running.

method

element:failedStoppingWithError

method element:failedStoppingWithError

required
- (void)element:(id <DJIMissionControlTimelineElement>)element failedStoppingWithError:(NSError *)error

Header:

DJIMissionControl.h

Description:

Used by elements to notify Mission Control of a failure to stop the execution of the element. This should only be used to handle error after stopRun is called.

Input Parameters:

id <DJIMissionControlTimelineElement> element	A previously scheduled element. Should also be the element running.
NSError * error	A valid error object.

Error

const

DJIMissionControlErrorDomain

const DJIMissionControlErrorDomain

extern const NSErrorDomain DJIMissionControlErrorDomain

Header:

DJIMissionControl.h

Description:

The domain associated with errors specific to Mission Control.

enum

DJIMissionControlError

enum DJIMissionControlError

typedef NS_ENUM(NSInteger, DJIMissionControlError)

Header:

DJIMissionControl.h

Description:

Defines all MissionControl related errors.

Enum Members:

DJIMissionControlErrorUnknown	Default placeholder when no other code matches.
DJIMissionControlTimelineErrorCannotPauseUnpausableElement	Can't pause an element which is not pausbile.
DJIMissionControlTimelineErrorCannotScheduleWhileRunning	Tried to schedule new element while the Timeline was running.
DJIMissionControlTimelineStartErrorAlreadyAtEnd	Can't start a timeline whose marker is already at the end.
DJIMissionControlTimelineStartErrorAlreadyRunning	Can't start a timeline which was already running.
DJIMissionControlTimelineStartErrorTimelineIsPaused	Can't start a paused timeline. Need to call resume instead.
DJIMissionControlTimelinePauseErrorNotRunning	Can't pause a timeline which is not running.
DJIMissionControlTimelinePauseErrorAlreadyPaused	Can't pause a timeline which is already paused.
DJIMissionControlTimelineResumeErrorNotRunning	Can't resume a timeline which is not running.
DJIMissionControlTimelineResumeErrorNotPaused	Can't resume a timeline which is not paused.
DJIMissionControlTimelineErrorCannotResumeUnpausableElement	Can't resume an element which is not pausbile.
DJIMissionControlTimelineStopErrorNotRunning	Can't stop a timeline which is not running.
DJIMissionControlElementErrorProtocolNotConform	Element passed does not conform to DJIMissionControlTimelineElement protocol
DJIMissionControlElementErrorInvalidMissionOperator	The element passed is a mission without a valid operator.
DJIMissionControlElementErrorInvalidPauseImplementation	IsPausable was set to yes but the item doesn't implement pauseRun and/or resumeRun methods.
DJIMissionControlTimelineTriggerErrorActionNotImplemented	Timeline trigger does not have an action implemented.