Release version 0.2.4

AUTHORS

@@ -4,3 +4,4 @@ Copyright (c) 2015 The OGN Project
 The following people and organizations have contributed code to OGN:
 
 Pawel Jalocha <[email protected]>
+Andrew Holme

Changelog

@@ -0,0 +1,23 @@
+0.2.4 (October 2015)
+- Introduce UseAsWhitelist parameter for strict opt-in using data from OGN DDB.
+- Provide hardware and software version of received device.
+- Add more precision to Latitude and Longitude in APRS messages.
+- Add error correction of radio messages.
+- Allow integer as config gain value.
+- Allow float as config GeoidSepar value.
+- Fix bug about incorrect altitude of 65500m.
+- Fix bug about turn rate.
+- Other minor fixes and enhancement.
+
+0.2.3 (June 2015)
+- Bug fixed in default setup which was reducing sensitivity.
+- Introduce adaptive algorithm to send positions to APRS.
+- Send arch info in version to APRS server.
+- Nothing changed on ogn-rf side.
+- Code cleanup.
+
+0.2.2 (April 2015)
+- Source code of public part of receiver is released
+
+0.2.0 (March 2015)
+- First version compatible with Flarm v6 recent changes in radio protocol

INSTALL

@@ -0,0 +1,234 @@
+==================================
+ OGN DVB-T receiver version 0.2.2
+==================================
+
+
+ Install guide
+===============
+
+
+ Important change: to comply with open-source licenses
+=======================================================
+
+we split the executable into two 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
+
+You need to create this FIFO with this command:
+
+mkfifo ogn-rf.fifo
+
+in the same directory as the executables.
+
+
+ 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
+
+
+ Frequency calibration
+=======================
+
+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
+
+  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 (beware that GSM signals are very strong !)
+  } ;
+} ;
+
+Position:
+{ Latitude   =   +48.0000; # [deg] Antenna coordinates
+  Longitude  =    +9.0000; # [deg]
+  Altitude   =        100; # [m]   Altitude above sea leavel
+  GeoidSepar =         48; # [m]   Geoid separation: FLARM transmits GPS altitude, APRS uses means Sea level altitude
+} ;
+
+APRS:
+{ Call = "SampleAPRSnameToChange";           # 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 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 [email protected]

Makefile

@@ -1,6 +1,6 @@
-VERSION = 0.2.2
+VERSION = 0.2.4
 
-USE_RPI_GPU_FFT = 1
+# USE_RPI_GPU_FFT = 1
 
 FLAGS = -Wall -O3 -ffast-math -DVERSION=$(VERSION)
 LIBS  = -lpthread -lm -ljpeg -lconfig -lrt

alloc.h

@@ -15,7 +15,7 @@
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+    along with this software.  If not, see <http://www.gnu.org/licenses/>.
 */
 #ifndef __ALLOC_H__
 #define __ALLOC_H__

asciitime.h

@@ -15,7 +15,7 @@
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+    along with this software.  If not, see <http://www.gnu.org/licenses/>.
 */
 #ifndef __ASCIITIME_H__
 #define __ASCIITIME_H__

buffer.h

@@ -15,8 +15,9 @@
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+    along with this software.  If not, see <http://www.gnu.org/licenses/>.
 */
+
 #ifndef __BUFFER_H_
 #define __BUFFER_H_
 

fft.h

@@ -15,7 +15,7 @@
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+    along with this software.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 #ifndef __FFT_H__

image.h

@@ -15,8 +15,9 @@
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
-    along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+    along with this software.  If not, see <http://www.gnu.org/licenses/>.
 */
+
 #ifndef __IMAGE_H__
 #define __IMAGE_H__
 
@@ -81,6 +82,13 @@ template <class Type=float>
        Data=ExtImage; Width=ExtWidth; Height=ExtHeight;
        return Size=Width*Height; }
 
+// -----------------------------------------------------------------------------
+
+   bool  isPixel(int X, int Y) const         { return (X>=0) && (X<Width) && (Y>=0) && (Y<=Height); }
+   void setPixel(int X, int Y, Type Value)   { Data[Y*Width+X]=Value; }
+   Type getPixel(int X, int Y) const         { return Data[Y*Width+X]; }
+   Type incPixel(int X, int Y, Type Value=1) { return Data[Y*Width+X]+=Value; }
+
 // -----------------------------------------------------------------------------
 
    template <class ExtType>
@@ -210,7 +218,7 @@ template <class Type=float>
        fclose(File); return Size; }
 
    int WriteJPG_8bpp(FILE *File, int Quality=80, Type LogRef=0, Type Scale=1, Type Bias=0) const
-     { 
+     {
        struct jpeg_compress_struct JpegCompress;
        struct jpeg_error_mgr       JpegErrorManager;
               jmp_buf              JpegErrorJmp;
@@ -232,16 +240,16 @@ template <class Type=float>
          return -1; }
 
        uint8_t Line[Width];
-       for(int Row=0; Row<Height; Row++)
+       for(int Row=0; Row<Height; Row++)     // loop over image lines
        { Type *Img = Data+(Row*Width);
-         for(int Col=0; Col<Width; Col++)
+         for(int Col=0; Col<Width; Col++)    // loop over pixels in a line
          { Type Pixel=(*Img++);
-           if(LogRef)
+           if(LogRef)                        // logarythimc pixel rescale
            { if(Pixel) { Pixel=logf((float)Pixel/LogRef); Pixel = Pixel*Scale + Bias; }
-             else Pixel=0; }
-           else
+             else Pixel=0; }                 //
+           else                              // linear pixel rescale
            { Pixel = Pixel*Scale + Bias; }
-           if(Pixel<0x00) Pixel=0x00;
+           if(Pixel<0x00) Pixel=0x00;        // limit to 8 bits
            else if(Pixel>0xFF) Pixel=0xFF;
            Line[Col]=(uint8_t)Pixel; }
          uint8_t *RowPtr=Line;