SIMCom 3G MQTT Application Note V1.00

SIMCom_3G_MQTT_Application
Note_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 Notes
SIMCom offers this information as a service to its customers, to support application and
engineering efforts that use the products designed by SIMCom. The information provided is based
upon requirements specifically provided to SIMCom by the customers. SIMCom has not
undertaken any independent search for additional relevant information, including any information
that may be in the customers possession. Furthermore, system validation of this product designed
by SIMCom within a larger electronic system remains the responsibility of the customer or the
customers system integrator. All specifications supplied herein are subject to change.
Copyright
This document contains proprietary technical information which is the property of SIMCom
Limited., copying of this document and giving it to others and the using or communication of the
contents thereof, are forbidden without express authority. Offenders are liable to the payment of
damages. All rights reserved in the event of grant of a patent or the registration of a utility model
or design. All specification supplied herein are subject to change without notice at any time.
Copyright Shanghai SIMCom Wireless Solutions Ltd. 2013
Contents
1
Introduction............................................................................................................................... 1
1.1
Features........................................................................................................................... 1
AT commands............................................................................................................................ 1
Examples.................................................................................................................................... 1
3.1
Network Environment.....................................................................................................1
3.2
Network open/close.........................................................................................................1
3.3
Connect............................................................................................................................2
3.3.1
Acquire client resource....................................................................................... 2
3.3.2
Set will topic and message..................................................................................2
3.3.3
Set retry timer......................................................................................................2
3.3.4
Send CONNECT message.................................................................................. 3
3.4
Publish topic to MQTT server........................................................................................ 3
3.5
Subscribe topic................................................................................................................ 3
3.6
Receive topic published by MQTT server......................................................................4
3.7
Unsubscribe topic............................................................................................................5
3.8
Disconnect.......................................................................................................................6
3.8.1
Disconnect actively.............................................................................................6
3.8.2
Disconnect passively...........................................................................................6
3.9
Release client resource....................................................................................................6
Result code................................................................................................................................. 7
Complete Examples...................................................................................................................1
Appendix............................................................................................................................................ 4
A Related Documents.............................................................................................................4
B Terms and Abbreviations....................................................................................................4
SIMCom_3G_MQTT_Application Note _V1.00
2/3/2015
Version History
Date
Version
Description of change
2014-02-18
V1.00
New version
Author
SCOPE
This document describes how to use the MQTT function of SIM5320, SIM5310
and SIM5215/SIM5216 through AT commands.
Examples are also given for reference. This document can also be used for
SIM5320 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.
2/3/2015
1 Introduction
This document presents the AT command of MQTT operation for SIMCom 3G modules.
1.1 Features
1.
2.
3.
4.
Support multiple Client (max num=2) sending and receiving synchronously.

