SIMCom_3G_MQTT_Application Note_V1.00

SIMCom_3G_MQTT_Application Note_V1.00

Document Title: SIMCom_3G_MQTT_Application Note Version: 1.00 Date: 2014-2-18 Status: Document Control ID: Prepare 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 customer s possession. Furthermore, system validation of this product designed by SIMCom within a larger electronic system remains the responsibility of the customer or the customer s 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 2 AT commands... 1 3 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 4 Result code... 7 5 Complete Examples...1 Appendix... 4 A Related Documents...4 B Terms and Abbreviations...4 SIMCom_3G_MQTT_Application Note _V1.00 2

Version History Date Version of change Author 2014-02-18 V1.00 New version 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. SIMCom_3G_MQTT_Application Note _V1.00 3

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 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 AT+CMQTTSTART AT+CMQTTSTOP AT+CMQTTACCQ AT+CMQTTREL AT+CMQTTWILLTOPIC AT+CMQTTWILLMSG AT+CMQTTRETRYTIMEOUT AT+CMQTTCONNECT AT+CMQTTDISC AT+CMQTTTOPIC AT+CMQTTPAYLOAD AT+CMQTTPUB AT+CMQTTSUBTOPIC AT+CMQTTSUB AT+CMQTTUNSUBTOPIC AT+CMQTTUNSUB Start network Close network Acquire a client resource Release the client resource Set will topic Set will message Set the value of retry timeout for connection Set up a connection to server Disconnecting for the client Set publishing topic Set publishing message Publish the configured topic Set one or more subscribe topic Subscribe the topic Set one or more unsubscribe topic 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 "" 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. AT+CSQ +CSQ: 31,99 Check CSQ AT+CREG? +CREG: 0,1 Check CREG state. AT+CPSI? +CPSI: GSM,Online,460-00 0x1816,63905,81 EGSM 900,-68,0,31-31 Check network information. AT+CGREG? +CGREG: 0,1 Check CGREG state. 3.2 Network open/close AT+CGSOCKCONT=1,"IP","CMNET" AT+CSOCKSETPN=1 AT+CMQTTSTART +CMQTTSTART: 0 Set APN. Note, usually CSOCKAUTH and CSOCKSETPN parameter are kept default if not care about. Open up the network library and start up the network subsystem(cdma data service and PPP) over the Um interface for all sockets.

AT+CMQTTSTOP +CMQTTSTOP: 0 Bring down PPP and Close the network library. All opened sockets must be closed before calling this command. 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 AT+CMQTTACCQ=0,"client c" +CMQTTACCQ: 0,0 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 CONNECT flow of the new client. 3.3.2 Set will topic and message Will topic and will message setting is optional. AT+CMQTTWILLTOPIC=0,10 >will topic AT+CMQTTWILLMSG=0,56,1 >you d better set will topic before setting will message. Set client index-0 will topic. The will topic should be UTF-encoded string. The range of length is [1, 1024] Set client index-0 will message. The will msg should be UTF-encoded 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 SIMCom_3G_MQTT_Application Note _V1.00 2

not set. AT+CMQTTRETRYTIMEOUT=0,60 This command is used to set the value of retry timeout for connection. 3.3.4 Send CONNECT message AT+CMQTTCONNECT=0,"tcp://116.247.119.165:514 1",20,1, username, password +CMQTTCONNECT: 0,0 You should ensure the server address <IP=116.247.119.165, port=5141> is reachable, and the MQTT server is running. 3.4 Publish topic to MQTT server After the client is connected with MQTT server, you could publish topic to MQTT server. AT+CMQTTTOPIC=0,13 >publish topic AT+CMQTTPAYLOAD=0,62 >you d better set publish topic before setting publish message. AT+CMQTTPUB=0,1,60 +CMQTTPUB: 0,0 The topic should be UTF-encoded string. The range of length is [1, 1024] The message should be UTF-encoded string. The range of length is [1, 10240] 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 doesn t respond to PUBLISH request, 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 to MQTT server. SIMCom_3G_MQTT_Application Note _V1.00 3

