src/Instrumentation/gps.hxx

   1 // gps.hxx - distance-measuring equipment.
   2 // Written by David Megginson, started 2003.
   3 //
   4 // This file is in the Public Domain and comes with no warranty.
   5
   6
   7 #ifndef __INSTRUMENTS_GPS_HXX
   8 #define __INSTRUMENTS_GPS_HXX 1
   9
  10 #include <cassert>
  11 #include <memory>
  12
  13 #include <simgear/props/props.hxx>
  14 #include <simgear/structure/subsystem_mgr.hxx>
  15 #include <simgear/props/tiedpropertylist.hxx>
  16
  17 #include <Navaids/positioned.hxx>
  18 #include <Instrumentation/rnav_waypt_controller.hxx>
  19
  20 // forward decls
  21 class SGRoute;
  22 class FGRouteMgr;
  23 class FGAirport;
  24 class GPSListener;
  25
  26 class SGGeodProperty
  27 {
  28 public:
  29     SGGeodProperty()
  30     {
  31     }
  32
  33     void init(SGPropertyNode* base, const char* lonStr, const char* latStr, const char* altStr = NULL);
  34     void init(const char* lonStr, const char* latStr, const char* altStr = NULL);
  35     void clear();
  36     void operator=(const SGGeod& geod);
  37     SGGeod get() const;
  38
  39 private:
  40     SGPropertyNode_ptr _lon, _lat, _alt;
  41 };
  42
  43 /**
  44  * Model a GPS radio.
  45  *
  46  * Input properties:
  47  *
  48  * /position/longitude-deg
  49  * /position/latitude-deg
  50  * /position/altitude-ft
  51  * /environment/magnetic-variation-deg
  52  * /systems/electrical/outputs/gps
  53  * /instrumentation/gps/serviceable
  54  *
  55  *
  56  * Output properties:
  57  *
  58  * /instrumentation/gps/indicated-longitude-deg
  59  * /instrumentation/gps/indicated-latitude-deg
  60  * /instrumentation/gps/indicated-altitude-ft
  61  * /instrumentation/gps/indicated-vertical-speed-fpm
  62  * /instrumentation/gps/indicated-track-true-deg
  63  * /instrumentation/gps/indicated-track-magnetic-deg
  64  * /instrumentation/gps/indicated-ground-speed-kt
  65  *
  66  * /instrumentation/gps/wp-distance-nm
  67  * /instrumentation/gps/wp-bearing-deg
  68  * /instrumentation/gps/wp-bearing-mag-deg
  69  * /instrumentation/gps/TTW
  70  * /instrumentation/gps/course-deviation-deg
  71  * /instrumentation/gps/course-error-nm
  72  * /instrumentation/gps/to-flag
  73  * /instrumentation/gps/odometer
  74  * /instrumentation/gps/trip-odometer
  75  * /instrumentation/gps/true-bug-error-deg
  76  * /instrumentation/gps/magnetic-bug-error-deg
  77  */
  78 class GPS : public SGSubsystem, public flightgear::RNAV
  79 {
  80 public:
  81     GPS (SGPropertyNode *node);
  82     GPS ();
  83     virtual ~GPS ();
  84
  85   // SGSubsystem interface
  86     virtual void init ();
  87     virtual void update (double delta_time_sec);
  88
  89     virtual void bind();
  90     virtual void unbind();
  91
  92   // RNAV interface
  93     virtual SGGeod position();
  94     virtual double trackDeg();
  95     virtual double groundSpeedKts();
  96     virtual double vspeedFPM();
  97     virtual double magvarDeg();
  98     virtual double selectedMagCourse();
  99     virtual double overflightArmDistanceM();
 100
 101 private:
 102     friend class GPSListener;
 103     friend class SearchFilter;
 104
 105     /**
 106      * Configuration manager, track data relating to aircraft installation
 107      */
 108     class Config
 109     {
 110     public:
 111       Config();
 112
 113       void bind(GPS* aOwner, SGPropertyNode* aCfg);
 114
 115       bool turnAnticipationEnabled() const { return _enableTurnAnticipation; }
 116
 117       /**
 118        * Desired turn rate in degrees/second. From this we derive the turn
 119        * radius and hence how early we need to anticipate it.
 120        */
 121       double turnRateDegSec() const        { return _turnRate; }
 122
 123       /**
 124        * Distance at which we arm overflight sequencing. Once inside this
 125        * distance, a change of the wp1 'TO' flag to false will be considered
 126        * overlight of the wp.
 127        */
 128       double overflightArmDistanceNm() const { return _overflightArmDistance; }
 129
 130       /**
 131        * Time before the next WP to activate an external annunciator
 132        */
 133       double waypointAlertTime() const     { return _waypointAlertTime; }
 134
 135       bool requireHardSurface() const      { return _requireHardSurface; }
 136
 137       bool cdiDeflectionIsAngular() const  { return (_cdiMaxDeflectionNm <= 0.0); }
 138
 139       double cdiDeflectionLinearPeg() const
 140       {
 141         assert(_cdiMaxDeflectionNm > 0.0);
 142         return _cdiMaxDeflectionNm;
 143       }
 144
 145       bool driveAutopilot() const          { return _driveAutopilot; }
 146
 147       bool courseSelectable() const        { return _courseSelectable; }
 148
 149     private:
 150       bool _enableTurnAnticipation;
 151
 152       // desired turn rate in degrees per second
 153       double _turnRate;
 154
 155       // distance from waypoint to arm overflight sequencing (in nm)
 156       double _overflightArmDistance;
 157
 158       // time before reaching a waypoint to trigger annunciator light/sound
 159       // (in seconds)
 160       double _waypointAlertTime;
 161
 162       // minimum runway length to require when filtering
 163       double _minRunwayLengthFt;
 164
 165       // should we require a hard-surfaced runway when filtering?
 166       bool _requireHardSurface;
 167
 168       double _cdiMaxDeflectionNm;
 169
 170       // should we drive the autopilot directly or not?
 171       bool _driveAutopilot;
 172
 173       // is selected-course-deg read to set desired-course or not?
 174       bool _courseSelectable;
 175     };
 176
 177     class SearchFilter : public FGPositioned::Filter
 178     {
 179     public:
 180       virtual bool pass(FGPositioned* aPos) const;
 181
 182       virtual FGPositioned::Type minType() const;
 183       virtual FGPositioned::Type maxType() const;
 184     };
 185
 186     /** reset all output properties to default / non-service values */
 187     void clearOutput();
 188
 189     void updateBasicData(double dt);
 190
 191     void updateTrackingBug();
 192     void updateReferenceNavaid(double dt);
 193     void referenceNavaidSet(const std::string& aNavaid);
 194     void updateRouteData();
 195     void driveAutopilot();
 196
 197     void routeActivated();
 198     void routeManagerSequenced();
 199     void routeEdited();
 200     void routeFinished();
 201
 202     void updateTurn();
 203     void updateOverflight();
 204     void beginTurn();
 205     void endTurn();
 206
 207     double computeTurnProgress(double aBearing) const;
 208     void computeTurnData();
 209     void updateTurnData();
 210     double computeTurnRadiusNm(double aGroundSpeedKts) const;
 211
 212     /** Update one-shot things when WP1 / leg data change */
 213     void wp1Changed();
 214
 215 // scratch maintenance utilities
 216     void setScratchFromPositioned(FGPositioned* aPos, int aIndex);
 217     void setScratchFromCachedSearchResult();
 218     void setScratchFromRouteWaypoint(int aIndex);
 219
 220     /** Add airport-specific information to a scratch result */
 221     void addAirportToScratch(FGAirport* aAirport);
 222
 223     void clearScratch();
 224
 225     /** Predicate, determine if the lon/lat position in the scratch is
 226      * valid or not. */
 227     bool isScratchPositionValid() const;
 228
 229     FGPositioned::Filter* createFilter(FGPositioned::Type aTy);
 230
 231    /** Search kernel - called each time we step through a result */
 232     void performSearch();
 233
 234 // command handlers
 235     void selectLegMode();
 236     void selectOBSMode();
 237     void directTo();
 238     void loadRouteWaypoint();
 239     void loadNearest();
 240     void search();
 241     void nextResult();
 242     void previousResult();
 243     void defineWaypoint();
 244     void insertWaypointAtIndex(int aIndex);
 245     void removeWaypointAtIndex(int aIndex);
 246
 247 // tied-property getter/setters
 248     void setCommand(const char* aCmd);
 249     const char* getCommand() const { return ""; }
 250
 251     const char* getMode() const { return _mode.c_str(); }
 252
 253     bool getScratchValid() const { return _scratchValid; }
 254     double getScratchDistance() const;
 255     double getScratchMagBearing() const;
 256     double getScratchTrueBearing() const;
 257     bool getScratchHasNext() const;
 258
 259     double getSelectedCourse() const { return _selectedCourse; }
 260     void setSelectedCourse(double crs);
 261     double getDesiredCourse() const { return _desiredCourse; }
 262
 263     double getCDIDeflection() const;
 264
 265     double getLegDistance() const;
 266     double getLegCourse() const;
 267     double getLegMagCourse() const;
 268
 269     double getTrueTrack() const { return _last_true_track; }
 270     double getMagTrack() const;
 271     double getGroundspeedKts() const { return _last_speed_kts; }
 272     double getVerticalSpeed() const { return _last_vertical_speed; }
 273
 274     //bool getLegMode() const { return _mode == "leg"; }
 275     //bool getObsMode() const { return _mode == "obs"; }
 276
 277     const char* getWP0Ident() const;
 278     const char* getWP0Name() const;
 279
 280     const char* getWP1Ident() const;
 281     const char* getWP1Name() const;
 282
 283     double getWP1Distance() const;
 284     double getWP1TTW() const;
 285     const char* getWP1TTWString() const;
 286     double getWP1Bearing() const;
 287     double getWP1MagBearing() const;
 288     double getWP1CourseDeviation() const;
 289     double getWP1CourseErrorNm() const;
 290     bool getWP1ToFlag() const;
 291     bool getWP1FromFlag() const;
 292
 293     // true-bearing-error and mag-bearing-error
 294
 295
 296     /**
 297      * Tied-properties helper, record nodes which are tied for easy un-tie-ing
 298      */
 299     template <typename T>
 300     void tie(SGPropertyNode* aNode, const char* aRelPath, const SGRawValue<T>& aRawValue)
 301     {
 302         _tiedProperties.Tie(aNode->getNode(aRelPath, true), aRawValue);
 303     }
 304
 305     /** helper, tie the lat/lon/elev of a SGGeod to the named children of aNode */
 306     void tieSGGeod(SGPropertyNode* aNode, SGGeod& aRef,
 307                    const char* lonStr, const char* latStr, const char* altStr);
 308
 309     /** helper, tie a SGGeod to proeprties, but read-only */
 310     void tieSGGeodReadOnly(SGPropertyNode* aNode, SGGeod& aRef,
 311                            const char* lonStr, const char* latStr, const char* altStr);
 312
 313 // members
 314     SGPropertyNode_ptr _gpsNode;
 315     SGPropertyNode_ptr _currentWayptNode;
 316     SGPropertyNode_ptr _magvar_node;
 317     SGPropertyNode_ptr _serviceable_node;
 318     SGPropertyNode_ptr _electrical_node;
 319     SGPropertyNode_ptr _tracking_bug_node;
 320     SGPropertyNode_ptr _raim_node;
 321
 322     SGPropertyNode_ptr _odometer_node;
 323     SGPropertyNode_ptr _trip_odometer_node;
 324     SGPropertyNode_ptr _true_bug_error_node;
 325     SGPropertyNode_ptr _magnetic_bug_error_node;
 326     SGPropertyNode_ptr _eastWestVelocity;
 327     SGPropertyNode_ptr _northSouthVelocity;
 328
 329     SGPropertyNode_ptr _ref_navaid_id_node;
 330     SGPropertyNode_ptr _ref_navaid_bearing_node;
 331     SGPropertyNode_ptr _ref_navaid_distance_node;
 332     SGPropertyNode_ptr _ref_navaid_mag_bearing_node;
 333     SGPropertyNode_ptr _ref_navaid_frequency_node;
 334     SGPropertyNode_ptr _ref_navaid_name_node;
 335
 336     SGPropertyNode_ptr _route_active_node;
 337     SGPropertyNode_ptr _route_current_wp_node;
 338     SGPropertyNode_ptr _routeDistanceNm;
 339     SGPropertyNode_ptr _routeETE;
 340     SGPropertyNode_ptr _routeEditedSignal;
 341     SGPropertyNode_ptr _routeFinishedSignal;
 342     SGPropertyNode_ptr _desiredCourseNode;
 343
 344     double _selectedCourse;
 345     double _desiredCourse;
 346
 347     bool _dataValid;
 348     SGGeod _last_pos;
 349     bool _lastPosValid;
 350     double _last_speed_kts;
 351     double _last_true_track;
 352     double _last_vertical_speed;
 353     double _lastEWVelocity;
 354     double _lastNSVelocity;
 355
 356     std::string _mode;
 357     GPSListener* _listener;
 358     Config _config;
 359     FGRouteMgr* _routeMgr;
 360
 361     bool _ref_navaid_set;
 362     double _ref_navaid_elapsed;
 363     FGPositionedRef _ref_navaid;
 364
 365     std::string _name;
 366     int _num;
 367
 368     SGGeodProperty _position;
 369     SGGeod _wp0_position;
 370     SGGeod _indicated_pos;
 371     double _legDistanceNm;
 372
 373 // scratch data
 374     SGGeod _scratchPos;
 375     SGPropertyNode_ptr _scratchNode;
 376     bool _scratchValid;
 377
 378 // search data
 379     int _searchResultIndex;
 380     std::string _searchQuery;
 381     FGPositioned::Type _searchType;
 382     bool _searchExact;
 383     FGPositioned::List _searchResults;
 384     bool _searchIsRoute; ///< set if 'search' is actually the current route
 385     bool _searchHasNext; ///< is there a result after this one?
 386     bool _searchNames; ///< set if we're searching names instead of idents
 387
 388 // turn data
 389     bool _computeTurnData; ///< do we need to update the turn data?
 390     bool _anticipateTurn; ///< are we anticipating the next turn or not?
 391     bool _inTurn; // is a turn in progress?
 392     bool _turnSequenced; // have we sequenced the new leg?
 393     double _turnAngle; // angle to turn through, in degrees
 394     double _turnStartBearing; // bearing of inbound leg
 395     double _turnRadius; // radius of turn in nm
 396     SGGeod _turnPt;
 397     SGGeod _turnCentre;
 398
 399     std::auto_ptr<flightgear::WayptController> _wayptController;
 400
 401     SGPropertyNode_ptr _realismSimpleGps; ///< should the GPS be simple or realistic?
 402     flightgear::WayptRef _prevWaypt;
 403     flightgear::WayptRef _currentWaypt;
 404
 405 // autopilot drive properties
 406     SGPropertyNode_ptr _apDrivingFlag;
 407     SGPropertyNode_ptr _apTrueHeading;
 408     SGPropertyNode_ptr _apTargetAltitudeFt;
 409     SGPropertyNode_ptr _apAltitudeLock;
 410
 411     simgear::TiedPropertyList _tiedProperties;
 412
 413 };
 414
 415 #endif // __INSTRUMENTS_GPS_HXX