Support TCP MQTT clientnot support SSL MQTT client.
Not support server.
Base on MQTT V3.1.
2 AT commands
Below is the MQTT associated with AT commands, detailed information please refer to
document [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 recommended
steps.
Grammar
Description
AT+CSQ
+CSQ: 31,99
Check CSQ
OK
AT+CREG?
+CREG: 0,1
Check CREG state.
OK
AT+CPSI?
Check network information.
+CPSI: GSM,Online,460-00 0x1816,63905,81 EGSM
900,-68,0,31-31
OK
AT+CGREG?
+CGREG: 0,1
Check CGREG state.
OK
3.2 Network open/close

Grammar
Description
AT+CGSOCKCONT=1,"IP","CMNET"
OK
AT+CSOCKSETPN=1
OK
Set APN.
Note, usually CSOCKAUTH and
CSOCKSETPN parameter are kept
default if not care about.
AT+CMQTTSTART
OK
Open up the network library and start

up the network subsystem(CDMA
data service and PPP) over the Um
interface for all sockets.
+CMQTTSTART: 0
AT+CMQTTSTOP
+CMQTTSTOP: 0
Bring down PPP and Close the

network library. All opened sockets
must be closed before calling this
command.
OK
3.3 Connect
When network is opened, you would establish the connection from one client to server. You
need to acquire the client resource with command<AT+CMQTTACCQ> before
command<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
Acquire client index-0 resource.

Client c is the client ID, The Client
Identifier (Client ID) is between 1 and
23 characters long, and uniquely
identifies the client to the server.
If a client with the same Client ID is
already connected to the server, the
"older" client must be disconnected by
the server before completing the
+CMQTTACCQ: 0,0
CONNECT 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 topic
OK
Set client index-0 will topic.

The will topic should be UTF-encoded
string. The range of length is [1, 1024]
AT+CMQTTWILLMSG=0,56,1
Set client index-0 will message.
>youd better set will topic before setting will message. The will msg should be UTF-encoded
OK
string. 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
2/3/2015
not set.
Grammar
Description
AT+CMQTTRETRYTIMEOUT=0,60
OK
This command is used to set the value

of retry timeout for connection.
3.3.4
Send CONNECT message
Grammar
Description
AT+CMQTTCONNECT=0,"tcp://116.247.119.165:514 You should ensure the server address

1",20,1,username,password
<IP=116.247.119.165, port=5141> is
OK
reachable, and the MQTT server is
running.
+CMQTTCONNECT: 0,0
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 topic
OK
The topic should be UTF-encoded

string. The range of length is [1, 1024]
AT+CMQTTPAYLOAD=0,62
The message should be UTF-encoded
>youd better set publish topic before setting publish string. The range of length is [1,
message.
10240]
OK
AT+CMQTTPUB=0,1,60
OK
AT+CMQTTPUB=<client_index>,<q
os>,<publish_interval>
The publishing interval is used for
setting the timer when publish is
timeout. For example, the MQTT
server doesnt respond to PUBLISH
request, the publish timer is timeout,
the client will be disconnected.
+CMQTTPUB: 0,0
3.5 Subscribe topic

After the client is connected with MQTT server, you could subscribe one or more topic to
MQTT server.
Grammar
Description
3
2/3/2015
AT+CMQTTSUBTOPIC=0,9,1
>subscribe
OK
You would set this command

repeatedly for more than one
subscribing topic. Please set this
command before you set the
subscribing topic if you want to
subscribe more than one topic.
+CMQTTSUBTOPIC: 0,0
AT+CMQTTSUBTOPIC=0,10,1
>subscribe1
OK
+CMQTTSUBTOPIC: 0,0
AT+CMQTTSUB=0
OK
Subscribe
+CMQTTSUB: 0,0
1024 - The max input length of

subscribe message.
topics
subscribe
subscribe1
which
be
AT+CMQTTSUBTOPIC
set
and
by
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 will
transmit 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_pa
yload>
[<CR><LF>+CMQTTRXPAYLOAD:
<client_index>,<sub_payload_len><CR><LF><sub_pa
yload>]
<CR><LF>+CMQTTRXEND: <client_index>
1) +CMQTTRXSTART:
<client_index>,<topic_total_len>,<pa
yload_total_len>
At the beginning of receiving
published message, the module will
send this command to user, and
indicate client index with
<client_index>, the topic total length
with <topic_total_len> and the
payload total length with
<payload_total_len>.
2) +CMQTTRXTOPIC:
<client_index>,<sub_topic_len>\r\n<s
ub_topic>
After the command
+CMQTTRXSTART received, the
module will send second command to
user, and indicate client index with
<client_index>, the topic packet length
Example:
2/3/2015
+CMQTTRXSTART: 1, 13, 12
+CMQTTRXTOPIC: 1, 13
MQTT Examples
+CMQTTRXPAYLOAD: 1, 12
Hello World!
+CMQTTRXEND: 1
with <sub_topic_len> and the topic

content with <sub_topic> after \r\n.
For long topic, it will be split to
multiple packets to report and the
command +CMQTTRXTOPIC will
be send more than once with the rest
of 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, the
module will send third command to
user, and indicate client index with
<client_index>, the payload packet
length with <sub_payload_len> and
the 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 fourth
command to user and indicate the
topic and payload have been
transmitted completely.
3.7 Unsubscribe topic

After the client is connected with MQTT server, and one or more topic have been subscribed
to MQTT server, you could unsubscribe this/these topic.
Grammar
Description
AT+CMQTTUNSUBTOPIC=0,11
>unsubscribe
OK
You would set this command

repeatedly for more than one
unsubscribing topic. Please set this
command before you set the
unsubscribing topic if you want to
unsubscribe more than one topic.
+CMQTTUNSUBTOPIC: 0,0
AT+CMQTTUNSUBTOPIC=0,12
>unsubscribe1
OK
2/3/2015
+CMQTTUNSUBTOPIC: 0,0
AT+CMQTTUNSUB=0
OK
Unsubscribe topics unsubscribe and
+CMQTTUNSUB: 0,0
1024 - The max input length of

