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