Quectel OpenCPU Quick Start Application Note V1.1

OpenCPU Quick Start
Application Note
GPS/GPRS Module Series
Rev. OpenCPU_Quick_Start_Application_Note_V1.1
Date: 2014-10-11
www.quectel.com
GSM/GPRS Module Series
OpenCPU Quick Start 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.

Office 501, Building 13, No.99, Tianzhou Road, Shanghai, China, 200233
Tel: +86 21 5108 6236
Mail: [email protected]
Or our local office, for more information, please visit:
l
http://www.quectel.com/support/salesupport.aspx
t e
For technical support, to report documentation errors, please visit:
c l
http://www.quectel.com/support/techsupport.aspx
u e t ia
GENERAL NOTES
n
QUECTEL OFFERS THIS INFORMATION AS A SERVICE TO ITS CUSTOMERS. THE INFORMATION
PROVIDED IS BASED UPON CUSTOMERS’ REQUIREMENTS. QUECTEL MAKES EVERY EFFORT
Q ide
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
f
RELIANCE UPON THE INFORMATION. ALL INFORMATION SUPPLIED HEREIN IS SUBJECT TO
CHANGE WITHOUT PRIOR NOTICE.
COPYRIGHT
o n
THIS INFORMATION CONTAINED HERE IS PROPRIETARY TECHNICAL INFORMATION OF
C
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. 2014. All rights reserved.
OpenCPU_Quick_Start_Application_Note Confidential / Released 1 / 33

APPLICATIVE PRODUCT
MODULE TYPE
M85
l
M66
c t e l
u e t ia
Q ide n
n f
Co

About the Document
History
el
Revision Date Author Description
t l
1.0 2014-03-13 Stanley YONG Initial
c a
1. Added M66 and M85 R2.0 as
e i
supported modules, and modified the
t
1.1 2014-10-11 Stanley YONG description about download tool.
u
2. Added the description about how to
n
work with Eclipse.
Q ide
n f
Co

Contents
About the Document ................................................................................................................................... 3

Contents ....................................................................................................................................................... 4
Table Index ................................................................................................................................................... 6
Figure Index ................................................................................................................................................. 7
1 Introduction .......................................................................................................................................... 8
2 OpenCPU Documentation ................................................................................................................... 9
l
3 Necessaries ........................................................................................................................................ 10
3.1. Host System .......................................................................................................................... 10
e
3.2. Compiler and IDE .................................................................................................................. 10
t
3.3. Programming Language ........................................................................................................ 10
c l
3.4. Module Hardware .................................................................................................................. 10
3.5. OpenCPU SDK ...................................................................................................................... 11
e ia
4 Set up Development Environment ................................................................................................... 12
u t
4.1. Command Line ...................................................................................................................... 12
n
4.2. Work with IDE (Eclipse) ......................................................................................................... 12
Q ide
5 Compilation ........................................................................................................................................ 13
5.1. Compiling ............................................................................................................................... 13
5.2. Compiling Output ................................................................................................................... 13
f
6 Download ............................................................................................................................................ 14
6.1. For TE-A ................................................................................................................................ 14
n
6.2. For Raw Module .................................................................................................................... 14
o
6.3. For Mass Production ............................................................................................................. 14
6.4. Download ............................................................................................................................... 14
C
7 Debugging .......................................................................................................................................... 15
8 About OpenCPU SDK ........................................................................................................................ 16
9 Create Your Project ........................................................................................................................... 18
10 Quick Start with Program .................................................................................................................. 19

10.1. How to Program GPIO .......................................................................................................... 19
10.2. How to Program GPRS ......................................................................................................... 23
11 Reference Design and Programming Notes ................................................................................... 30

11.1. External Watchdog ................................................................................................................ 30
11.2. Resetting Module Solution .................................................................................................... 30
11.3. Critical User Data Protection ................................................................................................. 30
11.4. Power Saving Mode .............................................................................................................. 31
11.5. UART Port ............................................................................................................................. 31
11.6. Timer ...................................................................................................................................... 31

11.7. Dynamic Memory................................................................................................................... 32

11.8. GPRS and TCP ..................................................................................................................... 32
12 Appendix ............................................................................................................................................. 33
12.1. Reference .............................................................................................................................. 33
t el
e c ia l
u n t
Q ide
n f
Co

Table Index
TABLE 1: OPENCPU DOCUMENTATION .......................................................................................................... 9

TABLE 2: DIRECTORY DESCRIPTION ............................................................................................................ 16
TABLE 3: REFERENCE DOCUMENT .............................................................................................................. 33
t el
e c ia l
u n t
Q ide
n f
Co

Figure Index
FIGURE 1: DIRECTORY HIERARCHY ............................................................................................................. 16

