FirmwarePlugin.h 18 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

#include <QList>
#include <QString>
25
#include <QVariantList>
Don Gagne's avatar
Don Gagne committed
26

27
class Vehicle;
28 29
class QGCCameraControl;
class QGCCameraManager;
30

Don Gagne's avatar
Don Gagne committed
31 32
/// This is the base class for Firmware specific plugins
///
33 34 35 36
/// 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
37

38
class FirmwarePlugin : public QObject
Don Gagne's avatar
Don Gagne committed
39 40 41 42 43 44
{
    Q_OBJECT

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

    /// 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;
66

67
    /// @return The AutoPilotPlugin associated with this firmware plugin. Must be overridden.
68 69
    virtual AutoPilotPlugin* autopilotPlugin(Vehicle* vehicle);

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

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

Don Gagne's avatar
Don Gagne committed
76 77 78 79
    /// 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.
80
    virtual QList<VehicleComponent*> componentsForVehicle(AutoPilotPlugin* vehicle);
81

82 83
    /// Returns the list of available flight modes. Flight modes can be different in normal/advanced ui mode.
    /// Call will be made again if advanced mode changes.
84
    virtual QStringList flightModes(Vehicle* vehicle) {
85 86 87 88
        Q_UNUSED(vehicle);
        return QStringList();
    }

Don Gagne's avatar
Don Gagne committed
89 90 91
    /// 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
92
    virtual QString flightMode(uint8_t base_mode, uint32_t custom_mode) const;
93

Don Gagne's avatar
Don Gagne committed
94 95 96
    /// 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
97
    virtual bool setFlightMode(const QString& flightMode, uint8_t* base_mode, uint32_t* custom_mode);
Don Gagne's avatar
Don Gagne committed
98

99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
    /// Returns The flight mode which indicates the vehicle is paused
    virtual QString pauseFlightMode(void) const { return QString(); }

    /// Returns the flight mode for running missions
    virtual QString missionFlightMode(void) const { return QString(); }

    /// Returns the flight mode for RTL
    virtual QString rtlFlightMode(void) const { return QString(); }

    /// Returns the flight mode for Land
    virtual QString landFlightMode(void) const { return QString(); }

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

Don Gagne's avatar
Don Gagne committed
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
    /// 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);

    /// 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);

130
    /// Command vehicle to takeoff from current location to a firmware specific height.
131
    virtual void guidedModeTakeoff(Vehicle* vehicle, double takeoffAltRel);
132

133 134 135
    /// @return The minimum takeoff altitude (relative) for guided takeoff.
    virtual double minimumTakeoffAltitude(Vehicle* vehicle) { Q_UNUSED(vehicle); return 10; }

136 137
    /// Command the vehicle to start the mission
    virtual void startMission(Vehicle* vehicle);
Don Gagne's avatar
Don Gagne committed
138 139 140 141

    /// Command vehicle to move to specified location (altitude is included and relative)
    virtual void guidedModeGotoLocation(Vehicle* vehicle, const QGeoCoordinate& gotoCoord);

142 143 144
    /// Command vehicle to change altitude
    ///     @param altitudeChange If > 0, go up by amount specified, if < 0, go down by amount specified
    virtual void guidedModeChangeAltitude(Vehicle* vehicle, double altitudeChange);
145

146
    /// FIXME: This isn't quite correct being here. All code for Joystick suvehicleTypepport is currently firmware specific
Don Gagne's avatar
Don Gagne committed
147
    /// not just this. I'm going to try to change that. If not, this will need to be removed.
148 149 150 151
    /// 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
152
    virtual int manualControlReservedButtonCount(void);
153

154 155 156 157
    /// 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);

158 159 160 161 162
    /// 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);

163 164 165 166
    /// Returns true if the vehicle and firmware supports the use of negative thrust
    /// Typically supported rover.
    virtual bool supportsNegativeThrust(void);

167 168 169 170
    /// 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);

171 172 173 174
    /// 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);

175 176 177 178
    /// Returns true if the firmware supports calibrating motor interference offsets for the compass
    /// (CompassMot). Default is true.
    virtual bool supportsMotorInterference(void);

179 180 181
    /// Returns true if the firmware supports MAV_FRAME_GLOBAL_TERRAIN_ALT
    virtual bool supportsTerrainFrame(void) const;

182
    /// Called before any mavlink message is processed by Vehicle such that the firmwre plugin
Don Gagne's avatar
Don Gagne committed
183 184
    /// 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.
185
    ///     @param vehicle Vehicle message came from
Don Gagne's avatar
Don Gagne committed
186
    ///     @param message[in,out] Mavlink message to adjust if needed.
187 188
    /// @return false: skip message, true: process message
    virtual bool adjustIncomingMavlinkMessage(Vehicle* vehicle, mavlink_message_t* message);
189

Don Gagne's avatar
Don Gagne committed
190 191 192 193
    /// 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
194
    ///     @param outgoingLink Link that messae is going out on
Don Gagne's avatar
Don Gagne committed
195
    ///     @param message[in,out] Mavlink message to adjust if needed.
196
    virtual void adjustOutgoingMavlinkMessage(Vehicle* vehicle, LinkInterface* outgoingLink, mavlink_message_t* message);
Don Gagne's avatar
Don Gagne committed
197

198 199 200 201 202 203
    /// 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
204
    virtual bool sendHomePositionToVehicle(void);
205

206 207 208 209 210 211 212
    /// 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.
213
    virtual QString internalParameterMetaDataFile(Vehicle* vehicle) { Q_UNUSED(vehicle); return QString(); }
214 215

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

220 221 222 223 224
    /// Returns the FactMetaData associated with the parameter name
    ///     @param opaqueParameterMetaData Opaque pointer returned from loadParameterMetaData
    ///     @param name Parameter name
    virtual FactMetaData* getMetaDataForFact(QObject* parameterMetaData, const QString& name, MAV_TYPE vehicleType) { Q_UNUSED(parameterMetaData); Q_UNUSED(name); Q_UNUSED(vehicleType); return NULL; }

225
    /// Adds the parameter meta data to the Fact
226 227
    ///     @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; }
228 229

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

232 233 234
    /// 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;
235

236 237 238 239 240
    /// 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;
241 242 243 244 245 246

    /// @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; }
247

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

251 252 253 254 255
    /// Return the resource file which contains the brand image for the vehicle for Indoor theme.
    virtual QString brandImageIndoor(const Vehicle* vehicle) const { Q_UNUSED(vehicle) return QString(); }

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

257 258 259 260 261 262 263 264 265
    /// 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;

266
    /// Allows the core plugin to override the toolbar indicators
267
    ///     signals toolbarIndicatorsChanged
268
    /// @return A list of QUrl with the indicators (see MainToolBarIndicators.qml)
269
    virtual const QVariantList& toolBarIndicators(const Vehicle* vehicle);
270

271
    /// Returns a list of CameraMetaData objects for available cameras on the vehicle.
272
    /// TODO: This should go into QGCCameraManager
273 274
    virtual const QVariantList& cameraList(const Vehicle* vehicle);

275 276
    /// Creates vehicle camera manager. Returns NULL if not supported.
    virtual QGCCameraManager* createCameraManager(Vehicle *vehicle);
277 278 279 280

    /// Camera control. Returns NULL if not supported.
    virtual QGCCameraControl* createCameraControl(const mavlink_camera_information_t* info, Vehicle* vehicle, int compID, QObject* parent = NULL);

281 282
    /// Returns a pointer to a dictionary of firmware-specific FactGroups
    virtual QMap<QString, FactGroup*>* factGroups(void);
283

284 285 286
    /// @true: When flying a mission the vehicle is always facing towards the next waypoint
    virtual bool vehicleYawsToNextWaypointInMission(const Vehicle* vehicle) const;

287 288 289 290
    /// Returns the data needed to do battery consumption calculations
    ///     @param[out] mAhBattery Battery milliamp-hours rating (0 for no battery data available)
    ///     @param[out] hoverAmps Current draw in amps during hover
    ///     @param[out] cruiseAmps Current draw in amps during cruise
Don Gagne's avatar
Don Gagne committed
291
    virtual void batteryConsumptionData(Vehicle* vehicle, int& mAhBattery, double& hoverAmps, double& cruiseAmps) const;
292

293
    // Returns the parameter which control auto-disarm. Assume == 0 means no auto disarm
294 295
    virtual QString autoDisarmParameter(Vehicle* vehicle);

296 297 298 299 300 301 302
    /// Used to determine whether a vehicle has a gimbal.
    ///     @param[out] rollSupported Gimbal supports roll
    ///     @param[out] pitchSupported Gimbal supports pitch
    ///     @param[out] yawSupported Gimbal supports yaw
    /// @return true: vehicle has gimbal, false: gimbal support unknown
    virtual bool hasGimbal(Vehicle* vehicle, bool& rollSupported, bool& pitchSupported, bool& yawSupported);

303 304 305
    /// Returns true if the vehicle is a VTOL
    virtual bool isVtol(const Vehicle* vehicle) const;

306 307 308
    /// Convert from HIGH_LATENCY2.custom_mode value to correct 32 bit value.
    virtual uint32_t highLatencyCustomModeTo32Bits(uint16_t hlCustomMode);

309
    // FIXME: Hack workaround for non pluginize FollowMe support
310
    static const QString px4FollowMeFlightMode;
311

312 313 314
signals:
    void toolbarIndicatorsChanged(void);

315
protected:
316
    // Arms the vehicle with validation and retries
317
    // @return: true - vehicle armed, false - vehicle failed to arm
318
    bool _armVehicleAndValidate(Vehicle* vehicle);
319

320 321 322 323
    // Sets the vehicle to the specified flight mode with validation and retries
    // @return: true - vehicle in specified flight mode, false - flight mode change failed
    bool _setFlightModeAndValidate(Vehicle* vehicle, const QString& flightMode);

324
private:
325
    QVariantList _toolBarIndicatorList;
326
    static QVariantList _cameraList;    ///< Standard QGC camera list
327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
};

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;

342 343 344 345 346
    /// @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;
347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
};

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
363 364 365
};

#endif