FirmwarePlugin.h 19.3 KB
Newer Older
1 2
/****************************************************************************
 *
Gus Grubba's avatar
Gus Grubba committed
3
 * (c) 2009-2020 QGROUNDCONTROL PROJECT <http://www.qgroundcontrol.org>
4 5 6 7 8 9
 *
 * 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"
22
#include "FollowMe.h"
Don Gagne's avatar
Don Gagne committed
23 24 25

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

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

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

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

public:
    /// Set of optional capabilites which firmware may support
    typedef enum {
Don Gagne's avatar
Don Gagne committed
46
        SetFlightModeCapability =           1 << 0, ///< FirmwarePlugin::setFlightMode method is supported
47 48 49 50
        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
51
        ROIModeCapability =                 1 << 5, ///< Vehicle supports ROI (both in Fly guided mode and from Plan creation)
Don Gagne's avatar
Don Gagne committed
52
    } FirmwareCapabilities;
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67

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

Patrick José Pereira's avatar
Patrick José Pereira committed
69
    /// @return The AutoPilotPlugin associated with this firmware plugin. Must be overridden.
70 71
    virtual AutoPilotPlugin* autopilotPlugin(Vehicle* vehicle);

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

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

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

84 85 86 87 88
    /// Returns the list of available flight modes for the Fly View dropdown. This may or may not be the full
    /// list available from the firmware. Call will be made again if advanced mode changes.
    virtual QStringList flightModes(Vehicle* /*vehicle*/) { return QStringList(); }

    /// Returns the list of additional flight modes to add to the list for joystick button actions.
89
    /// Call will be made again if advanced mode changes.
90
    virtual QStringList extraJoystickFlightModes(Vehicle* /*vehicle*/) { return QStringList(); }
91

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

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

102 103 104 105 106 107 108 109 110
    /// 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(); }

DonLakeFlyer's avatar
DonLakeFlyer committed
111 112 113 114 115
    /// Returns the flight mode for Smart RTL
    virtual QString smartRTLFlightMode(void) const { return QString(); }

    virtual bool supportsSmartRTL(void) const { return false; }

116 117 118 119 120 121
    /// 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
122 123 124
    /// Returns whether the vehicle is in guided mode or not.
    virtual bool isGuidedMode(const Vehicle* vehicle) const;

Don Gagne's avatar
Don Gagne committed
125 126 127
    /// Returns the flight mode which the vehicle will be in if it is performing a goto location
    virtual QString gotoFlightMode(void) const;

128
    /// Returns the flight mode which the vehicle will be for follow me
129
    virtual QString followFlightMode(void) const { return QString(); }
130

Don Gagne's avatar
Don Gagne committed
131 132 133 134 135 136 137 138
    /// 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
DonLakeFlyer's avatar
DonLakeFlyer committed
139
    virtual void guidedModeRTL(Vehicle* vehicle, bool smartRTL);
Don Gagne's avatar
Don Gagne committed
140 141 142 143

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

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

147
    /// @return The minimum takeoff altitude (relative) for guided takeoff.
148
    virtual double minimumTakeoffAltitude(Vehicle* /*vehicle*/) { return 10; }
149

150 151
    /// Command the vehicle to start the mission
    virtual void startMission(Vehicle* vehicle);
Don Gagne's avatar
Don Gagne committed
152 153 154 155

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

156 157 158
    /// 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);
159

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

164 165 166 167 168
    /// 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);

169 170
    /// Returns true if the vehicle and firmware supports the use of negative thrust
    /// Typically supported rover.
171
    virtual bool supportsNegativeThrust(Vehicle *);
172

173 174 175 176
    /// 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);

177 178 179 180
    /// 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);

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

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

201 202 203 204 205 206
    /// 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
207
    virtual bool sendHomePositionToVehicle(void);
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.
213
    /// Note: The implementation for this must not vary by vehicle type.
214 215 216
    virtual void getParameterMetaDataVersionInfo(const QString& metaDataFile, int& majorVersion, int& minorVersion);

    /// Returns the internal resource parameter meta date file.
217
    virtual QString internalParameterMetaDataFile(Vehicle* /*vehicle*/) { return QString(); }
218 219

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

224 225 226
    /// Returns the FactMetaData associated with the parameter name
    ///     @param opaqueParameterMetaData Opaque pointer returned from loadParameterMetaData
    ///     @param name Parameter name
227
    virtual FactMetaData* getMetaDataForFact(QObject* /*parameterMetaData*/, const QString& /*name*/, MAV_TYPE /*vehicleType*/) { return nullptr; }