FIGURE 2: CUSTOM DIRECTORY .................................................................................................................. 18
FIGURE 3: EVB LED INDICATOR .................................................................................................................... 20
t el
e c ia l
u n t
Q ide
n f
Co

1 Introduction
This document describes how to quickly start to program with OpenCPU Software Development Kit.
Besides, this document tells the dos and don’ts for reference to design and program the application.
t el
e c ia l
u n t
Q ide
n f
Co

2 OpenCPU Documentation
Table 1: OpenCPU Documentation
Document Description
l
Description of the first step to use OpenCPU
Quectel_OpenCPU_Quick_Start_Application_Note
e
SDK to develop application.
t
Complete description of OpenCPU platform.
l
Quectel_OpenCPU_User_Guide This document includes the description of the
c
OpenCPU user APIs.
e ia
This document describes how to program AT
t
Quectel_OpenCPU_RIL_Application_Note command with RIL API, and get the response
u
of AT command when the API returns.
n
This document describes how to program
Quectel_OpenCPU_FOTA_Application_Note
Q ide
FOTA in application.
This document introduces OpenCPU Security
Quectel_OpenCPU_Security_Data_Application_Note Data Solution, and shows how to program the
critical data in OpenCPU platform.
f
This document introduces OpenCPU
Quectel_OpenCPU_Watchdog_Application_Note
n
watchdog solution.
Guide for the installation steps of GCC
o
Quectel_OpenCPU_GCC_Installation_Guide
compiler.
This document tells how to set up the Eclipse
Quectel_OpenCPU_GCC_Eclipse_User_Guide
C
IDE development environment.
This document describes how to download
Firmware_Upgrade_Tool_Lite_GS2_User_Guide firmware using the download tool, which is
applicable to M85 R1.0 OpenCPU module.
This document describes how to download
firmware using the download tool, which is
Quectel_QFlash_User_Guide
applicable to M66 and M85 R2.0 OpenCPU
module.

3 Necessaries
To work with OpenCPU, you need to confirm if you have had the software and hardware components
listed below.
l
3.1. Host System
t e l
The following host operating systems and architectures are supported.
e c ia
 Microsoft Windows XP (SP1 or later)
t
 Windows Vista
u
 Windows 7 systems using IA32, AMD64, and Intel 64 processors
Q ide
3.2. Compiler and IDE
n
f
 GCC Compiler (Sorcery CodeBench Lite for ARM EABI). Please refer to the document [1].
n
 Command-line complication. Please refer to the document [2].
 IDE: Eclipse (Optional). Please refer to the document [4].
Co
3.3. Programming Language
Basic C-language programming knowledge is a must.
3.4. Module Hardware
 Quectel GSM/GPRS Module with OpenCPU features

 Quectel EVB
 Other accessories (power adapter, COM cable)
If you need these parts, please contact Quectel technical support.

3.5. OpenCPU SDK
 OpenCPU SDK software package
You can get the software package from Quectel technical support at [email protected].
 Firmware Download Tool (included in SDK).
t el
e c ia l
u n t
Q ide
n f
Co

4 Set up Development Environment

Quecel OpenCPU supports two ways to develop and compile application program: command-line and
Eclipse IDE. Two different software development kit packages are issued for the different compiling tools.
For example, the “OpenCPU_GS3_SDK_V1.0” package is applicable to command line, and
“OpenCPU_GS3_SDK_V1.0_Eclipse” (_Eclipse suffix is appended) is applicable to Eclipse.
l
Whatever compiling way it is, the compiler is GCC (Sourcery CodeBench Lite for ARM). Please refer to
t e
the Chapter 2 in document [1] to install GCC compiler and verify the validity before you choose a
l
compiling way.
e c t ia
u
4.1. Command Line
Q ide n
Since the compiling commands are very simple in OpenCPU (only make clean/new are used), so this
compiling way is the default compiling way. And developer may mange the application codes with some
code management tool, such as Source Insight.
f
Developer just needs to refer to the following two steps to set up the development environment.
n
 Install Sourcery CodeBench Lite on your host computer. Please refer to the Chapter 2 in
o
document [1] to install GCC compiler and verify the validity.
C
 Set up the environment after installation. Please refer to the Chapter 3 in document [1] to
configure the environment.
4.2. Work with IDE (Eclipse)
Please refer to the document [4] for how to work with Eclipse.

