SirfGPS= Tweaker documentation

A= pplication for displaying output from NMEA or SIRFBINARY based GPS device. It has autodetection of data format (so it works both in NME= A or SIRF with on the fly detection). It can display statistics and data panel f= or cockpit use. Cockpit mode includes history graphs for speed and altitude. <= span class=3DSpellE>Programm is able to tweak GPS receivers by changing t= he operation mode or resetting the device. It can save output from GPS to a du= mp file and save comprehensive debug information. .

Downloads

A= pplication: SirfGPSTweaker.zip

P= DF Documentation: SirfGPSTweaker.pdf

H= TML Documentation: SirfGPSTweaker.mht

Concepts

I= wanted to create the application which can be used for two needs: to debug, fine tune= GPS receiver as well as examine operation characteristics of GPS receivers in various conditions, and as a dashboard computer for a journey with logging functionality & speed / altitude graphs. I was trying to use some avail= able software like VisualGPS CE or SirfDemo. None of them was good for me – so I decided to write my own.

<= o:p>

The basic assumptions are:

· Application decodes both NMEA and SIRF BINARY code. It can find which protocol to use on the fly, you do not have to set any modes in adv= ance. It is easy to setup the device. Any device capable of NMEA output can be used = with the program. It does not need to be SIRF based however you can do more fine tuning with SIRF.

· It can give a lot of debugging information on user level: good screen with BOTH signal level and satellites azimuth/elevation on one screen, screen with on= line dump of GPS output and lots of statistics (bytes read, used, discarded, sentences processed successfully e= tc)

· It has a good on-board computer dashboard for a car, showing all trip informat= ion on one screen: current speed (number&graph), heading, time of travel, distance traveled etc. as well as nice graphs with speed /altitude history.

· Ability to record all data coming from GPS receiver to a file or use file as input<= o:p>

· Records detailed debug log showing all connection details, incoming bytes, informat= ion on decoding them as sentences or discarding as invalid etc. – very detailed information.

· I do not intend this to be a mapping application. I am not planning to add mapping functionality

· Application remembers it’s connection settings and reconnects to a last recently used GPS data source (com port or file) upon startup.

<= o:p>

Requirements

· Application requires .NET framework 2.0 or higher. Pocket PC version can be downloaded = from http://www.microsoft.com= /downloads/details.aspx?displaylang=3Den&FamilyID=3D0C1B0A88-59E2-4EBA-= A70E-4CD851C5FCC4

· The same executable works on PC/Windows and Pocket PC etc.

· No need to install the application, just copy to any folder and run it. <= /o:p>

<= o:p>

