Guidance API¶

Anafi Ai¶

Enumerations¶

enum guidance::Trigger¶

A Guidance Mode can specify at which rate their step() method should be called. This is done through the guidance::Mode::getTriggers method, which returns a timeout T, a period N and a bitmask build from the following values. Each enum value correspond to a possible event that triggers the step() method. TRIGGER_TIMER and TRIGGER_TICK cannot both be set.

Values:

enumerator TRIGGER_TIMER¶: Fired after T ms after the last trigger, if no other trigger happen

enumerator TRIGGER_TICK¶: Every N ticks as computed by Drone Controller

enum class guidance::ChannelKind¶

Each enum value identifies one predefined Channel

Values:

enumerator GUIDANCE¶: Server channel (normally the client is Flight Supervisor)

enumerator DRONE_CONTROLLER¶: Client channel connected to Drone Controller.

enum class guidance::SenderKind¶

Each enum identifies a Sender object, i.e. an interface through which protobuf messages can be sent (see libmsghub).

Values:

enumerator DRONE_CONTROLLER¶

enumerator FRONT_CAM_CONTROLLER¶

enumerator FRONT_ZOOM_CAM_CONTROLLER¶

enumerator GUIDANCE¶

Classes¶

class GuidanceLocal : public GuidanceBase¶

Guidance interface

This is the Guidance interface as seen from modes.

Subclassed by guidance::GuidanceImpl

Public Functions

virtual msghub::Channel *getChannel(ChannelKind kind) const = 0¶

Get the instance of Channel associated with an identifier

Parameters:: kind – identifies the kind of channel to access.

virtual msghub::MessageSender *getSender(SenderKind kind) = 0¶

Get the MessageSender associated with an identifier.

Parameters:: kind – identifies the kind of sender to access.

virtual std::string getConfigDir() const = 0¶

Return the configuration directory associated with the plugin currently being loaded (for example missions are all located in distinct directories and can use specific configuration files).

Calling this method is only valid while a plugin is being initialized. More precisely, it corresponds to the extent of a call to guidance::Plugin::init().

In practice, that means that Python modes can only access this path from inside Mode constructors, and C++ modes can only access it during the extent of guidance_plugin_init().

The resulting string is a copy, the caller owns the value. The string is empty if the method is called outside of its valid usage.

class Input¶

Guidance input

The active mode has access to an instance of Input, which holds the current inputs at each step.

Public Functions

inline Input()¶

inline void clearPcmds()¶: Clear members

inline void clearFrontCamPitch()¶

Public Members

PilotingCommands mPcmd¶

CamController::Messages::AxisReference mFrontCamPitch¶

class Output¶

Guidance output

At each step of execution the active mode can update an instance of Output, which holds different drone and camera references expressed as protobuf messages.

Each output is associated with a boolean flag for that output that indicates if the output is present at this step or not. At the beginning of a step, all flags are false.

Public Types

using PcmdExternal = DroneController::Messages::Pcmd¶

using MissionExternal = DroneController::Messages::Autopilot::Mission¶

using HorizontalReference = DroneController::Messages::HorizontalReference ¶

using VerticalReference = DroneController::Messages::VerticalReference ¶

using YawReference = DroneController::Messages::YawReference ¶

using GeoReference = DroneController::Messages::GeoReference¶

using FrontCamReference = AxesCamController::Messages::Reference ¶

using FrontCamZoom = ZoomCamController::Messages::Zoom ¶

using FrontCamReferenceConfig = AxesCamController::Messages::Config ¶

using FrontCamZoomConfig = ZoomCamController::Messages::Config ¶

using LoiterDirection = DroneController::Messages::Autopilot::LoiterDirection¶

Public Functions

inline Output()¶

inline void clear()¶: Clear members

inline void setPcmdExternal(const PilotingCommands &pcmd, const uint32_t &tickNum, const PcmdMode &mode = PcmdMode::PCMD_MODE_NONE)¶

Forwards the received pcmd to the client as output.

When the pcmds are not processed by guidance, as the task is delegated to an external autopilot, these can be forwarded directly to the latter to be processed there. This command does that. Note that the native controller cannot interpret raw pcmd commands.

Parameters:

pcmd – Input pcmd command provided to guidance
tickNum – Tick on which reference must be applied
mode – Piloting mode (default: PCMD_MODE_NONE)

inline void setHorizontalTrajectoryReference(const PositionState &reference, const ControllerConfig &cfg)¶

Set references and config for horizontal trajectory

Parameters:

reference – Output state reference
cfg – Controller config to be used

inline void setVerticalTrajectoryReference(const PositionState &reference, const ControllerConfig &cfg)¶

Set references and config for vertical trajectory

Parameters:

reference – Output state reference
cfg – Controller config to be used

inline void setTrajectoryReference(const PositionState &reference, const uint32_t &tickNum, const ControllerConfig &cfg)¶

Set references and config for both horizontal and vertical trajectory

Parameters:

reference – Output state reference
tickNum – Tick on wich reference must be applied
cfg – Controller config to be used

