ENF0000CB001

API Reference

Programmers Guide
Version: 2.01

24 June, 2013

General
TERMS OF USE OF NEW MATERIALS - PLEASE READ CAREFULLY
From time to time, Novatel Wireless M2M, in its sole discretion, may make available for
download on its website (www.nvtl.com), or may transmit via mail or email, updates or
upgrades to, or new releases of, the firmware, software or documentation for its products
(collectively, 'New Materials'). Use of such New Materials is subject to the terms and
conditions set forth below, and may be subject to additional terms and conditions as set forth
in Novatel Wireless M2M's Technical Support Policy (posted on its website) and/or any
written agreement between the user and Novatel Wireless M2M.
All New Materials are provided AS IS. Novatel Wireless M2M makes no warranty or
representation with respect to the merchantability, suitability, functionality, accuracy or
completeness of any such New Materials. The user of such New Materials assumes all risk
(known or unknown) of such use. Novatel Wireless M2M reserves all rights in such New
Materials. The user shall have only a revocable and limited license to use such New Materials
in connection with the products for which they are intended. Distribution or modification of
any New Materials without Novatel Wireless M2M's consent is strictly prohibited.
IN NO EVENT WILL Novatel Wireless M2M BE RESPONSIBLE FOR ANY INCIDENTAL,
INDIRECT, CONSEQUENTIAL OR SPECIAL DAMAGES AS A RESULT OF THE USE OF ANY
NEW MATERIALS. Novatel Wireless M2M'S MAXIMUM LIABILITY FOR ANY CLAIM BASED
ON THE NEW MATERIALS SHALL NOT EXCEED FIFTY U.S. DOLLARS ($50).

Version Verification
Please ensure you have the latest version of this document by downloading it from
www.nvtl.com

-i-

Copyright
2013 Novatel Wireless M2M, Inc. All rights reserved. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording or
otherwise), or for any purpose, without the express written permission of Novatel Wireless
M2M, Inc.
Novatel Wireless M2M and the Novatel Wireless M2M logo are either registered trademarks or
trademarks of Novatel Wireless M2M, Inc. in the United States.
251 Renner Pkwy
Richardson, TX 75080 USA
Phone: (972) 633-4400
Fax: (972) 633-4444
Email: [email protected]
www.nvtl.com

- ii -

Table of Contents
1 Introduction

Overview

2 Modem Communication

Serial Communication

Over The Air Communication

3 AT Commands Over DUN Or OTA

IP Header

UDP Header

TCP Header

10

API Header

11

Wakeup Messages

13

Send Password To Modem

14

Read/Write AT Command Request

14

Unsolicited Messages

15

UDP API

15

TCP API

16

ACK Messages

16

ERROR Messages

17

API Optional Header

17

End Of Option Sequence Type 0

19

MDMID Type 1

20

Output Message Event Format- Type 2

21

Event Sequence Number Type 3

22

Firmware Version - Type 4

22

Cause Code Type 5

22

Output Event Number Type 6

23

- iii -

Hex Modem ID Type 7

23

Driver ID Type 8

24

Param 3 Type 9

25

FOTA Complete Message

25

26

4 Terms Explained

26
Byte

27

Big Endian

27

Little Endian

27

28

5 Example
Sending AT Command

29

Response From Modem To Host:

30

Receiving UDP ASCII Event Data With Option Header MDMID And Sequence Number
Enabled

- iv -

31

1
Introduction
Overview

-1-

Overview
This document describes the Application Program Interface (API) for Novatel Wireless M2Ms
modems.
With this API, programmers can access information and control modem functions in real-time.
The API gives a wide-range of information and includes modem management and status
functions.
The API is most useful if you are considering a customized application that includes:
mandatory real-time performance parameters
a status window that reports performance
an indicator for when network conditions begin to degrade
consistent data updates during an established session
Though not required, many host computers that use this API contain a TCP/IP stack, which
includes UDP and Point-to-Point Protocol (PPP). This API includes documents that detail how
to create your own UDP and PPP formatting for a minimal implementation.

This document contains proprietary information and must not be reproduced without the prior written
consent of Novatel Wireless M2M, Inc. (Novatel Wireless M2M).

-2-

2
Modem Communication
Serial Communication
Over The Air Communication

-3-

Most AT commands may be read and/or written via UDP/IP or TCP/IP.

The AT command state is entered upon power-up/reset. The modem always starts in AT
command mode. Use Windows HyperTerminal or a similar application to send AT commands
to the modem. Connect directly to the COM port used by the modem.
If you do not require real-time status/control, the AT Command set may offer an easier
integration alternative. Refer to the applicable AT Command Reference document for a list of
AT commands.
You may choose to use AT Commands to configure the modem and/or start Network
registration before switching to the UDP/IP or TCP/IP messaging for real-time status during
data transfers.
You can communicate with the modem via one of the two possible methods:
l
l

RS232 Serial communication

Over The Air (OTA) via SMS or Data Network

