PSDK 云台相关功能的头文件为dji_gimbal.h，本文档描述了dji_gimbal.h 文件中结构体和函数原型的关键信息和使用方法。

说明： 仅使用Skyport 开发的负载设备可使用dji_gimbal.h，若使用X-Port 开发负载设备，请使用dji_xport.h。

目录

• 宏定义、枚举与结构体
  E_DjiGimbalCalibrationStage
  E_DjiGimbalAxis
  E_DjiGimbalResetMode
  T_DjiGimbalControllerSmoothFactor
  T_DjiGimbalControllerMaxSpeedPercentage
  T_DjiGimbalSystemState
  T_DjiGimbalReachLimitFlag
  T_DjiGimbalAttitudeInformation
  T_DjiGimbalCalibrationState
  T_DjiGimbalRotationProperty
  T_DjiGimbalCommonHandler

• 函数原型
  DjiGimbal_Init
  DjiGimbal_DeInit
  DjiGimbal_RegCommonHandler

宏定义、枚举与结构体

typedef enum E_DjiGimbalCalibrationStage

云台校准

typedef enum {
    DJI_GIMBAL_CALIBRATION_STAGE_COMPLETE = 0,   云台校准成功 
    DJI_GIMBAL_CALIBRATION_STAGE_PROCRESSING = 1,云台校准中 
    DJI_GIMBAL_CALIBRATION_STAGE_FAILED = 3,云台校准失败
} E_DjiGimbalCalibrationStage;

typedef enum E_DjiGimbalAxis

云台轴

typedef enum {
    DJI_GIMBAL_AXIS_PITCH = 0,  俯仰轴
    DJI_GIMBAL_AXIS_ROLL = 1,  横滚轴
    DJI_GIMBAL_AXIS_YAW = 2,  偏航轴
} E_DjiGimbalAxis;

typedef enum E_DjiGimbalResetMode

云台复位模式

typedef enum {
   DJI_GIMBAL_RESET_MODE_YAW = 1,  航向轴复位：将云台航向轴的角度复位为无
 人机航向轴角度与云台航向轴微调角度的和
   DJI_GIMBAL_RESET_MODE_PITCH_AND_YAW = 3,  俯仰轴与航向轴复位：将云台俯仰轴的角度
 复位为微调的角度，将云台航向轴的角度复
 位为无人机航向轴角度与云台航向轴微调角
 度的和
   DJI_GIMBAL_RESET_MODE_PITCH_DOWNWARD_UPWARD_AND_YAW = 11,  重置云台的偏航轴和
   俯仰轴，将偏航轴的
   角度重置为无人机偏
   航轴和微调角度的和。
   重置俯仰轴为-90°与
   微调角度的和（云台
   下置），90°与微调
   角度的和（云台上置）。
   DJI_GIMBAL_RESET_MODE_PITCH_DOWNWARD_UPWARD = 12,重置云台的偏航轴为
   -90°与微调角度的和
   （云台下置），90°与
   微调角度的和（云台上
   置）。
} E_DjiGimbalResetMode;

typedef struct T_DjiGimbalControllerSmoothFactor

云台的平滑系数

typedef struct {
    uint8_t pitch;  俯仰轴平滑系数：0～30 
    uint8_t yaw;    横滚轴平滑系数：0～30 
} T_DjiGimbalControllerSmoothFactor;

typedef struct T_DjiGimbalControllerMaxSpeedPercentage

最大速度百分比

typedef struct {
    uint8_t pitch;    俯仰轴最大速度百分比：1～100 
    uint8_t yaw; 偏航轴最大速度百分比：1～100 
} T_DjiGimbalControllerMaxSpeedPercentage;

typedef struct T_DjiGimbalSystemState

云台的状态

typedef struct {
    bool resettingFlag;云台重置中 
    bool mountedUpward;上置云台 
    bool blockingFlag; 云台卡顿 
    bool pitchRangeExtensionEnabledFlag;   开启云台俯仰轴角度范围扩展功能 
    E_DjiGimbalMode gimbalMode; 云台控制方式 
    T_DjiAttitude3d fineTuneAngle;   云台角度微调，单位：0.1 度 
    T_DjiGimbalControllerSmoothFactor smoothFactor; 云台平滑度 
    T_DjiGimbalControllerMaxSpeedPercentage maxSpeedPercentage;    云台最大速度百分比 
} T_DjiGimbalSystemState;

typedef struct T_DjiGimbalReachLimitFlag

