MC25&M25&M56-R-OpenCPU

DFOTA Application Note

GSM/GPRS/GNSS Module Series

Rev. MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note_V1.1

Date: 2019-07-26

Status: Released

www.quectel.com
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

Our aim is to provide customers with timely and comprehensive service. For any
assistance, please contact our company headquarters:

Quectel Wireless Solutions Co., Ltd.

Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District,
Shanghai, China 200233

Tel: +86 21 5108 6236

Mail: [email protected]

Or our local office, for more information, please visit:

http://www.quectel.com/support/salesupport.aspx

For technical support, to report documentation errors, please visit:

http://www.quectel.com/support/techsupport.aspx

GENERAL NOTES
QUECTEL OFFERS THIS INFORMATION AS A SERVICE TO ITS CUSTOMERS. THE INFORMATION
PROVIDED IS BASED UPON CUSTOMERS’ REQUIREMENTS. QUECTEL MAKES EVERY EFFORT
TO ENSURE THE QUALITY OF THE INFORMATION IT MAKES AVAILABLE. QUECTEL DOES NOT
MAKE ANY WARRANTY AS TO THE INFORMATION CONTAINED HEREIN, AND DOES NOT ACCEPT
ANY LIABILITY FOR ANY INJURY, LOSS OR DAMAGE OF ANY KIND INCURRED BY USE OF OR
RELIANCE UPON THE INFORMATION. ALL INFORMATION SUPPLIED HEREIN IS SUBJECT TO
CHANGE WITHOUT PRIOR NOTICE.

COPYRIGHT
THIS INFORMATION CONTAINED HERE IS PROPRIETARY TECHNICAL INFORMATION OF
QUECTEL CO., LTD. TRANSMITTABLE, REPRODUCTION, DISSEMINATION AND EDITING OF THIS
DOCUMENT AS WELL AS UTILIZATION OF THIS CONTENTS ARE FORBIDDEN WITHOUT
PERMISSION. OFFENDERS WILL BE HELD LIABLE FOR PAYMENT OF DAMAGES. ALL RIGHTS
ARE RESERVED IN THE EVENT OF A PATENT GRANT OR REGISTRATION OF A UTILITY MODEL
OR DESIGN.

Copyright © Quectel Wireless Solutions Co., Ltd. 2019. All rights reserved.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 1 / 16
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

About the Document

History

Revision Date Author Description

Edwin WEN/
1.0 2019-05-30 Initial
Waner PAN
Updated the API of DFOTA and related
1.1 2019-07-26 Allan LIANG
description (Chapter 3.4, 4 and 5.2)

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 2 / 16
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

Contents

About the Document ................................................................................................................................... 2

Contents ....................................................................................................................................................... 3
Table Index ................................................................................................................................................... 4
Figure Index ................................................................................................................................................. 5

1 Introduction .......................................................................................................................................... 6

2 Package Tool ........................................................................................................................................ 7

3 DFOTA Flow.......................................................................................................................................... 9
3.1. Compile Application.lod File and Generate New .lod File ..................................................... 10
3.2. Make the Delta Firmware Package ....................................................................................... 10
3.2.1. Configuration for Packaging Firmware .lod ................................................................... 11
3.2.2. Configuration for Packaging Application .lod ................................................................. 11
3.3. Put the Generated .pack File on the Server.......................................................................... 11
3.4. Start DFOTA .......................................................................................................................... 12

4 DFOTA API .......................................................................................................................................... 13

4.1. Ql_DFOTA_StartUpgrade ...................................................................................................... 13

5 How to Program DFOTA .................................................................................................................... 15

5.1. Define DFOTA Downloading Protocol ................................................................................... 15
5.2. Execute DFOTA API .............................................................................................................. 15

6 Appendix A Reference....................................................................................................................... 17

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 3 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

Table Index

TABLE 1: REFERENCE DOCUMENTS ............................................................................................................ 17

TABLE 2: ABBREVIATIONS .............................................................................................................................. 17

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 4 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

Figure Index

FIGURE 1: OPENCPU DFOTA PACKAGE TOOL............................................................................................... 7

FIGURE 2: OPENCPU DFOTA FLOW ................................................................................................................ 9
FIGURE 3: MAKE THE DELTA FIRMWARE PACKAGE ................................................................................... 10
FIGURE 4: CONFIGURATION FOR PACKAGING FIRMWARE .LOD .............................................................. 11
FIGURE 5: CONFIGURATION FOR PACKAGING APPLICATION .LOD .......................................................... 11

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 5 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

