1AUTOMATIC PUSHBACK FOR FLIGHTGEAR
2http://gitlab.com/mdanil/flightgear-autopush
3
4Version 2.0.1
5
6Copyright (c) 2018 Autopush authors:
7 Michael Danilov <mike.d.ft402 -eh- gmail.com>
8 Joshua Davidson http://github.com/Octal450
9 Merspieler http://gitlab.com/merspieler
10Some of the code (c) FlightGear
11Distribute under the terms of GPLv2.
12
13
14This project aims to develop a generic pushback for JSBSim and YASim
15aircraft, with the following characteristics.
16
171. Do the pushback procedure automatically.
182. Scale to different aircraft with minimum changes to their logic.
193. Use no computer resources in flight.
20
21
22INSTALLATION
23
24Minimum FlightGear version: 2018.0
25
26NOTE: these steps cover the minimal testing setup. To get the most
27realism out of Autopush, you will have to add logic aircraft-side as
28described in the last step.
29
301. Copy the autopush.config.xml.template into your aircraft directory
31and the Goldhofert.xml into <your-airfraft>/Models/Autopush/
32
332. Set up the pushback logic.
34
35Add the following line under <sim><model> of your set.xml
36
37<autopush include="autopush-config.xml"/>
38
39Rename autopush-config.xml.template to autopush-config.xml and edit
40the file as described below.
41
42Alternatively, you can copy the contents of
43autopush-config.xml.template to under <sim><model><autopush> of your
44set.xml and make these modifications there.
45
46Change the aliases to point to the following data:
47
48steer-cmd-norm   nose wheel steering command norm
49yaw              nose wheel steering output norm or angle (see below)
50chocks           chocks command bool (or leave it until step 7)
51available        pushback availability bool (or leave it until step 7)
52
53Replace the MULTIPLIER in yaw-mult with:
54
55max steering angle  if yaw is norm
561.0                 if yaw is degrees
5757.3                if yaw is radians
58
59Replace PITCH with the pushback's pitch relative to aircraft. If your
60aircraft's ground pitch varies greatly, you can make an alias to
61property with calculated relative pitch.
62
63Replace MIN_RADIUS with the minimum allowed turning radius in m of the
64center of the aircraft during pushback procedure.
65
66NOTE: on some aircraft the turning radius is different for taxi and
67pushback. Please check the aircraft's literature.
68
69Replace STOP_DIST with the stopping distance in m from pushback speed.
70
71Add under <nasal> of your set.xml:
72
73 <autopush>
74  <file>Nasal/Autopush/autopush.nas</file>
75 </autopush>
76 <autopush_driver>
77  <file>Nasal/Autopush/driver.nas</file>
78 </autopush_driver>
79 <dynarr>
80  <file>Nasal/Autopush/dynarr.nas</file>
81 </dynarr>
82 <autopush_route>
83  <file>Nasal/Autopush/route.nas</file>
84 </autopush_route>
85
86Add under <sim><aircraft-data> of your set.xml:
87
88 <path>/sim/model/autopush/route/show</path>
89 <path>/sim/model/autopush/route/show-wingtip</path>
90
913. Connect the force to FDM.
92
93 3.a. JSBSim:
94
95  3.a.1. Add the following under <external_reactions> of your JSBSim
96         XML.
97
98 <force name="tractor" frame="BODY">
99  <location unit="M">
100   <x>FRONT-X</x>
101   <y>FRONT-Y</y>
102   <z>FRONT-Z</z>
103  </location>
104  <direction>
105   <x>1.0</x>
106   <y>0.0</y>
107   <z>0.0</z>
108  </direction>
109 </force>
110
111Replace FRONT-X, FRONT-Y, FRONT-Z with coordinates of your front
112bogey.
113
114  3.a.2. Add the following under <fdm><jsbsim><external_reactions> of
115         your set.xml.
116
117   <tractor>
118    <magnitude alias="/sim/model/autopush/force-lbf"/>
119    <x alias="/sim/model/autopush/force-x"/>
120    <y alias="/sim/model/autopush/force-y"/>
121    <z alias="/sim/model/autopush/force-z"/>
122   </tractor>
123
124 3.b. YASim. Add the following under <airplane> of your YASim xml.
125
126 <thruster x="FRONT-X" y="FRONT-Y" z="FRONT-Z" vx="1" vy="0" vz="0" thrust="100000.0">
127  <control-input axis="/sim/model/autopush/force-x-yasim" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
128 </thruster>
129 <thruster x="FRONT-X" y="FRONT-Y" z="FRONT-Z" vx="0" vy="1" vz="0" thrust="100000.0">
130  <control-input axis="/sim/model/autopush/force-y-yasim" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
131 </thruster>
132 <thruster x="FRONT-X" y="FRONT-Y" z="FRONT-Z" vx="0" vy="0" vz="1" thrust="100000.0">
133  <control-input axis="/sim/model/autopush/force-z-yasim" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
134 </thruster>
135
136Replace FRONT-X, FRONT-Y, FRONT-Z with coordinates of your front
137bogey.
138
1394. Add the pushback model to your Model XML:
140
141 <model>
142  <name>Pushback</name>
143  <path>MODEL</path>
144  <offsets>
145   <x-m>FRONT-X</x-m>
146   <y-m>FRONT-Y</y-m>
147   <z-m>FRONT-Z</z-m>
148  </offsets>
149 </model>
150
151Replace FRONT-X, FRONT-Y, FRONT-Z with coordinates of your front
152bogey. Replace MODEL with one of the following file names:
153
154Autopush/Goldhofert.xml  for Goldhofer towbarless pushback
155
156Edit the "SETTINGS" part in the beginning of the Goldhofert.xml to match
157your setup.
158
1595. Add gui/dialogs/autopush.xml to your aircraft's menu (see
160   FlightGear documentation for editing the menu).
161
1626. If you have a bug tracker, please add a note, that autopush related
163   bugs should be reported here:
164
165https://gitlab.com/mdanil/flightgear-autopush/issues
166
1677. Launch the simulator and try Autopush. After making sure it works,
168   complete the support by implementing some logic in your aircraft
169   and connecting the rest of the interface.
170
171CAUTION.
1721. Make sure to HAVE A BACK-UP COPY of your work.
1732. If anything is not clear in the instruction below, do not guess --
174   contact the authors.
175
176 7.1. When pushback is connected ("/sim/model/autopush/connected"),
177      nose wheel steering must actuate at different speed, depending
178      on its rollspeed. The exact dependency is different per aircraft
179      and used pushback visual, and for most aircraft the only way to
180      find it is trial and error until it "looks right":
181      - the input must be taken from pushback steering command norm
182        (set by autopush-config.xml, default:
183        "/controls/flight/rudder");
184      - the output must be written to pushback orientation in degrees,
185        radians or norm (set by autopush-config.xml, default:
186        "/gear/gear[0]/steering-norm").
187
188 7.2. Set or alias (in autopush-config.xml) the availability property
189      "/sim/model/autopush/available". It must be false if e.g. the
190      aircraft is moving too fast, the front wheel is not touching
191      the ground, the aircraft is damaged or is outside of an airport
192      etc.
193
194 7.3. Make Autopush remove wheel chocks by setting the alias in
195      autopush-config.xml to the chocks property. (default:
196      "/controls/gear/wheel-chocks").
197
198 7.4. Optionally, Autopush may be made visible in multiplayer by
199      duplicating the properties used in its model.xml into some
200      unused MP properties. See the list in
201
202https://sourceforge.net/p/flightgear/flightgear/ci/next/tree/src/MultiPlayer/multiplaymgr.cxx
203
204      around line 215, and then using those properties in the
205      "SETTINGS" part of Autopush model.xml.
206
207   After making these changes check the Autopush model.xml's settings
208   and make sure they match the setup. Launch the simulator and try
209   Autopush.
210
211
212TUNING
213
214There should normally be no need to change the coefficients, because
215the inertia of different aircraft is already taken into account. But
216the gear setup may differ enough to require some tuning.
217
218If these settings are changed during simulation, they take effect
219after disconnecting and reconnecting the pushback.
220
221Pushback (/sim/model/autopush):
222
223Coefficient  Unit                    Description
224
225K_p          ((km/h)/s)/(km/h)       Proportional coefficient of PID.
226                                     Defines the start/stop throttle
227                                     and immediate response to speed
228                                     difference deltaV = V_set - V.
229
230F_p          (km/h)/s                Proportional clipping.
231
232K_i          ((km/h)/s)/((km/h)*s)   Integral coefficient of PID.
233                                     Defines how fast the steady
234                                     throttle is ramped during the
235                                     push.
236
237F_i          (km/h)/s                Integral clipping.
238
239K_d          -((km/h)/s)/((km/h)/s)  Differential coefficient of PID.
240                                     Stabilizes the approaching of
241                                     steady throttle.
242
243F_d          (km/h)/s                Differential clipping.
244
245Pushback driver (/sim/model/autopush/driver):
246
247Coefficient  Unit        Description
248
249F_V          km/h        Max towing speed in auto mode.
250K_psi        1/deg       Amount of steering per heading correction.
251F_psi        1/deg       Max steering per heading correction.
252K_deltapsi   -1/(deg/s)  Amount of steering compensation per heading
253                         derivative.
254F_psi        1/(deg/s)   Max amount of steering compensation per
255                         heading derivative.
256