AT-command based Control Plane in Android

[updated on 2014.05.14]

1. Overview

This page discusses about Control Plane (CP) implementation based on 3GPP TS 27.007 (http://www.3gpp.org/ftp/Specs/html-info/27007.htm) in Android. Currently, our implementation is based on 3GPP TS 27.007 V10.0.0 (2010-06). Please refer to allPartners/deliverables/glhal/unix/3GPPAT/ code section for more information.

This integration applies to 4750, 4751, 47511, 4752, 47520, 47521, 47531 Android SDK.

Unless the modem provider directly provides the CP socket, the "CP AT-command Stub" is important and it's the point where integration must be made in order to activate AT-command based CP implementation. From here on we will refer "CP AT-command Stub" as simply "the stub". If the modem provider provides the direct CP socket, the daemon will be the client of the socket and talk directly with the modem in AT-command syntax.




2. AT-commands used for CP implementation

Following AT commands are needed from the modem for standard CP implmentation. (Please refer to allPartners/deliverables/glhal/unix/3GPPAT/inc/brcm_ril_at_config.h for detailed information)


Each command and response below shows Standard. If Standard is "Y", details can be found in 3GPP 27.007.




AT Commands sent by gpsd to the modem

Keyword       Usage            Standard    Description
--------     --------------   ----------  -------------------------
E0           ATE0                 Y       Sent once after powerup to disable command echo by modem.

+CPOSR       AT+CPOSR=1           Y       Sent once after powerup to enable +CPOSR: unsolicited response from the modem.

+CMTLR       AT+CMTLR=1           Y       Sent once after powerup to enable unsolicited "+CMTLR:" message from the modem.

+CRESET      AT+CRESET=1          N       Sent once after powerup to enable +CRESET: unsolicited response from the modem.
+CMTLRA      AT+CMTLRA=0          Y       Notifies the modem that user denied to expose one's location
             AT+CMTLRA=1          Y       Notifies the modem that user agreed to expose one's location

+CPOS        AT+CPOS<xmlStr>      Y       Send position responses and requests for assistance to the modem.  XML string carries information

+CCLOCK      AT+CCLOCK=0          N       Disable Reference Clock at the start of each position request.
             AT+CCLOCK=1          N       Enable  Reference Clock at the start of each position request.

+CGED        AT+CGED=0            N       Request current list of cell IDs

+REFCLKFREQ  AT+REFCLKFREQ=0      N       Disable unsolicited responses for Reference Clock status from the modem
             AT+REFCLKFREQ=1      N       Enable  unsolicited responses for Reference Clock status from the modem
             AT+REFCLKFREQ?       N       Request current Reference Clock status

+CREG        AT+CREG=0            Y       Disable unsolicited responses for Reference Clock status from the modem - DEPRECATED
             AT+CREG=2            Y       Enable  unsolicited responses for Reference Clock status from the modem - DEPRECATED
             AT+CREG?             Y       Request current Reference Clock status - DEPRECATED

+ECID        AT+ECID=0            N       Request current enhanced cell ID information

%LPPIE       AT%LPPIE=<ASN.1>     N       Send OTDOA information in ASN.1 format.  See description below.




AT Commands sent by modem to the gpsd

There are no AT commands sent from the modem to gpsd.  The modem may only send unsolicited responses.




Unsolicited responses sent by modem to gpsd

Keyword       Usage                                Standard    Description
--------     -------------------------------      ---------- -----------------------------------
+CREG:        +CREG: <Varies>                         Y       Reports current cell registration status  See 3GPP27.007 for syntax - DEPRECATED

+CPOSR:       +CPOSR: <pos_meas><XML string>          Y       Requests position attempt and passes assistance data to gpsd.  See 3GPP27.007 for syntax

+CMTLR:       +CMTLR: <Varies>                        Y       Notification status for the position request.  See 3GPP27.007 for syntax

+CGED:        +CGED: <text>                           N       Shows the current/neighbor cell information in plain text. Please refer to the modem provider's documentation.

+CRESET:      +CRESET: 1                              N       Request next fix to be cold start by ignoring all stored assistance data.

+CPING:       +CPING: <text>                          N       Test command. gpsd will will simply echo back the same command to the modem. Once used for IPC/socket stress testing.

+REFCLKFREQ:  +REFCLKFREQ:0,26000000,100,1            N       Reports current reference clock status.  See description below for details

+ECID=        --  see description below  --           N       Report current enhanced cell ID information.

%LPPIE       %LPPIE=<ASN.1>                           N       Send OTDOA information in ASN.1 format.  See description below.

(Note: Currently, +CMOLR is not supported.)
(Note: Currently, there are unsupported fields in +CPOSR. Please refer to Appendix A. Unsupported XML fields in +CPOSR for more information.)

2.1. Description of the +CMTLR: response

The unsolicited response "+CMTLR: " can be used if the modem needs user notification/verification. It is not required for a position attempt. If the modem sends this response, the gpsd will use the same method as SUPL notification/verification. The modem is not required to implement this response if other methods are available to obtain user notification/verification. Please refer to User Privacy Popup Notification Sequence for message sequence. Please refer to 3GPP TS 51.010 test case 70.9.2.* ~ 70.9.3.* for more information on test case.



2.2. Description of the +CGED: response


NOTE: This command is deprecated for new designs. It should only be used in existing projects. Please use +ECID instead.
The +CGED: response provides current cell ID information used for the SUPL ECID positioning method. There are two forms of the response and the correct report will depend on the RAT (GSM or UMTS) used.

Form #1: GSM environment

+CGED:RAT:"GSM" B:"<bandVal>", Arfcn: <arfcnVal>, Rssi: <rssiVal>,RXQual:<rxQualVal>, Bsic:<bsicVal>

  • <bandVal> : One letter in the set [GDP]. G=GSM D=DCS P=PCS
  • <arfcnVal>: Integer value for ARFCN. Range is [0..1023]
  • <rssiVal> : RSSI signal strength. Range is [0..62]
  • <bsicVal> : Base station identity code, always 2 characters in hexadecimal format. Range is [00..3F]

These values may be repeated once for each cell or neighbor cell. Additional values may be included and will be ignored.

Example:
+CGED: RAT:"GSM" B:"G", Arfcn: 1, Rssi:51, RXQual:255, C1:30, C2:30, Bsic:0d, MA:0, MADed:65535 B:"G", Arfcn: 2, Rssi: 52, RXQual:250, C1:31, C2:31, Bsic:0e, MA:1, MADed:65534


Form #2: UMTS environment

+CGED: RAT:"UMTS" Cell-ID: DLF:<dlfVal>,ULF:<ulfVal>,Cell:<cellType>, SC:<scVal>, RSCP:<rscpVal>, ECN0:<pwrVal>

  • <dlfVal> : Downlink frequency. Range is [0...16383]
  • <ulfVal> : Uplink frequency. Range is [0...16383]
  • <cellType> : Cell type. Can be one of AS (active set) M (monitor set) D (detected set) U (ranked set) NU (non-ranked set)
  • <scVal> : Scrambling code. Range is [0..511]
  • <rscpVal> : Received signal code power. Range is [0..91]
  • <pwrVal> : EC/N0 value. Range is [0..24]

Cell values can be repeated once for each cell or neighbor cell. Additional values may be included and will be ignored.

Example:
+CGED: RAT:"UMTS" Cell-ID: DLF:123,ULF:456,Cell:AS, SC:1, RSCP:1, ECN0:29,Cell:M, SC:3, RSCP:1, ECN0:22





2.3. AT Commands used for clock calibration


Clock calibration is used to reduce the frequency uncertainty of the TCXO at the start of a position request. Successful clock calibration can help reduce time to first fix (TTFF) and improve sensitivity during initial acquisition of satellite signals. Broadcom GNSS chipsets can operate without calibration but it is highly recommended to achieve best performance.

Clock calibration occurs during the first few seconds of a new position request. A reference clock from the modem is wired to the Broadcom GNSS chipset to provide the calibration signal. Positioning software assumes there are times when the reference clock may be accurate for calibration and other times when the reference clock is not accurate and should be ignored. There are two supported methods for gpsd software to check reference clock status.

Method 1 - AT+CREG

This command is supported for existing modems that can not be modified to determine reference clock accuracy. This AT command reports registration status of the modem in the wireless network. It is assumed that if the modem is registered in the network, then refeference clock will be accurate. This command is deprecated and should only be used if modem software can not support another method.



Method 2 - AT+REFCLKFREQ

This proprietary command is recommended to avoid ambiguous reference clock status.

Command Syntax:
   AT+REFCLKFREQ=1          : Sent by gpsd to  enable unsolicited responses for reference clock status from the modem
   AT+REFCLKFREQ=0          : Sent by gpsd to disable unsolicited responses for reference clock status from the modem
   AT+REFCLKFREQ?           : Sent by gpsd to request current status of the reference clock


Response Syntax:
    +REFCLKFREQ:0,26000000,100,1

                            0 : Indicates the version ID for this command.  Always 0
                     26000000 : Indicates the nominal reference clock frequency, in Hertz.
                          100 : Indicates current reference clock nominal frequency uncertainty, in parts-per-billion (ppb)
                            1 : Indicates reference clock lock status.  0=Unlocked   1=Locked


NOTES:
   1)  Response to an AT command request and unsolicited response are identical syntax.
   2)  The modem should send an unsolicited response any time the reference clock lock status changes.
   3)  Gpsd software sends AT+CCLOCK command to enable and disable reference clock to the GNSS chipset.
   4)  Nominal reference clock frequency usually never changes for most designs.  Dual frequency designs may use two values.
   5)  Nominal reference clock values of 19.2, 26, and 38.4 MHz are currently supported.  Others can be added upon request.
   6)  Nominal frequency uncertainty may be any value but will be rounded up internally to 100ppb, 300ppb, or  'no clock'