inline void setFixedReference(const uint32_t &tickNum, const ControllerConfig &cfg)¶

Set a fixed reference

Parameters:

tickNum – Tick on wich reference must be applied
cfg – Controller config to be used

inline void setGeoReference(const physics::CoordGeo3 &geoPose, const DroneController::Messages::AltitudeType altitudeType, const uint32_t &tickNum, const std::optional<float> &heading = std::nullopt, const std::optional<float> &loiterRadius = std::nullopt, const std::optional<LoiterDirection> &loiterDirection = std::nullopt)¶

Set a geographic reference point.

The altitude field requires the type.

Parameters:

geoPose – 3D geographic point (latitude, longitude, altitude)
altitudeType – Type of the altitude field
tickNum – Tick on which reference must be applied
heading – Optional heading angle (0° is North, positive is clockwise looking from above)
loiterRadius – Optional loiter radius upon point reach (used for planes)
loiterDirection – Optional loiter direction upon point reach (CW/CCW)

inline void setExternalAutopilotMode(const ExternalAutopilotModeType &mode, const uint32_t &tickNum, const ExternalAutopilotMode &params = ExternalAutopilotMode())¶

Set flight mode for external autopilot.

The external autopilot needs to be informed on which mode has to be set upon entering a specific mode.

Parameters:

mode – Mode that the external autopilot needs to set
tickNum – Tick on which reference must be applied
params – Additional parameters required to trigger some modes

Public Members

PcmdExternal mPcmdExternal¶

bool mHasPcmdExternal¶

MissionExternal mMissionExternal¶

bool mHasMissionExternal¶

HorizontalReference mHorizontalReference¶

bool mHasHorizontalReference¶

VerticalReference mVerticalReference¶

bool mHasVerticalReference¶

YawReference mYawReference¶

bool mHasYawReference¶

GeoReference mGeoReference¶

bool mHasGeoReference¶

FrontCamReference mFrontCamReference¶

bool mHasFrontCamReference¶

FrontCamZoom mFrontCamZoom¶

bool mHasFrontCamZoom¶

ExternalAutopilotMode mExternalAutopilotMode¶

bool mHasExternalAutopilotMode¶

FrontCamReferenceConfig mFrontCamReferenceConfig¶

bool mHasFrontCamReferenceConfig¶

FrontCamZoomConfig mFrontCamZoomConfig¶

bool mHasFrontCamZoomConfig¶

uint32_t mTickNum¶

struct ControllerConfig¶

Container for colibry controller config.

Public Functions

inline ControllerConfig()¶

inline ControllerConfig(bool isGroundConstrained, ColibryLite::Messages::ReferencePropagationModel::Enum propagationModel, ColibryLite::Messages::HorizontalControlConfig::Enum horizPropagationModelGains, ColibryLite::Messages::VerticalControlConfig::Enum vertPropagationModelGains, ColibryLite::Messages::HorizontalControllerReactivity::Enum reactivity)¶

Public Members

bool isGroundConstrained¶

ColibryLite::Messages::ReferencePropagationModel::Enum propagationModel¶

ColibryLite::Messages::HorizontalControlConfig::Enum horizPropagationModelGains¶

ColibryLite::Messages::VerticalControlConfig::Enum vertPropagationModelGains¶

ColibryLite::Messages::HorizontalControllerReactivity::Enum reactivity¶

class LocalMode : public Mode¶

Guidance Mode

At each step (with registered triggers) the methods will be called in this order:

beginStep
generateDroneReference
correctDroneReference
generateAttitudeReferences
endStep

Subclassed by AbsoluteMoveMode, BypassMode, CameraRotationMoveMode, CarpetMode, CylindricalMode, DescentMode, FlightPlanMode, LookAtMode, ManualMode, PlaneAbsoluteMoveMode, PlaneLandMode, PlaneLoiterMode, PlaneManualMode, PlaneRthMode, PlaneTakeoffMode, PoiMode, RthMode, guidance::NullMode

Public Functions

virtual void getTriggers(uint32_t *triggers, uint32_t *timeout, uint32_t *period) = 0¶

Get the triggers for the mode

Parameters:

triggers – mask of Trigger values. TRIGGER_TICK can not be combined with TRIGGER_TIMER.
timeout – if no frames received during this time (in ms), force a step.
period – if a timer is required, its period (in ms). If there is also a trigger on frame with a timeout specified, it will only be called when there is no frame. For tick trigger, this is the period of wakeup measured in ticks of the Drone Controller. For a 200Hz tick in drone controller this means a increment of 5ms per tick.

inline virtual void configure(const ::google::protobuf::Any &config)¶: Called when the mode is set with a configuration

inline virtual void beginStep()¶: Start a new step of the guidance The input data is valid at this point

inline virtual void endStep()¶: Finish a step of the guidance Output data shall be valid after this point

inline virtual void generateDroneReference()¶: Generate the drone trajectory reference (horizontal and vertical).

inline virtual void correctDroneReference()¶: Correct the generated trajectory using obstacle avoidance data.

inline virtual void generateAttitudeReferences()¶: Generate the camera and drone attitude references. The camera references do not depend on the drone ones, but will be saturated if not reachable.

