2170012_Software Integration Application Notes for Sprint OMA-DM_rev2

2170012 Rev 2

Proprietary and Confidential

Mini Card Software Integration Application Notes for Sprint OMA-DM

Sof tware In tegrat ion Appl icat ion Notes fo r Spr in t OMA-DM

2 Propr ie ta ry and conf iden t ia l 2170012

Preface Limitation of liability The information in this manual is subject to change without notice and does not represent a commitment on the part of Sierra Wireless. SIERRA WIRELESS AND ITS AFFILIATES SPECIFICALLY DISCLAIM LIABILITY FOR ANY AND ALL DIRECT, INDIRECT, SPECIAL, GENERAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES INCLUDING, BUT NOT LIMITED TO, LOSS OF PROFITS OR REVENUE OR ANTICIPATED PROFITS OR REVENUE ARISING OUT OF THE USE OR INABILITY TO USE ANY SIERRA WIRELESS PRODUCT, EVEN IF SIERRA WIRELESS AND/OR ITS AFFILIATES HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR THEY ARE FORESEEABLE OR FOR CLAIMS BY ANY THIRD PARTY.

Notwithstanding the foregoing, in no event shall Sierra Wireless and/or its affiliates aggregate liability arising under or in connection with the Sierra Wireless product, regardless of the number of events, occurrences, or claims giving rise to liability, be in excess of the price paid by the purchaser for the Sierra Wireless product.

Patents This product may contain technology developed by or for Sierra Wireless Inc. This product includes technology licensed from QUALCOMM. This product is manufactured or sold by Sierra Wireless Inc. or its affiliates under one or more patents licensed from InterDigital Group.

Copyright 2012 Sierra Wireless. All rights reserved.

Trademarks AirCard is a registered trademark of Sierra Wireless. Sierra Wireless, AirPrime, AirLink, AirVantage, Watcher and the Sierra Wireless logo are trademarks of Sierra Wireless.

Windows and Windows Vista are registered trademarks of Microsoft Corporation.

Macintosh and Mac OS are registered trademarks of Apple Inc., registered in the U.S. and other countries.

QUALCOMM is a registered trademark of QUALCOMM Incorporated. Used under license.

Other trademarks are the property of the respective owners.

Preface

Rev 2 Aug-12 Propr ie ta ry and conf iden t ia l 3

Contact Information Sales Desk: Phone: 1-604-232-1488

Hours: 8:00 am to 5:00 pm Pacific Time

E-mail: [email protected]

Technical Support:

Included with the purchase of the Development Kit you receive five hours of tier 3 engineering integration support. You will have received instructions by e-mail on how to access the OEM Customer Support web site. For more details, please contact your account manager, or the Sierra Wireless sales desk (see above).

RMA Support: [email protected]

Post: Sierra Wireless 13811 Wireless Way Richmond, BC Canada V6V 3A4

Fax: 1-604-231-1109

Web: www.sierrawireless.com

For up-to-date product descriptions, documentation, application notes, firmware upgrades, troubleshooting tips, and press releases, consult our website: www.sierrawireless.com



Table of Contents About This Guide ..................................................................................... 8

Introduction .................................................................................. 8

Scope .......................................................................................... 8

Glossary of terms ......................................................................... 9

References .................................................................................10

Revision history ..........................................................................11

Integration overview ...............................................................................12 CnS required support ..................................................................12

AT required support ....................................................................12

Sierra Wireless SDK required support .........................................12

Comprehensive sequences ....................................................................14 DC / PRL ....................................................................................14

HFA ............................................................................................16

Scenarios ...............................................................................................17 CI DC Successful update ..........................................................17

CI DC Failure Empty session ..................................................18

CI DC Failure user cancellation ...............................................19

CI DC Failure Generic .............................................................20

NI (Idle) DC Successful update .................................................20

NI (Idle) DC Failure empty session ..........................................21

NI (Idle) DC Failure User cancellation .....................................22

NI (Idle) DC Failure Generic ....................................................23

NI (Dormant / Active) DC Accept ...............................................24

NI (Dormant / Active) DC Reject................................................25

CI PRL Successful update ........................................................26

CI PRL No PRL candidate.........................................................26

CI PRL Failure User cancelled ................................................27

CI PRL Failure Generic ...........................................................28

NI (Idle) PRL Successful update ...............................................29

Table of Con tents


NI (Idle) PRL No PRL candidate................................................30

NI (Idle) PRL Failure User cancelled .......................................31

NI (Idle) PRL Failure Generic ..................................................32

NI (Dormant) PRL Accept .........................................................33

NI (Dormant) PRL Reject ..........................................................34

HFA Successful 1st try ...............................................................35

HFA Successful after retry ........................................................35

HFA Failure Generic ...............................................................36

Appendix A: CI vs. NI Idle vs. NI Dormant/Active User Experience .........37

Appendix B: UI Text ................................................................................38 Preparing services ......................................................................38

Profile update success ................................................................38

Profile empty error ......................................................................38

Profile update failed Generic .....................................................38

Profile update prompt ..................................................................38

PRL checking ..............................................................................38

PRL updating ..............................................................................38

PRL no candidate .......................................................................38

PRL success ...............................................................................38

PRL update prompt .....................................................................38

HFA initiation ..............................................................................39

HFA success ...............................................................................39

HFA retry ....................................................................................39

HFA failure ..................................................................................39