到达限位标志

typedef struct {
    bool pitch;    俯仰轴到达限位 
    bool roll;横滚轴到达限位 
    bool yaw; 偏航轴到达限位 
} T_DjiGimbalReachLimitFlag;

typedef struct T_DjiGimbalAttitudeInformation

云台角度

typedef struct {
    T_DjiAttitude3d attitude;   云台角度 单位：0.1 度 
    T_DjiGimbalReachLimitFlag reachLimitFlag;  云台关节角到达限位标志 
} T_DjiGimbalAttitudeInformation;

typedef struct T_DjiGimbalCalibrationState

云台校准状态

typedef struct {
    bool calibratingFlag;   云台校准中 
    bool lastCalibrationResult;  云台最近一次校准成功的结果 
    uint8_t currentCalibrationProgress;    云台当前的校准进度，进度的范围为0～100 
    E_DjiGimbalCalibrationStage currentCalibrationStage; 云台当前的校准状态和校准结果，
   云台校准时的详细信息，请参见：DJI_GIMBAL_CALIBRATION_STAGE_PROCRESSING，
   云台未在校准时的详细信息为最近一次的校准结果 
} T_DjiGimbalCalibrationState;

typedef struct T_DjiGimbalRotationProperty

云台转动命令的属性

typedef struct {
    struct {
        bool pitch; 无视俯仰轴转动命令
        bool roll;  无视横滚轴转动命令
        bool yaw;   无视偏航轴转动命令
    } rotationValueInvalidFlag; 指定云台中无视转动命令的轴

    union {
        struct {
            uint16_t actionTime; 云台转动到目标角度的时间，单位：0.01s
        } relativeAngleRotation; 相对角度控制
        struct {
            uint16_t actionTime; 云台转动到目标角度的时间，单位：0.01s
            /*! 关节角度有效标志，指定绝对角度控制时T_DjiGimbalRotationProperty::absoluteAngleRotation::jointAngle是否有效。 */
            bool jointAngleValid;
            /*! 云台关节角度，单位：0.1度。 如果
T_DjiGimbalRotationProperty::absoluteAngleRotation::jointAngleValid 为假，此处指定关节角度无效，请忽略关节角度。 如果关节角度有效，用户应确保云台的目标关节角度与指定值大致相同。 */
            T_DjiAttitude3d jointAngle;
        } absoluteAngleRotation; 绝对角度控制
    };
} T_DjiGimbalRotationProperty;

typedef struct T_DjiGimbalCommonHandler

云台控制，请根据本结构体中的函数构造云台控制相关功能的回调函数，其中包括：

• 获取云台当前的状态
• 获取云台当前的角度
• 获取云台校准状态
• 获取云台转动速度
• 获取云台关节角的角度
• 转动云台
• 控制云台开始校准
• 设置云台的平滑度
• 开启或关闭俯仰轴欧拉角扩展角
• 设置云台最大速度百分比
• 恢复云台信息
• 设置云台模式
• 重置云台参数
• 云台角度微调

说明： 为防止该函数阻塞PSDK 的主线程，导致出现程序响应缓慢、相机类负载设备断连及死循环等问题，请勿以阻塞的方式在回调函数中执行该函数。