Screenshots with explaination of displayed data

	Speed =3D current speed obtained from GPS. Be= low is the graph showing current speed. It is scaled from 0 to 200km/h. On the right – compass. North relative to current travel direction is shown by the blue pointer. <= /o:p> Avg =3D average speed from be= ginning of journey or history cleared (in km/h). I can be reset by CLR button= . Time when GPS is not transmitting (File->Disconnect) or pocket PC is turned= off for >30 seconds is not calculated into average. However if device is s= till in one place (speed=3D0km/h) and GPS is transmitting is taken into account lowering the average. Dist =3D distance traveled while online in = kilometres. Distance is calculated from speed multi= plied by time, not from latitude / longitude readings. Alt =3D current altitude above sea level in meters. Travel =3D travel time in minutes / seconds 1249p =3D number of history points used for = graphs on the left side. Next point is added when GPS sends new update to application (usually every second) Speed graph =3D shows graph of speed from beginnin= g of journey till now. If all history buffer is used (default is 10 hours of recording) the graph moves to the left discarding oldest data (so the gra= ph will show speed during last 10 hours). Discarding oldest graph data does = not affect average speed, min and max speed and other statistical information calculated.
	Navigation data consists of: Latitude, Longitude, Speed, Heading (direction of traveling) and current Altitude above sea level. Geoid separation is the correction applied to Altitude to make altitude real. If number is nonzero, than Altitude is probably correct above mean sea level, if zero = it means Altitude is not corrected and can be invalid because is used from a simplified WGS-81 model. Additionally it shows: HDOP =3D horizontal dilution of precision as reported from GPS. The same with VDOP (vertical) and PDOP (3D fix dilution of precision. DOP parameters are taking into account only current satellites configuration (positions, number of sats<= /span> visible) and not real time environment.&= nbsp; Time & Date =3D date and time of last succesfull fix. Not= current date and time. Data source is the COM port and baud rate or filename used as GPS input. = Fix3D/Fix2D – type of last fix. Usuall= y if >3 satellites can be used the fix is 3D it means altitude is also calculated. DGPS =3D shows Differential GPS status. No = DGPS =3D not in use, DGPS fix time and satelliute ID is shown when in use. DGPS is additional source of information on current GPS error obtained from extra satellite (WAAS/EGNOS) or terrestal station <= o:p> Protocol=3D the protocol used to successfully d= ecode last sentence. Can be SIRF binary or NMEA Buffer used =3D number of bytes left in input buffe= r after last fix. Nonzero number means that part of next sentence was read which = will be probably completed and read in next update. It is normal. Large number= s however (above 100) mean there is some junk in input and both= SIRF nor NMEA decoders can’t find anything for themselves. <= /o:p> Bytes read,used,di= scarded =3D how many bytes were r= ead from GPS receiver, how many were used in successfully decoded SIRF or NMEA sentences an how many had to be discarded because they couldn’t be recognized as valid sentences. History in use – how many updates are recorded = in history buffer for speed & altitude & position graphs, and total = size of that buffer. This does not affect logging to file. History buffer is used only for graphs. If full buffer is used, the oldest updates are discarded.
	On this screen bytes received from GPS which are forming valid sentences are show= n. For NMEA – it is text output, for SIRF it is HEX dump. This is preliminary and rough debug information. Full information can be obtained from Debug Log file if recorded. This can be used to see if GPS is transmitting at all and if the transmission is anyhow useful for decoding.
	As input you can use COM port (serial) or previously recorded dump file with GPS receiver output. File can be recorded with this application or can be from any other application like VisualGPS or SIRFDemo. This screen is used to specify the source= and source parameters.
About dialog	File menu
GPS commands menu	Log files menu

<= o:p>

Notes on operation

W= hen launched the application first searches current user’s ‘My Documents’ folder for a file ‘SirfGPSTweaker.ini’ contain= ing the previously used configuration (previously open GPS device and previously open panel etc). If found – loads the data. If not – uses defau= lt values for startup.

Known bugs

· SIRF decoder is not implemented yet.

· From NMEA only the following sentences are fully implemented: GPRMC, GPGGA, GPGS= A, GPGSV, GPGLL

· GPRMB, PGRME, PGRMZ, GPBOD, GPRTE are partially implemented

· Application hangs when the device is switched on during serial transmission and the dev= ice is switched on some time later.

Technical details – source code analysis

Programm consists of a set of forms and some libraries:

<= o:p>

Form1.cs – main screen with all tabs (outpu= t, panel, GPS data etc) & main menu

FormAbout.cs – about dialog

FormConnectionSettings.cs – dialog for choosing= GPS data source

<= o:p>

L= ibraries:

GPSData.cs= – structure containin= g data obtained from last fix of GPS and tables containing historical data for Latitude, Longitude, Altitude + calculated statistics. Also contains few methods for manipulating historical data (HistoryClear= , HistoryUpdate etc).

<= o:p>

GPSDecoder.cs – class containing ma= in decoding loop ‘GetNextUpdate= IfPossible()’ called periodically from application. This function reads all available data from GPS receiver to the buffer, and checks the buffer for

<= o:p>

GPSDataSource.cs<= /span> – class for reading G= PS data from serial port or file, opening and using gps= dump log file, and debug log file.

<= o:p>

NMEA0183.cs – class containing static function= s for decoding NMEA sentences. Main function of this class is UpdateGPSData(nmea_sentence, gps_data_to_updat= e) which takes nmea sentence string as input, and updates object of a class GPSData with decoded = inforation.

<= o:p>

SIRFBINARY.cs – identical class wit= h static functions for decoding SIRF. It has similar UpdateGPSData(*) fun= ction

Simplified listings

Listing 1: Form1.cs=

/********= ********************************************************<= /p>

* GPS Application and Libraries

* www.gosiewski.pl

* marcin@gosiewski.pl

* Do not remove the copyright note!=

***********************************= *****************************/

namespace= SirfGPSTweaker<= /span>

{

public partial class<= /span> Form1 : Form

{

GPSDataSource dataSource;

GPSDecoder gpsDecoder =3D new GPSDecoder();

private void timer1_Tick(object sender, EventArgs e)

{

= gpsDecoder.GetNextUpdateIfPossible(dataSource))

= switch (this.tabControl1.SelectedIndex)

= {

= case 0: // Panel OUTPUT

= &nb= sp; { //tu rysujemy zawartość ekranu

&= nbsp; &nbs= p; //na bazie obiektu gpsDecoder.currentGPSData

= case 2: // Panel DATA

= &nb= sp; {

= case 3: // Panel PANEL

= &nb= sp; {

= case 4:// Panel TRA= CE

= &nb= sp; break;

= default:

= &nb= sp; break;

= }

}

} // namespace

<= o:p>

Listing 2: GPSDecoder.cs<= /span>

GPS Decod= ing functionality, Class where the GPS decoding functionality lies. It maintains buffer to read data from, holds the data read from GPSDataSource and parses= it through appriopriate NMEA or SIRFBINARY decoder Most important method is GetNextUpdateIfPossible which reads data and parses it.

public class GPSDecoder

{

// The data from GPS receiver is stored here before dec= oding.

public int[] buffer =3D new int[MAXBUFFER];

// Holds the data currently decoded by the class. =

public GPSData CurrentGPSData =3D new GPSData()= ;

public void BufferDiscardFirstItems(int count)

{ … }=

// <summary> try to find valid NMEA sentence in buffer, decode it= and discard from buffer.

public bool DecodeNMEA(GPSDataSource datasource)

{

// parse buffer to find valid NMEA= sentence.

// Than process it using static me= thods from NMEA0183.cs

//and discard from buffer everything between beginnig of the buffer

// and the sentence, including the processed sentence.

= if (NME= A0183.ChecksumValid(NMEASentence))

= {

= //update statistics

= NMEA0183.UpdateGPSData(NMEASentenc= e, CurrentGPSData);

= BufferDiscardFirstItems(j + 2);

= }

}

public bool DecodeSIRF(GPSDataSource datasource)

{

// Same= as DecodeNMEA but for SIRF =

if (SIRFBINARY.ChecksumValid(SIRFSentence))

{

= // update statistics

= // update CurrentGPSData

SIRFBINARY.UpdateGPSData(SIRFSentence, CurrentGPSData);

= BufferDiscardFirstItems(i + 8 + payloadlength);

= }

}

// Get next bytes from GPS receiver, process it via NME= A or

// SIRFBINARY & di= scard when done.

public bool GetNextUpdateIfPossible(GPSDataSource datasource)

{

// if we encounter full buffer at start – =

// let's discart at least part of it.

if (buffertail =3D=3D MAXBUFFER - 1)=

{

= BufferDiscardFirstItems(bytestodiscard);

}

// now read till input empty or buffer full

while ((datasource.BytesToRead() > 0) &&= amp; (buffer not full))

{

= buffer[buffertail++] =3D datasource.ReadByte();

}

// now try to process all sentences in buffer

while (DecodeSIRF(datasource)) { done =3D true; } // first SI= RF

= &nb= sp; = because it is more strict in format

while (DecodeNMEA(datasource)) { done =3D true; } // now NMEA= , more

= &nb= sp; = relaxed

}

<= o:p>

Listing 3 GPSData.cs

This is a structure holding all current and historical data obtained from GPS. Data stored here falls into categories:

1) data f= rom last fix (latitude, longitude, speed etc., visible satelites etc.

2) data on the fix itself (protocol used NMEA or SIRF, etc)

3) histor= ical data and statistics

public class GPSData

{

// ******************************

// current data obtained from GPS.

// ******************************

&nbs= p;

/// Satellites are numbered from 1, not from 0.

public const int MAXSATELITES =3D 40;

/// From which protocol the data was obtained.

public enum Protocols= {

unknown,

Sirf,

NMEA

};

public Protocols Protocol =3D Protocols.unknown;

public bool DataValid =3D false;

public class Satelite= Info

{

public bool D= ataValid =3D false;

/// true if satelit= e is in view

public bool I= nView =3D false;

/// true if satelit= e was used for last fix

public bool I= nUse =3D false;

/// ID of this sate= lite

public int SateliteNumber =3D 0;

public int Az= imuth =3D 0;

public int El= evation =3D 0;

/// Signal To Noise= ratio for this satelite.

public int SN= R =3D 0;

}

// our approach is to keep data on all satellites, not only visible=

public SateliteInfo[] Satelites =3D new SateliteInfo[MAXSATELITES + 1];

public int SatelitesInView =3D 0;

// fix data

public enum FixModes<= /span> {

Fix2D,

Fix3D,

FixInvalid

};

public FixModes FixMode =3D FixModes.FixInvalid;

/// Operation modes of GPS receiver.

/// As defined in NMEA

public enum Operation= Modes {

Unknown,

Automatic,

///ManualForced2D3D= =3D force receiver to use 2D mode=

ManualForced2D3D

};

public OperationModes OperationMode =3D OperationModes.Unknown;

/// Number= of satelites used for last fix. obtained from GPS receiver. =

public int SatelitesInUse =3D 0;

/// Diluti= on of precision

public double PDOP =3D 0;

public double HDOP =3D 0; // HDOP in meters (dilution of precision)

public double VDOP =3D 0; // VDOP in meters (dilution of precision)

&nbs= p;

// navigation data

/// String= format of Date of last fix. Directly as received from GPS=

public string DateDMY =3D "";

/// String= format of UTC time of last fix. Not corrected by timezone.

public string TimeUTC =3D "";

/// Time o= f last fix (we name it current here).

public DateTime TimeCurrentFix =3D new DateTime(= );

/// Time of PREVIOUS fix. Used to calculate timespan between fixes.

public DateTime TimeLastFix =3D new DateTime();

/// Naviga= tion status obtained from GPS. 'V' - means receiver warinig,

p= ublic string NavigationStatus =3D "";

/// Values= received from GPS

public double Latitude =3D 0;<= /p>

public char LatitudeNS =3D 'N';

public double Longitude =3D 0;=

public char LongitudeEW =3D 'E';

public double SpeedOverGround =3D 0;<= /span>

public double Heading =3D 0;

public double MagneticVariation =3D 0;

public char MagneticVariationEW =3D 'E';

public double Altitude =3D 0;<= /p>

public char AltitudeUnits =3D 'M';

/// Correction applied by GPS to Altitude to convert from WG= S81 to

true sea level

/// If '0' than probably Altitude is not corrected and c= an show weird

results on the sea beach.

public double HeightOfGeoid =3D 0;

public char HeightOfGeoidUnits =3D 'M';

/// If DGPS (Differential GPS) is in use.

public bool DGPSInUse =3D false;

pu= blic int DGPSCorrectionAge =3D 0;

public string DGPSStationID =3D "";

//********************************

// history and statistics

// ********************************

&nbs= p;

public int MAXHISTORY =3D 36000;

/// Number= of valid records stored in HistorySpeed, HistoryAltitude

etc.

public int HistoryUsed =3D 0;<= /p>

/// Helper variable for records stored in <code&g= t;HistorySpeed</co= de>, <code>HistoryAltitude<= /code> etc.

/// All the History* arrays are rotating, i.e. when the = array is full - next elements are stored from the beginning

/// To calculate the index of element x (where x is nega= tive, because 0 =3D current element, -1 =3D beforelast, etc.)

/// We have to perform 'MODULO' calculations taking into account also the <code>HistoryUsed</cod= e>

/// Helper function CalculateHistoryIndex(x) has been pr= ovided although it is not really used in the

/// programm.

///

/// index =3D (x + HistoryTail - HistoryUsed + MAXHISTOR= Y) % MAXHISTORY;

public int HistoryTail =3D 0;<= /p>

/// Total = number of elements added to history tables. If we are over the size of MAXHISTORY = it means some of thenm were already discarded

/// This can be used to determine if we have consumed all history elements to draw on screen. We cannot use the HistoryUsed because

/// when it reaches MAXHISTORY it does not increment any= more

public int HistoryTotalProcessed =3D 0;

/// Tables holding historical data.Next element added ev= ery update.

/// All the History* arrays are rotating, i.e. when the = array is full –

next elements are stored from the beginning

/// To calculate index:

///

/// index =3D (x + HistoryTail - HistoryUsed + MAXHISTOR= Y) % MAXHISTORY;

///

public double[] HistorySpeed =3D null;

public double[] HistoryAltitude =3D null;

public double[] HistoryLatitude =3D null;

public double[] HistoryLongitude =3D null;

public double HistorySpeedMax =3D 0;<= /span>

public double HistoryAltitudeMin =3D 99999;=

public double HistoryAltitudeMax =3D 0;

public double HistoryLatitudeMin =3D 360;

public double HistoryLatitudeMax =3D 0;

public double HistoryLongitudeMin =3D 360;<= /o:p>

public double HistoryLongitudeMax =3D 0;

public double HistoryAverageSpeed =3D 0;

public double HistoryTimeCoveredSeconds =3D 0;

p= ublic long HistoryGPSSentencesProcessed =3D 0;<= o:p>

public long HistoryGPSBytesRead =3D 0;

/// Number of bytes from GPS used for decoding (identifi= ed as valid)

public long HistoryGPSBytesUsed =3D 0;

/// Number of bytes read from GPS discarded (invalid sentences, bad

public long HistoryGPSBytesDiscarded =3D 0;=

/// Total = distance traveled since history is recorded.

/// Note:

/// 1) This is calculated from Speed and TimeBetweenFixe= s, not Latitude/Longitude.

/// 2) Distances traveled with poor reception and GPS sw= itched off for more than 20 seconds are excluded

/// that the maximum value is not any more in the table = at some moment.

public double HistoryDistance =3D 0;<= /span>

public void HistoryClear(int newsize)

{ }<= /p>

public void HistoryClear()

{ }<= /p>

/// Adds new history record if new data is available fro= m GPS

/// This function adds new record to all history arrays.=

///

/// 1) first checks time span between TimeLastUpdate and=

<code&= gt;TimePrevi= ousUpdate</code= >.

/// <= /span>if the timespan is too long (i.e. GPS was switched off or poor

receiption) the History is not updated

///

/// 2) Arrays that are updated by this function:

/// <code>HistorySpeed</co= de>, <code>HistoryAltitude<= /code>,

<code&= gt;HistoryLo= ngitude</code= >, = <code&= gt;HistoryAl= titude</code= >

/// All the arrays are rotating FIFO buffers.

///

/// 3) To use the arrays you have to correctly calculate= index of the

element. See discussion in <code>CalculateHistoryIndex method.

public void HistoryUpdate()

{

TimeSpan TimeSinceLastUpdate =3D TimeCurrentFix= - TimeLastFix;

if (HistoryUsed < MAXHISTORY)

= HistoryUsed++;

// update history FIFO arrays

HistorySpeed[HistoryTail] =3D SpeedOverGround;

if (SpeedOverGround > HistorySpeedMax) HistorySpeedMax =3D SpeedOverGround;

HistoryAltitude[HistoryTail] =3D Altitude;

if (Altitude > HistoryAltitudeMax) HistoryAltitudeMax =3D Altitude;

if ((Altitude < HistoryAltitudeMin) && (Altitude !=3D 0)) HistoryAltitudeMin =3D Altitude; // we ignore A= lt=3D0 which results from 2DFix

HistoryLatitude[HistoryTail] =3D Latitude;

if (Latitude > HistoryLatitudeMax) HistoryLatitudeMax =3D Latitude;

if (Latitude < HistoryLatitudeMin) HistoryLatitudeMin =3D Latitude;

HistoryLongitude[HistoryTail] =3D Longitude;

if (Longitude > HistoryLongitudeMax) HistoryLongitudeMax =3D Longitude;

if (Longitude < HistoryLongitudeMin) History= LongitudeMin =3D Longitude;

// calculate distance and average speed

HistoryTimeCoveredSeconds +=3D TimeSinceLastUpdate.TotalSeconds; // seconds

HistoryDistance +=3D SpeedOverGround * TimeSinceLastUpdate.TotalHour= s; //km

HistoryAverageSpeed =3D HistoryDistance / HistoryTimeCoveredSeconds * 3600; //km/h

&nbs= p;

// move the tail of the FIFO rotating buffers

HistoryTail =3D (HistoryTail + 1) % MAXHISTORY;

HistoryTotalProcessed++;

}

<= o:p>

Listing 4 NMEA0183.cs, SIRFBINARY.cs<= /span> is fairly identical

<= o:p>

class NMEA0183

{

public static string<= /span> CalculateChecksum(string sentence)

{ }<= /p>

/// Build full NMEA sentence from a given command and parameters.

/// Sentence includes leading '$' and valid checksum.

public static string<= /span> BuildNMEASentence(string command, string parameters)

{ }<= /p>

public static string<= /span> BuildNMEASentence(string command, string[] parameters)

{ }<= /p>

/// Returns true if NMEA sentence has a valid checksum. =

public static bool ChecksumValid(string sentence)=

{ }<= /p>

/// Main NMEA parser. Update given GPSData structure with values from a given NMEA sentence.

/// Function does not check if a sentence is valid and h= as a good checksum.

/// This should be done earlier.

///

/// Returns true if sentence was parsed succesfully.

/// false if sentence was invalid, thrown exception or i= s not implemented by this parser.

public static bool UpdateGPSData(string sentence, GPSData currentdata)

{

// decode NMEA sentence and update fields of GPS Data accordingly

currentdata.Protocol =3D GPSData.Protocols.NMEA;

string cmd =3D ParseCommand(sente= nce);

string[] cmdparams =3D ParseParameters(sentence= );

try

{

= if (cmd =3D=3D "GPRMC")

= {

= currentdata.NavigationStatus =3D cmdparams[1];// Status, V =3D Navigation receiver warning

= currentdata.Latitude =3D GetDoubleValue(cmdparams[2]);

= currentdata.LatitudeNS =3D cmdparams[3][0];

= currentdata.Longitude =3D GetDoubleValue(cmdparams[4]);

******* etc etc ****

= }

= else if= (cmd =3D=3D "GPRMB")

= {

= }

= else if= (cmd =3D=3D "GPGGA")

= {

= }

= else if= (cmd =3D=3D "GPGSA")

= {

= }

= Else, else, else --- other NMEA sentences=

= "GPGSV","PGRME","GPGLL", "PGRMZ", "PGRMM", "GPBOD",

"= GPRTE"

currentdata.HistoryGPSSentencesProcessed++;

}

<= o:p>