==================================
 OGN DVB-T receiver version 0.2.7
==================================


 Install guide
===============

sudo apt-get install build-essential ntp ntpdate libjpeg-dev libconfig-dev fftw3-dev procserv lynx telnet rtl-sdr make cmake aptitude

get the binary package like: rtlsdr-ogn-bin-RPI-GPU-0.2.7.tgz

# assuming the .tgz file is in the top user directory like /home/pi for Raspberry PI
tar xvzf rtlsdr-ogn-bin-RPI-GPU-0.2.7.tgz # unpack the tar archive, create the rtlsdr-ogn-0.2.7 and the symbolic link
cd rtlsdr-ogn
source setup-rpi.sh                # set the binaries to run on the GPS: give the ogn-rf root rights
source getEGM.sh                   # get the WW15MGH.DAC file for conversion between the Height-above-Elipsoid to Height-above-Geoid thus above MSL
source install-service.sh          # install the service which runs in the background and restarts the executable should they crash for any reason
sudo nano /etc/rtlsdr-ogn.conf     # edit the directory where the binaries are and the config file name, exit with Ctrl-X
cp Template.conf <your name>.conf
nano <your name>.conf              # put the name and position of your receiver, exit with Ctrl-X
sudo service rtlsdr-ogn start      # start the service thus run the two executables: ogn-rf and ogn-decode

 Overall software configuration
================================

o Runable binaries are in the /home/pi/rtlsdr-ogn where "pi" can be any other user depending on the speific system
o There are two binaries to run: ogn-rf and ogn-decode, then exchange data through the named pipe of TCP socket
o Service "rtlsdr-ogn" is arranged to run the two binaries in the background, it can be controlled with: sudo service rtlsdr-ogn start/stop/restart
o Service configuration file /etc/rtlsdr-ogn.conf tells where the binaries are and where the specific receiver configuration file is
o Stdout/stdin of ogn-rf and ogn-decode can be seen with telnet localhost 50000 and 50001 (ports are defined in /etc/rtlsdr-ogn.conf)
o Status of ogn-rf and ogn-decode can be seen with lynx or other HTTP browser on port 8080 and 8081 (ports are defined in specific OGN receiver config. file)

 Quick trouble shooting
========================

o Check that both binaries are running (HTTP ports are active) and some CPU usage by them is visible with htop or top 
o Check stdout with telnet to 50000/1 for error messages like no RTLSDR stick attached
o If binaries not running make sure in the /etc/rtlsdr-ogn.conf that user name, path to binaries and receiver configuration are correct and files exist
o Check the noise level measured by ogn-decode on HTTP port 8081: noise of few dB is fine, more than 10dB means troubles unless you use an LNA
o Measure the frequency error of the RTLSDR stick with the gsm_scan or by other means, sticks with TCXO don't need this
o Dialog with the APRS server can be seen on port 50001, the data exchanged is prefixed with "APRS <-" (to server) or "APRS ->" (from server)

 Hardware requirements
=======================

o Computer running Linux able to process the data: 4 core SBC are fine, single core SBC may not be enough
o RTLSDR USB stick for as SDR radio receiver: R820T(2) tunesr work best on 868MHz
o Good antenna for 868MHz, possibly a filter or a filtered LNA

 System Requirements
=====================

o Connection to internet so data can be send to the APRS servers (TCP conenction)
o NTP service running or system time correctly set to better than 100-200ms

 Configuration file parameters
===============================

The parameters are read from a file with the libconfig library, thus the syntax is defined there.

Parameter        Type    Units   Description

Essential parameters:

Position.Latitude      float  [deg] Position
Position.Longitude     float  [deg]
Position.Altitude       int   [  m]
APRS.Call              string [   ]

To adjust the RTLSDR:

RF.FreqCorr        int   [ppm]   Frequency correction of the RTLSDR crystal, for TCXO stick it is less than 1-2ppm, for black and blue R820T it is 40-80ppm
RF.OGN.Gain       float  [ dB]   Tuner gain for OGN RF reception
RF.GSM.Gain       float  [ dB]   Tuner gain for GSM RF reception
RF.GSM.CenterFreq float  [MHz]   
RF.Bandwidth      float  [MHz]   Receiver IF bandwidth
RF.OGN.GainMode    int  [mode]

To catch PilotAware signals on 869.525MHz set RF.SampleRate=2.0; RF.OGN.CenterFreq=868.8;

