Payload SDK

Gimbal Function

2022-08-23
4 Ratings
2 customers rated

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

NOTE The payload only developed based on the Skyport could use psdk_gimbal.h, if you use X-Port, please refer to psdk_xport.h.

Catalog

Enum

typedef enum E_PsdkGimbalMode

Gimbal work mode, specifies how gimbal follow aircraft movement

typedef enum {
    PSDK_GIMBAL_MODE_FREE = 0,             Free mode, fix gimbal attitude in the ground coordinate,   
                                           ignoring movement of aircraft. 
    PSDK_GIMBAL_MODE_FPV = 1,              FPV (First Person View) mode, only control roll and yaw 
                                           angle of gimbal in the ground coordinate to follow aircraft. 
    PSDK_GIMBAL_MODE_YAW_FOLLOW = 2,       Yaw follow mode, only control yaw angle of gimbal in the 
                                           ground coordinate to follow aircraft. 
} E_PsdkGimbalMode;

typedef enum E_PsdkGimbalCalibrationStage

Gimbal calibration stage and result

typedef enum {
    PSDK_GIMBAL_CALIBRATION_STAGE_COMPLETE = 0,          Calibration have been completed and the result is successful. 
    PSDK_GIMBAL_CALIBRATION_STAGE_PROCRESSING = 1,       Gimbal is calibrating.
    PSDK_GIMBAL_CALIBRATION_STAGE_FAILED = 3,            Calibration have been completed and the result is failure. 
} E_PsdkGimbalCalibrationStage;

typedef enum E_PsdkGimbalRotationMode

Gimbal rotation mode, specifies control style

typedef enum {
    PSDK_GIMBAL_ROTATION_MODE_RELATIVE_ANGLE = 0,       Relative angle rotation mode, represents rotating 
                                                        gimbal specified angles based on current angles. 
    PSDK_GIMBAL_ROTATION_MODE_ABSOLUTE_ANGLE = 1,       Absolute angle rotation mode, represents rotating 
                                                        gimbal to specified angles in the ground coordinate. 
    PSDK_GIMBAL_ROTATION_MODE_SPEED = 2,                Speed rotation mode, specifies rotation speed of 
                                                        gimbal in the ground coordinate. 
} E_PsdkGimbalRotationMode;

typedef enum E_PsdkGimbalRotationMode

Rotation mode, specified the control mode of the gimbal

typedef enum {
    PSDK_GIMBAL_AXIS_PITCH = 0,       Pitch axis. 
    PSDK_GIMBAL_AXIS_ROLL = 1,        Roll axis. 
    PSDK_GIMBAL_AXIS_YAW = 2,         Yaw axis. 
} E_PsdkGimbalAxis;

typedef enum E_PsdkGimbalResetMode

Reset mode of gimbal

typedef enum {
        PSDK_GIMBAL_RESET_MODE_YAW = 1,         Only reset yaw axis of gimbal. Reset angle 
                                                of yaw axis to the sum of yaw axis angle of
                                                aircraft and fine tune angle of yaw axis of gimbal.
        PSDK_GIMBAL_RESET_MODE_PITCH_AND_YAW = 3,           Reset yaw axis and pitch axis of gimbal. 
                                                            Reset angle of yaw axis to sum of yaw axis angle of aircraft and fine tune angle of yaw axis of gimbal, and reset pitch axis angle to the fine tune angle. 
        PSDK_GIMBAL_RESET_MODE_PITCH_DOWNWARD_UPWARD_AND_YAW = 11,       Reset yaw axis and pitch axis of
                                                                         gimbal. Reset angle of yaw axis to sum of yaw axis angle of aircraft and fine tune angle of yaw axis of gimbal, and reset pitch axis angle to sum of -90 degree and fine tune angle if gimbal downward, sum of 90 degree and fine tune angle if upward. 
    
        PSDK_GIMBAL_RESET_MODE_PITCH_DOWNWARD_UPWARD = 12,               Reset pitch axis of gimbal. Reset 
                                                                         pitch axis angle to sum of -90 degree and fine tune angle if gimbal downward, sum of 90 degree and fine tune angle if upward.
} E_PsdkGimbalResetMode;

