1FlightGear Flight Recorder Mini-HOWTO 2 3Thorsten Brehm 4Started in August 2011 5Last revised: 2011-09-26 6 7 8FlightGear provides a customizable flight recorder capable of capturing 9any selection of properties described via XML configuration files. 10The recorder is currently used for the replay system. 11 12 13Feature Brief 14------------- 15* Generic recording system, adaptable to any aircraft/data, provided that 16 data is accessible via the property tree. No hard-coded selections or 17 assumptions on properties to be recorded. 18* Configuration read from XML files or the property tree itself. 19* Interpolation method configurable per recorded/replayed signal. 20* Adaptable recording resolution per signal. 21* Multiple configurations supported. 22 23 24Quick Start: Basic Configuration 25-------------------------------- 26To configure and adapt the flight recorder, add a "/sim/flight-recorder" 27section to your aircraft -set.xml file. 28 29Example: 30 31<sim> 32 33 <!-- ... --> 34 35 <flight-recorder> 36 <replay-config type="int">0</replay-config> 37 <config n="0" 38 include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml"> 39 <name type="string">My Aircraft's Flight Recorder</name> 40 <!-- Custom properties --> 41 <signal> 42 <type>float</type> 43 <property type="string">/controls/gear/nosegear-steering-cmd-norm</property> 44 <interpolation>linear</interpolation> 45 </signal> 46 <!-- More custom signals here --> 47 </config> 48 </flight-recorder> 49 50 <!-- ... --> 51 52</sim> 53 54Default type for each signal is "float". Default "interpolation" method 55is "linear" (for float/double). Default values may be omitted. See 56configuration details below. 57 58 59Generic Configuration Files 60--------------------------- 61Select one of the default configuration files to specify the basic 62properties to be recorded. It's not recommended to specify all 63properties to be recorded individually. 64The following generic files are provided: 65 66* /Aircraft/Generic/flightrecorder/generic-piston-propeller-4.xml 67 Matches propeller aircraft with 4 piston engines, 4 tanks, 68 3 retractable gear. 69 It is the same configuration that was hard-coded for the replay system 70 up to FlightGear 2.4.0. To provide backward compatibility this 71 configuration is loaded by default, unless an aircraft provides a 72 specific flight recorder configuration. 73 74* /Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml 75 Matches propeller aircraft with 1 piston engines, 2 tanks, 3 fixed 76 gear. 77 78* /Aircraft/Generic/flightrecorder/generic-turboprop-2.xml 79 Matches turboprop aircraft with 2 turbines/propellers, 4 tanks, 80 3 retractable gear. 81 82* /Aircraft/Generic/flightrecorder/generic-jet.xml 83 Matches jet aircraft with 2 jet engines, 4 tanks. 84 85* /Aircraft/Generic/flightrecorder/generic-glider.xml 86 Matches gliders (no engines, no tanks, single fixed gear). 87 88* /Aircraft/Generic/flightrecorder/generic-helicopter.xml 89 Matches helicopters with main and tail rotor (tested with YASim). 90 91If none of the generic files matches your aircraft, simply use a 92configuration which covers more than you need. Alternatively, copy the 93contents of one of these generic files to your aircraft, and adapt as 94needed (see below). 95 96FDM experts are welcome to add more generic configuration files to 97/Aircraft/Generic/flightrecorder - such as YASim-/JSBSim-specific 98configurations, and configurations for other types of aircraft 99(balloons, airships, ...). 100 101 102Generic Components 103----------------- 104The generic configuration files in turn include a set of generic 105components. If you copy the contents of a generic file to your aircraft, 106you can adapt the components to your needs. See examples. 107It is not recommended to copy the contents of the _component_ files to 108an aircraft though (causes too much hassle and dependencies). 109 110Engine Selection: 111 * /Aircraft/Generic/flightrecorder/components/engine-jet.xml 112 Records properties of a single jet engine. 113 For multiple jet engines, use "count". Example for 4 jets: 114 <signals include="/Aircraft/Generic/flightrecorder/components/engine-jet.xml"> 115 <count>4</count> 116 </signals> 117 118 * /Aircraft/Generic/flightrecorder/components/engine-piston.xml 119 Records properties of a single piston engine and propeller. 120 For multiple piston engines, use "count" (see "jet" example). 121 122 * /Aircraft/Generic/flightrecorder/components/rotor.xml 123 Records properties of a single helicopter rotor (tested with YASim). 124 To use this, provide the base property path to the rotor as "prefix". 125 Example recording the rotor below "/rotors/main": 126 <signals include="/Aircraft/Generic/flightrecorder/components/rotor.xml"> 127 <prefix type="string">/rotors/main</prefix> 128 </signals> 129 130Gear Selection: 131 * /Aircraft/Generic/flightrecorder/components/gear-fixed.xml 132 Records properties of a single non-retractable gear. 133 For multiple fixed gear, use "count" (see "jet" example). 134 135 * /Aircraft/Generic/flightrecorder/components/gear-retractable.xml 136 Records properties of a single retractable gear. 137 For multiple retractable gear, use "count" (see "jet" example). 138 139Tanks: 140 * /Aircraft/Generic/flightrecorder/components/tanks.xml 141 Records properties of a single fuel tank. 142 For multiple fuel tanks, use "count" (see "jet" example). 143 144Other: 145 * /Aircraft/Generic/flightrecorder/components/surfaces.xml 146 Records properties of flight control surfaces. Include this 147 for aircraft (with wings). Not useful for helicopters, 148 balloons, ... 149 150 * /Aircraft/Generic/flightrecorder/components/faults-engines.xml 151 Records fault properties of a single engine. Only include this 152 if your aircraft supports fault simulation. 153 For multiple engines, use "count" (see "jet" example). If used, 154 it should be compined with piston or jet engine. 155 156 * /Aircraft/Generic/flightrecorder/components/environment.xml 157 Records properties of environment/weather (visibility, 158 temperature - but _not_ cloud position...). 159 160 * /Aircraft/Generic/flightrecorder/components/position.xml 161 Records properties of a the aircrafts main position (latitude, 162 longitude, velocities, ...). 163 This is the most important component. Always include this. 164 165 * /Aircraft/Generic/flightrecorder/components/controls.xml 166 Records most important flight controls (rudder, aileron, 167 elevator, ...). Always include this. 168 169 170Custom Properties 171----------------- 172When the generic or component files are not be sufficient to record or 173replay aircraft-specific effects, you can add custom properties (signals 174to be recorded) to the configuration. 175Each signal consits of a recording type/resolution (which does _not_ 176need to match the actual type in the property tree!), the path to the 177property and interpolation type. 178 179Example recording some additional custom properties: 180 <sim> 181 <flight-recorder> 182 <config n="0" 183 include="/Aircraft/Generic/flightrecorder/generic-piston-propeller-1.xml"> 184 <!-- Add custom properties here --> 185 <signal> 186 <type>float</type> 187 <property type="string">/controls/gear/nosegear-steering-cmd-norm</property> 188 </signal> 189 <signal> 190 <type>double</type> 191 <interpolation>rotational-deg</interpolation> 192 <property type="string">/ai/model/carrier/alpha-angle-deg</property> 193 </signal> 194 <signal> 195 <type>bool</type> 196 <property type="string">/controls/panel/custom-switch</property> 197 </signal> 198 </config> 199 </flight-recorder> 200 </sim> 201 202 203Signal Configuration 204-------------------- 205Template: 206 <signal> 207 <type>bool</type> 208 <interpolation>angular-deg</interpolation> 209 <property type="string">/controls/panel/custom-switch</property> 210 </signal> 211 212* type: The signal's type specifies the recording resolution - not the 213 type of the original property. The following types are supported: 214 215 - double: 8 byte/sample 216 - float: 4 byte/sample (default) 217 - int: 4 byte/sample, integer 218 - int16: 2 byte/sample, integer 219 - int8: 1 byte/sample, integer 220 - bool: 1 bit/sample (yes, 1 bit. 8 bools per byte). 221 222 String type is unsupported (too expensive). 223 224* interpolation: Specifies how values are interpolated during replay, i.e. 225 when replay is in slow-motion mode and more frames/second are required 226 than recorded, or when replaying data from the medium/long term memory. 227 Supported methods: 228 - discrete: No interpolation. Default for integer/bool types. 229 - linear: Standard linear interpolation. Default for float/double. 230 - angular-rad (or angular): Angular values in radians (0-2pi). 231 - angular-deg: Angular values in degrees (0-360). 232 233* property: Path to the property to be recorded. 234 235 236Advanced Configuration 237---------------------- 238- Multipe recorder configurations for a single aircraft are supported 239 (multiple "<config n=..>" sections for n=0,1,...). 240 Active configuration to be used for the replay system is selected via 241 /sim/flight-recorder/replay-config (= 0,1,...). 242 This can be useful for specific recorders for specific scenarios, 243 which should not be used by default. For example, a specific recorder 244 configuration could be provided which also records the position of 245 an aircraft carrier, of other AI aircraft, ... 246 This may also be useful for future use, i.e. to select another flight 247 recorded configuration for a different purpose, such as for the 248 multiplayer system. 249 250- Flight recorder configuration can be adapted during run-time 251 (configuration is visible in the property browser below 252 /sim/flight-recorder). However it is necessary to reset (reinit) the 253 replay subsystem first - which also erases earlier recordings. It is 254 not possible to mix recordings of different configurations on to a 255 single "tape". 256 257- Each configuration should be given a name. Useful for a (future) 258 selection GUI, when multiple configurations are available. 259 260 261Optimizing Performance 262---------------------- 263- Recording properties consumes memory and also CPU time. A few 264 additional properties don't matter much, but avoid execessive numbers. 265 Reduce the resolution (type) of signals to the minimum necessary to 266 save space. 267- Use "bool" types where possible, they are most efficient. 268- Avoid recording with "double" resolution (type "double"). Use "float" 269 instead - even if the original property in the property tree is a 270 "double" (almost all of them do). "float" precision is almost always 271 sufficient for recording/replay purposes, with few exceptions (like 272 latitude/longitude properties). 273- Use int16/int8 for "small" integer values. 274 275 276Recording/Replay Limits 277----------------------- 278- All properties can be recorded, however, only writable properties can 279 be replayed. Properties marked as read-only, or tied properties not 280 implementing the "set" method cannot be replayed. 281- Replaying a property overwrites the property's value. However, other 282 sources may also write to the same property - such as Nasal code, 283 autopilot rules etc. When multiple sources "fight" over a property's 284 value then the last update "wins" - resulting in a dependency to an 285 unknown/random sequence. Hence, during deplay, try to disable other 286 sources writing to properties which were recorded and should be 287 replayed. 288 If the other source cannot be disabled, check if you're recording the 289 right property. It may be better to record the input properties of the 290 other source instead (i.e. the inputs processed by the Nasal or 291 autopilot rule). 292 293__end__ 294 295