· c 9 < 2 ? %;% l!$(! ( !" & ' $ %% c 9 < 2 ? % % l!$(! ( !" & ' $ %% e$ .$ & ! " ! & & ) " !$(! ( '
Post on 12-Jul-2018
256 Views
Preview:
Transcript
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
Smart Machine Smart Decision
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
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20153
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.
Smart Machine Smart Decision
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.
Smart Machine Smart Decision
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
Smart Machine Smart Decision
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.
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20152
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
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20153
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
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20154
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
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20155
+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.
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20156
+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.
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20157
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.
Smart Machine Smart Decision
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
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20152
OK
+CMQTTDISC: 0,0AT+CMQTTREL=0OKAT+CMQTTSTOP=0+CMQTTSTOP: 0
OKExample: publish 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+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
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20153
+CMQTTSTOP: 0
OKExample: subscribe and unsubscribeAT+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+CMQTTSUB=0,9,1>subscribeOK
+CMQTTSUB: 0,0AT+CMQTTUNSUB=0,9>subscribeOK
+CMQTTUNSUB: 0,0AT+CMQTTDISC=0OK
+CMQTTDISC: 0,0AT+CMQTTREL=0OKAT+CMQTTSTOP=0+CMQTTSTOP: 0
OK
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20154
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
Smart Machine Smart Decision
SIMCom_3G_MQTT_Application Note _V1.00 2/3/20155
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
top related