This is the header file for "psdk_xport.c", defining the structure and (exported) function prototypes.

NOTE Only payload which developrd based on the X-Port could use psdk_xport.h，for SkyPort please use psdk_gimbal.h

Catalog

• Structure
  E_PsdkXPortLimitAngleCategory
  T_PsdkXPortLimitAngle
  ReceiveXPortSystemStateCallback
  ReceiveXPortAttitudeInformationCallback

• Function
  PsdkXPort_Init
  PsdkXPort_DeInit
  PsdkXPort_RegReceiveSystemStateCallback
  PsdkXPort_RegReceiveAttitudeInformationCallback
  PsdkXPort_SetGimbalModeSync
  PsdkXPort_RotateSync
  PsdkXPort_ReleaseControlPermissionSync
  PsdkXPort_ResetSync
  PsdkXPort_SetLimitAngleSync
  PsdkXPort_GetLimitAngleSync
  PsdkXPort_SetSpeedConversionFactor

Enum Structure and Define

typedef enum E_PsdkXPortLimitAngleCategory

X-Port limit angle category

typedef enum {
    PSDK_XPORT_LIMIT_ANGLE_CATEGORY_ROLL_JOINT_ANGLE = 0,        Joint angle limit of roll axis. 
    PSDK_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_JOINT_ANGLE = 1,       Joint angle limit of pitch axis. 
    PSDK_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE = 2,       Euler angle limit of pitch axis, just is limitation of angle in ground coordinate. 
   PSDK_XPORT_LIMIT_ANGLE_CATEGORY_PITCH_EULER_ANGLE_EXTENSION = 3,    Extended euler angle limit of pitch axis, just is limitation of angle in ground coordinate. Extended euler angle limit is activated when enable extended pitch axis angle limit. 
    PSDK_XPORT_LIMIT_ANGLE_CATEGORY_YAW_JOINT_ANGLE = 4,         Joint angle limit of yaw axis. 
} E_PsdkXPortLimitAngleCategory;

typedef struct

Limit angle data structure

typedef struct {
    int16_t upperLimit;        Upper limit of limit angle, unit: 0.1degree. 
    int16_t lowerLimit;        Lower limit of limit angle, unit: 0.1degree. 
} T_PsdkXPortLimitAngle;

typedef function ReceiveXPortSystemStateCallback

Prototype of callback function used to receive system state of X-Port

NOTE Developer can not execute blocking style operations or functions in callback function, because that will block PSDK root thread, causing problems such as slow system response, payload disconnection or infinite loop.

typedef T_PsdkReturnCode (*ReceiveXPortSystemStateCallback)(T_PsdkGimbalSystemState systemState);

Parameter
systemState：ystem state of X-Port.
Return
The details for the return code please refer to：PsdkErrorCode

typedef function ReceiveXPortAttitudeInformationCallback

Prototype of callback function used to receive attitude information of X-Port

NOTE Developer can not execute blocking style operations or functions in callback function, because that will block PSDK root thread, causing problems such as slow system response, payload disconnection or infinite loop.

typedef T_PsdkReturnCode (*ReceiveXPortAttitudeInformationCallback)(
    T_PsdkGimbalAttitudeInformation attitudeInformation);

Parameter
attitudeInformation： attitude information of X-Port.
Return
The details for the return code please refer to：PsdkErrorCode

Function

function PsdkXPort_Init

Function:Initialise X-Port module

product：all

Initialise X-Port module.

NOTE The function have to be called before other functions related to X-Port.

T_PsdkReturnCode PsdkXPort_Init(void);

Return

The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_DeInit

Function:Deinitialize X-Port module.

product：all

Deinitialize X-Port module.

T_PsdkReturnCode PsdkXPort_DeInit(void);

Return

The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_RegReceiveSystemStateCallback

Function:Receive system state of X-Port.

product：all

Register callback function used to receive system state of X-Port.

NOTE The callback function will be called after registering. The call frequency is 1Hz.

T_PsdkReturnCode PsdkXPort_RegReceiveSystemStateCallback(ReceiveXPortSystemStateCallback callback);

Parameter
callback：pointer to the callback function.
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_RegReceiveAttitudeInformationCallback

Function:Receive attitude information of X-Port

product：all

Register callback function used to receive attitude information of X-Port.

NOTE The callback function will be called after registering. The call frequency is 10Hz.

T_PsdkReturnCode PsdkXPort_RegReceiveAttitudeInformationCallback(ReceiveXPortAttitudeInformationCallback callback);

Parameter
callback：pointer to the callback function
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_SetGimbalModeSync

Function:Set gimbal mode of X-Port

product：all

Set gimbal mode of X-Port in blocking mode.

NOTE Max execution time of this function is slightly larger than 600ms.

T_PsdkReturnCode PsdkXPort_SetGimbalModeSync(E_PsdkGimbalMode mode);

Parameter
mode：X-Port's mode
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_RotateSync

Function:Rotate gimbal of X-Port

product：all

Rotate gimbal of X-Port in blocking mode.

NOTE