RF.SampleRate     float  [MHz]   Sampling = sampled bandwidth 1.0 or 2.0MHz, you need 2MHz to receive PilotAware on 869.525MHz
RF.OGN.CenterFreq float  [MHz]   Center frequency for OGN RF reception, to include PilotAware reception set to 868.8MHz and RF.SampleRate=2.0;

To extern tolerance to frequency errors set Demodulator.ScanMargin=50; or more

Demodulator.ScanMargin float  [kHz] Tolerance for signals being off frequency

To supply LNA set RF.BiasTee=1; but don't set it if there is no LNA in front of the RTLSDR !

RF.BiasTee         int   [0,1]   Bias-T for some RTLSDR sticks to supply the LNA like Uputronics, do not activate, unless really needed, can samage the stick

Other parameters take some default or automatic values and normally need not to be changed.

RF.FreqPlan        int   [0..4]  1=Europe/Africa, 2=USA/Canada, 3=South America/Australia, 4=New Zeeland (but normally automatic from the Position)
RF.OGN.StartTime  float  [sec]
RF.OfsTune         int   [0.1]
RF.OGN.SensTime   float  [sec]
RF.OGN.SaveRawData int   [sec]   Save raw data for given number of seconds: large files !
RF.GSM.Scan        int   [0,1]
Demodulator.DetectSNR  float  [ dB]
Position.GeoidSepar     int   [  m]
APRS.Icon              string [   ] I&
APRS.Server            string [   ] aprs.glidernet.org
APRS.HighResolution     int   [0,1] 1
APRS.MaxDistError       int   [  m]
APRS.MaxBitError        int   [  m]
APRS.ReportDelay        int   [sec]
APRS.Beacon.Interval    int   [sec]
APRS.Beacon.Comment    string [   ]
APRS.FilterRange        int   [  m]

 Data processing
=================

The processing is split into two major parts:
1. ogn-rf - RF signal acquisition, GSM cablibration, FFT
2. ogn-decode - packet demodulator and decoder

ogn-rf user open source RTLSDR and FFT code and is now open source,
while ogn-decode is closed source.

The two executable run in parallel and ogn-rf passes
Fourier spectra to ogn-decode through the named Unix FIFO: ogn-rf.fifo
or through the local socket 50010 (default, starting from 0.2.7)

If you want to use the named fifo you need to create this FIFO with this command:

mkfifo ogn-rf.fifo

in the same directory as the executables, or use the setup-rpi.sh script


 To run on Raspberry PI with executable using GPU for faster FFT
=================================================================

For the executables to be able to use GPU the following needs to be done:

sudo chown root ogn-rf
sudo chmod a+s  ogn-rf
sudo chown root gsm_scan
sudo chmod a+s  gsm_scan
sudo mknod gpu_dev c 100 0

the script setup-rpi.sh does the above


 Frequency calibration
=======================

If you have a RTLSDR dongle with TCXO, like the silver one, you may skip this part

DVB-T USB dongle use cheap crystals and these are not very accurate.
They can be off by as much to 100ppm, which at 868MHz is 86kHz away
- far too much for correct reception of FSK modulation with +/-50kHz deviation

Fortunately, this can be corrected, we only need to know by how much the crystal is off.
GSM signals are a good reference and not far away in frequency thus they can be used
for precise frequency calibration.

To measure the frequency offset of your DVB-T stick use the gsm_scan tool, like this:

./gsm_scan --ppm 50 --gain 20

-ppm is your initial guess for the offset and --gain is the RF front end gain.

As you can see using gsm_scan is not fully automatic. You may need to make few guesses
and the frequency offset and the optimal gain. Too little gain and you don't get any signals.
Too much gain and the signals get so distorted you get plenty of false readings.

The most popular big black DVB-T sticks with R820T tuner have crystals with offest between 40and 80ppm.
The tiny black sticks with R820T are around zero.

With a good antenna in a GSM-dense area you may need to go down with the gain to 15-20dB
while far from civilation you may need to go to maximum 50-60dB.

After few tries you should be able to catch several broadcast channels and get a consistent reading.
Note that as the DVB-T dongle acquires data, it warms up and frequency offset starts drifting by few ppm
this is normal. However the small DVB-T sticks can get too hot and then they suddenly jump in frequency.
If you identify such stick, use it with good cooling - thus don't close it in a small box without ventilation.

Here is sample output of: ./gsm_scan --ppm 40 --gain 40

935.400MHz:  +14.7dB: -25.84 -25.81 -25.71 [ppm]
936.000MHz:  +14.4dB: -25.68 -25.47 -25.44 -25.63 -25.62 [ppm]
936.400MHz:   +9.7dB: -25.51 -25.47 -25.38 -25.34 -25.28 -25.22 [ppm]
938.000MHz:   +6.4dB: -25.18 -25.10 -25.22 -25.17 -25.09 [ppm]
939.000MHz:   +4.5dB: -24.90 -25.12 -24.38 -25.14 -24.84 [ppm]
948.000MHz:  +23.1dB: -25.69 -25.77 -25.78 -25.71 -25.72 [ppm]
949.600MHz:  +14.9dB: -25.32 -25.21 [ppm]
950.000MHz:  +24.8dB: -25.46 -25.65 [ppm]
952.000MHz:  +18.1dB: -25.28 -25.36 -25.29 -25.17 -25.34 [ppm]
952.400MHz:  +24.0dB: -25.90 -25.90 -25.77 -25.87 -25.92 [ppm]
953.200MHz:  +21.3dB: -24.83 -24.87 [ppm]
956.400MHz:  +11.6dB: -25.73 -25.28 -25.46 -24.49 -24.89 [ppm]
956.600MHz:  +30.9dB: -24.70 -25.10 -24.83 -25.19 [ppm]
957.000MHz:   +9.4dB: -25.20 -25.20 -25.19 -25.35 [ppm]
957.200MHz:  +23.5dB: -24.56 -14.85 [ppm]
957.600MHz:  +28.7dB: -25.12 -25.14 -25.12 -25.06 -25.14 [ppm]
958.200MHz:   +6.5dB: -24.40 -24.61 -24.21 -23.86 -24.30 -24.52 [ppm]
959.000MHz:  +10.1dB: -25.00 -25.02 -25.22 -24.76 -25.31 -25.08 [ppm]
959.200MHz:  +28.9dB: -24.72 -24.71 -24.66 -24.69 -24.71 -24.70 [ppm]
959.800MHz:  +12.3dB: -23.80 -23.65 -24.06 -24.08 -23.88 -23.49 -23.95 [ppm]
Receiver Xtal correction = 40-25.135 = +14.865 (0.188) ppm [46]

which means we guessed about 25 ppm to high,
and so we retry: ./gsm_scan --ppm 15 --gain 40

935.400MHz:  +16.0dB:  +0.47  +0.31  +0.24  +0.37  +0.41 [ppm]
936.000MHz:  +15.3dB:  +0.40  +0.07  +0.63  +0.44  +0.51 [ppm]
936.400MHz:   +7.9dB:  -0.13  +0.19  -0.08  -0.18  -0.25 [ppm]
938.000MHz:   +6.2dB:  -0.08  -0.06  -0.06  -0.03  +0.01 [ppm]
948.000MHz:  +23.3dB:  +0.33  +0.31  +0.33  +0.33  +0.32 [ppm]
949.600MHz:  +15.0dB:  -0.21  -0.16  -0.15  -0.21  -0.17 [ppm]
950.000MHz:  +25.1dB:  -0.23  -0.30  -0.08  -0.15  -0.28 [ppm]
950.800MHz:   +6.8dB:  +0.16  +0.16  +0.10 [ppm]
952.000MHz:  +16.3dB:  +0.28  +0.28  +0.27  +0.27  +0.26 [ppm]
952.400MHz:  +24.7dB:  -0.34  -0.31  -0.33  -0.32  -0.29  -0.34 [ppm]
952.800MHz:  +12.1dB:  -0.21  -0.26  -0.26  -0.28  -0.33 [ppm]
953.200MHz:  +21.7dB:  -0.25  -0.25  -0.25  -0.24  -0.26 [ppm]
954.000MHz:  +15.3dB:  -0.26  -0.19  -0.23  -0.21  -0.24 [ppm]
954.400MHz:   +9.7dB:  +0.10  +0.13  +0.03  +0.07 [ppm]
955.600MHz:   +4.2dB:  +0.07  +0.59 [ppm]
956.600MHz:  +31.2dB:  -0.30  -0.38  -0.34  -0.30  -0.32 [ppm]
957.000MHz:   +8.5dB:  -0.35  -0.53  -0.27  -0.59  -0.19  -0.31 [ppm]
957.200MHz:  +23.2dB:  -0.31  -0.31  -0.29  -0.28  -0.30 [ppm]
957.600MHz:  +29.6dB:  -0.29  -0.25  -0.24  -0.28  -0.27 [ppm]
958.800MHz:  +13.3dB:  +0.11  +0.04  +0.15  +0.08  +0.14  +0.12 [ppm]
959.200MHz:  +28.1dB:  +0.14  +0.16  +0.18  +0.14  +0.15 [ppm]
959.800MHz:  +15.6dB:  +0.13  +0.19  +0.17  +0.18  +0.14 [ppm]
Receiver Xtal correction = 15-0.064 = +14.936 (0.199) ppm [81]

Which means that our guess 15ppm is just correct.

Here we should choose a frequency with several signals within 1MHz,
for example 952.800MHz is a good choice because there are good calibration signals
just below and just above.

These three numbers we need to put int he config file:
1. frequency offset = +15ppm
2. GSM frequency for fine calibration: 952.800MHz
3. Optimum RF gain to find the signals but not oversdrive the receiver: 40dB

Whith correct numbers the ogn-rf should output such messages:

GSM freq. calib. =  -1.298 +/- 0.067 ppm, 8 points
GSM freq. calib. =  -1.231 +/- 0.066 ppm, 6 points

This means the GSM calibration is succesfully receiving the signals and calibrating
and we are just on the frequency (jus 1.3ppm away, which is unimportant)


 Config file
=============

about ready to make the configuration file, here is a template:

# ------------------------------------------------------------------------------------------------------------------

RF:
{
  FreqCorr = +15;          # [ppm]      "big" R820T sticks have 40-80ppm correction factors, measure it with gsm_scan
  SampleRate = 2.0;        # [MHz]      

  GSM:                     # for frequency calibration based on GSM signals
  { CenterFreq  = 952.8;   # [MHz] find the best GSM frequency with gsm_scan
    Gain        =  40.0;   # [dB]  RF input gain, you normally don't need the full gain here
  } ;

  OGN:
  { CenterFreq = 868.8;
    Gain       =  50.0;
  }

} ;

Position:
{ Latitude   =   +48.0000; # [deg] Antenna coordinates
  Longitude  =    +9.0000; # [deg]
  Altitude   =        100; # [m]   Altitude above sea leavel
} ;

APRS:
{ Call = "APRSname";           # APRS callsign (max. 9 characters)
} ;

# ------------------------------------------------------------------------------------------------------------------

The elements are:
1. Station name: up to 9 characters -> replace "SampleAPRSnameToChange" with your station name
2. Station coordinates
3. Frequency offset and GSM parameters aspreviously discussed

Station coordinates does not have to be precise, in case you prefere not to disclose your exact geographical position.


 Running the receiver as a service
===================================

We use shellbox: a tool to run any number of processes in the background with the capability to restart should they crash.
You need to install two file: rtlsdr-ogn and rtlsdr-ogn.conf like this:

sudo apt-get -y install procserv telnet nano
sudo cp -v rtlsdr-ogn /etc/init.d/rtlsdr-ogn
sudo cp -v rtlsdr-ogn.conf /etc/rtlsdr-ogn
sudo update-rc.d rtlsdr-ogn defaults

then you should edit the rtlsdr-ogn.conf like this:

sudo nano -w /etc/rtlsdr-ogn.conf

which should look like this:

50000 pi /home/pi/rtlsdr-ogn    ./ogn-rf     SampleAPRSnameToChange.conf
50001 pi /home/pi/rtlsdr-ogn    ./ogn-decode SampleAPRSnameToChange.conf

this is example from Raspberry PI wheere the receiver runs under user "pi" and files are in the directory "rtlsdr-ogn".
Replace SampleAPRSnameToChange.conf with your configuration file.

To start the service you type:

sudo service rtlsdr-ogn start

and this will start the executables listed in /etc/rtlsdr-ogn.conf
To stop:

sudo service rtlsdr-ogn stop


 Monitoring
============

To check if things work alright you can watch the output of the executables by telnet'ing to ports 50000 and 50001:

telnet localhost 50000

or

telnet localhost 50001

On the ogn-rf output you should see the GSM caibration messages and on the ogn-decode output there should be
APRS keep-alive messages and decoded position packets from aircrafts.


 Quesions and comments
=======================

please send to contact@glidernet.org
