wolfMQTT User Manual
Contents
1. 4 4 MqttClient_Publish Synopsis include lt wolfmatt maqtt_client h gt int MqttClient_Publish MattClient client MqttPublish publish Description Encodes and sends the MQTT Publish packet and waits for the Publish response if QoS gt 0 This is a blocking function that will wait for MqttNet read data If QoS level 1 then will wait for PUBLISH_ACK If QoS level 2 then will wait for PUBLISH_REC then send PUBLISH_REL and wait for PUBLISH_COMP Return Values See enum MaqttPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init publish Pointer to MqttPublish structure initialized with message data Note MaqttPublish and MqttMessage are same structure Example define TEST MESSAGE test NULL int rc 0 MgttPublish publish wordl6 packet_id 0 Publish Topic publish retain 0 publish gqos qos publish duplicate 0 publish topic_ name pubtopic publish packet id packet_id publish message byte TEST MESSAGE publish message len strlen TEST MESSAGE re MqttClient Publish amp client amp publish if rc MQTT CODE SUCCESS printf MQOTT Publish s d n MqttClient ReturnCodeToString rc rc See Also MattClient_Init MattClient_Subscribe 4 5 MqttClient_Subscribe Sy2. examples mattclient mattclient MQTT Client MQTT Net Init Success 0 MQTT Init Success 0 MQTT Socket Connect Success 0 MQTT Connect Success 0 MQTT Connect Ack Return Code 0 Session Present 0 MQTT Ping Success 0 MQTT Subscribe Success 0 Topic subtopic1 Qos 0 Return Code 0 Topic subtopic2 Qos 0 Return Code 0 MQTT Publish Topic pubtopic Success 0 MQTT Waiting for message 4CReceived SIGINT MQTT Unsubscribe Success 0 MQTT Disconnect Success 0 MQTT Socket Disconnect Success 0 MQTT Net Delnit Success 0 Chapter 4 Library Design Library header files are located in the wolfmatt directory Only the wolfmqtt mqtt_client h header is required to be included include lt wolfmgtt mgtt client h gt The library has three components 1 mqtt_client This is where the top level application interfaces for the MQTT client reside If the API performs a network write it will block on a network read if an acknowledgment is expected 2 mqtt_packet This is where all the packet encoding decoding is handled This contains the MQTT Packet structures for Connect MqttConnect Publish Message MqttPublish MqttMessage they are the same Subscribe MqttSubscribe Unsubscribe MqttUnsubscribe 3 mqtt_socket This is where the transport socket optionally wraps TLS and uses the MqttNet callbacks for the platform specific network handling This contains the MQTT Network st
3. Connect packet and waits for the Connect Acknowledgement packet This is a blocking function that will wait for MqttNet read data Return Values See MqttPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init connect Pointer to MqttConnect structure populated with connection options Example int rc 0 MgttClient client MgttConnect connect MqttMessage lwt_ msg Define connect parameters connect keep alive sec keep alive sec connect clean_ session clean _ session connect client_id client_id Last will and testament sent by broker to subscribers of topic when broker connection is lost memset amp lwt_msg 0 sizeof lwt_msg connect lwt msg amp lwt_msg connect enable lwt enable lwt if enable lwt lwt_msg qos qos lwt_msg retain 0 lwt_msg topic name lwttopic lwt_msg message byte DEFAULT CLIENT ID lwt_msg message len strlen DEFAULT CLIENT ID H Optional authentication connect username username connect password password Send Connect and wait for Connect Ack re MqttClient Connect amp client amp connect if rc MQTT_CODE SUCCESS T printf MQTT Connect s d n MqttClient ReturnCodeToString rc rc See Also MattClient_Init MattClient_Disconnect
4. Encodes and sends the MQTT Ping Request packet and waits for the Ping Response packet This is a blocking function that will wait for MqttNet read data Return Values See enum MaqttPacketResponseCodes in wolfmaqtt maqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init Example Send Ping int re MgttClient Ping amp client if rc MQTT CODE SUCCESS printf MQOTT Ping s d n MqttClient ReturnCodeToString rc rc See Also MattClient_Init 4 8 MqttClient_Disconnect Synopsis include lt wolfmatt maqtt_client h gt int MqttClient_Disconnect MattClient client Description Encodes and sends the MQTT Disconnect packet no response Return Values See enum MaqttPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init Example int re MqttClient Disconnect client if rc MOTT CODE SUCCESS printf MOTT Disconnect s sd n MqttClient ReturnCodeToString rc rc See Also MattClient_Init MattClient_Connect 4 9 MqttClient_WaitMessage Synopsis include lt wolfmatt maqtt_client h gt int MqttClient_WaitMessage MattClient client MaqttMessage message int timeout_ms Description Waits for Publish packets to arrive This
5. ReturnCodeToString rc re See Also MattClient_NetConnect 4 12 MqttClient_ReturnCodeToString Synopsis include lt wolfmatt maqtt_client h gt const char MattClient_ReturnCodeToString int return_code Description Performs lookup of a wolfMQTT API return value Return Values String representation of the return code Parameters return_code The return value from an API function Example printf Return s d n MgttClient ReturnCodeToString rc rc See Also None
6. is a blocking function that will wait for MattNet read data based on timeout_ms value provided Return Values See enum MaqttPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init message Pointer to MqttWMessage structure uninitialized is okay timeout_ms Milliseconds until read timeout Example define DEFAULT CMD TIMEOUT MS 1000 int rc 0 MgttMessage msg Read Loop while mStopRead 0 Try and read packet re MqttClient WaitMessage amp client amp msg DEFAULT CMD TIMEOUT MS if rc gt 0 Print incoming message printf MOTT Message Topic s Len u n msg topic_ name msg message len else if re MOTT CODE ERROR _ TIMEOUT There was an error printf MQTT Message Wait s d n MgttClient ReturnCodeToString rc rc break See Also MattClient_Init MqttClient_Publish 4 10 MqttClient_NetConnect Synopsis include lt wolfmatt maqtt_client h gt typedef int MqttTlsCb struct _MqttClient client int MqttClient_NetConnect MattClient client const char host word16 port int timeout_ms int use_tls MattTIlsCb cb Description Performs network connect with TLS if use_tls is non zero value Will perform the MattTlsCb callback if use_tls is non zero value Return Values See enum Maqt
7. L wolfMQTT git 2 2 Building on nix When building on Linux BSD OS X Solaris or other nix like systems use the autoconf system To build wolfMQTT you only need to run three commands autogen sh configure make You can append any number of build options to configure For a list of available build options please see Section 2 5 or run configure help from the command line to see a list of possible options to pass to the configure script To build wolfMQTT run make To install wolfMQTT run make install You may need superuser privileges to install in which case precede the command with sudo sudo make install To test the build run the testsuite program from the root wolfMQTT source directory examples mgttclient mgttclient If you want to build only the wolfMQTT library and not the additional items examples testsuite benchmark app etc you can run the following command from the wolfMQTT root directory make src libwolfmqtt la 2 3 Building on Windows Visual Studio 2015 The wolfmatt sIn solution is included for Visual Studio 2015 in the root directory of the install To test each build choose Build All from the Visual Studio menu and then run the mqattclient program To edit build options in the Visual Studio project select your desired project wolfmatt mqttclient and browse to the Properties panel For instructions on building the required wolfssl dll see https w
8. The protocol efficiently packs messages to keep the overhead very low The MQTT specification recommends TLS as a transport option to secure the protocol using port 8883 secure matt Constrained devices can benefit from using TLS session resumption to reduce the reconnection cost MQTT defines QoS levels 0 2 to specify the delivery integrity required 0 At most once delivery No acknowledgment 1 At least once delivery Sends acknowledgment PUBLISH_ACKk 2 Exactly once delivery Sends recevied PUBLISH REC gets back released PUBLISH_REL and then sends complete PUBLISH_COMP Highlights e A publish message payload can be up to 256MB 28 bits e Packet header remaining length is encoded using a scheme where the most significant bit 7 indicates an additional length byte e Packets which require a response must include a 16 bit packet Id This needs to be unique for any outstanding transactions Typically an incremented value e A client can provide a last will and testament upon connect which will be delivered when the broker sees the client has disconnected or network keep alive has expired e The packet types are CONNECT CONNECT _ACK PUBLISH PUBLISH_ACK PUBLISH_REC PUBLISH_REL PUBLISH_COMP SUBSCRIBE SUBSCRIBE_ACK UNSUBSCRIBE UNSUBSCRIBE_ACK PING_REQ PING_RESP and DISCONNECT e The connect packet contains the ASCII string MQTT to define the protocol name This can be useful for wireshark sniffing Mu
9. cture populated with network callbacks and context cb Pointer to MqttMsgCb callback function tx_buf Pointer to transmit buffer used during encoding tx_buf_len Maximum length of the transmit buffer rx_buf Pointer to receive buffer used during decoding rx_buf_len Maximum length of the receive buffer connect_timeout_ms Maximum command wait timeout in milliseconds Example define MAX BUFFER SIZE 1024 define DEFAULT CMD TIMEOUT MS 1000 static int mqttclient message cb MqttClient client MqttMessage msg byte msg new byte msg done if msg new Message new if msg done Message done return MQTT CODE SUCCESS Return negative to terminate publish processing int rc 0 MgttClient client MaqttNet net byte tx_ buf NULL rx_ buf NULL tx buf malloc MAX BUFFER SIZE rx buf malloc MAX BUFFER SIZE rc MgttClient Init amp client amp net mqttclient message cb tx buf MAX BUFFER SIZE rx buf MAX BUFFER SIZE DEFAULT CMD TIMEOUT MS if re MOTT CODE SUCCES printf MOTT Init s A d n MqttClient ReturnCodeToString rc rc See Also None 4 3 MqttClient_Connect Synopsis include lt wolfmatt maqtt_client h gt int MqttClient_Connect MattClient client MqttConnect connect Description Encodes and sends the MQTT
10. h maximum length and command timeout 4 Call MqttClient_NetConnect to connect to broker over network If use_tls gt is non zero value then it will perform a TLS connection The TLS callback MattTIsCb should be defined for WolfSSL certificate configuration 5 Call MqttClient_Connect passing pointer to MqttConnect structure to send MQTT connect command and wait for Connect Ack 6 Call MqttClient_Subscribe passing pointer to MqttSubscribe structure to send MQTT Subscribe command and wait for Subscribe Ack depending on QoS level 7 Call MqttClient_WaitWMessage passing pointer to MqttMessage to wait for incoming MQTT Publish message 3 1 Example An example MQTT client implementation is located in examples mattclient This example exercises all exposed API s and prints any incoming publish messages for subscription topics subtopic1 and subtopic2 Usage examples mattclient mattclient mattclient Help print this usage h lt host gt Host to connect to default iot eclipse org p lt num gt Port to connect on default Normal 1883 TLS 8883 t Enable TLS c lt file gt Use provided certificate file q lt num gt Qos Level 0 2 default 0 S Disable clean session connect flag k lt num gt Keep alive seconds default 60 i lt id gt Client Id default WolfMQTTClient Enable LWT Last Will and Testament u lt str gt Username w lt str gt Password Output
11. ing a big endian system 4 Try to build the library and let us know if you run into any problems If you need help contact us at info wolfss com 2 5 Cross Compiling Many users on embedded platforms cross compile for their environment The easiest way to cross compile the library is to use the configure system It will generate a Makefile which can then be used to build wolfMQTT When cross compiling you ll need to specify the host to configure such as configure host arm linux You may also need to specify the compiler linker etc that you want to use configure host arm linux CC arm linux gcc AR arm linux ar RANLIB arm linux After correctly configuring wolfMQTT for cross compilation you should be able to follow standard autoconf practices for building and installing the library make sudo make install If you have any additional tips or feedback about cross compiling wolfMQTT please let us know at info wolfssl com Chapter 3 Getting Started Here are the steps for creating your own implementation 1 Create network callback functions for Connect Read Write and Disconnect See examples mattnet c and examples mattnet h for reference implementation 2 Define the network callback functions and context in a MqttNet structure 3 Call MqttClient_Init passing in a MqttClient structure pointer MqttNet structure pointer MqttMsgCb function callback pointer TX RX buffers wit
12. ltiple topics can be subscribed or unsubscribed in the same packet request Each subscription topic must define a QoS level The QoS level is confirmed in the subscription acknowledgment A publish message can be sent or received by either the client or the broker Publish messages can be flagged for retention on the broker A QoS level 2 requires two round trips to complete the delivery exchange confirmation e Strings are UTF 8 encoded See http matt org documentation for additional MQTT documentation Chapter 2 Building wolfMQTT wolfMQTT was written with portability in mind and should generally be easy to build on most systems If you have difficulty building please don t hesitate to seek support through our support forums http www wolfssl com forums or contact us directly at support wolfssl com This chapter explains how to build wolfMQTT on Unix and Windows and provides guidance for building in a non standard environment You will find a getting started guide and example client in Chapter 3 When using the autoconf automake system to build wolfMQTT uses a single Makefile to build all parts and examples of the library which is both simpler and faster than using Makefiles recursively 2 1 Getting the Source Code The most recent version can be downloaded from the GitHub website here https github com wolfSSL wolfMQTT Either click the Download ZIP button or use the command git clone git github com wolfSS
13. nopsis include lt wolfmatt maqtt_client h gt int MqttClient_Subscribe MattClient client MqttSubscribe subscribe Description Encodes and sends the MQTT Subscribe packet and waits for the Subscribe Acknowledgement packet This is a blocking function that will wait for MqttNet read data Return Values See enum MaqttPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init subscribe Pointer to MqttSubscribe structure initialized with subscription topic list and desired QoS Example define TEST TOPIC COUNT 2 int rc 0 MaqttSubscribe subscribe MgttTopic topics TEST TOPIC COUNT topic wordl6 packet id 0 Build list of topics topics 0 topic filter subtopicl topics 0 qos qos topics 1 topic filter subtopic2 topics 1 qos qos Subscribe Topic subscribe packet_ id packet_id subscribe topic_ count TEST TOPIC COUNT subscribe topics topics re MqttClient Subscribe amp client amp subscribe if rc MQTT CODE SUCCESS for i 0 i lt subscribe topic_ count i topic amp subscribe topics i printf Topic s Qos Su Return Code u n topic gt topic filter topic gt qos topic gt return_code else printf MOTT Subscribe s d n MqttClient ReturnCodeToString rc rc See Als
14. o MattClient_Init MattClient_Unsubscribe 4 6 MqttClient_Unsubscribe Synopsis include lt wolfmatt maqtt_client h gt int MqttClient_Unsubscribe MattClient client MqttUnsubscribe unsubscribe Description Encodes and sends the MQTT Unsubscribe packet and waits for the Unsubscribe Acknowledgement packet This is a blocking function that will wait for MqttNet read data Return Values See enum MaqttPacketResponseCodes in wolfmaqtt maqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init unsubscribe Pointer to MqttUnsubscribe structure initialized with topic list Example define TEST TOPIC COUNT 2 int rc 0 MgttUnsubscribe unsubscribe MgttTopic topics TEST TOPIC COUNT topic wordl6 packet id 0 Build list of topics topics 0 topic_ filter subtopicl topics 1 topic filter subtopic2 Unsubscribe Topics unsubscribe packet id packet id unsubscribe topic_ count TEST TOPIC COUNT unsubscribe topics topics re MqttClient Unsubscribe amp client amp unsubscribe if rc MOTT CODE SUCCESS printf MOTT Unsubscribe s d n MqttClient ReturnCodeToString rc rc See Also MattClient_Init MattClient_Subscribe 4 7 MqttClient_Ping Synopsis include lt wolfmatt maqtt_client h gt int MqttClient_Ping MattClient client Description
15. ructure MqttNet for network callback and context Chapter 5 API Reference This describes the public application interfaces for the wolfMQTT library 4 1 MqttPacketResponseCodes enum These are the API response codes MQTT_CODE_SUCCESS 0 Success MQTT CODE _ERROR_BAD_ARG 1 Invalid argument provided MQTT CODE ERROR_OUT_OF_BUFFER 2 Rx or Tx buffer out of space MQTT_CODE_ERROR_MALFORMED_ DATA 3 Malformed packet remaining length MQTT_CODE_ERROR_PACKET_TYPE 4 Invalid packet type in header MQTT_CODE_ERROR_PACKET_ID 5 Packet Id mismatch MQTT_CODE_ERROR_TLS_CONNECT 6 TLS connect error MQTT_CODE_ERROR_TIMEOUT 7 Net read write connect timeout MQTT CODE_ERROR_NETWORK 8 Network error 4 2 MattClient_Init Synopsis include lt wolfmatt maqtt_client h gt typedef int MaqttMsgCb struct _MqttClient client MqttMessage message byte is_new byte is_done int MqttClient_Init MattClient client MattNet net MaqttMsgCb cb byte tx_buf int tx_buf_len byte rx_buf int rx_buf_len int cmd_timeout_ms Description Initializes the wolfSSL library for use Must be called once per application and before any other call to the library Return Values See MaqttPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS Success MQTT_CODE_ERROR_BAD_ARG Invalid argument provided Parameters client Pointer to MqttClient structure okay if not initialized net Pointer to MqttNet stru
16. tPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init host Address of the broker server port Optional custom port If zero will use defaults 1883 normal 8883 TLS use_tls If non zero value will connect with and use TLS for encryption of data cb A function callback for configuration of the SSL context certificate checking Example define DEFAULT CON TIMEOUT MS 5000 define DEFAULT MOTT HOST iot eclipse org wordl6 port 0 const char host DEFAULT MQTT HOST Connect to broker int rc MgttClient NetConnect client host port DEFAULT CON TIMEOUT MS use tls mqttclient tls ch if rc MQTT CODE SUCCESS printf MQOTT Net Connect s d n MqttClient ReturnCodeToString rc re See Also MattClient_NetDisconnect 4 11 MqttClient_NetDisconnect Synopsis include lt wolfmatt maqtt_client h gt int MqttClient_NetDisconnect MattClient client Description Performs a network disconnect Return Values See enum MaqttPacketResponseCodes in wolfmatt mqtt_types h MQTT_CODE_SUCCESS Success Parameters client Pointer to MqttClient structure already initialized using MqttClient_Init Example int re MqttClient NetDisconnect amp client if rc MOTT CODE SUCCESS printf MQTT Net Disconnect s d n MqttClient
17. wolfMQTT User Manual November 16 2015 Version 0 3 Table of Contents Chapter 1 Introduction 1 1 Chapter 2 2 1 2 2 2 3 2 4 2 5 Chapter 3 3 1 Chapter 4 Chapter 5 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 4 10 4 11 4 12 Protocol overview Building wolfSSL Getting the Source Code Building on nix Building on Windows Building in a Non Standard Environment Cross Compiling Getting Started Example Library Design API Reference MattPacketResponseCodes enum MattClient_Init MattClient_Connect MattClient_Publish MattClient_Subscribe MattClient_Unsubscribe MattClient_Ping MattClient_Disconnect MattClient_WaitMessage MattClient_NetConnect MattClient_NetDisconnect MattClient_ReturnCodeToString Chapter 1 Introduction This is an implementation of the MQTT Message Queuing Telemetry Transport Client written in C This library was built from the ground up to be multi platform space conscience and extensible It supports all Packet Types all Quality of Service QoS levels 0 2 and supports SSL TLS using the wolfSSL library This implementation is based on the MQTT v3 1 1 specification 1 1 Protocol Overview MQTT is a lightweight open messaging protocol that was developed for constrained environments such as M2M Machine to Machine and loT Internet of Things where a small code footprint is required MQTT is based on the Pub Sub messaging principle of publishing messages and subscribing to topics
18. ww wolfssl com wolfSSL Docs wolfssl visual studio html When done copy the wolfssl dll and wolfssl lib into the wolfMQTT root The project also assumes the wolfSSL headers are located wolfssl Cygwin If using Cygwin or other toolsets for Windows that provides nix like commands and functionality please follow the instructions in section 2 2 above for Building on nix If building wolfMQTT for Windows on a Windows development machine we recommend using the included Visual Studio project files to build wolfMQTT 2 4 Building in a non standard environment While not officially supported we try to help users wishing to build wolfMQTT in a non standard environment particularly with embedded and cross compilation systems Below are some notes on getting started with this 1 The source and header files need to remain in the same directory structure as they are in the wolfMQTT download package 2 Some build systems will want to explicitly know where the wolfMQTT header files are located so you may need to specify that They are located in the lt wolfmatt_root gt wolfmatt directory Typically you can add the lt wolfmqtt_root gt directory to your include path to resolve header problems 3 wolfMQTT defaults to a little endian system unless the configure process detects big endian Since users building in a non standard environment aren t using the configure process BIG_ENDIAN_ORDER will need to be defined if us
Download Pdf Manuals
Related Search