Gobi 3000 SDK

For Notebook OEM

Software Integration Guide

Revision:

Draft G

2003-2010 Sierra Wireless, Inc.

This document contains information which is proprietary and confidential to Sierra
Wireless, Inc. Disclosure to persons other than the officers, employees, agents, or
subcontractors of the Company or licensee of this document without the prior written
permission of Sierra Wireless, Inc. is strictly prohibited.
QUALCOMM is a registered trademark of QUALCOMM Incorporated. Other product
and brand names may be trademarks or registered trademarks of their respective owners.
CDMA2000 is a registered certification mark of the Telecommunications Industry
Association, used under license.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 2 of 15

Table of Contents
1

General ..................................................................................................... 3
1.1
1.2
1.3
1.4
1.5

Purpose ............................................................................................................... 3
Scope ................................................................................................................... 3
Revision History .................................................................................................. 3
References ........................................................................................................... 3
Terminology and Acronyms ................................................................................ 4

Overview .................................................................................................. 5
2.1
System Requirements .......................................................................................... 5
2.2
SDK Installation.................................................................................................. 5
2.3
Folder Structure .................................................................................................. 5
2.3.1
Documents .................................................................................................. 5
2.3.2
Drivers......................................................................................................... 5
2.3.3
GobiConnectionMgmt ................................................................................ 6
2.3.4
GobiApi....................................................................................................... 6
2.3.5
GobiDiagnostics .......................................................................................... 6
2.3.6
GobiImageMgmt ......................................................................................... 6
2.3.7
GobiSampleCM .......................................................................................... 7
2.3.8
SimpleCM ................................................................................................... 7
2.3.9
SmsSample.................................................................................................. 7
2.3.10
WMCQG3 ................................................................................................... 7
2.4
Platform Integration ........................................................................................... 7
2.4.1
Gobi Vendor Libraries ................................................................................ 8
2.4.2
Gobi Firmware Downloader ....................................................................... 8
2.4.3
Firmware Images ........................................................................................ 8
2.4.4
API Libraries and Applications .................................................................. 9

Driver Installer ....................................................................................... 10

3.1
3.2

Drivers .................................................................................................... 12
4.1

Configuration file .............................................................................................. 10

Command Line Options .................................................................................... 10
Selective Suspend .............................................................................................. 12

GobiApi .................................................................................................. 13
5.1
Multiple Client Support..................................................................................... 13
5.2
Threading Model ............................................................................................... 13
5.2.1
Notification Callback Handling ................................................................ 13

Logging .................................................................................................. 14
6.1

SwiDiagUtil....................................................................................................... 14

Known Issues ......................................................................................... 15

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Revision:

Document #:

Draft G

Page 3 of 15

1 General
1.1 Purpose
This document contains a collection of references and development notes to aid in the
software integration of Sierra Wireless Gobi 3000 modules on Microsoft Windows
operating systems for notebook platforms. OEMs and third party application developers
are the intended audience of this document.
1.2 Scope
This document only pertains to software integration on Microsoft Windows notebook
operation systems. Gobi Application Programming Interface (API) and driver design and
usage are discussed. Hardware integration and other operation systems are not covered in
this document.
1.3 Revision History
Revision
Date
Draft A
2010-08-06
Draft B
2010-08-26
Draft C
2010-09-09
Draft D
Draft E
Draft F

2010-09-14
2010-09-17
2010-10-22

Draft G

2010-11-12

Summary
Initial draft
Updated driver details
Removed references to obsolete Gobi 2000
documents. Updated for Qualcomm 0.0.30 SDK
baseline.
Updated platform integration section. Updated driver
installer command line options.
Title change
Updated package folder structure. Updated driver
installer command line options and driver file name
description. Added configuration file description.
Added GPS command line option, updated installation
path