It is very important for the modem to send unsolicited responses when any field in the +REFCLKCFREQ response changes. The gpsd task will also request current status multiple times during the calibration process. The modem should always send current lock status.



2.4. AT Command Protocol Details


Many XML strings are very long and may exceed the length of a normal buffer. It is possible to break up XML strings by sending many +CPOS: or +CPOSR: responses. Please refer to NOTE in 3GPP 27.007, section 8.55 and Section 8.56, for further description.

There are two special characters sent with the XML strings for +CPOS. Refer to 3GPP 27.007 section 8.55 for further description of these two special characters.

  • The modem may send the <ESC> character (decimal 27) to cancel any previous XML string without further processing. This is useful to resynchronize the gpsd after an error may have occured.
  • The modem must send the <ctrl-Z> charcter (decimal 26) at the end of an XML string to begin processing.



The gpsd will ignore all whitespace (tab, space, <CR> or <LF> characters) while processing XML string sequences. It is useful to include these characters for easier debugging.



2.5. Description of the +ECID: command and response


This command provides enhanced cell ID information for all supported RATs (GSM, WCDMA, LTE). Enhanced cell ID information includes serving cell and neighbor cell information. Gpsd will use this information to provide location IDs for SUPL 1.0 and 2.0, as well as ECID information for LTE cells when the LPP protocol is use for SUPL 2.0.