Serial Communication
The modems default serial communication is set at 115200 baud, no parity, 8 data bits, 1 stop
bit, and with hardware flow control enabled. A user can send/receive AT commands, data, or
respond to/from the modem via one of the two methods:
l
l

Straight serial communication via HyperTerminal or similar application

Serial communication via Dial-Up Network (DUN)

Straight serial communication provides the following capabilities:

l
l
l
l

Send AT commands/receive response

Receive SMS notification
Make a voice, data, or fax call
Receive any unsolicited message

Serial communication via DUN provides the following capabilities:

l
l

l
l
l

Send and receive UDP/IP and/or TCP/IP data

Surf the Internet (provided that a data service is provided by the service provider) via
Internet Explorer or similar application software
Send AT commands via UDP/IP. The destination IP address and port number for AT
commands sent via UDP/IP can be configured via AT$UDPAPI command
Make a voice or fax call by sending AT commands via UDP/IP
Receive SMS notification via UDP/IP
Receive any unsolicited message via UDP/IP

-4-

Over The Air Communication

A user can send/receive AT commands to configure the modem OTA via UDP/IP or TCP/IP.
Configuration command request has to be sent at the modems IP address and port number
configured by AT$UDPAPI command for UDP/IP or AT$TCPSRC command for TCP/IP. A user
must make sure that they do not send non-configuration IP data at this port or the modem will
ignore it.

-5-

3
AT Commands Over DUN Or OTA
IP Header
UDP Header
TCP Header
API Header

-6-

The figure below describes the communication between a modem and a PC (or any RS232
compatible device) via a Dial-Up Network (DUN) connection. To send and receive AT
commands over UDP/IP, a user must first create the message and then encapsulate it within a
UDP/IP header. DUN connection must be established before the message is sent to the
modem. The modem will process the request and respond appropriately.

Figure 3-1 Communication Flow Chart

Please note that API communication using the TCP protocol is ONLY available over the air
(OTA). The TCP protocol is not operable over a PPP link. The UDP version of the API should
be used for serial communication.
Table 1 describes the details of an AT command sent to the modem via UDP/IP over a DUN
session. The host computer or remote host will send all messages, and the modem will
respond. The modem may generate unsolicited UDP/IP messages (if subscribed).
Table 2 describes the details of an AT command sent to the modem via TCP/IP over the air.
The host computer or remote host will send all messages, and the modem will respond. The
modem may generate unsolicited TCP/IP messages (if subscribed).
The data order for all fields is big endian (most significant byte first).
As described below, most of the fields within the UDP and IP headers will remain constant for
all messages. The fields that need modifying are: Length of IP Packet, Packet Number, IP
header checksum, Source IP, Destination IP, Source Port number, Destination port numbers,
UDP packet length, and UDP checksum.

-7-

Bytes

Bits 0 7

Bits 8 15

0 3

Version length

Type Of Service

4 7
8 11

Bits 16 23

Header Information

Length of the IP Packet

Packet Number
Time To Live

Bits 24 31

IP Header

Fragmentation Offset
Protocol

IP header checksum

12 15

Source IP

16 19

Destination IP

20 23

Source Port Number

Destination Port Number

24 27

Length of UDP Packet

UDP Checksum

28 31

API Number

Command Type

32 thru (32+m)

API Optional Header (m bytes)

(32+m) thru n

Data/AT command

API Optional Header

Size (bytes)

UDP Header

API Message Header

Data

Table 3-1 ATI command sent via UDP/IP

Bytes

Bits 0 7

Bits 8 15

0 3

Version length

Type Of Service

4 7
8 11

Bits 16 23

Protocol

IP header checksum
Source IP

16 19

Destination IP
Source Port Number

Destination Port Number

24 27

Sequence Number

28 31

Acknowledge Number

32 35

Data Offset + Control Bits

Window

36 39

TCP header checksum

Urgent Pointer

40 43

Data Length*

API Number

44 47

Command Type

IP Header

Fragmentation Offset

12 15

20 23

Header Information

Length of the IP Packet

Packet Number
Time To Live

Bits 24 31

API Optional Header

Size (bytes)

API Optional Header (m bytes) or Data/AT command

48 thru (46+m)

API Optional Header or Data/AT command (cont)

(46+m) thru n

Data/AT command

TCP Header

API Message Header

/Data

* Only used for API commands sent via TCP/IP

Table 3-2 ATI command sent via TCP/IP

IP Header
The Internet Protocol (IP) header consists of 20 bytes. The definition and minimal
implementation consists of the following:

-8-

Data

Bytes

Bits 0 7

Bits 8 15

0 3

Version length

Type Of Service

4 7
8 11

Bits 16 23

Length of the IP Packet

Packet Number
Time To Live

Bits 24 31

Fragmentation Offset
Protocol

IP header checksum

12 15

Source IP

16 19

Destination IP

Table 3-3 IP Header (RFC 791)

Byte 0

8-bit field for version and length. This API only supports version 4 with IP header
length of 5*4=20 bytes. This field must be set to 0x45.

