Windows Embedded CE / Windows Mobile software package
Version:
for HABI 4.30

Overview

The GPS software delivery for Windows Embedded CE / Windows Mobile based platforms is commonly referred to as HABI. The remainder of the Windows CE specific documentation will mostly refer to the full software delivery with this abbreviated term.

The documentation will generally not make a distinction between Windows Embedded CE and Windows Mobile based platforms unless a particular feature is supported on one particular platform only, in which case it is explicitly noted as such. The abbreviation WinCE will commonly be used to refer to any of the supported platforms.

Target audience

The Overview and Architectural overview sections are suitable for all stakeholders, the remainder of the documentation is targeted at the engineers performing the system integration. The reader is expected to have a good knowledge of Microsoft's tools used in creating operating system images and of the WinCE platforms in general and will not be given instructions that are already provided by Microsoft in their documentation.

Introduction

Due to the standardized nature of components and APIs on the WinCE platforms it is possibly to provide a more integrated solution than is normally possibly for other (proprietary and closed) platforms, where the core libraries are available as static libraries only and more integration work has to be performed by the customer.

Subject to the requirements outlined in HABI Requirements it is possible to very quickly integrate the HABI on the target device, with minimal platform specific work required to optimize the system as a whole.

Supported platforms

All of the following platforms are supported:

  • Windows Embedded CE 6.0
  • Windows Mobile 6 Standard
  • Windows Mobile 6 Professional
  • Windows Mobile 6 Classic
  • Windows CE 5.0
  • Windows Mobile 5.0 for Smartphone
  • Windows Mobile 5.0 for PocketPC Phone Edition
  • Windows Mobile 5.0 for PocketPC
  • Windows Desktop XP/Vista/7 x86/x64

Since the HABI gets built for each customer in order to account for system-specific configuration it is key to provide Broadcom with the necessary information to be able to create a targeted delivery. Refer to section Information required from customer to properly use generic build for details.

HABI features

The HABI is a "drop-in" software suite providing full support of Broadcom's A-GPS chipsets' capabilities for Windows Embedded CE and Windows Mobile powered devices, enabling quick integration. In addition to supporting basic GPS functionality, software for managing the automated retrieval of Express GPS Connect data for enhanced autonomous performance is included and integration into the Windows Mobile help system is provided.

GPS core

The core GPS driver stack is comprised of several components that achieve seamless integration of the host-based architecture A-GPS chipset into WinCE powered platforms. Fully localized configuration software is currently available for Windows Mobile Professional or Classic devices with limited options for OEM-specific customization of product (product name). It is strongly recommended to implement a simple driver (not supplied) for optimizing power-consumption of the system as a whole.

Express GPS Connect

Express GPS Connect is a software utility that downloads GPS assistance data, also referred to as LTO (Long Term Orbit) data. Unlike typical offerings of GPS assistance data, which usually consist of standard ephemeris data and must be refreshed at 4-hour intervals, the assistance data provided is valid for several days, giving users the advantages of Assisted GPS performance while preserving the freedom of autonomous GPS operation.

The Express GPS Connect component will attempt to get the assistance data whenever the device is connected to the Internet via a PC and can also automatically download the data if another transport is available, e.g. GPRS data connection on Smartphone. To ensure optimum GPS performance, the assistance data should be refreshed every few days.

HABI Requirements

The minimal requirements for the GPS core to function properly are as follows (expressed as Sysgen Variables). Note that not all components are listed here, but just the ones commonly missing on created O/S images.

  • C++ exceptions and runtime type information (SYSGEN_CPP_EH_AND_RTTI)
  • basic windowing (SYSGEN_MINGWES)
  • support for services (SYSGEN_SERVICES)
  • (thread-safe) device drivers

If SUPL support is required, basic networking components for the TCP/IP protocol and Winsock support as well as the CryptoAPI and Schannel (SSL/TLS) are needed.

The optional Express GPS Connect component requires the .NET Compact Framework 1.1 SP3 or later to be available on the target platform.

Information required from customer to properly use generic build

For evaluation purposes, a generic WinCE build is available in multiple versions, compiled specifically for one of the Supported platforms. Depending on the typical capabilities of the platform, some features like the control panel applet may not be available. The generic build includes LTO data support in the core driver and the Express GPS Connect component.

As chipset integration for a particular project progresses, a dedicated release may be made available, e.g. to take advantage of customer-specific customizations.

