· c 9 < 2 ? %;% l!$(! ( !" & ' $ %% c 9 < 2 ? % % l!$(! ( !" & ' $ %% e$ .$ & ! " ! & & ) " !$(! ( '

SIMCom_3G_MQTT_ApplicationNote_V1.00

Smart Machine Smart Decision

Document Title: SIMCom_3G_MQTT_Application Note

Version: 1.00

Date: 2014-2-18

Status: Prepare

Document Control ID: SIMCom_3G_MQTT_Application Note_V1.00

General NotesSIMCom offers this information as a service to its customers, to support application andengineering efforts that use the products designed by SIMCom. The information provided is basedupon requirements specifically provided to SIMCom by the customers. SIMCom has notundertaken any independent search for additional relevant information, including any informationthat may be in the customer’s possession. Furthermore, system validation of this product designedby SIMCom within a larger electronic system remains the responsibility of the customer or thecustomer’s system integrator. All specifications supplied herein are subject to change.

CopyrightThis document contains proprietary technical information which is the property of SIMComLimited., copying of this document and giving it to others and the using or communication of thecontents thereof, are forbidden without express authority. Offenders are liable to the payment ofdamages. All rights reserved in the event of grant of a patent or the registration of a utility modelor design. All specification supplied herein are subject to change without notice at any time.

Copyright © Shanghai SIMCom Wireless Solutions Ltd. 2013


SIMCom_3G_MQTT_Application Note _V1.00 2/3/20152

Contents

1 Introduction............................................................................................................................... 11.1 Features........................................................................................................................... 1

2 AT commands............................................................................................................................ 1

3 Examples.................................................................................................................................... 13.1 Network Environment.....................................................................................................13.2 Network open/close.........................................................................................................13.3 Connect............................................................................................................................2

3.3.1 Acquire client resource....................................................................................... 23.3.2 Set will topic and message..................................................................................23.3.3 Set retry timer......................................................................................................23.3.4 Send CONNECT message.................................................................................. 3

3.4 Publish topic to MQTT server........................................................................................ 33.5 Subscribe topic................................................................................................................33.6 Receive topic published by MQTT server......................................................................43.7 Unsubscribe topic............................................................................................................53.8 Disconnect.......................................................................................................................6

3.8.1 Disconnect actively.............................................................................................63.8.2 Disconnect passively...........................................................................................6

3.9 Release client resource....................................................................................................6

4 Result code................................................................................................................................. 7

5 Complete Examples...................................................................................................................1

Appendix............................................................................................................................................ 4A Related Documents.............................................................................................................4B Terms and Abbreviations....................................................................................................4



Version History

Date Version Description of change Author

2014-02-18 V1.00 New version

SCOPE

This document describes how to use the MQTT function of SIM5320, SIM5310and SIM5215/SIM5216 through AT commands.

Examples are also given for reference. This document can also be used forSIM5320 serial modules, like SIM5320, SIM5320JE and SIM5320AD.

The develop software refer to MQTT V3.1.This document is subject to change without notice at any time.


1 Introduction

This document presents the AT command of MQTT operation for SIMCom 3G modules.

1.1 Features

1. Support multiple Client (max num=2) sending and receiving synchronously.2. Support TCP MQTT client，not support SSL MQTT client.3. Not support server.4. Base on MQTT V3.1.


2 AT commands

Below is the MQTT associated with AT commands, detailed information please refer todocument [1].Through these AT commands can achieve the following functions.1) Open/close network for MQTT client.2) Disconnect/release a client.3) Publish one topic to server.4) Subscribe/unsubscribe one or more topic.

Command Description

AT+CMQTTSTART Start network

AT+CMQTTSTOP Close network

AT+CMQTTACCQ Acquire a client resource

AT+CMQTTREL Release the client resource

AT+CMQTTWILLTOPIC Set will topic

AT+CMQTTWILLMSG Set will message

AT+CMQTTRETRYTIMEOUT Set the value of retry timeout for connection

AT+CMQTTCONNECT Set up a connection to server