5 Compilation
This section only introduces how to compile the program in command line. Please refer to document [4]
for how to compile with Eclipse.
l
5.1. Compiling
t e l
In OpenCPU, compiling commands are executed in command line. The clean and compiling commands
c
are defined as below.
e t ia
make clean
u
make new
Q ide
5.2. Compiling Output
n
f
In command-line, some compiler processing information will be output during compiling. All WARNINGs
n
and ERRORs are recorded in “\SDK\build\gcc\build.log”.
o
If there’s any compiling error during compiling, please check the “build.log” for the error line number and
the error hints.
C
6 Download
6.1. For TE-A
l
If you are using TE-A module and EVB, please download firmware through the MAIN port on EVB.
6.2. For Raw Module
c t e l
e t ia
If the module has been pasted on your own board, please download firmware through the UART port 1.
u
Q ide
6.3. For Mass Production
n
f
In order to improve the production efficiency, Quectel provides the special fixture and download tool which
can download firmware to several pieces of modules at one time. Mass production customers can consult
n
Quectel technical support for that if needed.
6.4. Download
Co
The document [5] (for M85 R1.0) and [6] (for M85 R2.0 and M66) introduces the download tool and how to
use it to download application bin.

7 Debugging
In OpenCPU, printing trace messages through serial port is the main debugging method.
OpenCPU module provides three serial ports, MAIN UART (UART PORT 1), DEBUG UART (UART
PORT 2) and AUX UART (UART PORT 3).
l
In program, you can call Ql_UART_Open() to open any UART port, and call Ql_UART_Write() to output
t e
debugging messages. Especially, if the DEBUG port is used as debugging port, the API function
l
Ql_Debug_Trace() is available to output messages through DEBUG port. The Ql_Debug_Trace function
c
can format and print a series of characters and values through DEBUG port.
u e t ia
Q ide n
n f
Co

8 About OpenCPU SDK

You can decompress the SDK package to get the directory structure of OpenCPU SDK. The typical
directory hierarchy is as below.
t el
e c ia l
u n t
Q ide
f
Figure 1: Directory Hierarchy
n
Table 2: Directory Description
o
Directory Description
C
OpenCPU_SDK The root directory of OpenCPU SDK.
build All compiling results are output to this directory.

This directory is designed as the root directory of your project.
In the subdirectory “custom\config\”, you can reconfigure the
application according to requirements, such as heap memory
custom
size, multitasks and the stack size of tasks, GPIO initial status.
All configuration files for you are named with prerfix
“custom_”.
docs Store all OpenCPU related documents.

All example codes are here. Each example file implements an
example application of independent function. And each example file
can be compiled to an executable image bin.

include All APIs head files are stored here.
libs Dependent libraries for compiling.
make All compiling scripts and makefile are placed here.

Place the open source codes of OpenCPU RIL.
ril You can also easily add a new API to implement a standard AT
command based on the open source of RIL.
Some tools for application development, such as download
tools
tool and packaging tool for FOTA.
l
Please refer to the Section 2.4 in document [2] for more details about SDK development environment,
such as compiling method and download.
t e
Please refer to Chapter 4 in document [2] for system configuration of application, such as heap memory
c l
size, tasks, stack size of tasks and GPIO initial status.
u e t ia
Q ide n
n f
Co

9 Create Your Project

By default, the directory SDK\custom\ is designed as the root directory of your project. In this directory, a
program file “main.c” is placed, which demonstrates the primary program framework of OpenCPU
program.
t el
e c ia l
u n t
Q ide Figure 2: Custom Directory
n f
In the directory SDK\custom\, you can add other module files and subdirectories. Please refer to the
o
Section 2.4.5 in document [2] for extended information.
All source code files are managed by the makefile \SDK\make\gcc\gcc_makefile. You can decide which
C
directories, and which source code files need to be compiled in this makefile. Please refer to the Section
2.4.5 in document [2] for extended information.
Up to now, you may notice that there is a default project. What you need to do is to add codes to main.c,
or change the existing codes in main.c. Besides, you can add other .c files. And all newly-added .c files in
SDK\custom\ will be compiled automatically.

10 Quick Start with Program

In this section, two example applications are given to guide how to start to program over OpenCPU SDK.
The first example application implements an LED blinking by periodically pulling down/up a GPIO. The
other example application demonstrates how to program GPRS, and send a package of data to server.
l
All example codes will cover SDK\custom\main.c. Or you can delete the main.c and create a new .c file.
c
10.1. How to Program GPIO
t e l
e t ia
 Include Head Files
u n
To know which head files are needed, you should understand the requirements of this application. For this
Q ide
example application, the requirement is: implementing an LED blinking by periodically pulling down/up a
GPIO.
First of all, you need to control a GPIO, the APIs and related definitions are in ql_gpio.h.
n f
Secondly, “periodically” means a timer is needed. The related definitions are in ql_timer.h.
o
Finally, any application has a message loop procedure, so the ql_system.h is must. Besides, you need to
print some log information to debug the program, the related head files are ql_stdlib.h and ql_trace.h. All
C
return values for API functions are defined in ql_error.h.
Conclusions as a result, the head files that you need to include are as follows:
#include "ql_stdlib.h"
#include "ql_trace.h"
#include "ql_error.h"
#include "ql_system.h"
#include "ql_gpio.h"
#include "ql_timer.h"
 Program GPIO
