| 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/rpc.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 | */
|
|---|