typedef struct {
    
@brief 获取云台当前状态的回调函数
@param systemState: 指向用于存储云台状态的内存空间
@return 执行结果
T_DjiReturnCode (*GetSystemState)(T_DjiGimbalSystemState *systemState);
    
@brief 获取云台当前角度的回调函数
@param attitudeInformation: 指向用于存储云台角度信息的内存空间
@return 执行结果
T_DjiReturnCode (*GetAttitudeInformation)(T_DjiGimbalAttitudeInformation *attitudeInformation);

@brief 获取云台校准状态的回调函数
@param calibrationState: 指向用于存储云台校准状态的内存空间
@return 执行结果
T_DjiReturnCode (*GetCalibrationState)(T_DjiGimbalCalibrationState *calibrationState);

@brief 转动云台的回调函数，当有模块控制云台时将触发该函数
@note 在某些场景中，由于该回调函数的调用频率较高（如200Hz），因此请为该回调函数设置较短的执行时间
@param rotationMode: 云台控制方式
@param rotationProperty: 云台转动的属性
@param rotationValue:  云台转动的角度，单位：0.1 度（若云台的控制方式为DJI_GIMBAL_ROTATION_MODE_RELATIVE_ANGLE 
* 或DJI_GIMBAL_ROTATION_MODE_ABSOLUTE_ANGLE，0.1 度/s（若云台的控制方式为DJI_GIMBAL_ROTATION_MODE_SPEED）
@return 执行结果
T_DjiReturnCode (*Rotate)(E_DjiGimbalRotationMode rotationMode, 
  T_DjiGimbalRotationProperty rotationProperty,
  T_DjiAttitude3d rotationValue);

@brief 控制云台开始校准
@note 云台校准的时间最大为120s，超出该时间后，DJI Pilot 或基于MSDK 开发的移动端App 将认为云台校准失败
@return 执行结果
T_DjiReturnCode (*StartCalibrate)(void);

@brief 设置云台的平滑度
@param smoothingFactor: 平滑度，该数值越大，云台的加速度越大，云台转动的最大
    加速度= 10000 × (0.8 ^ (1 + X)) deg/s^2 (X 为平滑控制系数) 取值范围为0～30
@param axis: 指定云台上所需设置平滑度的轴
@return 执行结果
T_DjiReturnCode (*SetControllerSmoothFactor)(uint8_t smoothingFactor, E_DjiGimbalAxis axis);
    
@brief 开启或关闭俯仰轴欧拉角扩展角的回调函数
@details 使用俯仰轴角度范围扩展功能后，可将云台俯仰轴的欧拉角角度限制设置为默认限制或扩展限制
@param enabledFlag: 开启或关闭俯仰轴欧拉角扩展角功能
@return 执行结果
T_DjiReturnCode (*SetPitchRangeExtensionEnabled)(bool enabledFlag);

@brief 设置云台最大速度百分比
@param maxSpeedPercentage: 设置云台的最大速度（范围：1～100），云台实际最大的转动速度= 默认最大速度 × 最大速度百分比
@param axis: 指定云台上所需设置最大速度百分比的轴
@return 执行结果
T_DjiReturnCode (*SetControllerMaxSpeedPercentage)(uint8_t maxSpeedPercentage, E_DjiGimbalAxis axis);
   
@brief 恢复云台信息
@return 执行结果
T_DjiReturnCode (*Restore FactorySettings)(void);
    
@brief 设置云台模式的回调函数
@param mode: 云台模式
@return 执行结果
T_DjiReturnCode (*SetMode)(E_DjiGimbalMode mode);
    
@brief 重置云台参数的回调函数
@note 重置云台参数时，将会中断云台的工作
@param mode: 云台复位模式
@return 执行结果
T_DjiReturnCode (*Reset)(E_DjiGimbalResetMode mode);
    
@brief 云台角度微调
@param fineTuneAngle:  微调值，单位：0.1 度。大于0代表朝向机体坐标的正方向旋转
@return 执行结果
T_DjiReturnCode (*FineTuneAngle)(T_DjiAttitude3d fineTuneAngle);
    
@brief 获取云台转动速度的回调函数
@note 调用该函数后，用户即可20 ms 内获取云台转动的速度（50 Hz）
@param rotationSpeed: 指向用于存储云台转动速度的内存空间，使用机体坐标系，单位：0.1度/s。
@return 执行结果
T_DjiReturnCode (*GetRotationSpeed)(T_DjiAttitude3d *rotationSpeed);

@brief 获取云台关节角的回调函数
@param jointAngle: 指向用于存储云台关节角的内存空间，单位：0.1 度
@return 执行结果
T_DjiReturnCode (*GetJointAngle)(T_DjiAttitude3d *jointAngle);
} T_DjiGimbalCommonHandler;

函数原型

function DjiGimbal_Init

功能：初始化云台模块

product：all

在使用云台控制功能前，请先调用本接口初始化云台模块。

T_DjiReturnCode DjiGimbal_Init(void);

返回值
返回云台初始化的结果，详情请参见：DjiErrorCode

function DjiGimbal_DeInit

功能：反初始化云台模块

product：all

T_DjiReturnCode DjiGimbal_DeInit(void);

返回值
根据程序执行的情况输出对应的返回值，详情请参见：DjiErrorCode

function DjiGimbal_RegCommonHandler

功能：注册云台控制功能

product：all

注册控制云台的回调函数。

T_DjiReturnCode DjiGimbal_RegCommonHandler(const T_DjiGimbalCommonHandler *commonHandler);

参数
commonHandler：指向回调函数
返回值
根据程序执行的情况输出对应的返回值，详情请参见：DjiErrorCode