FirmwarePlugin.h 14.7 KB
Newer Older
1 2 3 4 5 6 7 8 9
/****************************************************************************
 *
 *   (c) 2009-2016 QGROUNDCONTROL PROJECT <http://www.qgroundcontrol.org>
 *
 * QGroundControl is licensed according to the terms in the file
 * COPYING.md in the root of the source code directory.
 *
 ****************************************************************************/

Don Gagne's avatar
Don Gagne committed
10 11 12 13 14 15 16

/// @file
///     @author Don Gagne <don@thegagnes.com>

#ifndef FirmwarePlugin_H
#define FirmwarePlugin_H

Don Gagne's avatar
Don Gagne committed
17
#include "QGCMAVLink.h"
Don Gagne's avatar
Don Gagne committed
18 19
#include "VehicleComponent.h"
#include "AutoPilotPlugin.h"
20
#include "GeoFenceManager.h"
21
#include "RallyPointManager.h"
Don Gagne's avatar
Don Gagne committed
22 23 24 25

#include <QList>
#include <QString>

26 27
class Vehicle;

Don Gagne's avatar
Don Gagne committed
28 29
/// This is the base class for Firmware specific plugins
///
30 31 32 33
/// The FirmwarePlugin class represents the methods and objects which are specific to a certain Firmware flight stack.
/// This is the only place where flight stack specific code should reside in QGroundControl. The remainder of the
/// QGroundControl source is generic to a common mavlink implementation. The implementation in the base class supports
/// mavlink generic firmware. Override the base clase virtuals to create your own firmware specific plugin.
Don Gagne's avatar
Don Gagne committed
34

