Prev: Module compass: Magnetometer Measurements
Module location: Location Information
| | |
| Compatibility of module location |
| Sony Ericsson phones and Nokia S60 2nd Edition phones lack this module. | Module not found |
|
This module returns information about the current geographical position of the device, i.e. its longitude, latitude, and altitude. Derived information like speed, course and heading is also available.
The source of location information is typically a GPS receiver (either built into the device, or an external device connected via Bluetooth®), but network based methods (e.g. GSM cell and signal, WLAN IP location) may also be supported.
location.course
• function course() → Array
Permissions: ReadApp
Capabilities: extended
After a new position has been obtained with location.get, returns an array with information about the course of the device:
| Key | Meaning | Type |
| course | Course over ground (degrees, 0 is north) | Number |
| speed | Speed over ground (meters per second) | Number |
| heading | Heading (degrees, 0 is north) | Number |
| courseacc | Accuracy of the course over ground | Number |
| speedacc | Accuracy of the speed over ground | Number |
| headingacc | Accuracy of the heading | Number |
| |
Throws ErrNotReady if there is no up to date position, i.e. location.get was not called before. Throws ErrNotSupported if the current source does not provide course information.
while true do
// get the most recent position
p=location.get();
// also get the course
c=location.course();
// output the speed, converting m/s to km/h
print "speed:",c["speed"]*3.6,"km/h"
end
→ speed: NaN km/h
speed: 3.132 km/h
speed: 4.464 km/h
|
location.get
• function get(timeout=-1, interval=100) → Array|null
Permissions: ReadApp
Capabilities: extended
Attempts to get an up to date position, and returns it as an array. If timeout>=0 and timeout milliseconds have passed without obtaining a position, null is returned. The interval for position updates is set to interval milliseconds.
The position is returned as an array with the following fields:
| Key | Meaning | Type |
| long | The longitude (degrees, positive is east) | Number |
| lat | The latitude (degrees, positive is north) | Number |
| alt | The altitude (meters above sea level) | Number |
| horacc | Accuracy of longitude and latitude | Number |
| veracc | Accuracy of altitude | Number |
| utc | The device time when the fix was obtained, in number of seconds since year 0 UTC. See also module time. | Number |
| |
Fields for which no valid information can be obtained are set to math.nan or 0.
p=location.get();
print "Longitude:",location.str(p["long"]);
print "Latitude: ",location.str(p["lat"]);
print "Altitude: ",p["alt"],"m"
→ Longitude: +8°33'10.412"
Latitude: +47°21'19.268"
Altitude: 478 m
|
location.last
• function last(timeout=-1) → Array|null
Permissions: ReadApp
Capabilities: extended
Gets the last known position and returns it with the same fields as location.get. This can be used to obtain an estimate for the current position if there is currently no positioning mechanism available (e.g. because the device is inside a building, shielded from GPS reception). If timeout>=0 and timeout milliseconds have passed without obtaining data, null is returned.
location.sats
• function sats() → Array
Permissions: ReadApp
Capabilities: extended
After a new position has been obtained with location.get, returns an array with information about the GPS satellites:
| Key | Meaning | Type |
| used | Number of satellites used | Number |
| utc | The GPS time when the fix was obtained, in number of seconds since year 0 UTC. See also module time. | Number |
| hordop | Dilution of precision of horizontal coordinate (1 is best, larger values indicate increased scatter) | Number |
| verdop | Dilution of precision of vertical coordinate | Number |
| utcdop | Dilution of precision of time | Number |
| sats | The satellites in view | Array |
| |
Each member of the array with key sats describes a satellite in view, as an array with the following fields:
| Key | Meaning | Type |
| id | Id of the GPS satellite | Number |
| used | Whether this satellite is used for the fix | Boolean |
| signal | The strength of the received signal in dB | Number |
| azimuth | The azimuth (in degrees) of the satellite's position relative to the device | Number |
| elevation | The elevation (in degrees) of the satellite's position relative to the device | Number |
| |
Throws ErrNotReady if there is no up to date position, i.e. location.get was not called before. Throws ErrNotSupported if the current source does not provide satellite information.
This fragment updates the device clock from the very accurate GPS clock:
// Difference between device time and GPS time
delta=location.get()["utc"]-location.sats()["utc"];
// Apply the difference to the device time
time.set(time.get()-delta)
|
The following example draws the satellites in view at their (projected) location:
function drawsats(sats)
// determine center and radius
s=graph.size(); cx=s[0]/2; cy=s[1]/2;
if cy<cx then r=0.8*cy else r=0.8*cx end;
// draw circle denoting horizon
graph.pen(graph.black); graph.circle(cx-r, cy-r, 2*r);
for sat in sats do
// on xy, elevation is distance from center
re=math.cos(sat["elevation"]*math.pi/180)*r;
// azimuth is direction from center (0 is north!)
alpha=sat["azimuth"]*math.pi/180;
x=cx+re*math.sin(alpha); y=cy-re*math.cos(alpha);
// draw the satellite red if it is used
if sat["used"] then graph.pen(graph.red)
else graph.pen(graph.blue) end;
// center the id in a circle
s=graph.size(sat["id"]); // size of id text
graph.text(x-s[0]/2, y+s[1]/2, sat["id"]);
graph.circle(x-s[1], y-s[1], 2*s[1])
end
end
drawsats(location.sats()["sats"]); graph.show()
|
 | Sample m screen |
location.source
• function source() → Array
• function source(required, prohibited=0) → Array
Permissions: ReadApp
Capabilities: extended
Without arguments, returns the currently used source of location information as an array:
| Key | Meaning | Type |
| name | The name or description of the source | String |
| flags | The flags indicating the type of source | Number |
| |
The flags are a bitwise combination of the following values:
• const gps = 1
The information source is a plain GPS receiver (e.g. an external Bluetooth device).
• const network = 2
The information source uses data available from a network (e.g. GSM, WLAN).
• const assisted = 4
The information source is assisted, e.g. a GPS receiver assisted by network information to obtain a rapid initial fix.
With one or two arguments, returns the currently used source of location information, and attempts to find and use a source having all the flags in required, and not having any of those in prohibited.
Throws ErrNotFound if no source meeting the criteria can be found or is available.
// Print the currently used source
print location.source()
→ [Assisted GPS,4]
// Select a source which is network based
location.source(location.network)
|
location.stop
• function stop() → null
Stops using the location service. Since some location services (the builtin GPS for instance) draw much power, this function should be called as soon as no new location information is needed.
Location services can be started again by calling any of location.get, location.last, location.source.
location.str
• function str(degrees) → String
Converts the value degrees (with fractions of degrees) into a string representation with degrees, minutes, seconds, and fractions of a second. The format of the string returned is:
| | |
Coordinate := ('+' | '-') Degrees '°' Minutes ''' Seconds '.'
Fractions '"'.
Degrees := Digit Digit .
Minutes := Digit Digit .
Seconds := Digit Digit .
Fractions := Digit Digit Digit .
|
|
See location.get for an example.
Next: Cryptography© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