AT+CMQTTDISC Disconnecting for the client

AT+CMQTTTOPIC Set publishing topic

AT+CMQTTPAYLOAD Set publishing message

AT+CMQTTPUB Publish the configured topic

AT+CMQTTSUBTOPIC Set one or more subscribe topic

AT+CMQTTSUB Subscribe the topic

AT+CMQTTUNSUBTOPIC Set one or more unsubscribe topic

AT+CMQTTUNSUB Unsubscribe the topic


3 Examples

There are some examples to explain how to use these commands.Please ensure TCP layer communication is ok before you use these command.In the "Grammar" columns of following tables, input of AT commands are in black , module

return values are in blue.

3.1 Network Environment

MQTT application is based on GPRS/WCDMA network and TCP layer communication; so,ensure GPRS/WCDMA network is available before TCPIP setup. Following are the recommendedsteps.

Grammar Description

AT+CSQ+CSQ: 31,99

OK

Check CSQ

AT+CREG?+CREG: 0,1

OK

Check CREG state.

AT+CPSI?+CPSI: GSM,Online,460-00 0x1816,63905,81 EGSM900,-68,0,31-31

OK

Check network information.

AT+CGREG?+CGREG: 0,1

OK

Check CGREG state.

3.2 Network open/close

Grammar Description

AT+CGSOCKCONT=1,"IP","CMNET"OKAT+CSOCKSETPN=1OK

Set APN.Note, usually CSOCKAUTH andCSOCKSETPN parameter are keptdefault if not care about.

AT+CMQTTSTARTOK

+CMQTTSTART: 0

Open up the network library and startup the network subsystem(CDMAdata service and PPP) over the Uminterface for all sockets.



AT+CMQTTSTOP+CMQTTSTOP: 0

OK

Bring down PPP and Close thenetwork library. All opened socketsmust be closed before calling thiscommand.

3.3 Connect

When network is opened, you would establish the connection from one client to server. Youneed to acquire the client resource with command<AT+CMQTTACCQ> beforecommand<AT+CMQTTCONNCT> is set. Will topic and will message setting is optional.

3.3.1 Acquire client resource

Grammar Description

AT+CMQTTACCQ=0,"client c"OK

+CMQTTACCQ: 0,0

Acquire client index-0 resource.“Client c” is the client ID, The ClientIdentifier (Client ID) is between 1 and23 characters long, and uniquelyidentifies the client to the server.If a client with the same Client ID isalready connected to the server, the"older" client must be disconnected bythe server before completing theCONNECT flow of the new client.

3.3.2 Set will topic and message

Will topic and will message setting is optional.

Grammar Description

AT+CMQTTWILLTOPIC=0,10>will topicOK

Set client index-0 will topic.The will topic should be UTF-encodedstring. The range of length is [1, 1024]

AT+CMQTTWILLMSG=0,56,1>you’d better set will topic before setting will message.OK

Set client index-0 will message.The will msg should be UTF-encodedstring. The range of length is [1,10240]

3.3.3 Set retry timer

This command is optional. The client will not retry to connect server when this command is



not set.

Grammar Description

AT+CMQTTRETRYTIMEOUT=0,60OK

This command is used to set the valueof retry timeout for connection.

3.3.4 Send CONNECT message

Grammar Description

AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1,”username”,”password”OK

+CMQTTCONNECT: 0,0

You should ensure the server address<IP=116.247.119.165, port=5141> isreachable, and the MQTT server isrunning.

3.4 Publish topic to MQTT server

After the client is connected with MQTT server, you could publish topic to MQTT server.

Grammar Description

AT+CMQTTTOPIC=0,13>publish topicOK

The topic should be UTF-encodedstring. The range of length is [1, 1024]

AT+CMQTTPAYLOAD=0,62>you’d better set publish topic before setting publishmessage.OK

The message should be UTF-encodedstring. The range of length is [1,10240]

AT+CMQTTPUB=0,1,60OK

+CMQTTPUB: 0,0

