README

============
FGMap README
============



Brief description
=================

FGMap (0.1) started off as a simple web page that shows, on the Google Map
(GM), where all the FlightGear Multiplayer server users are. Shortly after, the
interface was redesigned to be a full web window map, with a proper menu, and
some whistles and bells.  The current version (0.2) now also has navaids lookup
support, which can display information of airports, VORs/NDBs, fixes and
airways.

You can see some more details and screenshots at

http://pigeond.net/flightgear/fgmap.html

This is also a beta version of FGMap using Google Earth as well, see below.



How it works
============

At the moment it is pretty simple. The FlightGear server listens on a port for
TCP connections, known as the "admin" port. When there's an incoming connection
it answers in plain text who's online and their data, including locations and
aircraft being used. FGMap uses AJAX to poll the server via a CGI, which
translate the server admin port output into XML, and then presented onto the
map.

In short:

Browser/JavaScript/AJAX <---> HTTP server/CGI <---> FlightGear server


This will definitely change in the future, to provide more information on the
pilots and the environment.

As for the navaids, they are imported into a database (running PostgreSQL) from
FlightGear's data. The map talks to it using AJAX via a CGI which does queries
on the database and returns the result in XML.



Getting FGMap
=============

You can get the latest development tree using git. The URL at the moment is:

git://pigeond.net/flightgear/fgmap.git

For example at the command line you do

$ git clone git://pigeond.net/flightgear/fgmap.git

which will checkout FGMap into a directory called fgmap/. The next time you
want to update to the latest you can simply do a:

$ git pull

To learn more about git, visit http://git.or.cz/



Web browser requirements
========================

You simply need a web browser that supports Javascript, AJAX and DHTML. FGMap
has been tested under Mozilla/Firefox, Opera, Konqueror, and IE6. It also works
on Safari, though there has been a few known bugs reported.



Hosting FGMap
=============

Requirements
------------

- A Google Map API (GMAPI) key. You have to get it at
  http://www.google.com/apis/maps/ . You also need a Google/GMail account.

- A web server with Perl CGI support. This document assumes you use Apache.
  Optionally you can enable server-side-include (SSI) in Apache. In Apache2 the
  module is mod_include. The .htaccess shipped with FGMap enables SSI for .html
  file, and hence fg_server_map.html. See the description of fgmap.keys below
  too.

- You probably want to install libwww-perl (under Debian) for the navaids
  and metar lookup proxy.

- You need to compile sg_perl perl bindings. See sg_perl/README for details.


Files to tune/edit
------------------

fgmap.keys:

You should put the Google Map API key(s) for your site into this file. See the
comments in the file for more details. This assumes you have enabled
server-side-include (SSI) in your Apache.

After adding your keys(s), you can run 'make', which will update
fg_server_map.html for you.

If you don't want or don't need to use SSI, you can manually edit
fg_server_map.html to have the appropriate GMAPI keys. See
fg_server_map.sample.html for example.


fgmap.servers:

This file contains a list of servers which will appear in the FGMap server
list. See the comments in the file for more details.

The first server in this file will be the default startup server used for the
map page. So you probably want to at least re-order some of the servers listed
in the file provided.


fg_server_map.css:

The CSS for FGMap, referenced from fg_server_map.html at the moment. If you
want any cosmetic changes such as colors, hack it. Most people won't need to
touch this file.


.htaccess:

The Apache configuration file for FGMap. You might not want these in your web
server configuration. Or you might prefer to have these options specified in
the Apache main config. Tune this file as you like.


Example steps
-------------

- Put the entire FGMap tree somewhere which is accessible via your web server.

  For example, if your DocumentRoot is /var/www/
  $ cd /var/www/
  $ git clone git://pigeond.net/flightgear/fgmap.git

  Now the FGMap tree is at /var/www/fgmap/

- Either edit fgmap.keys and fgmap.servers, 'make', which generates
  fg_server_map.html, or manually change fg_server_map.html to use the
  appropriate GMAPI key and servers list. Alternatively, edit
  fg_server_map.html yourself to add GMAPI key and update the server list.

- Test it


Additional notes
----------------

- At the moment, FGMap will always request navaids and metar lookup via
  pigeond.net/mpserver02. This is done to so that not everyone will have the
  trouble of setting up a database and installing metar packages. In this case,
  the map will talk to a proxy CGI instead, because for security reason an AJAX
  request cannot request a foreign host.
  If you really really want to host your own database, contact Pigeon.

- The CGI that talks to FG server, namely fg_server_xml.cgi, written in Perl,
  uses a function in a very tiny SimGear Perl binding. The binary for this
  binding is no longer in the repo. So you have to compile it yourself. Please
  read the README in sg_perl/.


Troubleshooting
---------------

* Map not loading, all I got is a blank page:

  - You have an invalid or malformed line for the Google Map API script code.
    
  - Javascript errors, check the Javascript error console to see if there's
    anything.
    
  - Javascript turned off maybe?


* "The Google Maps API key used on this web site was registered for a different
  web site.":

  - You need to get a GMAPI key for the hostname in the URL you're getting to
    the map.


* Map loaded, but it's stuck at "Loading pilots" for a long time:

  - Make sure the hostname and port are correct in your fgmap.servers
  
  - Make sure the machine hosting FGMap can access the hostname and port for the
    fg server. An easy way is to 'telnet hostname port' on the machine hosting
    FGMap. You should see something like:
  
    # This is pigeond.net
    # FlightGear Multiplayer Server v0.9.10 using protocol version v1.1
    # 1 pilots(s) online
    mpdummy@LOCAL: -2707665.104931 -4273364.498832 3871246.876475 37.610037 -122.358934 4.384606 -2.053077 -1.094549 -1.121333 Aircraft/c172p/Models/c172p.xml
  
  - Goto http://yourfgmaphost/fg_server_xml.cgi?hostname:port
    If you see some XML output, then it should be ok.
    If you see the actual perl script source code, that means your web server
    is somehow not configured to run the script as a CGI. You might want to
    have a look at the server configuration.

  - Make sure you have compiled sg_perl. Read sg_perl/README for more info, or
    contact me if you have trouble building it.


FGMap on Google Earth
=====================

This feature is still in its beta, and might be beta for a little while.

You can try it out by opening fg_server_map.kml in Google Earth.



Everything else
===============

Bug me (Pigeon), which can be reached either on irc.flightgear.org #flightgear,
or via e-mail pigeon at pigeond dot net