The generic builds must be configured properly in order to be usable on the selected platform, since several assumptions had to be taken. Those assumptions are outlined in the following, also refer to section Configuration.

In particular, please ensure that there are no conflicts with other device names existing on the system!

Platform details
In order to provide a software delivery that is compiled with the appropriate SDK, the exact information of the target platform is required. Also indicate the BSP that is being used as a basis for the system.
LTO data support in core driver

Specify whether you would like to enable support for LTO data in the core gpsct executable. Note that you must obtain the required license for enabling this feature on your platform.

SUPL support in core driver
Specify whether you like to enable SUPL support. The feature can also be locally switched off by changing corresponding registry value. Please refer to SUPL settings in section Configuration
Control panel
A control panel application is available for Windows Mobile based devices (WM6 Standard devices are exluded). Indicate whether you would like to enable support for this component.
ASIC connection type
Specify through which of possible connections the ASIC is connected to the host platform, one of {UART, SPI, I2C}. If it's connected on UART, please indicate the desired baud rate. The generic HABI build comes configured for using UART at 115200baud rate.
GPS COM port
The device name through which communication to the chipset is done. When connected on UART it is usually COMn:, where n is a number in the range [0-9]. Ensure that there is no conflict with other drivers on the platform. If connected on SPI or I2C, it is recommended to use GPS1:. The default device is COM1:.
GPS Control Port
Select the device name that allows to control power gpios to the chipset. Usually GPS2: unless implemented in same driver that is being used for communication to chipset
Virtual COM Port
The name of the (virtual) COM port that applications should open to start using the GPS. Generally this is COMn:, where n is a number in the range [0-9], so general purpose GPS applications will be able to find it. COM8: is the default used for this purpose. For tightly integrated systems, this value can also be set to GPSn:, with GPS8: being a suggested value.
GPS Intermediate Driver
Windows Mobile and Windows Embedded CE 6.0 based systems offer the GPS Intermediate Driver component that enables multiple applications to use GPS Hardware at the same time and offers a simplified API for obtaining position information. Indicate whether you plan on connecting the GPS to the GPSID or not.

Known restrictions

Version 3.98 does not yet fully support power management via controlling gpio device driver. Also, the "single-shot" API available in earlier versions of the HABI has temporarily been disabled.

How to ...?

Architectural overview

GpsCoreArchitecture.png
GPS Core Architecture

Delivery and Installation

Delivery

A HABI release usually is comprised of four or more zip files, zipped into yet another zip file. The files are named according to the following convention, where items in square brackets ([]) are optional and not always there, items in <> are to be replaced with their corresponding value, and platform is a value from the set {WCE60, WM6Std, WM6Pro, WM6Cls, WCE50, PPC2005, SP2005} (platform acronyms are subject to change, but should still be understandable without big leaps of imagination):

  • HABI_[ProjectName_]Platform_<habiReleaseNumber>_ROM_<gllReleaseNumber>[_languages].zip: the actual executables with required registry settings.

E.g. Habi_WCE50_3.98.2936.0_ROM_1.10.13.43256_en.zip for a generic build targetting Windows CE 5.0 Standard SDK.

  • HABI_[ProjectName_]Platform_<habiReleaseNumber>_RN.zip: the release notes for this release.
  • HABI_[ProjectName_]Platform_<habiReleaseNumber>_SYM.zip: the symbol files of executables for debugging purposes
  • HABI_[ProjectName_]Platform_<habiReleaseNumber>_DOCU.zip: Core library and HABI Documentation

Delivery and Installation

The ..._ROM_...zip file contains all the required files for a build with the features selected in Information required from customer to properly use generic build. All files are zipped up with a folder structure that matches their required location on the target device's file system and need to be installed in the corresponding place on the target.

It is expected that recipients of the HABI are knowledgeable in the process of adding additional files and registry settings to an operating system image with Platform Builder. Should this not be the case, please refer to Microsoft's documentation on the subject.

GPS core
  • \Windows\GlvcDriver.dll
  • \Windows\gpsconfig.xml
  • \Windows\Gpsct.exe
  • \Windows\GpsctService.dll
  • \Windows\GpsctServiceLauncher.exe
  • \Windows\GpsNavigationLauncher.exe
  • \Windows\Startup\GpsctServiceLauncher.lnk
