source: doc/overview.dox@ 586:6e5ba20962e3

Last change on this file since 586:6e5ba20962e3 was 474:f24264c8a82f, checked in by István Váradi <ivaradi@…>, 12 years ago

Fixed unresolved references in the developers' documentation

File size: 12.8 KB
Line 
1/*! \mainpage MAVA Logger X Developers' Documentation
2 *
3 * \section intro Introduction
4 *
5 * This (partially generated) documentation describes the MAVA Logger
6 * X from a developer's perspective. Its purpose is to give enough
7 * information, so that a developer could understand how the software
8 * works in general, and easily understand the code to be able to make
9 * modifications to it.
10 *
11 * Note, that to be able to understand the code most effectively, it
12 * is important to either use the application actively, or to read its
13 * user documentation carefully.
14 *
15 * \section overview Overview
16 *
17 * The application was written in
18 * <a href="http://python.org">Python 2</a>. The Python wrapper
19 * <a href="http://gtk.org">Gtk+</a> toolkit was used for the graphical
20 * user interface. The program is designed to run on both Windows and
21 * Linux, though as of this writing only the Windows version can be
22 * used practically. However, Linux distributions move towards Gtk+ 3
23 * as the primary toolkit, while it has no reliable port for Windows
24 * yet. Therefore it was decided to support both Gtk+ 2 and 3
25 * depending on the platform. For Gtk+ 2 the
26 * <a href="http://pygtk.org">PyGTK</a> wrapper is used, while for Gtk+
27 * 3 the <a href="https://live.gnome.org/PyGObject">PyGObject</a>
28 * bindings. See the mlx.gui.common module for information on how the
29 * differences between these toolkits are handled.
30 *
31 * At present only Microsoft Flight Simulator 2004 and X (also,
32 * perhaps, Prepar3D) are supported, and are accessed via the
33 * <a href="http://www.schiratti.com/dowson.html">FSUIPC</a>
34 * interface. The author has created a Python mapping for it, which
35 * has been submitted for inclusion into the SDK, so it will hopefully
36 * appear in its next version. It is planned to support X-Plane in the
37 * near future (hopefully by the end of 2012) on both Linux and
38 * Windows.
39 *
40 * \subsection overview_devenv Development environment
41 *
42 * The software is primarily being developed on Linux, but is possible
43 * to perform development on Windows as well. You need to have Python
44 * 2.7.x installed as well as one of the above mentioned wrappers for
45 * Gtk+ and Gtk+ itself. Since Python is an interpreted language,
46 * there is no need for any special build system.
47 *
48 * Python and Gtk+ are readily available on most Linux distributions,
49 * but some links are probably useful for Windows users:
50 * \li Python has its own Windows installers: http://www.python.org/download/releases
51 * \li PyGTK provides convenient all-in-one installers including Gtk+
52 * itself: http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.24
53 * \li The Windows version uses some Python extensions: http://sourceforge.net/projects/pywin32/files
54 * \li To create install packages, you also need py2exe: <a href="http://www.py2exe.org/">http://www.py2exe.org</a>,
55 * \li as well as the Nullsoft Install System: http://nsis.sourceforge.net/Main_Page
56 *
57 * The install package can be created by running the \c makeinst.bat
58 * file. It contains some absolute paths, so check those befure
59 * running the batch file. Windows is needed currently to create an
60 * install package.
61 *
62 * On Linux you can use the \c makesdist.sh script to create the
63 * archive that you can extract on Windows. This archive goes in to
64 * the \c dist subdirectory, and contains everything needed (from the
65 * logger) to create the package.
66 *
67 * \section arch Architecture
68 *
69 * The two major parts of the application are the GUI and the rest of
70 * it (let's call it the "business logic").
71 * The main interface for the GUI is the mlx.gui.gui.GUI class, which
72 * is referenced from the business logic only from the
73 * mlx.flight.Flight class. The rest of the business logic uses the
74 * actual instance of this class to access values entered into the
75 * GUI by the user.
76 *
77 * The program uses a few threads. The main thread is reserved for the
78 * GUI, which has two implications:
79 *
80 * -# No GUI operations should be executed directly from another
81 * thread. Instead, use \c gobject.idle_add to "inject" the
82 * operation into the main thread.
83 * -# To ensure the responsiveness of the GUI, only operations
84 * that take a short time should be executed in the GUI thread.
85 *
86 * \subsection arch_buslog Business Logic
87 *
88 * The business logic part deals with the connection towards the
89 * simulator. The mlx.fsuipc module implements this connection using
90 * the FSUIPC interface. Its \ref mlx.fsuipc.Simulator "Simulator"
91 * class creates a \ref mlx.fsuipc.Handler "Handler" object, which
92 * starts its own thread, in which the FSUIPC requests are called. In
93 * case of reading data from FSUIPC, the data is passed to a callback
94 * function, which is called in this thread. This should be considered
95 * when the retrieved data is processed on the GUI in same way
96 * (e.g. displayed). The main interface towards the simulator is the
97 * \ref mlx.fsuipc.Simulator "Simulator" class, so if another
98 * simulator is to be supported, a class with the same (or at least
99 * sufficiently similar) public interface should be implemented.
100 *
101 * The most important function of the program is the
102 * continuous monitoring of the aircraft's parameters and some other
103 * data. The monitoring is started using the \ref
104 * mlx.fsuipc.Simulator.startMonitoring "startMonitoring" function of
105 * the simulator object. If started, it calls the \ref
106 * mlx.acft.Aircraft.handleState "handleState" function of the
107 * mlx.acft.Aircraft instance used. The mlx.acft module contains one
108 * child class of \ref mlx.acft.Aircraft "Aircraft" for each aircraft
109 * type in the MAVA fleet. These subclasses contain the type-specific
110 * behaviour, but the main handling logic is in the \ref
111 * mlx.acft.Aircraft "Aircraft" class.
112 *
113 * Upon calling its \c handleState function, it calculates the
114 * smoothed values of IAS and VS, and then calls each "checker". A
115 * checker is an instance of a subclass of mlx.checks.StateChecker,
116 * which checks a one or a few parameters that are important from some
117 * aspect of the correct execution of a flight. For example, a checker
118 * may check if the \ref mlx.checks.StrobeLightsChecker
119 * "strobe lights" are switched on and off at the right stages of the
120 * flight. But some checkers simply log some \ref
121 * mlx.checks.AltimeterLogger "value" whenever it changes
122 * in an "interesting" way, or \ref mlx.checks.ACARSSender "send the
123 * ACARS" periodically.
124 *
125 * There is also a \ref mlx.checks.StageChecker "checker" which
126 * detects the changes in the stage of the flight, and calls the
127 * \ref mlx.acft.Aircraft.setStage "setStage" function of the
128 * aircraft, if there is a change. It first calls the
129 * \ref mlx.flight.Flight "flight"'s \ref mlx.flight.Flight.setStage
130 * "setStage" function, which notifies the GUI and the \ref
131 * mlx.logger.Logger "logger" of this change, and records the block
132 * and flight times. Then the aircraft's \c setStage function logs
133 * some values in case of certain stages, such as the takeoff weights
134 * and speeds when the takeoff stage is entered. After calling the
135 * checkers, the \c handleState function of the aircraft calls the
136 * \ref mlx.flight.Flight.handleState "function" with the same name of
137 * the flight. It again records some statistical data, such as the
138 * flown distance and the amount of fuel used, and calls the \ref
139 * mlx.soundsched.SoundScheduler "sound scheduler" to check if some
140 * backround sound should be played. If the check list hotkey is
141 * pressed, the \ref mlx.soundsched.ChecklistScheduler
142 * "checklist scheduler" is notified too.
143 *
144 * As mentioned, there is a \ref mlx.logger.Logger "logger" in the
145 * application, which contains the textual log lines as well as the
146 * faults and their scores.
147 *
148 * The business logic part contains many other components, but they
149 * are quite simple and are built around the principles mentioned
150 * above. Consult the documentation and the code of the relevant
151 * modules for more information.
152 *
153 * \subsection arch_gui GUI
154 *
155 * As mentioned, the GUI is implemented using Gtk+. This toolkit
156 * provides the Glade graphical user interface designer, but due to
157 * the requirement of supporting both Gtk+ 2 and 3, and due to a so-so
158 * experience with Glade in an earlier project, it was decided to not
159 * use it. Instead, the GUI elements are created and handled by
160 * hand-written code.
161 *
162 * The central class of the graphical user interface is
163 * mlx.gui.gui.GUI. Upon creation, it creates the rest of the GUI,
164 * sets up the menus and shortcuts, etc. It also maintains the
165 * connection to the simulator and creates the \ref mlx.flight.Flight
166 * "flight" and \ref mlx.acft.Aircraft "aircraft" objects as
167 * needed.
168 *
169 * To understand the operation of the GUI, one should be familiar with
170 * Gtk+, but otherwise it is pretty straighforward. See the
171 * documentation of the relevant modules for more information.
172 *
173 * \section newtype Adding a new aircraft type
174 *
175 * While new aircraft types will probably not be added too often, here
176 * is a checklist about what should be modified when such a
177 * requirement arises.
178 *
179 * First, it is worth to know what data you need to add the new type:
180 *
181 * \li the aircraft's type name and its ICAO code
182 * \li the following weights: DOW, MZFW, MTOW, MLW
183 * \li the flap settings and their speed limits
184 * \li the speed limit for extending/retracting the gear (VLE)
185 * \li the number and types of the fuel tanks
186 * \li the type code the MAVA website uses to identify the type
187 * \li if the plane has reversers, what is the operating limit speed,
188 * if any
189 * \li does the plane support the notion of a takeoff derate, and if
190 * so, what data should be given
191 * \li what lights does the plane have
192 *
193 * If you have the data, you can add the type by modifying the source
194 * files as per the checklist below:
195 *
196 * -# \c src/mlx/const.py: look for the constants named AIRCRAFT_xxx.
197 * Add the new type at the end of the list of those constants, with
198 * a number 1 greater than the number of the last existing
199 * type. The part of the constant's name after the underscore (xxx
200 * above) should be the ICAO code of the aircraft type.
201 * -# \c src/mlx/const.py: below this list of constants, you can find
202 * an array named \c aircraftTypes. Add the type constant to it.
203 * -# \c src/mlx/const.py: further below you can find a dictionary
204 * mapping te aircraft type to the corresponding ICAO codes. Add
205 * the new type to it.
206 * -# \c src/mlx/acft.py: add a new subclass of \ref
207 * mlx.acft.Aircraft. Its name should be the ICAO code. Check an
208 * existing aircraft and add the same variables containing the
209 * weights, the flap speed limits and the gear speed limit. There
210 * may be some other member variables or functions that should be
211 * -# \c src/mlx/acft.py: there is a dictionary named \c _classes
212 * towards the end of the file. Add the type to it.
213 * -# \c src/mlx/web.py: the \ref mlx.web.BookedFlight class contains
214 * two dictionaries, the mapping between the types and the values the MAVA
215 * website uses to identify the type. Add the appropriate values
216 * here.
217 * -# \c src/mlx/fsuipc.py: add a subclass of \ref
218 * mlx.fsuipc.GenericAircraftModel for the new type named the ICAO
219 * code of the type followed by the word \c Model. Implement its
220 * constructor to supply the base class with the flaps notches
221 * (starting with 0), the array of constants describing the fuel
222 * tanks the model has, and the number of engines. Also implement
223 * the name of the model, which should be something like
224 * "FSUIPC/Generic ...". If necessary implement other functions or
225 * set other members.
226 * -# \c src/mlx/fsuipc.py: add the new type and model class to the
227 * dictionary named \c _genericModels towards the end of the file.
228 * -# \c src/mlx/fsuipc.py: if you have a model that has some
229 * non-generic characteristics, create a specific class for
230 * it. This class should be a subclass of the generic class
231 * created, and it should be registered at the bottom of the file,
232 * as the other models are.
233 * -# \c src/mlx/gui/common.py: this file contains a dictionary called
234 * \c mlx.gui.common.aircraftNames. Add the new type it it. It
235 * contains the mapping from the type constants to their
236 * language-specific names. The string ID is "aircraft_" followed by
237 * the lower-cased ICAO code.
238 * -# \c locale/hu/mlx.po, locale/en/mlx.po: the beginning of this
239 * file contains mapping from the string ID previously used to the
240 * actual name of the aircraft. Add the new type as appropriate.
241 * -# \c dcdatagen.py: this program generates some source and message
242 * files related to the delay codes. Currently there are two
243 * tables, one for old-timer types and the other for the "modern" types.
244 * The file contains a list of lists called \c typeGroups. Add the
245 * type's ICAO code the appropriate list.
246 *
247 * When all the changes have been made, run \c make in the root
248 * directory to update some source files.
249 */
Note: See TracBrowser for help on using the repository browser.