# GPS

The Location service provides basic location services for single or multiple location fixes.

Notes:

- Some carriers may not support, or may limit access to, Assisted-GPS (A-GPS) for location services. This can dramatically increase the time necessary for an initial position fix. This can be mitigated to some extent by choosing the parameters "responseTime:1" and "accuracy:3" when requesting position information. These settings, when combined with Google Services, will return a low-resolution fix within 30 seconds in most environments. Once the low resolution fix is acquired, updating the location using 'responseTime:3' and 'accuracy:1' will provide a high resolution location fix when available.

- To avoid excessive battery use:
  - Use the maximumAge field whenever appropriate.
  - Only use the Location service when necessary.
  - If you do not need fixes every second, limit the number of tracking requests.
  - Do not do a lot of location requests while your application is minimized, unless absolutely necessary.
  - Tracking fixes are suspended (not canceled) if the power turns off. When the power is back on, the tracking fixes resume.
- If the Location service returns an error code 6:
  - Error code 6 (Permission Denied) indicates that the user has not accepted the terms of use for the Google Location Service, or the Google Location Service is off. In this case, the Google Location Service cannot be used by the application, but the GPS Service can still return locations.
  - The user can accept the terms from the Location service preference panel or in response to a dialog that appears each time there is a location service request made by an application. Remind the user with a message similar to this: Permission Denied. To use this service, you must enable the Location service using the Location Services Preferences in the Launcher.

- In the emulator, the user is not required to perform the First Use setup. Consequently, the Location service returns error code 6 until it is switched on manually in the Location Prefs application.

## Methods

This section describes the following methods:

- getCurrentPosition
- startTracking
- getReverseLocation

### getCurrentPosition

Requests a location fix. This method does not return until a valid fix is available or the responseTime is exceeded. If called without any parameters, it returns the medium accuracy result.

Required parameters:

None.

#### Parameters

Parameter | Type | Description
--- | --- | ---
accuracy | integer | Accuracy or precision of the location fix as follows: 1: High (100 mt or less) 2 (default): Medium (350 mt or less) 3: Low
maximumAge | integer | Indicates that the application can accept a cached position whose age is not greater than the specified time in seconds. If set to 0 or not specified, the service immediately attempts to acquire a new position object. Default is 0, which means do not use the cached value.
responseTime | integer | Desired time to first fix as follows: 1: Immediate less than 5 sec 2 (default): Greater than 5 sec and less than 20 sec 3: Greater than 20 sec

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
altitude | double | Number representing the altitude of the location in meters. If unknown, the value is -1.
errorCode | integer | Set as follows: 0: Success 1: Timeout 2: Position_Unavailable 3: Unknown 5: LocationServiceOFF - No Location source available. Both Google and GPS are off. 6: Permission Denied - The user has not accepted the terms of use for the Google Location Service, or the Google Service is off. 7: The application already has a pending message 8: The application has been temporarily blacklisted.

Note:

All of the other data is valid only if errorCode is 0.

heading | double | Number representing the compass azimuth in degrees. Valid range: 0.0, 360.0. If unknown, the value is -1.
horizAccuracy | double | Horizontal accuracy of the location in meters. If unknown, the value is -1.
latitude | double | Number representing the location's latitude in degrees. Valid range: -90.0, 90.0.
longitude | double | Number representing the location's longitude in degrees. Valid range: -180.0, 180.0.
timestamp | double | The time (in milliseconds) when this location fix was created.
velocity | double | Number representing the velocity in meters per second. If unknown, the value is -1.
vertAccuracy | double | Vertical accuracy of the location in meters. If unknown, the value is -1.

onFailure

Attribute | Type | Description
--- | --- | ---
errorCode | integer | Set as follows: 0: Success 1: Timeout 2: Position_Unavailable 3: Unknown 5: LocationServiceOFF 6: Permission Denied - The user has not accepted the terms of use for the GPS Services. 7: The application already has a pending message 8: The application has been temporarily blacklisted.

Note:

All of the other data is valid only if errorCode is 0.

#### Example

>     this.controller.serviceRequest('palm://com.palm.location', {
>       method:"getCurrentPosition",
>       parameters:{},
>       onSuccess:{},
>       onFailure:{}

> });

### startTracking

Requests a continuous location fix by invoking the onSuccess callback with a new location object every time the service determines that the position of the device has changed. In case of error, the service calls the callback with an error code set to some value greater than 0.

Required parameter:

- subscribe

#### Parameters

