QUECTEL EC200U Series QuecOpen SMS API

Product Information: EC200U Series QuecOpen SMS API Reference Manual

The EC200U Series QuecOpen SMS API Reference Manual is a document that provides comprehensive information on the LTE Standard Module Series manufactured by Quectel. It contains technical details on the SMS API that can be used with the module, along with legal notices, trademarks, and third-party rights information. The document also includes a revision history and table index for easy reference.

Product Usage Instructions

The EC200U Series QuecOpen SMS API Reference Manual can be used by product experts to gain in-depth knowledge about the LTE Standard Module Series and its SMS API. The manual can be accessed online through the Quectel website or downloaded for offline use. To use the manual effectively, follow these instructions:

1. Read the introduction section to understand the purpose and scope of the manual.
2. Refer to the table index to quickly find the information you need.
3. Review the legal notices section to understand the restrictions and obligations applicable to the use of the information provided in the manual.
4. Refer to the SMS demo section to learn how to use the SMS API with the module.
5. Contact Quectel’s headquarters or local offices for assistance if needed.

By following these instructions, product experts can effectively use the EC200U Series QuecOpen SMS API Reference Manual to gain a better understanding of the LTE Standard Module Series and its SMS API.

At Quectel, our aim is to provide timely and comprehensive services to our customers. If you require any assistance, please contact our headquarters:
Quectel Wireless Solutions Co., Ltd.
Building 5, Shanghai Business Park Phase III (Area B), No.1016 Tianlin Road, Minhang District, Shanghai 200233, China
Tel: +86 21 5108 6236
Email: info@quectel.com
Or our local offices. For more information, please visit:
http://www.quectel.com/support/sales.htm.
For technical support, or to report documentation errors, please visit:
http://www.quectel.com/support/technical.htm.
Or email us at: support@quectel.com.

Legal Notices
We offer information as a service to you. The provided information is based on your requirements and we make every effort to ensure its quality. You agree that you are responsible for using independent analysis and evaluation in designing intended products, and we provide reference designs for illustrative purposes only. Before using any hardware, software or service guided by this document, please read this notice carefully. Even though we employ commercially reasonable efforts to provide the best possible experience, you hereby acknowledge and agree that this document and related services hereunder are provided to you on an “as available” basis. We may revise or restate this document from time to time at our sole discretion without any prior notice to you.

Use and Disclosure Restrictions

License Agreements
Documents and information provided by us shall be kept confidential, unless specific permission is granted. They shall not be accessed or used for any purpose except as expressly provided herein.

Copyright
Our and third-party products hereunder may contain copyrighted material. Such copyrighted material shall not be copied, reproduced, distributed, merged, published, translated, or modified without prior written consent. We and the third party have exclusive rights over copyrighted material. No license shall be granted or conveyed under any patents, copyrights, trademarks, or service mark rights. To avoid ambiguities, purchasing in any form cannot be deemed as granting a license other than the normal non-exclusive, royalty-free license to use the material. We reserve the right to take legal action for noncompliance with abovementioned requirements, unauthorized use, or other illegal or malicious use of the material.

Trademarks
Except as otherwise set forth herein, nothing in this document shall be construed as conferring any rights to use any trademark, trade name or name, abbreviation, or counterfeit product thereof owned by Quectel or any third party in advertising, publicity, or other aspects.

Third-Party Rights
This document may refer to hardware, software and/or documentation owned by one or more third parties (“third-party materials”). Use of such third-party materials shall be governed by all restrictions and obligations applicable thereto.
We make no warranty or representation, either express or implied, regarding the third-party materials, including but not limited to any implied or statutory, warranties of merchantability or fitness for a particular purpose, quiet enjoyment, system integration, information accuracy, and non- infringement of any third-party intellectual property rights with regard to the licensed technology or use thereof. Nothing herein constitutes a representation or warranty by us to either develop, enhance, modify, distribute, market, sell, offer for sale, or otherwise maintain production of any our products or any other hardware, software, device, tool, information, or product. We moreover disclaim any and all warranties arising from the course of dealing or usage of trade.