AT+CMQTTPUB=<client_index>,<qos>,<publish_interval>The publishing interval is used forsetting the timer when publish istimeout. For example, the MQTTserver doesn’t respond to PUBLISHrequest, the publish timer is timeout,the client will be disconnected.

3.5 Subscribe topic

After the client is connected with MQTT server, you could subscribe one or more topic toMQTT server.

Grammar Description



AT+CMQTTSUBTOPIC=0,9,1>subscribeOK

+CMQTTSUBTOPIC: 0,0

AT+CMQTTSUBTOPIC=0,10,1>subscribe1OK

+CMQTTSUBTOPIC: 0,0

You would set this commandrepeatedly for more than onesubscribing topic. Please set thiscommand before you set thesubscribing topic if you want tosubscribe more than one topic.

AT+CMQTTSUB=0OK

+CMQTTSUB: 0,0

Subscribe topics subscribe andsubscribe1 which be set byAT+CMQTTSUBTOPIC1024 - The max input length ofsubscribe message.

3.6 Receive topic published by MQTT server

After the client is connected with MQTT server, the client subscribes to one or more topics,any message published to those topics will be sent by the server to the client and client willtransmit these topic and message to user with URC.

Grammar Description

<CR><LF>+CMQTTRXSTART:<client_index>,<topic_total_len>,<payload_total_len><CR><LF><CR><LF>+CMQTTRXTOPIC:<client_index>,<sub_topic_len><CR><LF><sub_topic>[<CR><LF>+CMQTTRXTOPIC:<client_index>,<sub_topic_len><CR><LF><sub_topic>]<CR><LF>+CMQTTRXPAYLOAD:<client_index>,<sub_payload_len><CR><LF><sub_payload>[<CR><LF>+CMQTTRXPAYLOAD:<client_index>,<sub_payload_len><CR><LF><sub_payload>]<CR><LF>+CMQTTRXEND: <client_index>

Example:

1) +CMQTTRXSTART:<client_index>,<topic_total_len>,<payload_total_len>

At the beginning of receivingpublished message, the module willsend this command to user, andindicate client index with<client_index>, the topic total lengthwith <topic_total_len> and thepayload total length with<payload_total_len>.

2) +CMQTTRXTOPIC:<client_index>,<sub_topic_len>\r\n<sub_topic>

After the command“+CMQTTRXSTART” received, themodule will send second command touser, and indicate client index with<client_index>, the topic packet length



+CMQTTRXSTART: 1, 13, 12+CMQTTRXTOPIC: 1, 13MQTT Examples+CMQTTRXPAYLOAD: 1, 12Hello World!+CMQTTRXEND: 1

with <sub_topic_len> and the topiccontent with <sub_topic> after “\r\n”.

For long topic, it will be split tomultiple packets to report and thecommand “+CMQTTRXTOPIC” willbe send more than once with the restof topic content. The sum of<sub_topic_len> is equal to<topic_total_len>.

3) +CMQTTRXPAYLOAD:<client_index>,<sub_payload_len>\r\n<sub_payload>

After the command“+CMQTTRXTOPIC” received, themodule will send third command touser, and indicate client index with<client_index>, the payload packetlength with <sub_payload_len> andthe payload content with<sub_payload> after “\r\n”.

For long payload, the same as“+CMQTTRXTOPIC”.

4) +CMQTTRXEND:<client_index>

At last, the module will send fourthcommand to user and indicate thetopic and payload have beentransmitted completely.

3.7 Unsubscribe topic

After the client is connected with MQTT server, and one or more topic have been subscribedto MQTT server, you could unsubscribe this/these topic.

Grammar Description

AT+CMQTTUNSUBTOPIC=0,11>unsubscribeOK

+CMQTTUNSUBTOPIC: 0,0AT+CMQTTUNSUBTOPIC=0,12>unsubscribe1OK

You would set this commandrepeatedly for more than oneunsubscribing topic. Please set thiscommand before you set theunsubscribing topic if you want tounsubscribe more than one topic.



+CMQTTUNSUBTOPIC: 0,0