• Max execution time of this function is slightly larger than 600ms.
• If rotation mode is ::PSDK_GIMBAL_ROTATION_MODE_RELATIVE_ANGLE or ::PSDK_GIMBAL_ROTATION_MODE_ABSOLUTE_ANGLE, range of yaw value in rotation value argument is [-1800, 1800]. Gimbal can rotate to any angle of yaw axis by the range.Symbol of yaw value does not determine the rotation direction of the gimbal.
• X-Port Attitude that gimbal can reach is also determined by angle limitation and angle limitation buffer of the gimbal.
• When the gimbal is upward, angle limitation differs from limitation users set. For angle limitation and angle limitation buffer, please refer to PSDK documentation for details.
• If gimbal attitude is within range limitation buffer and control gimbal move towards limit direction still, or gimbal attitude is outside the angle limitation buffer but control gimbal to the range limitation buffer, the gimbal will return an error. For the former case, the gimbal will not move. In the latter case, the gimbal will try to move towards the direction of angle limit but it will stop at somewhere in angle limitation buffer.
• Rotation speed and rotation duration are also limited by the maximum speed of gimbal and maximum acceleration. The maximum acceleration is determined by the smooth factor of the gimbal controller set by APP. The maximum speed is determined by default maximum speed and maximum speed percentage set by APP, and the default maximum speed of X-Port is 90degree/s. For the detailed relationship, please refer to SetControllerSmoothFactor() and SetControllerMaxSpeedPercentage() callback function prototype in psdk_gimbal.h file.
• PSDK Only pitch and yaw axis of X-Port is controllable.
• X-Port do not response rotation command in process of control parameters auto-tuning, coaxiality detection, balance detection and resetting. And these operations will interrupt rotation of X-Port.
• Effective time of a speed control command is 500ms, that is, if X-Port do not receive other control commands within 500ms after speed control, X-Port will stop rotation.

T_PsdkReturnCode
PsdkXPort_RotateSync(E_PsdkGimbalRotationMode rotationMode, T_PsdkGimbalRotationProperty rotationProperty,
                     T_PsdkAttitude3d rotationValue);

Parameter
rotationMode：mode of rotation command.
rotationProperty：property of rotation command.
rotationValue：value of rotation command, unit: 0.1 degree (if rotation mode is PSDK_GIMBAL_ROTATION_MODE_RELATIVE_ANGLE or PSDK_GIMBAL_ROTATION_MODE_ABSOLUTE_ANGLE), 0.1 degree/s (if rotation mode is PSDK_GIMBAL_ROTATION_MODE_SPEED).
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_ReleaseControlPermissionSync

Function:Release gimbal control permission

product：all

Release gimbal control permission out in blocking mode.
When PSDK application control X-Port gimbal, PSDK application will capture and gain control permission of gimbal if allowable. After PSDK application sending a sequence of the gimbal control command, PSDK application should call this interface to release control permission of gimbal, to allow other modules (like APP, flight controller) can control gimbal right now. For example, PSDK application can release control permission after tap zooming. Of course, if PSDK application does not release control permission after controlling gimbal, the gimbal will also release control permission automatically at some time point later than the completion of control commands. Undoubtedly, this is inefficient.

T_PsdkReturnCode PsdkXPort_ReleaseControlPermissionSync(void);

Return

The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_ResetSync

Function:Reset gimbal of X-Port

product：all

The interface reset angle of pitch axis to corresponding fine tune value in ground coordinate, and yaw axis to superimposed value of yaw axis angle of aircraft and corresponding fine tune value in ground coordinate.

NOTE

• Max execution time of this function is slightly larger than 600ms.
• X-Port do not response reset command in process of control parameters auto-tuning, coaxiality detection and balance detection.

T_PsdkReturnCode PsdkXPort_ResetSync(E_PsdkGimbalResetMode mode);

Parameter
mode：Reset mode
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_SetLimitAngleSync

Function:Set limit angle for X-Port

product：all

Set limit angle for X-Port in blocking mode.

NOTE Max execution time of this function is slightly larger than 1200ms.X-Port do not response set limit angle command in process of control parameters auto-tuning, coaxiality detection and balance detection.

T_PsdkReturnCode
PsdkXPort_SetLimitAngleSync(E_PsdkXPortLimitAngleCategory limitAngleCategory, T_PsdkXPortLimitAngle limitAngle);

Parameter
limitAngleCategory： limit angle category.
limitAngle：limit angle.
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_GetLimitAngleSync

Function:Get limit angle of X-Port

product：all

Get limit angle of X-Port in blocking mode.

NOTE Max execution time of this function is slightly larger than 1200ms.

T_PsdkReturnCode
PsdkXPort_GetLimitAngleSync(E_PsdkXPortLimitAngleCategory limitAngleCategory, T_PsdkXPortLimitAngle *limitAngle);

Parameter
limitAngleCategory：limit angle category.
limitAngle：pointer to memory space used to store limit angle.
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkXPort_SetSpeedConversionFactor

Function:Set speed conversion factor

product：all

Set speed conversion factor for speed control from joystick and APP. X-Port convert speed control command from joystick and APP to rotation speed based on the speed conversion factor. The formula is "speed = maximum rotation speed × conversion factor", and maximum rotation speed is a product of default maximum speed and maximum speed percentage. The default maximum rotation speed is 90degree/s. The maximum speed percentage is set by APP. The default speed conversion factor is 1.0.

NOTE The value will be effective after a while, and the max value is 100ms.

T_PsdkReturnCode PsdkXPort_SetSpeedConversionFactor(float factor);

Parameter
factor：Speed conversion factor and it has to be smaller than or equal to 1.0.
Return
The details for the return code please refer to：PsdkErrorCode