228

229
    /// Adds the parameter meta data to the Fact
230
    ///     @param opaqueParameterMetaData Opaque pointer returned from loadParameterMetaData
231
    virtual void addMetaDataToFact(QObject* /*parameterMetaData*/, Fact* /*fact*/, MAV_TYPE /*vehicleType*/) { return; }
Don Gagne's avatar
Don Gagne committed
232 233

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

236 237 238
    /// 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;
239

240 241 242 243 244
    /// 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
245 246

    /// @return true: Motors are coaxial like an X8 config, false: Quadcopter for example
247
    virtual bool multiRotorCoaxialMotors(Vehicle* /*vehicle*/) { return false; }
Don Gagne's avatar
Don Gagne committed
248 249

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

252
    /// Return the resource file which contains the set of params loaded for offline editing.
253
    virtual QString offlineEditingParamFile(Vehicle* /*vehicle*/) { return QString(); }
254

255
    /// Return the resource file which contains the brand image for the vehicle for Indoor theme.
256
    virtual QString brandImageIndoor(const Vehicle* /*vehicle*/) const { return QString(); }
257 258

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

261 262 263 264 265 266 267 268 269
    /// 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;

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

275
    /// Returns a list of CameraMetaData objects for available cameras on the vehicle.
276
    /// TODO: This should go into QGCCameraManager
277 278
    virtual const QVariantList& cameraList(const Vehicle* vehicle);

279
    /// Creates vehicle camera manager.
280
    virtual QGCCameraManager* createCameraManager(Vehicle *vehicle);
281

282 283
    /// Camera control.
    virtual QGCCameraControl* createCameraControl(const mavlink_camera_information_t* info, Vehicle* vehicle, int compID, QObject* parent = nullptr);
284

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

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

291 292 293 294
    /// 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
295
    virtual void batteryConsumptionData(Vehicle* vehicle, int& mAhBattery, double& hoverAmps, double& cruiseAmps) const;
296

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

300 301 302 303 304 305 306
    /// 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);

307 308 309
    /// Returns true if the vehicle is a VTOL
    virtual bool isVtol(const Vehicle* vehicle) const;

310 311 312
    /// Convert from HIGH_LATENCY2.custom_mode value to correct 32 bit value.
    virtual uint32_t highLatencyCustomModeTo32Bits(uint16_t hlCustomMode);

313 314 315
    /// Used to check if running firmware is latest stable version.
    virtual void checkIfIsLatestStable(Vehicle* vehicle);

316 317 318 319 320
    /// Used to check if running current version is equal or higher than the one being compared.
    /// returns 1 if current > compare, 0 if current == compare, -1 if current < compare
    int versionCompare(Vehicle* vehicle, QString& compare);
    int versionCompare(Vehicle* vehicle, int major, int minor, int patch);

321 322 323
    /// Allows the Firmware plugin to override the facts meta data.
    ///     @param vehicleType - Type of current vehicle
    ///     @param metaData - MetaData for fact
324
    virtual void adjustMetaData(MAV_TYPE /*vehicleType*/, FactMetaData* /*metaData*/) {}
325

326 327 328
    /// Sends the appropriate mavlink message for follow me support
    virtual void sendGCSMotionReport(Vehicle* vehicle, FollowMe::GCSMotionReport& motionReport, uint8_t estimatationCapabilities);

329
    // FIXME: Hack workaround for non pluginize FollowMe support
330
    static const QString px4FollowMeFlightMode;
331

332 333 334
signals:
    void toolbarIndicatorsChanged(void);

335
protected:
336
    // Arms the vehicle with validation and retries
337
    // @return: true - vehicle armed, false - vehicle failed to arm
338
    bool _armVehicleAndValidate(Vehicle* vehicle);
339

340 341 342 343
    // 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);

344
    // returns url with latest firmware release information.
345
    virtual QString _getLatestVersionFileUrl(Vehicle* /*vehicle*/) { return QString(); }
346 347 348 349 350 351 352

    // Callback to process file with latest release information
    virtual void _versionFileDownloadFinished(QString& remoteFile, QString& localFile, Vehicle* vehicle);

    // Returns regex QString to extract version information from text
    virtual QString _versionRegex() { return QString(); }

353
private:
354
    QVariantList _toolBarIndicatorList;
355
    static QVariantList _cameraList;    ///< Standard QGC camera list
356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
};

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;

371 372 373 374 375
    /// @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;
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391
};

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
392 393 394
};

#endif