inline const Input *getInput() const¶

inline Output *getOutput()¶

inline void setError(const std::string &message)¶: Report an error in this mode. The error message is logged and sent back to the Flight Supervisor. Guidance will call the exit() method (in case we are not already in exit()), and deactivate the current mode.

inline GuidanceLocal *getGuidance()¶

class SpatialPerception (ONLY FOR ANAFI AI)

Subclassed by guidance::SpatialPerceptionImpl

PUBLIC TYPES

typedef Eigen::Matrix<float, 3, -1, Eigen::RowMajor> PointsVector

PUBLIC FUNCTIONS

virtual const moser::IGrid &getGrid() const = 0¶

virtual void publishMiscDebugData(const PointsVector &nominalTraj, const std::array<float, 4> &nominalTrajColor, const PointsVector &referenceTraj, const std::array<float, 4> &referenceTrajColor) const = 0¶

class TrajectoryFcamMode : public guidance::Mode (ONLY FOR ANAFI AI)

Subclassed by RelativeMoveMode

PUBLIC FUNCTIONS

TrajectoryFcamMode(Guidance *guidance, const std::string &name, ModeGroup *group = nullptr)¶

virtual ~TrajectoryFcamMode() override¶

void setDroneNominalPositionTrajectoryGlobal(const guidance::PositionTrajectoryPoint &point)¶: Set nominal global drone trajectory (to be called from generateDroneReference). Will be adjusted in correctDroneReference if obstacle avoidance is enabled.

void setDroneNominalPositionTrajectoryLocal(const guidance::PositionTrajectoryPoint &point)¶: Set nominal local drone trajectory (to be called from generateDroneReference). Will be adjusted in correctDroneReference if obstacle avoidance is enabled.

void setFcamEulerAnglesZyxNed(const guidance::EulerAnglesZyx &angles, const guidance::EulerAnglesZyx &derivatives)¶

Set front camera angles and derivative angles (to be called from generateFcamAttitudeReference) in NED.

Parameters:

angles – Euler angles.
derivatives – First derivatives of Euler angles.

void setFcamEulerAnglesZyxNedStart(const guidance::EulerAnglesZyx &angles, const guidance::EulerAnglesZyx &derivatives)¶

Set front camera angles and derivative angles (to be called from generateFcamAttitudeReference) in NED Start.

Parameters:

angles – Euler angles.
derivatives – First derivatives of Euler angles.

virtual void generateFcamAttitudeReference()¶: Called at the beginning of generateAttitudeReference to let derived class fill mFcamEulerAnglesNedStartRef, mFcamEulerAnglesDerivativesNedStartRef, mFcamAcceleration and mFcamZoom.

virtual const guidance::PositionTrajectoryPoint &processObstacleAvoidance()¶: Process obstacle avoidance algorithm. This method is usually called by correctDroneReference. It can be overridden to change obstacle avoidance behavior.

void enableObstacleAvoidance(bool enable)¶

Enable or disable obstacle avoidance.

Parameters:: enable – true to enable obstacle avoidance, false otherwise.

bool isObstacleAvoidanceEnabled()¶

Get obstacle avoidance status.

Returns:: true if obstacle avoidance is enabled.

inline uint32_t getTickPeriod() const¶

inline float getTimePeriod() const¶

inline const PositionTrajectoryPoint &getDroneNominalPositionTrajectoryLocal() const¶

inline const PositionTrajectoryPoint &getDroneReferencePositionTrajectoryLocal() const¶

float getMaxHorizontalSpeed() const¶: Return the maximum admissible horizontal speed [m/s] (> 0).

float getMaxDescentSpeed() const¶: Return the maximum admissible descent speed [m/s] (> 0).

float getMaxAscentSpeed() const¶: Return the maximum admissible ascent speed [m/s] (> 0).

virtual bool hasObstacleAvoidance() override¶: Return whether the mode implements obstacle avoidance. Unless this function is overridden, modes do not advertise they implement obstacle avoidance. TODO: Add to mode descriptor.

virtual void getTriggers(uint32_t *triggers, uint32_t *timeout, uint32_t *period) override¶

Get the triggers for the mode.

Parameters:

triggers – Mask of Trigger values. TRIGGER_TICK cannot be combined with TRIGGER_TIMER.
timeout – If no frames are received during this time (in ms), force a step.
period – If a timer is required, its period (in ms). If there is also a trigger on frame with a timeout specified, it will only be called when there is no frame. For tick trigger, this is the period of wakeup measured in ticks of the Drone Controller. For a 200Hz tick in Drone Controller, this means an increment of 5ms per tick.

virtual void configure(const ::google::protobuf::Any &config, bool disableObstacleAvoidance, bool overrideFrontCamera, bool overrideStereoCamera) override¶: Called when the mode is set with a configuration.

virtual void enter() override¶: Called when the mode is activated and becomes the current one.

virtual void beginStep() override¶: Start a new step of the guidance. The input data is valid at this point.

virtual void correctDroneReference() override¶: Correct the generated trajectory using obstacle avoidance data.