unsubscribe message.
unsubscribe1 which be
AT+CMQTTUNSUBTOPIC
set
by
3.8 Disconnect
You could send DISCONNECT message to MQTT server and the acquired client resource is
remained after the client is connected with MQTT server. You could send CONNECT message
again when you want to connect with MQTT server again.
When client disconnect passively, URC +CMQTTCONNLOST will be reported, then user
need to connect MQTT server again.
3.8.1
Disconnect actively
Grammar
Description
AT+CMQTTDISC=0,120
OK
Disconnect client index-0 with MQTT

server. Timeout
is
120s
for
disconnection
3.8.2
Disconnect passively
Grammar
Description
<CR><LF>+CMQTTCONNLOST:
<client_index>,<cause><CR><LF>
When client disconnect passively,

URC +CMQTTCONNLOST will be
reported, then user need to connect
MQTT server again. Please refer to
document [1]
3.9 Release client resource

You should release one client resource after sending DISCONNECT message to MQTT
server or the client is disconnected passively.
Grammar
Description
AT+CMQTTREL=0
OK
Release the resource of client index-0.
2/3/2015
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.
2/3/2015
Complete Examples
Example: connect
AT+CMQTTSTART
OK
+CMQTTSTART: 0
OK
AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1
OK
+CMQTTCONNECT: 0,0
AT+CMQTTDISC=0
OK
+CMQTTDISC: 0,0
AT+CMQTTREL=0
OK
AT+CMQTTSTOP=0
+CMQTTSTOP: 0
OK
Example: connect with will topic
AT+CMQTTSTART
OK
+CMQTTSTART: 0
OK
>will topic
OK
>youd better set will topic before setting will message.
OK
AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1,username,password
OK
+CMQTTCONNECT: 0,0
AT+CMQTTDISC=0
OK
+CMQTTDISC: 0,0
AT+CMQTTREL=0
OK
AT+CMQTTSTOP=0
+CMQTTSTOP: 0
OK
Example: publish topic
AT+CMQTTSTART
OK
+CMQTTSTART: 0
OK
>will topic
OK
OK
OK
+CMQTTCONNECT: 0,0
AT+CMQTTTOPIC=0,13
>publish topic
OK
AT+CMQTTPAYLOAD=0,62
>youd better set publish topic before setting publish message.
OK
AT+CMQTTPUB=0,1,60
OK
+CMQTTPUB: 0,0
AT+CMQTTDISC=0
OK
+CMQTTDISC: 0,0
AT+CMQTTREL=0
OK
AT+CMQTTSTOP=0
2/3/2015
+CMQTTSTOP: 0
OK
Example: subscribe and unsubscribe
AT+CMQTTSTART
OK
+CMQTTSTART: 0
OK
>will topic
OK
OK
OK
+CMQTTCONNECT: 0,0
AT+CMQTTSUB=0,9,1
>subscribe
OK
+CMQTTSUB: 0,0
AT+CMQTTUNSUB=0,9
>subscribe
OK
+CMQTTUNSUB: 0,0
AT+CMQTTDISC=0
OK
+CMQTTDISC: 0,0
AT+CMQTTREL=0
OK
AT+CMQTTSTOP=0
+CMQTTSTOP: 0
OK
2/3/2015
Appendix
A
Related Documents
SN
Document name
[1]
SIMCOM_SIM5320_ATC_EN_V1.31.doc
[2]
MQTT_V3.1_Protocol_Specific.pdf
Remark
Terms and Abbreviations
Abbreviation
Description
MQTT
MQ Telemetry Transport
2/3/2015
Contact us:
Shanghai SIMCom Wireless Solutions Co.,Ltd.
Address: Building A, SIM Technology Building, No. 633, Jinzhong Road, Shanghai,
P. R. China 200335
Tel: +86 21 3252 3300
Fax: +86 21 3252 2030
URL: www.sim.com/wm
2/3/2015

SIMCom 3G MQTT Application Note V1.00

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

SIMCom 3G MQTT Application Note V1.00

Caricato da

Copyright:

Formati disponibili

SIMCom_3G_MQTT_Application

Smart Machine Smart Decision

Document Control ID:

Smart Machine Smart Decision