Flightdeck-UI Multi-Variable Monitor (MVM) Release 0.2.1 (Stable) ----------------------------------------------------------------- The MVM allows you to quickly create a Flightdeck-UI application -- even without coding (of course, you are welcome to code as much as you want -- see the MVM plug-in module 'MVMDefaultCmd.py' to get started). For instance, you can put together several controls to monitor the amount of free disk space, network activity, etc. on your machine. Other applications (e.g. monitoring multiple servers or even industrial processes) are also possible -- several control files are provided as examples. Under Unix, the standard Python 'commands' module can also be used in control files. MVM includes a graphical editor with theme support. Many parameters (e.g. colors, size of the gauges, etc.) can be varied on a per-element basis, or across all elements in the application. You can also add your name and a brief message to control or theme files that you create (see the examples included). Any text editor can be used for this; your name and message will be shown in the 'About' dialog. Below is a quick manual to get you started with MVM. Like lots of popular Open Source/Free Software (including the Linux kernel ), MVM is released under the GPL license -- see GPLv2.TXT. The Flightdeck-UI library is released under the LGPL license (see LGPLv2.1.TXT). 1. A Brief Manual ----------------- MVM does not follow the conventional GUI paradigm in its layout. There are very few popup dialog boxes, and no menus at all. Instead, all of the controls are laid out in a single large window, so that they are visible all of the time. This approach (based, like the rest of Flightdeck-UI, on the design of aircraft instrumentation) ultimately makes it easier to work with the application. For a detailed explanation, see Donald A. Norman's classic book, _The Psychology of Everyday Things_ (also known as _The Design of Everyday Things_). *** Quickstart (assuming that Python, Tkinter and TCL are installed already): (i) Download the MVM archive -- includes the Flightdeck-UI library. (ii) Unpack the distribution to a directory of your choice. (iii) Run 'python /mvm.py' on Unix, or 'pythonw \mvm.py' on Windows, where is the directory where the 'mvm.py' file has been copied; will most likely end with 'fdui-mvm-0.2.0'. (iii) Also try some examples, shown below ( is 'python' or 'pythonw', depending on the platform; is the install directory of MVM; also use '\' instead of '/' on Windows). The following 2 examples require a working Internet connection. /mvm.py -sn -f /ctrl-files/tpool/usa-temp-tp.mvm /mvm.py -sn -f /ctrl-files/tpool/europe-temp-tp.mvm The following 2 examples do not require Internet access. /mvm.py -sn -f /ctrl-files/dialmania.mvm /mvm.py -sn -f /ctrl-files/snowman.mvm *** Pay attention to safety and security: (i) Don't use theme and especially control files from unknown sources. (ii) MVM will execute any commands that you tell it to. DO NOT USE DESTRUCTIVE COMMANDS THAT DELETE FILES, ETC., BECAUSE MVM WILL HAPPILY RUN THEM OVER AND OVER AGAIN IN ITS SAMPLING LOOP. (iii) Keep in mind that MVM executes commands in a continuous loop after you click the 'START' button. It can execute these commands many times a second. If your commands are writing files to disk, sending messages over a network, etc., be sure that no harmful effects will result from such repeated execution, and watch carefully how high you set MVM's sampling rate. (iv) There is absolutely no need to run MVM with root or administrator privileges, and you should refrain from doing so. By default, MVM starts in Edit mode, which allows Flightdeck-UI elements to be added, deleted and configured. The 'SHRINK' button in the editor window launches Run mode, where all editing controls are removed, and the Flightdeck-UI elements are packed together in a reasonably small amount of space. Note that the actual monitoring will not begin until you click the 'START' button. The '-s' (or '--shrink') command line option will launch immediately into Run mode. Closing the Run mode window will bring up the Edit mode window. If, however, the '-n' (or '--noedit') option is also given, then the Edit mode is disabled, and closing the Run mode window exits MVM. This option also causes MVM's monitoring loop to start immediately. You can use the two options together in your startup scripts, to launch a running MVM monitor. In Edit mode, you create MVM control files (with the 'mvm' extension by default). At the top of the window is the status bar and other global controls. You can load control files and edit them, load theme files, try running your control files (click 'START'), etc. 'CLEAR' erases the current message in the status bar. 'SHRINK' will launch Run mode, and close the edit window. Closing the Run mode window shows the Edit window again, as stated previously. Below the global controls, most of the Edit window is taken up by the element panes, with one Flightdeck-UI element per pane. Unless a previously made control file has been loaded, MVM starts with no panes displayed. Clicking the 'ADD>' button in the third row will add a pane. The new pane is mostly empty; it will be filled in once you select the type of element you want in the drop box. When a pane is displaying an element, the element is shown towards the top of the pane. Text entry boxes below the element allow you to change its appearance and functionality. Remember to click on the pane's 'UPD' button to apply your changes (this also records them so that they can later be saved). The 'EXP' button will stretch the textboxes in the frame, which makes editing easier. Click the button again (it will have been renamed 'SHR' after the first click) to shrink the textboxes back to their regular size. The topmost textbox in every pane (labeled 'bg') is used to set the filename for the element background. You can specify pictures of your choice: a logo, or even a photograph of an actual instrument. MVM uses standard Tkinter image handling (i.e. GIF and PPM images are allowed). If you do not want to type the filename, place the cursor in the textbox (usually by left-clicking), and right-click -- a dialog box will come up, and you can select the file of your choice. Several textboxes deal with setting colors (including comma-separated lists of colors). Just like with the 'bg' textbox, you can place the cursor on the color name that you want to change, and right-click to bring up a color dialog. In a comma-separated list, only the color name on which the cursor was positioned will be replaced by a text representation of the new color that you select. Below the 'ADD>' button are three controls that allow easier operation of MVM on 800x600 screens, which cannot show the full height of the editor window. These consist of a pair of checkboxes and a button. These checkboxes determine which types of controls will be visible in the element panes to the right. The 'Style' checkbox indicates that the controls mostly related to the element's style (such as the needle color) should be shown. The 'Func' checkbox plays the same role for function-related controls (such as the command that is executed for that element during every sampling loop). Hiding one or the other type of control greatly reduces the edit window height, thus allowing it to fit much better on a smaller screen. For convenience, the 'Togl' button reverses the state of both checkboxes when the button is clicked. If only one checkbox is selected, clicking 'Togl' will effectively swap the category of controls being displayed in the panes to the right, without making the user deselect one checkbox and select the other. Errors encountered by MVM are displayed in the status bar. Most errors also highlight the control on the screen that caused the error. A number of error messages use less specific highlighting, and set the background of the entire pane instead. Theme files (with the 'mtm' extension by default) can be loaded at any time. Click on 'APPLY ALL' to force all currently displayed controls to style themselves based on the theme. Right beside 'APPLY ALL' is the 'UNLOAD' button, which removes the theme (click on 'APPLY ALL' after removing the theme if you want the displayed panes to start using default styling again). There is a second 'UNLOAD' button -- beside 'SAVE'. This button unloads control files. If you want to start writing a new control file from a 'clean slate', use the 'UNLOAD' button to fully remove the old one (this also cleanly shuts down any plug-in modules that have been initialized). If you are reading in a control file by clicking the 'LOAD' button, however, there is no need to 'UNLOAD' the previous file -- it happens automatically. By far the easiest way to get started quickly with MVM is to use the example files supplied with the package. Load a file, change one thing at a time, and you should soon learn what all the controls do. Click on 'ABOUT' for helpful hints on the loaded files. 2. Release Notes ---------------- * MVM 0.2.1 (Stable) -- Library portion of the release changed to the LGPL license. * MVM 0.2.0 (Stable) -- This is a stable (production) release of MVM. -- Most of the sampling logic is now in the 'MVMSampler' module. The addition of a resample mode (which retries periodically if data is not ready, up to a configurable number of times) allows many different concurrency models (e.g. thread pools, asynchronous I/O) to be supported via plug-in modules. -- An HTTP plug-in module based on 'asyncore' is now included ('MVMasynchttpCmd'), as is a 'urllib' module which uses a thread pool ('MVMurllibTpCmd'). The original, synchronous 'urllib'-based module ('MVMurllibCmd') is also provided in this release. -- There are significant enhancements (all backwards compatible) with respect to functions in plug-in modules. The enhancements (listed below) makes it possible to write very simple or very complex plug-ins. + It is now possible to use many different functions in a plug-in module, by specifying them with the . syntax (in place of just the ) in control files. The older syntax (which implies that the 'getoutput' should be used) is still accepted. + Functions may return a float, an int or a long, in addition to a string (which continues to be supported). In case of a numerical value return, the regular expresson filter is ignored; the value is accessed via 'g[0]' in the numerical expression. + Functions may take no arguments -- in this case, the command parameter specified in the control file is simply not used. The old single argument of string (which is used to pass the command) continues to be supported. + Functions may specify that they are not ready to provide data: this is done by returning the output of the 'retval_dnr' (Data Not Ready) function. The new 'DriverUtil' module defines 'retval_dnr'. A DNR return will force MVM to retry sampling a configurable number of times. Each resample is preceeded by a brief pause (also configurable). This feature allows the plug-in module to implement asynchronous I/O, thread pools and other concurrency models. + Plug-in modules may implement 'fduif_stop' and 'fduif_unload' functions. The former is called when sampling stops; the latter is used to cleanly shut down the plug-in (e.g. by telling threads to exit). Both functions take no arguments, and are optional (i.e. MVM will not complain if they are not present, so there is no need to implement do-nothing versions). See 'MVMasynchttpCmd', 'MVMurllibCmd', and 'MVMhttplibTpCmd' modules for examples. -- Errors in Run mode are now displayed in a popup window, which gives the option of either exiting Run mode, or restarting sampling. For "fatal" errors (i.e. ones that stop sampling), the offending element is highlighted, just like in Edit mode. -- In Edit mode, digital output is now displayed for every gauge (digital output for the Run can be turned on or off as before). -- Using the 'EXP'/'SHR' no longer forces an update -- the new behavior avoids some errors, and is easier for the user. -- "Local" updates (e.g. adjusting the sampling rate using a Dial) no longer force caching plug-ins (such as 'MVMurllibCmd') to update themselves. This makes the application much more responsive (in many cases, responsiveness can be further improved by using 'MVMasynchttpCmd' or 'MVMhttplibTpCmd' in place of 'MVMurllibCmd'). -- 'MVMurllibCmd' no longer announces which URLs are being read; the synchronous I/O used in this module means that Tkinter will not always have a chance to display these messages at the right time. * MVM 0.1.2 -- The control file options have changed slightly. Old control files will still load in this version, but previous MVM implementations will not be able to read the new MVM files. Changes are detailed below. + The little-used 'mscale_DE' parameter has been removed. It is now treated as always having the value of 1. + The 'offst_DE' parameter has been added. It has the effect of moving the zero-point of a gauge away from the default position on the dial. Since this option was not available before, the value of 'offst_DE' in older files is assumed to be 0 (i.e. leave the zero-point of the gauge at default). + An optional 'SAMPLE-RATE' parameter has been added to the header. It must be set via a text editor. When present, 'SAMPLE-RATE' (whose value is interpreted as a floating point number) is used to set the MVM sampling rate upon loading of the control file. -- An additional element (labeled 'BndedQty' in the element drop-down list) has been added. This element looks like the 'Rate' element, but is designed to display a quantity rather than a rate. It is bounded because the needle has a limited range of travel -- unlike the Altimeter-style 'Quantity', which can wrap around again and again. 'BndedQty' is useful because it has the same critical, warning and normal color bands as does 'Rate'. -- Server monitoring features are being introduced in this version (see module 'MVMurllibCmd'). The features use the standard 'urllib'. For reasons why things were done this way, see the monitoring whitepaper at "http://www.openlight.com/fdui/fdui-monitoring-html/book1.html". -- Updates can be slow when using the 'MVMurllibCmd' module (this is especially noticeable with dial elements and other input controls which do not operate until an update completes). Concurrency (either through threads or via 'asyncore') will be introduced in future releases. -- The control file specifications of supplementary digital outputs in Run mode are no longer overridden by the settings in the theme file. -- The 'About' dialog still does not expand enough with all platforms/fonts. For now, a scroll bar has been added so that all text can be viewed even if the dialog is sized too small. * MVM 0.1.1 -- With the addition of the 'Style' and 'Func' checkboxes together with the 'Togl' button. (all on the left side of the Edit mode window), MVM Edit mode can be used quite easily on an 800x600 screen, because either one or the other category of control element may be hidden, thus causing the editor window to reduced in height. -- The 'About' dialog size now adapts a lot better to the number of lines (which can vary by a large margin depending on the theme and control file loaded) that it needs to display. * MVM 0.1.0 -- Currently, a 1024x768 screen is needed for proper operation in Edit mode (shrunk Run mode windows can, of course do with far less). -- The 'Dial' element currently controls the MVM sampling rate only (plug-in modules which would extend this should be, however, quite easy to write). -- Needs additional handling for window scaling. -- Not all error conditions flag a control via AnunStatus. -- Some error conditions cause non-specific flagging: either the gauge element or the background of the whole frame is highlighted, rather than one individual entry box. -- AnunStatus error messages for problems during sampling tend to be cryptic. -- Specifying a background image will hide AnunStatus highlighting in gauges. -- When changing the gauge type, all values (including cmd, filt and expr fields) in that pane are reset. -- The expand feature (used to widen the entry boxes in a pane for more convenient editing) is done via the same method as the update, and hence forces an update (i.e. all the values entered in the pane will be read and processed). -- When files are saved, the ordering of name-value pairs is non-intuitive, and changes made manually may be reordered (although this does not alter their effect). -- Does not use text mode to load/save under Windows. -- Control file load routine currently strips away all comments, which will then disappear if the file is saved again. 3. Features Planned for Future Releases --------------------------------------- -- Undo/Redo. -- Support for more types of keystrokes for turning 'Dial' knobs. -- Python Distutils-based distribution. -- A theme editor. -- Internationalization features. -- Better support for single-button mice. -- Enhanced theme handling, which keeps track of which parameters the user changed in each pane, and applies the theme only to unmodified parameters. -- The concept of mini themes that can be assembled together into larger mini themes, to create a certain kind of instrument, for example, or even a large theme encompassing an entire application. -- The Run mode will be split off into a separate program, which will be as small as possible so that it could be easily ported (e.g. to Jython, wxPython, etc.). The Edit mode will continue with Tkinter.