src/FDM/JSBSim/input_output/FGScript.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2  Header:       FGScript.h
   3  Author:       Jon Berndt
   4  Date started: 12/21/2001
   5
   6  ------------- Copyright (C) 2001  Jon S. Berndt (jsb@hal-pc.org) -------------
   7
   8  This program is free software; you can redistribute it and/or modify it under
   9  the terms of the GNU Lesser General Public License as published by the Free Software
  10  Foundation; either version 2 of the License, or (at your option) any later
  11  version.
  12
  13  This program is distributed in the hope that it will be useful, but WITHOUT
  14  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  15  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  16  details.
  17
  18  You should have received a copy of the GNU Lesser General Public License along with
  19  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  20  Place - Suite 330, Boston, MA  02111-1307, USA.
  21
  22  Further information about the GNU Lesser General Public License can also be found on
  23  the world wide web at http://www.gnu.org.
  24
  25 HISTORY
  26 --------------------------------------------------------------------------------
  27 12/21/01   JSB   Created
  28
  29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  30 SENTRY
  31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  32
  33 #ifndef FGSCRIPT_HEADER_H
  34 #define FGSCRIPT_HEADER_H
  35
  36 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  37 INCLUDES
  38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  39
  40 #include "FGJSBBase.h"
  41 #include "FGState.h"
  42 #include "FGFDMExec.h"
  43 #include <math/FGCondition.h>
  44 #include <vector>
  45
  46 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  47 DEFINITIONS
  48 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  49
  50 #define ID_FGSCRIPT "$Id$"
  51
  52 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  53 FORWARD DECLARATIONS
  54 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  55
  56 namespace JSBSim {
  57
  58 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  59 CLASS DOCUMENTATION
  60 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  61
  62 /** Encapsulates the JSBSim scripting capability.
  63     <h4>Scripting support provided via FGScript.</h4>
  64
  65     <p>There is support for scripting provided in the FGScript
  66     class. Commands are specified using the <em>Scripting
  67     Directives for JSBSim</em>. The script file is in XML
  68     format. A test condition (or conditions) can be set up in an event in a
  69     script and when the condition evaluates to true, the specified
  70     action[s] is/are taken. An event can be <em>persistent</em>,
  71     meaning that at all times when the test condition evaluates to true
  72     the specified <em>set</em> actions take place. When the set of
  73     tests evaluates to true for a given
  74     condition, an item may be set to another value. This value may
  75     be a value, or a delta value, and the change from the
  76     current value to the new value can be either via a step function,
  77     a ramp, or an exponential approach. The speed of a ramp or
  78     approach is specified via the time constant. Here is an example
  79     illustrating the format of the script file:
  80
  81     @code
  82 <?xml version="1.0"?>
  83 <runscript name="C172-01A takeoff run">
  84   <!--
  85     This run is for testing the C172 altitude hold autopilot
  86   -->
  87
  88   <use aircraft="c172x"/>
  89   <use initialize="reset00"/>
  90   <run start="0.0" end="3000" dt="0.0083333">
  91
  92     <event name="engine start">
  93       <notify/>
  94       <condition>
  95         sim-time-sec >= 0.25
  96       </condition>
  97       <set name="fcs/throttle-cmd-norm" value="1.0" action="FG_RAMP" tc ="0.5"/>
  98       <set name="fcs/mixture-cmd-norm" value="0.87" action="FG_RAMP" tc ="0.5"/>
  99       <set name="propulsion/magneto_cmd" value="3"/>
 100       <set name="propulsion/starter_cmd" value="1"/>
 101     </event>
 102
 103     <event name="set heading hold">
 104       <!-- Set Heading when reach 5 ft -->
 105       <notify/>
 106       <condition>
 107         position/h-agl-ft >= 5
 108       </condition>
 109       <set name="ap/heading_setpoint" value="200"/>
 110       <set name="ap/attitude_hold" value="0"/>
 111       <set name="ap/heading_hold" value="1"/>
 112     </event>
 113
 114     <event name="set autopilot">
 115       <!-- Set Autopilot for 20 ft -->
 116       <notify/>
 117       <condition>
 118         aero/qbar-psf >= 4
 119       </condition>
 120       <set name="ap/altitude_setpoint" value="100.0" action="FG_EXP" tc ="2.0"/>
 121       <set name="ap/altitude_hold" value="1"/>
 122       <set name="fcs/flap-cmd-norm" value=".33"/>
 123     </event>
 124
 125     <event name="set autopilot 2" persistent="true">
 126       <!-- Set Autopilot for 6000 ft -->
 127       <notify/>
 128       <condition>
 129         aero/qbar-psf > 5
 130       </condition>
 131       <set name="ap/altitude_setpoint" value="6000.0"/>
 132     </event>
 133
 134     <event name="Time Notify">
 135       <notify/>
 136       <condition> sim-time-sec >= 500 </condition>
 137     </event>
 138
 139     <event name="Time Notify">
 140       <notify/>
 141       <condition> sim-time-sec >= 1000 </condition>
 142     </event>
 143
 144   </run>
 145
 146 </runscript>
 147     @endcode
 148
 149     The first line must always be present - it identifies the file
 150     as an XML format file. The second line
 151     identifies this file as a script file, and gives a descriptive
 152     name to the script file. Comments are next, delineated by the
 153     &lt;!-- and --&gt; symbols. The aircraft and initialization files
 154     to be used are specified in the &quot;use&quot; lines. Next,
 155     comes the &quot;run&quot; section, where the conditions are
 156     described in &quot;event&quot; clauses.</p>
 157     @author Jon S. Berndt
 158     @version "$Id$"
 159 */
 160
 161 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 162 CLASS DECLARATION
 163 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 164
 165 class FGScript : public FGJSBBase
 166 {
 167 public:
 168   /// Default constructor
 169   FGScript(FGFDMExec* exec);
 170
 171   /// Default destructor
 172   ~FGScript();
 173
 174   /** Loads a script to drive JSBSim (usually in standalone mode).
 175       The language is the Script Directives for JSBSim.
 176       @param script the filename (including path name, if any) for the script.
 177       @return true if successful */
 178   bool LoadScript( string script );
 179
 180   /** This function is called each pass through the executive Run() method IF
 181       scripting is enabled.
 182       @return false if script should exit (i.e. if time limits are violated */
 183   bool RunScript(void);
 184
 185 private:
 186   enum eAction {
 187     FG_RAMP  = 1,
 188     FG_STEP  = 2,
 189     FG_EXP   = 3
 190   };
 191
 192   enum eType {
 193     FG_VALUE = 1,
 194     FG_DELTA = 2,
 195     FG_BOOL  = 3
 196   };
 197
 198   struct event {
 199     FGCondition     *Condition;
 200     bool             Persistent;
 201     bool             Triggered;
 202     bool             PrevTriggered;
 203     bool             Notify;
 204     double           Delay;
 205     double           StartTime;
 206     double           TimeSpan;
 207     string           Name;
 208     vector <FGPropertyManager*>  SetParam;
 209     vector <FGPropertyManager*>  NotifyProperties;
 210     vector <eAction> Action;
 211     vector <eType>   Type;
 212     vector <double>  SetValue;
 213     vector <double>  TC;
 214     vector <double>  newValue;
 215     vector <double>  OriginalValue;
 216     vector <double>  ValueSpan;
 217     vector <bool>    Transiting;
 218
 219     event() {
 220       Triggered = false;
 221       PrevTriggered = false;
 222       Persistent = false;
 223       Delay = 0.0;
 224       Notify = false;
 225       Name = "";
 226       StartTime = 0.0;
 227       TimeSpan = 0.0;
 228     }
 229   };
 230
 231   struct LocalProps {
 232     double *value;
 233     string title;
 234     LocalProps() {
 235       value = new double(0.0);
 236       title = "";
 237     }
 238   };
 239
 240   string  ScriptName;
 241   double  StartTime;
 242   double  EndTime;
 243   vector <struct event> Events;
 244   vector <LocalProps*> local_properties;
 245
 246   FGFDMExec* FDMExec;
 247   FGState* State;
 248   FGPropertyManager* PropertyManager;
 249   void Debug(int from);
 250 };
 251 }
 252 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 253 #endif
 254