Byte 1

8-bit type of service. The API ignores this field. This field must be set to 0x00.

Bytes 2 - 3 16-bit total length of packet. This field must be changed for each API message. It
includes the message data, IP header, and UDP header. This field equals data length +
28 (size of UDP and IP headers).
Bytes 4 - 5 16-bit identification. This field may be incremented for each packet. It is not required
and may be left 0x0000.
Bytes 6 7:

16-bit Fragmentation offset. The API ignores this field. This field must be set to
0x0000.

Bytes 8

8-bit Time to live. The API ignores this field. This field must be set to 0x00.

Bytes 9

8-bit Protocol. The API only supports UDP. This field must be set to 17 (0x11).

Bytes 10 11

16-bit IP header checksum.

Bytes 12 15

32-bit source IP address. For messages from the host to the modem, this is the IP
address of hosts UDP port. This IP address may be any valid IP address desired by
the users application, but will need to match the hosts TCP/IP stack. This IP address
will be used as the destination IP address for all response messages from the modem.

Bytes 16 19

32-bit destination IP address. For messages from the host to the modem, this is the IP
address of modems UDP API port. This IP address may be configured using AT commands if desired. This IP address will be used as the source IP address for all
response messages from the modem. The default IP address for the modems UDP
API is 199.245.180.13. Unless changed via AT commands, byte 16 will be 199 (0xC7),
byte 17 will be 245 (0xF5), byte 18 will be 180 (0xB4), and byte 19 will be 13 (0x0D).

UDP Header
The User Datagram Protocol (UDP) header consists of 8 bytes. The definition and minimal
implementation consists of the following (see RFC 768 for further details):
Bytes

Bits 0 7

Bits 8 15

Bits 16 23

Bits 24 31

0 3

Source Port Number

Destination Port Number

4 7

Length of UDP Packet

UDP Checksum

-9-

Table 3-4 UDP Header (RFC 768)

Bytes 0 - 1 16-bit source port number. For messages from the host to the modem, this is the
source port number of the hosts UDP port. This port may be any number desired by
the users application. This number will be used as the destination port for all
response messages from the modem.
Bytes 2 3

16-bit destination port number. For messages from the host to the modem, this is the
port number of the modems UDP API port. The modems UDP API port number may
be changed using AT commands (AT$UDPAPI) if desired. The modems default UDP
API port number is 1720 (0x06B8).

Bytes 4 5

16-bit length of UDP packet. This is the data length only; it does not include the IP
header length. This length must be filled in for each message depending upon the
amount of data in the packet.

Bytes 6 7

16-bit UDP checksum. This checksum may be used to validate the UDP packet. If the
value is 0, then the checksum is ignored.

TCP Header
The Transmission Control Protocol (TCP) header consists of 20 bytes. The definition and
minimal implementation consists of the following (see RFC 793 for further details):

Bytes

Bits 0 7

0 3

Source Port Number

4 7

Sequence Number

8-11

Acknowledgement Number

12-15

Data Offset

16-19

Checksum

Reserved

Bits 8 15

Bits 16 23

Bits 24 31

Destination Port Number

URG

Ack

PSH

RST

SYN

Fin

Window

Table 3-5 TCP Header (RFC 793)

Bytes 0 - 1

16-bit source port number

Bytes 2 - 3

16-bit destination port number. For messages from the host to the modem, this is
the port number of the modems TCP API port. The modems TCP API port number
may be changed using AT commands (AT$TCPSRC) if desired. The modems
default TCP API port number is 1024 (0x0400).

Bytes 4 - 7

32-bit sequence number of the first data octet in this segment

Bytes 8 - 11

32-bit acknowledge number

Bytes 12 - 15

4 bits: Data Offset, number of 32 bit words in the TCP header indicating where
data begins

- 10 -

6 bits: Reserved.
URG: Urgent Pointer field significant
ACK: Acknowledgment field significant
PSH: Push function
RST: Reset the connection
SYN: Synchronize sequence numbers
FIN: No more data from sender
16 bits: Number of data octets beginning with the one indicated in the
acknowledgement field, which the sender of this segment is willing to accept
Bytes 16 - 17

16-bit checksum

Bytes 18 - 19

Urgent Pointer

API Header
Configuration commands/messages can be sent to the modem either OTA or when a DUN
connection is present. Commands sent over a DUN connection can only be sent via UDP/IP.
However, commands sent OTA can be sent via UDP/IP or TCP/IP. Table 1 describes a high
level overview for data sent over UDP/IP while table 2 describes a high level overview for
data sent over TCP/IP. The API commands provide easy integration and message parsing for
the embedded developer and application developer. The Registration of Unsolicited message
registers the requestors IP address and Port number and sends unsolicited messages to the
requestors IP address and Port number.
The base API message header is 4 bytes long for commands sent via UDP/IP or 6 bytes long
for commands sent via TCP/IP. The API message header, for both UDP/IP and TCP/IP, can be
extended up to an additional 255 bytes by the inclusion of an API Optional Header. The
Supported API number and commands are described in table 5 below. The definition and
minimal implementation consists of the following:
Messages sent via UDP/IP has the following API header:
Bytes 0 - 1

