December 1, 2005
This file explains how to get Flightdeck-UI Online up and running quickly on your site.
Flightdeck-UI Online is a web dashboard (runs entirely in your browser) which is based on the ideas of aircraft instruments and controls. You can use this system to monitor servers, networks, industrial processes or any other data. Flightdeck-UI Online is released under version 2 of the GPL license -- see file GPLv2.TXT that came with this distribution.
The latest version of Flightdeck-UI Online is available at:
Flightdeck-UI Online requires the following packages on the server. The versions listed are the earliest needed; you should have no trouble with later releases of these packages.
- Apache 2.0.48
- Python 2.3
- mod_python 3.1.3
In addition, you should have the "iostat" command available for the "demo" control panel. If "iostat" is missing, one of the instruments in the panel will be covered up with a red square, and you will see errors in the Apache logs. The rest of the demo will still work.
On the client, a browser with the Flash 7 plugin installed is needed (although Flash 6 may also work).
This is a quick installation guide. You should also read the section "Installation Options" if you want to deviate from the instructions given here.
The distribution tar archive contains the following subdirectories.
Ignore "flash_src". Move (or copy) "Flightdeck-UI" into "/opt". You MUST set the permissions so that Apache can read the entire "Flightdeck-UI" directory tree.
The contents of "docroot" go into your document root. You may also store them elsewhere; just remember to put the appropriate "Alias" directives into your Apache configuration file; "/fdui-panels" should be aliased to where the "fdui-panels" subdirectory is in your filesystem. Likewise, "/fdui-resources" should be aliased to the "fdui-resources" subdirectory.
Alias /fdui-panels /var/fdui/fdui-panels Alias /fdui-resources /var/fdui/fdui-resources
if you stored the contents of "docroot" in "/var/fdui".
You will need to load "mod_python" in your apache configuration file. Here is an example.
LoadModule python_module /usr/lib/apache2/modules/mod_python.so
Finally, add the following to your apache configuration file.
Options FollowSymLinks AllowOverride None SetHandler mod_python PythonHandler mod-python-driver
Start (or re-start) Apache. Browse to "http://YOUR-URL/fdui-panels". You should see a static display of some gauges.
Next, launch the Flightdeck-UI panel daemon in order to see a live demo (feel free to substitute "python2.3", etc. for "python", if it is what you normally use).
python /opt/Flightdeck-UI/python/fdui-run-panel.py -m demo-panel -n demo
Refresh the page in your browser. The live demo will run for 30 seconds. Note that the daemon will not actually run in the background as a daemon unless you use the "-d" option.
BE SURE TO READ THE NEXT SECTION FOR IMPORTANT INFORMATION ON BANDWIDTH USAGE AND CHARGES.
A Flightdeck-UI Online control panel is defined by a module in "/opt/Flightdeck-UI/conf". Two sample modules are provided in the distribution -- "demo-panel.py" and "weather-panel.py". You can use these modules as examples when building your own control panels.
In particular, note the "registry.setPeriod(..." command in the example modules. THIS CONTROLS HOW OFTEN THE FLASH CLIENT WILL GET UPDATES FROM THE SERVER.
There are two other configuration files in "/opt/Flightdeck-UI/conf": "versions.conf" and "panels.conf". The first controls which versions of the client "canvas.swf" will be allowed to connect to this server. DO NOT CHANGE "versions.conf" IN THIS RELEASE, OR YOUR CLIENTS WILL JUST SHOW AN ERROR MESSAGE, AND REFUSE TO RUN.
The "panels.conf" contains entries for every control panel, separated by commas. Here is an example of an entry.
This entry says that a panel named "demo" should run for 30 seconds, and then stop with a message, saying that the demo is finished. Putting "0" instead of "30" would allow "demo" to run forever.
*** BE VERY CAREFUL ABOUT PANELS THAT SAMPLE AT HIGH RATES AND *** NEVER TIME OUT.
Remember that Flightdeck-UI Online is a live monitoring system, not a static web page. If a thousand people load your control panel, and leave it running in their browsers over the weekend, you could pay a lot of money in bandwidth charges.
Each update typically transfers several kilobytes of data. While this is not a large amount by itself, the total can grow quickly. It is safest to run publicly accessible panels in demo mode (i.e. with a small, non-zero timeout like 30). For another layer of safety, it is also advisable to set up server-side bandwidth limiting that is not dependent on Flightdeck-UI Online.
You will need to run one instance of the Flightdeck-UI Online panel daemon for every control panel. It does not matter how many clients actually connect to view the panel -- one daemon will supply the information that they will all share.
Here is how to launch the panel daemon, from an earlier example.
python /opt/Flightdeck-UI/python/fdui-run-panel.py -m demo-panel -n demo
Add the "-d" option to the above if you want the daemon to actually run as a daemon in the background.
You MUST have Apache already running, and properly configured to execute the "mod-python-driver.py" script when appropriate. The panel daemon NEEDS to access the web server on the local machine, in order to log messages.
The "-m" option specifies the panel configuration module. You place these modules in "/opt/Flightdeck-UI/conf". The module file itself will have a ".py" extension, but you should not specify it to the "-m" option.
The "-n" option names the control panel. The name should consist of only letters and numbers, with no whitespace. It should also match an entry in "/opt/Flightdeck-UI/conf/panels.conf" as described in the previous section.
In order to view a panel named "mypanel", browse to
A default HTML template ("/opt/Flightdeck-UI/conf/html-template.txt") will be used to display the panel. If you write your own template specifically for "mypanel", you should name it
Alternatively, just embed the control panel in a web page; see "http://www.openlight.com/demo.html" for an example on how to do this.
If you wish to install Flightdeck-UI Online differently from the instructions given here, you will need to make changes in some (or all) of the following subdirectories of the installation archive.
- "Flightdeck-UI/python/FdUI/config/Params.py". The parameters that you will most likely need to change are at the top of the file.
- "docroot/fdui-panels/mod-python-driver.py". The line "sys.path.append('/opt/Flightdeck-UI/python')". You will need to change this in order to reflect your installation.
- The HTML templates in "Flightdeck-UI/python/FdUI/config".
You will also need to change your Apache configuration file.
A compiled flash program ("canvas.swf") is provided with the distribution. Should you wish to rebuild it (not usually necessary), the source code is in the "flash_src" subdirectory. The only tool that you need to recompile "canvas.swf" is MTASC (see "http://www.mtasc.org/" for instructions). Nothing else is required. MTASC is free/open source software.
Here is the list of changes from the last beta release.
- A bug in the "__getattr__" method of "CachedObject" (file "Flightdeck-UI/python/FdUI/engine/Cache.py" was corrected.
- Minor whitespace inconsistencies were fixed in the following files.
Flightdeck-UI/python/FdUI/apache/RemoteLogger.py Flightdeck-UI/python/FdUI/logic/_DrawPrimitives.py Flightdeck-UI/python/FdUI/util/Daemon.py
- The stylesheet ("/docroot/fdui-resources/css/fdui.css") was updated to control the body colors, and eliminate validator warnings.
This release is a minor update to 0.3.9. The following list describes the changes.
- A bug that caused the analog clock in the demo panel to read incorrectly after Daylight Savings Time ends has been fixed.
- A special offset class ("FdUI.logic.Offsets.Localtime") has been added, which automatically adjusts to Daylight Savings Time without the need to restart the panel daemon. The "Offsets" module itself is also new.
- The wind speed label in the weather demo panel was too narrow, causing the digital wind display to be cut off in some cases. This has been fixed.