src/Device/Descriptor.hpp

   1 /*
   2 Copyright_License {
   3
   4   XCSoar Glide Computer - http://www.xcsoar.org/
   5   Copyright (C) 2000-2013 The XCSoar Project
   6   A detailed list of copyright holders can be found in the file "AUTHORS".
   7
   8   This program is free software; you can redistribute it and/or
   9   modify it under the terms of the GNU General Public License
  10   as published by the Free Software Foundation; either version 2
  11   of the License, or (at your option) any later version.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18   You should have received a copy of the GNU General Public License
  19   along with this program; if not, write to the Free Software
  20   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  21 }
  22 */
  23
  24 #ifndef XCSOAR_DEVICE_DESCRIPTOR_HPP
  25 #define XCSOAR_DEVICE_DESCRIPTOR_HPP
  26
  27 #include "IO/DataHandler.hpp"
  28 #include "Port/LineSplitter.hpp"
  29 #include "Port/State.hpp"
  30 #include "Device/Parser.hpp"
  31 #include "Profile/DeviceConfig.hpp"
  32 #include "RadioFrequency.hpp"
  33 #include "NMEA/ExternalSettings.hpp"
  34 #include "Time/PeriodClock.hpp"
  35 #include "Job/Async.hpp"
  36 #include "Event/Notify.hpp"
  37 #include "Thread/Mutex.hpp"
  38 #include "Thread/Debug.hpp"
  39
  40 #include <assert.h>
  41 #include <tchar.h>
  42 #include <stdio.h>
  43
  44 struct NMEAInfo;
  45 struct MoreData;
  46 struct DerivedInfo;
  47 struct Declaration;
  48 struct Waypoint;
  49 class Port;
  50 class Device;
  51 class AtmosphericPressure;
  52 struct DeviceRegister;
  53 class InternalSensors;
  54 class BMP085Device;
  55 class I2CbaroDevice;
  56 class NunchuckDevice;
  57 class VoltageDevice;
  58 class RecordedFlightList;
  59 struct RecordedFlightInfo;
  60 class OperationEnvironment;
  61 class OpenDeviceJob;
  62
  63 class DeviceDescriptor final : private Notify, private PortLineSplitter {
  64   /**
  65    * This mutex protects modifications of the attribute "device".  If
  66    * you use the attribute "device" from a thread other than the main
  67    * thread, you must hold this mutex.
  68    */
  69   Mutex mutex;
  70
  71   /** the index of this device in the global list */
  72   const unsigned index;
  73
  74   /**
  75    * This device's configuration.  It may differ from the instance in
  76    * #SystemSettings, because overlapping devices might have been
  77    * cleared.
  78    */
  79   DeviceConfig config;
  80
  81   /**
  82    * This object runs the DoOpen() method in background to make it
  83    * non-blocking.
  84    */
  85   AsyncJobRunner async;
  86
  87   /**
  88    * The #Job that currently opens the device.  NULL if the device is
  89    * not currently being opened.
  90    */
  91   OpenDeviceJob *open_job;
  92
  93   /**
  94    * The #Port used by this device.  This is not applicable to some
  95    * devices, and is NULL in that case.
  96    */
  97   Port *port;
  98
  99   /**
 100    * A handler that will receive all data, to display it on the
 101    * screen.  Can be set with SetMonitor().
 102    */
 103   DataHandler  *monitor;
 104
 105   /**
 106    * A handler that will receive all NMEA lines, to dispatch it to
 107    * other devices.
 108    */
 109   PortLineHandler *dispatcher;
 110
 111   /**
 112    * The device driver used to handle data to/from the device.
 113    */
 114   const DeviceRegister *driver;
 115
 116   /**
 117    * An instance of the driver.
 118    *
 119    * Modifications (from the main thread) must be protected by the
 120    * attribute "mutex".  Read access and any use of this object
 121    * outside of the main thread must also be protected, unless the
 122    * device was borrowed with the method Borrow().  The latter,
 123    * however, is only possible from the main thread.
 124    */
 125   Device *device;
 126
 127 #ifdef ANDROID
 128   /**
 129    * A pointer to the Java object managing all Android sensors (GPS,
 130    * baro sensor and others).
 131    */
 132   InternalSensors *internal_sensors;
 133
 134 #ifdef IOIOLIB
 135   BMP085Device *droidsoar_v2;
 136   I2CbaroDevice *i2cbaro[3]; // static, pitot, tek; in any order
 137   NunchuckDevice *nunchuck;
 138   VoltageDevice *voltage;
 139 #endif
 140 #endif
 141
 142   /**
 143    * This clock keeps track when we need to reopen the device next
 144    * time after a failure or after a timeout.  It gets updated each
 145    * time the failure/timeout occurs, and again after each retry.
 146    */
 147   PeriodClock reopen_clock;
 148
 149   /**
 150    * The generic NMEA parser for this device.  It may hold internal
 151    * state.
 152    */
 153   NMEAParser parser;
 154
 155   /**
 156    * The settings that were sent to the device.  This is used to check
 157    * if the device is sending back the new configuration; then the
 158    * device isn't actually sending a new setting, it is merely
 159    * repeating the settings we sent it.  This should not make XCSoar
 160    * reconfigure itself.
 161    */
 162   ExternalSettings settings_sent;
 163
 164   /**
 165    * The settings that were received from the device.  This temporary
 166    * buffer mirrors NMEA_INFO::settings; NMEA_INFO::settings may get
 167    * cleared with ExternalSettings::EliminateRedundant(), so this one
 168    * always preserves the original values from the device, without
 169    * having to do a full NMEA_INFO copy.
 170    */
 171   ExternalSettings settings_received;
 172
 173   /**
 174    * Number of port failures since the device was last reset.
 175    *
 176    * @param see ResetFailureCounter()
 177    */
 178   unsigned n_failures;
 179
 180   /**
 181    * Internal flag for OnSysTicker() for detecting link timeout.
 182    */
 183   bool was_alive;
 184
 185   /**
 186    * Internal flag for OnSysTicker() for calling Device::OnSysTicker()
 187    * only every other time.
 188    */
 189   bool ticker;
 190
 191   /**
 192    * True when somebody has "borrowed" the device.  Link timeouts are
 193    * disabled meanwhile.
 194    *
 195    * This attribute is only accessed from the main thread.
 196    *
 197    * @see CanBorrow(), Borrow()
 198    */
 199   bool borrowed;
 200
 201 public:
 202   DeviceDescriptor(unsigned index);
 203   ~DeviceDescriptor() {
 204     assert(!IsOccupied());
 205   }
 206
 207   unsigned GetIndex() const {
 208     return index;
 209   }
 210
 211   const DeviceConfig &GetConfig() const {
 212     return config;
 213   }
 214
 215   void SetConfig(const DeviceConfig &config);
 216   void ClearConfig();
 217
 218   bool IsConfigured() const {
 219     return config.port_type != DeviceConfig::PortType::DISABLED;
 220   }
 221
 222   gcc_pure
 223   PortState GetState() const;
 224
 225   /**
 226    * Was there a failure on the #Port object?
 227    */
 228   bool HasPortFailed() const {
 229     return config.IsAvailable() && config.UsesPort() && port == NULL;
 230   }
 231
 232   /**
 233    * Wrapper for Driver::HasTimeout().  This method can't be inline
 234    * because the Driver struct is incomplete at this point.
 235    */
 236   bool ShouldReopenDriverOnTimeout() const;
 237
 238   /**
 239    * Should the #Port be reopened automatically when a timeout occurs?
 240    */
 241   bool ShouldReopenOnTimeout() const {
 242     return config.ShouldReopenOnTimeout() &&
 243       ShouldReopenDriverOnTimeout();
 244   }
 245
 246   /**
 247    * Should the #Port be reopened?
 248    */
 249   bool ShouldReopen() const {
 250     return HasPortFailed() || (!IsAlive() && ShouldReopenOnTimeout());
 251   }
 252
 253   /**
 254    * Returns the Device object; may be NULL if the device is not open
 255    * or if the Device class is not applicable for this object.
 256    *
 257    * Should only be used by driver-specific code (such as the CAI 302
 258    * manager).
 259    */
 260   Device *GetDevice() {
 261     return device;
 262   }
 263
 264 private:
 265   /**
 266    * Cancel the #AsyncJobRunner object if it is running.
 267    */
 268   void CancelAsync();
 269
 270   /**
 271    * When this method fails, the caller is responsible for freeing the
 272    * Port object.
 273    */
 274   gcc_nonnull_all
 275   bool OpenOnPort(Port *port, OperationEnvironment &env);
 276
 277   bool OpenInternalSensors();
 278
 279   bool OpenDroidSoarV2();
 280
 281   bool OpenI2Cbaro();
 282
 283   bool OpenNunchuck();
 284
 285   bool OpenVoltage();
 286 public:
 287   /**
 288    * To be used by OpenDeviceJob, don't call directly.
 289    */
 290   bool DoOpen(OperationEnvironment &env);
 291
 292   void ResetFailureCounter() {
 293     n_failures = 0u;
 294   }
 295
 296   /**
 297    * @param env a persistent object
 298    */
 299   void Open(OperationEnvironment &env);
 300
 301   void Close();
 302
 303   /**
 304    * @param env a persistent object
 305    */
 306   void Reopen(OperationEnvironment &env);
 307
 308   /**
 309    * Call this periodically to auto-reopen a failed device after a
 310    * certain delay.
 311    *
 312    * @param env a persistent object
 313    */
 314   void AutoReopen(OperationEnvironment &env);
 315
 316   /**
 317    * Call this method after Declare(), ReadFlightList(),
 318    * DownloadFlight() when you're done, to switch back to NMEA mode.
 319    *
 320    * Even when the driver's EnableNMEA() method fails, this method
 321    * will re-enable the receive thread, to avoid false negatives due
 322    * to flaky cables.
 323    */
 324   bool EnableNMEA(OperationEnvironment &env);
 325
 326   const TCHAR *GetDisplayName() const;
 327
 328   /**
 329    * Compares the driver's name.
 330    */
 331   bool IsDriver(const TCHAR *name) const;
 332
 333   gcc_pure
 334   bool CanDeclare() const;
 335
 336   gcc_pure
 337   bool IsLogger() const;
 338
 339   bool IsCondor() const {
 340     return IsDriver(_T("Condor"));
 341   }
 342
 343   bool IsVega() const {
 344     return IsDriver(_T("Vega"));
 345   }
 346
 347   bool IsNMEAOut() const;
 348   bool IsManageable() const;
 349
 350   bool IsBorrowed() const {
 351     return borrowed;
 352   }
 353
 354   /**
 355    * Is this device currently occupied, i.e. does somebody have
 356    * exclusive access?
 357    *
 358    * May only be called from the main thread.
 359    */
 360   bool IsOccupied() const {
 361     assert(InMainThread());
 362
 363     return IsBorrowed() || async.IsBusy();
 364   }
 365
 366   /**
 367    * Can this device be borrowed?
 368    *
 369    * May only be called from the main thread.
 370    *
 371    * @see Borrow()
 372    */
 373   bool CanBorrow() const {
 374     assert(InMainThread());
 375
 376     return device != NULL && GetState() == PortState::READY && !IsOccupied();
 377   }
 378
 379   /**
 380    * "Borrow" the device.  The caller gets exclusive access, e.g. to
 381    * submit a task declaration.  Call Return() when you are done.
 382    *
 383    * May only be called from the main thread.
 384    *
 385    * @return false if the device is already occupied and cannot be
 386    * borrowed
 387    */
 388   bool Borrow();
 389
 390   /**
 391    * Return a borrowed device.  The caller is responsible for
 392    * switching the device back to NMEA mode, see EnableNMEA().
 393    *
 394    * May only be called from the main thread.
 395    */
 396   void Return();
 397
 398   /**
 399    * Query the device's "alive" flag from the DeviceBlackboard.
 400    * This method locks the DeviceBlackboard.
 401    */
 402   gcc_pure
 403   bool IsAlive() const;
 404
 405 private:
 406   bool ParseNMEA(const char *line, struct NMEAInfo &info);
 407
 408 public:
 409   void SetMonitor(DataHandler  *_monitor) {
 410     monitor = _monitor;
 411   }
 412
 413   void SetDispatcher(PortLineHandler *_dispatcher) {
 414     dispatcher = _dispatcher;
 415   }
 416
 417   /**
 418    * Write a line to the device's port if it's a NMEA out port.
 419    */
 420   void ForwardLine(const char *line);
 421
 422   bool WriteNMEA(const char *line, OperationEnvironment &env);
 423 #ifdef _UNICODE
 424   bool WriteNMEA(const TCHAR *line, OperationEnvironment &env);
 425 #endif
 426
 427   bool PutMacCready(fixed mac_cready, OperationEnvironment &env);
 428   bool PutBugs(fixed bugs, OperationEnvironment &env);
 429   bool PutBallast(fixed fraction, fixed overload,
 430                   OperationEnvironment &env);
 431   bool PutVolume(unsigned volume, OperationEnvironment &env);
 432   bool PutActiveFrequency(RadioFrequency frequency,
 433                           OperationEnvironment &env);
 434   bool PutStandbyFrequency(RadioFrequency frequency,
 435                            OperationEnvironment &env);
 436   bool PutQNH(const AtmosphericPressure &pres, OperationEnvironment &env);
 437
 438   /**
 439    * Caller is responsible for calling Borrow() and Return().
 440    */
 441   bool Declare(const Declaration &declaration, const Waypoint *home,
 442                OperationEnvironment &env);
 443
 444   /**
 445    * Caller is responsible for calling Borrow() and Return().
 446    */
 447   bool ReadFlightList(RecordedFlightList &flight_list,
 448                       OperationEnvironment &env);
 449
 450   /**
 451    * Caller is responsible for calling Borrow() and Return().
 452    */
 453   bool DownloadFlight(const RecordedFlightInfo &flight, const TCHAR *path,
 454                       OperationEnvironment &env);
 455
 456   void OnSysTicker();
 457
 458   /**
 459    * Wrapper for Driver::OnSensorUpdate().
 460    */
 461   void OnSensorUpdate(const MoreData &basic);
 462
 463   /**
 464    * Wrapper for Driver::OnCalculatedUpdate().
 465    */
 466   void OnCalculatedUpdate(const MoreData &basic,
 467                           const DerivedInfo &calculated);
 468
 469 private:
 470   bool ParseLine(const char *line);
 471
 472   /* virtual methods from class Notify */
 473   virtual void OnNotification() override;
 474
 475   /* virtual methods from DataHandler  */
 476   virtual void DataReceived(const void *data, size_t length) override;
 477
 478   /* virtual methods from PortLineHandler */
 479   virtual void LineReceived(const char *line) override;
 480 };
 481
 482 #endif