GPS (TotalCrossSDK 6.1.0 API)

java.lang.Object
- totalcross.io.device.gps.GPS

```
public class GPS
extends java.lang.Object
```
Class that retrieves GPS coordinates read from the COM (or Bluetooth, or IR) port. Windows Mobile, Android and iOS use the native API instead of reading from the COM port. This class only retrieves data updating the internal fields. If you want to display that data, you may use the GPSView class. For example:
```
 new Thread() 
 {
    public void run()
    {
       gps = new GPS();
       for (int i = 0; i < 60*2 && gps.location[0] == 0; i++) // wait 60s
       {
          Vm.safeSleep(500);
          try
          {
             gps.retrieveGPSData();
          }
          catch (GPSDisabledException gde)
          {
             Toast.show("Please enable GPS!",2000);
          }
          catch (Exception eee)
          {
             eee.printStackTrace();
             break;
          }
       }
    }
 }.start();
 
```
If the GPS fails connecting to the satellites, and the phone has signal, you can use the cell tower location as a rough location. The precision is vary between 50m to 3km, depending where the phone is. You can get the latitude and longitude using CellInfo.toCoordinates. See the tc.samples.maps.GoogleMaps sample.
Since:

TotalCross 1.38

See Also:

GPS, CellInfo.toCoordinates()

Field Summary

Fields
Modifier and Type	Field and Description
`double`	`direction` Stores the direction in degrees from the North.
`static int`	`HIGH_GPS_PRECISION` Used in gpsPrecision
`static double`	`INVALID` A value that indicates that invalid data was retrieved.
`Time`	`lastFix` Stores the time of the last updated.
`double[]`	`location` Stores the location - latitude on first index (0) and longitude on second index (1).
`static int`	`LOW_GPS_PRECISION` Used in gpsPrecision
`java.lang.String`	`lowSignalReason` The reason for the low signal, if retrieveGPSData returned false.
`java.lang.String`	`messageReceived` The retrieved message, or null in Windows Mobile and Android.
`double`	`pdop` The last PDOP, if any.
`int`	`precision` Defines the GPS precision (currently has effect only on Android): if HIGH, only the GPS is used, if LOW, then Google Play Services is also used.
`int`	`satellites` Number of satellites in view.
`double`	`velocity` Stores the speed in knots.

Constructor Summary

Constructors
Constructor and Description
`GPS()` Constructs a GPS control.
`GPS(int precision)` Constructs a GPS control, with the given precision.
`GPS(PortConnector sp)` Constructs a GPS control with the given serial port.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`finalize()`
`double`	`getLatitude()` Returns the latitude (`location[0]`).
`double`	`getLongitude()` Returns the longitude (`location[1]`).
`static java.lang.String`	`getWinCEGPSCom()` Returns the Windows CE GPS COM port, which can be used to open a PortConnector.
`boolean`	`retrieveGPSData()` Call this method to retrieve the data from the GPS.
`void`	`stop()` Closes the underlying PortConnector or native api.
`static double`	`toCoordinate(java.lang.String s, char dir)` Returns the coordinate of the given string and direction.
`static java.lang.String`	`toCoordinateGGMMSS(java.lang.String coord, char dir)`

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - location
```
public double[] location
```
    Stores the location - latitude on first index (0) and longitude on second index (1). On low signal, it contains the value INVALID.
  - direction
```
public double direction
```
    Stores the direction in degrees from the North. On low signal, it contains the value INVALID.
  - velocity
```
public double velocity
```
    Stores the speed in knots. On low signal, it contains the value INVALID.
  - satellites
```
public int satellites
```
    Number of satellites in view.
    
    Since:
    
    TotalCross 1.20
  - lastFix
```
public Time lastFix
```
    Stores the time of the last updated.
  - messageReceived
```
public java.lang.String messageReceived
```
    The retrieved message, or null in Windows Mobile and Android.
  - pdop
```
public double pdop
```
    The last PDOP, if any. On low signal, it contains the value INVALID.
    
    Since:
    
    TotalCross 1.27
  - lowSignalReason
```
public java.lang.String lowSignalReason
```
    The reason for the low signal, if retrieveGPSData returned false.
    
    Since:
    
    TotalCross 1.38
  - HIGH_GPS_PRECISION