ECID information is requested at the start of a SUPL session. Gpsd will request ECID information using this command:

AT+ECID=0

The modem should respond to this command with the following syntax for each RAT. Each response should be a single line with each field below separted by a single comma. No field may be left blank. All numeric values are decimal.


+ECID=<version> ,RAT:,<Cell description>


<version>      Version of the response.  Zero is the initial version.

<RAT>          A string indicating the current used RAT.  Supported values are:
    NONE:
    GSM:
    WCDMA:
    LTE:

<Cell description> : A string indicating the cell environment. The description is specific for each RAT.  All parameters
                     are sent on a single line.  Parameter fields within a line are separated by a comma.  No parameter
                     field may be empty.  Multiple lines are used for clarity only in the descriptions below.

For NONE RAT:
------------
      NONE is used to indicate no cell ID information is available from the modem.  It is typically sent when the modem
      is in Flight mode or otherwise has no cell ID information.  Any data after the RAT type is ignored.

Example +ECID response from modem when no cell ID information is available:

+ECID=0,NONE:



For GSM RAT:
------------
+---------------------+
| GSM RAT - Version 0 |
+---------------------+
<MCC>,<MNC>,<LAC>,<CID>,<TA>,<NB_CELL>,
[<BSIC>,<ARFCN>,<RX_level>] * NB_CELL

with :
    <MCC>      Current Mobile Country Code: range 0 to 999
    <MNC>      Current Mobile Network Code: range 0 to 999
    <LAC>      Current Location Area Code: range 0 to 65535
    <CID>      Current Cell ID: range 0 to 65535
    <TA>       Current Timing Advance: range 0 to 63 or -1 for undefined
    <NB_CELL>  Number of neighbor cells: 0 to 15 (0 indicates that no neighbor cell is present)

For each neighbor cell:
    <BSIC>       BSIC, range 0 to 63
    <ARFCN>      Carrier number, range 0 to 1023
    <RX_level>   RX level, range 0 to 63


Example +ECID response from modem for GSM RAT, one serving cell and two neighbor cells:

+ECID=0,GSM:,310,410,6042,4626,3,2,1,653,39,19,234,36



For WCDMA RAT:
--------------
+-----------------------+
| WCDMA RAT - Version 0 |
+-----------------------+
<MCC>,<MNC>,<UCID>,<Primary Scrambling>,<UARFCN_UL>,<UARFCN_DL>,<NB_FREQ>,
[<UARFCN_UL>,<UARFCN_DL>,<UC_RSSI>, <CMR_NB>,
[<Cell_ID>,<Primary CPICH>, <CPICH Ec NO>, <CPICH_RSCP>, <Pathloss>] * CMR_NB ] * NB_FREQ

with:
    <MCC>                 Current Mobile Country Code. range 0 to 999
    <MNC>                 Current Mobile Network Code. range 0 to 999
    <UCID>                UCID of the serving cell. range 0 to 268435455
    <Primary Scrambling>  Primary scrambling code. range 0 to 511 or -1 for undefined
    <UARFCN_UL>           Uplink UARFCN. range 0 to 16383 or -1 for undefined
    <UARFCN_DL>           Downlink UARFCN. range 0 to 16383 or -1 for undefined
    <NB_FREQ>             Number of frequences. range 0 to 8 (0 indicates that no frequency is present)

For each frequency:
    <UARFCN_UL>  Uplink UARFCN. range 0 to 16383 or -1 for undefined
    <UARFCN_DL>  Downlink UARFCN. range 0 to 16383 or -1 for undefined
    <UC_RSSI>    UTRA Carrier RSSI. range 0 to 127 or -1 for undefined
    <NB_CMR>     Number of Cell Measured Results: 0 to 32 (0 indicates that no cell measure result is present)

For each cell measured:
    <Cell_ID>        UCID range 0 to 268435455 or -1 for undefined
    <Primary CPICH>  Primary CPICH: range 0 to 511 or -1 for undefined
    <CPICH Ec NO>    CPICH Ec NO: range 0 to 63 or -1 for undefined
    <CPICH_RSCP>     CPICH RSCP: range -4 to 127 or -127 for undefined
    <Pathloss>       Pathloss  range 46 to 173 or -1 for undefined


Example +ECID response from modem for WCDMA RAT, one serving cell, three frequencies, and thirty neighbor cells:

+ECID=0,WCDMA:,310,410,131353446,447,1314,1539,3,1314,1539,63,24,1,204,15,14,-1,2,183,-1,-127,-1,3,168,-1,-127,-1,4,104,7,10,-1,5,402,-1,-127,-1,6,186,-1,-127,-1,7,480,13,13,-1,8,420,-1,-127,-1,9,391,-1,-127,-1,10,374,14,14,-1,11,347,-1,-127,-1,12,167,-1,-127,-1,13,137,-1,-127,-1,14,99,-1,-127,-1,15,133,-1,-127,-1,16,199,-1,-127,-1,17,320,-1,-127,-1,18,470,-1,-127,-1,19,451,-1,-127,-1,20,120,-1,-127,-1,21,306,-1,-127,-1,22,411,-1,-127,-1,23,110,9,13,-1,24,144,-1,-127,-1,212,612,78,3,0,420,-1,-127,-1,1,402,-1,-127,-1,2,447,20,17,-1,1687,1912,83,3,3,447,18,14,-1,4,402,-1,-127,-1,5,420,-1,-127,-1



