5.19 标准云台组件（X-PORT）

5.19.1 基本功能介绍

标准云台组件（X-PORT）是DJI推出的一个完全兼容PSDK和DJI无人机（M210，M300）的可二次开发的物理云台。与5.8中gimbal emu实际是同一个功能，因为gimbal emu需要自己开发一个物理云台或者使用第三方（非DJI的云台），需要较高的开发成本。作为DJI官方的云台，将行业领先的云台产品直接整合到PSDK的开发中会大大降低开发成本，适配效果也可做到最优。

X-PORT必须挂载在DJI无人机上并结合PSDK开发使用，可以直接连接至无人机，不再需要转接环。可以理解为X-PORT是基于skyport已经天然集成gimbal emu模块后的云台设备，使用X-PORT只需开发其他的模块，比如相机负载等，将设备安装到X-PORT上使用。

此文档中主要结合PSDK sample从软件层面介绍X-PORT的相关使用，因为X-PORT也会涉及到硬件结构或安装相关特性，相关特性请访问DJI developer官方网站负载特性了解，或查看X-PORT用户手册。

5.19.2 主要代码文件

xport/
├── test_payload_xport.c
└── test_payload_xport.h

PSDK lib头文件：

dji_xport.h

5.19.3 sample代码实现

功能入口

#ifdef CONFIG_MODULE_SAMPLE_XPORT_ON
if (aircraftInfoBaseInfo.djiAdapterType == DJI_SDK_ADAPTER_TYPE_XPORT) {
    if (DjiTest_XPortStartService() != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
    USER_LOG_ERROR("psdk xport init error");
    }
}
#endif

需使用X-PORT接入时才可以使用X-PORT模块功能。

初始化

/**
 * @brief Initialise XPort module.
 * @note The function have to be called before other functions related to XPort.
 * @return Execution result.
 */
T_DjiReturnCode DjiXPort_Init(void);

使用X-PORT模块功能前调用
需要注意，X-PORT的初始化中会用到PSDK的订阅功能，自行设计X-PORT开发时，调用此API前请务必先调用订阅初始化API：DjiFcSubscription_Init，否则初始化会出错。

注册接收X-PORT系统状态回调

/**
 * @brief Data structure describes gimbal system state.
 */
typedef struct {
    bool resettingFlag; /*!< Specifies whether gimbal is resetting now or not. */
    bool mountedUpward; /*!< Specifies whether gimbal is upward or not. */
    bool blockingFlag; /*!< Specifies whether gimbal is stuck or not. */
    bool pitchRangeExtensionEnabledFlag; /*!< Specifies whether extended angle range of gimbal pitch axis is enabled or not. */
    E_DjiGimbalMode gimbalMode; /*!< Gimbal mode. */
    T_DjiAttitude3d fineTuneAngle; /*!< Fine tune angles, unit: 0.1 degree. */
    T_DjiGimbalControllerSmoothFactor smoothFactor; /*!< Smooth factor of gimbal controller. */
    T_DjiGimbalControllerMaxSpeedPercentage maxSpeedPercentage; /*!< Max speed percentage of gimbal controller. */
} T_DjiGimbalSystemState;

/**
 * @brief Prototype of callback function used to receive system state of XPort.
 * @warning User can not execute blocking style operations or functions in callback function, because that will block DJI
 * root thread, causing problems such as slow system response, payload disconnection or infinite loop.
 * @param systemState: system state of XPort.
 * @return Execution result.
 */
typedef T_DjiReturnCode (*DjiReceiveXPortSystemStateCallback)(T_DjiGimbalSystemState systemState);

/**
 * @brief Register callback function used to receive system state of XPort.
 * @note The callback function will be called after registering. The call frequency is 1Hz.
 * @param callback: pointer to the callback function.
 * @return Execution result.
 */
T_DjiReturnCode DjiXPort_RegReceiveSystemStateCallback(DjiReceiveXPortSystemStateCallback callback);

负载端通过此回调可以接收到X-PORT运行系统的状态，包括挂载位置，复位状态，云台模式等状态。
相比gimbal emu，X-PORT的系统状态非PSDK端实现的物理状态，所以需要注册一个回调来被动接收此状态。

注册X-PORT姿态角信息

/**
 * @brief Gimbal attitude related information.
 */
typedef struct {
    T_DjiAttitude3d attitude; /*!< Gimbal attitude in the ground coordinate, unit: 0.1 degree. */
    T_DjiGimbalReachLimitFlag reachLimitFlag; /*!< Reach limit flag, being set when the joint angles of gimbal reach limits. */
} T_DjiGimbalAttitudeInformation;

/**
 * @brief Prototype of callback function used to receive attitude information of XPort.
 * @warning User can not execute blocking style operations or functions in callback function, because that will block DJI
 * root thread, causing problems such as slow system response, payload disconnection or infinite loop.
 * @param attitudeInformation: attitude information of XPort.
 * @return Execution result.
 */
typedef T_DjiReturnCode (*DjiReceiveXPortAttitudeInformationCallback)(T_DjiGimbalAttitudeInformation attitudeInformation);

/**
 * @brief Register callback function used to receive attitude information of XPort.
 * @note The callback function will be called after registering. The call frequency is 10Hz.
 * @param callback: pointer to the callback function.
 * @return Execution result.
 */