Express GPS Connect
  • \Windows\GlGpsCommon.dll
  • \Windows\log4net.dll
  • \Windows\LtoManager.exe
  • \Windows\LtoManager.exe.config
  • \Windows\LtoManagerLauncher.exe
  • \Windows\OpenNETCF.Net_GL.dll
  • \Windows\OpenNetCF.Windows.Forms_GL.dll
  • \Windows\OpenNETCF_GL.dll
Network Initiated SUPL
  • \Windows\SuplInitListener.exe

Also part of the zip file is the file \Windows\GlobalLocate-Gpsct-flatrom.reg. It is not required to copy this file to the target device, but it lists in detail all the required registry settings for the HABI to properly function. The file is in the same format as expected by Microsoft's tools and as such can be #include'd in the target project's project.reg file.

If the Express GPS Connect option was selected, you must ensure that LtoManager.exe is enabled after a hard reset in order to support automatic downloads. To do so, use the "/Install" flag to enable automatic execution of LtoManager.exe (the component responsible for doing the actual download of Express GPS Connect data).

If SUPL is enabled, you would need to install a certificate issued by BRCM for communication with our SUPL server.

Rebuild the O/S image and download to the target device. Assuming all configuration was done properly (see also Information required from customer to properly use generic build) the GPS will be fully functional.

Quick evaluation installation

On many platforms it is possible to do a quick installation for starting evaluation of the chipset's performance. This normally only works on systems where you can connect the ASIC on UART. The quick install is fundamentally the same as the regular install. All the files need to be copied to the correct place and the registry needs to be configured properly. Since the HABI architecture requires the service to be running, you need to manually load the service at this time before being able to use the GPS. This can be achieved by executing the GpsctServiceLauncher.exe. Alternatively, the device should be soft-reset at this point.

Configuration

The configuration of the HABI is split into two parts. Please refer to GL XML Config file description for instructions on how to configure the core GPS library embedded in the Gpsct.exe binary. The remainder of the HABI is configured through the registry, as is common practice on WinCE systems. The documentation below details the various options in the format used by Microsoft's regedit tool. Defaults, when applicable, are denoted between square brackets, i.e. [default value for option].

GPS core configuration options

All the following registry values are relative to the [HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct] registry key:

ValueDescription
"Configuration"="\<config\>" ["HABI"] Selects which platform specific code to load. Do not change unless instructed by Broadcom.
"Job"="\<jobName\>" ["Periodic"] Forces the job (from the gpsconfig.xml file) that should be executed.
"GpsComPort"="\<deviceName\>" ["GPS1:"] The device through which communication to the chipset is done.
"GpsControlPort"="\<deviceName\>" ["none:"] The device that allows to control power to the chipset through custom ioctls.
"NmeaComPort"="\<deviceName\>" ["NAV1:"] The device into thich NMEA data should be streamed. "none:" indicates that no NMEA data should be sent. This may make sense during early integration, when logging of NMEA data into file only is preferred for whatever reason.
"BusType"="\<type\>" ["BUS_UART"] Connection type of chipset. One of {BUS_UART, BUS_SPI, BUS_I2C}
"ThreadPriority"="dword:\<data\>" [00000f8] Thread priority of main GPS processing thread.
"ExitDelay"="dword:\<data\>" [00000bb8] Time before core GPS will be closed after client application stops using it (closing the corresponding virtual COM Port)
"DisableUI"="hex:\<data\>" [00] Disable tray icon from service
"DynamicMode"="dword:\<data\>" [DYN_AUTOMATIC (= 0)] Configure Dynamic Mode to one of the supported values of GL_DYNAMIC_MODE_SETTING.
"SBAS"="dword:\<data\>" [SBAS_DEFAULT (= SBAS_ENABLED_HIGH_PRIORITY)] Configure SBAS setting to one of the supported values of GL_SBAS_SETTING.
"nvRamPath"="\<data\>" [\Application Data\Global Locate\Gpsct\gldata.bin] Don't set this on Desktop Windows. Optional for CE-based devices. If the root directory (such as "\SD Memory") does not exist, default path will apply. Full path name of file where non-volatile information should be stored.
"eeDataPath"="\<data\>" [\Application Data\Global Locate\Gpsct\eeData.bin] Don't set this on Desktop Windows. Optional for CE-based devices. If the root directory (such as "\SD Memory") does not exist, default path will apply. Full path name of file where onboard LTO (extended ephemeris) information should be stored.
"lbsDataPath"="\<data\>" [\Application Data\Global Locate\Gpsct\lbsData.bin] Don't set this on Desktop Windows. Optional for CE-based devices. If the root directory (such as "\SD Memory") does not exist, default path will apply. Full path name of file where LBS information should be stored.
"LowPowerMode"="hex:\<data\>" [00] Enable power saving mode.