On Quectel EVB, the NETLIGHT pin and STATUS pin have been respectively connected to an LED,
which means you can control NETLIGHT pin or STATUS pin to implement LED blinking.

Figure 3: EVB LED Indicator
Here, the program chooses NETLIGHT pin as GPIO pin.
el
// Define GPIO pin
t
static Enum_PinName m_gpioPin = PINNAME_NETLIGHT;
c l
At the beginning of this application, the GPIO is initialized like this:
e t ia
 Directory – output
u
 Initial level – low
n
 Pull state – pull enable and pull up
Q ide
// Initialize GPIO
ret = Ql_GPIO_Init(m_gpioPin, PINDIRECTION_OUT, PINLEVEL_LOW, PINPULLSEL_PULLUP);
if (QL_RET_OK == ret)
f
{
Ql_Debug_Trace("<-- Initialize GPIO successfully -->\r\n");
n
}else{
o
Ql_Debug_Trace("<-- Fail to initialize GPIO pin, cause=%d -->\r\n", ret);
}
C
Next, you need to start a timer, and pull up/down the GPIO periodically to implement LED blinking.
 Timer and LED Blinking
In this case, the program defines a timer with the timeout of 500ms. It means the LED will light for 500ms
and becomes dark for 500ms.
Firstly, define a timer and the timer interrupt handler.
// Define a timer and the handler

static u32 m_myTimerId = 2014;
static u32 m_nInterval = 500; // 500ms
static void Callback_OnTimer(u32 timerId, void* param);

Secondly, register and start the timer.
// Register and start timer

Ql_Timer_Register(m_myTimerId, Callback_OnTimer, NULL);
Ql_Timer_Start(m_myTimerId, m_nInterval, TRUE);
Finally, implement the timer interrupt handler.
static void Callback_OnTimer(u32 timerId, void* param)

{
s32 gpioLvl = Ql_GPIO_GetLevel(m_gpioPin);
l
if (PINLEVEL_LOW == gpioLvl)
{
e
// Set GPIO to high level, then LED is light
t
Ql_GPIO_SetLevel(m_gpioPin, PINLEVEL_HIGH);
c l
Ql_Debug_Trace("<-- Set GPIO to high level -->\r\n");
a
}else{
e i
// Set GPIO to low level, then LED is dark
u t
Ql_GPIO_SetLevel(m_gpioPin, PINLEVEL_LOW);
n
Ql_Debug_Trace("<-- Set GPIO to low level -->\r\n");
}
Q ide
}
Now, all programming work are finished. The complete codes are as below.
f
n
o
C
#include "ql_gpio.h"
#include "ql_timer.h"
// Define GPIO pin

static Enum_PinName m_gpioPin = PINNAME_NETLIGHT;
// Define a timer and the handler

static u32 m_myTimerId = 2014;
static u32 m_nInterval = 500; // 500ms
static void Callback_OnTimer(u32 timerId, void* param);
/************************************************************************/
/* The entrance procedure for this example application */
/************************************************************************/
void proc_main_task(s32 taskId)

{
s32 ret;
ST_MSG msg;
Ql_Debug_Trace("OpenCPU: LED Blinking by NETLIGH\r\n");
// Initialize GPIO
ret = Ql_GPIO_Init(m_gpioPin, PINDIRECTION_OUT, PINLEVEL_LOW,
PINPULLSEL_PULLUP);
if (QL_RET_OK == ret)
{
l
Ql_Debug_Trace("<-- Initialize GPIO successfully -->\r\n");
}else{
t e
Ql_Debug_Trace("<-- Fail to initialize GPIO pin, cause=%d -->\r\n", ret);
l
}
c a
// Register and start timer
e i
Ql_Timer_Register(m_myTimerId, Callback_OnTimer, NULL);
u t
Ql_Timer_Start(m_myTimerId, m_nInterval, TRUE);
n
// START MESSAGE LOOP OF THIS TASK
Q ide
while(TRUE)
{
Ql_OS_GetMessage(&msg);
f
switch(msg.message)
{
n
default:
o
break;
}
C
}
}
static void Callback_OnTimer(u32 timerId, void* param)

{
s32 gpioLvl = Ql_GPIO_GetLevel(m_gpioPin);
if (PINLEVEL_LOW == gpioLvl)
{
// Set GPIO to high level, then LED is light
Ql_GPIO_SetLevel(m_gpioPin, PINLEVEL_HIGH);
Ql_Debug_Trace("<-- Set GPIO to high level -->\r\n");
}else{
// Set GPIO to low level, then LED is dark
Ql_GPIO_SetLevel(m_gpioPin, PINLEVEL_LOW);
Ql_Debug_Trace("<-- Set GPIO to low level -->\r\n");

}
}
 Run This Application
