gpsFix (Functionblock)

The gpsFix function block is used to query the current position, time, and detailed satellite information from the internal GPS module.

Note regarding decimal minutes:

The value returned in decimal minutes, both latdecmin and londecmin, are assumed to be 4 digits large.

This means that the position 55 Deg. 51.3 Min. North is returned as latdeg=55 latmin=51 and latdecmin=3000, and the position 55 Deg. 52.0076 North is returned as latdeg=55 latmin=52 latdecmin=76.

SBAS Support:

Please see gpsSetSBAS.

When the "mode" parameter that is returned from gpsFix is 4, it indicates that the fix is not only a 3D fix but has also been SBAS-corrected.

Note regarding GPS with more than 12 channels:

While the full number of channels are used in position resolution, only the first 12 are included in the function block.

Note regarding HDOP, VDOP and PDOP:

The DOP values should be as low as possible. They describe the geometry of the satellites used. Generally a DOP value should not be higher than 6 as that will affect the accuracy negative.

Normally a DOP value will be between 2 and 3 when you have clear skies. In a city with houses screening the sky, the DOP value will be higher and accuracy will be affected.

One method to increase the accuracy of the used GPS positions is not to use fixes with an HDOP value higher than, for example, 300.

All values returned by gpsFix() are in the WGS-84 datum.

Input:

None.

Output:

mode : SINT;

0 = No info available (GPS not powered on?).

1 = Fix unavailable.

2 = 2D position fix.

3 = 3D position fix.

4 = 3D position fix with SBAS-correction (this requires that SBAS has been enabled, see gpsSetSBAS).

5 = Dead Reckoning fix.

linsec : DINT

Linsec for the timestamp received from the GPS receiver.

This is the same as the separate year, month, day, minute, and second but expressed as a linsec.

Also see clockLinsecToTime().

year : INT

Year (absolute).

month : SINT

Month (1..12).

day : SINT

Date (1..31).

hour : SINT

Hour (0..23).

minute : SINT

Minute (0..59).

second : SINT

Second (0..59).

millisecond : INT

Millisecond (0..999). Only available in firmware release 3.14 or newer.

latitude : DINT

Latitude expressed in a DINT.

Negative is south (ddmm.mmmm (multiplied by 10000)).

latsouth : BOOL

Direction of latitude (TRUE is south, FALSE is north).

latdeg : SINT

Latitude degress (0..90).

latmin : SINT

Latitude minutes (0..59).

latdecmin : INT

Latitude decimal minutes (0..9999).

This value is assumed to be 4 digits with the leading zeros removed.

Please see the note regarding decimal minutes above.

longitude : DINT

Longitude expressed in a DINT.

Negative is west (dddmm.mmmm (multiplied by 10000)).

lonwest : BOOL

Direction of longitude (TRUE is west, FALSE is east).

londeg : INT

Longitude degress (0..180).

lonmin : SINT

Longitude minutes (0..59).

londecmin : INT

Longitude decimal minutes (0..9999).

This value is assumed to be 4 digits with the leading zeros removed.

Please see note regarding decimal minutes above.

speed : DINT

Speed over ground in meters/hour.

course : DINT

Course over ground. In xxx.xx degrees (multiplied by 100) (0=north, 90=east, 225=southwest).

height : INT

Height in meters over mean sea level.

PDOP : INT

Position dilution of precision (multiplied by 100).

HDOP : INT

Horizontal dilution of precision (multiplied by 100).

VDOP : INT

Vertical dilution of precision (multiplied by 100).

inview : SINT

Number of satellites in view. This is the number of satellites that are above the horizon.

If gpsPowerLP is used, this will be 0.

used : SINT

Number of satellites used for the solution.

SVID[n] : SINT

Satellite ID.

El[n] : SINT

Elevation angle for satellite n.

Az[n] : INT

Azimuth angle for satellite n.

SNR[n] : SINT

Signal to noise ratio for satellite n. Max value is 55.

Declaration:

