source: core/trunk/client/README.txt @ 345

#-------------------------------------------------------------------------------
# This file is part of the FLARM®-Radar Project.
#   
#   Copyright 2012-2014 Simon Moser
#   Copyright 2013-2014 Dominic Spreitz
# 
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#   http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# 
#   Project Website: www.flarmradar.ch
#   Email: info@flarmradar.ch
#-------------------------------------------------------------------------------
    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) is available. Some customising 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 'pi') and install required dependencies
  -> $ sudo apt-get update && apt-get install zip dnsutils libwww-perl minicom
  
2. Connect the Flarm to the Raspberry and start minicom
  -> $ sudo minicom -s

3. Configure communication settings for minicom (tty, baud rate, etc.). Save the 
  configuration file, exit and restart mincom (no parameters) to see the data 
  stream. 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:

$ sudo 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

Installation is possible via software package or manually, the second option
is for advanced users. 

Installation via Software Package

1. Download and unzip the client from http://www.flarmradar.ch/public/dist/pkg
  -> $ wget http://www.flarmradar.ch/public/dist/client/pkg/flarmclient_<version>_all.deb

2. Install the pre-requisites
  -> sudo apt-get install libwww-perl,libdevice-serialport-perl
  
3. Install the package
  -> $ sudo dpkg -i flarmclient_<version>_all.deb
  

Manual Installation

1. Create a new account named 'flarm'
  -> $ sudo useradd -m --system 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'
  -> $ sudo su - flarm
  
4. Download and unzip the client from http://www.flarmradar.ch/public/dist
  -> $> wget http://www.flarmradar.ch/public/dist/client-<version>.zip
  -> $> unzip flarmclient-<version>.zip
  

    CONFIGURATION

The client reads a single configuration file /etc/flarmclient.conf

1. Set the a client key. If you use your own server, then you are free to set
  your own key. To use the public server, request a key at info@flarmradar.ch
  with the following information:
  o) ICAO-Code of your airport/airfield
  o) Short Name (will appear in the menu)
  o) Elevation (in mAMSL)
  o) Antenna level (in mAGL)
  o) Email Address of a responsible person/organization 

2. Configure the URL of the flarm server. If you use the public server, then
  you can leave the default value.

3. Configure the serial device:
  - serial_device = /dev/AMA0 (if you are using the UART port)
  - serial_device = /dev/ttyUSB0 (if you are using a USB-Serial adapter)

    TEST THE INSTALLATION

1. Download a file containing sample data for testing
  -> $ wget https://secure.netzschmiede.ch/trac/flarmradar/browser/core/trunk/client/data/2012_03_25_departure.data
    
2. Start the client as user 'flarm', use the test file from above for testing
  $> sudo -u flarm flarmclient -f 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.

3. 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.

If the client was installed via software package, then you find
a working example in /etc/cron.d/flarmclient. Remove the hash(#)-character 
at the beginning of the first line. The cron-job then periodically checks if 
the client is up and restarts it if necessary. This is useful for a device 
that is installed on the field where you don't have direct access to restart 
the process.

Alternatively, use a runlevel script to start the client at boot time. Many 
examples for this can be found in the internet.