Disclaimer

• We acknowledge no liability for any injury or damage arising from the reliance upon the information.
• We shall bear no liability resulting from any inaccuracies or omissions, or from the use of the information contained herein.
• While we have made every effort to ensure that the functions and features under development are free from errors, it is possible that they could contain errors, inaccuracies, and omissions. Unless otherwise provided by valid agreement, we make no warranties of any kind, either implied or express, and exclude all liability for any loss or damage suffered in connection with the use of features and functions under development, to the maximum extent permitted by law, regardless of whether such loss or damage may have been foreseeable.
• We are not responsible for the accessibility, safety, accuracy, availability, legality, or completeness of information, advertising, commercial offers, products, services, and materials on third-party websites and third-party resources.

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

About the Document

Revision History

Introduction

Quectel LTE Standard EC200U series module supports QuecOpen® solution. QuecOpen® is an embedded development platform based on RTOS system, which is intended to simplify the design and development of IoT applications. For more information on QuecOpen®, see document [1].
This document mainly introduces the SMS APIs of EC200U series module and related examples in QuecOpen® solution. SMS APIs in this document can mainly realize features listed below:

• Send SMS messages
• Receive SMS messages
• Delete SMS messages
• Get SMS center number
• Get the storage status of SMS messages

SMS APIs

Header File
ql_api_sms.h, the header file of SMS APIs, is located in the directory of ql- sdk\components\ql-kernel\inc in SDK. Unless otherwise specified, the header files mentioned in this document are all located in this directory.

API Functions Overview
Table 1: API Functions Overview

Function : Description

• ql_sms_get_init_status() Gets the initialization status of SMS
• ql_sms_send_msg() Sends SMS message in text format
• ql_sms_send_pdu() Sends SMS message in PDU format
• ql_sms_read_msg() Reads SMS message in text or PDU format
• ql_sms_read_msg_list() Reads the list of SMS messages
• ql_sms_delete_msg() Deletes SMS messages
• ql_sms_get_center_address() Gets the SMS center number
• ql_sms_set_center_address() Sets the SMS center number
• ql_sms_set_storage() Sets the storage location of SMS message
• ql_sms_get_storage() Gets storage location of SMS message
• ql_sms_get_storage_info()
• Gets the storage status of SMS message in (U)SIM card and ME
• ql_sms_callback_register() Registers the SMS message callback function

API Functions Description
ql_sms_get_init_status
This function gets the initialization status of SMS. The SMS related functions can only be called after initialization.

Prototype

• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
status:
[Out] The initialization status of SMS.
0 Uninitialized
1 Initialized

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_errcode_e
The enumeration of SMS APIs execution error codes is defined as follows:
ql_sms_errcode_e ql_sms_get_init_status(uint8_t nSim, uint8_t *status)
typedef enum
{
QL_SMS_SUCCESS = 0,
QL_SMS_ERROR = 1 | (QL_COMPONENT_SMS << 16),
QL_SMS_NOT_INIT_ERR,
QL_SMS_PARA_ERR,
QL_SMS_NO_MEMORY_ERR,
QL_SMS_SEM_CREATE_ERR,
QL_SMS_SEM_TIMEOUT_ERR,
QL_SMS_NO_MSG_ERR,
}ql_sms_errcode_e

• Parameter

Parameter : Description

• QL_SMS_SUCCESS Successful execution
• QL_SMS_ERROR Failed execution
• QL_SMS_NOT_INIT_ERR SMS service is not initialized
• QL_SMS_PARA_ERR Parameter error
• QL_SMS_NO_MEMORY_ERR No memory
• QL_SMS_SEM_CREATE_ERR Fail to create semaphore
• QL_SMS_SEM_TIMEOUT_ERR Semaphore times out
• QL_SMS_NO_MSG_ERR No SMS messages to read

ql_sms_send_msg
This function sends SMS messages in text format.

