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