Payload SDK

Waypoint Mission

2024-08-23
No Rating
Github Edit open in new window

Overview

DJI PSDK provides a motion planning function to meet users' needs for controlling drone flight automation. Developers can use the motion planning function to design corresponding waypoint tasks and hotspot tasks according to actual use requirements, and formulate control logic of control drone automation.

Waypoint missions

Waypoint planning is a control function that controls the drone to fly according to the specified route and realizes the flight automation of the drone. By calling the interface of DJI PSDK, the developer can control the drone to fly to the designated position at the designated altitude and perform the corresponding actions, and can also control the drone to repeat many times according to the actual use requirements. Perform specified tasks to achieve functions such as automatic cruise.

Waypoints

When using the waypoint task, the developer needs to specify the number of waypoints and the corresponding waypoint type.

  • Number of waypoints

    When using waypoint tasks, developers need to use the API interface in the PSDK to specify the waypoints that the drone needs to fly to. DJI PSDK supports developers to add up to 65535 waypoints in a task, with at least 2 waypoints.

  • Waypoint type

    The waypoint type refers to the way that the drone flies to the waypoint when performing the waypoint mission, including curvature flight, straight flight and coordinated turn.

    • Curvature flight
      • When the drone performs the flight mission in a continuous curvature, it will not stop when it reaches the designated waypoint.
      • When the drone performs a flight mission in a continuous curvature, it stops at the waypoint.
      • When the drone performs a flight mission with a discontinuous curvature, it stops at the waypoint.
    • Straight flight
      • Straight entry
      • Straight out
    • Coordinated turn: the drone turns ahead of time before reaching the waypoint

Action

When developers use waypoint tasks, developers or users can add corresponding actions to the drone at the designated waypoints, such as taking pictures, recording videos, or hovering.

  • Action information

    The action information mainly consists of the action ID, the trigger that triggers the action, and the executor that executes the action.

    • Action ID, the developer can specify a globally unique action ID to identify the action set by the user.
    • Trigger: The trigger that triggers the action of the drone, including the type of the trigger and the parameters corresponding to the trigger type. Only one trigger type is supported per trigger.
    • Actuator: The module that executes the user-specified action, including the type of the actuator, the number of the actuator, and the parameters corresponding to the actuator. Only one execution type is supported per executor

  • Number of actions

    DJI PSDK supports developers to add a total of 65535 actions in a task.

  • Action management:

    • Support to configure the action of camera focus and zoom to the ground station for automatic execution.
    • Support gimbal angle increment control
    • Support to configure multiple gimbal and multiple cameras

  • Action trigger

    To trigger the drone to perform a specified action during the waypoint mission performed by the drone, you need to add the conditions for triggering the action:

    • Timing trigger
    • Distance trigger
    • Action serial trigger
    • Actions are triggered in parallel
    • Waypoint trigger: When the drone is flying at the waypoint, it will end the waypoint mission at the Nth waypoint

speed control

PSDK provides developers with a speed control function, which enables developers to configure different speeds for specified waypoints (set multiple speeds for the same waypoint), and supports developers to modify or Query the global cruising speed of the drone.

Disconnection Control

Added support for configuring the function of continuing to perform flight missions after the remote controller is disconnected.

Note:

  • When the application developed based on PSDK controls the drone to perform tasks, the user can use the remote control to control the drone such as the drone's flight speed, flight altitude and flight direction.
  • The drone can only perform one automated flight mission at a time. After uploading a new mission, the existing mission will be overwritten.
  • In the waypoint mission, the waypoint of the drone is not necessarily related to the action of the drone. The developer can add the waypoint and the action of the drone according to the actual situation.

work process