Options related to NMEA data sent by Gpsct can be configured under [HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\NMEA]:

ValueDescription
"GsvRate"="dword:\<data\>" [00] Output $GPGSV messages every n seconds (see GlRequest::SetGsvRate)
"GPVTG"="hex:\<data\>" [00] 1: enable $GPVTG output
"GPGLL"="hex:\<data\>" [00] 1: enable $GPGLL output
"CustomVersion"="\<data\>" [""] Appends custom version string to $PGLOR,VER message

More options can be found under [HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\Rtc]:

ValueDescription
"UpdateSystemTime"="hex:\<data\>" [01] The platform's time can be synchronized with the GPS time. A non-zero value enables this feature while 00 disables it.

Furthermore, the GPS core expects to be able to find the installation directory of its files as specified below:

[HKEY_LOCAL_MACHINE\\SOFTWARE\\Apps\\Global Locate Gpsct]
"InstallDir"="<installationPath>" ["\\Windows"]

It is noteworthy to mention that not all files can be copied to a folder other than \Windows. This is due to restrictions of WinCE itself. The files affected are the device drivers, service and control panel (if available for platform), or more concretely GlvcDriver.dll, gpsctService.dll and ltoManagerConfig.dll.

Third-party applications may want to use the current status of the GPS, e.g. for today screen plug-in. This information is available in the registry under [HKEY_LOCAL_MACHINE\System\State\GPS] and can also easily be monitored with the State and Notification Broker of Windows Mobile.

ValueDescription
"GPSRadioState"=dword:<state> [1] The current state of GPS:
  1. GPS is not in use
  2. Transitioning between on and off
  3. On but not not able to determine valid position, i.e. not enough satellites in view.
  4. On and computing position.

Only if the BusType is configured to BUS_UART are the following values under [HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\Uart] relevant:

ValueDescription
"GpsComSpeed"=dword:<baudRate> [0001c200] The baud rate at which communication with ASIC should occur.
"ReadIntervalTimeout"=dword:<data> As documented in MSDN
"ReadTotalTimeoutMultiplier"=dword:<data> [0] As documented in MSDN
"ReadTotalTieoutConstant"=dword:<data> As documented in MSDN
"WriteTotalTimeoutMultiplier"=dword:<data> [0] As documented in MSDN
"WriteTotalTimeoutConstant"=dword:<data> [00000032] As documented in MSDN

There is a set of registry settings that do not normally need to be modified in a customer-specific build. They are driven by the customer provided configuration information and are appropriately set during the build process. Those settings are the configuration of the gpsct service, the public and private side of the virtual COM port. For the generic build it is required that they be configured properly. Anybody with familiarity of driver/service configuration mechanisms in WinCE can easily change the device name to something different, subject to the requirement that the service must have a GPS prefix, while the public virtual COM port's prefix must be either COM or GPS:

[HKEY_LOCAL_MACHINE\Services\GpsctController]
"DLL"="GpsctService.dll"
"Prefix"="GPS"
"FriendlyName"="Global Locate A-GPS task controller"
"Index"=dword:00000000
"Order"=dword:00000009
"Context"=dword:00000000
"Flags"=dword:00000008
@="Global Locate A-GPS Controller"

[HKEY_LOCAL_MACHINE\Drivers\BuiltIn\glvc_pub]
"FriendlyName"="Internal AGPS NMEA"
"DeviceType"=dword:00000000
"Index"=dword:00000008
"Order"=dword:00000002
"Prefix"="COM"
"DLL"="GlvcDriver.dll"

[HKEY_LOCAL_MACHINE\Drivers\BuiltIn\glvc_nav]
"DeviceType"=dword:00000000
"Index"=dword:00000001
"Order"=dword:00000002
"Prefix"="NAV"
"DLL"="GlvcDriver.dll" 

Logging

