云台功能

概述

使用 PSDK 的“云台控制”功能，开发者需要先设计负载设备的云台并开发出控制云台的程序，将云台的控制函数注册到 PSDK 指定的接口后，基于 MSDK 开发的移动端 App 及遥控器即可控制基于 PSDK 开发的具有云台功能的负载设备，同时获得负载设备的相关信息，如姿态等。

基础概念

云台状态信息

使用 PSDK 开发的云台类负载设备需要按照指定的要求上报云台的状态、当前姿态和校准状态等信息，方便用户移动端 App 或机载计算机根据云台的状态，实现精准控制。

云台关节与云台关节角

云台的关节如图所示，云台关节是云台上带动负载设备转动的结构件：云台电机，云台关节角即云台电机转动的角度。本教程使用机体坐标系描述云台的关节角。

云台姿态与云台姿态角

云台的姿态如图所示，根据用户的控制指令，云台能够调整姿态；云台姿态角即使用大地坐标系（NED，北东地坐标系）描述云台上负载设备的角度，该角度也称为欧拉角。

云台模式

云台模式决定了云台跟随无人机运动时的转动方式：

• 自由模式：当无人机的姿态改变时，云台将不会转动。
• FPV 模式：当无人机的姿态发生改变时，云台会转动航向轴与横滚轴，确保负载设备当前的视场角不会发生改变。
• YAW 跟随模式：在该模式下，云台的航向轴会跟随无人机的航向轴转动。

说明：

• 在以上三种模式下，无人机系统中的其他模块（航线飞行时的云台控制指令）、遥控器和移动端App，能够控制云台转动。

平滑度

云台的平滑度是指云台响应动作的缓急，使用 PSDK 开发的云台支持用户通过 MSDK 开发的移动端 App 通过设置平滑控制系数，实现云台的缓启停。

• 平滑控制系数：平滑控制系数决定云台转动的最大加速度。
• 云台转动的最大加速度= 10000 × (0.8 ^ (1 + X)) deg/s^2 (X 为平滑控制系数)

最大速度百分比

• 最大速度百分比：云台的最大速度百分比决定云台旋转的最大速度。
• 云台实际最大的转动速度= 默认最大速度 × 最大速度百分比

说明：

• 开发者根据实际的使用需要，可设置云台默认的最大云台转动运动速度。

角度微调

使用 PSDK 开发的云台支持用户通过 MSDK 开发的移动端 App，精细化地调整云台关节角的角度，调整结果还可作为校准参数存储在负载设备中，用于降低云台的各类误差。

云台限位功能

为避免云台在工作时，因结构干涉导致云台意外损坏或干扰无人机的执行飞行任务，请务必为云台设置机械限位和软件限位。

• 机械限位：机械限位由云台类负载设备的物理形态和设计结构决定，详情请参见标准声明。
• 软件限位：开发者可根据实际的使用需求设置软件限位：
  • 设置云台俯仰轴、横滚轴和航向轴的欧拉角角度限制；
  • 设置俯仰轴欧拉角扩展角角度限制；
  • 设置云台关节角限制。

提示：

• 使用俯仰轴角度范围扩展功能后，可将云台俯仰轴的欧拉角角度限制设置为默认限制或扩展限制。
• 当云台的关节角达到限位时，使用 MSDK 开发的移动端 App 将接收到云台转动到限位角的提示信息。

云台复位

使用 PSDK 开发的云台类负载设备支持用户通过 MSDK 开发的移动端 App 复位云台，将云台的姿态复位为初始状态。

• 航向轴复位：将云台航向轴的角度复位为无人机航向轴角度与云台航向轴微调角度的和。
• 俯仰轴与航向轴复位：将云台俯仰轴的角度复位为微调的角度，将云台航向轴的角度复位为无人机航向轴角度与云台航向轴微调角度的和。
• 重置云台的偏航轴和俯仰轴：将云台偏航轴的角度重置为无人机偏航轴和云台微调角度的和。重置云台俯仰轴为 -90° 与云台微调角度的和（云台下置），90° 与云台微调角度的和（云台上置）。
• 重置云台的偏航轴为 -90° 与云台微调角度的和（云台下置），90° 与云台微调角度的和（云台上置）。

实现云台功能

