GPS

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

Notes:

For the TouchPad, Google location services are used to provide WiFi fixes. This requires users to set Google services to ON. However, this does not apply to a 3G TouchPad, which has a GPS chip and a modem.
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 (Permission Denied):
- 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 application cannot use the Google Location service, 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 an application makes a Location service request.
  
  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

getCurrentPosition - Returns a location fix.
startTracking - Returns continuous location fixes.
getReverseLocation - Returns a location fix given a longitude and latitude.

Also in this document: GPS CSV Route File

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.

Syntax

{
    "accuracy"     : int,
    "maximumAge"   : int,
    "responseTime" : int
}

Parameters

Parameter	Required	Type	Description
accuracy	No	int	Location fix accuracy/precision: 1: High (100 mt or less) 2 (default): Medium (350 mt or less) 3: Low
maximumAge	No	int	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 - do not use the cached value.
responseTime	No	int	First fix desired time: 1: Immediate less than 5 sec 2 (default): Greater than 5 sec and less than 20 sec 3: Greater than 20 sec

Returns

{
   "returnValue"   : boolean,
   "altitude"      : double,
   "heading"       : double,
   "horizAccuracy" : double,
   "latitude"      : double,
   "longitude"     : double,
   "timestamp"     : double,
   "velocity"      : double,
   "vertAccuracy"  : double,
   "errorCode"     : int   
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	Always `true`.
errorCode	Yes	int	One of the following: 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: If errorCode=0, then the fields that are listed after this are returned.
altitude	No	double	Location altitude in meters. If unknown, the value is -1.
heading	No	double	Compass azimuth in degrees. Valid range: 0.0, 360.0. If unknown, the value is -1.
horizAccuracy	No	double	Location's horizontal accuracy in meters. If unknown, the value is -1.
latitude	No	double	Location's latitude in degrees. Valid range: -90.0, 90.0.
longitude	No	double	Location's longitude in degrees. Valid range: -180.0, 180.0.
timestamp	No	double	Time when location was fixed. This is milliseconds since Epoch, aka Unix time.
velocity	No	double	Velocity in meters per second. If unknown, the value is -1.
vertAccuracy	No	double	Location's vertical accuracy in meters. If unknown, the value is -1.

Examples

luna-send


root@webos-device:/var/home/root# luna-send -P -i palm://com.palm.location/getCurrentPosition '{"subscribe":true}'
{"altitude":0,"errorCode":0,"heading":0,"horizAccuracy":20,"latitude":37.390196,"longitude":-122.037845,"returnValue":true,"timestamp":1311197978000,"velocity":0,"vertAccuracy":0}

Enyo

enyo.kind({
   name : "enyo.gps",
   kind : enyo.VFlexBox,
   components : [ 
     { flex : 1,
      kind : "Pane",
      components : [{
         flex : 1,
         kind : "Scroller",
         components : [{
            name      : "getPos",
            kind      : "PalmService",
            service   : "palm://com.palm.location/",
            method    : "getCurrentPosition",
            onSuccess : "getPosSuccess",
            onFailure : "getPosFailure",
            subscribe : true
         },
         {kind : "Button", name : "getPosButton", caption : "Get Current Position", onclick : "getPosClick"}
        ]
      }]
    }],
    getPosClick: function() {       
         this.$.getPos.call({});
    },
    getPosSuccess : function(inSender, inResponse) {
        enyo.log("getCurrentPosition success, results=" + enyo.json.stringify(inResponse));
    },
    getPosFailure : function(inSender, inResponse) {
        enyo.log("getCurrentPosition failure, results=" + enyo.json.stringify(inResponse));
    }
});

Mojo

this.controller.serviceRequest('palm://com.palm.location', {
     method: 'getCurrentPosition',
     parameters: {},
     onSuccess : function (e){ Mojo.Log.info("getCurrentPosition success, results="+JSON.stringify(e)); },
     onFailure : function (e){ Mojo.Log.info("getCurrentPosition failure, results="+JSON.stringify(e)); }
});

Success

 getCurrentPosition success, results=
{
   "altitude":33,
   "errorCode":0,
   "heading":-1,
   "horizAccuracy":113,
   "latitude":37.790587,
   "longitude":-122.421341,
   "returnValue":true,
   "timestamp":1306194404000,
   "velocity":-1,
   "vertAccuracy":192
}

Failure

getCurrentPosition failure, results=
{
    "errorCode"   : 1,
    "returnValue" : true
}

startTracking

Requests a continuous location fix. Every time the service determines that the device position has changed, it invokes the onSuccess callback with a new location object. In case of error, the service invokes the callback with an errorCode greater than 0.

Syntax

{
    "subscribe"     : boolean
}

Parameters

Parameter	Required	Type	Description
subscribe	Yes	boolean	Set to `true` to get the response back.

Returns

{
   "returnValue"   : boolean,
   "altitude"      : double,
   "heading"       : double,
   "horizAccuracy" : double,
   "latitude"      : double,
   "longitude"     : double,
   "timestamp"     : double,
   "velocity"      : double,
   "vertAccuracy"  : double,
   "errorCode"     : int   
}

Attribute	Required	Type	Description
returnValue	Yes	boolean	Always `true`.
errorCode	No	int	One of the following: 0: Success 1: Timeout 2: Position_Unavailable 3: Unknown 4: GPS_Permanent_Error - No GPS fix but can still get the cell and Wifi fixes. A TouchPad without GPS returns this error. 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. (The user is not allowing this application to use this service.) Note: If errorCode=0, then the fields that are listed after this are returned.
altitude	No	double	Location altitude in meters. If unknown, the value is -1.
heading	No	double	Compass azimuth in degrees. Valid range: 0.0, 360.0. If unknown, the value is -1.
horizAccuracy	No	double	Location's horizontal accuracy in meters. If unknown, the value is -1.
latitude	No	double	Location's latitude in degrees. Valid range: -90.0, 90.0.
longitude	No	double	Location's longitude in degrees. Valid range: -180.0, 180.0.
timestamp	No	double	Time when location was fixed. This is milliseconds since Epoch, aka Unix time.
velocity	No	double	Velocity in meters per second. If unknown, the value is -1.
vertAccuracy	No	double	Location's vertical accuracy in meters. If unknown, the value is -1.

Examples

luna-send

luna-send -P -i palm://com.palm.location/startTracking '{"subscribe":true}'
{"errorCode":4}
{"returnValue":true}
{"altitude":0,"errorCode":0,"heading":0,"horizAccuracy":20,"latitude":37.390196,"longitude":-122.037845,"returnValue":true,"timestamp":1311188810000,"velocity":0,"vertAccuracy":0}
. . .

Enyo

enyo.kind({
   name : "enyo.gps",
   kind : enyo.VFlexBox,
   components : [ 
     { flex : 1,
      kind : "Pane",
      components : [{
         flex : 1,
         kind : "Scroller",
         components : [ {
            name      : "startTrack",
            kind      : "PalmService",
            service   : "palm://com.palm.location/",
            method    : "startTracking",
            onSuccess : "startTrackSuccess",
            onFailure : "startTrackFailure",
            subscribe : true
         },      
         {kind : "Button", name : "startTrackButton", caption : "Start Tracking", onclick : "startTrackClick"}
        ]
      }]
    }],
    startTrackClick: function() {       
         this.$.startTrack.call({"subscribe":true});
    },
    startTrackSuccess : function(inSender, inResponse) {
        enyo.log("startTracking success, results=" + enyo.json.stringify(inResponse));
    },
    startTrackFailure : function(inSender, inResponse) {
        enyo.log("startTracking failure, results=" + enyo.json.stringify(inResponse));
    }   
});

Mojo

this.controller.serviceRequest('palm://com.palm.location', {
    method: 'startTracking',
    parameters: {"subscribe":true},
    onSuccess : function (e){ Mojo.Log.info("startTracking success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("startTracking failure, results="+JSON.stringify(e)); }
});

Success

startTracking success, results=
{
    "returnValue" : true
}

startTracking success, results=
{
   "altitude":60,
   "errorCode":0,
   "heading":0,
   "horizAccuracy":50,
   "latitude":37.791435,
   "longitude":-122.420241,
   "returnValue":true,
   "timestamp":1306201144000,
   "velocity":0,
   "vertAccuracy":128
}

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.

Syntax

{
    latitude  : double,
    longitude : double
}

Parameters

Parameter	Required	Type	Description
latitude	Yes	double	Location's latitude in degrees. Valid range: -90.0, 90.0.
longitude	Yes	double	Location's longitude in degrees. Valid range: -180.0, 180.0.

Returns

{
    "address"   : string,
    "street"    : string,
    "substreet" : string,
    "city"      : string,
    "state"     : string,
    "country"   : string,
    "zipcode"   : string,
    "errorCode" : int
}

Attribute	Required	Type	Description
address	No	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
street	No	string	Street
substreet	No	string	Substreet
state	No	string	State
country	No	string	Two-digit country code, i.e., "RU" (Russia)
zipcode	No	string	Zipcode
errorCode	Yes	integer	One of the following: 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.

Examples

luna-send

luna-send -P -i palm://com.palm.location/getReverseLocation '{"latitude":80, "longitude":80}'
{"address":"Russia","country":"RU","errorCode":0}

luna-send -P -i palm://com.palm.location/getReverseLocation '{"latitude":37.390196,"longitude":-122.037845}'
{"address":"485 Potrero Ave ;Sunnyvale, CA 94085 ;USA","city":"Sunnyvale","country":"US","errorCode":0,"state":"California","street":"Potrero Ave","substreet":"485","zipcode":"94085"}

Enyo

enyo.kind({
   name : "enyo.gps",
   kind : enyo.VFlexBox,
   components : [ 
     { flex : 1,
      kind : "Pane",
      components : [{
         flex : 1,
         kind : "Scroller",
         components : [{
            name      : "getRevLoc",
            kind      : "PalmService",
            service   : "palm://com.palm.location/",
            method    : "getReverseLocation",
            onSuccess : "getRevLocSuccess",
            onFailure : "getRevLocFailure",
            subscribe : true
         },       
         {kind : "Button", name : "getRevLocButton", caption : "Get Reverse Location", onclick : "getRevLocClick"}
        ]
      }]
    }],
    getRevLocClick: function() {        
         this.$.getRevLoc.call({"latitude":37.390196,"longitude":-122.037845});
    },
    getRevLocSuccess : function(inSender, inResponse) {
        enyo.log("getReverseLocation success, results=" + enyo.json.stringify(inResponse));
    },
    getRevLocFailure : function(inSender, inResponse) {
        enyo.log("getReverseLocation failure, results=" + enyo.json.stringify(inResponse));
    }   
});

Mojo

this.controller.serviceRequest('palm://com.palm.location', {
    method: 'getReverseLocation',
    parameters: {"latitude":80, "longitude":80},
    onSuccess : function (e){ Mojo.Log.info("getReverseLocation success, results="+JSON.stringify(e)); },
    onFailure : function (e){ Mojo.Log.info("getReverseLocation failure, results="+JSON.stringify(e)); }
});

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 column order 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	Location's latitude in degrees	Floating point; Valid range: [-90.0, 90.0] Example: 37.39237547
longitude	Location's longitude in degrees	Floating point; Valid range: [-180.0, 180.0] Example: -122.04251111
altitude	Location's altitude 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	Location's horizontal accuracy in meters	Floating point; if unknown, value is -1 Example: 7.07 Default: 5
vaccuracy	Location's vertical accuracy 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