The information provided herein is confidential and must not be released to end-consumers. The following registry value enable and control the logging functionality for the core GPS software components. The settings below are useful for collecting test data used for analyzing in detail the performance of the GPS system. Whenever the GPS core software is executed log files are placed under the directory specified in the registry. The *-N-*.log file contains the NMEA data stream also output over the virtual COM port, whereas the *-S-*.txt file contains diagnostics from the GPS core executable. A recommended configuration is displayed below.

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct]
"keZPd7Qkka" = <directory where log files are placed, e.g. \Temp\gl-log
"Xan=V5ovMA" = dword:01100001

For gaining better insight into real-world performance without much of the overhead incurred by detailed system logging, set

"Xan=V5ovMA" = dword:00100000

This enables logging of NMEA data only. The registry value Xan=V5ovMA allows to en-/disable the various log subsystems. The value is a bitmask where individual bits are mapped to a subsystem as follows:

0x00000001: core GPS library, with more detailed output configuration options as outlined in GL XML Config file description.

0x00100000: NMEA logged into *-N-*.log file

0x01000000: gpsct, general-purpose within Gpsct.exe

0x02000000: asic_io, details i/o operations with chipset, useful for analyzing communication issues with chipset.

0x04000000: network_io, details i/o operations with network (for SUPL)

In addition, adding "enableWinCeDebugZones" = hex:01 [00] adds streaming of log data to the kernel log, which can be useful, if there are issues writing log files to the file system.

Communications tuning

The UART communication is highly configurable through the registry. There are two modes/strategies to talk with the UART, polling and event-driven (using WaitCommEvent API with EV_RXCHAR). In addition to that fundamental difference in doing the communication, one can configure the thread priority of the reader thread, control timeouts on the loop used to do the reads and all the timeouts defined for serial ports as documented before. See also Microsoft's documentation on the subject. There is an additional mode, normally used when the chipset is connected on either SPI/I2C and a custom driver is needed.

The registry settings involved in selecting the appropriate strategy is detailed below. Be advised that changing the strategy type and its settings alone is not sufficient for switching between event-driven and polling from UART, since the settings for UART itself also need to change.

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\ReadStrategy]:

ValueDescription
"Type"="dword:\<data\>" [1]
0:UART polling mode, runs on dedicated thread.
1:UART event-driven mode, runs on dedicated thread.
2:Event-driven reading from custom driver.

Furthermore, various parameters of the read strategies themselves can be tweaked. The default values are compiled into the Gpsct.exe binary, but can be overridden at any time. Those settings are under an additional registry key found below the ReadStrategy, where the name of key is the type of the read strategy, i.e.

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\ReadStrategy\<strategyType>]:

ValueDescription
"ThreadPriority"="dword:\<data\>" [00000f8] Thread priority of reader thread (if applicable).
"Timeout"="dword:\<data\>" [00000f8] Thread priority of reader thread (if applicable).
"YieldThreshold"="dword:\<data\>" The read strategies will try to read as many bytes from ASIC as possible before passing them to the core library for processing. The value specified here limits this. Note that the thread priorities selected for main thread and reader thread also affect the behaviour at a system level
"EventName"="\<data\>"

Name of event used to signal the availability of data in device driver. Only relevant for read strategy type 2.

Some recommended configurations are listed below as examples. They are good starting points before tweaking the communication with ASIC any further.

UART Polling Mode

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\Uart]
"ReadTotalTimeoutConstant"=dword:00000032
"ReadIntervalTimeout"=dword:00000000
 
[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\ReadStrategy]
"Type"=dword:00000000
 
[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\ReadStrategy\0]
"ThreadPriority"=dword:000000f8
; no timeout on the loop, since we already have a 50ms timeout on the ReadFile, configured in UART section 
"Timeout"=dword:00000000

UART event-driven mode

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\Uart]
"ReadTotalTimeoutConstant"=dword:00000000
"ReadIntervalTimeout"=dword:FFFFFFFF
 
[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\ReadStrategy]
"Type"=dword:00000001
 
[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\ReadStrategy\1]
"ThreadPriority"=dword:000000F8
; no timeout on the loop, since we block on WaitCommEvent 
"Timeout"=dword:00000000

SUPL settings

Following are the registry values when SUPL features are build in the release package.

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\Supl]:

