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