请开发者根据选用的开发平台以及行业应用实际的使用需求，按照 PSDK 中的结构体 T_UavGimbalCommonHandler 构造实现云台类负载设备控制功能的函数，将云台控制功能的函数注册到 PSDK 中指定的接口后，用户通过使用 MSDK 开发的移动端 App 能够控制基于 PSDK 开发的云台类负载设备执行指定的动作。

    s_commonHandler.GetSystemState = GetSystemState;
    s_commonHandler.GetAttitudeInformation = GetAttitudeInformation;
    s_commonHandler.GetCalibrationState = GetCalibrationState;
    s_commonHandler.GetRotationSpeed = GetRotationSpeed;
    s_commonHandler.GetJointAngle = GetJointAngle;

    s_commonHandler.Rotate = UavTest_GimbalRotate;
    s_commonHandler.StartCalibrate = StartCalibrate;
    s_commonHandler.SetControllerSmoothFactor = SetControllerSmoothFactor;
    s_commonHandler.SetPitchRangeExtensionEnabled = SetPitchRangeExtensionEnabled;
    s_commonHandler.SetControllerMaxSpeedPercentage = SetControllerMaxSpeedPercentage;
    s_commonHandler.RestoreFactorySettings = RestoreFactorySettings;
    s_commonHandler.SetMode = SetMode;
    s_commonHandler.Reset = Reset;
    s_commonHandler.FineTuneAngle = FineTuneAngle;

使用云台功能

用云台控制功能，需要先实现云台控制功能，再实现云台限位功能，根据云台模式调整云台的姿态、目标角度和限位标志，最后实现云台校准功能校准云台。

使用云台管理功能

1. 云台控制功能模块初始化

使用“云台控制”功能前，需要先初始化云台控制功能模块，确保云台控制功能可正常运行。

if(UAV_ERROR_SYSTEM_MODULE_CODE_SUCCESS != UavGimbal_Init) {
    printf("UavGimbal_Init failed\n");
    return;
}

2. 注册云台控制功能

使用 PSDK 的云台控制功能控制云台类负载设备时，开发者需要将控制云台的函数注册到指定的接口中。

if(UAV_ERROR_SYSTEM_MODULE_CODE_SUCCESS != UavGimbal_RegCommonHandler(&s_commonHandler)) {
    printf("UavGimbal_RegCommonHandler failed\n");
    return;
}

3. 构造回调函数计算云台的转动速度

构造回调函数计算云台的转动速度、调整云台的姿态并记录云台转动的目标角度和转动速度。

T_UAVReturnCode UavTest_GimbalRotate(E_UAVGimbalRotationMode rotationMode, T_UavGimbalRotationProperty rotationProperty,
                              T_UAVAttitude3d rotationValue)
{
    /// do gimbal rotate
}

5. 控制云台转动

负载设备根据云台的姿态和转动速度，将相对角度控制量、绝对角度控制量或速度控制量转换为控制云台转动的速度，根据该速度控制云台转动。

调整云台处于不同模式时的参数

开发者能够根据实际的使用需求调整云台处于不同模式时的姿态、目标角度和到达限位标志。

• 在FPV 模式下：
  • 调整云台姿态：将无人机姿态的变化量叠加到云台的横滚轴和航向轴上；
  • 调整云台转动的目标角度：云台旋转时，将无人机的姿态变化量叠加到云台的横滚轴和航向轴上。
• 在YAW 模式下：
  • 调整云台姿态：将无人机姿态的变化量叠加到云台的航向轴上；
  • 调整云台转动的目标角度：云台旋转时，将无人机的姿态变化量叠加到云台的航向轴上。
• 调整云台姿态与目标角度的转动范围，负载设备能够计算出云台的达到限位标志。

使用云台校准功能

如需使用云台校准功能，请先实现云台校准功能，并将云台校准功能的函数，注册到指定的接口中，方便用户使用 MSDK 开发的移动端 App 校准具有云台功能的负载设备。

云台校准状态更新

负载设备执行云台校准功能后，将记录云台的校准状态，基于 MSDK 开发的移动端 App 能够获取云台的校准状态。

基于 MSDK 开发的移动端 App 中使用“云台自动校准”功能后，使用 PSDK 开发的负载设备将接收到云台校准命令并校准云台，