AT+CMQTTSUBTOPIC=0,9,1 >subscribe +CMQTTSUBTOPIC: 0,0 AT+CMQTTSUBTOPIC=0,10,1 >subscribe1 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+CMQTTSUB=0 +CMQTTSUB: 0,0 Subscribe topics subscribe and subscribe1 which be set by AT+CMQTTSUBTOPIC 1024 - The max input length of subscribe 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 will transmit these topic and message to user with URC. <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> Example: 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 SIMCom_3G_MQTT_Application Note _V1.00 4

+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. AT+CMQTTUNSUBTOPIC=0,11 >unsubscribe +CMQTTUNSUBTOPIC: 0,0 AT+CMQTTUNSUBTOPIC=0,12 >unsubscribe1 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. SIMCom_3G_MQTT_Application Note _V1.00 5

+CMQTTUNSUBTOPIC: 0,0 AT+CMQTTUNSUB=0 +CMQTTUNSUB: 0,0 Unsubscribe topics unsubscribe and unsubscribe1 which be set by AT+CMQTTUNSUBTOPIC 1024 - The max input length of unsubscribe message. 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 AT+CMQTTDISC=0,120 Disconnect client index-0 with MQTT server. Timeout is 120s for disconnection 3.8.2 Disconnect passively <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. AT+CMQTTREL=0 Release the resource of client index-0. SIMCom_3G_MQTT_Application Note _V1.00 6

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. SIMCom_3G_MQTT_Application Note _V1.00 7

5 Complete Examples Example: connect AT+CMQTTSTART +CMQTTSTART: 0 AT+CMQTTACCQ=0,"client c" AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1 +CMQTTCONNECT: 0,0 AT+CMQTTDISC=0 +CMQTTDISC: 0,0 AT+CMQTTREL=0 AT+CMQTTSTOP=0 +CMQTTSTOP: 0 Example: connect with will topic AT+CMQTTSTART +CMQTTSTART: 0 AT+CMQTTACCQ=0,"client c" AT+CMQTTWILLTOPIC=0,10 >will topic AT+CMQTTWILLMSG=0,56,1 >you d better set will topic before setting will message. AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1, username, password +CMQTTCONNECT: 0,0 AT+CMQTTDISC=0

+CMQTTDISC: 0,0 AT+CMQTTREL=0 AT+CMQTTSTOP=0 +CMQTTSTOP: 0 Example: publish topic AT+CMQTTSTART +CMQTTSTART: 0 AT+CMQTTACCQ=0,"client c" AT+CMQTTWILLTOPIC=0,10 >will topic AT+CMQTTWILLMSG=0,56,1 >you d better set will topic before setting will message. AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1, username, password +CMQTTCONNECT: 0,0 AT+CMQTTTOPIC=0,13 >publish topic AT+CMQTTPAYLOAD=0,62 >you d better set publish topic before setting publish message. AT+CMQTTPUB=0,1,60 +CMQTTPUB: 0,0 AT+CMQTTDISC=0 +CMQTTDISC: 0,0 AT+CMQTTREL=0 AT+CMQTTSTOP=0 SIMCom_3G_MQTT_Application Note _V1.00 2

+CMQTTSTOP: 0 Example: subscribe and unsubscribe AT+CMQTTSTART +CMQTTSTART: 0 AT+CMQTTACCQ=0,"client c" AT+CMQTTWILLTOPIC=0,10 >will topic AT+CMQTTWILLMSG=0,56,1 >you d better set will topic before setting will message. AT+CMQTTCONNECT=0,"tcp://116.247.119.165:5141",20,1, username, password +CMQTTCONNECT: 0,0 AT+CMQTTSUB=0,9,1 >subscribe +CMQTTSUB: 0,0 AT+CMQTTUNSUB=0,9 >subscribe +CMQTTUNSUB: 0,0 AT+CMQTTDISC=0 +CMQTTDISC: 0,0 AT+CMQTTREL=0 AT+CMQTTSTOP=0 +CMQTTSTOP: 0 SIMCom_3G_MQTT_Application Note _V1.00 3

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 and Abbreviations Abbreviation MQTT MQ Telemetry Transport SIMCom_3G_MQTT_Application Note _V1.00 4

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 SIMCom_3G_MQTT_Application Note _V1.00 5