• Prototype

ql_sms_errcode_e ql_sms_send_msg(uint8_t nSim, char phone_num, char data, ql_sms_code_e code)

• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
phone_num:
[In] The recipient’s mobile phone number.
data:
[In] Message content. Length of the message content is less than 140 bytes.
code:
[In] SMS encoding method. See Chapter 2.3.2.1 for details.
0 GSM-7 bit
1 UCS2

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_code_e
The SMS encoding method is defined as follows:
typedef enum
{
GSM = 0,
UCS2 = 1,
}ql_sms_code_e

• Parameter

Parameter : Description

• GSM GSM encoding
• UCS2
• UCS2 encoding, used when the sent message contains Chinese.

ql_sms_send_pdu
This function sends SMS messages in PDU format.

Prototype
ql_sms_errcode_e ql_sms_send_pdu(uint8_t nSim, char *pdu)

Parameter
nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
pdu:
[In] PDU message.

Return Value
See Chapter 2.3.1.1 for details.

ql_sms_read_msg
This function reads SMS messages in text or PDU format.

• Prototype

ql_sms_errcode_e ql_sms_read_msg(uint8_t nSim, uint8_t index, char *buf, uint16_t buf_len,
ql_sms_format_e format)

Parameter
nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
index:
[In] Index of SMS message.
buf:
[Out] An array pointer for receiving SMS message.
buf_len:
[In] The array length.
format:
[In] SMS message format. See Chapter 2.3.4.1 for details.
Return Value
See Chapter 2.3.1.1 for details.
ql_sms_format_e
The SMS message format is defined as follows:
typedef enum
{
PDU = 0,
TEXT = 1,
}ql_sms_format_e

Parameter

Parameter : Description

• PDU PDU format
• TEXT Text format

ql_sms_read_msg_list
This function reads the list of SMS messages.

• Prototype
• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
format:
[In] SMS message format. See Chapter 2.3.4.1 for details.

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_delete_msg
This function deletes SMS messages.

• Prototype

ql_sms_errcode_e ql_sms_delete_msg(uint8_t nSim, uint8_t index)

Parameter
nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
index:
[In] The index of the SMS messages to be deleted.

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_get_center_address
This function gets the SMS center number.

• Prototype
  ql_sms_errcode_e ql_sms_get_center_address(uint8_t nSim, char* address, uint8_t len)

• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
address:
[Out] An array pointer for receiving the SMS center number.
len:
[In] The array length.

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_set_center_address
This function sets the SMS center number. If there is no special requirement, it is not recommended to change the SMS center number

Prototype
ql_sms_errcode_e ql_sms_set_center_address(uint8_t nSim, char* address)

• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
address:
[In] SMS center number in string format. The prefix “+86” is required.

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_set_storage
This function sets the storage location of the SMS message.

• Prototype

ql_sms_errcode_e ql_sms_set_storage(uint8_t nSim, ql_sms_stor_e mem1, ql_sms_stor_e mem2,
ql_sms_stor_e mem3)

• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
mem1:
[In] The storage location for SMS messages that have been read and deleted. See Chapter 2.3.9.1 for details. mem2:
[In] The storage location for SMS messages to be written and sent. See Chapter 2.3.9.1 for details.
mem3:
[In] The preferred storage location for SMS messages that have been received. See Chapter 2.3.9.1 for details.

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_stor_e
The enumeration of SMS message storage location is defined as follows:
typedef enum
{
ME = 1,
SM = 2,
}ql_sms_stor_e

• Parameter

Parameter : Description

• ME Mobile equipment (ME)
• SM (U)SIM card

ql_sms_get_storage
This function gets the storage location of SMS message.

• Prototype

ql_sms_errcode_e ql_sms_get_storage(uint8_t nSim, ql_sms_mem_info_t *mem_info)

• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
mem_info:
[Out] The storage location of SMS message. See Chapter 2.3.10.1 for details.

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_mem_info_t
The structure of SMS message storage location is defined as follows:
typedef struct
{
ql_sms_stor_e mem1;
ql_sms_stor_e mem2;
ql_sms_stor_e mem3;
}ql_sms_mem_info_t

• Parameter

Type:  Parameter : Description

• ql_sms_stor_e mem1 The storage location for SMS messages that have been read and deleted. See Chapter 2.3.9.1 for details.
• ql_sms_stor_e mem2 The storage location for SMS messages to be written and sent. See Chapter 2.3.9.1 for details.
• ql_sms_stor_e mem3 The preferred storage location for SMS messages that have been received. See Chapter 2.3.9.1 for details

ql_sms_get_storage_info
This function gets the storage status of SMS message in the (U)SIM card and ME.

• Prototype

ql_sms_errcode_e ql_sms_get_storage_info(uint8_t nSim, ql_sms_stor_info_s *stor_info)

• Parameter

nSim:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
stor_info:
[Out] The structure of SMS message storage status. See Chapter 2.3.11.1 for details.

• Return Value

See Chapter 2.3.1.1 for details.

ql_sms_stor_info_s
The structure of SMS message storage status is defined as follows:
typedef struct
{
uint16_t usedSlotSM;
uint16_t totalSlotSM;
uint16_t unReadRecordsSM;
uint16_t usedSlotME;
uint16_t totalSlotME;
uint16_t unReadRecordsME;
ql_sms_stor_e newSmsStorId;
}ql_sms_stor_info_s

• Parameter

Type : Parameter : Description

• uint16_t usedSlotSM The number of SMS message stored in (U)SIM card (used storage memory)
• uint16_t totalSlotSM The total number of SMS message that can be stored in (U)SIM card
• uint16_t unReadRecordsSM The number of unread SMS message in (U)SIM card
• uint16_t usedSlotME The number of SMS message stored in ME (used storage memory)
• uint16_t totalSlotME The total number of SMS message that can be stored in ME
• uint16_t unReadRecordsME The number of unread SMS message in ME
• ql_sms_stor_e newSmsStorId The storage location of new SMS message. See Chapter 2.3.9.1 for details.

ql_sms_callback_register
This function registers the SMS message callback function.

Prototype
void ql_sms_callback_register(ql_sms_event_handler_t cb)

• Parameter

cb:
[In] Callback function. See Chapter 2.3.12.1 for details.

• Return Value

None

ql_sms_event_handler_t
This function defines the callback function for SMS message events.

• Prototype

typedef void (ql_sms_event_handler_t)(uint8_t sim_id, int event_id, void ctx)

• Parameter

sim_id:
[In] The (U)SIM card used. If the module only supports one (U)SIM interface, this parameter can only be
set to 0.
0 (U)SIM card 1
1 (U)SIM card 2
event_id:
[In] SMS message events. See Chapter 2.3.12.2 for details.
ctx:
[In] The pointer of inputting parameters for the callback function.

• Return Value

None

ql_sms_event_id_e
The enumeration of SMS message events is defined as follows:
typedef enum
{
QL_SMS_INIT_OK_IND = 1| (QL_COMPONENT_SMS << 16),
QL_SMS_NEW_MSG_IND,
QL_SMS_LIST_IND,
QL_SMS_LIST_END_IND,
QL_SMS_MEM_FULL_IND,
}ql_sms_event_id_e

Parameter

Parameter : Description

• QL_SMS_INIT_OK_IND Successfully initialization of SMS
• QL_SMS_NEW_MSG_IND New SMS message
• QL_SMS_LIST_IND List of SMS message
• QL_SMS_LIST_END_IND The list of SMS message has been read
• QL_SMS_MEM_FULL_IND The storage memory of SMS message is full

SMS Demo

This chapter mainly introduces how to use the above APIs to develop SMS functions on the Application side.

Demo Introduction
sms_demo.c, provided in the SDK of Quectel EC200U series QuecOpen module, is located in the directory of components\ql-application\sms. The demo contains some functions including sending, reading and deleting SMS messages. The following example shows how to use the API to send English and Chinese SMS messages.