Structure

typedef struct T_PsdkGimbalControllerSmoothFactor

Smooth factor of gimbal controller

typedef struct {
    uint8_t pitch;       Smooth factor of pitch axis, range from 0 to 30. 
    uint8_t yaw;         Smooth factor of yaw axis, range from 0 to 30. 
} T_PsdkGimbalControllerSmoothFactor;

typedef struct T_PsdkGimbalControllerMaxSpeedPercentage

Max speed percentage of every axis of gimbal

typedef struct {
    uint8_t pitch;       Max speed percentage of pitch axis, range from 1 to 100. 
    uint8_t yaw;         Max speed percentage of yaw axis, range from 1 to 100.
} T_PsdkGimbalControllerMaxSpeedPercentage;

typedef struct T_PsdkGimbalSystemState

Data structure describes gimbal system state

typedef struct {
    bool resettingFlag;        Specifies whether gimbal is resetting now or not. 
    bool mountedUpward;        Specifies whether gimbal is upward or not. 
    bool blockingFlag;         Specifies whether gimbal is stuck or not. 
    bool pitchRangeExtensionEnabledFlag;       Specifies whether extended angle range of gimbal pitch axis is enabled or not. 
    E_PsdkGimbalMode gimbalMode;          Gimbal mode. 
    T_PsdkAttitude3d fineTuneAngle;       Fine tune angles, unit: 0.1 degree. 
    T_PsdkGimbalControllerSmoothFactor smoothFactor;                   Smooth factor of gimbal controller. 
    T_PsdkGimbalControllerMaxSpeedPercentage maxSpeedPercentage;       Max speed percentage of gimbal controller. 
} T_PsdkGimbalSystemState;

typedef struct T_PsdkGimbalReachLimitFlag

Reach limit flag

typedef struct {
    bool pitch;       Specifies whether gimbal has reached angle limit of pitch axis, if true,
                      reached the limit. 
    bool roll;        Specifies whether gimbal has reached angle limit of roll axis, if true, 
                      reached the limit. 
    bool yaw;         Specifies whether gimbal has reached angle limit of yaw axis, if true, 
                      reached the limit. 
} T_PsdkGimbalReachLimitFlag;

typedef struct T_PsdkGimbalAttitudeInformation

Gimbal attitude related information

typedef struct {
    T_PsdkAttitude3d attitude;                     Gimbal attitude in the ground coordinate,
                                                   unit: 0.1 degree. 
    T_PsdkGimbalReachLimitFlag reachLimitFlag;     Reach limit flag, being set when the joint 
                                                   angles of gimbal reach limits. 
} T_PsdkGimbalAttitudeInformation;

typedef struct T_PsdkGimbalCalibrationState

Gimbal calibration state

typedef struct {
    bool calibratingFlag;                     Specifies whether gimbal is calibrating now or not. 
    bool lastCalibrationResult;               Result of the last calibration, and true specifies success. 
    uint8_t currentCalibrationProgress;       Progress percentage of current calibration. If gimbal is calibrating now and fill in real progress percentage, if not, fill in zero. The item ranges from 0 to 100. 
    E_PsdkGimbalCalibrationStage currentCalibrationStage;       Current calibration stage and result. If 
                                                                gimbal is calibrating now and fill in ::PSDK_GIMBAL_CALIBRATION_STAGE_PROCRESSING, if not, fill in result of the last calibration. 
} T_PsdkGimbalCalibrationState;

typedef struct T_PsdkGimbalRotationProperty

Gimbal rotation command property

typedef struct {
    struct {
        bool pitch;       Specifies whether ignore rotation command of pitch axis, and true specifies ignoring. 
        bool roll;        Specifies whether ignore rotation command of roll axis, and true specifies ignoring. 
        bool yaw;         Specifies whether ignore rotation command of yaw axis, and true specifies ignoring. 
    } rotationValueInvalidFlag;        Specifies whether ignore rotation command of some axis, including pitch, roll and yaw. 

    union {
        struct {
            uint16_t actionTime;        Action time during which gimbal move to target angles, unit: 0.01s. 
        } relativeAngleRotation;        Property of relative angle rotation command. 
        struct {
            uint16_t actionTime;        Action time during which gimbal move to target angles, unit: 0.01s.
            bool jointAngleValid;       Joint angle valid flag, specifying whether T_PsdkGimbalRotationProperty::absoluteAngleRotation::jointAngle is valid when absolute angle control
            T_PsdkAttitude3d jointAngle;    Joint angles of gimbal, unit: 0.1 degree. If T_PsdkGimbalRotationProperty::absoluteAngleRotation::jointAngleValid is false, specifying here joint angles are invalid, and please ignore the joint angles. If joint angles are valid, users should ensure that target joint angles of gimbal is approximately the same as the specified value
        } absoluteAngleRotation;       Property of absolute angle rotation command. 
    };
} T_PsdkGimbalRotationProperty;

typedef struct T_PsdkGimbalCommonHandler

Please construct the callback function of the gimbal:

  • Get the current status
  • Get the current angle
  • Get the calibration status
  • Get the rotation speed
  • Get the joint angle
  • Rotate the gimbal
  • Start to calibrate
  • Set the smoothness
  • Set the extension angle of Euler angle
  • Set maximum speed percentage
  • Restore information
  • Set gimbal mode
  • Reset the parameters
  • Fine adjustment of gimbal

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 struct {
         
    @brief Prototype of callback function used to report system state of gimbal.
    @param systemState: pointer to memory space used to store gimbal system state.
    @return Execution result.
    T_PsdkReturnCode (*GetSystemState)(T_PsdkGimbalSystemState *systemState);
         
    @brief Prototype of callback function used to report attitude information of gimbal.
    @param attitudeInformation: pointer to memory space used to store gimbal attitude information.
    @return Execution result.
    T_PsdkReturnCode (*GetAttitudeInformation)(T_PsdkGimbalAttitudeInformation *attitudeInformation);

    @brief Prototype of callback function used to report calibration state of gimbal.
    @param calibrationState: pointer to memory space used to store gimbal calibration state.
    @return Execution result.
    T_PsdkReturnCode (*GetCalibrationState)(T_PsdkGimbalCalibrationState *calibrationState);
         
    @brief Prototype of callback function used to rotate gimbal. Rotation callback function will be called when other modules control gimbal.
    @warning User should control execution time of the callback function to be short, because this callback function may be called at very high frequency in some scenarios, just like 200Hz.
    @param rotationMode: mode of rotation command.
    @param rotationProperty: property of rotation command.
    @param 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 Execution result.
     
    T_PsdkReturnCode (*Rotate)(E_PsdkGimbalRotationMode rotationMode, T_PsdkGimbalRotationProperty rotationProperty, T_PsdkAttitude3d rotationValue);
         
    @brief Prototype of callback function used to start calibrating gimbal.
    @note Maximum allowable time of gimbal calibration is 120s. If gimbal has not completed calibration during 120s, DJI Pilot believe calibration failed.
    @return Execution result.
    T_PsdkReturnCode (*StartCalibrate)(void);

    @brief Set smooth factor for gimbal controller, using to smooth control.
    @param smoothingFactor: smooth factor. The larger the value, the smaller the acceleration of gimbal. Recommended calculation formula is "acc = 10000 * (0.8 ^ (1 + x)) deg/s^2", x is smooth factor. Range from 0 to 30.
    @param axis: axis to be set.
    @return Execution result.
    T_PsdkReturnCode (*SetControllerSmoothFactor)(uint8_t smoothingFactor, E_PsdkGimbalAxis axis);
         
    @brief Prototype of callback function used to enable or disable extended pitch axis angle range.
    @details Switching the gimbal limit euler angle of pitch axis to the extended limit angle or the default limit angle.
    @param enabledFlag: flag specified whether enable or disable extended pitch axis angle range.
    @return Execution result.
    T_PsdkReturnCode (*SetPitchRangeExtensionEnabled)(bool enabledFlag);

    @brief Set max speed percentage for gimbal controller.
    @param maxSpeedPercentage: max speed value. Recommended calculation formula is "spd = default_max_spd * x / 100", x is default max speed value. Range from 1 to 100.
    @param axis: axis to be set.
    @return Execution result.     
    T_PsdkReturnCode (*SetControllerMaxSpeedPercentage)(uint8_t maxSpeedPercentage, E_PsdkGimbalAxis axis);

    @brief Restore factory settings of gimbal, including fine tune angle, pitch angle extension enable flag and max speed etc.
    @return Execution result.
    T_PsdkReturnCode (*RestoreFactorySettings)(void);
         
    @brief Prototype of callback function used to set gimbal work mode.
    @param mode: gimbal work mode.
    @return Execution result.
    T_PsdkReturnCode (*SetMode)(E_PsdkGimbalMode mode);
         
    @brief Prototype of callback function used to reset gimbal.
    @note Reset command will interrupt rotation process.
    @param mode: Reset mode.
    @return Execution result.     
    T_PsdkReturnCode (*Reset)(E_PsdkGimbalResetMode mode);
         
    @brief Prototype of callback function used to fine tune angle of gimbal.
    @param fineTuneAngle: fine tune angle, unit: 0.1 degree. Angle value of greater than 0 specifies rotation towards the positive direction of body coordinate.
    @return Execution result.
    T_PsdkReturnCode (*FineTuneAngle)(T_PsdkAttitude3d fineTuneAngle);

    @brief Prototype of callback function used to report rotation speed of gimbal.
    @note The callback function will be called at 50 Hz. Developers should ensure that, the average rotation speed of   gimbal within 20 ms after the callback function is called is approximately equal to the reported rotation speed.
    @param rotationSpeed: pointer to memory space used to store rotation speed, in body coordinate, unit: 0.1 degree/s.
    @return Execution result.
    T_PsdkReturnCode (*GetRotationSpeed)(T_PsdkAttitude3d *rotationSpeed);

    @brief Prototype of callback function used to report joint angle of gimbal.
    @param jointAngle: pointer to memory space used to store joint angles, unit: 0.1 degree.
    @return Execution result.
    T_PsdkReturnCode (*GetJointAngle)(T_PsdkAttitude3d *jointAngle);
} T_PsdkGimbalCommonHandler;

Function

function PsdkGimbal_Init

Function:Initialise gimbal module product:all

Initialise gimbal module, and user should call this function before using gimbal features.

T_PsdkReturnCode PsdkGimbal_Init(void);


Return

The details for the return code please refer to：PsdkErrorCode

function PsdkGimbal_DeInit

Function: De-initialize gimbal module product:all
T_PsdkReturnCode PsdkGimbal_DeInit(void);


Return

The details for the return code please refer to：PsdkErrorCode

function PsdkGimbal_RegCommonHandler

Function:Register common handler functions/callback functions of gimbal product:all

Register common handler functions/callback functions of gimbal. After registering, callback functions will be called automatically.

T_PsdkReturnCode PsdkGimbal_RegCommonHandler(const T_PsdkGimbalCommonHandler *commonHandler);
Parameter
commonHandler：pointer to common handler functions of gimbal.
Return
The details for the return code please refer to：PsdkErrorCode
Last Updated: 8/23/2022, 8:30:21 AM
How was your reading experience of our documentation?
If you have any comments or confusion about our documentation, you can click here to give feedback and we will get back to you as soon as possible.