AT+CMQTTUNSUB=0OK

+CMQTTUNSUB: 0,0

Unsubscribe topics unsubscribe andunsubscribe1 which be set byAT+CMQTTUNSUBTOPIC1024 - The max input length ofunsubscribe message.

3.8 Disconnect

You could send DISCONNECT message to MQTT server and the acquired client resource isremained after the client is connected with MQTT server. You could send CONNECT messageagain when you want to connect with MQTT server again.

When client disconnect passively, URC “+CMQTTCONNLOST” will be reported, then userneed to connect MQTT server again.

3.8.1 Disconnect actively

Grammar Description

AT+CMQTTDISC=0,120OK

Disconnect client index-0 with MQTTserver. Timeout is 120s fordisconnection

3.8.2 Disconnect passively

Grammar Description

<CR><LF>+CMQTTCONNLOST:<client_index>,<cause><CR><LF>

When client disconnect passively,URC “+CMQTTCONNLOST” will bereported, then user need to connectMQTT server again. Please refer todocument [1]

3.9 Release client resource

You should release one client resource after sending DISCONNECT message to MQTTserver or the client is disconnected passively.

Grammar Description

AT+CMQTTREL=0OK

Release the resource of client index-0.



4 Result code

<result>The result of cmd.0 – net open successful.1 – failed.2 – bad UTF-8 string.3 – sock connect fail.4 – sock create fail.5 – sock close fail.6 – message receive fail.7 – network open fail.8 – network close fail.9 – network not opened.10 – client index error.11 – no connection.12 – invalid parameter.13 – not supported operation.14 – client is busy.15 – require connection fail.16 – sock sending fail.17 – timeout.18 – topic is empty.


5 Complete Examples

Example: connectAT+CMQTTSTARTOK

+CMQTTSTART: 0AT+CMQTTACCQ=0,"client c"OK

AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1OK

+CMQTTCONNECT: 0,0AT+CMQTTDISC=0OK

+CMQTTDISC: 0,0AT+CMQTTREL=0OKAT+CMQTTSTOP=0+CMQTTSTOP: 0

OKExample: connect with will topicAT+CMQTTSTARTOK

+CMQTTSTART: 0AT+CMQTTACCQ=0,"client c"OKAT+CMQTTWILLTOPIC=0,10>will topicOKAT+CMQTTWILLMSG=0,56,1>you’d better set will topic before setting will message.OKAT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1,”username”,”password”OK

+CMQTTCONNECT: 0,0AT+CMQTTDISC=0



OK


OKExample: publish topicAT+CMQTTSTARTOK


+CMQTTCONNECT: 0,0AT+CMQTTTOPIC=0,13>publish topicOKAT+CMQTTPAYLOAD=0,62>you’d better set publish topic before setting publish message.OKAT+CMQTTPUB=0,1,60OK

+CMQTTPUB: 0,0AT+CMQTTDISC=0OK

+CMQTTDISC: 0,0AT+CMQTTREL=0OKAT+CMQTTSTOP=0



+CMQTTSTOP: 0

OKExample: subscribe and unsubscribeAT+CMQTTSTARTOK


+CMQTTCONNECT: 0,0AT+CMQTTSUB=0,9,1>subscribeOK

+CMQTTSUB: 0,0AT+CMQTTUNSUB=0,9>subscribeOK

+CMQTTUNSUB: 0,0AT+CMQTTDISC=0OK


OK



Appendix

A Related Documents

SN Document name Remark

[1] SIMCOM_SIM5320_ATC_EN_V1.31.doc

[2] MQTT_V3.1_Protocol_Specific.pdf

B Terms andAbbreviations

Abbreviation Description

MQTT MQ Telemetry Transport



Contact us:Shanghai SIMComWireless Solutions Co.,Ltd.Address: Building A, SIM Technology Building, No. 633, Jinzhong Road, Shanghai,P. R. China 200335Tel: +86 21 3252 3300Fax: +86 21 3252 2030URL: www.sim.com/wm

http://www.sim.com/wm