OVERVIEW
    
This document describes the installation procedure for the Flarm-Radar Client
on a Raspberry PI running Raspbian. At the time of writing this document, this
is the only platform where the client has been tested over a long time period 
in a production-like environment.

However, the client can be installed on any operating system where
Perl (http://www.perl.org) can be installed. Some adaptions might be required
in this case.


    REQUIREMENTS
    
Note: Early versions of Raspbian had a nasty bug that caused minicom to freeze
  the entire system after some hours or days of operations. Don't forget to
  update the OS before starting with the installation.

1. Log on the Raspberry as user 'root' and install required software packages
  -> $# apt-get update
  -> $# apt-get install zip dnsutils libwww-perl minicom
  
2. Connect the Flarm Device and configure communication settings for minicom (baud rate, etc.). Save the 
  configuration file. Once the configuration is correct and the Flarm Device is
  turned on, you must be able to see live position data when you start minicom:

$> minicom
....
$GPRMC,123512.00,A,4710.24781,N,00902.46662,E,0.017,237.67,240312,,,A*6E
$GPGGA,123512.00,4710.24781,N,00902.46662,E,1,8,1.40,413.2,M,48.0,M,,*6E
$PFLAA,0,-118,-85,1,1,4B51BC,0,,0,0.1,1*1E
$PFLAA,0,-35,-124,2,1,4B51FF,158,,0,0.1,1*14
$PFLAU,2,1,1,1,0,,0,,*61
$GPRMC,123513.00,A,4710.24782,N,00902.46659,E,0.002,237.67,240312,,,A*60
$GPGGA,123513.00,4710.24782,N,00902.46659,E,1,8,1.40,413.1,M,48.0,M,,*67
....
  
If you reach that: Congratulations, you're nearly done :-)


    INSTALLATION
  
1. Create a new account named 'flarm'
  -> $# useradd -m flarm

Note1: This account does not need a password (because you might loose it and
  it is safer anyway).
  
2. Make sure that the user 'flarm' has permissions to read from the device
  that was previously configured in minicom. If RS232-USB adapter is used, then
  this is /dev/ttyUSB0, or alike. It is usually sufficient to assign the user
  with an additional secondary group.
  
3. Change identity to 'flarm'
  -> $# su - flarm
  
4. Download and unzip the client from http://www.flarmradar.ch/public/dist
  -> $> wget http://www.flarmradar.ch/public/dist/client-SNAPSHOT.zip
  -> $> unzip flarmclient-SNAPSHOT.zip
  

    CONFIGURATION

The client reads a single configuration file ~flarm/.flarmclient/client.conf.

1. Configure the URL of the flarm server. If you use the public server, then
  you can leave the default value for this setting.

2. Set the correct client key. Request a key at info@flarmradar.ch if you use
  the public server. 


    TEST THE INSTALLATION
    
1. Start the client using one of the provided data files
  $> flarmclient -f testdata/2012_03_25_departure.data
  
The client must run without errors and stream the data to the server. Check on
the server while the client is processing the data file.

2. Connect the FLARM device and run the client software
  $> flarmclient
  
... if all goes well, you can see live data on your radar. Congratulations!

    
    INTEGRATION

We must make sure that the client starts automatically after booting the
device. There are two common options to achieve that

  - a cron job
The job periodically checks if the client is up and restarts it if necessary.
Use this option for a device that is installed on the field and where you don't
have direct access to restart the process. 

To install the cron-job, just copy the file examples/flarmradar.cron to
/etc/cron.d on you Raspberry and restart the cron service
  $# /etc/init.d/cron restart 


  - a runlevel script
The runlevel script starts the client automatically during at boot time. An
example is shipped in 'examples/flarmradar.rc'.