GPS

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

Notes:


Methods

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.

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:

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:

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