Parameter | Type | Description
--- | --- | ---
subscribe | boolean | Should be true to get the response back.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
altitude | double | Number representing the altitude of the location in meters. If unknown, the value is -1.
errorCode | integer | As follows: 0: Success 1: Timeout 2: Position_Unavailable 3: Unknown 4: GPS_Permanent_Error (no more GPS fix in this case, but can still get the Cell and Wi-Fi fixes) 5: LocationServiceOFF - No Location source available. Both Google and GPS are off. 6: Permission Denied - The user has not accepted the terms of use for the Google Location Service, or the Google Service is off. 7: The application already has a pending message 8: The application has been temporarily blacklisted.

Note:

All of the other data is valid only if errorCode is 0.

heading | double | Number representing the compass azimuth in degrees. Valid range: 0.0, 360.0. If unknown, the value is -1.
horizAccuracy | double | Horizontal accuracy of the location in meters. If unknown, the value is -1.
latitude | double | Number representing the location's latitude in degrees. Valid range: -90.0, 90.0.
longitude | double | Number representing the location's longitude in degrees. Valid range: -180.0, 180.0.
timestamp | double | The time (in milliseconds) when this location fix was created.
velocity | double | Number representing velocity in meters per second. If unknown, the value is -1.
vertAccuracy | double | Vertical accuracy of the location in meters. If unknown, the value is -1.

onFailure

Attribute | Type | Description
--- | --- | ---
errorCode | integer | As follows: 0: Success 1: Timeout 2: Position_Unavailable 3: Unknown 4: GPS_Permanent_Error (no more GPS fix in this case, but can still get the Cell and wifi fixes) 5: LocationServiceOFF 6: Permission Denied - The user has not accepted the terms of use for Location Services. 7: The application already has a pending message 8: The application has been temporarily blacklisted.

Note:

All of the other data is valid only if errorCode is 0.

#### Example

>     this.controller.serviceRequest('palm://com.palm.location', {
>       method:"startTracking",
>       parameters:{},
>       onSuccess:{},
>       onFailure:{}
>     });

### getReverseLocation

Requests a location for the given latitude and longitude. This method can only be used when the Google Service is on and the terms of use have been accepted.

Required parameters:

- latitude
- longitude

#### Parameters

Parameter | Type | Description
--- | --- | ---
latitude | double | Number representing the location's latitude in degrees. Valid range: -90.0, 90.0.
longitude | double | Number representing the location's longitude in degrees. Valid range: -180.0, 180.0.

#### Return Handling

onSuccess

Attribute | Type | Description
--- | --- | ---
address | string | Formatted user-readable address lines. For example, if there are three address lines: 123 Abc Street Your Town, ST 12345 USA A semicolon separates each of the lines. There can be 0 formatted lines. The return value for this example address is: 123 Abc Street ; Your Town, ST 12345 ; USA
errorCode | integer | As follows: 0: Success 6: Permission Denied - The user has not accepted the terms of use for GPS Services. 7: The application already has a pending message 8: The application has been temporarily blacklisted.

onFailure

Attribute | Type | Description
--- | --- | ---
errorCode | integer | As follows: 0: Success 6: Permission Denied - The user has not accepted the terms of use for GPS Services. 7: The application already has a pending message 8: The application has been temporarily blacklisted.

#### Example

>     this.controller.serviceRequest('palm://com.palm.location', {
>       method:"getReverseLocation",
>       parameters:{},
>       onSuccess:{},
>       onFailure:{}
>     });

## GPS CSV Route File

The Route file is a text-based CSV (Comma Separated Values) file that contains information about waypoints on a route, including satellite information. This file is used only for GPS simulations on the emulator.

- Each row corresponds to a GPS fix received by the radio from a group of satellites.
- Each column represents an attribute of a GPS fix.

The order of the columns is significant; swapping header or data columns is not permitted. Each row consists of 20 fields related to the GPS fix itself, followed by 30 fields representing data about up to 10 satellites used for the fix.

To get the best simulation results (accurate pinpointing of the location), put the values mentioned as Default values in the fields. These are the ideal values.

For each satellite, three fields are used to represent the following information:

- The SV (space vehicle) number
- The signal-to-noise ratio and azimuth, concatenated into a string of five digits
- The elevation

If fewer than 10 satellites are available, some of the fields are empty. All fields must be present even if empty. Fields with values should be shifted to the left. For example, if 4 satellites are available, the satellite data consists of 12 fields with data, followed by 18 empty fields.

The following fields are currently used for simulation only, and are not activated on the device:

- utctime
- utcdate
- timetofix
- verticaldilusionofprecision
- horizontaldilusionofprecision
- fixtype (2d/3d)
- position mode
- satellites in use
- satellites in view mask
- satellite details for the first 10 satellites