16bit API number

Bytes 2

8bit Command Type information. This value determines the type of message being sent or
received by the host

Bytes 3

API Optional Header Size. This field defines the size of the API Optional Header in Bytes. This
field is set to zero (0) if an API Optional Header is not included.

Bytes 4 thru (4+m)

API Optional Header.

- 11 -

Messages sent via TCP/IP have the following API header:

Bytes 0 - 1:

16bit Data length (data length should include the 6 byte of API header as part of its length
ex: 00 1a in example given below)

Bytes 2 - 3

16bit API number (ex: 00 0a in example given below)

Bytes 4

8bit Command Type information. This value determines the type of message being sent or
received by the host (ex: 08 in example given below)

Bytes 5

API Optional Header Size. This field defines the size of the API Optional Header in Bytes. This
field is set to zero (0) if an API Optional Header is not included.(ex: 00 in example given
below)

Bytes 6 thru (6+m)

API Optional Header

Example 26 byte TCP connect ID message:

00 1a 00 0a 08 00 31 32 33 34 35 36 37 38 39 30 |.'....1234567890|
31 32 33 34 35 36 37 38 39 30 |1234567890 |
API number (values given below are
decimal)
Byte 0

Byte 1

Command Type

API Optional Header

Size

Byte 2

Byte 3

Direction

0 4 Reserved
5 GPS Binary Read*
6 65535 Reserved

0 (Read Request)

Modem <- OTA

0 Unsolicited Msg Request

1 9 Reserved
10 ACK
11 Password
12 65535 Reserved

1 (Write Request)

Modem <- OTA

0 Unsolicited Msg
1 3 Reserved
4 ASCII Event Data (Param2>=256)*
5 Binary Event Data*
6 Reserved
7 ASCII TAIP Data*
8 $MSGSND Data
9 Reserved
10 ASCII Event Data (Param2<256)
12 Information Element Data

2 (General Status Inform- (Size of API Optional

ation)
Header)

Modem -> OTA

Echo first 2 bytes of an incoming data

3 (Error)

(Size of API Optional

Header)

Modem -> OTA

0 65535

4 (AT Command)

Modem <- OTA

Echo first 2 bytes of an incoming AT command request

5 (AT Command
Response)

(Size of API Optional

Header)

Modem -> OTA

First 2 bytes of AT$UDPMSG command in

ASCII format

(Size of API Optional

Header)

Modem <--> OTA

First 2 bytes of AT$UDPMSG command in

Binary format

(Size of API Optional

Header)

Modem <--> OTA

10

Modem ID

Table 3-6 API Table

- 12 -

Modem -> OTA

Wakeup Messages
The wakeup/keep-alive message is sent to the local host as a Status command message.
The following data will be sent by the modem at the periodic interval configured by the
AT$WAKEUP command:
Bytes Data Description Comments
0

0x00

0x0A

Parameter Number

0x02

Status

0x00

Reserved

0x20

Parameter Number ( 1)

0x20

0x20

0x20

0x20

0x20

10

0x20

11

0x20

12

0x20

13

0x31

14

0x20

15

0x20

16

0x31

17

0x32

18

0x33

19

0x34

20

0x35

21

0x36

22

0x37

23

0x38

24

0x39

25

0x30

26

0x31

27

0x32

28

0x33

29

0x34

30

0x35

31

0x36

32

0x37

33

0x38

34

0x39

35

0x30

36

0x20

Modem ID (12345678901234567890)

Table 3-7 Wakeup/keep alive message

- 13 -

Send Password To Modem

If APIPWD is set, the modem will require the correct password from a "friendly IP" (set by
AT$FRIEND command) before accepting any remote requests. Remote requests are only
accepted from the last "friendly IP" that sent the correct password. If APIPWD is null, then all
remote requests from any IP address will be accepted. The password is a maximum of 8
characters:
Bytes Data Description Comments
0

0x00

0x0B

Parameter Value

0x01

Write Request

0x00

Reserved

0x41

0x42

0x43

0x44

0x45

0x46

10

0x00

11

0x00

Password (ABCDEF)
<8 - Alpha - Numeric Upper Case Characters (0-9 A-Z)>

Table 3-8 Sending of password to the modem OTA

Read/Write AT Command Request

AT commands mentioned in the AT Command document can be sent to the modem when a
DUN session is present or OTA. The host-to-modem message structure for reading/writing an
AT command is as follows:
Bytes Data Description Comments
0

0x00

0x01

SEquence Number

0x04

AT Command Read / Write

0x00

Reserved

0x41

AT Command (ATI)

0x54

0x49

Table 3-9 AT command to the modem

The modem will respond with the following message:

- 14 -

Bytes Data Description Comments

0