ValueDescription
"EnableSupl"="hex:\<data\>" [01] A non-zero value enables this feature while 00 disables it.
"EnableTLS"="hex:\<data\>" [00] Secure socket connection (TLS) with server is enabled or not. A non-zero value enables this feature while 0 disables it.
"macap"="hex:\<data\>" [01] Enabling MS-Assisted capability or not. A non-zero value enables this feature while 0 disables it.
"mbcap"="hex:\<data\>" [01] Enabling MS-Based capability or not. A non-zero value enables this feature while 0 disables it.
"ecidcap"="hex:\<data\>" [00] Enabling enhanced cell ID capability or not. A non-zero value enables this feature while 0 disables it.
"PositionRequestAction"="\<data\>" [1] The action to take when NI request is received. 1: allow positioning request; 2: deny positioning request.
"SUPL Version"="\<data\>" [3]

There are also two optional registry entries to set SUPL server address and port. If these keys are not in the registry, default server and port as shown below would be applied.

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct\Supl]:

ValueDescription
"host"="\<data\>" [66.35.208.225] The ip of SUPL server. Default BRCM SUPL server is "66.35.208.225" if TLS is not applied. Default BRCM SUPL server when TLS communication is enabled is "66.35.208.226". Note: if EnableTLS is 1, and "host" registry key is present also not the default server, please make sure that the specified server supports TLS connection.
"port"="dword:\<data\>" [00001C6B] Port number of SUPL server for connection. Default BRCM SUPL server port is 7275.

For network-initiated SUPL request, wap-push feature on the device has to be properly configured in order to make it work. The following are the registries to be imported.


[HKEY_LOCAL_MACHINE\Security\PushRouter\Registrations\ByCTAndAppId\;x-oma-application:ulp.ua]
@="GL3"

[HKEY_LOCAL_MACHINE\Security\PushRouter\Registrations\ByGenericId\GL3]
"QueueId"=dword:00000001
"Trust"=dword:00000002
"RefCount"=dword:00000001
"AppId"="x-oma-application:ulp.ua"
"GenId"="GL3"
"Path"="SuplInitListener.exe"
"ContentTypes"=""
"Params"="/wap_supl"

[HKEY_LOCAL_MACHINE\Software\Microsoft\Shell\Event\Network\WDP\7275\SuplInitListener]
"NotifyOnLaunch"=dword:00000001
"Command"="SuplInitListener.exe"
"Class"="SuplInitListener"
"7275"=dword:00008001

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\SuplInitListener]
"DestroyTimer"=dword:00002710
"PeriodicTimer"=dword:000003e8

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\SuplInitListener\32769]
"WDP timeout"=dword:00002710
"WDP Port"=dword:00001c6b

Preloading the GPS ahead of navigation application

At times it can be useful to preload the GPS software stack prior to executing the target navigation application. This is particularly applicable if that software is written in a way where e.g. it opens the GPS' assigned COM port only after loading all the UI and maps, which is commonly a time-consuming task. While the maps and UI are loaded by the navigation software, the GPS could already be acquiring position, so it will be available faster when the navigation app can make use of it.

To achieve this, configure the path of target navigation app in the registry and execute GpsNavigationLauncher.exe instead of the actual navigation app.

[HKEY_LOCAL_MACHINE\SOFTWARE\Global Locate\Gpsct]
"3rdPartyGpsApp" = "<full path to navigation application>

Explain the available read strategies and when a particular one should be used.

Interpreting log files

Detailed analysis should be left to Broadcom staff, however some simple analysis can be performed by anybody. ...

Supporting Factory Testing

The Factory Test page spells out the generically applicable considerations for factory testing and how to configure the factory test options. The following paragraph provides information specific to HABI.

The Gpsct.exe supports command line arguments that make it easy to programmatically execute the factory tests (or any other job) defined in the XML configuration file with the built-in batch request manager (BRM).

Gpsct.exe <path to gpsconfig.xml> <batch job>

In order to perform the factory tests the test application first executes \Windows\Gpsct.exe \Windows\gpsconfig.xml Factory_High_SNR and then opens the virtual COM port to receive the NMEA data stream containing the proprietary $PGLOR,0,FTS - Factory Test Status NMEA message, which it can then parse and use for pass/fail decisions.

Besides the NMEA file, the following information is also available in the registry under [HKEY_LOCAL_MACHINE\System\State\GPS] and can easily be monitored with the State and Notification Broker of Windows Mobile.