The waypoint task function controls the drone to perform the waypoint task according to the following process:

  1. Upload the overall information of the route mission A waypoint task includes the ID of the waypoint task, the number of waypoints in the waypoint task, the number of task repetitions, the action after the waypoint task ends, the maximum flight speed and the cruise speed.
  2. Upload waypoint information
  • Basic parameters: waypoint coordinates (set the waypoint's longitude, latitude and altitude relative to the take-off point), waypoint type, heading type and flight speed.
  • Optional parameters: buffer distance, heading angle, steering mode, point of interest, single point maximum flight speed, single point cruise speed.

Note: Only after the developer has set all the basic parameters of the waypoint information, can the optional parameters of the waypoint information be set.

  1. Set the action information (optional) Set the ID, trigger and executor of the action
  2. Upload the information of the waypoint mission of the drone
  3. Control the drone to perform the waypoint mission After uploading the drone waypoint and the corresponding action information, the developer can control the waypoint task through the specified interface, such as starting, stopping or pausing the task, setting or obtaining the cruise speed, etc.

Using Waypoint Missions - Waypoint 2.0 Features

Note: Waypoint 2.0 function currently only supports Matrice 300 RTK and Matrice 350 RTK models

The Waypoint 2.0 function provides functions such as uploading route tasks, obtaining and setting cruise speed, monitoring route status and controlling route execution actions.

1. Waypoint mission initialization

Initialize the information of the waypoint task, and send the overall information of the waypoint task and the waypoint information to the drone flight controller. The overall information of the waypoint task includes the cruise speed of the drone, disconnection control and waypoint information, etc.; Waypoint information includes waypoint altitude, waypoint latitude and longitude, etc.

returnCode = DjiTest_WaypointV2Init();
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("Init waypoint V2 sample failed, error code: 0x%08X", returnCode);
USER_LOG_INFO("Waypoint V2 sample end");
return returnCode;
}

USER_LOG_INFO("--> Step 2: Subscribe gps fused data");
DjiTest_WidgetLogAppend("--> Step 2: Subscribe gps fused data");
returnCode = DjiFcSubscription_SubscribeTopic(DJI_FC_SUBSCRIPTION_TOPIC_POSITION_FUSED,
DJI_DATA_SUBSCRIPTION_TOPIC_50_HZ, NULL);
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("Subscribe gps fused data failed, error code: 0x%08X", returnCode);
goto out;
}

USER_LOG_INFO("--> Step 3: Register waypoint V2 event and state callback\r\n");
DjiTest_WidgetLogAppend("--> Step 3: Register waypoint V2 event and state callback\r\n");
returnCode = DjiWaypointV2_RegisterMissionEventCallback(DjiTest_WaypointV2EventCallback);
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("Register waypoint V2 event failed, error code: 0x%08X", returnCode);
goto out;
}
returnCode = DjiWaypointV2_RegisterMissionStateCallback(DjiTest_WaypointV2StateCallback);
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("Register waypoint V2 state failed, error code: 0x%08X", returnCode);
goto out;
}
osalHandler->TaskSleepMs(timeOutMs);

2. Upload waypoint mission

  • Upload waypoint missions
T_DjiReturnCode returnCode;
uint16_t polygonNum = missionNum - 2;
dji_f32_t radius = 6;
uint16_t actionNum = 5;
T_DjiWayPointV2MissionSettings missionInitSettings = {0};
T_DJIWaypointV2ActionList actionList = {NULL, 0};

/*!Generate actions*/
actionList.actions = DjiTest_WaypointV2GenerateWaypointV2Actions(actionNum);
actionList.actionNum = actionNum;

/*!Init waypoint settings*/
missionInitSettings.missionID = s_missionID + 10;
USER_LOG_DEBUG("Generate mission id:%d", missionInitSettings.missionID);
missionInitSettings.repeatTimes = 1;
missionInitSettings.finishedAction = DJI_WAYPOINT_V2_FINISHED_GO_HOME;
missionInitSettings.maxFlightSpeed = 10;
missionInitSettings.autoFlightSpeed = 2;
missionInitSettings.actionWhenRcLost = DJI_WAYPOINT_V2_MISSION_KEEP_EXECUTE_WAYPOINT_V2;
missionInitSettings.gotoFirstWaypointMode = DJI_WAYPOINT_V2_MISSION_GO_TO_FIRST_WAYPOINT_MODE_POINT_TO_POINT;
missionInitSettings.mission = DjiTest_WaypointV2GeneratePolygonWaypointV2(radius, polygonNum);
missionInitSettings.missTotalLen = missionNum;
missionInitSettings.actionList = actionList;

