MQTT-Client-Framework - MQTT Client Library Encyclopedia
MQTT-Client-Framework is a native Objective-C iOS library. It uses CFNetwork for networking and CoreData for persistence. It is a complete implementation of MQTT 3.1.1 and supports TLS. Three flavors of API are available: A simple blocking API, an elaborate low level callback based API as well as a session manager, which takes care of the iOS specific app life cycle.
Overview of MQTT-Client-Framework
| MQTT-Client-Framework | |
|---|---|
| Language | Objective-C |
| License | Eclipse Public License - v 1.0 |
| Website | https://github.com/ckrey/MQTT-Client-Framework |
| API Style | Asynchronous and Blocking |
When I started in 2013 developing the library based on the work of 2lemetry, there was no iOS MQTT client library existing, which met the criteria for the OwnTracks project, especially TLS support and protocol completeness. Today there are some Objective-C and Swift wrappers for libmosquitto and Swift native implementations available as open source. MQTT-Client-Framework is actively maintained and used in various projects. Contributions are welcome. It integrates well with Swift. The extensive test cases cover a huge percentage of MQTT 3.1.1 test cases for MQTT brokers.
Features Supported by MQTT-Client-Framework
| Feature | |
|---|---|
| MQTT 3.1 | Yes |
| MQTT 3.1.1 | Yes |
| LWT | Yes |
| SSL/TLS | Yes |
| Automatic Reconnect | Yes |
| Disk Persistence | Yes |
Advanced Features Supported by MQTT-Client-Framework
| Feature | |
|---|---|
| QoS 0 | Yes |
| QoS 1 | Yes |
| QoS 2 | Yes |
| Authentication | Yes |
| Throttling | Yes |
| Offline Message Buffering | Yes |
Usage
Installation of MQTT-Client-Framework
There are 3 options to use MQTT-Client-Framework:
Use CocoaPods
The simplest way is to add „MQTTClient“ to your Podfile and run „pod update“Include Framework
After cloning the repo from GitHub you may add the iOS framework included under…/MQTTClient/dist/MQTTClient.frameworkto your iOS project.Include Source
After cloning the repo from GitHub you may add the sources under…/MQTTClient/MQTTClientdirectly to your iOS project. Doxygen generated documentation is part of the repo under…/MQTTClient/dist/documentation/html
How to Connect the MQTT-Client-Framework to an MQTT Broker?
#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
[session connectToHost:@"192.168.0.1" port:1883 usingSSL:NO];Connect With MQTT 3.1 or MQTT 3.1.1
session.protocolLevel = 4;
[session connectToHost:@"192.168.0.1" port:1883 usingSSL:NO];protocolLevel specifies the protocol to be used. The value of the Protocol Level field for the version 3.1.1 of the protocol is 4. The value for the version 3.1 is 3.
Connect with LWT
session.willFlag = TRUE;
session.willTopic = @"example/status";
session.willMsg = [@"offline" dataUsingEncoding:NSUTF8StringEncoding];
session.willQoS = MQTTQosLevelExactlyOnce;
[session connectToHost:@"192.168.0.1" port:1883 usingSSL:NO];willFlag If the Will Flag is set to YES this indicates that a Will Message MUST be published by the Server when the Server detects that the Client is disconnected for any reason other than the Client flowing a DISCONNECT Packet.
willTopic If the Will Flag is set to YES, the Will Topic is a string, nil otherwise.
willMsg If the Will Flag is set to YES the Will Message must be specified, nil otherwise.
willQoS specifies the QoS level to be used when publishing the Will Message. If the Will Flag is set to NO, then the Will QoS MUST be set to 0. If the Will Flag is set to YES, the value of Will QoS can be 0 (0x00), 1 (0x01), or 2 (0x02).
Connect with Username/Password
session.userName = @"myname";
session.password = @"secret";
[session connectToHost:@"192.168.0.1" port:1883 usingSSL:NO];userName an NSString object containing the user’s name (or ID) for authentication. May be nil.
password an NSString object containing the user’s password. If userName is nil, password must be nil as well.
How to Publish an MQTT Message Using MQTT-Client-Framework?
[session publishData:[@"Sample Data" dataUsingEncoding:NSUTF8StringEncoding]
topic:@"example/data"
retain:NO
qos:MQTTQosLevelAtMostOnce];How to Publish a Retained Message?
[session publishData:[@"Sample Data" dataUsingEncoding:NSUTF8StringEncoding]
topic:@"example/data"
retain:YES
qos:MQTTQosLevelExactlyOnce];How to Subscribe to an MQTT Message Using MQTT-Client-Framework?
[session subscribeToTopic:@"example/#" atLevel:MQTTQosLevelExactlyOnce];How to Unsubscribe to an MQTT Message Using MQTT-Client-Framework?
[session unsubscribeTopic:@"example/#"];How to Disconnect to an MQTT Message Using MQTT-Client-Framework?
[session close];Using TLS / SSL While Using MQTT-Client-Framework
You may use iOS’ keyChain to validate server certificates:
[session connectToHost:@"192.168.0.1" port:8883 usingSSL:YES];Or you may use a custom security policy:
NSString* certificate = [[NSBundle bundleForClass:[MQTTSession class]] pathForResource:@"certificate" ofType:@"cer"];
session.securityPolicy = [MQTTSSLSecurityPolicy policyWithPinningMode:MQTTSSLPinningModeCertificate];
session.securityPolicy.pinnedCertificates = @[ [NSData dataWithContentsOfFile:certificate] ];
session.securityPolicy.allowInvalidCertificates = YES;
[session connectToHost:@"192.168.0.1" port:8883 usingSSL:YES];You may use client certificates:
NSString *path = [[NSBundle bundleForClass:[MQTTClientTests class]] pathForResource:parameters[@„client"] ofType:@"p12"];
session.certificates = [MQTTSession clientCertsFromP12:path passphrase:@„secret“];
[session connectToHost:@"192.168.0.1" port:8883 usingSSL:YES];Example Application of Using MQTT-Client-Framework
You can find a full iPhone application called MQTTChat in GitHub at https://github.com/ckrey/MQTTChat
MQTTChat implements a chat protocol over MQTT on an MQTT broker of your choice.
The application presents a tab view with 3 tabs to chat within the app or you may use the app on different devices. A separate MQTT session is used in each tab.
The app CONNECTs to the MQTT broker and sends a join message when the tab is first opened. The MQTT connection can be gracefully DISCONNECTed (after sending a leave message) and reCONNECTed on user request.
Simple text messages can be entered and sent and will be displayed on all other connected clients and tabs.
The app publishes the text messages as UTF8 encoded strings to the MQTT broker to the topic <base>/<devicename>-<tabnumber>, e.g. MQTTChat/iPhone Simulator-3. Messages are not retained. Each session subscribes to the topic <base>/#, e.g. MQTTChat/#. Both PUBLISH and SUBSCRIBE use QoS 2.
To run the app, you need Xcode 6 and CocoaPods. You may change the connect parameters for your MQTT broker by updating the mqtt.plist file.
Christoph Krey
Christoph Krey is a freelance network application specialist who designs and implements client/server solutions in corporate environments since 1983. After a career in IT Management, he began his focus on protocols, mobile devices, and distributed applications. Christoph Krey maintains the MQTT client framework and has created MQTTInspector and OwnTracks for iOS.