For LTE RAT:
------------
+---------------------+
| LTE RAT - Version 0 |
+---------------------+
NOTE: The first cell in each list is the serving cell, all others are neighbor cells.  Timing advance is only
      used for the serving cell.

<MCC>,<MNC>,<TAC>,<CI>,<NB_CELL>,
[<Cell Code>,<EARFCN>, <RSRP>, <RSRQ>, <TA> ] * NB_CELL

For each cell measured:
    <MCC>      Current MCC. range 0 to 999
    <MNC>      Current MNC. range 0 to 999
    <TAC>      Current TAC. range 0 to 65535 (Length of 16 bits)
    <CI>       Current Cell Identity. range 0 to 268435455   (Length of 28 bits)
    <NB_CELL>  Number of Cells. 0 to 9 (0 indicates that no cell measured result is present)

For each cell measured:
<Cell Code>  Physical cell ID. range 0 to 503
<EARFCN>     EUTRAN ARFCN. range 0 to 65535 or -1 for undefined.
<RSRP>       Reference Signal Received Power.  range 0 to 97 or -1 for undefined.
<RSRQ>       Reference Signal Received Quality.  range 0 to 34 or -1 for undefined
<TA>         Timing Advance.  range 0 to 1282 or -1 for undefined


Example +ECID response from modem for LTE RAT, one serving cell and seven neighbor cells:

+ECID=0,LTE:,310,410,35653,169078288,8,265,12345,60,25,256,289,23456,42,0,-1,290,34567,48,19,-1,19,45678,37,9,-1,20,56789,38,10,-1,21,01234,39,11,1,22,02345,40,12,2,23,03456,41,13,3




+---------------------+
| LTE RAT - Version 1 |
+---------------------+
NOTE: The first cell in each list is the serving cell, all others are neighbor cells.  Timing advance is only
      used for the serving cell.

NOTE: Version 1 changes:
   -  add optional parameters for SystemFrameNumber and ue-RxTxTimeDiff. 
   -  allow specifying MCC/MNC/CI/TAC for all cells individually
   -  increase number of possible cells to 1 serving cell + 32 neighbor cells, compliant with LPP
   -  Make MCC, MNC, CI, and TAC optional


<NB_CELL>
[<MCC>,<MNC>,<TAC>,<CI>,<Cell Code>,<EARFCN>, <RSRP>, <RSRQ>, <TA>, <SFN>, <RXTXDIFF>] * NB_CELL

For all cells:
    <NB_CELL>  Number of Cells. 0 to 33 (0 indicates that no cell measured result is present)

For each cell measured:
<MCC>        Current MCC. range 0 to 999, -1 for undefined
<MNC>        Current MNC. range 0 to 999, -1 for undefined, valid range is mandatory for SUPL 2.0 serving cell
<TAC>        Current TAC. range 0 to 65535 (Length of 16 bits), -1 for undefined, valid range is mandatory for SUPL 2.0 serving cell
<CI>         Current Cell Identity. range 0 to 268435455   (Length of 28 bits), -1 for undefined, valid range is mandatory for SUPL 2.0 serving cell
<Cell Code>  Physical cell ID. range 0 to 503, valid range is mandatory for all SUPL 2.0 and LPP cells
<EARFCN>     EUTRAN ARFCN. range 0 to 65535 or -1 for undefined, valid range is mandatory for all LPP neighbor cells
<RSRP>       Reference Signal Received Power.  range 0 to 97 or -1 for undefined.
<RSRQ>       Reference Signal Received Quality.  range 0 to 34 or -1 for undefined
<TA>         Timing Advance.  range 0 to 1282 or -1 for undefined
<SFN>        System Frame Number, range 0 to 1023 or -1 of undefined
<RXTXDIFF>   ue-RxTxTimeDiff, range 0 to 4095 or -1 of undefined


NOTE:  Most parameters are optional to allow compliance with SUPL 2.0 and LPP requirements.  Relevant specifications should be
       consulted to determine requirements for each project.

Example +ECID response from modem for LTE RAT, one serving cell and three neighbor cells:

+ECID=0,LTE:,8,310,410,35653,169078280,265,12345,60,25,256,1011,3922,310,410,35653,169233211,289,23456,42,0,-1,1021,321,310,410,35653,9322832,290,34567,48,19,-1,322,405









2.6. Description of the %LPPIE command and response


The LPPIE command is a general interface that allows information elements (IEs) to be passed between the modem and gpsd. This command supports the LPP protocol between network and gpsd. This command supports ECID and OTDOA measurement methods between modem and gpsd.

ECID support is an alternative location method to use for E911 requests for some operators that support VoLTE. The ECID method is supported using the LPP payload and is only use when the LPP protocol is used for LTE cells (not RRLP, not GSM or WCDMA). The LPP protocol provides a slightly different list of parameters from what is provided by the SUPL Location Identifiers. Gpsd software only provides the SUPL message interface between the modem and network server, it does not perform or participate in the ECID measurement process.

OTDOA support is an alternative location method to use for E911 requests for some Operators who support VoLTE. Some North American Operators have a requirement that OTDOA be supported over SUPL 2.0. The gpsd provides the SUPL 2.0 client software. OTDOA measurements are performed completely within the modem hardware and gpsd is only the SUPL message interface between the modem and network server. OTDOA information must pass between the modem and gpsd. Gpsd software only provides the SUPL message interface between the modem and network server, it does not perform or participate in the OTDOA measurement process.

Gpsd supports ECID and OTDOA by sending ASN.1 encoded data between modem and gpsd. This interface defines AT commands for the following Information Elements:

Modem Inputs 36.355 Information Elements
Network wants to know OTDOA capabilities of the modem OTDOA-RequestCapabilities
Network wants OTDOA measurements OTDOA-RequestLocationInformation
Network is sending OTDOA assistance to the modem OTDOA-ProvideAssistanceData
Network wants to know ECID capabilities of the modem ECID-RequestCapabilities
Network wants ECID measurements ECID-RequestLocationInformation


Modem Outputs 36.355 Information Elements
Modem sends OTDOA capabilities to the network OTDOA-ProvideCapabilities
Modem sends OTDOA measurements to the network OTDOA-ProvideLocationInformation
Modem needs OTDOA assistance OTDOA-RequestAssistanceData
Modem sends ECID capabilities to the network ECID-ProvideCapabilities
Modem sends ECID measurements to the network ECID-ProvideLocationInformation


Please notice these are Information Elements only, not the entire PDU. Information Elements must be aligned to the most significant bit (MSB) of the first byte in the <data> field, described below.

The AT command interface supports passing these six information elements as ASN.1 encoded data. AT command sequences are described below to allow sending an IE in either direction between the modem and gpsd. ASN.1 data should be encoded according to the IE descriptions found in this document:

Document: 3GPP TS 36.355 version 10.4.0 Release 10
Date: 2011-12-21




Command Syntax:

   AT%LPPIE=<version>,<sessionId>,<type>,<msgNum>,<maxMsgs>,<extraInfo>,<data>



Field Description
%LPPIE AT command prefix for this custom command. The modem should not send the “AT” string when sending an IE to gpsd.
<version> A numeric version number for this message. This should be 0 for the initial release, other values are reserved for future use.
<sessionId> A numeric session ID used to track requests and responses. Range is [0..4294967295]. Sessions are restricted so that only one may be active at any time.
<type>

Specifies the kind of Information Element represented in the data. Values are:

Value Information Element Source Destination
1 OTDOA-RequestCapabilities gpsd modem
2 OTDOA-ProvideCapabilities modem gpsd
3 OTDOA-RequestAssistanceData modem gpsd
4 OTDOA-ProvideAssistanceData gpsd modem
5 OTDOA-RequestLocationInformation gpsd modem
6 OTDOA-ProvideLocationInformation modem gpsd
7 Reserved - do not use N/A N/A
8 Reserved - do not use N/A N/A
9 Reserved - do not use N/A N/A
10 Reserved - do not use N/A N/A
11 ECID-RequestCapabilities gpsd modem
12 ECID-ProvideCapabilities modem gpsd
13 ECID-RequestLocationInformation gpsd modem
14 ECID-ProvideLocationInformation modem gpsd


Additional Information Elements may be defined in the future

<msgNum>

Counting sequence for multi-part ASN.1 sequences. Start at 1, counts up sequentially with each AT command until reaching <maxMsgs>

<maxMsgs>

The total number of lines to expect in this IE. The IE can not be processed further until all elements for it have arrived.

<extraInfo>

Contains additional information not encoded in the ASN.1 data. This field should be set to -9999 if it is not required. The only current purpose for this field is to contain the responseTime (in seconds) when gpsd sends ECID-RequestLocationInformation or OTDOA-RequestLocationInformation to the modem.

<data>

ASCII string of hexadecimal values. Each character represents four bits of the IE. A maximum of 64 data bytes (128 characters in <data>) may be sent in one string. If the string is longer, multiple commands should be used to send the IE. All characters are limited to the range of [0123456789ABCDEF].

The number of ASCII characters in the <data> portion for each line must be a multiple of 2. The <data> field shall start and end with the character ' " ' (quotation mark) to conform to AT command rules for strings. The first (left-most) character representing each data byte shall contain the most significant four bits, the second character of each data byte shall contain the least significant four bits.



The message structure for %LPPIE will allow any IE of any length to be sent. Each AT command length is limited to avoid problems with large data through the transport layer. Lines may be shorter than the maximum data length. The destination can know when the entire IE has arrived because <msgNum> will equal <maxMsgs>. The maximum line length is about 150 characters and will allow printing in log files.

All message transmission must obey the rules of AT command transport. This means each AT command from gpsd to modem must be acknowledged by "OK" or "ERROR" and all lines should be terminated by the usual <cr><lf> found on every AT command and response.



%LPPIE Example 1:

Send OTDOA-RequestCapabilities from gpsd to modem with session ID of 42. <Data> is random and not a valid IE, for example only. Lines are shorter than maximum length for clarity in this example:

AT%LPPIE=0,42,1,1,3,-9999,"39359f9B9C54BCA333"
AT%LPPIE=0,42,1,2,3,-9999,"B983A431C8CC3221AB"
AT%LPPIE=0,42,1,3,3,-9999,"1A33647BC83F30"



%LPPIE Example 2:

Send OTDOA-ProvideCapabilities from modem to gpsd with session ID of 137. <data> is random and not a valid IE, for example only. Lines are shorter than maximum length for clarity in this example:

%LPPIE=0,137,2,1,6,-9999,"4983811100098A7FDE"
%LPPIE=0,137,2,2,6,-9999,"023F9B8AA77654CCD1"
%LPPIE=0,137,2,3,6,-9999,"BBA78DCEFA98720981"
%LPPIE=0,137,2,4,6,-9999,"980B00313333EA77AC"
%LPPIE=0,137,2,5,6,-9999,"94939BFEEDAAAB98C3"
%LPPIE=0,137,2,6,6,-9999,"44D93FC9300A"





3. About the Stub and the Test Code