You can copy the complete codes to SDK\custom\main.c to cover the existing codes, and compile and
download the app bin to module. Please refer to the Section 2.4.3 and 2.4.4 in document [2] for compiling
and download information.
When this application is running, you can watch the “D502” LED on EVB blinking at the period of 500ms.
Meanwhile, you can watch the following output from DEBUG port.
t el
e c ia l
u n t
Q ide
10.2. How to Program GPRS
f
 Include Head Files
n
To know which head files are needed, you should understand the requirements of this application.
o
First of all, you need to use OpenCPU RIL feature, so custom_feature_def.h and ril.h are required.
C
Secondly, GPRS-related API functions are defined in ql_gprs.h and ql_socket.h.
Finally, any application has a message loop procedure, so the ql_system.h is must. Besides, you need to
print some log information to debug the program, the related head files are ql_stdlib.h and ql_trace.h. All
return values for API are defined in ql_error.h.
Conclusions as a result, the head files that you need to include are as follows:
#include "custom_feature_def.h"
#include "ril.h"

#include "ql_gprs.h"
#include "ql_socket.h"
 Define PDP Context and GPRS Configurations
#define PDP_CONTEXT_ID 0
static ST_GprsConfig m_GprsConfig = {
"CMNET", // APN name
"", // User name for APN
"", // Password for APN
0,
l
NULL,
NULL,
e
};
c t l
Here, the APN is set to China Mobile’s APN name – “CMNET” and account. You can change APN name
a
and account accordingly.
e t i
 Define Server IP and Socket Port
u n
static u8 m_SrvADDR[20] = "116.247.104.27\0";
Q ide
static u32 m_SrvPort = 6003;
Here, the same codes define a public server and socket port of Quectel. You can use your own server.
f
 Define Receive Buffer
n
When the socket connection is established, the program needs a buffer to accept data from socket.
o
#define SOC_RECV_BUFFER_LEN 1460
C
static u8 m_SocketRcvBuf[SOC_RECV_BUFFER_LEN];
 Declare Callback for GPRS and Socket
static void Callback_GPRS_Deactived(u8 contextId, s32 errCode, void* customParam);

static void Callback_Socket_Close(s32 socketId, s32 errCode, void* customParam );
static void Callback_Socket_Read(s32 socketId, s32 errCode, void* customParam );
static void Callback_Socket_Write(s32 socketId, s32 errCode, void* customParam );
Callback_GPRS_Deactivated: when GPRS network drops down, this callback will be invoked.
Callback_Socket_Close: when socket connection is disconnected, this callback will be invoked.
Callback_Socket_Read: when socket data comes, this callback will be invoked.
Callback_Socket_Write: when call Ql_SOC_Write to send data to socket, but socket is busy. Later, this
callback will be invoked to inform App that socket is available.

 Program OpenCPU RIL
Since you need to use OpenCPU RIL feature, application needs to call Ql_RIL_Initialize() to initialize
RIL-related functions when the main task receives the message MSG_ID_RIL_READY.

