X-Port Function

2024-08-23
No Rating

Note:

Overview

DJI X-Port standard gimbal is a hardware platform for developing payload devices. Users can use X-Port to quickly develop payload devices with gimbal functions; combined with custom widgetopen in new window function, using DJI Pilot and apps developed based on MSDK can also display the controls designed by the developer, which is convenient for users to control the use of X-Port standard gimbal and PSDK through the controls developed load device.

basic functions

X-Port Status Information

The payload developed based on PSDK can obtain information such as the mode of the X-Port, the current attitude of the X-Port and the calibration result. Please refer to PSDK API documentationopen in new window for details on how the payload device obtains the X-Port status.

  • Basic information: X-Port mode
  • X-Port status: rotation status, control status, reset status, limit angle
  • Key parameter: speed conversion factor

X-Port Control

Description: X-Port standard gimbal integrates the basic functions of gimbal . For details, please refer to Gimbal Functionopen in new window.

X-Port Control Mode

  • Relative angle control: X-Port rotates by the specified angle within the specified time according to the specified angle by the user.

    After X-Port receives the rotation control command, it first calculates the intermediate amount of the pan axis rotating to the target angle according to the control mode and control method, and then calculates the target angle of the final pan axis, X-Port will Rotate the X-Port pan axis according to the final pan axis target angle.

    • The rotation direction of the pan axis is independent of the rotation angle sign.
    • Intermediate amount (X) when the pan axis is rotated to the target angle = the current angle of the pan axis + the rotation angle of the pan axis
    • final pan axistarget angle=MOD((X + 180), 360) - 180
  • Absolute angle control: X-Port rotates from the current position to the specified position within the specified time according to the user's instructions.

  • Speed control: The actual movement speed of X-Port is limited by the maximum speed.

Note:

  • In the angle control mode, the rotation range of the X-Port pan axis is [-180,180], and the actual movement time of the X-Port is limited by the maximum acceleration and maximum speed of the X-Port movement.
  • The roll axis of the X-Port is used to eliminate the drone jitter, and the payload device developed with PSDK cannot control the roll axis of the X-Port.
  • X-Port Actual reachable position is limited by X-Port limit.

X-Port Control Permissions

See Table 1. X-Prot Control Privileges for a detailed description of X-Port Control Privileges.

  • Permission rules:

    • The control action with low priority can only control the X-Port after the control action with high priority is finished.
    • High-priority control actions can preempt control of low-priority control actions.
    • Control scenes with the same priority will preempt control according to the chronological order of starting control, and control scenes with a later start time cannot seize control.
  • Permission release

    • Release the control right after the load device developed with PSDK finishes controlling the X-Port.
    • If the load device developed by PSDK does not release the control right after completing the control of the X-Port, the X-Port will automatically release the control right within 2s after the rotation ends.

Table 1. X-Port Control Permissions

Permission rolesPrivilege Level
Use the remote control gimbal joystick to control the X-Port1
Control X-Port angle through MSDK interface1
Controlling the X-Port via DJI Pilot2
Controlling X-Port through load coordination function2
Control X-Port speed through MSDK interface2
Controlling the X-Port by flight route2
Controlling the angle of X-Port via PSDK2
Controlling speed of X-Port via PSDK2

Speed conversion factor

When the zoom factor of the camera-loaded device is large, if the X-Port rotates quickly, the picture recorded by the camera-loaded device will become blurred, which will affect the image recording effect and viewing experience. Therefore, PSDK provides "speed" "Conversion factor" function, by setting the conversion factor between the control command and the rotation speed, when the zoom factor of the load device is large, the user can recognize the stable picture and get the excellent recording effect and viewing experience. *Factor: User can set the speed conversion factor of X-Port according to actual needs, recommended to set the speed conversion factor to the reciprocal of the zoom factor.

  • Max_speed (Maximum speed of X-Port) = Default Max Speed × Max Speed Percent
  • Actual motion speed of X-Port = Max_speed * Factor, Factor≤ 1

Note: X-Port only supports users to use DJI Pilot and PSDK to set the speed conversion factor of X-Port.

X-Port reset

  • Pan axis reset: Reset the angle of the X-Port pan axis to the sum of the drone pan axis angle and the X-Port pan axis fine-tuning angle.
  • Pitch axis and pan axis reset: reset the X-Port pitch axis angle to the fine-tuning angle, reset the X-Port pan axis angle to the sum of the drone pan axis angle and the X-Port pan axis fine-tuning angle.
  • Reset X-Port's yaw and pitch axes: Reset the angle of the X-Port's yaw axis to the sum of the drone's yaw axis and the X-Port's trim angle. Reset the X-Port pitch axis to the sum of -90° and the X-Port trim angle (X-Port down), 90° and the X-Port trim angle (X-Port up).
  • Reset the yaw axis of the X-Port to the sum of -90° and the X-Port trim angle (X-Port down), and 90° and the X-Port trim angle ( X-Port up).

X-Port Limit

Limit angle

In order to avoid accidental damage to the drone due to structural problems hitting the parts on the drone or interfere with the drone's flight mission when the X-Port is working, be sure to set a limit for the X-Port. For details on the limit type and limit angle Please refer to Table 2. X-Port limit angle for the adjustment range.

Table 2. X-Port Limit Angle

limit angle typeDefault upper limitMaximum adjustable rangeDefault lower limitLower limit adjustable range
Pitch axis joint angle40°40° ~ 0-125°-125° ~ 0
Roll axis joint angle55°55° ~ 0-55°-55° ~ 0
Pan axis joint angle320°320° ~ 0-320°-320° ~ 0
Euler angle of pitch axis30°30° ~ 0-90°-90° ~ 0
Extended pitch axis Euler angles30°30° ~ 0-120°-120° ~ 0
Eulerian Angles for Roll Axis20°Not adjustable-20°Not adjustable

After setting the limit angle of the X-Port, the X-Port will rotate within the limit range. If the rotation angle of the X-Port exceeds the limit range of the limit angle, the X-Port will automatically adjust the attitude, which will cause the X-Port to rotate. Slight jitter, in order to reduce the jitter of X-Port, X-Port has set a limit buffer.

Note: Except that the range of "Eulerian Angle of Roll Axis" cannot be modified, the range of other types of limit angles can be adjusted according to actual use needs.

limit buffer

In order to reduce the jitter when adjusting the attitude of the X-Port that exceeds the limit angle, limit buffers have been set for the X-Port's pitch, roll and pan axes; when the X-Port enters the limit buffer, The X-Port will stop in the limit buffer.

Note:

  • When the X-Port is in the limit buffer, it will no longer be able to move towards the limit.
  • The limit buffer width of the X-Port pitch and roll axes is 5°, and the limit buffer width of the pan axis is 15°.

example

  • If the upper limit of the joint angle of the pan axis is 90° and the width of the limit buffer is 15°, the limit buffer is 75° ~ 90°;
  • When the X-Port pan axis angle is 30° and the angle control command controls the X-Port pan axis angle to reach 78°, the X-Port will stop somewhere within the limit buffer, such as 80°;
  • At this time, the X-Port's pan axis will not be able to move to a direction greater than 80°.

X-Port (bottom/top) Euler angle motion range description
  • Under X-Port:
    • When the pitch axis angle range extension is not enabled, the motion range of the pitch axis Euler angle is [pitchEulerAngleLowerLimit, pitchEulerAngleUpperLimit]
    • When the angle range extension of the pitch axis is enabled, the motion range of the Euler angle of the pitch axis is [pitchEulerAngleExtensionLowerLimit, pitchEulerAngleExtensionUpperLimit]
  • Top of X-Port:
    • When the pitch axis angle range extension is not enabled, the motion range of the pitch axis Euler angle is [-pitchEulerAngleUpperLimit, -pitchEulerAngleLowerLimit]
    • When the angle range extension of the pitch axis is enabled, the motion range of the Euler angle of the pitch axis is [-pitchEulerAngleExtensionUpperLimit, -pitchEulerAngleExtensionLowerLimit]

Using X-Port to develop payload devices

1. X-Port function module initialization

When using X-Port to develop a load device, you need to initialize the X-Port function module first.

djiStat = DjiXPort_Init();
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("XPort init error: 0x%08llX.", djiStat);
return djiStat;
}

2. Get X-Port status information

  1. Get system status of X-Port
  • Receive the status information of X-Port by constructing the callback function.