(NOTE: This section may be ignored if the modem provider supports the Unix socket or named pipes directly.)
The stub provides an API to send and receive strings from the modem to the gpsd.
It is also possible to send and receive strings directly to a TCP socket or create a custom function API. Refer to the source code shown in the files below for details on how to open a TCP socket and send/receive commands and responses.
A single TCP pipe is used to send commands and responses. The receiving end is responsible for correct parsing to separate commands from responses and handle each correctly.
The stub is comprised of following files.

allPartners/deliverables/glhal/unix/3GPPAT/inc/brcm_ril_at.h
allPartners/deliverables/glhal/unix/3GPPAT/inc/brcm_ril_at_config.h
allPartners/deliverables/glhal/unix/3GPPAT/src/brcm_ril_at_client.c
customers/$(CUST)/$(PLAF)/include/brcm_ril_at_config_custom.h

(Note: brcm_ril_at_config.h and brcm_ril_at_config_custom.h contains adjustable parameter information where you may change CP socket path or packet size, etc.)

We have prepared a sample test code and Makefile using the stub.

allPartners/deliverables/glhal/unix/3GPPAT/src/Makefile
allPartners/deliverables/glhal/unix/3GPPAT/src/brcm_ril_at_client_test.c

Please run this in order to compile the test code.

$ cd allPartners/deliverables/glhal/unix/3GPPAT/src/
$ make brcm_ril_at_client_test

This is the usage of the test application.

// allPartners/deliverables/glhal/unix/3GPPAT/src/brcm_ril_at_client_test.c
static void printSyntax(int argc, char **argv)
{
    printf("%s: The 3GPP 27 AT-command-based Control Plane tester v1.0\n", argv[0]);
    printf("Syntax: %s <rand_seed> <socket_path> <task_id>\n", argv[0]);
    printf("This simulation tester inject the archived assistance packets to our control plane module. ");
    printf("Please note that you might not get the matching GPS signal for these assistance data set. ");
    printf("Therefore, if you want to truly verify the interoperability with the modem implementation, you might want to use UMTS(ULTS) directly.\n");
    printf("rand_seed: Input 0 for automatic time-based random seed.\n");
    printf("\ttask %d: The basic pos_meas insertion.\n", TASK_SIMPLE);
    // ...
    printf("\ttask %d: Multiple instance of random AT+CPING. You should provide the repeat number after the task number.\n", TASK_MULTIPLE_CPING);
}

4. Integration Points

The actual integration points are following as shown in allPartners/deliverables/glhal/unix/3GPPAT/src/brcm_ril_at_client_test.c file.

4.1. Handler Initialization

This is how we initialize the AT-command handler.

// allPartners/deliverables/glhal/unix/3GPPAT/src/brcm_ril_at_client_test.c
    OsHandle *ath;
    // Registers the AT-command Control Plane handle to SOCKET_3GPP_PATH.
    if ((ath = BrcmGpsRilATInit(target_socket_path, ulsend, NULL)) == OS_HANDLE_INVALID)
    {
        LOG("Error initializing\n");
        return 1;
    }

Eventually, it gives the CP socket path, AT-command receiving function "ulsend", and reserved pointer (currently NULL). It is the implementer's responsibility to make ulsend() function to be connected to the real AT-command handler from the modem side. On the other hand, when the modem wants to send AT-command to the GPS daemon, simply use BrcmGpsRilDlSend() function.

4.2. Handler Finalization

This is how we deinitialize the AT-command handler.

// allPartners/deliverables/glhal/unix/3GPPAT/src/brcm_ril_at_client_test.c
    BrcmGpsRilATDestroy(ath);

4.3. Data Transfer

After you initialize the AT-command handler via BrcmGpsRilATInit, the function will create a socket listening thread in that process. When it receives AT-command data from the GPS daemon it will call the "ulsend" the callback function responsible for handling the AT-command and hand the AT-command to the modem. On the other hand, when the modem have AT-command to send to the GPS daemon it calls BrcmGpsRilDlSend() function like following.

// allPartners/deliverables/glhal/unix/3GPPAT/src/brcm_ril_at_client_test.c
static void injectATCmd(OsHandle ath, const char* atCmd, size_t atCmdSz)
{
    ASSERT(atCmdSz <= AT_3GPP_PACKET_SIZE_MAX);
    // Inject a AT-command request. Printout without the end part (Ctrl-Z,NULL)
    LOG("Received an AT command (size=%d):\n%.*s\n\n", (int)atCmdSz, (int)(atCmdSz - SENTENCE_END_SZ - 1), atCmd);
    BrcmGpsRilDlSend(ath, atCmd, atCmdSz);
}

5. SDK and XML Preparation

5.1. Compile Option

The 3GPP AT-command Control Plane feature is enabled when the SDK includes the compile option of CONFIG_HAL_CP_3GPP="true" or "yes". The GPS daemon with this compile option will create an internal Unix socket (the path will be explained 5.2. XML Configuration) which will listen to the stub's connection request.

5.2. XML Configuration

