云台功能

2021-02-02

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

说明: 仅使用Skyport 开发的负载设备可使用psdk_gimbal.h,若使用X-Port 开发负载设备,请使用psdk_xport.h

目录

枚举

typedef enum E_PsdkGimbalMode

云台模式

typedef enum {
PSDK_GIMBAL_MODE_FREE = 0, 自由模式,当无人机的姿态改变时,云台将不会转动
PSDK_GIMBAL_MODE_FPV = 1, FPV 模式,当无人机的姿态发生改变时,云台会转动航向轴与横滚轴
PSDK_GIMBAL_MODE_YAW_FOLLOW = 2, YAW 跟随模式,在该模式下,云台的航向轴会跟随无人机的航向轴转动
} E_PsdkGimbalMode;

typedef enum E_PsdkGimbalCalibrationStage

云台校准

typedef enum {
PSDK_GIMBAL_CALIBRATION_STAGE_COMPLETE = 0, 云台校准成功
PSDK_GIMBAL_CALIBRATION_STAGE_PROCRESSING = 1, 云台校准中
PSDK_GIMBAL_CALIBRATION_STAGE_FAILED = 3, 云台校准失败
} E_PsdkGimbalCalibrationStage;

typedef enum E_PsdkGimbalRotationMode

云台控制方式

typedef enum {
PSDK_GIMBAL_ROTATION_MODE_RELATIVE_ANGLE = 0, 相对角度控制:使用PSDK 开发的云台根据用户指定的角
度,在规定的时间内,转动指定的角度
PSDK_GIMBAL_ROTATION_MODE_ABSOLUTE_ANGLE = 1, 绝对角度控制:使用PSDK 开发的云台根据用户的指令,在规
定的时间内,从当前的位置转动到指定的位置
PSDK_GIMBAL_ROTATION_MODE_SPEED = 2, 速度控制:用户可控制使用PSDK 开发的云台的转动速度
} E_PsdkGimbalRotationMode;

typedef enum E_PsdkGimbalRotationMode

云台转动模式,尤其指定云台的控制方式

typedef enum {
PSDK_GIMBAL_AXIS_PITCH = 0, 俯仰轴
PSDK_GIMBAL_AXIS_ROLL = 1, 横滚轴
PSDK_GIMBAL_AXIS_YAW = 2, 偏航轴
} E_PsdkGimbalAxis;

typedef enum E_PsdkGimbalResetMode

云台复位

typedef enum {
PSDK_GIMBAL_RESET_MODE_YAW = 1, 航向轴复位:将云台航向轴的角度复位为无
人机航向轴角度与云台航向轴微调角度的和
PSDK_GIMBAL_RESET_MODE_PITCH_AND_YAW = 3, 俯仰轴与航向轴复位:将云台俯仰轴的角度
复位为微调的角度,将云台航向轴的角度复
位为无人机航向轴角度与云台航向轴微调角
度的和
PSDK_GIMBAL_RESET_MODE_PITCH_DOWNWARD_UPWARD_AND_YAW = 11, 重置云台的偏航轴和
俯仰轴,将偏航轴的
角度重置为无人机偏
航轴和微调角度的和。
重置俯仰轴为-90°与
微调角度的和(云台
下置),90°与微调
角度的和(云台上置)。
PSDK_GIMBAL_RESET_MODE_PITCH_DOWNWARD_UPWARD = 12, 重置云台的偏航轴为
-90°与微调角度的和
(云台下置),90°与
微调角度的和(云台上
置)。
} E_PsdkGimbalResetMode;

结构体

typedef struct T_PsdkGimbalControllerSmoothFactor

云台的平滑系数

typedef struct {
uint8_t pitch; 俯仰轴平滑系数:030
uint8_t yaw; 横滚轴平滑系数:030
} T_PsdkGimbalControllerSmoothFactor;

typedef struct T_PsdkGimbalControllerMaxSpeedPercentage

最大速度百分比

typedef struct {
uint8_t pitch; 俯仰轴最大速度百分比:1100
uint8_t yaw; 偏航轴最大速度百分比:1100
} T_PsdkGimbalControllerMaxSpeedPercentage;

typedef struct T_PsdkGimbalSystemState

云台的状态

typedef struct {
bool resettingFlag; 云台重置中
bool mountedUpward; 上置云台
bool blockingFlag; 云台卡顿
bool pitchRangeExtensionEnabledFlag; 开启云台俯仰轴角度范围扩展功能
E_PsdkGimbalMode gimbalMode; 云台控制方式
T_PsdkAttitude3d fineTuneAngle; 云台角度微调,单位:0.1
T_PsdkGimbalControllerSmoothFactor smoothFactor; 云台平滑度
T_PsdkGimbalControllerMaxSpeedPercentage maxSpeedPercentage; 云台最大速度百分比
} T_PsdkGimbalSystemState;

typedef struct T_PsdkGimbalReachLimitFlag

到达限位标志

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

typedef struct T_PsdkGimbalAttitudeInformation

云台角度

typedef struct {
T_PsdkAttitude3d attitude; 云台角度 单位:0.1
T_PsdkGimbalReachLimitFlag reachLimitFlag; 云台关节角到达限位标志
} T_PsdkGimbalAttitudeInformation;

typedef struct T_PsdkGimbalCalibrationState