ValueDescription
"LastCN0Estimate"=dword:<value> Last observed estimation of the C/No [dB Hz]
"AverageCN0Estimate"=dword:<value> Average estimation of the C/No [dB Hz]
"CWSignalStrength"=dword:<value> Signal strength in CW test mode [-dBm]

The duration of the factory test is configured in the xml file and the Gpsct.exe will stop after this job is finished. The test application can either wait on the process handle of Gpsct.exe to determine when the test is finished or interpret the absence of further NMEA message in the same way. Note that the order of first executing Gpsct.exe followed by opening the virtual COM port should not be changed.

For more thorough testing, the Factory_Low_SNR test can be performed after the Factory_High_SNR test.

Sending Custom Commands

Custom commands can be sent via the NMEA interface as specified by the registry HKEY_LOCAL_MACHINE\Drivers\BuiltIn\glvc_pub\ (only virtual COM port is currently supported). This is the same port that the application reads NMEA lines, which can be used to write commands to control how the GPS "Periodic" request can be (re)started. The following custom commands are supported.

CommandDescription
$PBCM,HOT Hot start, nothing is ignored
$PBCM,WARM Warn start, ignore ephemeris
$PBCM,COLD Cold start, ignore ephemeris, position and time
$PBCM,FACTORY_COLD Factory cold start, ignore ephemeris, position, oscillator, ROM almanac, almanac and time
$PBCM,DYNAMIC_MODE,PEDESTRIAN dynamicMode = DYN_PEDESTRIAN
$PBCM,DYNAMIC_MODE,VEHICLE dynamicMode = DYN_VEHICLE
$PBCM,SBAS,ON sBas = SBAS_DEFAULT
$PBCM,SBAS,OFF sBas = SBAS_DISABLED
$PBCM,RESET Reset to default: nothing is ignored, sBas = SBAS_DEFAULT, dynamicMode = DYN_AUTOMATIC

Sending Interactive Commands

Windows Desktop

Installation

The entire software package is installed by running the MSI installer. All the (executable and configuration) files and registry entries will be setup properly. See How.to.install.pdf from the release package for more details.

Program Data

The program data such as lto.dat and gldata.bin are configured as follows.

Windows OSPath
XP \Documents and Settings\All Users\Application Data\Global Locate\Gpsct
Vista/7 \ProgramData\Global Locate\gpsct

Desktop Specific Features and Behavior

One major difference in the desktop version is that the GPS manager service launches Gpsct.exe. The reason is that it is simpler to support the auto-start feature, since the GLL already manages multiple requests and the service does not have to manage it again. This also promotes the loose coupling design paradigm since there is only a one-way communication from service and/or CommandIntf.dll to Gpsct.exe.

There are two ways to start GPS "Periodic" request

  • Indirect NMEA delivery
    • User application opens the virtual COM (such as the Skyhook XPS) to read NMEA, XPS sends GPS start request via CommandInft.dll.
  • Direct NMEA delivery (filter driver required, sensor driver optional)
    • User application opens the "Broadcom GPS NMEA Port" to read NMEA, the service detects the port being opened and sends start request.
FilterMon.png
Filter Driver Monitored by Service (GpsMgr.exe)

The filter driver support pass-through mode when the Service is stopped.

FilterPassThru.png
Filter Driver Pass-Through (Service Stopped)

Troubleshooting

How to deal with "frozen" device?

During early integration it can happen that the device appears to freeze when the gpsct.exe is executing. The most likely reason for this is a buggy device driver where the HABI ends up busy-looping. Try increasing the thread priorities of gps core and reader thread to a value >= 251. This way you should still be able to interact with the device and copy the log files.

Integration and system performance tests

Common metrics used in assessing overall GPS system performance are time to first fix (TTFF) for "cold", "warm" and "hot" starts and the accuracy of the computed fixes. You can run those tests in automated fashion by configuring the HABI's job to auton-start and manually executing the Gpsct.exe by tapping on it in File Explorer. You can change the number of repeated tests to perform by changing the corresponding section in the gpsconfig.xml file. The results can be deduced by analyzing the regular logging data files (*N-*.log) in the chosen logging directory. If any one test in the batch fails, it will be noted in the *-S-*.txt file and the remaining tests may be aborted.

Before running these automated tests, it is recommended to first run a preliminary platform test as outlined in GL GPS Integration verification.

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines