6.6 positioning - Simplified interface to the position information
The positioning module provides basic access to the S60 position information. The module can be
e.g. used to access position information provided by external Bluetooth GPS-devices and by built-in
GPS-receivers from S60 2nd Edition FP 2 onwards.
The module offers a large amount of information (cost of service, device power consumption etc.) about
accessible positioning devices (like GPS-modules), position, course, accuracy and satellite information
(depending on the position device used) and much more. This module can also be used to obtain
device/vendor specific extended information.
Note: The module position requires Location capability to work fully in S60 3rd Edition devices.
The following data items are available in positioning:
POSITION_INTERVAL
The time interval (in microseconds) between the position function callback invocation. The
default value set is 1 000 000 microseconds (= 1 second)
The positioning module has the following functions (for examples of the values returned, see Section
6.6.1):
modules()
Get information about available positioning modules.
default_module()
Get default module id.
module_info(module id)
Get detailed information about the specied module.
select_module(module id)
Select a module.
set_requestors(requestors)
Set the requestors of the service (at least one must be set).
position(course=0,satellites=0,callback=None, interval=positioning.POSITION_INTERVAL, partial=0)
By default, returns the position information in a dictionary. With course and/or satellites set to
1, information about course and satellites is also returned (if available).
With no callback provided, this call blocks until the position information is available.
The call returns immediately if a valid callback function is given. This callback function is then
invoked with the specied time interval (in microseconds) in between the invocations. The callback
function is called with the the current position information as parameter.
If partial update is set to 1, the function might return e.g. information about satellites before the
nal location x has been calculated.
For an example of the dictionary returned and the detailed keys, see Section 6.6.1.
stop_position()
Stops an ongoing position request.
6.6.1 Example
The following example (invoked in a Nokia N95 device) demonstrates how to use the Python positioning
module to obtain information about the positioning technologies in the device:
>>> positioning.modules()
[{'available': 0, 'id': 270526873, 'name': u'Bluetooth GPS'}, {'available': 1, '
id': 270526858, 'name': u'Integrated GPS'}, {'available': 1, 'id': 270559509, 'n
ame': u'Network based'}]
>>> positioning.default_module()
270526858
>>> positioning.module_info(270526858)
{'available': 1, 'status': {'data_quality': 3, 'device_status': 7}, 'version': u
'1.00(0)', 'name': u'Integrated GPS', 'position_quality': {'vertical_accuracy':
10.0, 'time_to_first_fix': 1000000L, 'cost': 1, 'time_to_next_fix': 1000000L, 'h
orizontal_accuracy': 10.0, 'power_consumption': 3}, 'technology': 1, 'id': 27052
6858, 'capabilities': 127, 'location': 1}
>>>
The following example demonstrates how to use the Python positioning module.
# information about available positioning modules
print "***available modules***"
print positioning.modules()
print ""
# id of the default positioning module
print "***default module***"
print positioning.default_module()
print ""
# detailed information about the default positioning module
print "***detailed module info***"
print positioning.module_info(positioning.default_module())
print ""
# select a module (in practise, selecting default module has no
# relevance.).
positioning.select_module(positioning.default_module())
# set requestors.
# at least one requestor must be set before requesting the position.
# the last requestor must always be service requestor
# (whether or not there are other requestors).
positioning.set_requestors([{"type":"service",
"format":"application",
"data":"test_app"}])
# Example 1. Blocking call
# get the position.
# note that the first position()-call may take a long time
# (because of gps technology).
print "***position info***"
print positioning.position()
print ""
# re-get the position.
# this call should be much quicker.
# ask also course and satellite information.
print "***course and satellites***"
print positioning.position(course=1,satellites=1)
58 Chapter 6. Audio and Communication Services
print ""
# Example 2. Non-blocking call
def cb(event):
print "---"
print event
print "---"
print "***starts the position feed***"
print positioning.position(course=1,satellites=1,
callback=cb, interval=500000,
partial=0)
An example dictionary returned/printed from the above example script could be as follows:
{'satellites': {'horizontal_dop': 2.34999990463257, 'used_satellites': 5, 'verti
cal_dop': 2.29999995231628, 'time': 1187167353.0, 'satellites': 11, 'time_dop':
1.26999998092651}, 'position': {'latitude': 60.217033666473, 'altitude': 42.0, '
vertical_accuracy': 58.0, 'longitude': 24.878942093007, 'horizontal_accuracy': 4
7.531005859375}, 'course': {'speed': 0.0500000007450581, 'heading': 68.959999084
4727, 'heading_accuracy': 359.989990234375, 'speed_accuracy': NaN}}