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 #include <input_output/FGXMLFileRead.h>
  46
  47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  48 DEFINITIONS
  49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  50
  51 #define ID_FGSCRIPT "$Id$"
  52
  53 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  54 FORWARD DECLARATIONS
  55 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  56
  57 namespace JSBSim {
  58
  59 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  60 CLASS DOCUMENTATION
  61 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  62
  63 /** Encapsulates the JSBSim scripting capability.
  64     <h4>Scripting support provided via FGScript.</h4>
  65
  66     <p>There is support for scripting provided in the FGScript
  67     class. Commands are specified using the <em>Scripting
  68     Directives for JSBSim</em>. The script file is in XML
  69     format. A test condition (or conditions) can be set up in an event in a
  70     script and when the condition evaluates to true, the specified
  71     action[s] is/are taken. An event can be <em>persistent</em>,
  72     meaning that at all times when the test condition evaluates to true
  73     the specified <em>set</em> actions take place. When the set of
  74     tests evaluates to true for a given
  75     condition, an item may be set to another value. This value may
  76     be a value, or a delta value, and the change from the
  77     current value to the new value can be either via a step function,
  78     a ramp, or an exponential approach. The speed of a ramp or
  79     approach is specified via the time constant. Here is an example
  80     illustrating the format of the script file:
  81
  82     @code
  83 <?xml version="1.0"?>
  84 <runscript name="C172-01A takeoff run">
  85   <!--
  86     This run is for testing the C172 altitude hold autopilot
  87   -->
  88
  89   <use aircraft="c172x"/>
  90   <use initialize="reset00"/>
  91   <run start="0.0" end="3000" dt="0.0083333">
  92
  93     <event name="engine start">
  94       <notify/>
  95       <condition>
  96         sim-time-sec >= 0.25
  97       </condition>
  98       <set name="fcs/throttle-cmd-norm" value="1.0" action="FG_RAMP" tc ="0.5"/>
  99       <set name="fcs/mixture-cmd-norm" value="0.87" action="FG_RAMP" tc ="0.5"/>
 100       <set name="propulsion/magneto_cmd" value="3"/>
 101       <set name="propulsion/starter_cmd" value="1"/>
 102     </event>
 103
 104     <event name="set heading hold">
 105       <!-- Set Heading when reach 5 ft -->
 106       <notify/>
 107       <condition>
 108         position/h-agl-ft >= 5
 109       </condition>
 110       <set name="ap/heading_setpoint" value="200"/>
 111       <set name="ap/attitude_hold" value="0"/>
 112       <set name="ap/heading_hold" value="1"/>
 113     </event>
 114
 115     <event name="set autopilot">
 116       <!-- Set Autopilot for 20 ft -->
 117       <notify/>
 118       <condition>
 119         aero/qbar-psf >= 4
 120       </condition>
 121       <set name="ap/altitude_setpoint" value="100.0" action="FG_EXP" tc ="2.0"/>
 122       <set name="ap/altitude_hold" value="1"/>
 123       <set name="fcs/flap-cmd-norm" value=".33"/>
 124     </event>
 125
 126     <event name="set autopilot 2" persistent="true">
 127       <!-- Set Autopilot for 6000 ft -->
 128       <notify/>
 129       <condition>
 130         aero/qbar-psf > 5
 131       </condition>
 132       <set name="ap/altitude_setpoint" value="6000.0"/>
 133     </event>
 134
 135     <event name="Time Notify">
 136       <notify/>
 137       <condition> sim-time-sec >= 500 </condition>
 138     </event>
 139
 140     <event name="Time Notify">
 141       <notify/>
 142       <condition> sim-time-sec >= 1000 </condition>
 143     </event>
 144
 145   </run>
 146
 147 </runscript>
 148     @endcode
 149
 150     The first line must always be present - it identifies the file
 151     as an XML format file. The second line
 152     identifies this file as a script file, and gives a descriptive
 153     name to the script file. Comments are next, delineated by the
 154     &lt;!-- and --&gt; symbols. The aircraft and initialization files
 155     to be used are specified in the &quot;use&quot; lines. Next,
 156     comes the &quot;run&quot; section, where the conditions are
 157     described in &quot;event&quot; clauses.</p>
 158     @author Jon S. Berndt
 159     @version "$Id$"
 160 */
 161
 162 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 163 CLASS DECLARATION
 164 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 165
 166 class FGScript : public FGJSBBase, public FGXMLFileRead
 167 {
 168 public:
 169   /// Default constructor
 170   FGScript(FGFDMExec* exec);
 171
 172   /// Default destructor
 173   ~FGScript();
 174
 175   /** Loads a script to drive JSBSim (usually in standalone mode).
 176       The language is the Script Directives for JSBSim.
 177       @param script the filename (including path name, if any) for the script.
 178       @return true if successful */
 179   bool LoadScript( string script );
 180
 181   /** This function is called each pass through the executive Run() method IF
 182       scripting is enabled.
 183       @return false if script should exit (i.e. if time limits are violated */
 184   bool RunScript(void);
 185
 186 private:
 187   enum eAction {
 188     FG_RAMP  = 1,
 189     FG_STEP  = 2,
 190     FG_EXP   = 3
 191   };
 192
 193   enum eType {
 194     FG_VALUE = 1,
 195     FG_DELTA = 2,
 196     FG_BOOL  = 3
 197   };
 198
 199   struct event {
 200     FGCondition     *Condition;
 201     bool             Persistent;
 202     bool             Triggered;
 203     bool             PrevTriggered;
 204     bool             Notify;
 205     bool             Notified;
 206     double           Delay;
 207     double           StartTime;
 208     double           TimeSpan;
 209     string           Name;
 210     vector <FGPropertyManager*>  SetParam;
 211     vector <FGPropertyManager*>  NotifyProperties;
 212     vector <eAction> Action;
 213     vector <eType>   Type;
 214     vector <double>  SetValue;
 215     vector <double>  TC;
 216     vector <double>  newValue;
 217     vector <double>  OriginalValue;
 218     vector <double>  ValueSpan;
 219     vector <bool>    Transiting;
 220
 221     event() {
 222       Triggered = false;
 223       PrevTriggered = false;
 224       Persistent = false;
 225       Delay = 0.0;
 226       Notify = Notified = false;
 227       Name = "";
 228       StartTime = 0.0;
 229       TimeSpan = 0.0;
 230     }
 231   };
 232
 233   struct LocalProps {
 234     double *value;
 235     string title;
 236     LocalProps() {
 237       value = new double(0.0);
 238       title = "";
 239     }
 240   };
 241
 242   string  ScriptName;
 243   double  StartTime;
 244   double  EndTime;
 245   vector <struct event> Events;
 246   vector <LocalProps*> local_properties;
 247
 248   FGFDMExec* FDMExec;
 249   FGState* State;
 250   FGPropertyManager* PropertyManager;
 251   void Debug(int from);
 252 };
 253 }
 254 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 255 #endif
 256