Column | Meaning | Description
--- | --- | ---
error | Status of the GPS fix | A value of success if the GPS fix data is valid.
time | Time at which this fix was received from satellite. | format: HH:MM:SS Example: 13:32:22
date | Date on which this fix was received from satellite. | format: DDMMYYYY Example 2702008
latitude | Latitude of the location in degrees | Floating point; Valid range: [-90.0, 90.0] Example: 37.39237547
longitude | Longitude of the location in degrees | Floating point; Valid range: [-180.0, 180.0] Example: -122.04251111
altitude | Altitude of the location in meters | Floating point; if unknown, value is -10,000,000 Example: 53 Default: 0
velocity | Velocity of the moving target in meters per second. | Floating point; if unknown then value should be -1 Example: 4.75 Default: 0
heading | The compass azimuth in degrees | Floating point; valid range [0.0, 360.0]; If unknown, value is -1 Example: 124 or 0 or -1 Default: 0
timetofix | Time in seconds to get a fix | Default: 1
timextradown | Time in seconds for XTRA to download when using XTRA | Default: 0
timextrainject | Time in seconds for XTRA injection when using XTRA | Default: 0
haccuracy | Horizontal accuracy of the location in meters | Floating point; if unknown, value is -1 Example: 7.07 Default: 5
vaccuracy | Vertical accuracy of the location in meters | Floating point; if unknown, value is -1 Example: 12 Default: 5
hdilusion | Horizontal dilution of precision of the location | Not supported for simulation. Default: 1
vdilusion | Vertical dilution of precision of the location | Not supported for simulation. Default: 1
fixtype | Indicates whether a fix is 2D (lat / long) or 3D (lat / long / alt) | Possible values: "2d", "3d" Default: "3d"
attemptedmode | GPS Mode requested | Default: "msbased"
positionmode | GPS Mode used | Default: "msbased"
satsinview | Number of satellites in view (from 0 to 12) | Integer Example: 10 Default: 5
satsinuse | Bitmask indicating the number of valid satellites out of a max possible of 32 | Written as a sequence of ones-and-zeroes, terminated by "b". "1" indicates that this satellite is available for the fix, "0" indicates that it is not. Reads from right to left (starting from satellite number 0) Default: 0b This can also tell the number of satellite in view. Example: 000000010010001001010000000000b This shows that there were 5 satellites used for the fix satellite numbers 10, 12, 15, 19 and 22 were used.
s1prn | The SV (space vehicle) number of the first satellite in view | Integer; Example: 23
s1cno&azi | The signal-to-noise ratio and azimuth of the first satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s1elev | The elevation of the first satellite in view | Integer: Example: 31
s2prn | The SV (space vehicle) number of the second satellite in view | Integer; Example: 23
s2cno&azi | The signal-to-noise ratio and azimuth of the second satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s2elev | The elevation of the second satellite in view | Integer: Example: 31
s3prn | The SV (space vehicle) number of the third satellite in view | Integer; Example: 23
s3cno&azi | The signal-to-noise ratio and azimuth of the third satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s3elev | The elevation of the third satellite in view | Integer: Example: 31
s4prn | The SV (space vehicle) number of the fourth satellite in view | Integer; Example: 23
s4cno&azi | The signal-to-noise ratio and azimuth of the fourth satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s4elev | The elevation of the fourth satellite in view | Integer: Example: 31
s5prn | The SV (space vehicle) number of the fifth satellite in view | Integer; Example: 23
s5cno&azi | The signal-to-noise ratio and azimuth of the fifth satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s5elev | The elevation of the fifth satellite in view | Integer: Example: 31
s6prn | The SV (space vehicle) number of the sixth satellite in view | Integer; Example: 23
s6cno&azi | The signal-to-noise ratio and azimuth of the sixth satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s6elev | The elevation of the sixth satellite in view | Integer: Example: 31
s7prn | The SV (space vehicle) number of the seventh satellite in view | Integer; Example: 23
s7cno&azi | The signal-to-noise ratio and azimuth of the seventh satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s7elev | The elevation of the seventh satellite in view | Integer: Example: 31
s8prn | The SV (space vehicle) number of the eighth satellite in view | Integer; Example: 23
s8cno&azi | The signal-to-noise ratio and azimuth of the eighth satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s8elev | The elevation of the eighth satellite in view | Integer: Example: 31
s9prn | The SV (space vehicle) number of the ninth satellite in view | Integer; Example: 23
s9cno&azi | The signal-to-noise ratio and azimuth of the ninth satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s9elev | The elevation of the ninth satellite in view | Integer: Example: 31
s10prn | The SV (space vehicle) number of the tenth satellite in view | Integer; Example: 23
s10cno&azi | The signal-to-noise ratio and azimuth of the tenth satellite in view | Integer; Format: AAASS where AAA = azimuth in degrees 000 to 359 and SS = snr in dB 00 to 99, null when not tracking. Example: 27931
s10elev | The elevation of the tenth satellite in view | Integer: Example: 31