| 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.StageCheker "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.flight.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 | |
|---|