0x00

0x01

Sequence Number

0x05

AT Command Response

0x00

Reserved

0x0D

AT Command (Novatel Wireless M2M Inc.)

0x0A

0x45

0x6E

0x66

0x6F

10

0x72

11

0x61

12

0x2C

13

0x20

14

0x49

15

0x6E

16

0x63

17

0x2E

18

0x0D

19

0x0A

Table 3-10 AT command response

Unsolicited Messages
UDP API
A host has to register with the modem to receive any unsolicited messages. The modem
saves the hosts IP address and Port number. Unsolicited messages will then be sent to the
users IP and Port number. The host should send the following message structure to register
the reception of unsolicited messages:
Bytes Data Description Comments
0

0x00

0x00

Parameter Number (Unsolicited message registration request)

0x01

Write request)

0x00

Response Status

Table 3-11 Message structure for registration of unsolicited messages

The modem will send the following message structure for the registered unsolicited
messages:

- 15 -

Bytes Data Description Comments

0

0x00

0x00

Parameter Number (Unsolicited message registration request)

0x02

Write request

0x00

Response Status

4-n

...

Unsolicited message

Figure 3-2 Message structure of an incoming unsolicited message

TCP API
The AT command $TCPURC is used to enable or disable the sending of URCs over TCP API.
AT$TCPURC= will enable URCs to be sent to the TCPAPI server
AT$TCPURC= will disable URCs to be sent to the TCPAPI server
The default is the sending of URCs is disabled.
The format of the URCs sent over TCP is shown in Table 12a.
Bytes Data Description Comments
0-1

16 bit data length

0x00

16 bit parameter

0x00

number

0x02

Status Message

Optional header length

...

Unsolicited message

Table 3-12 Message structure of URC over TCP

ACK Messages
To disable sending of a message that requires acknowledgement, the server should send the
following data, indicating an ACK, to stop sending of the messages.

Acknowledge message should only be sent for messages configured to be sent

via UDP/IP

- 16 -

Bytes Data Description Comments

0

0x00

0x0A

Parameter Number

0x01

Write request

0x00

Response Status

Table 3-13 ACK message

ERROR Messages
If there is an error in processing an API request by the modem, the modem will respond with
the following message structure:
Bytes Data Description Comments
0

xx

xx

First two bytes of an incomming request will be echoed here

0x03

ERROR Message

0x00

Response Status

Table 3-14 Error message

API Optional Header

The API Optional Header can be appended to the end of the UDPAPI or TCPAPI Header. It is
comprised of a sequence of Optional Header Fields as shown below.
Optional Header Field Bytes

Bits 0-7

Size (m)

Type

2 thru (m-1)

Data

Size (n)

(m+1)

Type

...

(m+2) thru (m+n-1)

Data

(m+n)

Size (p)

(m+n+1)

Type

(m+n+2) thru (m+n+p-1)

Data

(m+n+p)

...

Table 3-15 API Optional Header Format

Each Optional Header Field has the following generic format:

Byte 0: 8 bit field indicating the size of the Optional Header Field including Size and Type
Fields

- 17 -

Byte 1: 8 bit field indicating the type of data contained in Data Field. Currently defined types
are shown in the table below.
Bytes 2+: Optional Header Data Field. The content is defined by the Optional Header Type
Currently there are eight defined Optional Header Types. The Complete list of defined types
is as follows:
Optional Header Type

Definition

End of Option Sequence

MDMID

Output Message Event Format

Event Sequence Number

Firmware Version

Cause Code

Output Event Number

Hex Modem ID

Driver ID

Param 3

Table 3-16 Optional Header Type

The inclusion of the Optional Headers is selected by the AT$APIOPT and is only sent for
applicable API message types. The following table defines when the Optional Headers are
applicable based on the API Number and Command Types. For complete syntax of the
AT$APIOPT Command.
API Message
UDP-API Number
0-4 Reserved

Optional Fields
Command Type

Event Sequence
Number

Output Message Event

Format

N/A

N/A

N/A

5 GPS Binary Read

N/A

N/A

N/A

6-65535 Reserved

N/A

N/A

N/A

N/A

N/A

N/A

1-9 Reserved

N/A

N/A

N/A

10 Ack

N/A

N/A

N/A

11 Password

N/A

N/A

N/A

12-65535 Reserved

N/A

N/A

N/A

0 Unsolicited Message Request

0 Read Request

MDMID

1 Write Request

- 18 -

API Message

Optional Fields

UDP-API Number
0 Unsolicited Message Request

Command Type

MDMID

Output Message Event

Format

TCP/UDP

N/A

N/A

TCP/UDP

N/A

N/A

4 Ascii Event Data Param2>=256

TCP/UDP

TCP/UDP

TCP/UDP

5 Binary Event Data

TCP/UDP

TCP/UDP

TCP/UDP

6 Reserved

TCP/UDP

N/A

N/A

7 Ascii TAIP Data

TCP/UDP

N/A

N/A

8 $MSGSND