1.4 References
The following table lists useful Qualcomm references for SDK integrators. Contact your
Sierra Wireless representative for a copy of the references; they are not included in the
Sierra Wireless Gobi WinCE SDK. Some are available for download from
www.gobianywhere.com.
ID
80-VF219-N

Title
Qualcomm Connection
Management API for Gobi3000

Comments
Interface specification and
operational description for

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Revision:

Document #:

Draft G

Module
80-VF219-N

Qualcomm Image Management

API for Gobi3000 Module

80-VR668-1
CL93-V3077-1

Gobi Connection Manager

Application Note: Software
Glossary for Customers

Page 4 of 15

connection management
functionality
Interface specification and
operational description for image
management
Connection manager FAQ
A list of acronyms and their
definitions compiled by
Qualcomm

1.5 Terminology and Acronyms

See CL93-V3077-1 for a complete list of acronyms and definitions from Qualcomm.
Term

Definition

API

Application Programming Interface

ODM

Original device Manufacturer

OEM

Original equipment manufacturer

QMI

Qualcomm Modem Interface; Qualcomm MSM Interface

SDK

Software Development Kit

SMS

Short message service

WDF

Windows Driver Foundation

MB

Mobile Broadband

WMC

Wireless Modem Control

HDD

Hard Disk Drive

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 5 of 15

2 Overview
2.1

System Requirements

The following operation systems are supported:

Microsoft Windows XP SP2 or later
Microsoft Windows Vista SP1 or later (32 and 64 bit)
Microsoft Windows 7 (32 and 64 bit)
Sample applications are produced using Visual Studio 2005 along with SP1.
2.2

SDK Installation

The SDK is packaged as a compressed ZIP file and can be uncompressed using the standard
extractor included with Windows.
The SDK package includes firmware images. See release notes for version of firmware included
with each SDK package. Firmware images are automatically copied to the required location (see
section 2.4.3).

2.3

Folder Structure

2.3.1 Documents
This folder contains API documentation and integration guides.
The following is a list of key components included in this folder:
Component
Description
GobiConnectionMgmtAPI.pdf Connection management API
GobiImageMgmtAPI.pdf
Image management API
GobiDiagnosticsAPI.pdf
Diagnostic API
Gobi 3000 SDK for HP.pdf
Integration notes
2.3.2 Drivers
This folder contains the driver installer, binaries, and INF files.
The following is a list of key components included in this folder:
Component
Description
swg3kmbbXX.sys
Windows 7 mobile broadband network interface driver
swg3knetXX.sys
Network interface driver
swg3kserialXX.sys
Serial interface driver
swibusXX.sys
Sierra Wireless USB driver
2003-2010 Sierra Wireless, Inc.
The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Revision:

Document #:
swg3knmeaXX.sys
swg3klocXX.sys
LocationHelper.dll

Draft G

Page 6 of 15

NMEA driver
Windows 7 location sensor driver
Location helper API

Where XX is a number from 00 - 99.

2.3.3 GobiConnectionMgmt
This folder contains WWAN connection manager APIs.
The following is a list of key components included in this folder:
Component
Description
GobiConnectionMgmtAPI.h Connection manager API definitions
GobiConnectionMgmt.dll
Implements connection manager APIs
2.3.4 GobiApi
This folder contains the Sierra Wireless value-added APIs.
The following is a list of key components included in this folder:
Component
Description
QCWWANCMAPI2k.h
Qualcomm wireless WWAN connection manager API for
Gobi 2000 (obsolete)
SwiWwanCmApi.h
Sierra Wireless API extensions for Gobi 3000
GobiApi.dll
Implements Sierra Wireless specific API extensions and
WWAN connection manager APIs.
2.3.5 GobiDiagnostics
This folder contains diagnostic APIs.
The following is a list of key components included in this folder:
Component
Description
GobiDiagnosticsAPI.h
Diagnostic API definitions
GobiDiagnostics.dll
Implements diagnostic APIs
2.3.6 GobiImageMgmt
This folder contains image management APIs.
The following is a list of key components included in this folder:
Component
Description
GobiImageMgmtAPI.h
Image management API
GobiImageMgmt.dll
Implements image management APIs

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 7 of 15

