X-Port 控制

2021-02-02

PSDK X-Port 控制相关功能的头文件为psdk_xport.h,本文档描述了psdk_xport.h 文件中结构体和函数原型的关键信息和使用方法。

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

目录

枚举、数据结构和宏定义

typedef enum E_PsdkXPortLimitAngleCategory

X-Port 角度限制类型

typedef enum {
PSDK_XPORT_LIMIT_ANGLE_CATEGORY_ROLL_JOINT_ANGLE = 0, 横滚轴关节角限制
PSDK_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_JOINT_ANGLE = 1, 俯仰轴关节角限制
PSDK_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE = 2, 俯仰轴欧拉角限制(在大地坐标系下)
PSDK_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE_EXTENSION = 3, 扩展俯仰轴欧拉角限制(在大地坐标系下),使用该功能时,请开启扩展俯仰轴角度限制功能
PSDK_XPORT_LIMIT_ANGLE_CATEGORY_YAW_JOINT_ANGLE = 4, 偏航轴关节角限制
} E_PsdkXPortLimitAngleCategory;

typedef struct

角度限制的数据结构

typedef struct {
int16_t upperLimit; 角度限制上限,单位:0.1
int16_t lowerLimit; 角度限制下限,单位:0.1
} T_PsdkXPortLimitAngle;

typedef function ReceiveXPortSystemStateCallback

接收X-Port 系统状态的回调函数

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

typedef T_PsdkReturnCode (*ReceiveXPortSystemStateCallback)(T_PsdkGimbalSystemState systemState);

参数
systemState:X-Port 系统的状态
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

typedef function ReceiveXPortAttitudeInformationCallback

接收X-Port 姿态角的回调函数

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

typedef T_PsdkReturnCode (*ReceiveXPortAttitudeInformationCallback)(
T_PsdkGimbalAttitudeInformation attitudeInformation);

参数
attitudeInformation:X-Port 的姿态角
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

函数原型

function PsdkXPort_Init

功能:X-Port 初始化 product:all

在使用X-Port 前请调用X-Port 初始化接口初始化X-Port。

T_PsdkReturnCode PsdkXPort_Init(void);

返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_DeInit

功能:释放X-Port 模块 product:all

释放X-Port 模块。

T_PsdkReturnCode PsdkXPort_DeInit(void);

返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_RegReceiveSystemStateCallback

功能:接收X-Port 状态 product:all

注册接收X-Port 状态的回调函数。

说明: 注册后,回调函数将会被自动调用,调用频率为1Hz

T_PsdkReturnCode PsdkXPort_RegReceiveSystemStateCallback(ReceiveXPortSystemStateCallback callback);

参数
callback:指向接收X-Port 状态的回调函数
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_RegReceiveAttitudeInformationCallback

功能:获取X-Port 姿态角 product:all

注册接收X-Port 姿态角的回调函数。

说明: 注册该回调函数后,该模块将会被自动调用,订阅频率为10Hz。

T_PsdkReturnCode PsdkXPort_RegReceiveAttitudeInformationCallback(ReceiveXPortAttitudeInformationCallback callback);

参数
callback:指向接收X-Port 姿态角的回调函数
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_SetGimbalModeSync

功能:设置X-Port 的模式 product:all

以阻塞的方式设置X-Port 的模式。

说明: 该接口执行的最大时间可能会大于600ms。

T_PsdkReturnCode PsdkXPort_SetGimbalModeSync(E_PsdkGimbalMode mode);

参数
mode:X-Port 的模式
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_RotateSync

功能:转动X-Port product:all

以阻塞的方式转动X-Port。

