src/FDM/JSBSim/models/flight_control/FGActuator.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGActuator.h
   4  Author:       Jon Berndt
   5  Date started: 21 February 2007
   6
   7  ------------- Copyright (C) 2006 Jon S. Berndt (jon@jsbsim.org) -------------
   8
   9  This program is free software; you can redistribute it and/or modify it under
  10  the terms of the GNU Lesser General Public License as published by the Free Software
  11  Foundation; either version 2 of the License, or (at your option) any later
  12  version.
  13
  14  This program is distributed in the hope that it will be useful, but WITHOUT
  15  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  16  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  17  details.
  18
  19  You should have received a copy of the GNU Lesser General Public License along with
  20  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  21  Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23  Further information about the GNU Lesser General Public License can also be found on
  24  the world wide web at http://www.gnu.org.
  25
  26 HISTORY
  27 --------------------------------------------------------------------------------
  28
  29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  30 SENTRY
  31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  32
  33 #ifndef FGACTUATOR_H
  34 #define FGACTUATOR_H
  35
  36 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  37 INCLUDES
  38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  39
  40 #include "FGFCSComponent.h"
  41 #include "input_output/FGXMLElement.h"
  42
  43 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  44 DEFINITIONS
  45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  46
  47 #define ID_ACTUATOR "$Id$"
  48
  49 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  50 FORWARD DECLARATIONS
  51 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  52
  53 namespace JSBSim {
  54
  55 class FGFCS;
  56
  57 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  58 CLASS DOCUMENTATION
  59 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  60
  61 /** Encapsulates an Actuator component for the flight control system.
  62     The actuator can be modeled as a "perfect actuator", with the Output
  63     being set directly to the input. The actuator can be made more "real"
  64     by specifying any/all of the following additional effects that can be
  65     applied to the actuator. In order of application to the input signal,
  66     these are:
  67
  68     - System lag (input lag, really)
  69     - Rate limiting
  70     - Deadband
  71     - Hysteresis (mechanical hysteresis)
  72     - Bias (mechanical bias)
  73     - Position limiting ("hard stops")
  74
  75     There are also several malfunctions that can be applied to the actuator
  76     by setting a property to true or false (or 1 or 0).
  77
  78 Syntax:
  79
  80 @code
  81 <actuator name="name">
  82   <input> {[-]property} </input>
  83   <lag> number </lag>
  84   <rate_limit> number <rate_limit>
  85   <bias> number </bias>
  86   <deadband_width> number </deadband_width>
  87   <hysteresis_width> number </hysteresis_width>
  88   [<clipto>
  89     <min> {property name | value} </min>
  90     <max> {property name | value} </max>
  91    </clipto>]
  92   [<output> {property} </output>]
  93 </actuator>
  94 @endcode
  95
  96 Example:
  97
  98 @code
  99 <actuator name="fcs/gimbal_pitch_position">
 100   <input> fcs/gimbal_pitch_command </input>
 101   <lag> 60 </lag>
 102   <rate_limit> 0.085 <rate_limit> <!-- 5 degrees/sec -->
 103   <bias> 0.002 </bias>
 104   <deadband_width> 0.002 </deadband_width>
 105   <hysteresis_width> 0.05 </hysteresis_width>
 106   <clipto> <!-- +/- 10 degrees -->
 107     <min> -0.17 </min>
 108     <max>  0.17 </max>
 109    </clipto>
 110 </actuator>
 111 @endcode
 112
 113 @author Jon S. Berndt
 114 @version $Revision$
 115 */
 116
 117 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 118 CLASS DECLARATION
 119 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 120
 121 class FGActuator  : public FGFCSComponent
 122 {
 123 public:
 124   /// Constructor
 125   FGActuator(FGFCS* fcs, Element* element);
 126   /// Destructor
 127   ~FGActuator();
 128
 129   /** This function processes the input.
 130       It calls private functions if needed to perform the hysteresis, lag,
 131       limiting, etc. functions. */
 132   bool Run (void);
 133
 134   // these may need to have the bool argument replaced with a double
 135   /** This function fails the actuator to zero. The motion to zero
 136       will flow through the lag, hysteresis, and rate limiting
 137       functions if those are activated. */
 138   inline void SetFailZero(bool set) {fail_zero = set;}
 139   inline void SetFailHardover(bool set) {fail_hardover = set;}
 140   inline void SetFailStuck(bool set) {fail_stuck = set;}
 141
 142   inline bool GetFailZero(void) const {return fail_zero;}
 143   inline bool GetFailHardover(void) const {return fail_hardover;}
 144   inline bool GetFailStuck(void) const {return fail_stuck;}
 145
 146 private:
 147   double span;
 148   double bias;
 149   double rate_limit;
 150   double hysteresis_width;
 151   double deadband_width;
 152   double lag;
 153   double ca; // lag filter coefficient "a"
 154   double cb; // lag filter coefficient "b"
 155   double PreviousOutput;
 156   double PreviousHystOutput;
 157   double PreviousRateLimOutput;
 158   double PreviousLagInput;
 159   double PreviousLagOutput;
 160   bool fail_zero;
 161   bool fail_hardover;
 162   bool fail_stuck;
 163
 164   void Hysteresis(void);
 165   void Lag(void);
 166   void RateLimit(void);
 167   void Deadband(void);
 168   void Bias(void);
 169
 170   void bind(void);
 171
 172   void Debug(int from);
 173 };
 174 }
 175 #endif