云台校准状态

typedef struct {
bool calibratingFlag; 云台校准中
bool lastCalibrationResult; 云台最近一次校准成功的结果
uint8_t currentCalibrationProgress; 云台当前的校准进度,进度的范围为0100
E_PsdkGimbalCalibrationStage currentCalibrationStage; 云台当前的校准状态和校准结果,
云台校准时的详细信息,请参见:PSDK_GIMBAL_CALIBRATION_STAGE_PROCRESSING,
云台未在校准时的详细信息为最近一次的校准结果
} T_PsdkGimbalCalibrationState;

typedef struct T_PsdkGimbalRotationProperty

云台转动命令的属性

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

union {
struct {
uint16_t actionTime; 云台转动到目标角度的时间,单位:0.01s
} relativeAngleRotation; 相对角度控制
struct {
uint16_t actionTime; 云台转动到目标角度的时间,单位:0.01s
bool jointAngleValid; 关节角有效标志,指示绝对角度控制时T_PsdkGimbalRotationProperty::absoluteAngleRotation::jointAngle是否有效
T_PsdkAttitude3d jointAngle; 云台关节角,单位:0.1度。如果T_PsdkGimbalRotationProperty::absoluteAngleRotation::jointAngleValid为假,代表关节角无效,请忽略关节角数值。如果关节角有效,用户应该控制云台关节角到指定值
} absoluteAngleRotation; 绝对角度控制
};
} T_PsdkGimbalRotationProperty;

typedef struct T_PsdkGimbalCommonHandler

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

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

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

typedef struct {

@brief 获取云台当前状态的回调函数
@param systemState: 指向用于存储云台状态的内存空间
@return 执行结果
T_PsdkReturnCode (*GetSystemState)(T_PsdkGimbalSystemState *systemState);

@brief 获取云台当前角度的回调函数
@param attitudeInformation: 指向用于存储云台角度信息的内存空间
@return 执行结果
T_PsdkReturnCode (*GetAttitudeInformation)(T_PsdkGimbalAttitudeInformation *attitudeInformation);

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

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

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

@brief 设置云台的平滑度
@param smoothingFactor: 平滑度,该数值越大,云台的加速度越大,云台转动的最大
加速度= 10000 × (0.8 ^ (1 + X)) deg/s^2 (X 为平滑控制系数) 取值范围为030
@param axis: 指定云台上所需设置平滑度的轴
@return 执行结果
T_PsdkReturnCode (*SetControllerSmoothFactor)(uint8_t smoothingFactor, E_PsdkGimbalAxis axis);

@brief 开启或关闭俯仰轴欧拉角扩展角的回调函数
@details 使用俯仰轴角度范围扩展功能后,可将云台俯仰轴的欧拉角角度限制设置为默认限制或扩展限制
@param enabledFlag: 开启或关闭俯仰轴欧拉角扩展角功能
@return 执行结果
T_PsdkReturnCode (*SetPitchRangeExtensionEnabled)(bool enabledFlag);

@brief 设置云台最大速度百分比
@param maxSpeedPercentage: 设置云台的最大速度(范围:1100),云台实际最大的转动速度= 默认最大速度 × 最大速度百分比
@param axis: 指定云台上所需设置最大速度百分比的轴
@return 执行结果
T_PsdkReturnCode (*SetControllerMaxSpeedPercentage)(uint8_t maxSpeedPercentage, E_PsdkGimbalAxis axis);

@brief 恢复云台信息
@return 执行结果
T_PsdkReturnCode (*Restore FactorySettings)(void);

@brief 设置云台模式的回调函数
@param mode: 云台模式
@return 执行结果
T_PsdkReturnCode (*SetMode)(E_PsdkGimbalMode mode);

@brief 重置云台参数的回调函数
@note 重置云台参数时,将会中断云台的工作
@param mode: 云台复位模式
@return 执行结果
T_PsdkReturnCode (*Reset)(E_PsdkGimbalResetMode mode);

@brief 云台角度微调
@param fineTuneAngle: 微调值,单位:0.1 度。大于0代表朝向机体坐标的正方向旋转
@return 执行结果
T_PsdkReturnCode (*FineTuneAngle)(T_PsdkAttitude3d fineTuneAngle);

@brief 获取云台转动速度的回调函数
@note 调用该函数后,用户即可20 ms 内获取云台转动的速度(50 Hz)
@param rotationSpeed: 指向用于存储云台转动速度的内存空间,使用机体坐标系,单位:0.1度/s。
@return 执行结果
T_PsdkReturnCode (*GetRotationSpeed)(T_PsdkAttitude3d *rotationSpeed);

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

函数原型

function PsdkGimbal_Init

功能:初始化云台模块 product:all

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

T_PsdkReturnCode PsdkGimbal_Init(void);

返回值
返回云台初始化的结果

function PsdkGimbal_DeInit

功能:反初始化云台模块 product:all
T_PsdkReturnCode PsdkGimbal_DeInit(void);

返回值
执行结果

function PsdkGimbal_RegCommonHandler

功能:注册云台控制功能 product:all

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

T_PsdkReturnCode PsdkGimbal_RegCommonHandler(const T_PsdkGimbalCommonHandler *commonHandler);

参数
commonHandler:指向回调函数
返回值
返回执行结果