TCP/UDP

N/A

N/A

9 Reserved

TCP/UDP

N/A

N/A

10 Ascii Event Data Param2<256

TCP/UDP

TCP/UDP

TCP/UDP

12 Informational Elements

TCP/UDP

N/A

N/A

1-3 Reserved

2 General Status
Information

Event Sequence
Number

Echo first 2 bytes of incomming data

3 Error

TCP/UDP

N/A

N/A

0-65535

4 AT Command
Request

N/A

N/A

N/A

Echo first 2 bytes of incomming AT Command request

5 AT Command
Response

TCP/UDP

N/A

N/A

First 2 bytes of AT$UDPMSG Command in

ASCII format

TCP/UDP

N/A

N/A

Modem to OTA
only
First 2 bytes of ATUDPMSG Command in Bin- 7
ary format

Modem to OTA
only

N/A

N/A

10

N/A

N/A

N/A

Table 3-17 Conditions for Including Optional Fields into API Optional Header

A detailed description for each of the Optional Field types is discussed in the following
paragraphs.

End Of Option Sequence Type 0

This API Optional Header Field Type indicates it is the last of the Optional Header Fields. It is
only used if the API Optional Header Size is defined to be larger than the combined Option
Header sizes. The size field for this type shall include the remaining bytes of the API Optional
Header. The Data Field shall contain all zeros. The primary purpose of this type is to allow

- 19 -

padding to re-align the Data contents of the API Message to a word boundary. To
accommodate single byte padding of the API Optional Header a size field of one (1) shall be
allowed as the last byte of the API Optional Header. If one (1) is seen in the size field it shall be
interpreted as the last byte of the API Optional Header with the Optional Header Field Type
assumed as End of Option Sequence. The End of Option Sequence formats are shown below:

Size

Type

Data

Data

Description
(Byte 0) (Byte 1) (Byte 2) (Byte 3-n)
Single Byte Pad 0x01

Two Byte Pad

0x02

0x00

Three Byte Pad

0x03

0x00

0x00

Multi-Byte Pad

(n)

0x00

0x00

0x00(s)

Table 3-18 End of Optional Header Sequence Formats

MDMID Type 1
The MDMID Optional Header Field allows servers to easily identify the source of the packet for
easier handling. The Optional Header Data Field would include the value set by the
AT$MDMID command. No additional padding will be added to the data. An example for a
MDMID of 12345678901234567890 is as follows:
Bytes Data Description Comments
0

0x16 (22)

Size

0x01

Type = MDMID

- 20 -

Bytes Data Description Comments

2

0x31

0x32

0x33

0x34

0x35

0x36

0x37

0x38

10

0x39

11

0x30

12

0x31

13

0x32

14

0x33

15

0x34

16

0x35

17

0x36

18

0x37

19

0x38

20

0x39

21

0x30

MDMID (12345678901234567890)

Table 3-19 MDMID Optional Header Field Format

Output Message Event Format- Type 2

The Output Message Event Format-Optional Header Field is available to messages generated
by the event engine. It contains the 32-bit <param2> value of the Output Message Event
Format. The inclusion of this option field is selected by the AT$APIOPT Command. The
format for this optional header field is as follows:
Bytes Data Description

Comments

0x06

Size

0x02

Type = output message event format

0x12

Output message event format (0x12345678)

0x34

0x56

0x78

Table 3-20 Output Message Event Format Header Field Format

- 21 -

Event Sequence Number Type 3

The Event Sequence Number-Optional Header Field is available to messages generated by
the event engine. The optional data field would include the value of the Event Sequence
Number. The Event Sequence Number increments with each Output Event. The Event
Sequence Number is not reset by power off or the AT&F command. The inclusion of this
option field is selected by the AT$APIOPT Command. When the Event Sequence Number
reaches its maximum value, it will roll over to zero and restart counting. The size of the Event
Sequence Number can be set to 8, 16, 24, 32 bits by the AT$APIOPT Command. The Event
Sequence Number Optional Header Field formats are shown below for all available sizes:
Size

Type

Data

Data

Data

Data

Description
(Byte 0) (Byte 1) (Byte 2) (Byte 3) (Byte 4) (Byte 5)
8-bit format

0x03

0x03

0x78

16-bit format 0x04

0x03

0x56

0x78

24-bit format 0x05

0x03

0x34

0x56

0x78

32-bit format 0x06

0x03

0x12

0x34

0x56

0x78

Table 3-21 Example of Event Sequence Number Header - Seq Num = 0x12345678

Firmware Version - Type 4

The Firmware Version Optional Header Element is used to specify the Novatel Wireless M2M
Version Number of the current firmware.
Bytes Data Description

Comments

0x06

Size

0x04

Type = Firmware Version

Data

3
4
5

Table 3-22 Firmware Version Optional Header Element

Cause Code Type 5

The Cause Code Optional Header Element is used to specify a status code for an operation.
Bytes Data Description
0

0x04

Comments
Size

- 22 -