virtual void generateAttitudeReferences() override¶: Generate the front camera, stereo camera and drone attitudes references. The camera references do not depend on the drone ones, but will be saturated if not reachable.

virtual void endStep() override¶: Finish a step of the guidance. Output data shall be valid after this point.

virtual void exit() override¶: Called when the mode is deactivated.

PUBLIC STATIC FUNCTIONS

static int init(Guidance *guidance)¶

static void destroy()¶

PROTECTED FUNCTIONS

void setFramer(AbsoluteFramer *framer)¶

Set the Framer object.

Warning

setFramer is unsafe. Need to call setFramer(nullptr) in the destructor of child class. Should be called only in constructor and destructor of child class.

Parameters:: framer – New framer.

void setPlanner(AbsolutePlanner *planner)¶

Set the Planner object.

In order to compute vertical/horizontal ideal model and target reached for autonomous flight.

Warning

setPlanner is unsafe. Need to call setPlanner(nullptr) in the destructor of child class. Should be called only in constructor and destructor of child class.

Parameters:: planner – New planner.

bool updateResetStatus()¶

Update the timer for checking if a mode should be reset.

This function should be called in each TrajectoryFcamMode mode: - in the configure() function to decide whether the mode should be reset, - in the beginStep() function to update the timer.

Returns:: true if the mode should be reset.

void updateTelemetry()¶

Update variables from latest telemetry.

Convert estimated position trajectory point from global to local. Convert estimated drone Euler angles from NED start to NED.

PROTECTED ATTRIBUTES

bool mFcamGroundConstraintEnabled¶

float mFcamYawAccelerationNedStartRef¶

float mFcamZoom¶

::ColibryLite::Messages::HorizontalControlConfig::Enum mDroneHorizontalControlConfig¶

::ColibryLite::Messages::VerticalControlConfig::Enum mDroneVerticalControlConfig¶

::ColibryLite::Messages::YawControlConfig::Enum mDroneYawControlConfig¶

::Guidance::Messages::msghub::EventSender mGuidanceEventSender¶

PROTECTED STATIC ATTRIBUTES

static timespec sLastCallTimestamp¶

static std::unique_ptr<boonta::IElcanoMpc> sReplannerLocal¶

static unsigned int sReplannerReferenceStatus¶

static bool sIsReplannerStuck = false¶

static bool sHasReplannerFailed = false¶

static Eigen::Vector3f sClosestObstaclePositionLocal¶

static float sClosestObstacleSignedDistance¶

static bool sIsInitialized = false¶

static guidance::PositionTrajectoryPoint sDronePositionStateLocalEst¶

static guidance::PositionTrajectoryPoint sDronePositionStateLocalNom¶

static guidance::PositionTrajectoryPoint sDronePositionStateLocalRef¶

static guidance::EulerAnglesZyx sDroneEulerAnglesNedEst¶

static guidance::EulerAnglesZyx sDroneEulerAnglesNedStartEst¶

static Eigen::Vector3f sDroneYawStateNedStartRef¶

static float sDroneMaxHorizSpeed¶

static float sDroneMinVerticalSpeed¶

static float sDroneMaxVerticalSpeed¶

static guidance::EulerAnglesZyx sStcamEulerAnglesNedStartRef¶

class TrajectoryStcamMode : public guidance::Mode (ONLY FOR ANAFI AI)

PUBLIC FUNCTION

TrajectoryStcamMode(Guidance *guidance, const std::string &name, ModeGroup *group = nullptr)¶

virtual ~TrajectoryStcamMode() override

void setDroneNominalPositionTrajectoryGlobal(const guidance::PositionTrajectoryPoint &point): Set nominal global drone trajectory (to be called from generateDroneReference).

void setDroneNominalPositionTrajectoryLocal(const guidance::PositionTrajectoryPoint &point): Set nominal local drone trajectory (to be called from generateDroneReference).

void setFcamEulerAnglesZyxNed(const guidance::EulerAnglesZyx &angles, const guidance::EulerAnglesZyx &derivatives)

Set front camera angles and derivative angles (to be called from generateFcamAttitudeReference) in NED.

Parameters:

angles – Euler angles.
derivatives – First derivatives of Euler angles.

void setFcamEulerAnglesZyxNedStart(const guidance::EulerAnglesZyx &angles, const guidance::EulerAnglesZyx &derivatives)

Set front camera angles and derivative angles (to be called from generateFcamAttitudeReference) in NED Start.

Parameters:

angles – Euler angles.
derivatives – First derivatives of Euler angles.

void setStcamEulerAnglesZyxNed(const guidance::EulerAnglesZyx &angles, const guidance::EulerAnglesZyx &derivatives)¶

Set stereo camera angles and derivative angles (to be called from generateStcamAttitudeReference) in NED.

Parameters:

angles – Euler angles.
derivatives – First derivatives of Euler angles.

void setStcamEulerAnglesZyxNedStart(const guidance::EulerAnglesZyx &angles, const guidance::EulerAnglesZyx &derivatives)¶

