X-port 控制
X-Port 控制相关功能的头文件为dji_xport.h
,本文档描述了dji_xport.h
文件中结构体和函数原型的关键信息和使用方法。
说明: 仅使用X-Port 开发的负载设备可使用
dji_xport.h
,若使用SkyPort 开发负载设备,请使用dji_gimbal.h。
目录
宏定义、枚举与结构体
E_DjiXPortLimitAngleCategory
T_DjiXPortLimitAngle
DjiReceiveXPortSystemStateCallback
DjiReceiveXPortAttitudeInformationCallback函数原型
DjiXPort_Init
DjiXPort_DeInit
DjiXPort_RegReceiveSystemStateCallback
DjiXPort_RegReceiveAttitudeInformationCallback
DjiXPort_SetGimbalModeSync
DjiXPort_RotateSync
DjiXPort_ReleaseControlPermissionSync
DjiXPort_ResetSync
DjiXPort_SetLimitAngleSync
DjiXPort_GetLimitAngleSync
DjiXPort_SetSpeedConversionFactor
宏定义、枚举与结构体
typedef enum E_DjiXPortLimitAngleCategory
X-Port 角度限制类型
typedef enum {
DJI_XPORT_LIMIT_ANGLE_CATEGORY_ROLL_JOINT_ANGLE = 0, 横滚轴关节角限制
DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_JOINT_ANGLE = 1, 俯仰轴关节角限制
DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE = 2, 俯仰轴欧拉角限制(在大地坐标系下)
DJI_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE_EXTENSION = 3, 扩展俯仰轴欧拉角限制(在大地坐标系下),使用该功能时,请开启扩展俯仰轴角度限制功能
DJI_XPORT_LIMIT_ANGLE_CATEGORY_YAW_JOINT_ANGLE = 4, 偏航轴关节角限制
} E_DjiXPortLimitAngleCategory;
typedef struct T_DjiXPortLimitAngle
角度限制的数据结构
typedef struct {
int16_t upperLimit; 角度限制上限,单位:0.1 度
int16_t lowerLimit; 角度限制下限,单位:0.1 度
} T_DjiXPortLimitAngle;
typedef function DjiReceiveXPortSystemStateCallback
接收X-Port 系统状态的回调函数
说明: 为防止该函数阻塞PSDK 的主线程,导致出现程序响应缓慢、相机类负载设备断连及死循环等问题,请勿以阻塞的方式在回调函数中执行该函数。
typedef T_DjiReturnCode (*DjiReceiveXPortSystemStateCallback)(T_DjiGimbalSystemState systemState);
systemState:X-Port 系统的状态
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
typedef function DjiReceiveXPortAttitudeInformationCallback
接收X-Port 姿态角的回调函数
说明: 为防止该函数阻塞PSDK 的主线程,导致出现程序响应缓慢、相机类负载设备断连及死循环等问题,请勿以阻塞的方式在回调函数中执行该函数。
typedef T_DjiReturnCode (*DjiReceiveXPortAttitudeInformationCallback)(
T_DjiGimbalAttitudeInformation attitudeInformation);
attitudeInformation:X-Port 的姿态角
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
函数原型
function DjiXPort_Init
功能:X-Port 初始化 | product:all |
在使用X-Port 前请调用X-Port 初始化接口初始化X-Port。
T_DjiReturnCode DjiXPort_Init(void);
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_DeInit
功能:释放X-Port 模块 | product:all |
释放X-Port 模块。
T_DjiReturnCode DjiXPort_DeInit(void);
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_RegReceiveSystemStateCallback
功能:接收X-Port 状态 | product:all |
注册接收X-Port 状态的回调函数。
说明: 注册后,回调函数将会被自动调用,调用频率为1Hz
T_DjiReturnCode DjiXPort_RegReceiveSystemStateCallback(DjiReceiveXPortSystemStateCallback callback);
callback:指向接收X-Port 状态的回调函数
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_RegReceiveAttitudeInformationCallback
功能:获取X-Port 姿态角 | product:all |
注册接收X-Port 姿态角的回调函数。
说明: 注册该回调函数后,该模块将会被自动调用,订阅频率为10Hz。
T_DjiReturnCode DjiXPort_RegReceiveAttitudeInformationCallback(DjiReceiveXPortAttitudeInformationCallback callback);
callback:指向接收X-Port 姿态角的回调函数
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_SetGimbalModeSync
功能:设置X-Port 的模式 | product:all |
以阻塞的方式设置X-Port 的模式。
说明: 该接口执行的最大时间可能会大于600ms。
T_DjiReturnCode DjiXPort_SetGimbalModeSync(E_DjiGimbalMode mode);
mode:云台模式
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_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_DjiReturnCode DjiXPort_RotateSync(E_DjiGimbalRotationMode rotationMode,
T_DjiGimbalRotationProperty rotationProperty, T_DjiAttitude3d 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
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_ReleaseControlPermissionSync
功能:释放X-Port 的控制权限 | product:all |
以阻塞的方式释放X-Port 的控制权限。当基于PSDK 开发的应用程序控制X-Port 时将会获取X-Port 的控制权限,在发送完控制命令后,请调用该接口释放X-Port 的控制权限,使其他模块(如DJI Pilot 或遥控器) 控制X-Port。
说明
- 该接口执行的时间可能会大于600ms;
- 在参数自动调整、同轴度检测和平衡检测的过程中,不响应释放控制权限的命令。
T_DjiReturnCode DjiXPort_ReleaseControlPermissionSync(void);
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_ResetSync
功能:X-Port 复位 | product:all |
以阻塞的方式控制X-Port 复位(大地坐标系)。
说明
- 该接口执行的时间可能会大于600ms;
- X-Port 在参数自动调整、同轴度检测和平衡检测的过程中,不响应复位的命令。
T_DjiReturnCode DjiXPort_ResetSync(E_DjiGimbalResetMode mode);
mode:云台重置项
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_SetLimitAngleSync
功能:设置X-Port 限位角 | product:all |
以阻塞的方式设置X-Port 限位角。
说明
- 该接口执行的时间可能会大于1200ms;
- X-Port 在参数自动调整、同轴度检测和平衡检测的过程中,不响应设置限位角的命令。
T_DjiReturnCode DjiXPort_SetLimitAngleSync(E_DjiXPortLimitAngleCategory limitAngleCategory,
T_DjiXPortLimitAngle limitAngle);
limitAngleCategory:角度限制类别
limitAngle:限制角度
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_GetLimitAngleSync
功能:获取X-Port 的限位角 | product:all |
以阻塞的方式获取X-Port 的限位角,该接口执行的时间可能会大于1200ms。
T_DjiReturnCode DjiXPort_GetLimitAngleSync(E_DjiXPortLimitAngleCategory limitAngleCategory,
T_DjiXPortLimitAngle *limitAngle);
limitAngleCategory:角度限制类别
limitAngle:指向用于存储限位角度的内存空间
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode
function DjiXPort_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_DjiReturnCode DjiXPort_SetSpeedConversionFactor(float factor);
factor:速度转换系数(≤1.0)
返回值
根据程序执行的情况输出对应的返回值,详情请参见:DjiErrorCode