NOTE: Please do not confuse between the GPS system's XML and +CPOS/+CPOSR's XML. This section discusses the GPS system's XML configuration.
These are the set of XML configuration parameters enabled when you include 3GPP Control Plane compile option.

  • cpApiSockName: [string (default: AT_3GPP_SOCKET_DEFAULT)] This XML parameter will set the path of the 3GPP Control Plane Unix socket explained in 5.1. Compile Option to be this system path. Please set this path to the system path appropriately secured.
  • cp-guard-time-sec: [integer (default: 0)] This XML parameter counts in the actual IPC delay caused between GPS <-> IPC <-> RIL layers. Sometimes due to 300~800ms delay, Spirent ULTS system declares failure to the successful GPS Control Plane session. Therefore the actual time taken for GPS system is following. Please note that usually this XML parameter is one second. If this value is over one, there might be slight GPS performance degradation.
    • RRLP: resp_time_seconds - cp-guard-time-sec
    • RRC: rep_interval_long - cp-guard-time-sec
  • cp-force-coldstart: ["true"/default "false"] This XML parameter will cause all the Control Plane GPS session to always delete assistance when the session is begun. In the real world, you do not need this option, but you might need this option in virtual setting like Spirent ULTS environment.
  • cp-3gpp-wait-OK: ["true"/default "false"] This XML parameter will enforce GPS system to wait for "OK\r" acknowledgement before sending the next AT-command to the RIL layer. This option helps the modem layer from choking up with too much AT-command sent from the GPS system.
  • cp-3gpp-raw-mode: ["true"/default "false"] This XML parameter will mimic the GPS system as if it is typing AT-command via modem's hyper-terminal when writing +CPOS command. In other words, it will wait for "\r\n" before writing +CPOS XML data.






6. Message Sequences used between the gpsd and modem

This section contains message sequence diagrams that show the exact sequence of commands and responses. Long XML strings are deleted for clarity.




6.1 Startup Initialization Sequence

msc_inline_mscgraph_1




6.2 Position Request Sequence

Please note that the sequence of the messages in this section is not rigid. For example, there may be multiple instances of "+CPOS: <GPS_assist_req>". +REFCLKFREQ and +CPOS/+CPOSR are separate AT-command flow which may interleave.

msc_inline_mscgraph_2




6.3 Possible Responses

There are three possible responses to the modem for each position request. Only one of following three responses will be sent to the modem.

  • Position attempt failure
  • UE-Assisted success
  • UE-Based success
msc_inline_mscgraph_3




User Privacy Popup Notification Sequence

This sequence shows the case where the UE user interacts with Android privacy popup notification message. Please refer to section 2.1. Description of the +CMTLR: response for AT-command description.

msc_inline_mscgraph_4
  1. Notification message may vary. (ex. +CMTLR: 123, 1, 0, "+0123456", "XYZ network",0) Usually <client-name> field may not be simple ASCII due to localization, please pay extra attention on <client-name> field.
  2. Internally, this will involve HAL layer to use SUPL layer which will eventually use Android's native popup interface.
  3. 3GPP 27.007 Section 8.58: allow 0 and disallow 1
  4. After +CMTRLA receiving, the network may proceed to 6.2 Position Request Sequence.






7. Examples of Message Transactions

This section shows examples of various AT commands and XML syntax. It is not intended as a complete reference but serves as a guide to show what is possible.


Example 1 - Unsolicited +CPOSR: response from modem to gpsd with GPS Reference Time assistance

+CPOSR: <?xml version="1.0" encoding="UTF-8"?>
<pos xsi:noNamespaceSchemaLocation="pos.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<assist_data>
    <GPS_assist>
        <ref_time>
            <GPS_time>
                <GPS_TOW_msec>519007280</GPS_TOW_msec>
                <GPS_week>282</GPS_week>
            </GPS_time>
        </ref_time>
    </GPS_assist>
</assist_data>
</pos>



Example 2 - Unsolicited +CPOSR: response from modem to gpsd with GPS Reference Location assistance

This example indicates the following:

  • 33.750000N Latitude
  • 84.383519E Longitude
  • 300 meters altitude
  • 3034 meters horizontal uncertainty
  • 500 meters vertical uncertainty
  • 68% confidence


+CPOSR: <?xml version="1.0" encoding="UTF-8"?>
<pos xsi:noNamespaceSchemaLocation="pos.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<assist_data>
    <GPS_assist>
        <location_parameters>
            <shape_data>
                <ellipsoid_point_alt_uncertellipse>
                    <coordinate>
                        <latitude>
                            <north>0</north>
                            <degrees>3145728</degrees>
                        </latitude>
                        <longitude>-3932557</longitude>
                    </coordinate>
                    <altitude>
                        <height_above_surface>0</height_above_surface>
                        <height>300</height>
                    </altitude>
                    <uncert_semi_major>60</uncert_semi_major>
                    <uncert_semi_minor>60</uncert_semi_minor>
                    <orient_major>0</orient_major>
                    <confidence>68</confidence>
                    <uncert_alt>101</uncert_alt>
                </ellipsoid_point_alt_uncertellipse>
            </shape_data>
        </location_parameters>
    </GPS_assist>
</assist_data>
</pos>



Example 3 - Unsolicited +CPOSR: response from modem to gpsd with aquisition assitance and multiple +CPOSR:
This is a good example of fragmented +CPOSR messages. Please note the '' ASCII character after "<sat_id>16</sat", which is equal to <Ctrl-z> control character that divides the fragmented CPOSR response packets.

+CPOSR: <?xml version="1.0" encoding="UTF-8"?>
<pos xsi:noNamespaceSchemaLocation="pos.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<assist_data>
    <GPS_assist>
        <acqu_assist>
            <tow_msec>519007280</tow_msec>
            <sat_info>
                <sat_id>1</sat_id>
                <dopl0>-974</dopl0>
                <code_ph>443</code_ph>
                <code_ph_int>3</code_ph_int>
                <GPS_bitno>0</GPS_bitno>
                <srch_w>10</srch_w>
                <az_el>
                    <az>9</az>
                    <elev>2</elev>
                </az_el>
            </sat_info>
            <sat_info>
                <sat_id>5</sat_id>
                <dopl0>265</dopl0>
                <code_ph>1011</code_ph>
                <code_ph_int>10</code_ph_int>
                <GPS_bitno>0</GPS_bitno>
                <srch_w>6</srch_w>
                <az_el>
                    <az>25</az>
                    <elev>5</elev>
                </az_el>
            </sat_info>
            <sat_info>
                <sat_id>9</sat_id>
                <dopl0>-969</dopl0>
                <code_ph>768</code_ph>
                <code_ph_int>7</code_ph_int>
                <GPS_bitno>0</GPS_bitno>
                <srch_w>8</srch_w>
                <az_el>
                    <az>4</az>
                    <elev>4</elev>
                </az_el>
            </sat_info>
            <sat_info>
                <sat_id>16</sat