Aborted .......................................................................................39

Appendix C: Frequently Asked Questions ..............................................40



List of Figures Figure 1: DC / PRL ................................................................................15

Figure 2: HFA ........................................................................................16

Figure 3: CI DC Successful update ......................................................17

Figure 4: CI DC Failure empty session ..............................................18

Figure 5: CI DC Failure user cancellation ..........................................19

Figure 6: CI DC Failure Generic.........................................................20

Figure 7: NI (Idle) DC Successful update .............................................21

Figure 8: NI (Idle) DC Failure empty session .....................................21

Figure 9: NI (Idle) DC Failure User cancellation .................................22

Figure 10: NI (Idle) DC Failure Generic ..............................................23

Figure 11: NI (Dormant / Active) DC Accept .........................................24

Figure 12: NI (Dormant / Active) DC Reject .........................................25

Figure 13: CI PRL Successful update ..................................................26

Figure 14: CI PRL No PRL candidate ..................................................26

Figure 15: CI PRL Failure User cancelled ..........................................27

Figure 16: CI PRL Failure Generic .....................................................28

Figure 17: NI (Idle) PRL Successful update .........................................29

Figure 18: NI (Idle) PRL No PRL candidate .........................................30

Figure 19: NI (Idle) PRL Failure User cancelled .................................31

Figure 20: NI (Idle) PRL Failure Generic ............................................32

Figure 21: NI (Dormant) PRL Accept ...................................................33

Figure 22: NI (Dormant) PRL Reject ....................................................34

Figure 23: HFA Successful 1st try .........................................................35

Figure 24: HFA Successful after retry ..................................................35

Figure 25: HFA Failure Generic .........................................................36

Lis t o f Tables


List of Tables Table 1: Acronyms .................................................................................. 9

Table 2: CnS messages that must be supported ...................................12



About This Guide Introduction This document describes and illustrates the most common host-device message exchanges that occur in standard OMA-DM operations on the Sprint network. This document is intended to act as an addendum to the Sprint OMA-DM Functional Requirements document [R-1] and the Sierra Wireless CnS Reference Guide [R-4].

This documents does not cover FOTA/FUMO operations. These can be found in the Sprint FOTA Integration Guide [R-2].

Note: You can view this guide online or print it to keep on hand. If you're viewing it online, simply click a topic in the Table of Contents or any section reference. (Most text that is blue is a clickable link.) The PDF automatically displays the appropriate page.

Scope This document targets CDMA devices on the Sprint Nextel network that are compliant with version 1.4.5 of the Sprint OMA-DM spec [R-1] and are operating with a host connection manager that also supports this messaging.

It is suggested that you review the Sprint OMA-DM spec and the Sierra Wireless CnS Reference Guide before reading through the current document.

About This Guide


Glossary of terms Table 1: Acronyms

Acronym/term Description

AT A set of modem commands, preceded by AT, originally developed by Hayes, Inc. for their modems. The structure (but not the specific commands, which vary greatly from manufacturer to manufacturer) is a de facto modem industry standard. For a detailed description of the AT commands supported by the modem, see the AT Command Reference document from Sierra Wireless (document 2130620).

CDMA Code Division Multiple AccessA wideband spread spectrum technique used in digital cellular, personal communications services, and other wireless networks. Wide channels (1.25 MHz) are obtained through spread spectrum transmissions, thus allowing many active users to share the same channel. Each user is assigned a unique digital code, which differentiates the individual conversations on the same channel.

CI Client-Initiated

CIDC Client-Initiated Device Configuration

CM Connection Manager (software)

CnS Control and Status (language)a proprietary protocol for managing the control and status of the modem. CnS is described in detail in the CnS Reference document from Sierra Wireless (document 2130754).

DC Device Configuration

DM Device Management

dormant The network switches a 3G (1X or 1xEV-DO) high-speed data connection into a dormant mode if there is no traffic on the connection for some time. This allows the modem, if it supports voice, to make and receive voice calls while the data connection is idle. When you resume data traffic, the high-speed data connection becomes active.

firmware Software stored in ROM or EEPROM; essential programs that remain even when the system is turned off. Firmware is easier to change than hardware, but more permanent than software stored on disk.

FOTA Firmware Update Over The Aira feature included in OMA Device Management (OMA-DM).

FUMO Firmware Update Management Object. Related to FOTA (Firmware Update Over The Air)a feature included in OMA Device Management (OMA-DM).

HFA Hands Free Activation



Acronym/term Description

NI Network-Initiated

NIA Network-Initiated Alert

NIDC Network-Initiated Device Configuration

NIFUMO Network-Initiated Firmware Update Management Object

NIPRL Network-Initiated PRL Update

notification A mechanism to send unsolicited data from either side (host; modem) of the interface; used when no reply or return data is required from the receiver (or conversations do not require stop-and-wait flow control)

OMA Open Mobile Alliance

OMA-DM Open Mobile Alliance - Device Management. A device management (DM) protocol specified by the Open Mobile Alliance (OMA) Device Management Working Group and the Data Synchronization (DS) Working Group.

PRI Product Release Instructionsa file that contains the settings used to configure wireless products for a particular service provider, customer, or purpose.

PRL Preferred Roaming Listan account configuration item set by the users service provider. It controls the radio channels/network carrier used by the modem.

References Ref. # Document title Doc. #

R-1 Sprint_OMA-DM_Client_Functional_Requirements_v1.5.1_080908.pdf

N/a

R-2 Sprint FOTA Integration Guide, Sierra Wireless 2131025

R-3 CDMA API Reference, Sierra Wireless 2130593

R-4 CDMA 1xEV-DO CnS Reference, Sierra Wireless 2130754

About This Guide


Revision history Version Date Summary of changes

0.1 28aug08 Initial draft.

0.2 22sep08 Incorporated review suggestions.

1.0 29sep08 Added Profile, PRL Update Prompts and Aborted message to Appendix B UI Text. Updated NI Dormant PRL Reject to include message.

1.1 19jan09 Added FAQ section and minor notes/updates.

1.2 27jan09 Updated doc to FileHold format and added to FileHold System.

1.3 Apr09 Used the Technical Publications layout. Changed CnS object names to match what the CnS Reference uses.

2 Aug12 Removed products that have reached end-of-life (MC5727). New template. Changes to the patents section.



Integration overview The OMA-DM feature covered in this document is a standardized protocol through which devices may be remotely administered by the network. This guide aims to cover integration of OMA-DM, particularly the Device Configuration (DC), PRL update, and Hands Free Activation (HFA) features per Sprints requirements.

The diagrams cover modem-to-SDK communication vis-a-vis CnS messages and the SDK-to-Application communication vis-a-vis Sierra Wireless API calls.

CnS required support The following table shows the CnS messages that must be supported, to implement OMA-DM at the CnS level.

Table 2: CnS messages that must be supported

Object ID Set Get Notification

DM Configuration 0x0E00 Start DM Session 0x0E01 Cancel DM Session 0x0E02 DM Session State 0x0E03 Network-Initiated Alert 0x0E04

AT required support At the time of publication of this document, AT-based implementation of OMA-DM is not supported.

Sierra Wireless SDK required support Implementing OMA-DM at the Sierra Wireless SDK level requires support of the following APIs and notification objects:

Sierra Wireless SDK APIs: SwiGetOMADMConfig

SwiStartOMADMSession

SwiCancelOMADMSession

SwiSetOMADMNIAlertResponse

In tegrat ion overview


Notifications:

SWI_NOTIFY_OMADM_State

SWI_NOTIFY_OMADM_NI_Alert The above two notifications must be enabled in order to support OMA-DM. These notifications should be registered as part of the host client (that is, connection manager) initiation sequence.

For details on the Sierra Wireless SDK APIs and Sierra Wireless SDK Notification objects, see the CDMA API Reference guide [R-3] and the header files accompanying the SDK.



Comprehensive sequences DC / PRL Figure 1 on page 15 illustrates standard alternative messages that may occur in a Sprint OMA-DM DC or PRL session.

An important subtle characteristic that should be noted is that an OMA-DM session may have multiple initiations messages (DM Session State [0x0E03] with state = Active) within a single session. This is a result of the auto-retry requirement, which specifies that, if a Network Initiated OMA-DM session fails to establish for reasons other than authentication failure or no-job, the device should retry up to five times.

Note: These flows assume that the CM has already properly registered for notifications for the OMA-DM CnS objects (see Table 2 on page 12). Prompts / host UI messages are not presented in this sectionthe UI experience varies depending between PRL/DC sessions and Idle/Dormant/Active states.

Comprehens ive sequences


Figure 1: DC / PRL

OMA - DM Session

CNS_DM_SESSION_STATE

SWI_NOTIFY_OMADM_State Active, ,

CNS_DM_SESSION_STATE SWI_NOTIFY_OMADM_State Not Active, , , Success, Updated

SwiStartOMADMSession ()

Return CNS _ DM _ SESSION _ START

CNS _ DM _ SESSION _ START < PRL / DC >

Success

SWI Modem

sd Generic OMA - DM Sequence

SDK / Host SDK Client

[If NI then retry up to 5 times upon soft establishment failures]

loop

[Successful]

[Failure]

alt

, Not Active,, , , Not Updated

opt SwiCancelOMADMSession()

Return CNS_DM_SESSION_CANCEL

Cancel

Success

CNS _ DM _ NI _ ALERT SWI _ NOTIFY _ OMADM _ NI _ Alert < UI Mode >, < PRL / DC >

[Network Initiated]

[Client Initiated]

alt


CNS_DM_SESSION_CANCEL

CNS_DM_SESSION_STATE



HFA Figure 2 illustrates standard alternative messages that may occur in a Sprint HFA session.

Note: The HFA attempted flag is now obsolete.

Figure 2: HFA

SWI Modem SDK / Host SDK Client

HFA Session

CNS_DM_SESSION_STATE SWI_NOTIFY_OMADM_State Active, HFA, D-CI

HFA Retry Pending, TTR, D-CI, HFA, Unspecified Error ,

Not Active, D-CI, HFA, Unspecified Error, Not Updated

[While not successful and retries

Scenar ios


Scenarios This section describes and illustrates the expected messaging sequences for OMA-DM DC, PRL and HFA scenarios described in the Sprint OMA-DM requirements document [R-1].

Note: Prompts or host UI messages referenced via bracket notation in the message flows are later described in Appendix B: UI Texton page 38.

CI DC Successful update User selects to perform a CI DC update, and it completes successfully.

Figure 3: CI DC Successful update

Steps:

(1) Host requests the Modem to initiate a User Client Initiated (U-CI) Device Configuration session.

(2) Modem acknowledges the request.

(3) Modem notifies the Host that the Device Configuration Session has begun.

(4) Modem notifies the Host that the Device Configuration Session has completed successfully.

CI DC Session

(3) CNS_DM_SESSION_STATE

SWI_NOTIFY_OMADM_State Active, Device Configuration, U-CI

Not Active, U-CI, Dev Conf, Success, Updated

SwiStartOMADMSession()

Return

(1) CNS_DM_SESSION_START

(2) CNS_DM_SESSION_START Device Configuration

Success

SWI Modem


SWI_NOTIFY_OMADM_State (4) CNS_DM_SESSION_STATE

sd CI DC - Successful



CI DC Failure Empty session User selects to perform a CI DC update, and the network erroneously sends an empty profile.

Figure 4: CI DC Failure empty session

Steps:




(4) Modem notifies the Host that the Device Configuration Session has completed, and that no operations were conducted and thus the configuration has not been updated.

SWI Modem


CI DC Session

Not Active , Dev Conf , U - CI , No Op , Not Updated


Return Device Configuration

Success




Active, Device Configuration, U-CI (3) CNS_DM_SESSION_STATE SWI_NOTIFY_OMADM_State


sd CI DC Failure Empty Session

Scenar ios


CI DC Failure user cancellation User selects to perform a CI DC update and cancels the session midway.

Figure 5: CI DC Failure user cancellation

Steps:




(4) Host requests the Modem to cancel the Device Configuration session.

(5) Modem responds to the Host indicating that the request was successfully received.

(6) Modem notifies the Host that the Device Configuration Session has aborted per the users request.

SWI Modem


CI DC Session

Active, Device Configuration, U-CI

Not Active, Dev Conf, U-CI, User Aborted, Not Updated



Success

SwiCancelOMADMSession()

Return

Cancel

Success






(4) CNS_DM_SESSION_CANCEL



sd CI DC Failure User Cancellation



CI DC Failure Generic User selects to perform a CI DC update, and it fails due to a generic error.

Figure 6: CI DC Failure Generic

Steps:




(4) Modem notifies the Host that the Device Configuration Session has erroneously ended for an unknown reason.

NI (Idle) DC Successful update Network pushes a NI update while the device is Idle, and it completes successfully.

Scenario prerequisite: Modem is in Idle Modethere are no packet data connections active/dormant or circuit switched calls active (for example, voice call).

SWI Modem


CI DC Session

Active, Device Configuration, U-CI

Not Active, Dev Conf, U-CI, Unspecified Error, Not Updated



Success



(3) CNS_DM_SESSION_STATE SWI_NOTIFY_OMADM_State


sd CI DC Failure Generic

Scenar ios


Figure 7: NI (Idle) DC Successful update

Steps:

(1) Modem notifies the Host that a Network Initiated (NI) Device Configuration request was received. Since this is an informative session, the host should display the status to the user.


(3) Modem notifies the Host that the Device Configuration Session has completed successfully.

NI (Idle) DC Failure empty session Network pushes a NI update while the device is Idle and erroneously sends an empty profile.


Figure 8: NI (Idle) DC Failure empty session

SWI Modem


NI DC Session

SWI_NOTIFY_OMADM_NI_Alert Informative, Device Conf

Active, NI, Device Configuration

Not Active, NI, Dev Conf, Success, Updated

(1) CNS_DM_NI_ALERT





SWI Modem


NI DC Session

Active, Device Configuration, NI

Not Active, Dev Conf, NI, No Op, Not Updated

Informative, Device Conf

SWI_NOTIFY_OMADM_NI_Alert

(1) CNS_DM_NI_ALERT



sd NI (Idle) DC Successful

sd NI (Idle) DC Failure Empty Session



Steps:



(3) Modem notifies the Host that the Device Configuration Session has completed, no operations were conducted and thus the configuration has not been updated.

NI (Idle) DC Failure User cancellation Network pushes a NI update while the device is Idle, and the user cancels the session midway.


Figure 9: NI (Idle) DC Failure User cancellation

Steps:



(3) Host requests the Modem to cancel the Device Configuration session.

SWI Modem


NI DC Session

Active, Device Configuration, NI

Not Active, Dev Conf, NI, User Aborted, Not Updated


Return

Cancel


Success

(1) CNS_DM_NI_ALERT SWI_NOTIFY_OMADM_NI_Alert






sd NI (Idle) DC Failure User Cancellation

Scenar ios



(5) Modem notifies the Host that the Device Configuration Session has aborted per the users request.

NI (Idle) DC Failure Generic Network pushes a NI update while the device is Idle and it fails due to a generic error.


Figure 10: NI (Idle) DC Failure Generic

Steps:


(2) Modem notifies the Host that the Device Configuration Session has begun. Because the modem is experiencing a generic error with the network, it will retry five times.

(3) Modem notifies the Host that the Device Configuration Session has erroneously ended for an unknown reason.

SWI Modem


NI DC Session



(1) CNS_DM_NI_ALERT SWI_NOTIFY_OMADM_NI_Alert

Active, Device Configuration, NI (2) CNS_DM_SESSION_STATE






Not Active, Dev Conf, NI, Unspecified Error, Not Updated (3) CNS_DM_SESSION_STATE







sd NI (Idle) DC Failure Generic



NI (Dormant / Active) DC Accept Network pushes NI update while device is Dormant, and the user elects to update the profile.

Scenario prerequisite: Modem is in a dormant or active packet data connection.

If the network pushes a NI update while the device is active (active data call or active circuit switch call), the modem queues the request until it becomes dormant. Once the notification is sent to the host, the connection will not necessarily still be dormant. It is suggested that the host handle NI sessions in the same manner for both active and dormant scenarios.

Figure 11: NI (Dormant / Active) DC Accept

Steps:

(1) Modem notifies the Host that a Network Initiated Device Configuration request was received. Since the device is dormant (connected but not active) when this notification is received the Modem will wait until it is dormant and notify the Host that it should interrupt the user and request permission to continue.

(2) As a result of the user selecting to continue with the OMA-DM session, the Host disconnects the current data session.

(3) Host sends a message to the Modem to indicate that it wants to interrupt the current data connection and perform a device configuration session.

(4) Modem acknowledges receipt of the message.

SWI Modem



SwiSetOMADMNIAlertResponse()

Return

Yes

Yes

ref (5) NI DC Session

Device active or dormant

ref (2) Disconnect Data Session

SWI_NOTIFY_OMADM_NI_Alert

(1) CNS_DM_NI_ALERT

(3) CNS_DM_NI_ALERT

(4) CNS_DM_NI_ALERT Success

sd NI (Dormant/Active) DC Accept

Scenar ios


(5) Subsequent messages follow the same flow as NI (Idle) DC Scenarios (see pages 20 through 23).

NI (Dormant / Active) DC Reject Network pushes NI update while device is dormant; the user elects to not interrupt their current session and thus not update the profile.



Figure 12: NI (Dormant / Active) DC Reject

Steps:

(1) Modem notifies the Host that a Network Initiated Device Configuration request was received. Since the device is Dormant (connected but not active) when this notification is received, the Modem notifies the Host that it should interrupt the user and request permission to continue.

(2) Host messages the Modem to indicate that it does not want to interrupt the current data connection with a DC session.


SWI Modem




Return

SwiSetOMADMNIAlertResponse() No

No

Success

SWI_NOTIFY_OMADM_NI_Alert (1) CNS_DM_NI_ALERT

(2) CNS_DM_NI_ALERT

(3) CNS_DM_NI_ALERT

sd NI (Dormant) DC Reject



CI PRL Successful update User selects to perform a CI PRL update and it completes successfully.

Figure 13: CI PRL Successful update

Steps:

(1) Host requests the Modem to initiate a User Client Initiated (U-CI) PRL update session.


(3) Modem notifies the Host that the PRL Session has begun.

(4) Modem notifies the Host that the PRL Session has completed successfully.

CI PRL No PRL candidate User selects to perform a CI PRL update, but the network does not have an update available.

Figure 14: CI PRL No PRL candidate

SWI Modem


CI PRL Session

Active, PRL, U-CI

Not Active, U-CI, PRL, Success, Updated


Return PRL

Success







SWI Modem


CI PRL Session

Active, PRL, U-CI

Not Active, PRL, U-CI, No Op, Not Updated


Return PRL

Success







sd CI PRL Successful

sd CI PRL No PRL Candidate

Scenar ios


Steps:

(1) Host requests the Modem to initiate a User Client Initiated (U-CI) PRL session.



(4) Modem notifies the Host that the PRL Session has ended with no operations completed and thus no updates.

CI PRL Failure User cancelled User selects to perform a CI PRL update and then cancels the session midway.

Figure 15: CI PRL Failure User cancelled

Steps:




(4) Host requests the Modem to cancel the PRL session in an effort to stop the update process.


(6) Modem notifies the Host that the PRL Session has aborted per the users request.

SWI Modem SDK / Host SDK Client


Return PRL

Success

CI PRL Session

Active, PRL, U-CI

Not Active, PRL, U-CI, User Aborted, Not Updated

SwiCancelOMADMSession() Return

Cancel

Success








sd CI PRL User Cancellation



CI PRL Failure Generic User selects to perform a CI PRL update and it fails due to a generic error.

Figure 16: CI PRL Failure Generic

Steps:




(4) Modem notifies the Host that the PRL Session has erroneously ended for an unknown reason.

SWI Modem


CI PRL Session

Active, PRL, U-CI

Not Active, PRL, U-CI, Unspecified Error, Not Updated


Return PRL

Success







sd CI PRL Failure Generic

Scenar ios


NI (Idle) PRL Successful update Network pushes a NI PRL session while the device is Idle and it completes successfully.


Figure 17: NI (Idle) PRL Successful update

Steps:

(1) Modem notifies the Host that a Network Initiated (NI) PRL request was received. Since this is a background session, the host should hide this session from the user unless the user interrupts the session.


(3) Modem notifies the Host that the PRL Session has completed successfully.

SWI Modem


NI PRL Session

Active, PRL, NI

Not Active, NI, PRL, Success, Updated

Background, PRL


SWI_NOTIFY_OMADM_ NI_Alert


(1) CNS_DM_NI_ALERT



sd NI (Idle) PRL Successful



NI (Idle) PRL No PRL candidate Network pushes a NI PRL session while the device is Idle, and the network does not have an update available.


Figure 18: NI (Idle) PRL No PRL candidate

Steps:



(3) Modem notifies the Host that the PRL Session has ended with no operations completed and thus no updates.

SWI Modem

SDK Client

NI PRL Session

Active, PRL, NI

Not Active, NI, PRL, No Op, Not Updated

Background, PRL

SDK / Host

(1) CNS_DM_NI_ALERT SWI_NOTIFY_OMADM_ NI_Alert




sd NI (Idle) PRL No PRL Candidate

Scenar ios


NI (Idle) PRL Failure User cancelled Network pushes a NI PRL session while the device is Idle and then cancels the session midway.


Figure 19: NI (Idle) PRL Failure User cancelled

Steps:



(3) Host requests the Modem to cancel the PRL session in an effort to stop the update process.


(5) Modem notifies the Host that the PRL Session has aborted per the users request.

SWI Modem

SDK Client

NI PRL Session

Active, PRL, NI

Background, PRL

Not Active, PRL, U-CI, User Aborted, Not Updated


Return

Cancel

User actions interrupt process

Success

SDK / Host







sd NI (Idle) PRL Failure User Cancellation



NI (Idle) PRL Failure Generic Network pushes a NI PRL session while the device is Idle and it fails due to a generic error.


Figure 20: NI (Idle) PRL Failure Generic

Steps:



(3) Modem notifies the Host that the PRL Session has erroneously ended for an unknown reason.

SWI Modem

SDK Client

Background, PRL

NI PRL Session

SDK / Host


SWI_NOTIFY_OMADM_State Active, PRL, NI


Active, PRL, NI (2) CNS_DM_SESSION_STATE





Not Active, NI, PRL, Unspecified Error, Not Updated (3) CNS_DM_SESSION_STATE







sd NI (Idle) PRL Failure Generic

Scenar ios


NI (Dormant) PRL Accept Network pushes NI PRL update while device is dormant, and the user elects to proceed.


If the network pushes a NI update while the device is active (active data call or active circuit switch call) the modem queues the request until it becomes dormant. Once the notification is sent to the host, the connection will not necessarily still be dormant. It is suggested that the host handle NI sessions in the same manner for both active and dormant scenarios.

Figure 21: NI (Dormant) PRL Accept

Steps:

(1) Modem notifies the Host that a Network Initiated (NI) PRL request was received. Since the device is dormant (connected but not active) when this notification is received, the Modem notifies the Host that it should interrupt the user and request permission to continue.

(2) As a result of the user selecting to continue with the OMA-DM session, the Host disconnects the current data session.

(3) Host messages the Modem to indicate that it does want to interrupt the current data connection and perform a device configuration session.


SwiSetOMADMNIAlertResponse()

Return Yes

Success

Background, PRL

SWI Modem

SDK Client

Yes

ref (5) NI PRL Session

ref (2) Disconnect Data Session


SDK / Host


(3) CNS_DM_NI_ALERT

(4) CNS_DM_NI_ALERT

sd NI (Dormant) PRL Accept



(5) Subsequent message follow same flow as NI (Idle) PRL Scenarios. Note: In the subsequent flows the UI should not treat this as a background session; instead, it should treat this as an informative session and inform the user of the progress.

NI (Dormant) PRL Reject Network pushes NI PRL update while device is dormant and the user elects to not interrupt their current session and thus not update the PRL.



Figure 22: NI (Dormant) PRL Reject

Steps:

(1) Modem notifies the Host that a Network Initiated (NI) PRL request was received. Since the device is Dormant (connected but not active) when this notification is received, the Modem notifies the Host that it should interrupt the user and request permission to continue.

(2) Host messages the Modem to indicate that it does not want to interrupt the current data connection with a PRL session.


SWI Modem

SDK Client

Background, PRL

Return

SwiSetOMADMNIAlertResponse() No

No

Success


SDK / Host


(2) CNS_DM_NI_ALERT

(3) CNS_DM_NI_ALERT

sd NI (Dormant) PRL Reject

Scenar ios


HFA Successful 1st try The modem automatically attempts Hands Free Activation, which completes successfully upon the first attempt.

Figure 23: HFA Successful 1st try

Steps:

(1) Modem notifies the Host that the modem has initiated a Device-Client Initiated (D-CI) Hand Free Activation (HFA) session.

(2) Modem notifies the Host that the HFA session has completed successfully.

HFA Successful after retry The modem automatically attempts Hands Free Activation, which completes successfully on the third attempt.

Note: HFA Retry occurs only if the error is no operation was performed.

Figure 24: HFA Successful after retry

HFA Session

(1) CNS_DM_SESSION_STATE SWI_NOTIFY_OMADM_StateActive, HFA, D-CI

(6) CNS_DM_SESSION_STATE SWI_NOTIFY_OMADM_StateNot Active, D-CI, HFA, Success, Updated



SWI Modem

sd HFA Retry Successful


HFA Retry Pending, TTR, D-CI, HFA, No Op, Not Updated

HFA Retry Pending, TTR, D-CI, HFA, No Op, Not Updated





HFA Session

Active, HFA, D-CI

Not Active, D-CI, HFA, Success, Updated

SWI Modem

SDK Client SDK / Host




sd HFA 1st Try Successful



Steps:


(2) Modem notifies the Host of a failed HFA attempt.

(3) Modem notifies the Host that the modem has re-initiated a Device-Client Initiated (D-CI) Hand Free Activation (HFA) session.

(4) Modem notifies the Host of a failed HFA attempt.

(5) Modem notifies the Host that the modem has re-initiated a Device-Client Initiated (D-CI) Hand Free Activation (HFA) session.

(6) Modem notifies the Host that the HFA session has completed successfully.

HFA Failure Generic Device automatically attempts Hands Free Activation and fails for unspecified reason.

Figure 25: HFA Failure Generic

SWI Modem

sd HFA Failure Generic


HFA Session


(2) CNS_DM_SESSION_STATE SWI_NOTIFY_OMADM_StateNot Active, D-CI, HFA, Unspecified Error, Not Updated

Steps:


(2) Modem notifies the Host that the HFA session has failed.

Appendix A: CI vs . NI Id le vs . NI Dormant /Act ive User Exper ience


Appendix A: CI vs. NI Idle vs. NI Dormant/Active User Experience The CI, NI Idle, and NI Dormant OMA-DM sessions have message flows that are very similar with only subtle parameter and UI experience differences. It is important to understand these differences in order to ensure compliance with Sprints OMA-DM specification [R-1].

A CI OMA-DM session requires the Host to display status of the entire OMA-DM session, regardless of the reported UI mode.

A Network Initiated (NI) Device Configuration (DC) session will report a standard UI mode of informative, which requires that the Host keep the user informed of the session status regardless of whether it was started in Dormant mode or in Idle mode.

A Network Initiated (NI) PRL session will report a standard UI mode of background. In this scenario the Host does not inform the user of the session unless interrupted by the user. If the user interrupts a NI Idle PRL session, then the Host shall display the status of the session so that the user is informed and may cancel the operation.

If a session is network initiated while the device is dormant or active, the host shall prompt the user to determine whether they wish to continue their data session or perform the update. If they choose to continue, the Host shall first disconnect the data session, send the Alert Response message and then continue to display the status of the session. If the prompt is not responded to and the device goes idle, the device may automatically continue with the NI session.

Note: Your application should ignore the Special UI mode parameter.



Appendix B: UI Text Preparing services The network is preparing your services. Please wait

Profile update success

Profile empty error The profile update could not be completed. Please try again later.

If the problem persists, you may need to contact Customer Service.

Profile update failed Generic Error Code: XXX

Profile update prompt The purpose of this prompt is to inform the user that a device configuration update is available and ask them if they wish to end their current data session in order to perform the update.

The Sprint requirements do not dictate specific text to be displayed.

PRL checking Checking for PRL update

PRL updating The network is updating your PRL. Please wait

PRL no candidate No PRL update available

PRL success PRL updated.

PRL update prompt The purpose of this prompt is to inform the user that a PRL update is available and ask them if they wish to end their current data session in order to perform the update.

Appendix B: UI Text



HFA initiation Hands Free Activation

Contacting network

HFA success Your device has been activated.

HFA retry Hands Free Activation

Waiting for retry in xx seconds

HFA failure Hands Free Activation

Your activation could not be completed. Please try again later.

If the problem persists, you may need to contact Customer Service.

Aborted This message indicates that the update was explicitly canceled by the user.




Appendix C: Frequently Asked Questions Q: If the host receives an interactive/forced interruption NI Alert indication and does not respond with an interactive response to the modem (for example, NIA-DC), does the modem resend the same indication to the host periodically or is there only one notification? A: For any given NIA received from the network the Network-Initiated Alert message (0x0E04) is sent only once.

Q: How many pending NIAs can the modem store (that is, if the host does not respond to a NIA-DC and the network pushes a NIA-PRL Update)? What happens if the modem's NIA queue overflows? A: If a NIA is received when the modem has an older NIA pending a response from the host, the newer NIA is queued until the previous NIA has been answered. Once the previous NIA has been answered, the queued NIA is sent to the host. Up to 6 NIAs can be queued. Once the queue is full, the subsequent NIAs are dropped. Queued NIAs are also cleared on power-cycle.

Q: For interactive/forced-interruption-on-dormancy NI sessions, the modem expects the host to respond with allow or deny. For adapter products, the decision is the responsibility of the end-user, however many embedded solutions are autonomous and do not have the ability to interact with a user; how should autonomous systems act? What is Sprint's requirement? Can the system always "allow" the NI alert session? What happens in this case when call is in dormant state? Will it be disconnected? A: This is a decision that the customer needs to make. The purpose of the prompt is to give the host the ability to choose whether or not it wants to interrupt its current data session to perform the OMA-DM session. If the customers device can support the data session being randomly dropped when an NIA comes in, then it should always allow the NI alert session. Otherwise it is the responsibility of the customer to implement the logic to determine when is a good time to perform an OMA-DM session.

Q: How many OMA-DM accounts does a Sierra Wireless device support? A: Sierra Wireless devices currently support only one OMA-DM account per device.

Appendix C: Frequent l y Asked Quest ions


Q: Please explain the steps the modem goes through when doing an HFA session to provision the MDN and/or MSID. How does the modem get account information over-the-air when the modem is not even activated? Is this over the data channel? A flow diagram will help a lot. A: Upon power-up the modem initiates HFA if any one of the three parameters (MSID, MDN and MIP1) are not provisioned. An unprovisioned modem is able to connect with the OMA-DM server through a MIP slot0 connection that is provisioned at the factory. More information on OMA-DM can be found at: http://www.openmobilealliance.org/Technical/DM.aspx.

Q: What happens if HFA fails after retries? Will UCI-DeviceConfiguration also provision all the account information and profile update over-the-air, similar to HFA? A: If HFA fails after all retries (if any), the modem will try again the next time the modem is powered up (that is, the modem continues to attempt HFA until it is fully provisioned).

Note: The initial deployment of Sprint Compass 597 USB modems would not retry after the first set of attempts.

Q: In addition to OMA-DM, is manual activation supported in the MC5728V Mini Card? A: Yes

Q: If yes, should the host support manual activation on a Sprint MC5728V Mini Card in addition to OMA-DM? A: No

Q: Is the OMA-DM server address carrier-specific? If so, should it be set in the PRI? How is the modem provisioned with the OMA-DM server address? A: At this point we support only Sprint OMA-DM requirements and don't support the provisioning of the OMA server address. If and when we support OMA-DM for other carriers, we will need to update the firmware and/or dmtree file at that point.

Q: The DM Configuration reply indicates the maximum number of DM accounts supported. Is this same as the DM-TLV Account node name in Start DM Session (0x0E01)? A: Currently we support only one DM account, and the DM-TLV account node name is not used.

Q: Is there a plan to support more than one DM account in the future, as indicated by Start DM Session? A: Currently there are no plans to support more than one DM account. It may happen in the future for dual-mode devices (for example, CDMA and WiMax) but not for the MC5728V Mini Card.



Q: What happens if the host sends a DM account name that is not supported? Does the modem respond with an error message? Do the current configuration and PRL remain valid? A: The firmware ignores the DM account name field so it does not make any difference.

Q: What can an OMA-DM Device Configuration session change? What happens when a client initiated session occurs? A: An OMA-DM device configuration session can update MIP profile 1, MSID and MDN. The Sprint OMA server normally re-programs all parameters (MIP1, MDN & MSID) with the same values (but we've seen cases where the server performs only a partial or no provisioning).

Q: What MIP profiles are used when performing an OMA-DM session, what about afterwards? A: The active MIP profile when in an OMA-DM session is profile 0. Once the session is completed, the active data profile is changed to profile 1.

Q: How can the host query the status of a specific DM account? A: The DM Session State object (0x0E03) returns whether the device is in a DM session state or not, and, if not, whether it is pending HFA retry. On a related note, the Activation Status object (0x1009) returns whether or not the device has been activated.

Q: Are the last session result codes for the DM Session State standardized? A: No; they are Sierra Wireless proprietary.

Q: At any point in time, can there be more than one active DM session? For example, the host sends Start DM Session (0x0E01) for CI-DeviceConfiguration and this DM session is in active state. Is it valid for the host to send Start DM Session (0x0E01) for CI-PRL update when previous one is still active? If it is not valid, does the modem respond with error? A: Only one DM session can be active at a time. The modem responds with error if a new DM request is made while a session is active.

Q: If the modem has an HFA retry pending and also has indicated NI alert for NI DC or NI PRL, when the host sends a cancel DM session to modem, are all the above cancelled or only the last session? A: It will only cancel the HFA.

Appendix C: Frequent l y Asked Quest ions


Q: If the host does not respond to an alert, is the current Device Configuration/PRL/Firmware still valid, or is it overwritten with the new one? A: The current parameters will still be valid (NIA itself does not contain the valuesinstead, it only has a URI to server).

Q: Is a simulator available to test some of the cases like NI Alert and failure cases indicated in Sprint-OMA-DM integration guide? How does Sierra Wireless test all of the corner cases? A: As of the publication date of this document, Sierra Wireless is not aware of a commercially-available OMA-DM simulator. Sierra Wireless generated its own simulation and test code, but they are not supported in the released code. Sierra Wireless staff spent a considerable amount of time at Sprints STIC lab and has used sandbox accounts for Sprint production OMA server.

PrefaceLimitation of liabilityPatentsCopyrightTrademarksContact Information

Table of ContentsList of FiguresList of TablesAbout This GuideIntroductionScopeGlossary of termsReferencesRevision history

Integration overviewCnS required supportAT required supportSierra Wireless SDK required support

Comprehensive sequencesDC / PRLHFA

ScenariosCI DC Successful updateCI DC Failure Empty sessionCI DC Failure user cancellationCI DC Failure GenericNI (Idle) DC Successful updateNI (Idle) DC Failure empty sessionNI (Idle) DC Failure User cancellationNI (Idle) DC Failure GenericNI (Dormant / Active) DC AcceptNI (Dormant / Active) DC RejectCI PRL Successful updateCI PRL No PRL candidateCI PRL Failure User cancelledCI PRL Failure GenericNI (Idle) PRL Successful updateNI (Idle) PRL No PRL candidateNI (Idle) PRL Failure User cancelledNI (Idle) PRL Failure GenericNI (Dormant) PRL AcceptNI (Dormant) PRL RejectHFA Successful 1st tryHFA Successful after retryHFA Failure Generic

Appendix A: CI vs. NI Idle vs. NI Dormant/Active User ExperienceAppendix B: UI TextPreparing servicesProfile update successProfile empty errorProfile update failed GenericProfile update promptPRL checkingPRL updatingPRL no candidatePRL successPRL update promptHFA initiationHFA successHFA retryHFA failureAborted

Appendix C: Frequently Asked Questions

Documents

2170012_Software Integration Application Notes for Sprint OMA-DM_rev2