include <stdio.h>

include <string.h>

include <stdlib.h>

include “ql_api_common.h”

include “ql_api_osi.h”

include “ql_api_sms.h”

include “ql_log.h”

ql_task_t sms_task = NULL;
ql_sem_t sms_init_sem = NULL;
void user_sms_event_callback(uint8_t nSim, int event_id, void ctx)
{
switch(event_id)
{
case QL_SMS_INIT_OK_IND:
{
QL_SMS_LOG(“QL_SMS_INIT_OK_IND”);
ql_rtos_semaphore_release(sms_init_sem);
break;
}
case QL_SMS_NEW_MSG_IND:
{
ql_sms_new_s msg = (ql_sms_new_s )ctx;
QL_SMS_LOG(“sim=%d, index=%d, storage memory=%d”, nSim, msg->index,
msg->mem);
break;
}
case QL_SMS_MEM_FULL_IND:
{
ql_sms_new_s msg = (ql_sms_new_s )ctx;
QL_SMS_LOG(“QL_SMS_MEM_FULL_IND sim=%d, memory=%d”,nSim,msg->mem);
break;
}
default :
break;
}
}
void sms_demo_task(void param)
{
uint8_t nSim = 0;
QL_SMS_LOG(“enter”);
ql_sms_callback_register(user_sms_event_callback);
//wait sms ok
if(ql_rtos_semaphore_wait(sms_init_sem, QL_WAIT_FOREVER)){
QL_SMS_LOG(“Waiting for SMS init timeout”);
}
//Send English text message
if(QL_SMS_SUCCESS == ql_sms_send_msg(nSim,”+86189xxxxxxxx”,”Hello,marvin”, GSM)){
QL_SMS_LOG(“send sms OK”);
}else{
QL_SMS_LOG(“send sms FAIL”);
}
//Send messages in Chinese and English. (Need use UTF8 encoding to open sms_demo.c for
chinese.)
if(QL_SMS_SUCCESS == ql_sms_send_msg(nSim,”+86189xxxxxxxx”,”hello,你好”, UCS2)){
QL_SMS_LOG(“send pdu sms OK”);
}else{
QL_SMS_LOG(“send pdu sms FAIL”);
}
ql_rtos_task_delete(NULL);
}
QlOSStatus ql_sms_app_init(void)
{
QlOSStatus err = QL_OSI_SUCCESS;
err = ql_rtos_task_create(&sms_task, 4096, APP_PRIORITY_NORMAL, “SMS_TASK”,
sms_demo_task, NULL, 2);
if(err != QL_OSI_SUCCESS)
{
QL_SMS_LOG(“sms_task created failed, ret = 0x%x”, err);
}
err = ql_rtos_semaphore_create(&sms_init_sem, 0);
if(err != QL_OSI_SUCCESS)
{
QL_SMS_LOG(“sms_init_sem created failed, ret = 0x%x”, err);
}
return err;
}

Demo Autorun
The Demo is not enabled by default in ql_init_demo_thread(). As shown in the figure below, uncomment the codes when you run a test. In addition, you need to change the target phone number of the ql_sms_send_msg() in the demo to the your own phone number.

Appendix References

Table 2: Related Document

Document Name

• Quectel_EC200U_Series_QuecOpen_CSDK_Quick_Start_Guide

Table 3: Terms and Abbreviations

Abbreviation : Description

• API Application Programming Interface
• App Application
• GSM Global System for Mobile Communications
• IoT Internet of Things
• LTE Long-Term Evolution
• ME Mobile Equipment
• PDU Packet Data Unit
• RTOS Real-Time Operating System
• SDK Software Development Kit
• (U)SIM (Universal) Subscriber Identity Module
• SMS Short Message Service
• UCS Universal Character Set
• UTF Unicode Transformation Format

EC200U_Series_QuecOpen_SMS_API_Reference_Manual

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>