Bytes Data Description

1

0x05

Comments
Type = Cause Code

Cause Code Value

Table 3-23 Cause Code Optional Header Element

Code

Description

Unknown

Restart due to system initialization

Restart due to FOTA completion

Table 3-24 Cause Code Value Definitions

Output Event Number Type 6

The Output Event Number Optional Header Element is used to specify an output event
number.
Bytes Data Description

Comments

0x03

Size

0x06

Type = Output Event Number

Output Event Number

Table 3-25 Output Event Number Optional Header Element

Hex Modem ID Type 7

The Hex Modem ID Optional Header Element is used to add the hex modem ID to the optional
header. The size of the Modem ID can be 1 byte to 9 bytes based on the value in $MDMID.
Leading zeros in the modem ID are not transmitted a modem ID of 0099 and 99 will be
transmitted with the same value.
Size

Type

Data

Data

Data

Data

Data

Description
(Byte 0) (Byte 1) (Byte 2) (Byte 3) (Byte 4) (Byte 5) (Byte 6)
Hex modem ID 0x07

0x07

0xF1

0x36

0x6C

0xB0

0x7F

Table 3-26 Example of Modem ID Header - $MDMID:"001036000211071"

- 23 -

Size

Type

Data

Description
(Byte 0) (Byte 1) (Byte 2)
Hex modem ID 0x03

0x07

0x63

Table 3-27 Example of Modem ID Header - $MDMID:"99"

Size

Type

Data

Description
(Byte 0) (Byte 1) (Byte 2)
Hex modem ID 0x03

0x07

0x0

Table 3-28 Example of Modem ID Header - $MDMID:"999999999999999999A"

Description

Hex modem ID

Size

Type

Data

Data

Data

Data

Data

Data

Data

Data

Data

(Byte
0)

(Byte
1)

(Byte
2)

(Byte
3)

(Byte
4)

(Byte
5)

(Byte
6)

(Byte
7)

(Byte
8)

(Byte
9)

(Byte
10)

0x0B

0x07

0x05

0x6B

0xC7

0x5E

0x2D

0x63

0x0F

0xFF

0xFF

Table 3-29 Example of Modem ID Header - $MDMID:"99999999999999999999"

Driver ID Type 8
The Driver ID Optional Header Element is used to add the driver ID to the optional header.
The entire 8 byte driver ID may be included, or the device may be configured to only report
the least significant 4 bytes of the serial number of the driver ID.
Size

Type

Data

Data

Data

Data

Data

Data

Data

Data

Data

Description

(Byte
0)

(Byte
1)

(Byte
2)

(Byte
3)

(Byte
4)

(Byte
5)

(Byte
6)

(Byte
7)

(Byte
8)

(Byte
9)

(Byte
10)

4 byte Driver ID

0x06

0x08

0x14

0xFD

0x42

0x5B

4 byte
Driver ID

8 byte Driver ID

0x0A

0x08

0xB9

0x00

0x00

0x14

0xFD

0x42

0x5B

0x01

8 byte
Driver ID

Table 3-30 Example of Driver ID Header - $IBTN: 1,b9,000014fd425b,01

- 24 -

Param 3 Type 9
The Param 3 Optional Header Element is used to add the Param 3 value used in the output
event to the optional header message. The length of Param 3 is 4 bytes.
Description

Size

Type

Data Data Data Data

Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5

Param 3

0x06

0x09

0x00

0x00

0x00

0x0C

Table 3-31 Example of Param 3 06 09 00 00 00 0C

FOTA Complete Message

The FOTA Complete Messsage is composed of the elements:
l
l
l

Modem ID Header Element

Cause Code Header Element
Firmware Version Header Element

ModemID Size

ModemID Type (1)

Modem ID Data (Variable Length)

Cause Code Size (4)

Cause Code Type (4)

Cause Code Data (16 bits) = 2 fpr FOTA Restart

FW Version Size (6)

Firmware Type (5)

Firmware Version Data (32 bits)

Table 3-32 FOTA Complete Message

The FOTA process will send a FOTA Complete Message to the first destination in the
FRIENDS list upon completion of the FOTA operation. The FOTA operation is normally
completed on the next Modem startup following the new Firmware load. This message is
composed by the Cause Code indicating that a FOTA operation caused the system to restart
with the new Firmware Version.

- 25 -

4
Terms Explained

- 26 -

Byte
In this document, One Byte = 8 bits. Bit-0 is the right most bit and is also referred to as pin-1
while Bit-7 is the left most bit and is referred to as Pin-8.
Byte
Upper Nibble
Bit-7

Lower Nibble

Bit-6 Bit-5

Bit-4 Bit-3

Bit-2

Bit-1

Bit-0

Pin-8 Pin-7 Pin-6 Pin-5 Pin-4 Pin-3 Pin-2 Pin-1

27

26

25

24

23

22

21

20