static T_DjiReturnCode ReceiveXPortSystemState(T_DjiGimbalSystemState systemState)
{
T_DjiReturnCode returnCode;
T_DjiOsalHandler *osalHandler = DjiPlatform_GetOsalHandler();

returnCode = osalHandler->MutexLock(s_userXPortMutex);
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("user XPort mutex lock error: 0x%08llX.", returnCode);
return returnCode;
}

s_isUserXPortSystemStateVaild = true;
memcpy(&s_userXPortSystemState, &systemState, sizeof(T_DjiGimbalSystemState));

returnCode = osalHandler->MutexUnlock(s_userXPortMutex);
if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("user XPort mutex unlock error: 0x%08llX.", returnCode);
return returnCode;
}

USER_LOG_DEBUG("receive XPort system state: mounted upward flag %d, gimbal mode %d.",
systemState.mountedUpward, systemState.gimbalMode);

USER_LOG_DEBUG("XPort fine tune: %d %d %d.", systemState.fineTuneAngle.pitch,
systemState.fineTuneAngle.roll, systemState.fineTuneAngle.yaw);

return DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS;
}
  • Receive the status information of X-Port by registering the callback function, as shown in Figure 1. X-Port status.
djiStat = DjiXPort_RegReceiveSystemStateCallback(ReceiveXPortSystemState);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("register receive XPort system state callback function error: 0x%08llX.", djiStat);
return djiStat;
}

Figure 1. X-Port Status

  1. Get X-Port attitude information
  • Construct a callback function to get the attitude of the X-Port, and print the attitude information of the X-Port in the callback function.
static T_DjiReturnCode ReceiveXPortAttitudeInformation(T_DjiGimbalAttitudeInformation attitudeInformation)
{
USER_LOG_DEBUG("receive XPort attitude information:");
USER_LOG_DEBUG("XPort attitude: pitch %d, roll %d, yaw %d.", attitudeInformation.attitude.pitch,
attitudeInformation.attitude.roll, attitudeInformation.attitude.yaw);

return DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS;
}
  • Obtain the attitude information of X-Port by registering the callback function, as shown in Figure 2. X-Port attitude.
djiStat = DjiXPort_RegReceiveAttitudeInformationCallback(ReceiveXPortAttitudeInformation);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("register receive XPort attitude information callback function error: 0x%08llX.", djiStat);
return djiStat;
}

Figure 2. X-Port pose

3. Set X-Port Limit Angle

  • Set X-Port limit angle In order to prevent the X-Port from being accidentally damaged due to structural interference or interfering with the drone's flight mission when the X-Port is working, please follow the ["Structural Standards"](https://developer.dji .com/cn/document/b404d63c-6d07-46a6-b66d-35796a5b2ae3), set the limit angle of X-Port, as shown in Table 3. X-Port limit angle.

Note: In the following code, the angle unit of X-Port is 0.1 degree.

Table 3. X-Port limit angle

CategoryLimit angle (degrees)
Pitch axis joint angle20 (upper limit), -100 (lower limit)
Roll axis joint angle20 (upper limit), -20 (lower limit)
Euler angle of pitch axis25 (upper limit), -80 (lower limit)
Extended pitch axis Euler angles25 (upper limit), -100 (lower limit)
Pan axis joint angleMounted on I gimbal: 30 (upper limit), -150 (lower limit)
Mounted on gimbal II: 150 (upper limit), -30 (lower limit)
limitAngle.upperLimit = 300;
limitAngle.lowerLimit = -1000;
djiStat = DjiXPort_SetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_JOINT_ANGLE, limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("set pitch joint angle limit angle for XPort error: 0x%08llX.", djiStat);
return djiStat;
}

limitAngle.upperLimit = 300;
limitAngle.lowerLimit = -800;
djiStat = DjiXPort_SetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE, limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("set pitch euler angle limit angle for XPort error: 0x%08llX.", djiStat);
return djiStat;
}

limitAngle.upperLimit = 300;
limitAngle.lowerLimit = -1000;
djiStat = DjiXPort_SetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE_EXTENSION, limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("set pitch extension euler angle limit angle for XPort error: 0x%08llX.", djiStat);
return djiStat;
}

djiStat = DjiAircraftInfo_GetBaseInfo(&aircraftInfoBaseInfo);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get aircraft base information error: 0x%08llX.", djiStat);
return djiStat;
}

if (aircraftInfoBaseInfo.mountPosition == DJI_MOUNT_POSITION_PAYLOAD_PORT_NO1) {
limitAngle.upperLimit = 300;
limitAngle.lowerLimit = -1500;
} else if (aircraftInfoBaseInfo.mountPosition == DJI_MOUNT_POSITION_PAYLOAD_PORT_NO2) {
limitAngle.upperLimit = 1500;
limitAngle.lowerLimit = -300;
} else if (aircraftInfoBaseInfo.mountPosition == DJI_MOUNT_POSITION_PAYLOAD_PORT_NO3) {
limitAngle.upperLimit = 1500;
limitAngle.lowerLimit = -1500;
} else {
USER_LOG_WARN("payload mount position is unknown.");
return DJI_ERROR_SYSTEM_MODULE_CODE_SYSTEM_ERROR;
}

djiStat = DjiXPort_SetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_YAW_JOINT_ANGLE, limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("set yaw joint angle limit angle for XPort error: 0x%08llX.", djiStat);
return djiStat;
}
  • Get the angle of the limit angle in the thread of the X-Port and print it on the terminal, as shown in Figure 3. X-Port limit angle.
djiStat = DjiXPort_GetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_ROLL_JOINT_ANGLE, &limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get roll joint angle limit angle from XPort error: 0x%08llX.", djiStat);
continue;
}

USER_LOG_DEBUG("roll joint angle limit angle of XPort: upper limit %d, lower limit %d.", limitAngle.upperLimit, limitAngle.lowerLimit);

djiStat = DjiXPort_GetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_JOINT_ANGLE, &limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get pitch joint angle limit angle from XPort error: 0x%08llX.", djiStat);
continue;
}

USER_LOG_DEBUG("pitch joint angle limit angle of XPort: upper limit %d, lower limit %d.", limitAngle.upperLimit, limitAngle.lowerLimit);

djiStat = DjiXPort_GetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE, &limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get pitch euler angle limit angle from XPort error: 0x%08llX.", djiStat);
continue;
}

USER_LOG_DEBUG("pitch euler angle limit angle of XPort: upper limit %d, lower limit %d.", limitAngle.upperLimit, limitAngle.lowerLimit);

djiStat = DjiXPort_GetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE_EXTENSION,
&limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get pitch extension euler angle limit angle from XPort error: 0x%08llX.", djiStat);
continue;
}

USER_LOG_DEBUG("pitch extension euler angle limit angle of XPort: upper limit %d, lower limit %d.", limitAngle.upperLimit, limitAngle.lowerLimit);

djiStat = DjiXPort_GetLimitAngleSync(DJI_XPORT_LIMIT_ANGLE_CATEGORY_YAW_JOINT_ANGLE, &limitAngle);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get yaw joint angle limit angle from XPort error: 0x%08llX.", djiStat);
continue;
}

USER_LOG_DEBUG("yaw joint angle limit angle of XPort: upper limit %d, lower limit %d.",
limitAngle.upperLimit, limitAngle.lowerLimit);

Figure 3. X-Port limit angle

4. Set the speed conversion factor

In order to realize stable control of X-Port, it is necessary to set the X-Port speed conversion factor.

if (USER_UTIL_IS_WORK_TURN(step, 10, XPORT_TASK_FREQ)) {
if (DjiTest_CameraIsInited()) {
djiStat = DjiTest_CameraGetOpticalZoomFactor(&opticalZoomFactor);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get camera optical zoom factor error: %d.", djiStat);
continue;
}

djiStat = DjiTest_CameraGetDigitalZoomFactor(&digitalZoomFactor);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("get camera digital zoom factor error: %d.", djiStat);
continue;
}

djiStat = DjiXPort_SetSpeedConversionFactor(1 / (opticalZoomFactor * digitalZoomFactor));
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("set speed conversion factor error: %d.", djiStat);
continue;
}
}
}

5. Set X-Port working mode

  • After setting the mode of the X-Port, you can check the working mode of the X-Port through the X-Port system status.
  • For the detailed description of X-Port working mode, please refer to Gimbal Functionopen in new window.
djiStat = DjiXPort_SetGimbalModeSync(DJI_GIMBAL_MODE_FREE);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("set XPort gimbal mode error: 0x%08llX.", djiStat);
return djiStat;
}

6. Using the X-Port reset function

djiStat = DjiXPort_ResetSync(DJI_GIMBAL_RESET_MODE_PITCH_AND_YAW);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
USER_LOG_ERROR("reset XPort gimbal error: 0x%08llX.", djiStat);
return djiStat;
}