Don Gagne's avatar
Don Gagne committed
35
class FirmwarePlugin : public QObject
Don Gagne's avatar
Don Gagne committed
36 37 38 39 40 41
{
    Q_OBJECT

public:
    /// Set of optional capabilites which firmware may support
    typedef enum {
Don Gagne's avatar
Don Gagne committed
42 43 44
        SetFlightModeCapability =           1 << 0, ///< FirmwarePlugin::setFlightMode method is supported
        MavCmdPreflightStorageCapability =  1 << 1, ///< MAV_CMD_PREFLIGHT_STORAGE is supported
        PauseVehicleCapability =            1 << 2, ///< Vehicle supports pausing at current location
45 46
        GuidedModeCapability =              1 << 3, ///< Vehicle supports guided mode commands
        OrbitModeCapability =               1 << 4, ///< Vehicle supports orbit mode
Don Gagne's avatar
Don Gagne committed
47
    } FirmwareCapabilities;
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62

    /// Maps from on parameter name to another
    ///     key:    parameter name to translate from
    ///     value:  mapped parameter name
    typedef QMap<QString, QString> remapParamNameMap_t;

    /// Maps from firmware minor version to remapParamNameMap_t entry
    ///     key:    firmware minor version
    ///     value:  remapParamNameMap_t entry
    typedef QMap<int, remapParamNameMap_t> remapParamNameMinorVersionRemapMap_t;

    /// Maps from firmware major version number to remapParamNameMinorVersionRemapMap_t entry
    ///     key:    firmware major version
    ///     value:  remapParamNameMinorVersionRemapMap_t entry
    typedef QMap<int, remapParamNameMinorVersionRemapMap_t> remapParamNameMajorVersionMap_t;
63

64 65 66
    /// @return The AutoPilotPlugin associated with this firmware plugin. Must be overriden.
    virtual AutoPilotPlugin* autopilotPlugin(Vehicle* vehicle);

67
    /// Called when Vehicle is first created to perform any firmware specific setup.
Don Gagne's avatar
Don Gagne committed
68 69
    virtual void initializeVehicle(Vehicle* vehicle);

Don Gagne's avatar
Don Gagne committed
70
    /// @return true: Firmware supports all specified capabilites
71
    virtual bool isCapable(const Vehicle *vehicle, FirmwareCapabilities capabilities);
72

Don Gagne's avatar
Don Gagne committed
73 74 75 76
    /// Returns VehicleComponents for specified Vehicle
    ///     @param vehicle Vehicle  to associate with components
    /// @return List of VehicleComponents for the specified vehicle. Caller owns returned objects and must
    ///         free when no longer needed.
77
    virtual QList<VehicleComponent*> componentsForVehicle(AutoPilotPlugin* vehicle);
78

Don Gagne's avatar
Don Gagne committed
79
    /// Returns the list of available flight modes
Daniel Agar's avatar
Daniel Agar committed
80
    virtual QStringList flightModes(Vehicle* vehicle) {
81 82 83 84
        Q_UNUSED(vehicle);
        return QStringList();
    }

Don Gagne's avatar
Don Gagne committed
85 86 87
    /// Returns the name for this flight mode. Flight mode names must be human readable as well as audio speakable.
    ///     @param base_mode Base mode from mavlink HEARTBEAT message
    ///     @param custom_mode Custom mode from mavlink HEARTBEAT message
Don Gagne's avatar
Don Gagne committed
88
    virtual QString flightMode(uint8_t base_mode, uint32_t custom_mode) const;
89

Don Gagne's avatar
Don Gagne committed
90 91 92
    /// Sets base_mode and custom_mode to specified flight mode.
    ///     @param[out] base_mode Base mode for SET_MODE mavlink message
    ///     @param[out] custom_mode Custom mode for SET_MODE mavlink message
93
    virtual bool setFlightMode(const QString& flightMode, uint8_t* base_mode, uint32_t* custom_mode);
Don Gagne's avatar
Don Gagne committed
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117

    /// Returns whether the vehicle is in guided mode or not.
    virtual bool isGuidedMode(const Vehicle* vehicle) const;

    /// Set guided flight mode
    virtual void setGuidedMode(Vehicle* vehicle, bool guidedMode);

    /// Returns whether the vehicle is paused or not.
    virtual bool isPaused(const Vehicle* vehicle) const;

    /// Causes the vehicle to stop at current position. If guide mode is supported, vehicle will be let in guide mode.
    /// If not, vehicle will be left in Loiter.
    virtual void pauseVehicle(Vehicle* vehicle);

    /// Command vehicle to return to launch
    virtual void guidedModeRTL(Vehicle* vehicle);

    /// Command vehicle to land at current location
    virtual void guidedModeLand(Vehicle* vehicle);

    /// Command vehicle to takeoff from current location
    ///     @param altitudeRel Relative altitude to takeoff to
    virtual void guidedModeTakeoff(Vehicle* vehicle, double altitudeRel);

118 119 120 121
    /// Command vehicle to orbit given center point
    ///     @param centerCoord Center Coordinates
    virtual void guidedModeOrbit(Vehicle* vehicle, const QGeoCoordinate& centerCoord, double radius, double velocity, double altitude);

Don Gagne's avatar
Don Gagne committed
122 123 124 125 126 127
    /// Command vehicle to move to specified location (altitude is included and relative)
    virtual void guidedModeGotoLocation(Vehicle* vehicle, const QGeoCoordinate& gotoCoord);

    /// Command vehicle to change to the specified relatice altitude
    virtual void guidedModeChangeAltitude(Vehicle* vehicle, double altitudeRel);

128 129 130 131 132 133 134 135 136
    /// Returns the flight mode for running missions
    virtual QString missionFlightMode(void);

    /// Returns the flight mode for RTL
    virtual QString rtlFlightMode(void);

    /// Returns the flight mode to use when the operator wants to take back control from autonomouse flight.
    virtual QString takeControlFlightMode(void);

137
    /// FIXME: This isn't quite correct being here. All code for Joystick suvehicleTypepport is currently firmware specific
Don Gagne's avatar
Don Gagne committed
138
    /// not just this. I'm going to try to change that. If not, this will need to be removed.
139 140 141 142
    /// Returns the number of buttons which are reserved for firmware use in the MANUAL_CONTROL mavlink
    /// message. For example PX4 Flight Stack reserves the first 8 buttons to simulate rc switches.
    /// The remainder can be assigned to Vehicle actions.
    /// @return -1: reserver all buttons, >0 number of buttons to reserve
143
    virtual int manualControlReservedButtonCount(void);
144

145 146 147 148
    /// Default tx mode to apply to joystick axes
    /// TX modes are as outlined here: http://www.rc-airplane-world.com/rc-transmitter-modes.html
    virtual int defaultJoystickTXMode(void);

149 150 151 152 153
    /// Returns true if the vehicle and firmware supports the use of a throttle joystick that
    /// is zero when centered. Typically not supported on vehicles that have bidirectional
    /// throttle.
    virtual bool supportsThrottleModeCenterZero(void);

154 155 156 157
    /// Returns true if the firmware supports the use of the MAVlink "MANUAL_CONTROL" message.
    /// By default, this returns false unless overridden in the firmware plugin.
    virtual bool supportsManualControl(void);

158 159 160 161
    /// Returns true if the firmware supports the use of the RC radio and requires the RC radio
    /// setup page. Returns true by default.
    virtual bool supportsRadio(void);

162 163 164 165
    /// Returns true if the firmware supports the AP_JSButton library, which allows joystick buttons
    /// to be assigned via parameters in firmware. Default is false.
    virtual bool supportsJSButton(void);

166 167 168 169
    /// Returns true if the firmware supports calibrating the pressure sensor so the altitude will read
    /// zero at the current pressure. Default is false.
    virtual bool supportsCalibratePressure(void);

170 171 172 173
    /// Returns true if the firmware supports calibrating motor interference offsets for the compass
    /// (CompassMot). Default is true.
    virtual bool supportsMotorInterference(void);

nopeppermint's avatar
nopeppermint committed
174
    /// Called before any mavlink message is processed by Vehicle such that the firmwre plugin
Don Gagne's avatar
Don Gagne committed
175 176
    /// can adjust any message characteristics. This is handy to adjust or differences in mavlink
    /// spec implementations such that the base code can remain mavlink generic.
177
    ///     @param vehicle Vehicle message came from
Don Gagne's avatar
Don Gagne committed
178
    ///     @param message[in,out] Mavlink message to adjust if needed.
179 180
    /// @return false: skip message, true: process message
    virtual bool adjustIncomingMavlinkMessage(Vehicle* vehicle, mavlink_message_t* message);
181

Don Gagne's avatar
Don Gagne committed
182 183 184 185
    /// Called before any mavlink message is sent to the Vehicle so plugin can adjust any message characteristics.
    /// This is handy to adjust or differences in mavlink spec implementations such that the base code can remain
    /// mavlink generic.
    ///     @param vehicle Vehicle message came from
186
    ///     @param outgoingLink Link that messae is going out on
Don Gagne's avatar
Don Gagne committed
187
    ///     @param message[in,out] Mavlink message to adjust if needed.
188
    virtual void adjustOutgoingMavlinkMessage(Vehicle* vehicle, LinkInterface* outgoingLink, mavlink_message_t* message);
Don Gagne's avatar
Don Gagne committed
189

190 191 192 193 194 195
    /// Determines how to handle the first item of the mission item list. Internally to QGC the first item
    /// is always the home position.
    /// @return
    ///     true: Send first mission item as home position to vehicle. When vehicle has no mission items on
    ///             it, it may or may not return a home position back in position 0.
    ///     false: Do not send first item to vehicle, sequence numbers must be adjusted
196
    virtual bool sendHomePositionToVehicle(void);
197

198 199 200 201 202 203 204
    /// Returns the parameter which is used to identify the version number of parameter set
    virtual QString getVersionParam(void) { return QString(); }

    /// Returns the parameter set version info pulled from inside the meta data file. -1 if not found.
    virtual void getParameterMetaDataVersionInfo(const QString& metaDataFile, int& majorVersion, int& minorVersion);

    /// Returns the internal resource parameter meta date file.
205
    virtual QString internalParameterMetaDataFile(Vehicle* vehicle) { Q_UNUSED(vehicle); return QString(); }
206 207

    /// Loads the specified parameter meta data file.
Ricardo de Almeida Gonzaga's avatar
Ricardo de Almeida Gonzaga committed
208
    /// @return Opaque parameter meta data information which must be stored with Vehicle. Vehicle is responsible to
209 210
    ///         call deleteParameterMetaData when no longer needed.
    virtual QObject* loadParameterMetaData(const QString& metaDataFile) { Q_UNUSED(metaDataFile); return NULL; }
211 212

    /// Adds the parameter meta data to the Fact
213 214
    ///     @param opaqueParameterMetaData Opaque pointer returned from loadParameterMetaData
    virtual void addMetaDataToFact(QObject* parameterMetaData, Fact* fact, MAV_TYPE vehicleType) { Q_UNUSED(parameterMetaData); Q_UNUSED(fact); Q_UNUSED(vehicleType); return; }
Don Gagne's avatar
Don Gagne committed
215 216

    /// List of supported mission commands. Empty list for all commands supported.
217
    virtual QList<MAV_CMD> supportedMissionCommands(void);
218

219 220 221
    /// Returns the name of the mission command json override file for the specified vehicle type.
    ///     @param vehicleType Vehicle type to return file for, MAV_TYPE_GENERIC is a request for overrides for all vehicle types
    virtual QString missionCommandOverrides(MAV_TYPE vehicleType) const;
222

223 224 225 226 227
    /// Returns the mapping structure which is used to map from one parameter name to another based on firmware version.
    virtual const remapParamNameMajorVersionMap_t& paramNameRemapMajorVersionMap(void) const;

    /// Returns the highest major version number that is known to the remap for this specified major version.
    virtual int remapParamNameHigestMinorVersionNumber(int majorVersionNumber) const;
Don Gagne's avatar
Don Gagne committed
228 229 230 231 232 233

    /// @return true: Motors are coaxial like an X8 config, false: Quadcopter for example
    virtual bool multiRotorCoaxialMotors(Vehicle* vehicle) { Q_UNUSED(vehicle); return false; }

    /// @return true: X confiuration, false: Plus configuration
    virtual bool multiRotorXConfig(Vehicle* vehicle) { Q_UNUSED(vehicle); return false; }
234

235
    /// Returns a newly created geofence manager for this vehicle.
236 237 238 239
    virtual GeoFenceManager* newGeoFenceManager(Vehicle* vehicle) { return new GeoFenceManager(vehicle); }

    /// Returns the parameter which holds the fence circle radius if supported.
    virtual QString geoFenceRadiusParam(Vehicle* vehicle) { Q_UNUSED(vehicle); return QString(); }
240

241 242 243
    /// Returns a newly created rally point manager for this vehicle.
    virtual RallyPointManager* newRallyPointManager(Vehicle* vehicle) { return new RallyPointManager(vehicle); }

244 245
    /// Return the resource file which contains the set of params loaded for offline editing.
    virtual QString offlineEditingParamFile(Vehicle* vehicle) { Q_UNUSED(vehicle); return QString(); }
246 247 248

    /// Return the resource file which contains the brand image for the vehicle.
    virtual QString brandImage(const Vehicle* vehicle) const { Q_UNUSED(vehicle) return QString(); }
249

250 251 252 253 254 255 256 257 258
    /// Return the resource file which contains the vehicle icon used in the flight view when the view is dark (Satellite for instance)
    virtual QString vehicleImageOpaque(const Vehicle* vehicle) const;

    /// Return the resource file which contains the vehicle icon used in the flight view when the view is light (Map for instance)
    virtual QString vehicleImageOutline(const Vehicle* vehicle) const;

    /// Return the resource file which contains the vehicle icon used in the compass
    virtual QString vehicleImageCompass(const Vehicle* vehicle) const;

259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275
    // FIXME: Hack workaround for non pluginize FollowMe support
    static const char* px4FollowMeFlightMode;
};