1 Introduction
This document introduces the method of upgrading the firmware and application via DFOTA (Delta
Firmware Upgrade Over-The-Air). Meanwhile, it describes how to program DFOTA and use the package
tool.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 6 / 16
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

2 Package Tool
The delta firmware package (.pack file) needs to be generated with the tool
OpenCPU_DFOTA_Package_Tool, which is placed in directory SDK\tools.

Figure 1: OpenCPU DFOTA Package Tool

The functions of the fields and buttons in the package tool are described as below.

 Old LOD and New LOD

Please select the .lod file running in the module in “Old LOD” field, and select the .lod file to be upgraded
to the module in “New LOD” field.

 Patch

Select the storage path in “Patch” field where the .pack file packaged will be saved, and the packaged file
can be renamed.

 Edit

Configure the base address and size of code flash.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 7 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

 Add and Remove

The two fields are used to configure tool OpenCPU_DFOTA_Package_Tool. For normal usage,
leave them as the default.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 8 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

3 DFOTA Flow
Firmware or application upgrade process via DFOTA consists of the following steps:

Step 1: Save the .lod file including firmware .lod or application .lod that is downloaded to the module
before.
Step 2: The application .lod file can be compiled to generate a new .lod file. And the firmware .lod is in
folder \upgrade of the new firmware package with the name “XXX_UPG.lod”.
Step 3: Make the delta firmware package with the tool OpenCPU_DFOTA_Package_Tool.
Step 4: Put the package (.pack file) on customers’ server.
Step 5: Launch upgrading processing by sending some commands locally or remotely.

Compile the new application .lod file

Make the delta firmware package.
or get the firmware .lod from the
new firmware package.

GPRS
(HTTP, TCP/
UDP, FTP)
Customers’ Server

Quectel
Module Memory

Terminal Device Figure 2: OpenCPU DFOTA Flow

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 9 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

3.1. Compile Application.lod File and Generate New .lod File

The application .lod file can be compiled to generate a new .lod file. And customers can compile the new
codes that they want to upgrade to the module. Quectel_MC25-OpenCPU_User_Guide,
Quectel_M25-OpenCPU_User_Guide, or Quectel_M56-R-OpenCPU_User_Guide introduces how to
compile codes to generate a new .lod file.

NOTE

If customers only want to upgrade firmware, then this step can be skipped.

3.2. Make the Delta Firmware Package

Open OpenCPU_DFOTA_Package_Tool (path: sdk\tools), select the .lod file that is downloaded to the
module before in “Old .LOD”, select the .lod file that to be upgraded to the module in “New .LOD”, select
the generated path in “Patch” and the other parameters will be set by default. Click the “Run” button, then
an .pack file named “DFOTA.pack” will be generated, and the file can be renamed.

Figure 3: Make the Delta Firmware Package

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 10 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

The configuration of packaging firmware .lod and that of packaging application .lod are different. And the
"Edit" button is used for the configuration. Please note that the DFOTA Reserved Size, Code Flash Base,
and Code Flash Size for configuration of packaging firmware and application .lod files must follow the two
figures shown below. Please refer to Chapter 3.2.1 and 3.2.2 for details.

3.2.1. Configuration for Packaging Firmware .lod

Figure 4: Configuration for Packaging Firmware .lod

3.2.2. Configuration for Packaging Application .lod

Figure 5: Configuration for Packaging Application .lod

3.3. Put the Generated .pack File on the Server

First of all, build a server that can be accessed by module via FTP or HTTP. Then put the generated .pack
file DFOTA.pack (can be renamed) on the server.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 11 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

3.4. Start DFOTA

The firmware or application upgrade process via DFOTA can be launched either locally or remotely. If the
device is portable, a local method can be designed to launch the firmware or application upgrade via
DFOTA, such as a button or a menu item; and if the device is unattended, a remote method to launch the
firmware or application upgrade via DFOTA is recommended. For example, a call, a short message, or a
special frame of TCP/UDP data can be used to start the firmware or application upgrade via DFOTA
remotely. For remote method, upgrade command can be sent to a lot of devices simultaneously.

After receiving the upgrade command or request, the program just need to call one API
Ql_DFOTA_StartUpgrade() to start DFOTA.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 12 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