X-Port debugging

After installing the payload device on the X-Port and connecting the drone to DJI Assistant 2, developers can use DJI Assistant 2open in new window to debug X-Port.

Note:

  • Please refer to DJI X-Port User Guideopen in new window.
  • When installing the payload device on the X-Port, please ensure that the payload device on the X-Port can stay in each position of the pitch axis, yaw axis, and roll axis, and Balance in each position.

Manual leveling

1. Adjust the pitch axis When installing the load device on the X-Port, rotate the load device around the central axis of the P-axis to ensure that the load device can stay at each position of the pitch axis.

2. Roll axis leveling

  1. Use an L-shaped socket head screwdriver to loosen the 4 screws on the Row shaft arm (no need to remove the screws);
  2. Adjust the position of the R-axis arm from left to right, so that when the R-axis arm rotates, it can maintain balance at any position;
  3. Re-tighten the 4 screws (torque batch size is 2.0±0.1 kgf.cm).

Figure 4. X-Port roll axis leveling

3. Yaw axis leveling

  1. Use an L-shaped socket head screwdriver to loosen the 4 screws on the yaw axis arm (no need to remove the screws);
  2. Adjust the position of the yaw shaft arm back and forth, so that when the axis of the yaw shaft base is not perpendicular to the ground, the load equipment can stay at any position without rotating around the yaw shaft base;
  3. Re-tighten the 4 screws (torque batch size is 2.0±0.1 kgf.cm ).

Figure 5. X-Port yaw axis leveling

Software debugging

Using DJI Assistant 2open in new window, developers can perform balance detection, coaxiality detection, and force adjustment debugging for load equipment operate.

Note:

  • While debugging the gimbal with DJI Assistant 2, do not control the gimbal, such as controlling the gimbal angle, speed, and gimbal return.
  • When using DJI Assistant 2 to debug the DJI X-Port, please debug the gimbal in the order of balance detection, coaxiality detection, control parameter auto-tuning, and auto-calibration.
1. Balance detection (X-Port is joint angle mode)
  1. On the "Gimbal Settings" page, click "Gimbal Balance Detection", and prepare the drone and X-Port gimbal according to the instructions;
  2. Detect and adjust the X-Port according to the guidance of DJI Assistant 2;
  3. During inspection, once the X-Port is not balanced, the developer needs to readjust the gimbal according to the inspection progress and inspection results:
  4. Please move the load forward (backward), upward (downward), and then perform the balance test again;
  5. Please adjust the position of the roll axis arm of the gimbal to the left (right), and then perform the balance test again;
  6. Please adjust the position of the yaw axis arm of the gimbal forward (backward), and then perform the balance check again.
2. Concentricity detection (X-Port is joint angle mode)

Note: Before executing the coaxiality detection function, please perform the balance detection first, and ensure that the balance of the X-Port is good.

  1. On the "Gimbal Settings" page, click "Gimbal Coaxiality Detection", and prepare the drone and X-Port gimbal according to the instructions;
  2. Detect and adjust the X-Port according to the guidance of DJI Assistant 2;
  3. During testing, once the X-Port's coaxiality test result is poor, the developer needs to re-adjust the installation method of the load device and the X-Port auxiliary shaft arm according to the test progress and test results: please forward (backward) , Adjust the screw of the load sub-shaft arm up (down) and perform the coaxiality test again.
3. Control parameter auto-tuning

Note:

  • Before executing the control parameter auto-tuning function, please perform the balance detection and coaxiality detection first, and ensure that the results of the X-Port balance detection and coaxiality detection are good;
  • When performing the "control parameter auto-tuning" operation, please place the drone horizontally, and ensure that the angle of the drone's roll axis and pitch axis is within ±5°.
  1. On the "gimbal Settings" page, click "gimbal Auto Tuning", DJI Assistant 2 will automatically adjust the control parameters of the X-Port according to the status of the load device;
  2. Turn off the drone motor and keep the load equipment in a static state;
  3. DJI Assistant 2 or DJI Pilot sends gimbal control commands to the X-Port to perform the auto-tuning function of control parameters.
4. Auto Calibration

If the initial position of the load device on the X-Port is not horizontally centered, use the auto-calibration function to calibrate the X-Port.

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.