class FirmwarePluginFactory : public QObject
{
    Q_OBJECT

public:
    FirmwarePluginFactory(void);

    /// Returns appropriate plugin for autopilot type.
    ///     @param autopilotType Type of autopilot to return plugin for.
    ///     @param vehicleType Vehicle type of autopilot to return plugin for.
    /// @return Singleton FirmwarePlugin instance for the specified MAV_AUTOPILOT.
    virtual FirmwarePlugin* firmwarePluginForAutopilot(MAV_AUTOPILOT autopilotType, MAV_TYPE vehicleType) = 0;

276 277 278 279 280
    /// @return List of firmware types this plugin supports.
    virtual QList<MAV_AUTOPILOT> supportedFirmwareTypes(void) const = 0;

    /// @return List of vehicle types this plugin supports.
    virtual QList<MAV_TYPE> supportedVehicleTypes(void) const;
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
};

class FirmwarePluginFactoryRegister : public QObject
{
    Q_OBJECT

public:
    static FirmwarePluginFactoryRegister* instance(void);

    /// Registers the specified logging category to the system.
    void registerPluginFactory(FirmwarePluginFactory* pluginFactory) { _factoryList.append(pluginFactory); }

    QList<FirmwarePluginFactory*> pluginFactories(void) const { return _factoryList; }

private:
    QList<FirmwarePluginFactory*> _factoryList;
Don Gagne's avatar
Don Gagne committed
297 298 299
};

#endif