src/FDM/JSBSim/models/FGLGear.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGLGear.h
   4  Author:       Jon S. Berndt
   5  Date started: 11/18/99
   6
   7  ------------- Copyright (C) 1999  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 11/18/99   JSB   Created
  29
  30 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  31 SENTRY
  32 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  33
  34 #ifndef FGLGEAR_H
  35 #define FGLGEAR_H
  36
  37 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  38 INCLUDES
  39 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  40
  41 #include <string>
  42
  43 #include "models/propulsion/FGForce.h"
  44 #include "math/FGColumnVector3.h"
  45 #include "math/FGMatrix33.h"
  46 #include "math/LagrangeMultiplier.h"
  47
  48 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  49 DEFINITIONS
  50 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  51
  52 #define ID_LGEAR "$Id: FGLGear.h,v 1.48 2011/10/31 14:54:41 bcoconni Exp $"
  53
  54 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  55 FORWARD DECLARATIONS
  56 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  57
  58 namespace JSBSim {
  59
  60 class FGTable;
  61 class Element;
  62 class FGPropertyManager;
  63
  64 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  65 CLASS DOCUMENTATION
  66 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  67
  68 /** Landing gear model.
  69     Calculates forces and moments due to landing gear reactions. This is done in
  70     several steps, and is dependent on what kind of gear is being modeled. Here
  71     are the parameters that can be specified in the config file for modeling
  72     landing gear:
  73     <p>
  74     <h3>Physical Characteristics</h3>
  75     <ol>
  76     <li>X, Y, Z location, in inches in structural coordinate frame</li>
  77     <li>Spring constant, in lbs/ft</li>
  78     <li>Damping coefficient, in lbs/ft/sec</li>
  79     <li>Dynamic Friction Coefficient</li>
  80     <li>Static Friction Coefficient</li>
  81     </ol></p><p>
  82     <h3>Operational Properties</h3>
  83     <ol>
  84     <li>Name</li>
  85     <li>Brake Group Membership {one of LEFT | CENTER | RIGHT | NOSE | TAIL | NONE}</li>
  86     <li>Max Steer Angle, in degrees</li>
  87     </ol></p>
  88     <p>
  89     <h3>Algorithm and Approach to Modeling</h3>
  90     <ol>
  91     <li>Find the location of the uncompressed landing gear relative to the CG of
  92     the aircraft. Remember, the structural coordinate frame that the aircraft is
  93     defined in is: X positive towards the tail, Y positive out the right side, Z
  94     positive upwards. The locations of the various parts are given in inches in
  95     the config file.</li>
  96     <li>The vector giving the location of the gear (relative to the cg) is
  97     rotated 180 degrees about the Y axis to put the coordinates in body frame (X
  98     positive forwards, Y positive out the right side, Z positive downwards, with
  99     the origin at the cg). The lengths are also now given in feet.</li>
 100     <li>The new gear location is now transformed to the local coordinate frame
 101     using the body-to-local matrix. (Mb2l).</li>
 102     <li>Knowing the location of the center of gravity relative to the ground
 103     (height above ground level or AGL) now enables gear deflection to be
 104     calculated. The gear compression value is the local frame gear Z location
 105     value minus the height AGL. [Currently, we make the assumption that the gear
 106     is oriented - and the deflection occurs in - the Z axis only. Additionally,
 107     the vector to the landing gear is currently not modified - which would
 108     (correctly) move the point of contact to the actual compressed-gear point of
 109     contact. Eventually, articulated gear may be modeled, but initially an
 110     effort must be made to model a generic system.] As an example, say the
 111     aircraft left main gear location (in local coordinates) is Z = 3 feet
 112     (positive) and the height AGL is 2 feet. This tells us that the gear is
 113     compressed 1 foot.</li>
 114     <li>If the gear is compressed, a Weight-On-Wheels (WOW) flag is set.</li>
 115     <li>With the compression length calculated, the compression velocity may now
 116     be calculated. This will be used to determine the damping force in the
 117     strut. The aircraft rotational rate is multiplied by the vector to the wheel
 118     to get a wheel velocity in body frame. That velocity vector is then
 119     transformed into the local coordinate frame.</li>
 120     <li>The aircraft cg velocity in the local frame is added to the
 121     just-calculated wheel velocity (due to rotation) to get a total wheel
 122     velocity in the local frame.</li>
 123     <li>The compression speed is the Z-component of the vector.</li>
 124     <li>With the wheel velocity vector no longer needed, it is normalized and
 125     multiplied by a -1 to reverse it. This will be used in the friction force
 126     calculation.</li>
 127     <li>Since the friction force takes place solely in the runway plane, the Z
 128     coordinate of the normalized wheel velocity vector is set to zero.</li>
 129     <li>The gear deflection force (the force on the aircraft acting along the
 130     local frame Z axis) is now calculated given the spring and damper
 131     coefficients, and the gear deflection speed and stroke length. Keep in mind
 132     that gear forces always act in the negative direction (in both local and
 133     body frames), and are not capable of generating a force in the positive
 134     sense (one that would attract the aircraft to the ground). So, the gear
 135     forces are always negative - they are limited to values of zero or less. The
 136     gear force is simply the negative of the sum of the spring compression
 137     length times the spring coefficient and the gear velocity times the damping
 138     coefficient.</li>
 139     <li>The lateral/directional force acting on the aircraft through the landing
 140
 141     gear (along the local frame X and Y axes) is calculated next. First, the
 142     friction coefficient is multiplied by the recently calculated Z-force. This
 143     is the friction force. It must be given direction in addition to magnitude.
 144     We want the components in the local frame X and Y axes. From step 9, above,
 145     the conditioned wheel velocity vector is taken and the X and Y parts are
 146     multiplied by the friction force to get the X and Y components of friction.
 147     </li>
 148     <li>The wheel force in local frame is next converted to body frame.</li>
 149     <li>The moment due to the gear force is calculated by multiplying r x F
 150     (radius to wheel crossed into the wheel force). Both of these operands are
 151     in body frame.</li>
 152     </ol>
 153
 154     <h3>Configuration File Format:</h3>
 155 @code
 156         <contact type="{BOGEY | STRUCTURE}" name="{string}">
 157             <location unit="{IN | M}">
 158                 <x> {number} </x>
 159                 <y> {number} </y>
 160                 <z> {number} </z>
 161             </location>
 162             <orientation unit="{RAD | DEG}">
 163                 <pitch> {number} </pitch>
 164                 <roll> {number} </roll>
 165                 <yaw> {number} </yaw>
 166             </orientation>
 167             <static_friction> {number} </static_friction>
 168             <dynamic_friction> {number} </dynamic_friction>
 169             <rolling_friction> {number} </rolling_friction>
 170             <spring_coeff unit="{LBS/FT | N/M}"> {number} </spring_coeff>
 171             <damping_coeff [type="SQUARE"] unit="{LBS/FT/SEC | N/M/SEC}"> {number} </damping_coeff>
 172             <damping_coeff_rebound [type="SQUARE"] unit="{LBS/FT/SEC | N/M/SEC}"> {number} </damping_coeff_rebound>
 173             <max_steer unit="DEG"> {number | 0 | 360} </max_steer>
 174             <brake_group> {NONE | LEFT | RIGHT | CENTER | NOSE | TAIL} </brake_group>
 175             <retractable>{0 | 1}</retractable>
 176             <table type="{CORNERING_COEFF}">
 177             </table>
 178         </contact>
 179 @endcode
 180     @author Jon S. Berndt
 181     @version $Id: FGLGear.h,v 1.48 2011/10/31 14:54:41 bcoconni Exp $
 182     @see Richard E. McFarland, "A Standard Kinematic Model for Flight Simulation at
 183      NASA-Ames", NASA CR-2497, January 1975
 184     @see Barnes W. McCormick, "Aerodynamics, Aeronautics, and Flight Mechanics",
 185      Wiley & Sons, 1979 ISBN 0-471-03032-5
 186     @see W. A. Ragsdale, "A Generic Landing Gear Dynamics Model for LASRS++",
 187      AIAA-2000-4303
 188 */
 189
 190 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 191 CLASS DECLARATION
 192 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 193
 194 class FGLGear : public FGForce
 195 {
 196 public:
 197   struct Inputs {
 198     double Vground;
 199     double VcalibratedKts;
 200     double Temperature;
 201     double DistanceAGL;
 202     double DistanceASL;
 203     double TotalDeltaT;
 204     bool TakeoffThrottle;
 205     bool WOW;
 206     FGMatrix33 Tb2l;
 207     FGMatrix33 Tec2l;
 208     FGMatrix33 Tec2b;
 209     FGColumnVector3 PQR;
 210     FGColumnVector3 UVW;
 211     FGLocation Location;
 212     std::vector <double> SteerPosDeg;
 213     std::vector <double> BrakePos;
 214     std::vector <FGColumnVector3> vWhlBodyVec;
 215     double FCSGearPos;
 216     double EmptyWeight;
 217   };
 218
 219   /// Brake grouping enumerators
 220   enum BrakeGroup {bgNone=0, bgLeft, bgRight, bgCenter, bgNose, bgTail, bgNumBrakeGroups };
 221   /// Steering group membership enumerators
 222   enum SteerType {stSteer, stFixed, stCaster};
 223   /// Contact point type
 224   enum ContactType {ctBOGEY, ctSTRUCTURE};
 225   /// Report type enumerators
 226   enum ReportType {erNone=0, erTakeoff, erLand};
 227   /// Damping types
 228   enum DampType {dtLinear=0, dtSquare};
 229   /// Friction types
 230   enum FrictionType {ftRoll=0, ftSide, ftDynamic};
 231   /** Constructor
 232       @param el a pointer to the XML element that contains the CONTACT info.
 233       @param Executive a pointer to the parent executive object
 234       @param number integer identifier for this instance of FGLGear
 235   */
 236   FGLGear(Element* el, FGFDMExec* Executive, int number, const struct Inputs& input);
 237   /// Destructor
 238   ~FGLGear();
 239
 240   /// The Force vector for this gear
 241   const FGColumnVector3& GetBodyForces(void);
 242
 243   /// Gets the location of the gear in Body axes
 244   const FGColumnVector3& GetBodyLocation(void) const { return in.vWhlBodyVec[GearNumber]; }
 245   double GetBodyLocation(int idx) const { return in.vWhlBodyVec[GearNumber](idx); }
 246
 247   const FGColumnVector3& GetLocalGear(void) const { return vLocalGear; }
 248   double GetLocalGear(int idx) const { return vLocalGear(idx); }
 249
 250   /// Gets the name of the gear
 251   const string& GetName(void) const {return name; }
 252   /// Gets the Weight On Wheels flag value
 253   bool    GetWOW(void) const {return WOW; }
 254   /// Gets the current compressed length of the gear in feet
 255   double  GetCompLen(void) const {return compressLength;}
 256   /// Gets the current gear compression velocity in ft/sec
 257   double  GetCompVel(void) const {return compressSpeed; }
 258   /// Gets the gear compression force in pounds
 259   double  GetCompForce(void) const {return StrutForce;   }
 260   double  GetBrakeFCoeff(void) const {return BrakeFCoeff;}
 261
 262   /// Gets the current normalized tire pressure
 263   double  GetTirePressure(void) const { return TirePressureNorm; }
 264   /// Sets the new normalized tire pressure
 265   void    SetTirePressure(double p) { TirePressureNorm = p; }
 266
 267   /// Sets the brake value in percent (0 - 100)
 268   void SetBrake(double bp) {brakePct = bp;}
 269
 270   /// Sets the weight-on-wheels flag.
 271   void SetWOW(bool wow) {WOW = wow;}
 272
 273   /** Set the console touchdown reporting feature
 274       @param flag true turns on touchdown reporting, false turns it off */
 275   void SetReport(bool flag) { ReportEnable = flag; }
 276   /** Get the console touchdown reporting feature
 277       @return true if reporting is turned on */
 278   bool GetReport(void) const  { return ReportEnable; }
 279   double GetSteerNorm(void) const { return radtodeg/maxSteerAngle*SteerAngle; }
 280   double GetDefaultSteerAngle(double cmd) const { return cmd*maxSteerAngle; }
 281   double GetstaticFCoeff(void) const { return staticFCoeff; }
 282
 283   int  GetBrakeGroup(void) const   { return (int)eBrakeGrp; }
 284   int  GetSteerType(void) const    { return (int)eSteerType; }
 285
 286   bool GetSteerable(void) const    { return eSteerType != stFixed; }
 287   bool GetRetractable(void) const  { return isRetractable;   }
 288   bool GetGearUnitUp(void) const   { return GearUp;          }
 289   bool GetGearUnitDown(void) const { return GearDown;        }
 290   double GetWheelRollForce(void) {
 291     UpdateForces();
 292     FGColumnVector3 vForce = mTGear.Transposed() * FGForce::GetBodyForces();
 293     return vForce(eX)*cos(SteerAngle) + vForce(eY)*sin(SteerAngle); }
 294   double GetWheelSideForce(void) {
 295     UpdateForces();
 296     FGColumnVector3 vForce = mTGear.Transposed() * FGForce::GetBodyForces();
 297     return vForce(eY)*cos(SteerAngle) - vForce(eX)*sin(SteerAngle); }
 298   double GetWheelRollVel(void) const   { return vWhlVelVec(eX)*cos(SteerAngle)
 299                                               + vWhlVelVec(eY)*sin(SteerAngle);  }
 300   double GetWheelSideVel(void) const   { return vWhlVelVec(eY)*cos(SteerAngle)
 301                                               - vWhlVelVec(eX)*sin(SteerAngle);  }
 302   double GetWheelSlipAngle(void) const { return WheelSlip;       }
 303   double GetWheelVel(int axis) const   { return vWhlVelVec(axis);}
 304   bool IsBogey(void) const             { return (eContactType == ctBOGEY);}
 305   double GetGearUnitPos(void);
 306   double GetSteerAngleDeg(void) const { return radtodeg*SteerAngle; }
 307
 308   const struct Inputs& in;
 309
 310   void bind(void);
 311
 312 private:
 313   int GearNumber;
 314   static const FGMatrix33 Tb2s;
 315   FGMatrix33 mTGear;
 316   FGColumnVector3 vGearOrient;
 317   FGColumnVector3 vLocalGear;
 318   FGColumnVector3 vWhlVelVec, vLocalWhlVel;     // Velocity of this wheel
 319   FGColumnVector3 normal, vGroundNormal;
 320   FGLocation contact, gearLoc;
 321   FGTable *ForceY_Table;
 322   double SteerAngle;
 323   double kSpring;
 324   double bDamp;
 325   double bDampRebound;
 326   double compressLength;
 327   double compressSpeed;
 328   double staticFCoeff, dynamicFCoeff, rollingFCoeff;
 329   double Stiffness, Shape, Peak, Curvature; // Pacejka factors
 330   double brakePct;
 331   double BrakeFCoeff;
 332   double maxCompLen;
 333   double SinkRate;
 334   double GroundSpeed;
 335   double TakeoffDistanceTraveled;
 336   double TakeoffDistanceTraveled50ft;
 337   double LandingDistanceTraveled;
 338   double MaximumStrutForce, StrutForce;
 339   double MaximumStrutTravel;
 340   double FCoeff;
 341   double WheelSlip;
 342   double TirePressureNorm;
 343   double GearPos;
 344   bool   useFCSGearPos;
 345   bool WOW;
 346   bool lastWOW;
 347   bool FirstContact;
 348   bool StartedGroundRun;
 349   bool LandingReported;
 350   bool TakeoffReported;
 351   bool ReportEnable;
 352   bool isRetractable;
 353   bool GearUp, GearDown;
 354   bool Servicable;
 355   bool Castered;
 356   bool StaticFriction;
 357   std::string name;
 358   std::string sSteerType;
 359   std::string sBrakeGroup;
 360   std::string sRetractable;
 361   std::string sContactType;
 362
 363   BrakeGroup  eBrakeGrp;
 364   ContactType eContactType;
 365   SteerType   eSteerType;
 366   DampType    eDampType;
 367   DampType    eDampTypeRebound;
 368   double  maxSteerAngle;
 369
 370   LagrangeMultiplier LMultiplier[3];
 371
 372   FGGroundReactions* GroundReactions;
 373   FGPropertyManager* PropertyManager;
 374
 375   void ComputeRetractionState(void);
 376   void ComputeBrakeForceCoefficient(void);
 377   void ComputeSteeringAngle(void);
 378   void ComputeSlipAngle(void);
 379   void ComputeSideForceCoefficient(void);
 380   void ComputeVerticalStrutForce(void);
 381   void ComputeGroundCoordSys(void);
 382   void ComputeJacobian(const FGColumnVector3& vWhlContactVec);
 383   void UpdateForces(void);
 384   void CrashDetect(void);
 385   void InitializeReporting(void);
 386   void ResetReporting(void);
 387   void ReportTakeoffOrLanding(void);
 388   void Report(ReportType rt);
 389   void Debug(int from);
 390 };
 391 }
 392
 393 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 394
 395 #endif