Gimbal API

Related C++ Header in the Auterion SDK: <auterion_sdk/gimbal/gimbal.hpp>

Auterion SDK provides an interface for managing and controlling the gimbals mounted on the vehicle.

The regular workflow for operating a gimbal entails the following steps:

• Finding and selecting a suitable gimbal (see Gimbal Discovery);

• Acquiring gimbal ownership (see Gimbal Ownership);

• Setting desired gimbal control mode (see Gimbal Modes);

• Actuating selected gimbal (see Gimbal Control).

Gimbal Discovery

The discovery process allows the user to select the most suitable gimbal for his needs.

Such process takes place during the auterion::Gimbal object construction. The Auterion SDK provides the user two ways select the desired gimbal: by using an auterion::GimbalDescriptor or by providing a custom filter function.

By Descriptor

The user can supply a auterion::GimbalDescriptor object that defines the characteristics used to select an appropriate gimbal (e.g., custom name, vendor name, model name, and capabilities).

In this case, the selection of the candidate gimbals behaves as follows:

1. If a custom name is provided, the candidate gimbal name must match it;

2. If vendor or model names are provided, the candidate gimbal must match those.

3. If no custom name, vendor, or model names are provided, it checks the provided capabilities.

For example, when developing for Virtual Skynode, we can select the simulated gimbal with the following:

auterion::SDK sdk(argc, argv, "gimbal_control_app");

// Select simulated gimbal
auterion::GimbalDescriptor gimbal_descriptor{};
gimbal_descriptor.vendor_name = "PX4";
gimbal_descriptor.model_name = "Gazebo Gimbal";

auterion::Gimbal gimbal(sdk, gimbal_descriptor);

The capabilities field of auterion::GimbalDescritptor can be used to specify the gimbal functionalities we are interested in. For example:

auterion::SDK sdk(argc, argv, "gimbal_control_app");

// Select gimbal that can yaw and that has a pitch range of at least [-30°; 30°]
auterion::GimbalDescriptor gimbal_descriptor{};
gimbal_descriptor.capabilities.canYaw().PitchRangeDeg(-30.0, 30.0);

auterion::Gimbal gimbal(sdk, gimbal_descriptor);

Please visit https://auterion.github.io/auterion-sdk/structauterion_1_1GimbalCapabilities.html for the full list of available capabilities.

By Selection Function

The user can provide the SDK with custom logic redefining the gimbal selection criteria; for example:

auterion::SDK sdk(argc, argv, "gimbal_control_app");

// Select gimbal having vendor name matching the model name
auterion::Gimbal gimbal(sdk, 
    [](const auterion::GimbalDescriptor& candidate) 
        {return candidate.vendor_name == candidate.model_name;}
    );

Gimbal Ownership

Before being able to send control commands the app needs to request control ownership of the gimbal:

if (gimbal.takeControl()) {
    // Gimbal control acquired, we can send commands
}

For the same reason, using gimbal.releaseControl() we can release the control so that other entities can use the same gimbal. At any time, we can check whether we are in control of the gimbal with gimbal.isInControl() .

Gimbal Modes

A gimbal may support multiple operating modes; in particular, each control axis (roll, pitch, and yaw) can be configured to be:

• Relative to the absolute world frame (auterion::GimbalMode::AxisMode::WorldLock), meaning that its deflection will compensate any vehicle movement;

• Relative to the vehicle frame (auterion::GimbalMode::AxisMode::VehicleFollow), meaning that its deflection is not affected by vehicle movements;

By default roll and pitch axes are in WorldLock mode, while yaw axis is in VehicleFollow mode.

The user can change the mode with:

auterion::GimbalMode gimbal_mode();
gimbal_mode.yaw = auterion::GimbalMode::AxisMode::WorldLock;
gimbal.setGimbalMode(gimbal_mode);

Gimbal Control

We can control either the gimbal axes rates or their absolute orientation.

// Rate control
if (gimbal.takeControl()) {
    gimbal.setRateControl(0, 0.1, 0.2); // pitching at 0.1 rad/s and yawing at 0.2 rad/s 
    gimbal.releaseControl();
}

// Attitude control
if (gimbal.takeControl()) {
    gimbal.setAttitudeControl(5, -10, 0); // roll 5° and pitch -10°
    gimbal.releaseControl();
}