Set stereo camera angles and derivative angles (to be called from generateStcamAttitudeReference) in NED Start.

Parameters:

angles – Euler angles.
derivatives – First derivatives of Euler angles.

float getMaxHorizontalSpeed() const: Return the maximum admissible horizontal speed [m/s] (> 0).

float getMaxDescentSpeed() const: Return the maximum admissible descent speed [m/s] (> 0).

float getMaxAscentSpeed() const: Return the maximum admissible ascent speed [m/s] (> 0).

virtual void generateFcamAttitudeReference(): Called at the beginning of generateAttitudeReferences to let derived class fill mFcamEulerAnglesNedStartRef, mFcamEulerAnglesDerivativesNedStartRef, mFcamAcceleration and mFcamZoom.

virtual void generateStcamAttitudeReference() = 0¶: Called at the beginning of generateAttitudeReferences to let derived class fill mStcamEulerAnglesNedStartRef, mStcamEulerAnglesDerivativesNedStartRef and mStcamAcceleration.

inline uint32_t getTickPeriod() const

inline float getTimePeriod() const

inline const PositionTrajectoryPoint &getDroneNominalPositionTrajectoryLocal() const

inline const PositionTrajectoryPoint &getDroneReferencePositionTrajectoryLocal() const

virtual bool hasObstacleAvoidance() override: Return whether the mode implements obstacle avoidance. Unless this function is overridden, modes do not advertise they implement obstacle avoidance. TODO: Add to mode descriptor.

virtual void getTriggers(uint32_t *triggers, uint32_t *timeout, uint32_t *period) override

Get the triggers for the mode.

Parameters:

triggers – Mask of Trigger values. TRIGGER_TICK cannot be combined with TRIGGER_TIMER.
timeout – If no frames are received during this time (in ms), force a step.
period – If a timer is required, its period (in ms). If there is also a trigger on frame with a timeout specified, it will only be called when there is no frame. For tick trigger, this is the period of wakeup measured in ticks of the Drone Controller. For a 200Hz tick in drone controller, this means an increment of 5ms per tick.

virtual void configure(const ::google::protobuf::Any &config, bool disableObstacleAvoidance, bool overrideFrontCamera, bool overrideStereoCamera) override: Called when the mode is set with a configuration.

virtual void beginStep() override: Start a new step of the guidance. The input data is valid at this point.

virtual void correctDroneReference() override: Correct the generated trajectory using obstacle avoidance data.

virtual void generateAttitudeReferences() override: Generate the front camera, stereo camera and drone attitudes references. The camera references do not depend on the drone ones, but will be saturated if not reachable.

virtual void endStep() override: Finish a step of the guidance. Output data shall be valid after this point.

PROTECTED FUNCTIONS

void setFramer(AbsoluteFramer *framer)

Set the Framer object.

In order to compute yaw ideal model and target reached for autonomous flight.

Warning

setFramer is unsafe. Need to call setFramer(nullptr) in destructor of child class. Should be called only in constructor and destructor of child class.

Parameters:: framer – New framer.

void setPlanner(AbsolutePlanner *planner)

Set the Planner object.

In order to compute vertical/horizontal ideal model and target reached for autonomous flight.

Warning

setPlanner is unsafe. Need to call setPlanner(nullptr) in destructor of child class. Should be called only in constructor and destructor of child class.

Parameters:: planner – New planner.

PROTECTED ATTRIBUTES

bool mStcamGroundConstraintEnabled¶

float mStcamYawAccelerationNedStartRef¶

float mFcamZoom

Native specific¶

It is possible to declare from one to several modes in a .cpp file. The files where modes are implemented must contain two functions that allow to use them:

static FirstMode *sFirstMode;
static SecondMode *sSecondMode;

void guidance_plugin_init(guidance::Guidance *guidance)
{
    sFirstMode = guidance->registerMode<FirstMode>();;
    sSecondMode = guidance->registerMode<SecondMode>();
}

void guidance_plugin_shutdown(guidance::Guidance *guidance)
{
    guidance->unregisterMode(sFirstMode);
    guidance->unregisterMode(sSecondMode);
}

Python specific¶

It is possible to declare from one to several modes in a .py file. The files where modes are implemented must contain a dictionary that allows to use them.

GUIDANCE_MODES = {
    'first_mode': FirstModeClass,
    'second_mode': SecondModeClass
}

All methods from guidance::Mode class use snake case instead of camel case, except for the guidance::Mode::getName() function which does not exist in Python.

Example:

Native method

void getTriggers(uint32_t *triggers, uint32_t *timeout, uint32_t *period)
{
    *triggers = guidance::TRIGGER_TICK;
    *timeout = 0;
    *period = 6;
}

becomes

def get_triggers(self):
    return (gdnc_core.Trigger.TICK, 0, 6)

Anafi UKR¶

Enumerations¶

enum guidance::Trigger

Values:

enumerator TRIGGER_TIMER: Fired after T ms after the last trigger, if no other trigger happen

enumerator TRIGGER_TICK: Every N ticks as computed by Drone Controller

enum class guidance::ChannelKind

