MQTTSN Component

Properties Methods Events Configuration Settings Errors

A lightweight, fully-featured MQTT-SN client implementation.

Syntax

TiotMQTTSN

Remarks

The MQTTSN component provides a lightweight, fully-featured MQTT-SN (MQTT for Sensor Networks) client implementation over UDP.

Connecting

Connecting to a gateway is easy; in the simplest case, set the ClientId property and call the Connect method, passing it the gateway's hostname and port number.

When connecting to an MQTT gateway, the component sends the following information:

The values of the ClientId, CleanSession, and KeepAliveInterval properties.
The values of the WillTopic and WillMessage properties and the WillRetain and WillQOS configuration settings.

Refer to CleanSession for more information about MQTT sessions; refer to WillTopic, WillMessage, WillQOS and WillRetain for more information about MQTT Wills.

Basic Connection Example

mqttsn1.ClientId = "testClient";
mqttsn1.CleanSession = true;
mqttsn1.KeepAliveInterval = 30;
mqttsn1.WillTopic = "wills/" + mqttsn1.ClientId;
mqttsn1.WillMessage = mqttsn1.ClientId + " was disconnected ungracefully!";
mqttsn1.Connect(host, port);

Topic Subscriptions

The Subscribe and Unsubscribe methods are used to subscribe to and unsubscribe from topics.

When subscribing, pass the topic name or id, topic id type and QoS level. Topic filters may contain wildcards in order to match multiple topics on the server. If a topic name is specified, the SubscribedTopicId configuration setting will contain the assigned id for the topic.

Subscribe Examples

String fullTopicName = "full/topic/name";
mqttsn1.Subscribe(fullTopicName, 0, 2); // subscribe with topic name
int assignedTopicId = mqttsn1.Config("SubscribedTopicId"); // map id to topic name used
 
mqttsn1.Subscribe(fullTopicName+"/#", 0, 2) // topic name with wildcard; SubscribedTopicId will be 0
mqttsn1.OnTopicId += (s,e) => { // will fire before messages matching the wildcard are sent to the client
  int topicId = e.TopicId;
  String topicName = e.TopicName;
  // establish mapping between these
};
 
mqttsn1.Subscribe("aa", 2, 2); // subscribe with short topic name; no need for registration

After subscribing to topics, any messages received on that topic will cause the MessageIn event to fire. Refer to MessageIn for more information about processing steps for inbound messages.

When unsubscribing, pass the topic id or exact topic name used to subscribe.

Unsubscribe Examples

String fullTopicName = "full/topic/name";
mqtt1.Unsubscribe(fullTopicName, 0); // unsubscribe from topic name
 
mqtt1.Unsubscribe(fullTopicName+"/#", 0); // must use full topic filter if includes wildcard; can't unsubscribe from individual topics included in the filter
 
mqtt1.Unsubscribe("aa", 2); // unsubscribe from short topic

Refer to Subscribe and Unsubscribe for more information about subscriptions and topic names.

Publishing Messages

To publish messages to topics, use the PublishMessage and PublishData methods.

PublishMessage is used to publish a message with a string payload, while PublishData is used to publish a message with a raw data payload. Both also accept the topic id to publish to, the topic id type and a QoS level at which to publish.

Publish Examples

// Publish string messages
int id = mqttsn1.RegisterTopic("topic/name"); // must register topic names that are not short or pre-defined
mqttsn1.PublishMessage(id, 0, 2, "hello"); // publish message with registered topic name
 
mqttsn1.PublishMessage("aa", 2, 2, "hello"); // publish message with short topic name
 
// Publish a raw data message.
byte[] picture = ...;
mqtt1.PublishData(id, 0, 2, picture);

Refer to PublishData and PublishMessage for more information about message publishing as well as topic names.

Sleeping

To save battery, clients may enter a sleep state in which their messages will be buffered for them. To manage sleeping, use StartSleep and StopSleep. To receive all buffered messages then return to sleep, use FetchMessages.

If the client exceeds the sleep duration passed to StartSleep without waking or sending any packets, it will be considered lost and will disconnect.

Sleep Examples

mqttsn1.StartSleep(8); // sleep for 8 seconds
// ... wait for 5 seconds
mqttsn1.FetchMessages(); // MessageIn will fire for each message buffered during that time
// ... wait for 5 more seconds (ok because <8 seconds since last packet sent)
mqttsn1.StopSleep();

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.


CleanSession	Determines whether a clean session is used once connected.
ClientId	A string that uniquely identifies this instance of the component to the server.
Connected	Triggers a connection or disconnection.
KeepAliveInterval	The maximum period of inactivity the gateway should allow between receiving messages from the client.
LocalHost	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPort	The UDP port in the local host where UDPPort binds.
RemoteHost	The address of the remote host. Domain names are resolved to IP addresses.
RemotePort	The UDP port in the remote host.
Timeout	A timeout for the component.
WillMessage	The message that the server should publish in the event of an ungraceful disconnection.
WillTopic	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 component with short descriptions. Click on the links for further details.


Config	Sets or retrieves a configuration setting.
Connect	Connects to the MQTTSN Gateway.
Disconnect	Disconnect from the MQTTSN Gateway.
DiscoverGateway	Broadcast a SEARCHGW message to network clients and gateways.
DoEvents	Processes events from the internal message queue.
FetchMessages	Receive currently buffered messages and return to sleep.
Ping	Send a PINGREQ message to the gateway to reset the Keep Alive interval and ensure the gateway's liveliness.
PublishData	Publishes a message with a raw data payload.
PublishMessage	Publishes a message with a string payload.
RegisterTopic	Register a topic name. Returns the topic id mapped to the newly registered topic name.
Reset	Reset the component.
SendDiscoverResponse	Asynchronously respond to a SEARCHGW message received from a peer.
StartSleep	Enter sleep state for the specified duration.
StopSleep	Enter active state, ending the sleep period.
Subscribe	Subscribes the component to the specified topic.
Unsubscribe	Unsubscribes the component from the specified topic.
UpdateWillMessage	Update the will message stored in session state data by the server.
UpdateWillTopic	Update the will topic, will QoS and will retain flag stored in session state data by the server.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.


Connected	Fired after a MQTTSN connection completes (or fails).
Disconnected	Fired when a MQTTSN connection is closed.
DiscoverRequest	Fired when the component receives a SEARCHGW packet from another client.
Error	Information about errors during data delivery.
GatewayInfo	Fired when the component receives a GWINFO or ADVERTISE packet.
Log	Fires once for each log message.
MessageIn	Fired when an incoming message has been received and/or fully acknowledged.
TopicInfo	Fired when the client receives a REGISTER packet from the gateway assigning a topic id to a topic name.

Configuration Settings

The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.


ConnectionTimeout	How long to wait for a connection attempt to succeed.
Duplicate	Whether to set the Duplicate flag when publishing a message.
LogLevel	The level of detail that is logged.
PingTimeout	Length of time to wait for a PINGRESP packet.
Retain	Whether to set the Retain flag when publishing a message.
SubscribedTopicId	Topic id assigned by the gateway when a topic name is used in a SUBSCRIBE message.
SubscribeDUP	Whether to set the Duplicate flag when subscribe to a topic.
WillQOS	The QoS value to use for the Will message.
WillRetain	Whether the server should retain the Will message after publishing it.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
UseInternalSecurityAPI	Tells the component whether or not to use the system security libraries or an internal implementation.

IPWorks IoT 2020 Delphi Edition