while(TRUE)
{
switch(msg.message)
{
l
case MSG_ID_RIL_READY:
Ql_Debug_Trace("<-- RIL is ready -->\r\n");
e
Ql_RIL_Initialize();
t
break;
c a l
 Program System URC Messages
u e t i
Before accessing GPRS network, you have to wait till the module has registered to GPRS network. When
n
the module registers to GPRS network, application will receive the URC message
URC_GPRS_NW_STATE_IND. Before this, application program receives some other URC messages
Q ide
which indicates the initializing status of module during booting, such as CFUN status, SIM card status and
GSM network status changing. You can properly program these URC messages after receiving them.
f
The following codes are the complete system messages and URC messages programming.
n
/************************************************************************/
o
/* The entrance procedure for this example application */
/************************************************************************/
void proc_main_task(s32 taskId)
C
{
ST_MSG msg;
Ql_Debug_Trace("OpenCPU: Simple GPRS-TCP Example\r\n");

while(TRUE)
{
switch(msg.message)
{
case MSG_ID_RIL_READY:
Ql_Debug_Trace("<-- RIL is ready -->\r\n");
Ql_RIL_Initialize();

break;
case MSG_ID_URC_INDICATION:
// Ql_Debug_Trace("<-- Received URC: type: %d, -->\r\n", msg.param1);
switch (msg.param1)
{
case URC_SYS_INIT_STATE_IND:
Ql_Debug_Trace("<-- Sys Init Status %d -->\r\n", msg.param2);
break;
case URC_SIM_CARD_STATE_IND:
Ql_Debug_Trace("<-- SIM Card Status:%d -->\r\n", msg.param2);
break;
l
case URC_GSM_NW_STATE_IND:
Ql_Debug_Trace("<-- GSM Network Status:%d -->\r\n", msg.param2);
e
break;
t
case URC_GPRS_NW_STATE_IND:
c l
Ql_Debug_Trace("<-- GPRS Network Status:%d -->\r\n", msg.param2);
a
if (NW_STAT_REGISTERED == msg.param2)
e i
{
u t
GPRS_Program();
n
}
break;
Q ide
case URC_CFUN_STATE_IND:
Ql_Debug_Trace("<-- CFUN Status:%d -->\r\n", msg.param2);
break;
f
default:
Ql_Debug_Trace("<-- Other URC: type=%d\r\n", msg.param1);
n
break;
o
}
break;
default:
C
break;
}
}
}

 Program GPRS
After module registers to GPRS network, you can start to program GPRS. GPRS programming mostly
contains the several steps below. You can also refer to the Section 5.8 in document [2] for the detailed
information of GPRS related APIs and usage.
First of all, register GPRS-related callback functions.
ST_PDPContxt_Callback callback_gprs_func = {
NULL,
Callback_GPRS_Deactived
l
};
ST_SOC_Callback callback_soc_func = {
e
NULL,
t
Callback_Socket_Close,
c l
// callback_socket_accept,
a
NULL,
e i
Callback_Socket_Read,
u t
Callback_Socket_Write
n
};
Q ide
// Register GPRS callback
ret = Ql_GPRS_Register(PDP_CONTEXT_ID, &callback_gprs_func, NULL);
if (GPRS_PDP_SUCCESS == ret)
f
{
Ql_Debug_Trace("<-- Register GPRS callback function -->\r\n");
n
}else{
o
Ql_Debug_Trace("<-- Fail to register GPRS, ret=%d. -->\r\n", ret);
return;
}
C
Secondly, configure PDP context.
ret = Ql_GPRS_Config(PDP_CONTEXT_ID, &m_GprsConfig);

if (GPRS_PDP_SUCCESS == ret)
{
Ql_Debug_Trace("<-- Configure GPRS PDP -->\r\n");
}else{
Ql_Debug_Trace("<-- Fail to configure GPRS PDP, ret=%d. -->\r\n", ret);
return;
}

Thirdly, activate PDP.
ret = Ql_GPRS_ActivateEx(PDP_CONTEXT_ID, TRUE);

if (ret == GPRS_PDP_SUCCESS)
{
m_GprsActState = 1;
Ql_Debug_Trace("<-- Activate GPRS successfully. -->\r\n\r\n");
}else{
Ql_Debug_Trace("<-- Fail to activate GPRS, ret=%d. -->\r\n\r\n", ret);
return;
}
l
Finally, deactivate PDP (if not needed).
t e
ret = Ql_GPRS_DeactivateEx(PDP_CONTEXT_ID, TRUE);
c l
Ql_Debug_Trace("<-- Deactivate GPRS, ret=%d -->\r\n\r\n", ret);
e ia
 Program Socket
u t
After GPRS PDP is activated, you can start to program TCP/UDP socket. Socket programming mostly
n
contains the several steps below. Please refer to the Section 5.9 in document [2] for the detailed
Q ide
information of GPRS related APIs and usage.
First, register socket related callback functions.
f
ret = Ql_SOC_Register(callback_soc_func, NULL);
n
if (SOC_SUCCESS == ret)
{
o
Ql_Debug_Trace("<-- Register socket callback function -->\r\n");
}else{
C
Ql_Debug_Trace("<-- Fail to register socket callback, ret=%d. -->\r\n", ret);
return;
}
Secondly, create socket.
m_SocketId = Ql_SOC_Create(PDP_CONTEXT_ID, SOC_TYPE_TCP);

if (m_SocketId >= 0)
{
Ql_Debug_Trace("<-- Create socket successfully, socket id=%d. -->\r\n", m_SocketId);
}else{
Ql_Debug_Trace("<-- Fail to create socket, ret=%d. -->\r\n", m_SocketId);
return;
}

Thirdly, connect to socket server.
ret = Ql_SOC_ConnectEx(m_SocketId,(u32)m_ipAddress, m_SrvPort, TRUE);

if (SOC_SUCCESS == ret)
{
m_SocketConnState = 1;
Ql_Debug_Trace("<-- Connect to server successfully -->\r\n");
}else{
Ql_Debug_Trace("<-- Fail to connect to server, ret=%d -->\r\n", ret);
Ql_Debug_Trace("<-- Close socket.-->\r\n");
Ql_SOC_Close(m_SocketId);
l
m_SocketId = -1;
return;
e
}
c t l
After the socket is connected with server, you can send data to server or receive data from server.
e ia
Fourthly, send socket data.
u n t
char pchData[200];
s32 dataLen = 0;
Q ide
u64 ackNum = 0;
Ql_memset(pchData, 0x0, sizeof(pchData));
dataLen += Ql_sprintf(pchData + dataLen, "%s", "A B C D E F G");
f
ret = Ql_SOC_Send(m_SocketId, (u8*)pchData, dataLen);
if (ret == dataLen)
n
{
o
Ql_Debug_Trace("<-- Send socket data successfully. --> \r\n");
}else{
Ql_Debug_Trace("<-- Fail to send socket data. --> \r\n");
C
}
Here, the codes demonstrate sending data “A B C D E F G” to server.
After sending data, you can call Ql_SOC_GetAckNumber() to check if the server has received the data.
Besides, you can call Ql_SOC_Close() to close socket connection, and call Ql_GPRS_DeactivateEx() to
deactivate GPRS PDP.
You can refer to the example_tcp_demo.c in SDK for the complete codes. And you can compile and run
this example. The usage for this example is included in the example.

11 Reference Design and

Programming Notes
11.1. External Watchdog
el
In actual product, if no external MCU, please add external watchdog chip to prevent application from
t
exception. When the external watchdog overflows, please reset the VBAT pin of module to power off/on
c l
the module, so that the module can reset status thoroughly.
e ia
In program, you can specify the GPIO pin to feed the extern watchdog in \SDK\custom\custom_sys_cfg.c.
u t
For multitask application, OpenCPU has designed the special watchdog solution that can monitor all tasks
n
with an external watchdog chip. Please refer to the document [7] for extended information.
Q ide
11.2. Resetting Module Solution
n f
In order to keep a stable running state, it is recommended to add resetting module mechanism. For
o
example, reset the module when the module is idle or has low load. The 24-hour of resetting period is
recommended.
C
When network trouble happens to module, such as GSM/GPRS registration failure, you can use this
resetting solution to restore it.
There are software method (API function) and hardware method to reset the module (refer to the previous
section - external watchdog). It is recommended to use hardware method, so that the module can reset
thoroughly.
11.3. Critical User Data Protection
Please adopt OpenCPU Security Data Solution to store the critical configurations for the application, such
as APN, server IP address and socket port number. The safe storing region can contain 1700 bytes data.

The data is directly accessed on raw flash. For the sake of flash life, please control the frequency of
writing. Please refer to the document [3] for the extended information of OpenCPU Security Data Solution.
11.4. Power Saving Mode
You can call Ql_SleepEnable to enable power saving mode (low power consumption mode, or sleep
mode), the system will switch to 32K clock to work when CPU is idle. Under sleep mode, UART port
cannot receive data. QL_SleepDisable can disable the power saving mode.
l
Please note that when application launches the GPT timer (fast timer), the module cannot enter into
power saving mode.
c t e l
a
11.5. UART Port
u e t i
OpenCPU module provides three serial ports. The default configuration parameters are: 115200 baud
n
rate, and 8N1. The data buffer size of UART port is 2KB.
Q ide
When received the event “EVENT_UART_READY_TO_READ” in UART callback, application should call
Ql_UART_Read to read all data out of the UART buffer. Or application cannot receive this event when
new data comes and cause UART port “dead”.
n f
When you call Ql_UART_Write to send data, if the returned bytes number is less than the bytes number
to write, which means the UART buffer is full, the program should stop sending data and wait for the
o
EVENT_UART_READY_TO_WRITE event in UART callback to send the remained data.
C
11.6. Timer
In OpenCPU, there are two kinds of timers, one is common timer, and the other is fast timer. There’re 10
common timers available for each task, and there’s only one fast timer for whole application. The common
timer is probably delayed because of task scheduling, so a common timer is a task timer, while the fast
timer doesn’t belong to any task, and it’s triggered by interruption. So the fast timer has good real-time.
However, please don’t put too much work load in the interruption handler, which can cause system
exception.

11.7. Dynamic Memory
You can call Ql_MEM_Alloc() to apply for the specified size of dynamic memory, and call Ql_MEM_Free()
to free the memory. The size of the dynamic memory of application is maximum 500KB available.
11.8. GPRS and TCP
For simplifying GPRS and TCP socket programming, the GPRS/TCP related API functions have been
l
designed for synchronous APIs, which means the API functions return the final result. The maximum time
for the synchronous API to return is 180s.
t e l
Synchronous APIs about GPRS:
c a

e
s32 Ql_GPRS_ActivateEx(u8 contextId, bool isBlocking); the timeout is 180s.
i

t
s32 Ql_GPRS_DeactivateEx(u8 contextId, bool isBlocking); the timeout is 90s.
u n
Synchronous APIs about TCP socket:
Q ide
 s32 Ql_SOC_ConnectEx(s32 socketId, u32 remoteIP, u16 remotePort, bool isBlocking); the timeout
is 75s.
 s32 Ql_IpHelper_GetIPByHostNameEx (u8 contextId, u8 requestId, u8 *hostName, u32*
f
ipCount,u32* ipAddress); the timeout is 60s.
o n
C
12 Appendix
12.1. Reference
el
Table 3: Reference Document
t l
SN Document Name
c a
[1] Quectel_OpenCPU_GCC_Installation_Guide
e t i
[2] Quectel_OpenCPU_User Guide
u n
[3] Quectel_OpenCPU_Security_Data_Application_Note
Q ide
[4] Quectel_OpenCPU_GCC_Eclipse_User_Guide
[5] Quectel_Firmware_Upgrade_Tool_Lite_GS2_User_Guide
f
[6] Quectel_QFlash_User_Guide
n
[7] Quectel_OpenCPU_Watchdog_Application_Note
Co

Quectel OpenCPU Quick Start Application Note V1.1

Uploaded by

Copyright:

Available Formats

Quectel OpenCPU Quick Start Application Note V1.1

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Quectel OpenCPU Quick Start Application Note V1.1

Uploaded by

Copyright:

Available Formats

OpenCPU Quick Start

GPS/GPRS Module Series

Quectel Wireless Solutions Co., Ltd.

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

OpenCPU_Quick_Start_Application_Note Confidential / Released 1 / 33

OpenCPU_Quick_Start_Application_Note Confidential / Released 2 / 33

About the Document

OpenCPU_Quick_Start_Application_Note Confidential / Released 3 / 33

About the Document ................................................................................................................................... 3

2 OpenCPU Documentation ................................................................................................................... 9

8 About OpenCPU SDK ........................................................................................................................ 16

9 Create Your Project ........................................................................................................................... 18

10 Quick Start with Program .................................................................................................................. 19

11 Reference Design and Programming Notes ................................................................................... 30

OpenCPU_Quick_Start_Application_Note Confidential / Released 4 / 33

11.7. Dynamic Memory................................................................................................................... 32

OpenCPU_Quick_Start_Application_Note Confidential / Released 5 / 33

TABLE 1: OPENCPU DOCUMENTATION .......................................................................................................... 9

OpenCPU_Quick_Start_Application_Note Confidential / Released 6 / 33

FIGURE 1: DIRECTORY HIERARCHY ............................................................................................................. 16

OpenCPU_Quick_Start_Application_Note Confidential / Released 7 / 33

OpenCPU_Quick_Start_Application_Note Confidential / Released 8 / 33

Table 1: OpenCPU Documentation

OpenCPU_Quick_Start_Application_Note Confidential / Released 9 / 33

Basic C-language programming knowledge is a must.

3.4. Module Hardware

 Quectel GSM/GPRS Module with OpenCPU features

If you need these parts, please contact Quectel technical support.

OpenCPU_Quick_Start_Application_Note Confidential / Released 10 / 33

3.5. OpenCPU SDK

 OpenCPU SDK software package

 Firmware Download Tool (included in SDK).

OpenCPU_Quick_Start_Application_Note Confidential / Released 11 / 33

4 Set up Development Environment

4.2. Work with IDE (Eclipse)

OpenCPU_Quick_Start_Application_Note Confidential / Released 12 / 33

6.1. For TE-A

6.2. For Raw Module

OpenCPU_Quick_Start_Application_Note Confidential / Released 14 / 33

OpenCPU_Quick_Start_Application_Note Confidential / Released 15 / 33

8 About OpenCPU SDK

build All compiling results are output to this directory.

docs Store all OpenCPU related documents.

OpenCPU_Quick_Start_Application_Note Confidential / Released 16 / 33

include All APIs head files are stored here.

libs Dependent libraries for compiling.

make All compiling scripts and makefile are placed here.

OpenCPU_Quick_Start_Application_Note Confidential / Released 17 / 33

9 Create Your Project

OpenCPU_Quick_Start_Application_Note Confidential / Released 18 / 33

10 Quick Start with Program

OpenCPU_Quick_Start_Application_Note Confidential / Released 19 / 33

Figure 3: EVB LED Indicator

Here, the program chooses NETLIGHT pin as GPIO pin.

 Timer and LED Blinking

Firstly, define a timer and the timer interrupt handler.

// Define a timer and the handler

OpenCPU_Quick_Start_Application_Note Confidential / Released 20 / 33

Secondly, register and start the timer.