Waypoint Mission Tutorial
1. Overview
Waypoint is an important module of the Mobile SDK. After you establish the waypoints on a map and configure waypoint action parameters and route parameters, the aircraft can fly through the established waypoints and perform preset route actions and waypoint actions.
This tutorial describes all classes and APIs that are involved and provides API call examples.
2. Waypoint flow
3. Key classes and APIs
3.1 Classes involved in a waypoint mission
| Class | Description | Remarks |
|---|---|---|
| AUTELWaypointMissionHandler | Inherits from AUTELMissionHandler. As the protocol manager that handles waypoint missions, it can download, upload, execute, and stop a mission. | |
| AUTELWaypointMission | Inherits from AUTELMission. It is the base class of a waypoint mission. | |
| AUTELGen2WaypointMission | AUTELWaypointMission, | |
| AUTELMCWaypointMission | Inherits from AUTELGen2WaypointMission. It is a waypoint mission class for EVO II V1 and EVO II V2. | |
| AUTELWaypointG2 | Inherits from AUTELWaypoint. It is a waypoint class in a waypoint mission of EVO I. | |
| AUTELWaypointMC | Inherits from AUTELWaypointG2. It is a waypoint class in a waypoint mission of EVO II V1 or EVO II V2. | |
| AUTELMissionProgressStatus | Base class of the current mission execution status class. Report the mission execution status using theonNavigationMissionStatusChanged method. | |
| AUTELWaypointMissionStatus | Inherits from AUTELMissionProgressStatus. It indicates the execution status of the current waypoint mission. |
3.1.1 AUTELMCWaypointMission Class
It is the waypoint mission class for EVO II V1 and EVO II V2. The relevant parameters and methods are described below:
| Parameter | Type | Description | Remarks |
|---|---|---|---|
| missionName | NSString | Mission name | |
| guid | NSString | Unique identifier of the mission | |
| missionType | AUTELMissionType | Mission type. See the enumerated values of AUTELMissionType. AUTELMissionTypeWaypoint : waypoint mission. AUTELMissionTypeRectangle: rectangle. AUTELMissionTypePolygon: polygon. AUTELMissionTypeObliquePhoto: oblique. | |
| altitudeType | int | Altitude type. Values: 0: relative height, 1: altitude. | This parameter is only applied to waypoint missions. |
| lostConnectAction | AUTELMission SignalLostHandleType | Action performed when the aircraft is lost. The default value is AUTELMissionSignalLostHandleTypeNone. If the value is AUTELMissionSignalLostHandleTypeGoHome, the aircraft returns to the Home points. If the value is AUTELMissionSignalLostHandleTypeContinue, the aircraft continues to execute the mission until the battery is insufficient or the mission is completed. | |
| finishMode | AUTELNavigation MissionFinishMode | Mission finish action. The default value is AUTELNavigationMissionFinishModeGoHome. If the value is AUTELNavigationMissionFinishModeGoHome, the aircraft automatically returns to the Home point after completing the mission. If the value is AUTELNavigationMissionFinishModeHover, the aircraft hovers at the current location after completing the mission. | |
| poiList | NSArray<InterestPointModel > | A collection of POIs. An POI can be associated with one or multiple waypoints. However, a waypoint can only be associated with only one POI. For waypoints associated with POIs, the aircraft faces towards the POIs when flying through or hovering at these waypoints. | This parameter is only applied to waypoint missions. |
| totalTimes | int | The total flight time, which is calculated and returned by the route planning algorithm. Currently, the value is set to -1. | This parameter is only applied to waypoint missions. |
| totalDistance | int | The total flight distance, which is calculated and returned by the route planning algorithm. Currently, the value is set to -1. | This parameter is only applied to waypoint missions. |
3.1.2 AUTELWaypointMC class
This is a waypoint class in a waypoint mission of EVO II V1 or EVO II V2 aircraft.
A waypoint mission contains one or multiple waypoints. You can configure the route actions or waypoint actions for each waypoint.
| Parameter | Type | Description | Remarks |
|---|---|---|---|
| coordinate | CLLocationCoordinate2D | Coordinate of a waypoint. | |
| style | AUTELWaypointStyle | Waypoint type. See enumerated values of AUTELWaypointStyle. Currently, only two types of waypoint types are supported: AUTELWaypointStyleNormal: flg over, which means that the aircraft continues to fly after arriving at a preset waypoint; AUTELWaypointStyleHover: hover, which means that the aircraft stops at a preset waypoint and perform the waypoint actions if they are configured. | |
| altitude | float | Altitude, which is relative to the height of the aircraft takeoff point. The value cannot exceed the maximum altitude of the aircraft. | |
| speed | float | Flight speed. | |
| headingMode | AUTELWaypointHeadingMode | Waypoint heading mode. If the value is AUTELWaypointHeadingModeTowardsNext, the aircraft faces towards the next waypoint when arriving at a waypoint. If the value is AUTELWaypointHeadingModeCustom, the aircraft faces towards the direction defined by the user when arriving at a waypoint. If the value is AUTELWaypointHeadingModeFreedom, the heading is random and controlled by the user. It changes according to the pull-and-push operations performed by the user on the command sticks. | |
| userDefinedHeading | float | User-defined nose heading. | |
| poiIndex | int | Associated POI. If no POI is associated, the value -1 is transferred. A waypoint can only be associated with only one POI. | |
| actions | NSArray <AUTELWaypointAction > | Waypoint action list. For details, see the description of the AUTELWaypointAction class. |
3.1.3 AUTELWaypointAction Class
This class describes the waypoint action information. It supports EVO II V1 and EVO II V2 series aircraft.
| Parameter | Type | Description | Remarks |
|---|---|---|---|
| actionId | int | current action ID, which corresponds to the index of the waypoint action list. | |
| actionType | AUTELWaypointActionType | Waypoint action type. For details, see 3.1.5 AUTELWaypointActionType enumeration class. | |
| actionPara | AUTELWaypointActionPara | Waypoint action parameter list. For details, see 3.1.4 AUTELWaypointActionPara class. |
If the waypoint type is fly over, you configure 1 group of waypoint actions or no waypoint actions for this waypoint. The supported action type and the number of parameters are shown below:
| Supported action type | Number of parameters | Description | Remarks |
|---|---|---|---|
| Starts recording | 0 | No parameter | |
| Stops video recording | 0 | No parameter | |
| Photo taking | 0 | No parameter | |
| Periodic | 1 | Period for timed shot (s) | |
| Fixed-distance shooting | 1 | Period for fixed-distance shooting (unit: m) |
If the waypoint type is hover, you can configure multiple groups of waypoint actions or no waypoint action for this waypoint. If the camera action is photo taking, no parameter is required. If the camera action is video recording, a parameter (recording duration) is required. If the camera action is timed shot, two parameters (photo taking period and duration) are required.
| Supported action type | Number of parameters | Description | Remarks |
|---|---|---|---|
| Photo taking | 0 | No parameter | |
| Video recording | 1 | Recording duration (s) | |
| Periodic | 2 | Photo-taking period (s), photo-taking duration (s) |
3.1.4 AUTELWaypointActionPara class
This class describes the waypoint action information. It supports EVO II V1 and EVO II V2 series aircraft.
Waypoint actions are classified into two types: route actions or waypoint actions
| Parameter | Type | Description | Remarks |
|---|---|---|---|
| cameraPitch | float | The gimbal pitch angle. The range is 0 -90 (0 indicates a horizontal level while 90 indicates that the gimbal faces vertically downwards). | |
| cameraYaw | float | The yaw angle of the aircraft. | |
| cameraRoll | float | Roll angle of the gimbal | This parameter is invalid. |
| timeInterval | float | Period for timed shot (s) | |
| timeIntervalTimeDuration | float | The total duration for a timed shot (s). | |
| distanceInterval | float | Period for fixed-distance shooting (unit: m) | |
| recordVideoTimeDuration | float | Recording duration (s) | |
| cameraZoom | float | The zoom level of the camera. The default value is 1. |
3.1.5 AUTELWaypointActionType enumeration class
This class defines the waypoint action type. It is defined below.
/**
* Define Waypoint Action Type
*
*/
typedef NS_ENUM(int, AUTELWaypointActionType) {
/**
* @brief Invalid
*
*/
AUTELWaypointActionTypeInvalid = 0,
/**
* @brief TakePhoto
*
*/
AUTELWaypointActionTypeTakePhoto = 1,
/**
* @brief Start Video Record
*
*/
AUTELWaypointActionTypeStartRecordVideo = 2,
/**
* @brief Stop Video Record
*
*/
AUTELWaypointActionTypeStopRecordVideo = 3,
/**
* @brief TakePhoto Interval
*
*/
AUTELWaypointActionTypeTimeInterval = 11,
/**
* @brief TakePhoto Distance
*
*/
AUTELWaypointActionTypeDistance= 12,
/**
* @brief Unknown
*
*/
AUTELWaypointActionTypeUnknown = 0xff
};
3.1.6 AUTELWaypointMissionStatus class
This class describes the execution status of the current waypoint mission.
| Parameter | Type | Description | Remarks |
|---|---|---|---|
| execState | AUTELWaypointMissionExecuteState | The current status of the waypoint mission. For details, see 3.1.7 AUTELWaypointMissionExecuteState enumeration class | |
| targetWaypointIndex | int | The index of the waypoint towards which the aircraft is flying. | |
| residualTime | float | The remaining flight time for the current waypoint mission. | |
| residualDistance | float | The remaining route distance for the current waypoint mission. | |
| photoCount | float | The number of photos that have already been taken during the current waypoint mission. |
3.1.7 API for reporting the waypoint mission status
/**
* @brief Updates the navigation mission status. If the missionType is of type AUTELNavigationMissionWaypoint
* then the missionStatus will be of class AUTELWaypointMissionStatus.
*
* @param missionStatus Mission status based on the current mission.
*
* @see AUTELWaypointMissionStatus
*/
- (void)onNavigationMissionStatusChanged:(AUTELMissionProgressStatus* _Nonnull)missionStatus;
/**
* @brief The mission status information is pushed in real time during mission flight execution.Specifically refers to mission flight (waypoint flight, rectangular mission, polygonal mission)
*
* @param missionStatus Mission status based on the current mission.
*
* @see AUTELMissionProgressStatus
*/
- (void)onMissionCurrentStatusUpdateNote:(AUTELWaypointMissionStatus* _Nonnull)missionStatus;
4. Implement a waypoint mission
1. Monitor the reporting of the waypoint mission status
Register a listener for monitoring the reporting of the waypoint mission status.
AUTELNavigationDelegateConnection.shared.addProtocol(self)
Monitor the reporting of the waypoint mission status.
func onNavigationMissionStatusChanged(_ missionStatus: AUTELMissionProgressStatus!) {
DispatchQueue.main.async {
}
}
- (void)onMissionCurrentStatusUpdateNote:(AUTELWaypointMissionStatus* _Nonnull)missionStatus {
DispatchQueue.main.async {
}
}
2. Start a mission
Before you start the mission, perform the following steps:
- Configure the mission data model
- Upload the mission data
- Start executing the mission
3.1 Create a waypoint mission
private func creatMissionForMC() -> AUTELMCWaypointMission {
let mission = AUTELMCWaypointMission()
mission.missionId = 5
let finishModeIndex = 0
mission.finishMode = finishModeIndex == 0 ? .goHome : .hover
mission.totalTimes = -1
mission.totalDistance = -1
mission.executeIndex = 0
mission.executePhotos = 0
mission.lostConnectAction = .continue
mission.guid = "0fd18b3fca64b83089d5c9bad4420c94"// An MD5 string, which contains a maximum of 32 characters.
mission.missionName = "Waypoint Mission"
mission.missionType = .waypoint
mission.addGen2Waypoints(setWayPointTypeForHover())
return mission
}
3.2 Configure task data (example 1)
If the waypoint type is fly over, set the yaw angle to 135°, the pitch angle of the gimbal to 45 degree, and the camera action to timed shot.
private func setWayPointTypeForflyOver() -> [AUTELWaypointMC] {
var items = [AUTELWaypointMC]()
typealias dataSetTuple = (curFlyTime: Float, curFlyDistance: Float, waypoint: WayPointModel)
var dataSets = [dataSetTuple]()
WayPointManager.shared.wayPoints.enumerated().forEach { (index, element) in
let dataSetTuple = (Float(19*index), Float(36*index), element)
dataSets.append(dataSetTuple)
}
for i in 0..<dataSets.count {
let mc = AUTELWaypointMC()
mc.coordinate = coordinateAntiCorrectIfNeeded(dataSets[i].waypoint.coordinate)
mc.altitude = dataSets[i].waypoint.height
mc.speed = dataSets[i].waypoint.speed
mc.userDefinedHeading = 0
mc.headingMode = .custom// Sets the yaw angle to a custom value.
mc.poiIndex = -1
mc.curFlyTime = dataSets[i].curFlyTime
mc.curFlyDistance = dataSets[i].curFlyDistance
mc.style = .normal// Sets the waypoint type to “Fly Over”’.
// Camera action example
var actions = [AUTELWaypointAction]()// Creates an action group.
let waypointAction = AUTELWaypointAction()// Configures Action 1.
waypointAction.actionId = 0
waypointAction.actionType = AUTELWaypointActionType.timeInterval// Sets the action type to Timed Shot.
let actioinPara = AUTELWaypointActionPara.init()// Configures action parameters.
actioinPara.cameraPitch = 45// Sets the gimbal pitch angle to a downward angle of 45 degrees.
actioinPara.cameraYaw = 135// Sets the yaw angle of the aircraft to 135°. If you set this to 0°, the aircraft flies due north. If you set this to 90°, the aircraft flies along the route.
actioinPara.cameraZoom = 1// Sets the zoom level to 1.
actioinPara.timeInterval = 2// Sets the time-lapse interval for timed shot to 2 s.
waypointAction.actionPara = actioinPara
actions.append(waypointAction)
mc.actions = actions
items.append(mc)
}
return items
}
3.3 Configure task data (example 2)
If the waypoint type is hover, you can define multiple groups of camera actons, specific the yaw angle, and customize the gimbal pitch angle by referring to the following code:
private func setWayPointTypeForHover() -> [AUTELWaypointMC] {
var items = [AUTELWaypointMC]()
typealias dataSetTuple = (curFlyTime: Float, curFlyDistance: Float, waypoint: WayPointModel)
var dataSets = [dataSetTuple]()
WayPointManager.shared.wayPoints.enumerated().forEach { (index, element) in
let dataSetTuple = (Float(19*index), Float(36*index), element)
dataSets.append(dataSetTuple)
}
for i in 0..<dataSets.count {
let mc = AUTELWaypointMC()
mc.coordinate = coordinateAntiCorrectIfNeeded(dataSets[i].waypoint.coordinate)
mc.altitude = dataSets[i].waypoint.height
mc.speed = dataSets[i].waypoint.speed
mc.userDefinedHeading = 0
mc.headingMode = .custom// Sets the yaw angle to a custom value. This parameter is used together with actioinPara.cameraYaw for defining a yaw angle.
mc.poiIndex = -1
mc.curFlyTime = -1//dataSets[i].curFlyTime
mc.curFlyDistance = -1//dataSets[i].curFlyDistance
mc.style = .hover// Sets the waypoint type to “Hover”, which means that the aircraft will stop at the waypoint and perform waypoint actions once the aircraft arrives at the waypoint.
mc.holdTime = 0
let actioinPara = AUTELWaypointActionPara.init()// Configures parameters for Action 1.
waypointAction.actionId = 0
if i == 0 {// Action parameter for Waypoint 0
waypointAction.actionType = AUTELWaypointActionType.takePhoto// Sets the action type to “Single”.
} else if i == 1 {// Action parameter for Waypoint 1
waypointAction.actionType = AUTELWaypointActionType.timeInterval// Sets the action type to “Single”.
actioinPara.timeIntervalTimeDuration = 20// Sets the time-lapse interval for timed shot to 20 s.
actioinPara.timeInterval = 3// Sets the time-lapse interval for timed shot to 3 s.
actioinPara.cameraPitch = 70// Sets the gimbal pitch angle to a downward angle of 45 degrees.
actioinPara.cameraYaw = 0// Sets the yaw angle of the aircraft to 0°, indicating that the aircraft will fly due north. If you set this to 90°, the aircraft will fly along the route.
} else if i == 2 {// Action parameter for Waypoint 1
actioinPara.timeIntervalTimeDuration = 21// Sets the time-lapse interval for timed shot to 21 s.
actioinPara.timeInterval = 3// Sets the time-lapse interval for timed shot to 3 s.
actioinPara.cameraPitch = 0// Sets the gimbal pitch angle to a downward angle of 0 degree.
} else {
actioinPara.cameraPitch = 90// Sets the gimbal pitch angle to a downward angle of 45 degrees.
actioinPara.cameraYaw = 180// Sets the yaw angle of the aircraft to 180°. If you set this to 0°, the aircraft will fly due north. If you set this to 90°, the aircraft will fly along the route.
}
waypointAction.actionPara = actioinPara
actions.append(waypointAction)
mc.actions = actions
items.append(mc)
}
return items
}
3.4 Upload the task and start to perform the mission
//1. Configure the mission data model
let mission = creatMissionForMC()
//2. Upload the mission data
let handler = DroneConnection.shared.drone?.mainController.navigationManager.waypointMissionHandler
handler?.prepare(mission, withProgress: { (progress) in
print("waypoint:\(progress)\n");
}, withCompletion: { (error) in
if let err = error {
print("prepare waypoint mission error: " + err.localizedDescription);
DispatchQueue.main.async {
completionHandler(error)
}
return
} else {
DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
//3. Start executing the mission
handler?.startMissionExecution(completion: { (error) in
if let err = error {
DispatchQueue.main.async {
print("2. Start the mission error: " + err.localizedDescription);
completionHandler(error)
}
} else {
DispatchQueue.main.async {
completionHandler(nil)
}
}
})
}
}
})
4. Pause the mission
DroneConnection.shared.drone?.mainController.navigationManager.waypointMissionHandler.pauseMissionExecution(completion: { (error) in
if let err = error {
print("pause waypoint error: \(err.localizedDescription)")
DispatchQueue.main.async {
}
} else {
}
})
5. Continue the mission
DroneConnection.shared.drone?.mainController.navigationManager.waypointMissionHandler.resumeMissionExecution(completion: { (error) in
if let err = error {
print("resume waypoint error: \(err.localizedDescription)")
DispatchQueue.main.async {
}
} else {
}
})
6. Stop the mission
When a waypoint mission is being executed, you can call the following method to stop the mission. Based on the input parameter, the aircraft will return to the Home point or hover in the sky after stopping the mission.
DroneConnection.shared.drone?.mainController.navigationManager.waypointMissionHandler.stopMissionExecution(.goHome, withCompletion: { [weak self] (error) in
guard let _ = self else { return }
if let err = error {
DispatchQueue.main.async {
}
print("exit waypoint mission error: \(err.localizedDescription)")
} else {
}
})
This is the end of the tutorial.