4 DFOTA API
An API function can be called to complete related programming of OpenCPU DFOTA. The URL address,
port and account information should be included in the API parameters.

4.1. Ql_DFOTA_StartUpgrade

This API function is used to start DFOTA upgrading process. Only this function needs be called to launch
DFOTA when the update data is ready in FTP or HTTP server.

 Prototype

typedef bool (* Callback_Upgrade_State)(Upgrade_State state, s32 fileDLPercent);

s32 Ql_DFOTA_StartUpgrade(u8* url, ST_GprsConfig* apnCfg, Callback_Upgrade_State

callbcak_UpgradeState_Ind);

 Parameters

url:
[In]: The URL address of the destination .pack file, along with other relative information such as port,
username and password.

The URL format of HTTP is: http://hostname:port/filePath/fileName. If “:port” in the URL is omitted, it means
the port is HTTP default port (80).

The URL format of FTP is: ftp://hostname:password/filePath/fileName:port@username:password. If “:port”

in the URL is omitted, it means the port is FTP default port (21). If there is no username and password,
“@username:password” (“@” must be included) can be omitted.

URL examples are given as below:

 ftp://www.jjj.com/filePath/xxx.pack:8021@username:passwerd
 ftp://www.jjj.com/filePath/xxx.pack@username:passwerd
 ftp://192.168.10.10/filePath/APP.pack
 http://23.11.67.89/filePath/xxx.pack
 http://www.quectel.com:8080/filePath/xxx.pack

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 13 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

apnCfg:
[In]: APN related parameters.

callbcak_UpgradeState_Ind:
[Out]: Callback function that reports the upgrade state. If it is Null, a default callback function
“Dfota_Upgrade_States” will be used.

 Return

0: Indicates this function is successfully executed.

-1: Indicates this function failed.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 14 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

5 How to Program DFOTA

Quectel provides two examples named example_dfota_ftp.c and example_dfota_http.c, which fully
demonstrate how to upgrade the firmware or application via DFOTA.

Please refer to the following instructions to program the upgrade process via DFOTA.

5.1. Define DFOTA Downloading Protocol

DFOTA function is controlled by macros defined in the file custom_feature_def.h.

/************************************************************************
* DFOTA Feature Definition
************************************************************************/
#define __OCPU_DFOTA_BY_HTTP__
#define __OCPU_DFOTA_BY_FTP__

For FTP:
If the delta firmware package is downloaded from a FTP server, customers need to define the macro
“__OCPU_DFOTA_BY_FTP__” and comment the macro “__OCPU_DFOTA_BY_HTTP__”.

For HTTP:
If the delta firmware package is downloaded from a HTTP server, customers need to define the macro
“__OCPU_DFOTA_BY_HTTP__” and comment the macro “__OCPU_DFOTA_BY_FTP__”.

5.2. Execute DFOTA API

Set the APN according to the actual situation of customers and write the URL according to the required
format. Then, call the function Ql_DFOTA_StartUpgrade() to start the upgrade process. Please note that
the URL must be written as required, otherwise the upgrade will fail. For more details of the URL format,
please refer to Chapter 4.

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 15 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

#define URL_ADDR ftp://192.168.xxx. xxx/filePath/app.pack:21@abc:abc

ST_GprsConfig apnCfg;
Ql_strncpy(apnCfg.apnName, “CMNET”, Ql_strlen(“CMNET”));
Ql_strncpy(apnCfg.apnUserId, “123”, Ql_strlen(“123”));
Ql_strncpy(apnCfg.apnPasswd, “123”, Ql_strlen(“123”));

s32 ret = Ql_DFOTA_StartUpgrade(URL_ADDR, &apnCfg, CallBack_UpgradeState_Ind);

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 16 / 17
 GSM/GPRS/GNSS Module Series
MC25&M25&M56-R-OpenCPU DFOTA Application Note

6 Appendix A Reference

Table 1: Reference Documents

SN Document Name

[1] Quectel_MC25-OpenCPU_User_Guide

[2] Quectel_M25-OpenCPU_User_Guide

[3] Quectel_M56-R-OpenCPU_User_Guide

Table 2: Abbreviations

Abbreviation Description

App OpenCPU Application

Core Core System, OpenCPU Operating System

OS Operating System

SDK Software Development Kit

API Application Programming Interface

DFOTA Delta Firmware Upgrade Over-The-Air

MC25&M25&M56-R-OpenCPU_DFOTA_Application_Note 17 / 17