returnCode = DjiWaypointV2_UploadMission(&missionInitSettings);

if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("Init waypoint V2 mission setting failed, ErrorCode:0x%lX", returnCode);
return returnCode;
}

3. Control the drone to perform the waypoint mission

  • Start the waypoint mission Before the drone starts to perform the waypoint mission, it will first check the mission information uploaded by the user. If the check fails, the drone will not be able to perform the waypoint mission. For details, please check the error code information.
T_DjiReturnCode DjiWaypointV2_Start(void);
  • Pause the waypoint mission Control the drone to suspend the waypoint mission.
T_DjiReturnCode DjiWaypointV2_Pause(void);
  • Resume the waypoint mission Control the drone from the paused position to continue the waypoint mission as completed.
T_DjiReturnCode DjiWaypointV2_Resume(void);
  • Stop executing waypoint missions Control the drone to stop the waypoint mission.
T_DjiReturnCode DjiWaypointV2_Stop(void);

4. Set the cruise speed of the drone

Set or get the cruising speed of the drone when performing a waypoint mission.

  • Set cruise speed
T_DjiReturnCode DjiWaypointV2_SetGlobalCruiseSpeed(T_DjiWaypointV2GlobalCruiseSpeed cruiseSpeed);
  • Get cruising speed
T_DjiReturnCode DjiWaypointV2_GetGlobalCruiseSpeed(T_DjiWaypointV2GlobalCruiseSpeed *cruiseSpeed);

Using Waypoint Missions - Waypoint 3.0 Features

Note: Waypoint 3.0 function currently only supports Matrice 30 Series, Mavic 3 Enterprise Series, and Matrice 3D/3TD models. Do not support Matrice 300 RTK and Matrice 350 RTK.

The Waypoint 3.0 function provides functions such as uploading route tasks, monitoring route status, and controlling route execution actions. Compared with Waypoint 2.0, it can directly import KMZ files in standard format, with better versatility and compatibility. Please refer to KMZ format: WPMLopen in new window.

1. Waypoint mission initialization

Before using the route task-Waypoint 3.0 function, you need to call the interface DjiWaypointV3_Init for initialization.

returnCode = DjiWaypointV3_Init();
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("Waypoint v3 init failed.");
return returnCode;
}

2. Upload waypoint mission

Compared with the complicated route configuration of Waypoint 2.0, the KMZ file of Waypoint 3.0 is simpler and easier to use. Users can directly transfer the KMZ file data by calling DjiWaypointV3_UploadKmzFile to perform flight tasks. The KMZ file can be exported in advance by planning the route in DJI Pilot.

T_DjiReturnCode DjiWaypointV3_UploadKmzFile(const uint8_t *data, uint32_t dataLen);

3. Control the drone to perform the waypoint mission

After the upload of the route is completed, you can call DjiWaypointV3_Action to execute the route task, including start, stop, pause and resume the route task.

T_DjiReturnCode DjiWaypointV3_Action(E_DjiWaypointV3Action action);

4. Monitor route status

Before the user starts to execute the route task, it is recommended to register the route status callback interface. During the route execution process, the route status information can be received in real time through the registered callback function to ensure flight safety.

returnCode = DjiWaypointV3_RegMissionStateCallback(DjiTest_WaypointV3StateCallback);
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("Register waypoint v3 state callback failed.");
goto out;
}

static T_DjiReturnCode DjiTest_WaypointV3StateCallback(T_DjiWaypointV3MissionState missionState)
{
USER_LOG_INFO("Waypoint v3 mission state: %d", missionState.state);

return DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS;
}
How was your reading experience of our documentation?
If you have any comments or confusion about our documentation, you can click here to give feedback and we will get back to you as soon as possible.