说明

  • 该接口执行的最大时间可能会大于600ms;
  • 在PSDK_GIMBAL_ROTATION_MODE_RELATIVE_ANGLE 或PSDK_GIMBAL_ROTATION_MODE_ABSOLUTE_ANGLE 模式下,偏航轴的转动范围为[-1800, 1800]。X-Port 转动角度的符号不决定X-Port 旋转的方向;
  • X-Port 可到达的角度主要受X-Port 转动角度的限制和限位缓冲区的影响;
  • X-Port 安装在无人机顶部时,可转动的角度范围与安装在无人机下置云台架上的范围可能会有较大的差异;
  • 当X-Port 超出限位角角度时,X-Port 将会返回错误值,或停留在限位缓冲区内;
  • X-Port 转动的速度和转动区间受最大转动速度和最大加速度的限制;X-Port 转动的最大加速度受云台转动平滑度的限制;X-Port 转动的最大速度受X-Port 默认最大速度(90°/s)和最大速度百分比的限制详情请参见:SetControllerSmoothFactor() 和 SetControllerMaxSpeedPercentage() ;
  • PSDK 仅支持开发者控制X-Port 的俯仰轴和偏航轴;
  • 为防止中断X-Port 的旋转,X-Port 在控制参数自动调整、同轴度检测过程、平衡检测和重置的过程中不会响应用户发送的旋转命令;
  • X-Port 的有效控制时间为500ms,若X-Port 在500ms 内未收到转动命令,X-Port 将无法转动。
T_PsdkReturnCode
PsdkXPort_RotateSync(E_PsdkGimbalRotationMode rotationMode, T_PsdkGimbalRotationProperty rotationProperty,
T_PsdkAttitude3d rotationValue);

参数
rotationMode:X-Port 的控制方式
rotationProperty:X-Port 旋转命令的属性
rotationValue:云台转动命令的值,当X-Port 的转动模式为 PSDK_GIMBAL_ROTATION_MODE_RELATIVE_ANGLE 或 PSDK_GIMBAL_ROTATION_MODE_ABSOLUTE_ANGLE 时,单位为0.1°;当X-Port 的转动模式为PSDK_GIMBAL_ROTATION_MODE_SPEED 时,单位为0.1°/s
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_ReleaseControlPermissionSync

功能:释放X-Port 的控制权限 product:all

以阻塞的方式释放X-Port 的控制权限。当基于PSDK 开发的应用程序控制X-Port 时将会获取X-Port 的控制权限,在发送完控制命令后,请调用该接口释放X-Port 的控制权限,使其他模块(如DJI Pilot 或遥控器) 控制X-Port。

说明

  • 该接口执行的时间可能会大于600ms;
  • 在参数自动调整、同轴度检测和平衡检测的过程中,不响应释放控制权限的命令。
T_PsdkReturnCode PsdkXPort_ReleaseControlPermissionSync(void);

返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_ResetSync

功能:X-Port 复位 product:all

以阻塞的方式控制X-Port 复位(大地坐标系)。

说明

  • 该接口执行的时间可能会大于600ms;
  • X-Port 在参数自动调整、同轴度检测和平衡检测的过程中,不响应复位的命令。
T_PsdkReturnCode PsdkXPort_ResetSync(E_PsdkGimbalResetMode mode);

参数
mode:云台重置项
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_SetLimitAngleSync

功能:设置X-Port 限位角 product:all

以阻塞的方式设置X-Port 限位角。

说明

  • 该接口执行的时间可能会大于1200ms;
  • X-Port 在参数自动调整、同轴度检测和平衡检测的过程中,不响应设置限位角的命令。
T_PsdkReturnCode
PsdkXPort_SetLimitAngleSync(E_PsdkXPortLimitAngleCategory limitAngleCategory, T_PsdkXPortLimitAngle limitAngle);

参数
limitAngleCategory:角度限制类别
limitAngle:限制角度
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_GetLimitAngleSync

功能:获取X-Port 的限位角 product:all

以阻塞的方式获取X-Port 的限位角,该接口执行的时间可能会大于1200ms。

T_PsdkReturnCode
PsdkXPort_GetLimitAngleSync(E_PsdkXPortLimitAngleCategory limitAngleCategory, T_PsdkXPortLimitAngle *limitAngle);

参数
limitAngleCategory:角度限制类别
limitAngle:指向用于存储限位角度的内存空间
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode

function PsdkXPort_SetSpeedConversionFactor

功能:设置X-Port 云台速度转换系数 product:all

从Joystick 和移动端APP 上在速度控制模式下设置X-Port 云台速度转换系数。
实际的运动速度 = Max_speed × Factor,Factor≤ 1,Factor:用户可根据实际的需要设置X-Port 的速度转换系数,推荐将速度转换系数设置为变焦倍数的倒数;Max_speed(X-Port 的最大速度)=默认最大速度(90°/s) × 最大速度百分比该参数将在100ms 内生效

T_PsdkReturnCode PsdkXPort_SetSpeedConversionFactor(float factor);

参数
factor:速度转换系数(≤1.0)
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode