MQTT Class
Properties Methods Events Configuration Settings Errors
A lightweight, fully-featured MQTT client implementation.
Syntax
class ipworksiot.MQTT
Remarks
The MQTT class provides a lightweight, fully-featured MQTT client implementation with support for versions 3.1.1 and 5.0. The class supports plaintext and TLS-enabled connections over both standard TCP and WebSockets.
Connecting
Connecting to an MQTT server is easy; in the simplest case, set the client_id property and call the connect method, passing it the server's hostname and port number.When connecting to an MQTT server, the class sends the following information:
- The values of the client_id, clean_session, and keep_alive_interval properties.
- The value of the user property (if non-empty).
- The value of the password property (if non-empty).
- The values of the will_topic and will_message properties and the WillQOS and WillRetain configuration settings.
- MQTT 5 specific values from ClientTopicAliasMax, SessionExpInterval, ConnectProperties and WillProperties.
If clean_session is True, check the SessionPresent configuration setting once connected to determine whether the server actually had any session state saved.
Refer to clean_session, save_session, and restore_session for more information about MQTT sessions and session state persistence; refer to will_topic, will_message, WillQOS, and WillRetain for more information about MQTT Wills.
Basic Connection Example
mqtt1.ClientId = "testClient";
mqtt1.CleanSession = true;
mqtt1.KeepAliveInterval = 30;
mqtt1.WillTopic = "wills/" + mqtt1.ClientId;
mqtt1.WillMessage = mqtt1.ClientId + " was disconnected ungracefully!";
mqtt1.Connect("mqtt.test-server.com", 1883);
Topic Subscriptions
The subscribe and unsubscribe methods are used to subscribe to and unsubscribe from topics.When subscribing, pass one or more topic filters and QoS levels to indicate the topics to subscribe to and the desired QoS level(s). Topic filters may contain wildcards in order to match multiple topics on the server.
Subscribe Examples
// Subscribed event handler.
mqtt1.OnSubscribed += (s, e) => {
if (e.ResponseCode <= 2)
Console.WriteLine("Subscribed to " + e.TopicFilter + " at QoS " + e.QOS + ".");
else
Console.WriteLine("Failed to subscribe to " + e.TopicFilter + ".");
};
// Basic, subscribe to some topic filters, all at the same QoS level.
mqtt1.Subscribe("home,home/floor1/+/temperature,home/floor2/#", 2);
// A bit more advanced, subscribe to the same topic filters, but at different QoS levels.
mqtt1.Config("TopicQOSArray=1,2,2");
// The 0 is ignored here since we've specified individual QoS values explicitly.
mqtt1.Subscribe("home,home/floor1/+/temperature,home/floor2/#", 0);
After subscribing to topics, any messages received will cause the on_message_in, and potentially also the on_message_ack, events to fire. Refer to those events for more information about processing steps for inbound messages.
When unsubscribing, pass the exact same topic filter that was used to subscribe.
Unsubscribe Example
// Unsubscribe from topic filters; have to use the exact same strings as before. If this
// was to be called after calling the code example shown for the Subscribe() method, we
// would still be subscribed to the "home" topic filter.
mqtt1.Unsubscribe("home/floor1/+/temperature,home/floor2/#");
Refer to subscribe and unsubscribe for more information about subscriptions and topic filters.
Publishing Messages
To publish messages to topics, use the publish_message and publish_data methods.publish_message is used to publish a message with a string payload, while publish_data is used to publish a message with a raw data payload. Both also accept the name of a topic to publish to, and a QoS level at which to publish.
Publish Examples
// Publish a simple string-based message.
mqtt1.PublishMessage("/home/floor1/security/camera2", 1, "Cat detected!");
// Publish a raw data message.
byte[] catPicture = ...;
mqtt1.PublishData("/home/floor1/security/camera2", 1, catPicture);
Refer to publish_data and publish_message for more information about message publishing and processing steps for outbound messages, as well as topic naming.
MQTT 5 Notes
MQTT 5 is similar to v3.1.1, with a few changes and several new features. Major differences include:
- The Clean Session flag functionality is divided into two properties to allow for finer control over session state data: the Clean Start flag (see clean_session) and the new SessionExpInterval.
- All response packets (CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT) now contain a reason code describing why operations succeeded or failed. See on_message_ack, on_subscribed, on_unsubscribed, and DisconnectReasonCode for details.
- The Request / Response pattern is formalized by the addition of the ResponseTopic. Additional properties such as correlation data and be specified via OutgoingMessageProperties and ConnectProperties.
- New subscription features: Shared Subscriptions, Subscription Options, and SubscriptionIdentifier (see subscribe for details).
- Topic Aliases can be sent by both client and server to refer to topic filters by shorter numerical identifiers in order to save bandwidth (see TopicAlias, ServerTopicAliasMax and ClientTopicAliasMax).
- Servers can communicate what features it supports in ConnAckProperties.
- More: message expiration (OutgoingMessageProperties), Receive Maximums and Maximum Packet Sizes (ConnectProperties and ConnAckProperties), and a Will Delay interval (WillProperties) are all supported.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
| clean_session | Determines whether a clean session is used once connected. |
| client_id | A string that uniquely identifies this instance of the class to the server. |
| connected | Triggers a connection or disconnection. |
| firewall_auto_detect | This property tells the class whether or not to automatically detect and use firewall system settings, if available. |
| firewall_type | This property determines the type of firewall to connect through. |
| firewall_host | This property contains the name or IP address of firewall (optional). |
| firewall_password | This property contains a password if authentication is to be used when connecting through the firewall. |
| firewall_port | This property contains the TCP port for the firewall Host . |
| firewall_user | This property contains a user name if authentication is to be used connecting through a firewall. |
| incoming_message_count | The number of records in the IncomingMessage arrays. |
| incoming_message_content_type | String describing the content of the message. |
| incoming_message_correlation_data | Used by the sender of the request message to identify which request the response message is for when it is received. |
| incoming_message_duplicate | Whether or not this message's Duplicate flag is set. |
| incoming_message_message | This message's raw data payload. |
| incoming_message_message_exp_interval | The lifetime of the message in seconds specified by the sender. |
| incoming_message_packet_id | This message's packet Id. |
| incoming_message_payload_format_indicator | Indicates whether the payload is unspecified bytes or UTF-8 Encoded character data. |
| incoming_message_qos | This message's QoS level. |
| incoming_message_response_topic | String used as the topic name for a response message. |
| incoming_message_retained | Whether or not this message's Retain flag is set. |
| incoming_message_state | This message's current state. |
| incoming_message_subscription_identifiers | A comma separated list of any SubscriptionIdentifiers associated with any client subscription(s) that caused this message to be delivered. |
| incoming_message_topic | This message's topic. |
| incoming_message_topic_alias | An integer used to identify the topic instead of the full topic filter in order to reduce the size of the publish packet. |
| keep_alive_interval | The maximum period of inactivity the class will allow before sending a keep-alive packet. |
| local_host | The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
| local_port | The TCP port in the local host where the class binds. |
| outgoing_message_count | The number of records in the OutgoingMessage arrays. |
| outgoing_message_content_type | String describing the content of the message. |
| outgoing_message_correlation_data | Used by the sender of the request message to identify which request the response message is for when it is received. |
| outgoing_message_duplicate | Whether or not this message's Duplicate flag is set. |
| outgoing_message_message | This message's raw data payload. |
| outgoing_message_message_exp_interval | The lifetime of the message in seconds specified by the sender. |
| outgoing_message_packet_id | This message's packet Id. |
| outgoing_message_payload_format_indicator | Indicates whether the payload is unspecified bytes or UTF-8 Encoded character data. |
| outgoing_message_qos | This message's QoS level. |
| outgoing_message_response_topic | String used as the topic name for a response message. |
| outgoing_message_retained | Whether or not this message's Retain flag is set. |
| outgoing_message_state | This message's current state. |
| outgoing_message_subscription_identifiers | A comma separated list of any SubscriptionIdentifiers associated with any client subscription(s) that caused this message to be delivered. |
| outgoing_message_topic | This message's topic. |
| outgoing_message_topic_alias | An integer used to identify the topic instead of the full topic filter in order to reduce the size of the publish packet. |
| password | A password if authentication is to be used. |
| ready_to_send | Indicates whether the class is ready to send data. |
| remote_host | The address of the remote host. Domain names are resolved to IP addresses. |
| remote_port | The port of the MQTT server (default is 1883). The default port for SSL is 8883. |
| ssl_accept_server_cert_encoded | The certificate (PEM/base64 encoded). |
| ssl_cert_encoded | The certificate (PEM/base64 encoded). |
| ssl_cert_store | The name of the certificate store for the client certificate. |
| ssl_cert_store_password | If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store. |
| ssl_cert_store_type | The type of certificate store for this certificate. |
| ssl_cert_subject | The subject of the certificate used for client authentication. |
| ssl_enabled | Whether TLS/SSL is enabled. |
| ssl_server_cert_encoded | The certificate (PEM/base64 encoded). |
| timeout | A timeout for the class. |
| user | A username if authentication is to be used. |
| version | The MQTT protocol version that the class will conform to. |
| will_message | The message that the server should publish in the event of an ungraceful disconnection. |
| will_topic | The topic that the server should publish the WillMessage to in the event of an ungraceful disconnection. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
| config | Sets or retrieves a configuration setting. |
| connect | Connects to the remote host. |
| disconnect | Disconnects from the remote host. |
| do_events | Processes events from the internal message queue. |
| interrupt | Interrupt the current action and disconnects from the remote host. |
| publish_data | Publishes a message with a raw data payload. |
| publish_message | Publishes a message with a string payload. |
| reset | Reset the class. |
| restore_session | Restores session state data. |
| save_session | Saves session state data. |
| subscribe | Subscribes the class to one or more topic filters. |
| unsubscribe | Unsubscribes the class from one or more topic filters. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
| on_connected | Fired immediately after a connection completes (or fails). |
| on_connection_status | Fired to indicate changes in connection state. |
| on_disconnected | Fired when a connection is closed. |
| on_error | Information about errors during data delivery. |
| on_log | Fires once for each log message. |
| on_message_ack | Fired when an incoming or outgoing message has completed all acknowledgment steps. |
| on_message_in | Fired when an incoming message has been received and/or fully acknowledged. |
| on_message_out | Fired when an outgoing message has been sent and/or fully acknowledged. |
| on_ready_to_send | Fired when the class is ready to send data. |
| on_ssl_server_authentication | Fired after the server presents its certificate to the client. |
| on_ssl_status | Shows the progress of the secure connection. |
| on_subscribed | Fires for each topic filter subscription the server acknowledges. |
| on_unsubscribed | Fires when the server has acknowledged an unsubscribe request. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
| AutoReconnect | Whether to automatically attempt to reconnect in the event of a connection error. |
| ClientTopicAliasMax | The maximum value the client will accept for a topic alias sent by the server. |
| ConnAckProperties | JSON string containing the properties returned in the CONNACK packet. |
| ConnectionTimeout | How long to wait for a connection attempt to succeed. |
| ConnectProperties | JSON string specifying properties to be included in the CONNECT packet. |
| DisconnectProperties | JSON string containing DISCONNECT packet properties. |
| DisconnectReasonCode | Code describing the reason the client or server closed the connection. |
| Duplicate | Whether to set the Duplicate flag when publishing a message. |
| IncomingUserPropCount | The size of the IncomingUserPropName and IncomingUserPropValue arrays. |
| IncomingUserPropName[i] | The name of the user property at index i. |
| IncomingUserPropValue[i] | The value of the user property at index i. |
| LogLevel | The level of detail that is logged. |
| OutgoingMessageProperties | JSON string specifying properties to be included in the PUBLISH packet. |
| OutgoingPacketId | The packet Id of the last message published. |
| OutgoingUserPropCount | Controls the size of the OutgoingUserPropName and OutgoingUserPropValue configuration arrays. |
| OutgoingUserPropName[i] | The name of the User Property at index i. |
| OutgoingUserPropValue[i] | The value of the User Property at index i. |
| RepublishInterval | How many seconds to wait before republishing unacknowledged messages. |
| ResponseTopic | Topic name for a response message. |
| Retain | Whether to set the Retain flag when publishing a message. |
| SendCustomPacket | Sends a packet constructed using the supplied hex byte string. |
| ServerTopicAliasMax | The highest value that the Server will accept as a Topic Alias sent by the Client. |
| SessionExpInterval | The length of time in seconds the client and server should store session state data after the connection is closed. |
| SessionPresent | When connecting with CleanSession disabled, indicates whether the server actually had any previous session data stored. |
| SessionStateFile | File to use for saving and restoring session data. |
| SubscriptionIdentifier | A numeric subscription identifier included in SUBSCRIBE packet which will be returned with messages delivered for that subscription. |
| TopicAlias | Value that is used to identify the Topic instead of using the Topic Name in order to reduce packet size. |
| TopicDelimiter | The string to use as a delimiter in a topic filter list string. |
| TopicNLArray | List of No Local option flags for subscription topic filters. |
| TopicQOSArray | Comma-separated list of topic filter QoS values to use when subscribing. |
| TopicRAPArray | List of Retain As Published option flags for subscription topic filters. |
| TopicRHArray | List of Retain Handling option values for subscription topic filters. |
| WillProperties | JSON string specifying will properties to be included in the CONNECT packet. |
| WillQOS | The QoS value to use for the Will message. |
| WillRetain | Whether the server should retain the Will message after publishing it. |
| ConnectionTimeout | Sets a separate timeout value for establishing a connection. |
| FirewallAutoDetect | Tells the class whether or not to automatically detect and use firewall system settings, if available. |
| FirewallHost | Name or IP address of firewall (optional). |
| FirewallPassword | Password to be used if authentication is to be used when connecting through the firewall. |
| FirewallPort | The TCP port for the FirewallHost;. |
| FirewallType | Determines the type of firewall to connect through. |
| FirewallUser | A user name if authentication is to be used connecting through a firewall. |
| KeepAliveInterval | The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received. |
| KeepAliveTime | The inactivity time in milliseconds before a TCP keep-alive packet is sent. |
| Linger | When set to True, connections are terminated gracefully. |
| LingerTime | Time in seconds to have the connection linger. |
| LocalHost | The name of the local host through which connections are initiated or accepted. |
| LocalPort | The port in the local host where the class binds. |
| MaxLineLength | The maximum amount of data to accumulate when no EOL is found. |
| MaxTransferRate | The transfer rate limit in bytes per second. |
| ProxyExceptionsList | A semicolon separated list of hosts and IPs to bypass when using a proxy. |
| TCPKeepAlive | Determines whether or not the keep alive socket option is enabled. |
| TcpNoDelay | Whether or not to delay when sending packets. |
| UseIPv6 | Whether to use IPv6. |
| LogSSLPackets | Controls whether SSL packets are logged when using the internal security API. |
| OpenSSLCADir | The path to a directory containing CA certificates. |
| OpenSSLCAFile | Name of the file containing the list of CA's trusted by your application. |
| OpenSSLCipherList | A string that controls the ciphers to be used by SSL. |
| OpenSSLPrngSeedData | The data to seed the pseudo random number generator (PRNG). |
| ReuseSSLSession | Determines if the SSL session is reused. |
| SSLCACertFilePaths | The paths to CA certificate files on Unix/Linux. |
| SSLCACerts | A newline separated list of CA certificate to use during SSL client authentication. |
| SSLCheckCRL | Whether to check the Certificate Revocation List for the server certificate. |
| SSLCipherStrength | The minimum cipher strength used for bulk encryption. |
| SSLEnabledCipherSuites | The cipher suite to be used in an SSL negotiation. |
| SSLEnabledProtocols | Used to enable/disable the supported security protocols. |
| SSLEnableRenegotiation | Whether the renegotiation_info SSL extension is supported. |
| SSLIncludeCertChain | Whether the entire certificate chain is included in the SSLServerAuthentication event. |
| SSLNegotiatedCipher | Returns the negotiated ciphersuite. |
| SSLNegotiatedCipherStrength | Returns the negotiated ciphersuite strength. |
| SSLNegotiatedCipherSuite | Returns the negotiated ciphersuite. |
| SSLNegotiatedKeyExchange | Returns the negotiated key exchange algorithm. |
| SSLNegotiatedKeyExchangeStrength | Returns the negotiated key exchange algorithm strength. |
| SSLNegotiatedVersion | Returns the negotiated protocol version. |
| SSLProvider | The name of the security provider to use. |
| SSLSecurityFlags | Flags that control certificate verification. |
| SSLServerCACerts | A newline separated list of CA certificate to use during SSL server certificate validation. |
| TLS12SignatureAlgorithms | Defines the allowed TLS 1.2 signature algorithms when UseInternalSecurityAPI is True. |
| TLS12SupportedGroups | The supported groups for ECC. |
| TLS13KeyShareGroups | The groups for which to pregenerate key shares. |
| TLS13SignatureAlgorithms | The allowed certificate signature algorithms. |
| TLS13SupportedGroups | The supported groups for (EC)DHE key exchange. |
| AbsoluteTimeout | Determines whether timeouts are inactivity timeouts or absolute timeouts. |
| FirewallData | Used to send extra data to the firewall. |
| InBufferSize | The size in bytes of the incoming queue of the socket. |
| OutBufferSize | The size in bytes of the outgoing queue of the socket. |
| BuildInfo | Information about the product's build. |
| CodePage | The system code page used for Unicode to Multibyte translations. |
| LicenseInfo | Information about the current license. |
| ProcessIdleEvents | Whether the class uses its internal event loop to process events when the main thread is idle. |
| SelectWaitMillis | The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process. |
| UseInternalSecurityAPI | Tells the class whether or not to use the system security libraries or an internal implementation. |