Big Endian
Big endian format means that the most significant byte is sent first. For example, a decimal
value of 1234567 will be displayed as hex 0x0012D687. While sending this data over a
communication link, the most significant byte 0x00 is sent first followed by 0x12, followed
by the third byte 0xD6, and followed by the least significant byte 0x87.
1234567 (decimal) = 0x0012D687 (hex)
Byte-0 Byte-1 Byte-2 Byte-3
0x00

0x12

0xD6

0x87

Little Endian
Little endian format means that the least significant byte is sent first. For example, a decimal
value of 1234567 will be displayed as hex 0x0012D687. While sending this data over a
communication link, the least significant byte 0x87 is sent first followed by 0xD6, followed
by the third byte 0x12, and followed by the most significant byte 0x00.
1234567 (decimal) = 0x0012D687 (hex)
Byte-0 Byte-1 Byte-2 Byte-3
0x87

0xD6

0x12

0x00

- 27 -

5
Example
Sending AT Command
Response from modem to host:
Receiving UDP ASCII Event Data with Option Header MDMID and Sequence Number
Enabled

- 28 -

Sending AT Command
IP and UDP checksum are not calculated in this example. They are left for the user
to calculate as an exercise.

Bytes Description Hex Value Notes

-------------------------------------------------------------------0 Version Length: 45
1 Type of Service: 00
2 & 3 Length of Packet: 00 23 IP + UDP Header + Message Data
4 & 5 Identification: 00 00
6 & 7 Fragmentation Offset: 00 00
8 Time to live: 00
9 Protocol: 11 UDP
10 & 11 IP Header Checksum: 00 00
12,13,14,15 Source IP: A6 85 AB 13 166.133.171.19
16,17,18,19 Destination IP: C7 F5 B4 0D 199.245.180.13
20 & 21 Source Port: 04 4C 1100
22 & 23 Destination Port: 06 B8 1720
24 & 25 Length of Packet: 00 04
26 & 27 UDP Checksum: 00 00
28 & 29 UPD API Command: 00 01 UDP API 00 01 'Sequence Number
30 UDP API Read: 04 AT Command Request = 04
31 UDP API Optional: No Optional Header
Header Size
32,33,34 AT Command 41 54 49 AT Command = ATI

- 29 -

Response From Modem To Host:

Bytes Description Hex Value Notes
-------------------------------------------------------------------0 Version Length: 45
1 Type of Service: 00
2 & 3 Length of Packet: 00 30 IP + UDP Header + Message Data
4 & 5 Identification: 00 00
6 & 7 Fragmentation Offset: 00 00
8 Time to live: 00
9 Protocol: 11 UDP
10 & 11 IP Header Checksum: 00 00
12,13,14,15 Source IP: A6 85 AB 13 166.133.171.19
16,17,18,19 Destination IP: C7 F5 B4 0D 199.245.180.13
20 & 21 Destination Port: 06 B8 1720
22 & 23 Source Port: 04 4C 1100
24 & 25 Length of Packet: 00 04
26 & 27 UDP Checksum: 00 00
28 & 29 UPD API Command: 00 01 UDP API 00 01 Sequence Number
30 UDP API Status: 05 AT Command Response = 05
31 UDP API Optional: No Optional Header
Header Size
32,33,34,35 AT Command Response 0D 0A 45 6E Novatel Wireless M2M, Inc.
36,37,38,39 Response continued 66 6F 72 61
40,41,42,43 Response continued 2C 20 49 6E
44,45,46,47 Response continued 63 2E 0D 0A

- 30 -

Receiving UDP ASCII Event Data With Option

Header MDMID And Sequence Number Enabled
Bytes Description Hex Value Notes
-------------------------------------------------------------------0 Version Length: 45
1 Type of Service: 00
2 & 3 Length of Packet: 00 32 IP + UDP Header + Message Data
4 & 5 Identification: 00 00
6 & 7 Fragmentation Offset: 00 00
8 Time to live: 00
9 Protocol: 11 UDP
10 & 11 IP Header Checksum: 00 00
12,13,14,15 Source IP: A6 85 AB 13 166.133.171.19
16,17,18,19 Destination IP: C7 F5 B4 0D 199.245.180.13
20 & 21 Destination Port: 06 B8 1720
22 & 23 Source Port: 04 4C 1100
24 & 25 Length of Packet: 00 04
26 & 27 UDP Checksum: 00 00
28 & 29 UPD API Number: 00 0A ASCII Event Data
30 UDP API Status: 02 General Status Info
31 UDP API Optional: 0B Combined Optional
Header Size Header Size
32 Optional Header Size: 07 Size of MDMID Optional Header
33 Optional Header Type: 01 Type is MDMID
34 thru 38 Optional Header Data: 31 32 33 34 35 MDMID 12345
39 Optional Header Size: 04 Size of Sequence Number Optional Header
40 Optional Header Type: 03 Type is Sequence Number

- 31 -

41 & 42 Optional Header Data: AB CD Event Sequence Number ABCD

43 thru 50 Output Message Event xx xx xx ...

- 32 -