Symbian3/PDK/Source/GUID-E73A181C-0C9B-513C-ABAE-585C80D566DF.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Thu, 11 Mar 2010 18:02:22 +0000
changeset 3 46218c8b8afa
parent 1 25a17d01db0c
child 5 f345bda72bc4
permissions -rw-r--r--
week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     6
<!-- Initial Contributors:
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     7
    Nokia Corporation - initial contribution.
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     8
Contributors: 
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
     9
-->
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    10
<!DOCTYPE concept
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    12
<concept xml:lang="en" id="GUID-E73A181C-0C9B-513C-ABAE-585C80D566DF"><title>Bluetooth GPS PSY Overview</title><shortdesc>This describes the Bluetooth GPS PSY, which connects the Location Server (<codeph>eposserver.exe</codeph>) to external Bluetooth GPS devices. The audience is device creators and developers who want to integrate the Bluetooth GPS PSY into their products. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>The Bluetooth GPS PSY is used by the Location Server (<codeph>eposserver.exe</codeph>) to obtain position fixes from external Bluetooth GPS devices. The PSY uses the Bluetooth APIs to pair with an external Bluetooth GPS device. The PSY obtains position fixes from the Bluetooth GPS device. If the Bluetooth GPS PSY is installed, a mobile device without an internal GPS chipset can obtain GPS position fixes from external Bluetooth GPS hardware. </p> </section> <section><title>Required background </title> <p>A knowledge of the material covered in the following is useful to understanding how this component fits into the LBS architecture: </p> <ul><li id="GUID-6280ECC6-A9DA-5C68-8646-9F4DF4C2E76B"><p><xref href="GUID-7233BC33-6060-5D6B-A5D2-01135F059337.dita">LBS Architecture Overview</xref>  </p> </li> <li id="GUID-619A1ABD-19E9-5955-BE5D-F2ACBB700E7D"><p><xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS Integration and Configuration Guide</xref>  </p> </li> </ul> </section> <section><title>Key concepts and terms</title> <dl><dlentry><dt>Bluetooth</dt> <dd><p>A wireless protocol for data exchange over small distances. </p> </dd> </dlentry> <dlentry><dt>PSY</dt> <dd><p>A Positioning Plug-in. The Bluetooth GPS PSY implements the Positioning Plug-in API to interface with the Location Server. It uses the Positioning Plug-in Information API to register itself with the Location Server. </p> </dd> </dlentry> <dlentry><dt>NMEA</dt> <dd><p>In this context, an abbreviation of the NMEA (National Maritime Electronics Association) 0183 standard. This defines an electrical and data exchange protocol for marine electronic devices (including GPS receivers). The Bluetooth GPS PSY supports devices that use the NMEA 0183 standard and also devices that support PNOK NMEA extensions. </p> </dd> </dlentry> <dlentry><dt>PNOK</dt> <dd><p>Nokia proprietary extension to the NMEA 0183 standard. It defines additional messages that give extra information about the status of a Bluetooth GPS device that supports PNOK. The Bluetooth GPS PSY supports PNOK. </p> </dd> </dlentry> <dlentry><dt>RFCOMM</dt> <dd><p>A Bluetooth protocol that provides simulated serial communications over a wireless connection. It is used by the Bluetooth stack to support data exchange with the Bluetooth GPS device on behalf of the Bluetooth GPS PSY. </p> </dd> </dlentry> </dl> </section> <section><title>Architecture</title> <p>Figure 1 shows the Bluetooth GPS PSY component with associated LBS components. </p> <fig id="GUID-32FFD99F-B574-5730-9152-FA33D4FE6647"><title>
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    13
             Figure 1. Bluetooth GPS PSY and related components. 
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    14
          </title> <image href="GUID-9C2421E6-FA53-5E3C-B073-57FB9F3591DD_d0e449075_href.png" placement="inline"/></fig> <p>The Bluetooth GPS PSY implements the Positioning Plug-in API. It also uses the Positioning Plug-in Information API to register itself with the LBS subsystem. The PSY provides three APIs (described in more detail later in this document). </p> <p>The PSY uses the Bluetooth APIs to pair with a Bluetooth GPS device. Bluetooth uses the RFCOMM protocols to connect with the Bluetooth GPS device. </p> <p><b>Supported features</b> </p> <p>The Bluetooth GPS PSY provides the following features: </p> <ul><li id="GUID-3B7B0DF4-623D-52EE-A22F-CEA3961ECF67"><p>Support for devices that use the NMEA 0183 protocol. </p> <p>A Bluetooth device must support NMEA 0183 to be compatible with the Bluetooth GPS PSY. </p> </li> <li id="GUID-3928BB6F-D157-5C0D-A2E8-9D1FFE3EF53B"><p>Support for devices that implement the PNOK NMEA 0183 extensions. </p> <p>These proprietary extensions support additional information about the paired Bluetooth GPS device. </p> </li> <li id="GUID-21F6D346-9374-54F8-8F94-0886BDEE84F4"><p>Support for multiple simultaneous client requests for position fixes. </p> <p>The PSY uses the target time specified as part of the client request to decide if multiple client requests can be bundled into a single request to the Bluetooth subsystem. Bundling requests improves efficiency and reduces the power requirements of using an external Bluetooth GPS device. </p> </li> <li id="GUID-F7E4E357-4052-53C0-82D5-CA89156F92F6"><p>Support for tracking. </p> <p>Tracking is the process of returning periodic position updates with a constant time interval between them. This feature is typically used by navigation applications. </p> </li> <li id="GUID-7A83C4AE-4090-5B89-B11E-A1A5EE5C28B2"><p>Support for multiple Bluetooth GPS devices. </p> <p>The Bluetooth protocols can discover more than one Bluetooth GPS device (for example a mobile phone may be able to connect with both a standalone Bluetooth GPS device and an in-car device). </p> <p>It is useful to be able to try to connect to more than one Bluetooth GPS device. One example use-case is when the mobile device is used for in-car navigation. GPS reception may be limited inside a vehicle, but there may be access to an in-car Bluetooth GPS device with an external aerial. The Bluetooth protocols can discover all available Bluetooth GPS devices and ask the user which one to pair with their mobile. The PSY then connects to the chosen Bluetooth GPS device. </p> <p>It is not necessary for a user to follow this manual pairing procedure each time LBS decides it needs to use a Bluetooth GPS device. The PSY maintains its own ordered list of Bluetooth GPS devices. It tries to connect to each of the devices in succession and pairs with the first device to which it can successfully connect. The details of this device are stored by the PSY and are automatically used the next time the mobile must be paired with Bluetooth GPS hardware. Note that the PSY can only be paired with one Bluetooth GPS device at any time. </p> </li> </ul> <p><b>PSY libraries and installation</b> </p> <p>Most of the Bluetooth GPS PSY is packaged in <filepath>nlabtgpspsy.dll</filepath>. The Bluetooth GPS PSY Configuration API (see below) is packaged as a separate library <filepath>lbsbtgpsconfig.dll</filepath>. </p> <p>The PSY can be installed in one of two ways: </p> <ul><li id="GUID-DAFBC288-94A4-5C15-892E-EE7F790940D2"><p>By a device creator at ROM build time by using a ROM build macro. </p> </li> <li id="GUID-A27C38E7-1280-5AC8-B5DA-5E0F639D1C94"><p>In a SIS file, which can be installed by the mobile device user. </p> </li> </ul> <p>See <xref href="GUID-90D938EA-E46A-512A-85E3-B8ADF81BC4D3.dita">Bluetooth GPS PSY Tutorial</xref> for more information about these installation options. </p> </section> <section><title>APIs</title> <p>The Bluetooth GPS PSY provides three APIs: </p> <ul><li id="GUID-1EA3EFF4-51B8-5A98-BD5C-9657ED9CBF93"><p><xref href="GUID-F84E7419-7F31-5E18-8854-27CB1F9F890E.dita">Bluetooth GPS PSY Settings Storage API</xref>  </p> <p>A client can use this API to get the properties of the Bluetooth GPS device paired with the Bluetooth GPS PSY. If the device supports PNOK, some properties can also be set. </p> <p>A client is typically a Bluetooth GPS settings application developed by a device creator. </p> </li> <li id="GUID-BAD8578D-A2D7-5BDE-938E-AF8ABB3E9288"><p><xref href="GUID-1D81831A-FFC9-50E7-9FA1-EC0958060588.dita">Bluetooth GPS PSY Events API</xref>  </p> <p>A client can use this API to get information about the paired Bluetooth GPS device. If the device supports PNOK, the client can subscribe for notification of some Bluetooth device events (such as device status changes). </p> <p>A client is typically a UI component, such as a notifier, that informs a user of Bluetooth GPS device events. </p> </li> <li id="GUID-A482EAF9-B74B-5A95-84F3-45B222B459CC"><p><xref href="GUID-2A137918-D949-5017-BB00-B93CFA8AA65F.dita">Bluetooth GPS PSY Configuration API</xref>  </p> <p>This API allows a user to manage an ordered list of Bluetooth GPS device details. The PSY tries to connect with each of the devices in the list in succession and stops when it is successful. </p> </li> </ul> </section> <section><title>Typical uses</title> <p>The PSY can be used to obtain a location fix one of two ways: </p> <ul><li id="GUID-7796E32E-163C-59D8-A874-77915806FE2D"><p>A Location Acquisition API client can select the PSY by default by opening a session with the Default PSY. The Default PSY always tries to use the Bluetooth GPS PSY first to obtain a location fix, and then tries to use other PSYs if the Bluetooth GPS PSY cannot provide a position fix. </p> </li> <li id="GUID-926342AB-70E0-510E-84D7-F298EC83D84E"><p>A Location Acquisition API client can select the PSY explicitly by opening a session with the Location Server. The client application must specify the implementation UID of the Bluetooth GPS PSY (<codeph>0x101FE999</codeph>). </p> </li> </ul> <p>The PSY can also report the status of a Bluetooth GPS device through the Bluetooth GPS PSY Events API. </p> </section> </conbody><related-links><link href="GUID-90D938EA-E46A-512A-85E3-B8ADF81BC4D3.dita"><linktext>Bluetooth GPS PSY
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    15
                Tutorial</linktext> </link> <link href="GUID-F84E7419-7F31-5E18-8854-27CB1F9F890E.dita"><linktext>Bluetooth
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    16
                GPS PSY Settings Storage API</linktext> </link> <link href="GUID-1D81831A-FFC9-50E7-9FA1-EC0958060588.dita"><linktext>Bluetooth
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    17
                GPS PSY Events API</linktext> </link> <link href="GUID-2A137918-D949-5017-BB00-B93CFA8AA65F.dita"><linktext>Bluetooth
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    18
                GPS PSY Configuration API</linktext> </link> <link href="GUID-CD8BF818-ED63-5504-8382-346776D3B78F.dita"><linktext>Bluetooth GPS
46218c8b8afa week 10 bug fix submission (SF PDK version): Bug 1892, Bug 1897, Bug 1319. Also 3 or 4 documents were found to contain code blocks with SFL, which has been fixed. Partial fix for broken links, links to Forum Nokia, and the 'Symbian platform' terminology issues.
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents: 1
diff changeset
    19
                PSY Reference</linktext> </link> <link href="GUID-7CE5CF4C-7661-5FE1-87CA-CC4EB1CECE34.dita"><linktext>Default
1
25a17d01db0c Addition of the PDK content and example code for Documentation_content according to Feature bug 1607 and bug 1608
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    20
                Positioning Module</linktext> </link> <link href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita"><linktext>Location Acquisition API</linktext> </link> </related-links></concept>