Enfora FOTA

Application Note

ENF0000AN002
Revision: 1.00
6/15/2009

Application Note

Page I

Revision: 1.00

GENERAL
TERMS OF USE OF NEW MATERIALS - PLEASE READ CAREFULLY
From time to time, Enfora, in its sole discretion, may make available for download on its
website (www.enfora.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 Enfora's
Technical Support Policy (posted on its website) and/or any written agreement between
the user and Enfora.
All New Materials are provided AS IS. Enfora 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. Enfora 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
Enfora's consent is strictly prohibited.
IN NO EVENT WILL ENFORA BE RESPONSIBLE FOR ANY INCIDENTAL, INDIRECT,
CONSEQUENTIAL OR SPECIAL DAMAGES AS A RESULT OF THE USE OF ANY NEW
MATERIALS. ENFORA'S MAXIMUM LIABILITY FOR ANY CLAIM BASED ON THE NEW
MATERIALS SHALL NOT EXCEED FIFTY U.S. DOLLARS ($50).

COPYRIGHT
2009 Enfora, 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 Enfora, Inc.
Enfora and the Enfora logo are either registered trademarks or trademarks of Enfora, Inc.
in the United States.
251 Renner Pkwy
Richardson, TX 75080 USA
972-633-4400
Phone: (972) 633-4400
Fax: (972) 633-4444
Email: info@enfora.com
www.enfora.com

Application Note

Page I

Revision: 1.00

Enfora FOTA

TABLE OF CONTENTS
General

Copyright

Table of Contents

Table of Tables

Introduction

1.1

Objective

1.2

Overview

1.3

Prerequisites

1.3.1

FOTA Upgrade server

1.3.2

FTP Server

1.3.3

FIRMWARE UPGRADE FILES

1.4

Basic FOTA Operation

1.5

FOTA Process

1.6

FOTA Specific AT Commands

1.6.1

AT$FOTACFG

1.6.2

AT$FOTAGET

1.6.3

AT$FOTAGET?

1.6.4

AT$FOTAUPG

1.7

FOTA URC STATUS

1.8

FOTAGET UPGRADE Status Values

1.9

FOTA RestarT

1.10

FOTA Upgrade

1.10.1

General Steps:

1.10.2

Example Scenario

Appendix A Acronyms

11

TABLE OF TABLES
Table 1 FOTA URC Values ............................................................................................... 6
Table 2 - FOTA Upgrade Status Values ............................................................................ 7
Table 3 - Acronym List ................................................................................................... 11
Application Note

Page 1

Revision: 1.00

Enfora FOTA

1 Introduction
1.1 OBJECTIVE
The intent of this document is to provide the user with a basic understanding of the
Enfora modem FOTA capabilities, including configuration and use of the various AT
Commands.

1.2 OVERVIEW
The FOTA process encompasses the following operations:

Download the upgrade file to system flash using FTP.

Initiate the modem upgrade process.
Inform the server of the upgrade status.

1.3 PREREQUISITES
1.3.1 FOTA UPGRADE SERVER

OTA AT commands are used to configure and initiate the upgrade process.
The FOTA Upgrade Server must support AT commands and unsolicited
responses using Enforas UDP API messages

1.3.2 FTP SERVER

Firmware upgrades are delivered to the device over the air using FTP. To
support FOTA, an FTP server must be available, but does not need to be colocated with the FOTA Upgrade server. The modem will access the FTP server
directly via a TCP connection to transfer the FOTA file.

FOTA is capable of restarting an interrupted FTP file transfer. To accomplish a

restart, FOTA utilizes the FTP file resume feature specified in RFC3659. It is
required that the FTP server support FTP File Restart command (REST) in
STREAMS mode as specified in RFC3659. Enfora has tested the FOTA FTP
support with Windows Server 2003 with Internet Information Services Version
7.0 (IIS7.0).

Application Note

Page 2

Revision: 1.00

Enfora FOTA

1.3.3 FIRMWARE UPGRADE FILES

Firmware upgrade files are provided by Enfora and should be stored on the FTP
server in a directory accessible by FTP clients. The recommended directory
structure is to create a directory named Enfora in the root FTP directory and
within the Enfora directory, create a directory named FOTA. For example:
<ftpRootDirectory>/Enfora/FOTA

The firmware upgrade file is dependent upon the current firmware version and
the new firmware version. Use the AT+CGMR command to determine the
current firmware version on your modem and contact Enfora Technical Support
to get the proper firmware upgrade file.

The average firmware upgrade delta file is 250K bytes. The maximum firmware
upgrade delta file size is 500K bytes.

1.4 BASIC FOTA OPERATION

The steps to accomplish the FOTA upgrade process are as follows.
1. Copy the FOTA upgrade file to the FTP server.
2. Configure the modem with the FOTA configuration parameters.
3. Initiate the FOTA file transfer.

1.5 FOTA PROCESS

The FOTA process encompasses the configuration, the FOTA file transfer using
FTP, copying the FOTA file onto the system flash, and alerting the Upgrade Server
of FOTA status. The overall steps to accomplishing a FOTA upgrade are as follows:
1. Configure the modem with the FOTA configuration parameters.
2. Initiate the FOTA file transfer.
3. If in Manual Upgrade Mode:
a. Apply the FOTA file to the target system.
b. Restart the system to execute with the new firmware.

FOTA configuration and state information are maintained in order to support

FOTA restarts across system interruptions.

All FOTA configuration parameters are automatically saved to flash as required.

The user is not required to issue an AT&W.

Application Note

Page 3

Revision: 1.00

Enfora FOTA

1.6 FOTA SPECIFIC AT COMMANDS

1.6.1 AT$FOTACFG
AT$FOTACFG=ftpServerHostname, ftpPort, ftpUsername, ftpPassword,
ftpMode, retries, reportMode, upgradeMode
ftpServerHostname either Fully Qualified Domain Name (FQDN) or a dotteddecimal IP address of the FTP server. The FQDN is resolved by DNS
immediately prior to opening IP connection to FTP server. The FQDN may be up
to a maximum of 63 characters. Default value: none.
ftpPort: The TCP port number on the FTP server. Port range: 0 65535,
Default value: 21
ftpUserame: FTP login name on the FTP server. The username may be up to a
maximum of 31 characters. Default value: none.
ftpPassword: The FTP password for the FTP user. The password may be an
empty string if the FTP user does not have a password. The password may be
up to a maximum of 31 characters. Default value: none.
ftpMode: The FTP mode to use for data connections. FTP data connections
may be active or passive. Passive mode is generally better to use with FTP
servers located behind firewalls. Values: 0 = active, 1 = passive. Default value: 0
(active mode).
retries: This is the maximum number of FTP file resumes to attempt before
giving up on original AT$FOTAGET command. The range of retries is 0 20.
Default Value: 0.
reportMode: The reporting mode is used to control the level of status reporting
during the FOTA process. Terse mode sends only critical status updates,
verbose mode sends informative and critical status updates. The command
parameters are: 0 = terse, 1 = verbose. Default value: 0 (terse mode).
upgradeMode: The system behavior following successful FOTA file transfer to
modem. The upgrade Mode may be either Automatic or Manual. Auto mode will
immediately initiate FOTA upgrade when file transfer completes. Manual mode
will wait after file transfer until an explicit upgrade command is issued
(AT$FOTAUPG). The command line parameters are: 0 = auto, 1 = manual.
Default value: 0 (automatic mode).
Any parameter may be left unspecified by using a comma separator to step to
the next parameter which leaves either the default value or the pre-existing
saved value active.

Application Note

Page 4

Revision: 1.00

Enfora FOTA

1.6.2 AT$FOTAGET
AT$FOTAGET=remoteFilename
remoteFilename: filename of FOTA file on FTP server. The filename may be up
to 31 characters. The filename should be the complete pathname starting from
the login directory associated with the FTP username.
1.6.3 AT$FOTAGET?
$FOTAGET: fotaMode, remoteFilename, retriesRemaining, fotaPreStatus,
fotaUpgradeStatus
fotaMode: current FOTA mode indicating if FOTA is in the process of
transferring a FOTA file. The values are: 0 = IDLE, 1 = BUSY.
remoteFilename: The filename of currently configured FOTA file.
retriesRemaining: The number of FTP resumes remaining before terminating file
transfer. This number starts with the retries specified in the AT$FOTACFG
command and is decremented for each FOTA restart which occurs.
fotaPreStatus: The status value of the FOTA upgrade process prior to system
restart.
fotaUpgradeStatus: The status value of the FOTA upgrade process after
system restart.
1.6.4 AT$FOTAUPG
AT$FOTAUPG
Manual command used to initiate a FOTA upgrade after FOTA file has been
successfully transferred to the system. This command should not be used if
Automatic upgrade is configured; the upgrade process is started by the modem
in automatic mode.

Application Note

Page 5

Revision: 1.00

Enfora FOTA

1.7 FOTA URC STATUS

AT$FOTAGET will generate various URCs to provide status information to the user
during the FOTA process. These URCs will be of either $FOTAGET: <status> or
$FOTAUPG: <status>. The configured Reporting Mode (verbose or terse) will affect
which URCs are displayed. Terse mode is limited to errors and important changes
in status. Verbose mode will report all the Terse mode values and additional
status URCs. The status values are for both the $FOTAGET and $FOTAUPG URCs
are as follows:
Status Value

Meaning

Type

Success

Status, terse and verbose

Failure, specific error not specified

Error

FTP Server configured

Status, verbose

FOTA file transfer started

Status, verbose

FOTA file transfer in progress

Status, verbose

FOTA file transfer complete

Status, terse and verbose

FOTA file transfer restarted

Status, terse and verbose

FOTA file transfer error

Error

FOTA upgrade failed

Error

FOTA upgrade complete

Status, terse and verbose

10

FOTA upgrade initiated

Status, terse and verbose

11

FOTA file transfer network error

Error

12

FOTA file transfer file error

Error

13

FOTA FTP authentication error

Error

14

FOTA DNS error

Error

15

FOTA timeout exceeded

Error

16

FOTA maximum retries exceeded

Error

17

FOTA flash file system error

Error

Table 1 FOTA URC Values

Application Note

Page 6

Revision: 1.00

Enfora FOTA

1.8 FOTAGET UPGRADE STATUS VALUES

FOTA upgrade status values are displayed by using the AT$FOTAGET? query. The
status values are set by the upgrade process after the system restarts and are valid
for the previous upgrade attempt. The most common error, 176, results from
attempting to perform a FOTA upgrade with a FOTA file not specifically created for
the target platform.
Status Value

Meaning

Success

33

Failure to open the Update Package

48

Invalid Update Package ID. This is most likely caused by no package

existing.

49

Invalid Update Package format ID.

50

Invalid Update Header. The package is most likely corrupted.

51

Invalid Update checksum verification. The Update Package is probably

corrupt.

176

Checksum validation mismatch.

178

Checksum mismatch.

-1

General Status Error

-2

Device not supported

-3

File Access Error

-4

File Open Error

-5

File Size Error

-6

File Read Error

-7

File Close Error

-8

File Access Error

-9

Install Error

-10

Checksum Error
Table 2 - FOTA Upgrade Status Values

Application Note

Page 7

Revision: 1.00

Enfora FOTA

1.9 FOTA RESTART

FOTA uses FTP as the underlying file transfer mechanism. If an FTP file transfer is
interrupted, FOTA provides a means to automatically restart the FTP file transfer
from the interrupted point repeatedly until the file is completely transferred. This
automatic restart occurs when the system re-acquires an IP address.
FOTA restart utilizes the FTP file resume feature specified in RFC3659. It is required
that the FTP server support FTP File Restart command (REST) in STREAMS mode
as specified in RFC3659.
FOTA is typically initiated with an Over-the-Air (OTA) AT command. An interrupted
FOTA file transfer usually results in disrupting the original OTA AT command
connection. To keep the remote system informed during a restart, FOTA will
transmit UDP API messages with FOTA status to the remote hosts configured in
the FRIENDS list. In order for the Upgrade Server to uniquely identify the modem
issuing these FOTA UDP API messages, the extended optional header should be
enabled on the remote modem. It is the responsibility of the Upgrade Server to be
configured to enable the optional headers with the AT$APIOPT command.

1.10 FOTA UPGRADE

If in Automatic Mode, the AT$FOTAGET command will complete the FOTA upgrade
process and no further commands are necessary. The modem will automatically
restart with the new firmware after the FOTA file is instantiated.
In Manual Mode, the AT$FOTAGET command will stop after the FTP transfer of the
FOTA file to the system flash memory. After the $FOTAGET: 0 status URC is
displayed, the AT$FOTAUPG command is used to complete the FOTA upgrade
process which will instantiate the upgrade file and restart the modem with the new
firmware.
The new system version information can be verified with the AT+CGMR command.
Some platforms contain an additional microprocessor. The FOTA upgrade process
will automatically handle the firmware upgrade for the additional microprocessor
when needed without any user intervention.

Application Note

Page 8

Revision: 1.00

Enfora FOTA

1.10.1 GENERAL STEPS:

Automatic Mode:
Command

Function

AT$FOTACFG="ftpServer",<port>,"user
name","password",<ftpMode>,<retries>
,<reportMode>,0

Configure the desired FOTA/FTP parameters,

Automatic mode is enabled.

AT$FOTAGET=remotefilename

Initiate the FOTA file transfer of remotefilename

and perform the FOTA upgrade

Manual Mode:
Command

Function

AT$FOTACFG="ftpServer",<port>,"user
name","password",<ftpMode>,<retries>
,<reportMode>,1

Configure the desired FOTA/FTP parameters,

Manual mode is enabled.

AT$FOTAGET=remotefilename

Initiate the FOTA file transfer of remotefilename

AT$FOTAUPG

Only for manual mode

1.10.2 EXAMPLE SCENARIO

The following is an example scenario for a successful FOTA upgrade process:
AT$FOTACFG="ftpServer,21,user,password <- FOTA configured
,0,0,1,0
AT$FOTAGET="fota.bin"

<- FOTA file transfer initiated

OK
$FOTAGET: 2

<- indicates FTP server Is

configured

$FOTAGET: 5

<- indicates file transfer is

complete

$FOTAUPG: 10

<- indicates upgrade initiated

AT-Command Interpreter ready

<- system restarted due to auto

mode

AT$FOTAGET?

<- query upgrade status

$FOTAGET: 0, fota.bin, 0, 0,0

<- indicates upgrade successful

Application Note

Page 9

Revision: 1.00

Enfora FOTA

The following is an example error scenario illustrating FOTAGET requesting an

incorrect FOTA file:
AT$FOTAGET=wrongfota.bin"

<- FOTA file transfer initiated

OK
$FOTAGET: 2

<- indicates FTP server Is configured

$FOTAGET: 5

<- indicates file transfer is complete

$FOTAUPG: 10

<- indicates upgrade initiated

AT-Command Interpreter ready

<- system restarted due to auto mode

AT$FOTAGET?

<- query upgrade status

$FOTAGET: 0, wrongfota.bin, 0, 0, 176

<- 176 indicates upgrade failed due to

checksum validation mismatch

Application Note

P a g e 10

Revision: 1.00

Enfora FOTA

2 Appendix A Acronyms
The following table lists acronyms that are used in this document.
Acronym

Meaning

API

Application Programming Interface

FOTA

Firmware Over-the-Air

FTP

File Transfer Protocol

MOTA

MSP Over-the-Air

OTA

Over-the-Air

UDP

User Datagram Protocol

URC

Unsolicited Result Code

Table 3 - Acronym List

Application Note

P a g e 11

Revision: 1.00