Each enum value identifies one predefined Channel

Values:

enumerator GUIDANCE: Server channel (normally the client is Flight Supervisor)

enumerator DRONE_CONTROLLER: Client channel connected to Drone Controller.

enum class guidance::SenderKind

Each enum identifies a Sender object, i.e. an interface through which protobuf messages can be sent (see libmsghub).

Values:

enumerator DRONE_CONTROLLER

enumerator FRONT_CAM_CONTROLLER

enumerator FRONT_ZOOM_CAM_CONTROLLER

enumerator GUIDANCE

enum class guidance::OutputPart : unsigned¶

Values:

enumerator REFERENCES¶

enumerator CAMERA_AXES_CONFIG¶

enumerator EXTERNAL_AUTOPILOT_MODE¶

Classes¶

class GuidanceLocal : public GuidanceBase

Guidance interface

This is the Guidance interface as seen from modes.

Subclassed by guidance::GuidanceImpl

Public Functions

inline explicit GuidanceLocal(pomp::Loop &loop)¶

inline virtual ~GuidanceLocal() = default¶

virtual msghub::Channel *getChannel(ChannelKind kind) const = 0

Get the instance of Channel associated with an identifier

Parameters:: kind – identifies the kind of channel to access.

virtual msghub::MessageSender *getSender(SenderKind kind) = 0

Get the MessageSender associated with an identifier.

Parameters:: kind – identifies the kind of sender to access.

virtual DebugData &getDebugData() = 0¶: Get the DebugData instance

virtual Geofence *getGeofence() const = 0¶: Get the Geofence instance owned by the guidance object. This gives access to the geofence getter, setter and process methods.

virtual const Telemetry *getTelemetry() const = 0¶

virtual const AutopilotSettings &getAutopilotSettings() const = 0¶: Get the AutopilotSettings struct owned by the guidance object.

virtual const SensorStatus &getSensorStatus() const = 0¶: Get the SensorStatus struct owned by the guidance object.

inline bool isExternalAutopilotModeType(ExternalAutopilotModeType mode) const¶

Checks if the current external autopilot mode matches the given mode.

Parameters:: mode – The mode to compare against the current mode.
Returns:: true if the current mode matches the input mode, false otherwise.

inline void setExternalAutopilotModeType(ExternalAutopilotModeType mode)¶

Sets the current external autopilot mode type.

Parameters:: mode – The new external autopilot mode to set.

virtual void updateModeTriggers() = 0¶: Called internally by guidance to update the triggers that wake up the current mode. This calls the mode’s getTriggers() method.

virtual uint32_t getTickNum() = 0¶: A tick is sent from drone_controller at regular intervals. getTickNum() returns the latest tick received. The tick is a strictly increasing number starting from zero.

virtual std::string getConfigDir() const = 0

Return the configuration directory associated with the plugin currently being loaded (for example missions are all located in distinct directories and can use specific configuration files).

Calling this method is only valid while a plugin is being initialized. More precisely, it corresponds to the extent of a call to guidance::Plugin::init().

In practice, that means that Python modes can only access this path from inside Mode constructors, and C++ modes can only access it during the extent of guidance_plugin_init().

The resulting string is a copy, the caller owns the value. The string is empty if the method is called outside of its valid usage.

virtual std::string getConfigFile(const std::string &file) const = 0¶

Return configuration path for #file relatively to the path returned by getConfigDir(); it is equivalent to the following, assuming getConfigDir() is called during plugin init (the function returns the empty string otherwise).

getConfigDir().append(file);

Calling this method is only valid while a plugin is being initialized. More precisely, it corresponds to the extent of a call to guidance::Plugin::init().

virtual void setError(const std::string &message) = 0¶

Called by a mode mode to signal an error; when called, guidance sends a ::Guidance::Local::Messages::Error message to all clients. The “message” parameter is an optional string (defaulting to the empty string) used for debugging and sent along the protobuf Error message.

An error in a mode means that the current configuration of the mode, or the current inputs sent to the mode, made it reach a bad state: the mode is exited but might be re-entered later. The mode is NOT disabled/removed from guidance.

Once setError() is called, guidance avoids calling any other method from the mode except its exit() method.

More precisely, if a mode calls setError() in any other method than exit() (even in enter()), then guidance calls exit() for this mode and reverts to the empty mode. If the mode’s exit() method itself calls setError(), this call is ignored (the mode is already treated as errorneous).

That means the exit() method must be robust enough to handle errors in any other method of the mode, and clean the resources allocated in configure()/enter() even if they fail to complete.

The guidance object never calls setError() by itself.

If setError() is called during the extent of setMode(), i.e. either in configure() or enter(), then: (1) the error message is sent, (2) ModeChanged with ok=false is sent (in other words, ModeChanged is always sent).

Messages associated with the mode’s Outputs at one step are sent only when no error happened at that step (but guidance cannot prevent the mode to explicitly send other messages).

Protected Attributes

ExternalAutopilotModeType mExternalAutopilotModeType = ExternalAutopilotModeType::MODE_NONE¶

class Input

Guidance input