+CPOSR: _id>
                <dopl0>-325</dopl0>
                <code_ph>730</code_ph>
                <code_ph_int>9</code_ph_int>
                <GPS_bitno>0</GPS_bitno>
                <srch_w>7</srch_w>
                <az_el>
                    <az>6</az>
                    <elev>5</elev>
                </az_el>
            </sat_info>
            <sat_info>
                <sat_id>17</sat_id>
                <dopl0>1037</dopl0>
                <code_ph>608</code_ph>
                <code_ph_int>19</code_ph_int>
                <GPS_bitno>3</GPS_bitno>
                <srch_w>10</srch_w>
                <az_el>
                    <az>22</az>
                    <elev>2</elev>
                </az_el>
            </sat_info>
            <sat_info>
                <sat_id>20</sat_id>
                <dopl0>1090</dopl0>
                <code_ph>31</code_ph>
                <code_ph_int>1</code_ph_int>
                <GPS_bitno>0</GPS_bitno>
                <srch_w>10</srch_w>
                <az_el>
                    <az>27</az>
                    <elev>2</elev>
                </az_el>
            </sat_info>
            <sat_info>
                <sat_id>25</sat_id>
                <dopl0>874</dopl0>
                <code_ph>466</code_ph>
                <code_ph_int>11</code_ph_int>
                <GPS_bitno>0</GPS_bitno>
                <srch_w>6</srch_w>
                <az_el>
                    <az>14</az>
                    <elev>5</elev>
                </az_el>
            </sat_info>
        </acqu_assist>
    </GPS_assist>
</assist_data>
</pos>



Example 4 - +CPOS command from gpsd to modem with failed position response

AT+CPOS <?xml version="1.0" encoding="UTF-8"?>
<pos>
   <pos_err>
      <err_reason literal="not_enough_gps_satellites"></err_reason>
   </pos_err>
</pos>






Appendix A. Unsupported XML fields in +CPOSR

Currently, there are unsupported XML fields in +CPOSR due to technical/insignificance reasons. Please note that this is excerpt of our XSD definition. (allPartners/deliverables/glhal/unix/3GPPAT/pos_new.xsd)

<xs:element name="shape_data">
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element name="polygon">
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element name="ellips_arc">

<xs:element name="location_parameters">
    <!-- Currently not implemented. It's not mandatory. -->
    <xs:element name="velocity_data">

<xs:element name="GPS_assist">
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element name="status_health" type="xs:integer" minOccurs="0"/>
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element name="BTS_clock_drift" type="xs:integer" minOccurs="0"/>
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element ref="DGPS_corrections" minOccurs="0"/>
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element ref="ionospheric_model" minOccurs="0"/>
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element ref="UTC_model" minOccurs="0"/>
    <!-- Currently not implemented. It is not mandatory. -->
    <xs:element ref="GPS_rt_integrity" minOccurs="0"/>

    <xs:element name="sat_status">
        <!-- Existing satellite, Uncompressed -->
        <!-- Currently not implemented. -->
        <xs:enumeration value="ES_NN-U"/>
        <!-- New satellite, Compressed -->
        <!-- Currently not implemented. -->
        <xs:enumeration value="NS_NN"/>
        <!-- Existing satellite, Compressed -->
        <!-- Currently not implemented. -->
        <xs:enumeration value="ES_SN"/>

    <xs:element name="RRLP_method_type">
        <!-- Currently not implemented. -->
        <xs:element ref="ms_based_pref"/>
        <!-- Currently not implemented. -->
        <xs:element ref="ms_assisted_pref"/>

    <xs:element name="RRC_method_type">
        <!-- Currently not implemented. -->
        <xs:enumeration value="ue_based_pref"/>
        <!-- Currently not implemented. -->
        <xs:enumeration value="ue_assisted_pref"/>

    <xs:attribute name="rep_amount" use="ra-Infinity">
        <!-- Currently not implemented. -->
        <xs:enumeration value="ra2"/>
        <!-- Currently not implemented. -->
        <xs:enumeration value="ra4"/>
        <!-- Currently not implemented. -->
        <xs:enumeration value="ra8"/>
        <!-- Currently not implemented. -->
        <xs:enumeration value="ra16"/>
        <!-- Currently not implemented. -->
        <xs:enumeration value="ra32"/>
        <!-- Currently not implemented. -->
        <xs:enumeration value="ra64"/>

    <xs:attribute name="rep_interval_long" use="required">
        <!-- Currently not implemented. Too short. -->
        <xs:enumeration value="ril0"/>
        <!-- Currently not implemented. Too short. -->
        <xs:enumeration value="ril0-25"/>
        <!-- Currently not implemented. Too short. -->
        <xs:enumeration value="ril0-5"/>

Please note that we can implement all of the unimplemented fields except:

  • DGPS correction,
  • BTS_clock_drift,
  • UTC_model Above three fields needs additional technical implementation/integration.
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines