Gimbal

public protocol Gimbal : CalibratableGimbal

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).

Two frames of reference are used to control the gimbal with the .position mode, and to retrieve the gimbal attitude Relative frame of reference:

  • 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. Absolute frame of reference:
  • 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.

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 }

  • 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 }

  • 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), the .absolute frame of reference is used. Otherwise .relative frame of reference is used.

    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.

  • Resets the attitude of the gimbal.

    The orientation of the gimbal is set back to its default value on each axis in its current frame of reference.

    Declaration

    Swift

    func resetAttitude()

  • 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()

  • Gets the current attitude for a given frame of reference.

    Declaration

    Swift

    func currentAttitude(frameOfReference: FrameOfReference) -> [GimbalAxis : Double]

    Parameters

    frameOfReference

    the frame of reference

    Return Value

    the current attitude as an array of axis.