src/Instrumentation/tcas.hxx

   1 // tcas.hxx -- Traffic Alert and Collision Avoidance System (TCAS)
   2 //
   3 // Written by Thorsten Brehm, started December 2010.
   4 //
   5 // Copyright (C) 2010 Thorsten Brehm - brehmt (at) gmail com
   6 //
   7 // This program is free software; you can redistribute it and/or
   8 // modify it under the terms of the GNU General Public License as
   9 // published by the Free Software Foundation; either version 2 of the
  10 // License, or (at your option) any later version.
  11 //
  12 // This program is distributed in the hope that it will be useful, but
  13 // WITHOUT ANY WARRANTY; without even the implied warranty of
  14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 // General Public License for more details.
  16 //
  17 // You should have received a copy of the GNU General Public License
  18 // along with this program; if not, write to the Free Software
  19 // Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20
  21 #ifndef __INSTRUMENTS_TCAS_HXX
  22 #define __INSTRUMENTS_TCAS_HXX
  23
  24 #include <assert.h>
  25
  26 #include <vector>
  27 #include <deque>
  28 #include <map>
  29
  30 #include <simgear/props/props.hxx>
  31 #include <simgear/sound/sample_openal.hxx>
  32 #include <simgear/structure/subsystem_mgr.hxx>
  33 #include "mk_viii.hxx" // FGVoicePlayer only
  34
  35 using std::vector;
  36 using std::deque;
  37 using std::map;
  38
  39 class SGSampleGroup;
  40
  41 #include <Main/globals.hxx>
  42
  43 #ifdef _MSC_VER
  44 #  pragma warning( push )
  45 #  pragma warning( disable: 4355 )
  46 #endif
  47
  48 ///////////////////////////////////////////////////////////////////////////////
  49 // TCAS  //////////////////////////////////////////////////////////////////////
  50 ///////////////////////////////////////////////////////////////////////////////
  51
  52 class TCAS : public SGSubsystem
  53 {
  54
  55     typedef enum
  56     {
  57         AdvisoryClear         = 0,                          /*< Clear of traffic */
  58         AdvisoryIntrusion     = 1,                          /*< Intrusion flag */
  59         AdvisoryClimb         = AdvisoryIntrusion|(1 << 1), /*< RA climb */
  60         AdvisoryDescend       = AdvisoryIntrusion|(1 << 2), /*< RA descend */
  61         AdvisoryAdjustVSpeed  = AdvisoryIntrusion|(1 << 3), /*< RA adjust vertical speed (TCAS II 7.0 only) */
  62         AdvisoryMaintVSpeed   = AdvisoryIntrusion|(1 << 4), /*< RA maintain vertical speed */
  63         AdvisoryMonitorVSpeed = AdvisoryIntrusion|(1 << 5), /*< RA monitor vertical speed */
  64         AdvisoryLevelOff      = AdvisoryIntrusion|(1 << 6)  /*< RA level off (TCAS II 7.1 only) */
  65     } EnumAdvisory;
  66
  67     typedef enum
  68     {
  69         OptionNone            = 0,        /*< no option modifier */
  70         OptionIncreaseClimb   = (1 << 0), /*< increase climb */
  71         OptionIncreaseDescend = (1 << 1), /*< increase descend */
  72         OptionCrossingClimb   = (1 << 2), /*< crossing climb */
  73         OptionCrossingDescent = (1 << 3)  /*< crossing descent */
  74     } EnumAdvisoryOption;
  75
  76     typedef enum
  77     {
  78         SwitchOff        = 0, /*< TCAS switched off */
  79         SwitchStandby    = 1, /*< TCAS standby (no TA/RA) */
  80         SwitchTaOnly     = 2, /*< TCAS in TA-only mode (no RA) */
  81         SwitchAuto       = 3  /*< TCAS in TA/RA mode */
  82     } EnumModeSwitch;
  83
  84     typedef enum
  85     {
  86         ThreatInvisible    = -1,/*< Traffic is invisible to TCAS (i.e. no transponder) */
  87         ThreatNone         = 0, /*< Traffic is visible but no threat. */
  88         ThreatProximity    = 1, /*< Proximity intruder traffic (no threat). */
  89         ThreatTA           = 2, /*< TA-level threat traffic. */
  90         ThreatRA           = 3  /*< RA-level threat traffic. */
  91     } EnumThreatLevel;
  92
  93     typedef struct
  94     {
  95       int  threatLevel;  /*< intruder threat level: 0=clear, 1=proximity,
  96                              2=intruder, 3=proximity intruder */
  97       int  RA;           /*< resolution advisory */
  98       int  RAOption;     /*< option flags for advisory */
  99     } ResolutionAdvisory;
 100
 101     typedef struct
 102     {
 103         float Tau;       /*< vertical/horizontal protection range in seconds */
 104         float DMOD;      /*< horizontal protection range in nm */
 105         float ALIM;      /*< vertical protection range in ft */
 106     } Thresholds;
 107
 108     typedef struct
 109     {
 110         double    maxAltitude; /*< max altitude for this sensitivity level */
 111         int        sl;         /*< sensitivity level */
 112         Thresholds TA;         /*< thresholds for TA-level threats */
 113         Thresholds RA;         /*< thresholds for RA-level threats */
 114     } SensitivityLevel;
 115
 116     typedef struct
 117     {
 118         string callsign;
 119         bool   verticalTA;
 120         bool   verticalRA;
 121         bool   horizontalTA;
 122         bool   horizontalRA;
 123         bool   isTracked;
 124         float  horizontalTau;
 125         float  verticalTau;
 126         float  relativeAltitudeFt;
 127         float  verticalFps;
 128         int    RASense;
 129     } ThreatInfo;
 130
 131     typedef struct
 132     {
 133         int    threatLevel;
 134         double TAtimestamp;
 135         double RAtimestamp;
 136     } TrackerTarget;
 137
 138     typedef map<string,TrackerTarget*> TrackerTargets;
 139
 140     typedef struct
 141     {
 142         double lat;
 143         double lon;
 144         float  altFt;
 145         float  heading;
 146         float  velocityKt;
 147         float  verticalFps;
 148     } LocalInfo; /*< info structure for local aircraft */
 149
 150 //    /////////////////////////////////////////////////////////////////////////////
 151 //    // TCAS::Timer //////////////////////////////////////////////////////////////
 152 //    /////////////////////////////////////////////////////////////////////////////
 153 //
 154 //    class Timer
 155 //    {
 156 //        double start_time;
 157 //
 158 //    public:
 159 //        bool   running;
 160 //
 161 //        inline Timer ()
 162 //          : running(false) {}
 163 //
 164 //        inline void start () { running = true; start_time = globals->get_sim_time_sec(); }
 165 //        inline void stop ()  { running = false; }
 166 //        inline double elapsed () const { assert(running); return globals->get_sim_time_sec() - start_time; }
 167 //        inline double start_or_elapsed ()
 168 //        {
 169 //            if (running)
 170 //                return elapsed();
 171 //            else
 172 //            {
 173 //                start();
 174 //                return 0;
 175 //            }
 176 //        }
 177 //    };
 178
 179     /////////////////////////////////////////////////////////////////////////////
 180     // TCAS::PropertiesHandler ///////////////////////////////////////////////
 181     /////////////////////////////////////////////////////////////////////////////
 182
 183     class PropertiesHandler : public FGVoicePlayer::PropertiesHandler
 184     {
 185       TCAS *tcas;
 186
 187     public:
 188       PropertiesHandler (TCAS *device) :
 189         FGVoicePlayer::PropertiesHandler(), tcas(device) {}
 190
 191       PropertiesHandler (void) : FGVoicePlayer::PropertiesHandler() {}
 192     };
 193
 194     /////////////////////////////////////////////////////////////////////////////
 195     // TCAS::VoicePlayer ////////////////////////////////////////////////////////
 196     /////////////////////////////////////////////////////////////////////////////
 197
 198     class VoicePlayer :
 199         public FGVoicePlayer
 200     {
 201     public:
 202         VoicePlayer (TCAS* tcas) :
 203           FGVoicePlayer(&tcas->properties_handler, "tcas") {}
 204
 205         ~VoicePlayer (void) {}
 206
 207         void init    (void);
 208
 209         struct
 210         {
 211           Voice* pTrafficTraffic;
 212           Voice* pClimb;
 213           Voice* pClimbNow;
 214           Voice* pClimbCrossing;
 215           Voice* pClimbIncrease;
 216           Voice* pDescend;
 217           Voice* pDescendNow;
 218           Voice* pDescendCrossing;
 219           Voice* pDescendIncrease;
 220           Voice* pClear;
 221           Voice* pAdjustVSpeed;
 222           Voice* pMaintVSpeed;
 223           Voice* pMonitorVSpeed;
 224           Voice* pLevelOff;
 225           Voice* pTestOk;
 226           Voice* pTestFail;
 227         } Voices;
 228     private:
 229         SGPropertyNode_ptr nodeSoundFilePrefix;
 230     };
 231
 232     /////////////////////////////////////////////////////////////////////////////
 233     // TCAS::Annunciator ////////////////////////////////////////////////////////
 234     /////////////////////////////////////////////////////////////////////////////
 235
 236     class Annunciator
 237     {
 238     public:
 239         Annunciator    (TCAS* tcas);
 240         ~Annunciator   (void) {}
 241         void bind      (SGPropertyNode* node);
 242         void init      (void);
 243         void update    (void);
 244
 245         void trigger   (const ResolutionAdvisory& newAdvisory, bool revertedRA);
 246         void test      (bool testOk);
 247         void clear     (void);
 248         bool isPlaying (void) { return voicePlayer.is_playing();}
 249
 250     private:
 251         TCAS* tcas;
 252         ResolutionAdvisory previous;
 253         FGVoicePlayer::Voice* pLastVoice;
 254         VoicePlayer voicePlayer;
 255         SGPropertyNode_ptr nodeGpwsAlertOn;
 256     };
 257
 258     /////////////////////////////////////////////////////////////////////////////
 259     // TCAS::AdvisoryCoordinator ////////////////////////////////////////////////
 260     /////////////////////////////////////////////////////////////////////////////
 261
 262     class AdvisoryCoordinator
 263     {
 264     public:
 265         AdvisoryCoordinator  (TCAS* _tcas);
 266         ~AdvisoryCoordinator (void) {}
 267
 268         void bind            (SGPropertyNode* node);
 269         void init            (void);
 270         void update          (int mode);
 271
 272         void clear           (void);
 273         void add             (const ResolutionAdvisory& newAdvisory);
 274
 275     private:
 276         TCAS* tcas;
 277         double lastTATime;
 278         ResolutionAdvisory current;
 279         ResolutionAdvisory previous;
 280         SGPropertyNode_ptr nodeTAWarning;
 281     };
 282
 283     /////////////////////////////////////////////////////////////////////////////
 284     // TCAS::Tracker ////////////////////////////////////////////////////////////
 285     /////////////////////////////////////////////////////////////////////////////
 286
 287     class Tracker
 288     {
 289     public:
 290         Tracker  (TCAS* _tcas);
 291         ~Tracker (void) {}
 292
 293         void update          (void);
 294
 295         void add             (const string callsign, int detectedLevel);
 296         bool active          (void) { return haveTargets;}
 297         bool newTraffic      (void) { return newTargets;}
 298         bool isTracked       (string callsign) { if (!haveTargets) return false;else return _isTracked(callsign);}
 299         bool _isTracked      (string callsign);
 300         int  getThreatLevel  (string callsign);
 301
 302     private:
 303         TCAS*  tcas;
 304         double currentTime;
 305         bool   haveTargets;
 306         bool   newTargets;
 307         TrackerTargets targets;
 308     };
 309
 310     /////////////////////////////////////////////////////////////////////////////
 311     // TCAS::AdvisoryGenerator //////////////////////////////////////////////////
 312     /////////////////////////////////////////////////////////////////////////////
 313
 314     class AdvisoryGenerator
 315     {
 316     public:
 317         AdvisoryGenerator        (TCAS* _tcas);
 318         ~AdvisoryGenerator       (void) {}
 319
 320         void init                (const LocalInfo* _pSelf, ThreatInfo* _pCurrentThreat);
 321
 322         void setAlarmThresholds  (const SensitivityLevel* _pAlarmThresholds);
 323
 324         int   resolution         (int mode, int threatLevel, float distanceNm,
 325                                   float altFt, float heading, float velocityKt);
 326
 327     private:
 328         float verticalSeparation (float newVerticalFps);
 329         void  determineRAsense   (int& RASense, bool& isCrossing);
 330
 331     private:
 332         TCAS*             tcas;
 333         const LocalInfo*  pSelf;          /*< info structure for local aircraft */
 334         ThreatInfo* pCurrentThreat; /*< info structure on current intruder/threat */
 335         const SensitivityLevel* pAlarmThresholds;
 336     };
 337
 338     /////////////////////////////////////////////////////////////////////////////
 339     // TCAS::ThreatDetector /////////////////////////////////////////////////////
 340     /////////////////////////////////////////////////////////////////////////////
 341
 342     class ThreatDetector
 343     {
 344     public:
 345         ThreatDetector            (TCAS* _tcas);
 346         ~ThreatDetector           (void) {}
 347
 348         void  init                (void);
 349         void  update              (void);
 350
 351         bool  checkTransponder    (const SGPropertyNode* pModel, float velocityKt);
 352         int   checkThreat         (int mode, const SGPropertyNode* pModel);
 353         void  checkVerticalThreat (void);
 354         void  horizontalThreat    (float bearing, float distanceNm, float heading,
 355                                    float velocityKt);
 356
 357         void  setAlt              (float altFt) { self.altFt = altFt;}
 358         float getAlt              (void)        { return self.altFt;}
 359         float getVelocityKt       (void)        { return self.velocityKt;}
 360         int   getRASense          (void)        { return currentThreat.RASense;}
 361
 362     private:
 363         void  unitTest            (void);
 364
 365     private:
 366         static const SensitivityLevel sensitivityLevels[];
 367
 368         TCAS*              tcas;
 369         int                checkCount;
 370
 371         SGPropertyNode_ptr nodeLat;
 372         SGPropertyNode_ptr nodeLon;
 373         SGPropertyNode_ptr nodeAlt;
 374         SGPropertyNode_ptr nodeHeading;
 375         SGPropertyNode_ptr nodeVelocity;
 376         SGPropertyNode_ptr nodeVerticalFps;
 377
 378         LocalInfo          self;          /*< info structure for local aircraft */
 379         ThreatInfo         currentThreat; /*< info structure on current intruder/threat */
 380         const SensitivityLevel* pAlarmThresholds;
 381     };
 382
 383 private:
 384     string              name;
 385     int                 num;
 386     double              nextUpdateTime;
 387     int                 selfTestStep;
 388
 389     SGPropertyNode_ptr  nodeModeSwitch;
 390     SGPropertyNode_ptr  nodeServiceable;
 391     SGPropertyNode_ptr  nodeSelfTest;
 392     SGPropertyNode_ptr  nodeDebugTrigger;
 393     SGPropertyNode_ptr  nodeDebugRA;
 394     SGPropertyNode_ptr  nodeDebugThreat;
 395
 396     PropertiesHandler   properties_handler;
 397     ThreatDetector      threatDetector;
 398     Tracker             tracker;
 399     AdvisoryCoordinator advisoryCoordinator;
 400     AdvisoryGenerator   advisoryGenerator;
 401     Annunciator         annunciator;
 402
 403 private:
 404     void selfTest       (void);
 405
 406 public:
 407     TCAS (SGPropertyNode* node);
 408
 409     virtual void bind   (void);
 410     virtual void unbind (void);
 411     virtual void init   (void);
 412     virtual void update (double dt);
 413 };
 414
 415 #ifdef _MSC_VER
 416 #  pragma warning( pop )
 417 #endif
 418
 419 #endif // __INSTRUMENTS_TCAS_HXX