```
public static final int HIGH_GPS_PRECISION
```
    Used in gpsPrecision
    
    See Also:
    
    Constant Field Values
  - LOW_GPS_PRECISION
```
public static final int LOW_GPS_PRECISION
```
    Used in gpsPrecision
    
    See Also:
    
    Constant Field Values
  - precision
```
public int precision
```
    Defines the GPS precision (currently has effect only on Android): if HIGH, only the GPS is used, if LOW, then Google Play Services is also used. Be aware that Google Play Services may return wifi and radio antenna values, with pdop ranging from 30m to 1500m or more; always check the pdop value and discard or store it. Note that this is set at the constructor, and changing it after will have no effect; you must create a new GPS instance.
    
    Since:
    
    TotalCross 3.1
  - INVALID
```
public static final double INVALID
```
    A value that indicates that invalid data was retrieved. Declared as the minimum double value.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - GPS
```
public GPS()
    throws IOException
```
    Constructs a GPS control. Already prepared for PIDION scanners. It automatically scans the Windows CE registry searching for the correct GPS COM port. Under Windows Mobile and Android, uses the internal GPS api.
    
    Throws:
    
    GPSDisabledException - If GPS is disabled
    
    IOException - If something goes wrong or if there's already an open instance of the GPS class
  - GPS
```
public GPS(int precision)
    throws IOException
```
    Constructs a GPS control, with the given precision. Already prepared for PIDION scanners. It automatically scans the Windows CE registry searching for the correct GPS COM port. Under Windows Mobile and Android, uses the internal GPS api.
    
    Throws:
    
    GPSDisabledException - If GPS is disabled
    
    IOException - If something goes wrong or if there's already an open instance of the GPS class
  - GPS
```
public GPS(PortConnector sp)
    throws IOException
```
    Constructs a GPS control with the given serial port. For example:
```
 PortConnector sp = new PortConnector(PortConnector.BLUETOOTH, 9600);
 sp.setReadTimeout(500);
 gps = new GPS(sp);
 
```
    Don't use this constructor under Android nor Windows Mobile.
    Throws:
    
    IOException - If something goes wrong or if there's already an open instance of the GPS class
    
    See Also:
    
    GPS()
- Method Detail
  - getWinCEGPSCom
```
public static java.lang.String getWinCEGPSCom()
```
    Returns the Windows CE GPS COM port, which can be used to open a PortConnector. Sample:
```
 String com;
 if (Settings.isWindowsDevice() && (com = GPS.getWinCEGPSCom()) != null)
    sp = new PortConnector(Convert.chars2int(com), 9600, 7, PortConnector.PARITY_EVEN, 1);
 
```
    Returns:
    
    A string like "COM3", or null if no keys with GPS was found under HKLM\Drivers\BuildIn.
  - stop
```
public void stop()
```
    Closes the underlying PortConnector or native api.
  - getLatitude
```
public double getLatitude()
```
    Returns the latitude (location[0]).
  - getLongitude
```
public double getLongitude()
```
    Returns the longitude (location[1]).
  - toCoordinate
```
public static double toCoordinate(java.lang.String s,
                                  char dir)
```
    Returns the coordinate of the given string and direction.
    
    Parameters:
    
    s - the string in coordinate format.
    
    dir - the direction: SWEN
  - toCoordinateGGMMSS
```
public static java.lang.String toCoordinateGGMMSS(java.lang.String coord,
                                                  char dir)
                                           throws InvalidNumberException
```
    Throws:
    
    InvalidNumberException
  - retrieveGPSData
```
public boolean retrieveGPSData()
```
    Call this method to retrieve the data from the GPS.
    
    See Also:
    
    lowSignalReason
  - finalize
```
protected void finalize()
```
    Overrides:
    
    finalize in class java.lang.Object

Class GPS

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

location

direction

velocity

satellites

lastFix

messageReceived

pdop

lowSignalReason

HIGH_GPS_PRECISION

LOW_GPS_PRECISION

precision

INVALID

Constructor Detail

GPS

GPS

GPS

Method Detail

getWinCEGPSCom

stop

getLatitude

getLongitude

toCoordinate

toCoordinateGGMMSS

retrieveGPSData

finalize