2.3.7 GobiSampleCM
This folder contains source code for a sample connection manager. Carrier selection,
data connection functionality, notification callback handling, and device detection are
demonstrated.
GobiSampleCM invokes API calls from GobiConnectionMgmt.dll.
GobiSampleCM relies on UMTSCarrier.txt to map APN/Username/Password
information for each carrier. When using the generic UMTS firmware image, the
UMTSCarrier.txt file must be updated with the appropriate APN/Username/Password
information for carrier index 1.
2.3.8 SimpleCM
This folder contains source code for a sample connection manager. Basic data
connection functionality, notification callback handling, and device detection are
demonstrated.
SimpleCM currently uses GobiApi.dll but can be modified to use
GobiConnectionMgmt.dll.
2.3.9 SmsSample
This folder contains source code for an SMS sample application which utilizes Sierra
Wireless SMS helper functions. SMS send, receive and handling of concatenated
messages are demonstrated.
SMS helper functions are implemented in GobiApi.dll.
2.3.10 WMCQG3
This folder contains WMC APIs.
The following is a list of key components included in this folder:
Component
Description
WMCQG3.dll
Implements WMC APIs
2.4 Platform Integration
There are interdependencies between the multiple components of this package. The driver
installation package will copy components to the required locations to fulfill these
dependencies. For reference, the dependencies are described; manual interaction is not
required.
All the Gobi files are placed in the 32-bit Program Files directory:

On 32-bit systems this is %PROGRAMFILES%, e.g., C:\Program Files\

On 64-bit systems this is %PROGRAMFILES(x86)%, e.g., C:\Program Files (x86)\

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Revision:

Document #:

Draft G

Page 8 of 15

2.4.1 Gobi Vendor Libraries

The x86 and x64 versions of the Gobi Vendor Libraries are placed in the following
locations:

<ProgramFiles>\Sierra Wireless Inc\Gobi\Manufacturers\x86\

<ProgramFiles>\Sierra Wireless Inc\Gobi\Manufacturers\x64\

These binaries support nOEM specific customizations such as VID/PID assignments.

2.4.2 Gobi Firmware Downloader
The Gobi Firmware Downloader is placed in the following location:

<ProgramFiles>\Sierra Wireless Inc\Gobi\QDLService\GobiQDLService.exe

The following command line options (case sensitive) are supported and automatically
invoked by the driver installer:

-i
-s
-e
-u

:
:
:
:

install
start service
stop service
uninstall service

2.4.3 Firmware Images

Firmware images are currently placed in subfolders at the following location:

<ProgramFiles>\Sierra Wireless Inc\Gobi\Images\3000\Generic\

NOTE: This path is subject to change in a future release. Applications should not hard
code this path but instead use the GetImageStore API to retrieve the firmware image path
supported by the SDK.
Firmware images are placed in the following folder structure:
Folder

Mobile Operator

Vodafone

Verizon

AT&T

Sprint

T-Mobile

Generic EU

Telefonica

Telecom Italia

Orange

14

AMX/Telcel

16

OMH

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 9 of 15

2.4.4 API Libraries and Applications

API libraries and applications, such as GobiConnectionMgmt.dll and
GobiSampleCM.exe, can be placed in any location. Note that GobiSampleCM.exe
require GobiConnectionMgmt.dll be in the same directory.

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Revision:

Document #:

Draft G

Page 10 of 15

