Gimbal

public protocol Gimbal : Peripheral

The gimbal is the peripheral holding and orientating the camera. It can be a real mechanical gimbal, or a software one.

The gimbal can act on one or multiple axes. It can stabilize a given axis, meaning that the movement on this axis will be following the horizon (for .roll and .pitch) or the North (for the .yaw).

This peripheral can be retrieved by:

device.getPeripheral(Peripherals.gimbal)
  • Set of supported axes, i.e. axis that can be controlled.

    Declaration

    Swift

    var supportedAxes: Set<GimbalAxis> { get }
  • Set of current errors.

    When empty, the gimbal can be operated normally, otherwise, it is currently inoperable. In case the returned set contains the .critical error, then gimbal has become completely inoperable until both all other reported errors are fixed and the device is restarted.

    Declaration

    Swift

    var currentErrors: Set<GimbalError> { get }
  • Set of currently locked axes. While an axis is locked, you cannot set a speed or a position.

    An axis can be locked because the drone is controlling this axis on itself, thus it does not allow the controller to change its orientation. This might be the case during a FollowMe or when the PointOfInterestPilotingItf is active.

    Only contains supported axes.

    Declaration

    Swift

    var lockedAxes: Set<GimbalAxis> { get }
  • Bounds of the attitude by axis. Only contains supported axes.

    Declaration

    Swift

    var attitudeBounds: [GimbalAxis : Range<Double>] { get }
  • Max speed by axis. Only contains supported axes.

    Declaration

    Swift

    var maxSpeedSettings: [GimbalAxis : DoubleSetting] { get }
  • Whether the axis is stabilized. Only contains supported axes.

    Declaration

    Swift

    var stabilizationSettings: [GimbalAxis : BoolSetting] { get }
  • Current gimbal attitude. Empty when not connected.

    Declaration

    Swift

    var currentAttitude: [GimbalAxis : Double] { get }
  • Offset correction process. Not nil when offset correction is started (see startOffsetsCorrectionProcess() and stopOffsetsCorrectionProcess()).

    Declaration

    Swift

    var offsetsCorrectionProcess: GimbalOffsetsCorrectionProcess? { get }
  • Whether the gimbal is calibrated.

    Declaration

    Swift

    var calibrated: Bool { get }
  • Calibration process state. See startCalibration() and cancelCalibration()

    Declaration

    Swift

    var calibrationProcessState: GimbalCalibrationProcessState { get }
  • Controls the gimbal.

    Unit of the yaw, pitch, roll values depends on the value of the mode parameter:

    • .position: axis value is in degrees and represents the desired position of the gimbal on the given axis.
    • .velocity: axis value is in max speed (maxSpeedSettings[thisAxis].value) ratio (from -1 to 1).

    If mode is .position, frame of reference of a given axis depends on the value of the stabilization on this axis. If this axis is stabilized (i.e. stabilizationSettings[thisAxis].value == true, here are the frame of references:

    • yaw: given angle is relative to the magnetic North (clockwise).
    • pitch: given angle is relative to the horizon. Positive pitch values means an orientation towards sky.
    • roll: given angle is relative to the horizon line. Positive roll values means an orientation to the right when seeing the gimbal from behind.

    However, if the axis is not stabilized:

    • yaw: given angle is relative to the heading of the drone. Positive yaw values means a right orientation when seeing the gimbal from above.
    • pitch: given angle is relative to the body of the drone. Positive pitch values means an orientation of the gimbal towards the top of the drone.
    • roll: given angle is relative to the body of the drone. Positive roll values means an clockwise rotation of the gimbal.

    Declaration

    Swift

    func control(mode: GimbalControlMode, yaw: Double?, pitch: Double?, roll: Double?)

    Parameters

    mode

    the mode that should be used to move the gimbal. This parameter will change the unit of the following parameters

    yaw

    target on the yaw axis. nil if you want to keep the current value.

    pitch

    target on the pitch axis. nil if you want to keep the current value.

    roll

    target on the roll axis. nil if you want to keep the current value.

  • Starts the offsets correction process.

    When offset correction is started, offsetsCorrectionProcess is not nil and correctable offsets can be corrected.

    Declaration

    Swift

    func startOffsetsCorrectionProcess()
  • Stops the offsets correction process.

    offsetsCorrectionProcess will be set to nil.

    Declaration

    Swift

    func stopOffsetsCorrectionProcess()
  • Starts calibration process. Does nothing when calibrationProcessState is calibrating.

    Declaration

    Swift

    func startCalibration()
  • Cancels the current calibration process. Does nothing when calibrationProcessState is not calibrating.

    Declaration

    Swift

    func cancelCalibration()