The active mode has access to an instance of Input, which holds the current inputs at each step.

Public Functions

inline Input()

inline void clearPcmds(): Clear members

inline void clearFrontCamPitch()

Public Members

PilotingCommands mPcmd

CamController::Messages::AxisReference mFrontCamPitch

class Output

Guidance output

At each step of execution the active mode can update an instance of Output, which holds different drone and camera references expressed as protobuf messages.

Each output is associated with a boolean flag for that output that indicates if the output is present at this step or not. At the beginning of a step, all flags are false.

Public Types

using PcmdExternal = DroneController::Messages::Pcmd

using MissionExternal = DroneController::Messages::Autopilot::Mission

using HorizontalReference = DroneController::Messages::HorizontalReference

using VerticalReference = DroneController::Messages::VerticalReference

using YawReference = DroneController::Messages::YawReference

using GeoReference = DroneController::Messages::GeoReference

using FrontCamReference = AxesCamController::Messages::Reference

using FrontCamZoom = ZoomCamController::Messages::Zoom

using FrontCamReferenceConfig = AxesCamController::Messages::Config

using FrontCamZoomConfig = ZoomCamController::Messages::Config

using LoiterDirection = DroneController::Messages::Autopilot::LoiterDirection

Public Functions

inline Output()

inline void clear(): Clear members

inline void setPcmdExternal(const PilotingCommands &pcmd, const uint32_t &tickNum, const PcmdMode &mode = PcmdMode::PCMD_MODE_NONE)

Forwards the received pcmd to the client as output.

Parameters:

pcmd – Input pcmd command provided to guidance
tickNum – Tick on which reference must be applied
mode – Piloting mode (default: PCMD_MODE_NONE)

inline void setHorizontalTrajectoryReference(const PositionState &reference, const ControllerConfig &cfg)

Set references and config for horizontal trajectory

Parameters:

reference – Output state reference
cfg – Controller config to be used

inline void setVerticalTrajectoryReference(const PositionState &reference, const ControllerConfig &cfg)

Set references and config for vertical trajectory

Parameters:

reference – Output state reference
cfg – Controller config to be used

inline void setTrajectoryReference(const PositionState &reference, const uint32_t &tickNum, const ControllerConfig &cfg)

Set references and config for both horizontal and vertical trajectory

Parameters:

reference – Output state reference
tickNum – Tick on wich reference must be applied
cfg – Controller config to be used

inline void setFixedReference(const uint32_t &tickNum, const ControllerConfig &cfg)

Set a fixed reference

Parameters:

tickNum – Tick on wich reference must be applied
cfg – Controller config to be used

Set a geographic reference point.

The altitude field requires the type.

Parameters:

geoPose – 3D geographic point (latitude, longitude, altitude)
altitudeType – Type of the altitude field
tickNum – Tick on which reference must be applied
heading – Optional heading angle (0° is North, positive is clockwise looking from above)
loiterRadius – Optional loiter radius upon point reach (used for planes)
loiterDirection – Optional loiter direction upon point reach (CW/CCW)

inline void setExternalAutopilotMode(const ExternalAutopilotModeType &mode, const uint32_t &tickNum, const ExternalAutopilotMode &params = ExternalAutopilotMode())

Set flight mode for external autopilot.

The external autopilot needs to be informed on which mode has to be set upon entering a specific mode.

Parameters:

mode – Mode that the external autopilot needs to set
tickNum – Tick on which reference must be applied
params – Additional parameters required to trigger some modes

Public Members

PcmdExternal mPcmdExternal

bool mHasPcmdExternal

MissionExternal mMissionExternal

bool mHasMissionExternal

HorizontalReference mHorizontalReference

bool mHasHorizontalReference

VerticalReference mVerticalReference

bool mHasVerticalReference

YawReference mYawReference

bool mHasYawReference

GeoReference mGeoReference

bool mHasGeoReference

FrontCamReference mFrontCamReference

bool mHasFrontCamReference

FrontCamZoom mFrontCamZoom

bool mHasFrontCamZoom

ExternalAutopilotMode mExternalAutopilotMode

bool mHasExternalAutopilotMode

FrontCamReferenceConfig mFrontCamReferenceConfig

bool mHasFrontCamReferenceConfig

FrontCamZoomConfig mFrontCamZoomConfig

bool mHasFrontCamZoomConfig

uint32_t mTickNum

struct ControllerConfig

Container for colibry controller config.

Public Functions

inline ControllerConfig()

inline ControllerConfig(bool isGroundConstrained, ColibryLite::Messages::ReferencePropagationModel::Enum propagationModel, ColibryLite::Messages::HorizontalControlConfig::Enum horizPropagationModelGains, ColibryLite::Messages::VerticalControlConfig::Enum vertPropagationModelGains, ColibryLite::Messages::HorizontalControllerReactivity::Enum reactivity)

Public Members

bool isGroundConstrained

ColibryLite::Messages::ReferencePropagationModel::Enum propagationModel

ColibryLite::Messages::HorizontalControlConfig::Enum horizPropagationModelGains