T_DjiReturnCode DjiXPort_RegReceiveAttitudeInformationCallback(DjiReceiveXPortAttitudeInformationCallback callback);

X-PORT的姿态角通过此回调API实时抛出来供负载端使用。
相比gimbal emu，X-PORT云台的姿态角不再需要回传给APP，但是需要知道X-PORT当前角度便于负载设备整合。

设置限位角

5.8云台功能组件中也有介绍，云台的限位角有关节角限制，以及自定义姿态范围角限制，主要是因为负载设备结构尺寸、多云台挂载以及挂载位置等因素的限制，云台不能完全按照其支持的关节角度自由转动。PSDK对X-PORT提供了设置限位角的接口，可以限定控制过程中的旋转角度。

说明：

实际上X-PORT云台负载结构不能完全自定义，因为云台有上电自检动作，自检动作会按关节角转动。自检动作无法通过PSDK软件层面来关闭或限制，仅在上电完成后的控制过程中保证X-PORT的控制角度在设定姿态角范围内。

/**
 * @brief Set limit angle for XPort in blocking mode.
 * @details Please refer to XPort part of <a href="https://developer.dji.com/payload-sdk">developer website</a> for
 * details about default limit angle of XPort.
 * @note Max execution time of this function is slightly larger than 1200ms.
 * @note XPort do not response set limit angle command in process of control parameters auto-tuning, coaxiality
 * detection and balance detection.
 * @param limitAngleCategory: limit angle category.
 * @param limitAngle: limit angle.
 * @return Execution result.
 */
T_DjiReturnCode DjiXPort_SetLimitAngleSync(E_DjiXPortLimitAngleCategory limitAngleCategory,
                                           T_DjiXPortLimitAngle limitAngle);

API简介：

用于设定云台的姿态角范围，之后云台只能在设定的范围内转动。
此API的执行时间在1.2s左右，所以在设定执行过程中可能会造成延时。
此API设定的范围仅在控制过程中生效，自检，同轴检测，平衡检测中不会生效。

参数简介：

limitAngleCategory，指定需要设定的云台轴向，roll，pitch，yaw。其中pitch包含可拓展的pitch角度。
limitAngle，指定轴向的角度设置值，NEU坐标系数值。角度设置需在关节角支持范围内。

启动X-PORT任务

if (osalHandler->TaskCreate("user_xport_task", UserXPort_Task, XPORT_TASK_STACK_SIZE, NULL, &s_userXPortThread) !=
    DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
    USER_LOG_ERROR("user XPort task create error.");
    return DJI_ERROR_SYSTEM_MODULE_CODE_UNKNOWN;
}

相比gimbal emu，X-PORT的任务中工作更为简单，因为不需要再具体的对物理云台进行计算和控制，仅提供了一个控制云台旋转变换因子的设置API，通过转换因子可以调整X-PORT转动的速度，sample中给出的是通过变焦倍数来变换转动速度。简单的逻辑，画面放大倍数越高，云台旋转时希望云台转动越慢。

/**
 * @brief Set speed conversion factor for speed control from joystick and APP.
 * @details XPort convert speed control command from joystick and APP to rotation speed based on the speed conversion
 * factor. The formula is "speed = maximum rotation speed * conversion factor", and maximum rotation speed is a product of
 * default maximum speed and maximum speed percentage. The default maximum rotation speed is 90degree/s. The maximum
 * speed percentage is set by APP. The default speed conversion factor is 1.0.
 * @note The value will be effective after a while, and the max value is 100ms.
 * @param factor: Speed conversion factor and it has to be smaller than or equal to 1.0.
 * @return Execution result.
 */
T_DjiReturnCode DjiXPort_SetSpeedConversionFactor(float factor);

API简介：

用于设置控制云台转动速度的转换因子，转换因子实际是最大速度的倍乘参数，也就是实际控制速度是最大速度 * factor。这样通过摇杆或SDK控制X-PORT云台转动的速度就会根据设定的参数有所调整。需要注意，最大是有默认的最大旋转速度90度/s 与APP上设置的百分比决定的，APP设置过后的最大速度再乘factor参数

参数：

factor，转换因子，取值范围：0 ~ 1.0。例如sample使用变焦倍数的倒数作为速度转换因子，1 / (opticalZoomFactor * digitalZoomFactor)。

5.19.4 开发注意事项

X-PORT必须连接至无人机上，并结合PSDK二次开发才能正常使用。
PSDK中X-PORT模块与gimbal emu模块不要同时使用。
与gimbal emu模块一样，在DJI官方APP上，PSDK负载相机模块和云台模块是一体的，如果使用X-PORT时不注册camera emu模块，在DJI Pilot APP上因无法识别到PSDK相机，在一些特定的情况下就无法控制云台。比如同时挂载多个负载设备时，Pilot上无法切换至X-PORT负载设备上，也就无法控制。云台联动功能也将无法使用。
除gimbal emu开发与X-PORT功能重合外，其他PSDK功能与skyport v2开发完全一样。
X-PORT上连接负载的端口为排线接口，线序定义与skyport v2的排线接口完全一样。
X-PORT上电会自检，自检会自动旋转到关节角限位，这个是无法关闭的，设计负载尺寸时需要注意设备物理干涉。

此组别内的文章

5.19 标准云台组件（X-PORT）