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