3 Driver Installer
The driver installer supports the following features:
Capable of install/uninstall when another installer setup.exe or MSI is currently
running
Uninstaller in Add / Remove program
Selective suspend (enabled by default)
Microsoft Windows 7 Mobile Broadband (enabled by default)
3.1 Configuration file
If configuration.ini file is present in the same directory as the installer, the default
installer behaviour is overridden with the values specified in the configuration file. The
following features are currently supported by the configuration file:
Logging
Quiet
Selective suspend
Microsoft Windows 7 MB
Location Sensor Driver
Default image
Carrier images
GPS
3.2 Command Line Options
Command line options will override both the default installer behaviour.
Currently supported command line options:
Feature
Option
Install
/i
Uninstall
/x
Logging
LOG=<value>

Quiet

SILENT=<value>

Selective
Suspend
Microsoft
Windows 7 MB
Location Sensor

SS=<value>
WIN7DRIVER=<value>
LOCATIONDRIVER=<value>

Description
Install drivers
Uninstall drivers
0 disable logging
1 enable logging
Log file is saved under
%APPDATA%\Sierra
Wireless\Logs
0 No user interface
1- User interface shown
0 disable
1 enable
0 disable
1 enable
0 disable

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Revision:

Document #:

Draft G

Page 11 of 15

Driver
Default Carrier
Image
Carrier Images

1 enable
DEFAULTIMAGE=<CarrierID> See 2.4.3 for CarrierID numbers

GPS

GPS=<value>

CARRIER<CarrierID>=<value>

See 2.4.3 for CarrierID numbers.

0 image is not copied to HDD
1 image is copied to HDD
0 Disable GPS
1 Enable GPS

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 12 of 15

4 Drivers
4.1 Selective Suspend
Selective suspend is enabled by default. Use the following registry key to configure
selective suspend functionality:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\swibus\Parameters]
"IdleTimeout"=dword:3
IdleTimeout is the timeout value in seconds. For example, setting IdleTimeout to
dword:3 will enable selective suspend functionality with a timeout of 3 seconds.
The minimum value for IdleTimeout is 3 seconds. If the IdleTimeout value is set to
less than 3 seconds, the driver will force it to 3 seconds. Similarly, IdleTimeout = 0
will default to the minimum 3 second value.
To disable selective suspend, the IdleTimeout key must be deleted.

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 13 of 15

5 GobiApi
5.1 Multiple Client Support
GobiApi supports simultaneous usage by multiple applications (processes). Each
application must initialize an instance of GobiApi DLL via procedures outlined in
document 80-VF219-N. Multiplexing of application requests are handled by the driver.
5.2 Threading Model
GobiApi can process API requests from multiple threads simultaneously. The order of
requests processed is NOT deterministic.
5.2.1 Notification Callback Handling
To receive unsolicited notifications, client applications must register callbacks with
GobiApi. Callbacks are then invoked by a thread created and maintained by GobiApi.
The same thread used to invoke callbacks is also responsible for processing all modem
responses. Therefore, it is imperative that client applications release control of the
callback thread immediately to avoid causing timeout errors for other threads invoking
API functionality.
The following is the recommended procedure to handle callbacks:
1. Callback handler invoked by GobiApi DLL thread
2. In the callback handler, cache a copy of relevant information provided by the
callback interface
3. Notify main application thread that notification has been received
4. Return from callback handler to release control of GobiApi callback thread
5. Process notification in main application thread
API calls invoked within the context of an API callback thread will be rejected (see
SwiWwanCmApi.h for more information).
See SimpleCM for an example on handling notifications.

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 14 of 15

6 Logging
6.1 SwiDiagUtil
SwiDiagUtil is a log collection tool developed by Sierra Wireless to capture detailed
operation system, application, and driver logs required to troubleshoot host related issues.
When submitting a troubleshooting request, please provide logs captured using
SwiDiagUtil to expedite the service request.
Please contact your Sierra Wireless representative for a copy of SwiDiagUtil.

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.

SIERRA WIRELESS, INC.

Document #:

Revision:

Draft G

Page 15 of 15

7 Known Issues

2003-2010 Sierra Wireless, Inc.

The contents of this page are subject to the confidentiality information on page one.