FUNCTION_BLOCK gpsFix;
VAR_OUTPUT
  mode         : SINT;   | 0=No info available, 1=Fix not available, 2=2D position fix, 3=3D position fix, 4=3D pos. with SBAS
  linsec       : DINT;   | Linsec of time-stamp
  year         : INT;     | year (absolute, like 2004)
  month       : SINT;   | month (1..12)
  day         : SINT;   | date (1..31)
  hour         : SINT;   | hour (0..23)
  minute       : SINT;   | minute (0..59)
  second       : SINT;   | second (0..59)
  millisecond : INT;     | millisecond (0..999)
  latitude     : DINT;   | Negative is South (ddmm.mmmm (multiplied by 10000))
  latsouth     : BOOL;   | True = South, False = North
  latdeg       : SINT;   | Degrees (0..90)
  latmin       : SINT;   | minutes (0..59)
  latdecmin   : INT;     | decimal minutes (0..9999)
  longitude   : DINT;   | Negative is West (dddmm.mmmm (multiplied by 10000))
  lonwest     : BOOL;   | True = West, False = East
  londeg       : INT;     | degrees (0..180)
  lonmin       : SINT;   | minutes (0..59)
  londecmin   : INT;     | decimal minutes (0..9999)
  speed       : DINT;   | Speed over ground in meters/hour
  course       : DINT;   | Course over ground. In xxx.xx degrees (multiplied by 100)
  height       : INT;     | Height in meters over Mean Sea Level.
  PDOP         : INT;     | Position dilution of precision (PDOP) (multipied by 100).
  HDOP         : INT;     | Horizontal dilution of precision (HDOP) (multipied by 100).
  VDOP         : INT;     | Vertical dilution of precision (VDOP) (multipied by 100).
  inview       : SINT;   | Number of satellites in view
  used         : SINT;   | Number of satellites used in solution
 
  // The following information is grouped, index 1 for all arrays is for the first satellite etc.
  SVID         : ARRAY[1..12] OF SINT; // Satellite Vehicle number
  El           : ARRAY[1..12] OF SINT; // Elevation angle for satellite
  Az           : ARRAY[1..12] OF INT; // Azimuth angle for satellite
  SNR         : ARRAY[1..12] OF SINT; // Signal to Noise ratio for satellite
END_VAR;

Example:

INCLUDE rtcu.inc
 
FUNCTION ShowDecmin : STRING;
VAR_INPUT
  decmin : INT;
END_VAR;
  ShowDecmin := intToStr(v := decmin);
  WHILE strLen(str := ShowDecmin) < 4 DO
     ShowDecmin := strConcat(str1 := "0", str2 := ShowDecmin);
  END_WHILE;
END_FUNCTION;
 
PROGRAM test;
VAR
gps   : gpsFix;
  index : SINT;
  str   : STRING;
END_VAR;
 
 
gpsPower(power := ON);
BEGIN
  gps();
  IF gps.mode > 1 THEN
    DebugFmt(message:="Mode=\1", v1:=gps.mode);
    DebugFmt(message:="   Linsec=\4", v4:=gps.linsec);
    DebugFmt(message:="   Time=\1:\2:\3", v1:=gps.hour, v2:=gps.minute, v3:=gps.second);
    DebugFmt(message:="   Date=\1:\2:\3", v1:=gps.year, v2:=gps.month, v3:=gps.day);
    DebugFmt(message:="   Lat: latitude=\4", v4:=gps.latitude);
    IF gps.latsouth THEN DebugMsg(message:="   Lat: South"); ELSE DebugMsg(message:="   Lat: North"); END_IF;
     str := strConcat(str1 := "   Lat: Deg=\1 Min=\2 Dec=", str2 := ShowDecmin(decmin := gps.latdecmin));
    DebugFmt(message:=str, v1:=gps.latdeg, v2:=gps.latmin);
    DebugFmt(message:="   Lon: longitude=\4", v4:=gps.longitude);
    IF gps.lonwest THEN DebugMsg(message:="   Lon: West"); ELSE DebugMsg(message:="   Lon: East"); END_IF;
     str := strConcat(str1 := "   Lon: Deg=\1 Min=\2 Dec=", str2 := ShowDecmin(decmin := gps.londecmin));
    DebugFmt(message:=str, v1:=gps.londeg, v2:=gps.lonmin);
    DebugFmt(message:="   Speed=\4", v4:=gps.speed);
    DebugFmt(message:="   Course=\4", v4:=gps.course);
    DebugFmt(message:="   Height=\1", v1:=gps.height);
    DebugFmt(message:="   PDOP=\1", v1:=gps.PDOP);
    DebugFmt(message:="   HDOP=\1", v1:=gps.HDOP);
    DebugFmt(message:="   VDOP=\1", v1:=gps.VDOP);
    DebugFmt(message:="   In view=\1, Used=\2", v1:=gps.inview, v2:=gps.used);
    FOR index := 1 TO gps.inview DO
        DebugFmt(message:="      SVID=\1, El=\2, Az=\3, SNR=\4",
                 v1:=gps.SVID[index], v2:=gps.El[index], v3:=gps.Az[index], v4:=gps.SNR[index]);
     END_FOR;
  END_IF;
END;
END_PROGRAM;