ColibryLite::Messages::VerticalControlConfig::Enum vertPropagationModelGains

ColibryLite::Messages::HorizontalControllerReactivity::Enum reactivity

class LocalMode : public Mode

Guidance Mode

At each step (with registered triggers) the methods will be called in this order:

beginStep
generateDroneReference
correctDroneReference
generateAttitudeReferences
endStep

Public Functions

inline LocalMode(const std::string name, GuidanceBase *guidance, ModeGroup *group)¶

inline LocalMode(const std::string name, GuidanceBase *guidance)¶

inline virtual ~LocalMode() = default¶

virtual void getTriggers(uint32_t *triggers, uint32_t *timeout, uint32_t *period) = 0

Get the triggers for the mode

Parameters:

triggers – mask of Trigger values. TRIGGER_TICK can not be combined with TRIGGER_TIMER.
timeout – if no frames received during this time (in ms), force a step.
period – if a timer is required, its period (in ms). If there is also a trigger on frame with a timeout specified, it will only be called when there is no frame. For tick trigger, this is the period of wakeup measured in ticks of the Drone Controller. For a 200Hz tick in drone controller this means a increment of 5ms per tick.

inline virtual void configure(const ::google::protobuf::Any &config): Called when the mode is set with a configuration

inline virtual void beginStep(): Start a new step of the guidance The input data is valid at this point

inline virtual void endStep(): Finish a step of the guidance Output data shall be valid after this point

inline virtual void generateDroneReference(): Generate the drone trajectory reference (horizontal and vertical).

inline virtual void correctDroneReference(): Correct the generated trajectory using obstacle avoidance data.

inline virtual void generateAttitudeReferences(): Generate the camera and drone attitude references. The camera references do not depend on the drone ones, but will be saturated if not reachable.

inline virtual bool sendOutput(OutputPart part)¶: Send optional drone/camera references and/or camera configuration

inline void setInput(const Input *input)¶

inline const Input *getInput() const

inline void setOutput(Output *output)¶

inline Output *getOutput()

inline void setError(const std::string &message): Report an error in this mode. The error message is logged and sent back to the Flight Supervisor. Guidance will call the exit() method (in case we are not already in exit()), and deactivate the current mode.

inline GuidanceLocal *getGuidance()

inline void updateExternalAutopilotMode(const ExternalAutopilotModeType &mode = ExternalAutopilotModeType::MODE_NONE, const uint32_t &tickNum = 0, const ExternalAutopilotMode &params = ExternalAutopilotMode(), const bool &forceUpdate = false)¶

Update the mode of the external autopilot

As guidance keeps track of which mode the external autopilot is in, this method checks if the new proposed mode is different and therefore be set.

Parameters:

mode – Mode type that is desired
tickNum – Tick on which mode must be applied
params – Additional parameters required to trigger some modes
forceUpdate – Set to true to send the mode update even if already in the mode

Protected Functions

inline EventSender *getGdncEventSender()¶

get the guidance event sender

Each mode can have its own event sender but also has access to the guidance event sender for common messages

Returns:: pointer to guidance event sender

inline DctlCommandSender *getDctlCommandSender()¶

get the drone controller command sender

Returns:: pointer to drone controller command sender

Protected Attributes

GuidanceLocal *mGuidance¶

const Input *mInput = nullptr¶

Output *mOutput = nullptr¶

Native specific¶

Modes are implemented in C++ by inheriting from guidance::LocalMode. Each mode file must define:

static FirstLocalMode *sFirstMode;
static SecondLocalMode *sSecondMode;

void guidance_plugin_init(guidance::GuidanceLocal *guidance)
{
    sFirstMode = guidance->registerMode<FirstLocalMode>();
    sSecondMode = guidance->registerMode<SecondLocalMode>();
}

void guidance_plugin_shutdown(guidance::GuidanceLocal *guidance)
{
    guidance->unregisterMode(sFirstMode);
    guidance->unregisterMode(sSecondMode);
}

Python specific¶

Modes are implemented in Python by inheriting from gdnc_core.LocalMode:

GUIDANCE_MODES = {
    'first_mode': FirstLocalModeClass,
    'second_mode': SecondLocalModeClass
}

All methods from guidance::LocalMode class use snake case instead of camel case, except for guidance::LocalMode::getName().

Example:

Native method

void getTriggers(uint32_t *triggers, uint32_t *timeout, uint32_t *period)
{
    *triggers = guidance::TRIGGER_TICK;
    *timeout = 0;
    *period = 6;
}

becomes

def get_triggers(self):
    return (gdnc_core.Trigger.TICK, 0, 6)

Usage notes¶

Include paths / base class:
- Anafi Ai: prefer #include <guidance.hpp> and implement modes by inheriting from guidance::Mode.
- Anafi UKR: prefer #include <guidance/local.hpp> and implement modes by inheriting from guidance::LocalMode.
Python bindings:
- Anafi Ai: import guidance.core as gdnc_core and inherit from gdnc_core.Mode.
- Anafi UKR: import guidance.local.core as gdnc_core and inherit from gdnc_core.LocalMode.