MQTTSN Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

nsoftware.IPWorksIoT.Mqttsn

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 ConnectTo method, passing it the gateway's hostname and port number.

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

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.ConnectTo(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.

CleanSessionDetermines whether a clean session is used once connected.
ClientIdA string that uniquely identifies this instance of the component to the server.
ConnectedTriggers a connection or disconnection.
KeepAliveIntervalThe maximum period of inactivity the gateway should allow between receiving messages from the client.
LocalHostThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPortThe UDP port in the local host where UDP binds.
RemoteHostThe address of the remote host. Domain names are resolved to IP addresses.
RemotePortThe UDP port in the remote host.
TimeoutA timeout for the component.
WillMessageThe message that the server should publish in the event of an ungraceful disconnection.
WillTopicThe 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.

ConfigSets or retrieves a configuration setting.
ConnectConnects to the MQTTSN Gateway.
ConnectToConnects to the remote host.
DisconnectDisconnect from the MQTTSN Gateway.
DiscoverGatewayBroadcast a SEARCHGW message to network clients and gateways.
DoEventsProcesses events from the internal message queue.
FetchMessagesReceive currently buffered messages and return to sleep.
PingSend a PINGREQ message to the gateway to reset the Keep Alive interval and ensure the gateway's liveliness.
PublishDataPublishes a message with a raw data payload.
PublishMessagePublishes a message with a string payload.
RegisterTopicRegister a topic name. Returns the topic id mapped to the newly registered topic name.
ResetReset the component.
SendDiscoverResponseAsynchronously respond to a SEARCHGW message received from a peer.
StartSleepEnter sleep state for the specified duration.
StopSleepEnter active state, ending the sleep period.
SubscribeSubscribes the component to the specified topic.
UnsubscribeUnsubscribes the component from the specified topic.
UpdateWillMessageUpdate the will message stored in session state data by the server.
UpdateWillTopicUpdate 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.

ConnectedFired after a MQTTSN connection completes (or fails).
DisconnectedFired when a MQTTSN connection is closed.
DiscoverRequestFired when the component receives a SEARCHGW packet from another client.
ErrorInformation about errors during data delivery.
GatewayInfoFired when the component receives a GWINFO or ADVERTISE packet.
LogFires once for each log message.
MessageInFired when an incoming message has been received and/or fully acknowledged.
TopicInfoFired when the client receives a REGISTER packet from the gateway assigning a topic id to a topic name.

Config Settings


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

ConnectionTimeoutHow long to wait for a connection attempt to succeed.
DuplicateWhether to set the Duplicate flag when publishing a message.
LogLevelThe level of detail that is logged.
PingTimeoutLength of time to wait for a PINGRESP packet.
RetainWhether to set the Retain flag when publishing a message.
SubscribedTopicIdTopic id assigned by the gateway when a topic name is used in a SUBSCRIBE message.
SubscribeDUPWhether to set the Duplicate flag when subscribe to a topic.
WillQOSThe QoS value to use for the Will message.
WillRetainWhether the server should retain the Will message after publishing it.
BuildInfoInformation about the product's build.
GUIAvailableTells the component whether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
MaskSensitiveWhether sensitive data is masked in log messages.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

CleanSession Property (MQTTSN Component)

Determines whether a clean session is used once connected.

Syntax

public bool CleanSession { get; set; }
Public Property CleanSession As Boolean

Default Value

True

Remarks

This property determines whether or not the component should instruct the server to use a clean session when it connects. (Note that this property must be set to the desired value before calling Connect.)

By default, CleanSession is true, so the server will discard any state data previously associated with the current ClientId once the component has connected successfully. In addition, the server will not save any state data when the component disconnects.

Setting CleanSession to False before connecting will cause the server to re-associate any previously stored state data for the current ClientId. The server will also save any state data that exists when the component is disconnected.

The server-side session state consists of:

  • client subscriptions,
  • QoS 1 and 2 messages which are buffering or unacknowledged,
  • QoS 2 messages received from the client but not completely acknowledged, and
  • the WillMessage and WillTopic if set.

Note that retained messages are not deleted as a result of a session ending, but are not part of the session state.

This property is not available at design time.

ClientId Property (MQTTSN Component)

A string that uniquely identifies this instance of the component to the server.

Syntax

public string ClientId { get; set; }
Public Property ClientId As String

Default Value

""

Remarks

The ClientId string is used by the server to uniquely identify each client that is connected to it.

If ClientId is empty when Connect is called, the component's behavior depends on value of CleanSession. If CleanSession is True, the component will automatically generate a unique value for ClientId before connecting. If CleanSession is False, the component throws an exception.

This property is not available at design time.

Connected Property (MQTTSN Component)

Triggers a connection or disconnection.

Syntax

public bool Connected { get; set; }
Public Property Connected As Boolean

Default Value

False

Remarks

This property triggers a connection or disconnection. Setting this property to True makes the component send a CONNECT packet to the MQTTSN Gateway identified by the RemoteHost property. If successful, after the connection is achieved the value of the property changes to True and the Connected event is fired.

Setting this property to False sends a DISCONNECT packet, closing the connection.

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

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.RemoteHost = host; mqttsn1.RemotePort = port; mqttsn1.Connect();

This property is not available at design time.

KeepAliveInterval Property (MQTTSN Component)

The maximum period of inactivity the gateway should allow between receiving messages from the client.

Syntax

public int KeepAliveInterval { get; set; }
Public Property KeepAliveInterval As Integer

Default Value

0

Remarks

The KeepAliveInterval, if set to a non-zero value, is the maximum number of seconds that the gateway will allow the connection to be idle without receiving a message from the client. The value of KeepAliveInterval is sent to the server when Connect is called; it cannot be changed when the component is already connected.

MQTT servers are required to measure periods of inactivity for all clients who specify a non-zero KeepAliveInterval, and must consider them lost if they have not communicated within the KeepAliveInterval. The gateway will activate the Will feature for lost clients.

To maintain the connection, the server must send a PINGREQ (ping request) packet within the KeepAliveInterval seconds after the most recent message sent. For more see the Ping method.

Similarly, if the component doesn't receive a PINGRESP (ping response) packet after multiple retransmissions of the PINGREQ packet, it should first try to connect to another gateway before trying to re-connect to the original one.

If KeepAliveInterval is set to 0 (default), the server is not required to consider inactivity. Note that, regardless of keep-alive settings, the server is always free to disconnect clients it deems "unresponsive".

This property is not available at design time.

LocalHost Property (MQTTSN Component)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

public string LocalHost { get; set; }
Public Property LocalHost As String

Default Value

""

Remarks

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the component initiate connections (or accept in the case of server components) only through that interface.

If the component is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

LocalPort Property (MQTTSN Component)

The UDP port in the local host where UDP binds.

Syntax

public int LocalPort { get; set; }
Public Property LocalPort As Integer

Default Value

0

Remarks

The LocalPort property must be set before UDP is activated (Active is set to True). It instructs the component to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the TCP/IP stack to choose a port at random. The chosen port will be shown by the LocalPort property after the connection is established.

LocalPort cannot be changed once the component is Active. Any attempt to set the LocalPort property when the component is Active will generate an error.

The LocalPort property is useful when trying to connect to services that require a trusted port in the client side.

RemoteHost Property (MQTTSN Component)

The address of the remote host. Domain names are resolved to IP addresses.

Syntax

public string RemoteHost { get; set; }
Public Property RemoteHost As String

Default Value

""

Remarks

The RemoteHost property specifies the IP address (IP number in dotted internet format) or Domain Name of the remote host.

If RemoteHost is set to 255.255.255.255, the component broadcasts data on the local subnet.

If the RemoteHost property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the RemoteHost property is set to the corresponding address. If the search is not successful, an error is returned.

If UseConnection is set to True, the RemoteHost must be set before the component is activated (Active is set to True).

RemotePort Property (MQTTSN Component)

The UDP port in the remote host.

Syntax

public int RemotePort { get; set; }
Public Property RemotePort As Integer

Default Value

0

Remarks

The RemotePort is the UDP port on the RemoteHost to send UDP datagrams to.

A valid port number (a value between 1 and 65535) is required.

If UseConnection is set to True, the RemotePort must be set before the component is activated (Active is set to True).

Timeout Property (MQTTSN Component)

A timeout for the component.

Syntax

public int Timeout { get; set; }
Public Property Timeout As Integer

Default Value

60

Remarks

This property defines the timeout when sending data. A value of 0 means data will be sent asynchronously and a positive value means data is sent synchronously.

The component will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the component throws an exception. Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received. The default value for the Timeout property is 60 seconds.

WillMessage Property (MQTTSN Component)

The message that the server should publish in the event of an ungraceful disconnection.

Syntax

public string WillMessage { get; set; }
Public Property WillMessage As String

Default Value

""

Remarks

This property may be set before calling Connect to specify to the server a message that should be published on WillTopic if the connection is closed ungracefully or lost.

The WillMessage will only be sent to the server when Connect is called if WillTopic is set. Note that in MQTTSN the clean session concept is extended to will topic and will message. The WillMessage can be updated with the UpdateWillMessage method.

Refer to WillTopic for more information about MQTT Will functionality.

This property is not available at design time.

WillTopic Property (MQTTSN Component)

The topic that the server should publish the WillMessage to in the event of an ungraceful disconnection.

Syntax

public string WillTopic { get; set; }
Public Property WillTopic As String

Default Value

""

Remarks

This property may be set before calling Connect to specify the topic name that the server should publish the WillMessage on if the connection is closed ungracefully or lost.

MQTT Wills

The Will feature of MQTT allows a client to specify to the server a WillMessage to publish (as well as a WillTopic to publish it on) in the event that the server considers the client lost or ungracefully disconnected.

An "ungraceful disconnection" is any disconnection other than one triggered by calling Disconnect. If the client enters sleep mode, the server will not publish the Will. However, if the client is lost as a result of exceeding the sleep duration without sending a message, the server will publish the Will.

In addition to the WillTopic and WillMessage properties, the WillQOS setting may be used to specify the Will message's QoS level, and the WillRetain setting to set the Will message's Retain flag. Refer to those settings for more information.

If WillTopic is set to empty string (default) when Connect is called, the component will not send a Will to the server.

In MQTTSN, the WillTopic, WillMessage, WillQOS and WillRetain may all be updated using the UpdateWillMessage and UpdateWillTopic methods.

This property is not available at design time.

Config Method (MQTTSN Component)

Sets or retrieves a configuration setting.

Syntax

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);
Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Connect Method (MQTTSN Component)

Connects to the MQTTSN Gateway.

Syntax

public void Connect();

Async Version
public async Task Connect();
public async Task Connect(CancellationToken cancellationToken);
Public Sub Connect()

Async Version
Public Sub Connect() As Task
Public Sub Connect(cancellationToken As CancellationToken) As Task

Remarks

This method connects to the MQTTSN Gateway, specified by RemoteHost and RemotePort, by sending a CONNECT packet. Calling this method is equivalent to setting the Connected property to True.

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

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.RemoteHost = host; mqttsn1.RemotePort = port; mqttsn1.Connect();

ConnectTo Method (MQTTSN Component)

Connects to the remote host.

Syntax

public void ConnectTo(string host, int port);

Async Version
public async Task ConnectTo(string host, int port);
public async Task ConnectTo(string host, int port, CancellationToken cancellationToken);
Public Sub ConnectTo(ByVal Host As String, ByVal Port As Integer)

Async Version
Public Sub ConnectTo(ByVal Host As String, ByVal Port As Integer) As Task
Public Sub ConnectTo(ByVal Host As String, ByVal Port As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method connects to the MQTTSN Gateway, specified by Host and Port, by sending a CONNECT packet. Calling this method is equivalent to setting the RemoteHost property to Host, setting RemotePort to Port, and then setting the Connected property to True.

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

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.ConnectTo(host, port);

Disconnect Method (MQTTSN Component)

Disconnect from the MQTTSN Gateway.

Syntax

public void Disconnect();

Async Version
public async Task Disconnect();
public async Task Disconnect(CancellationToken cancellationToken);
Public Sub Disconnect()

Async Version
Public Sub Disconnect() As Task
Public Sub Disconnect(cancellationToken As CancellationToken) As Task

Remarks

This method disconnects from the MQTTSN Gateway by sending a DISCONNECT packet. Calling this method is equivalent to setting the Connected property to False.

Refer to the Connected property for more information about MQTT-specific behavior.

DiscoverGateway Method (MQTTSN Component)

Broadcast a SEARCHGW message to network clients and gateways.

Syntax

public void DiscoverGateway(int broadcastRadius);

Async Version
public async Task DiscoverGateway(int broadcastRadius);
public async Task DiscoverGateway(int broadcastRadius, CancellationToken cancellationToken);
Public Sub DiscoverGateway(ByVal BroadcastRadius As Integer)

Async Version
Public Sub DiscoverGateway(ByVal BroadcastRadius As Integer) As Task
Public Sub DiscoverGateway(ByVal BroadcastRadius As Integer, cancellationToken As CancellationToken) As Task

Remarks

Broadcast a SEARCHGW message in order to discover nearby gateways. Network clients and gateways may respond with a GWINFO message containing a gateway id. Such a response will trigger the GatewayInfo event.

This functionality is not yet implemented.

DoEvents Method (MQTTSN Component)

Processes events from the internal message queue.

Syntax

public void DoEvents();

Async Version
public async Task DoEvents();
public async Task DoEvents(CancellationToken cancellationToken);
Public Sub DoEvents()

Async Version
Public Sub DoEvents() As Task
Public Sub DoEvents(cancellationToken As CancellationToken) As Task

Remarks

When DoEvents is called, the component processes any available events. If no events are available, it waits for a preset period of time, and then returns.

FetchMessages Method (MQTTSN Component)

Receive currently buffered messages and return to sleep.

Syntax

public void FetchMessages();

Async Version
public async Task FetchMessages();
public async Task FetchMessages(CancellationToken cancellationToken);
Public Sub FetchMessages()

Async Version
Public Sub FetchMessages() As Task
Public Sub FetchMessages(cancellationToken As CancellationToken) As Task

Remarks

Request any messages currently being buffered by the server for the current sleep period and return to sleep after they have been received.

Any available buffered messages will be sent to the client by the MQTTSN Gateway and the sleep interval will be reset.

This method sends a PINGREQ method with the ClientId, requesting buffered messages which will be sent if available (see MessageIn). When the server has sent all messages, it will sent a PINGRESP message, causing the client to re-enter sleep mode. Once the PINGRESP is received, the duration the client may sleep restarts.

Ping Method (MQTTSN Component)

Send a PINGREQ message to the gateway to reset the Keep Alive interval and ensure the gateway's liveliness.

Syntax

public void Ping();

Async Version
public async Task Ping();
public async Task Ping(CancellationToken cancellationToken);
Public Sub Ping()

Async Version
Public Sub Ping() As Task
Public Sub Ping(cancellationToken As CancellationToken) As Task

Remarks

The client must send a PINGREQ message using this method during each KeepAliveInterval period. If the client does not send any message to the gateway during this period, it will be considered lost and will disconnect.

The client also uses this message to supervise the liveliness of the gateway to which they are connected. If a client does not receive a PINGRESP from the gateway even after multiple retransmissions of the PINGREQ message, it should first try to connect to another gateway before trying to re-connect to this gateway.

See KeepAliveInterval for more information.

For more detailed requirements regarding Keep Alive intervals and reconnection, refer to the MQTTSN specification.

PublishData Method (MQTTSN Component)

Publishes a message with a raw data payload.

Syntax

public void PublishData(string topicId, int topicIdType, int QOS, byte[] data);

Async Version
public async Task PublishData(string topicId, int topicIdType, int QOS, byte[] data);
public async Task PublishData(string topicId, int topicIdType, int QOS, byte[] data, CancellationToken cancellationToken);
Public Sub PublishData(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer, ByVal Data As String)

Async Version
Public Sub PublishData(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer, ByVal Data As String) As Task
Public Sub PublishData(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer, ByVal Data As String, cancellationToken As CancellationToken) As Task

Remarks

This method publishes an MQTTSN message with a raw data payload to the specified TopicId at a given QOS level.

The Retain configuration setting may be set before calling this method in order to publish a retained message (see Retain for more information).

Note that the component will only allow one publish flow at a time.

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);

Topic Ids

A topic id is a short identifier corresponding to a longer topic name which is used in MQTTSN due to the limited bandwidth and small message payload in wireless sensor networks.

The type of topic id sent with the message must be specified. TopicIdType may have the following values:

  • 0: Registered topic id
  • 1: Pre-defined topic id
  • 2: Short topic name

A registered topic id identifies a topic name registered with the server before the time of the message. To register a topic id for a given topic name with the gateway so that messages may be published to that topic using that topic id, use the RegisterTopic method.

A pre-defined topic id is one whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.

A short topic name has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.

Topic Names

Topic names are case-sensitive, must be 1-65535 characters long, and may include any characters except wildcard characters (# and +) and the null character. The / character separates levels within a topic name, which is important in the context of subscribing (see Subscribe for more information).

Keep in mind that using topic names with leading or trailing / characters will cause topic levels with zero-length names to be created. That is, a topic name like /a/b/ consists of the levels '', 'a', 'b', and ''. Depending on the server, multiple successive /s may also cause zero-length levels to be created, or may be treated as a single /.

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

QoS Values

QoS values set the service level for delivery of a message. Values range from -1 to 2 and have the following meanings:

QoS LevelDescription
-1 Simple publish - No connection, registration or subscription needed.
0 At most once - The published message is sent once, and if it does not arrive it is lost.
1 At least once - Guarantees that the published message arrives, but there may be duplicates.
2 Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

To send a message with QoS -1, simply set RemoteHost and RemoteHost and call PublishMessage with a pre-defined topic id or short topic name. No connection or registration is necessary. The client will not be informed whether the gateway address is correct, whether the gateway is alive, or whether the messages arrive at the gateway.

Publish QoS -1 Example mqttsn1 = new Mqttsn(); mqttsn1.RemoteHost = gatewayAddress; mqttsn1.RemotePort = gatewayPort; mqttsn1.PublishMessage("aa", 2, -1, "hello"); // publish QoS -1 message; no connection or registration

Republishing Messages

For QoS 1 and 2 messages, the client is responsible for retransmitting the message if it is not fully acknowledged within a reasonable wait time. To do so, set the Duplicate flag configuration setting and call the publish method again.

After a reasonable amount of retransmission attempts, the client should abort the procedure and assume the gateway has disconnected. It should then try to connect to another gateway, only returning to the original if it fails.

PublishMessage Method (MQTTSN Component)

Publishes a message with a string payload.

Syntax

public void PublishMessage(string topicId, int topicIdType, int QOS, string message);

Async Version
public async Task PublishMessage(string topicId, int topicIdType, int QOS, string message);
public async Task PublishMessage(string topicId, int topicIdType, int QOS, string message, CancellationToken cancellationToken);
Public Sub PublishMessage(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer, ByVal Message As String)

Async Version
Public Sub PublishMessage(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer, ByVal Message As String) As Task
Public Sub PublishMessage(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer, ByVal Message As String, cancellationToken As CancellationToken) As Task

Remarks

This method publishes an MQTTSN message with a string payload to the specified TopicId at a given QOS level.

The Retain configuration setting may be set before calling this method in order to publish a retained message (see Retain for more information).

Note that the component will only allow one publish flow at a time.

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);

Topic Ids

A topic id is a short identifier corresponding to a longer topic name which is used in MQTTSN due to the limited bandwidth and small message payload in wireless sensor networks.

The type of topic id sent with the message must be specified. TopicIdType may have the following values:

  • 0: Registered topic id
  • 1: Pre-defined topic id
  • 2: Short topic name

A registered topic id identifies a topic name registered with the server before the time of the message. To register a topic id for a given topic name with the gateway so that messages may be published to that topic using that topic id, use the RegisterTopic method.

A pre-defined topic id is one whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.

A short topic name has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.

Topic Names

Topic names are case-sensitive, must be 1-65535 characters long, and may include any characters except wildcard characters (# and +) and the null character. The / character separates levels within a topic name, which is important in the context of subscribing (see Subscribe for more information).

Keep in mind that using topic names with leading or trailing / characters will cause topic levels with zero-length names to be created. That is, a topic name like /a/b/ consists of the levels '', 'a', 'b', and ''. Depending on the server, multiple successive /s may also cause zero-length levels to be created, or may be treated as a single /.

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

QoS Values

QoS values set the service level for delivery of a message. Values range from -1 to 2 and have the following meanings:

QoS LevelDescription
-1 Simple publish - No connection, registration or subscription needed.
0 At most once - The published message is sent once, and if it does not arrive it is lost.
1 At least once - Guarantees that the published message arrives, but there may be duplicates.
2 Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

To send a message with QoS -1, simply set RemoteHost and RemoteHost and call PublishMessage with a pre-defined topic id or short topic name. No connection or registration is necessary. The client will not be informed whether the gateway address is correct, whether the gateway is alive, or whether the messages arrive at the gateway.

Publish QoS -1 Example mqttsn1 = new Mqttsn(); mqttsn1.RemoteHost = gatewayAddress; mqttsn1.RemotePort = gatewayPort; mqttsn1.PublishMessage("aa", 2, -1, "hello"); // publish QoS -1 message; no connection or registration

Republishing Messages

For QoS 1 and 2 messages, the client is responsible for retransmitting the message if it is not fully acknowledged within a reasonable wait time. To do so, set the Duplicate flag configuration setting and call the publish method again.

After a reasonable amount of retransmission attempts, the client should abort the procedure and assume the gateway has disconnected. It should then try to connect to another gateway, only returning to the original if it fails.

RegisterTopic Method (MQTTSN Component)

Register a topic name. Returns the topic id mapped to the newly registered topic name.

Syntax

public int RegisterTopic(string topicName);

Async Version
public async Task<int> RegisterTopic(string topicName);
public async Task<int> RegisterTopic(string topicName, CancellationToken cancellationToken);
Public Function RegisterTopic(ByVal TopicName As String) As Integer

Async Version
Public Function RegisterTopic(ByVal TopicName As String) As Task(Of Integer)
Public Function RegisterTopic(ByVal TopicName As String, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

Requests that the gateway establish a new topic id mapping for the TopicName provided. If accepted, the gateway assigns a topic id to the received topic name and returns it. At this point, the client may begin sending messages with this topic id.

Topic Names

Topic names are case-sensitive, must be 1-65535 characters long, and may include any characters except wildcard characters (# and +) and the null character. The / character separates levels within a topic name, which is important in the context of subscribing (see Subscribe for more information).

Keep in mind that using topic names with leading or trailing / characters will cause topic levels with zero-length names to be created. That is, a topic name like /a/b/ consists of the levels '', 'a', 'b', and ''. Depending on the server, multiple successive /s may also cause zero-length levels to be created, or may be treated as a single /.

Topic names that begin with a $ are "system topics", and servers will typically prevent clients from publishing to them.

Reset Method (MQTTSN Component)

Reset the component.

Syntax

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);
Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method will reset the component's properties to their default values.

SendDiscoverResponse Method (MQTTSN Component)

Asynchronously respond to a SEARCHGW message received from a peer.

Syntax

public void SendDiscoverResponse(int gatewayId, string gatewayAddress);

Async Version
public async Task SendDiscoverResponse(int gatewayId, string gatewayAddress);
public async Task SendDiscoverResponse(int gatewayId, string gatewayAddress, CancellationToken cancellationToken);
Public Sub SendDiscoverResponse(ByVal GatewayId As Integer, ByVal GatewayAddress As String)

Async Version
Public Sub SendDiscoverResponse(ByVal GatewayId As Integer, ByVal GatewayAddress As String) As Task
Public Sub SendDiscoverResponse(ByVal GatewayId As Integer, ByVal GatewayAddress As String, cancellationToken As CancellationToken) As Task

Remarks

Asynchronously respond to a SEARCHGW message received from a peer. See also DiscoverRequest.

This functionality is not yet implemented.

StartSleep Method (MQTTSN Component)

Enter sleep state for the specified duration.

Syntax

public void StartSleep(int duration);

Async Version
public async Task StartSleep(int duration);
public async Task StartSleep(int duration, CancellationToken cancellationToken);
Public Sub StartSleep(ByVal Duration As Integer)

Async Version
Public Sub StartSleep(ByVal Duration As Integer) As Task
Public Sub StartSleep(ByVal Duration As Integer, cancellationToken As CancellationToken) As Task

Remarks

When this method is called, the gateway will buffer all incoming messages for the client until the next time it awakes. To receive all currently buffered messages, call StopSleep or FetchMessages.

While in the sleep state, the client no longer must abide by the KeepAliveInterval, but must awake before the end of the sleep duration. If it does not send the gateway any messages in this interval, it will be considered lost and will disconnect.

If FetchMessages is called, the client will return to sleep after receiving the messages and the sleep timer will restart. If StopSleep is called, the client will enter the active state.

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();

StopSleep Method (MQTTSN Component)

Enter active state, ending the sleep period.

Syntax

public void StopSleep();

Async Version
public async Task StopSleep();
public async Task StopSleep(CancellationToken cancellationToken);
Public Sub StopSleep()

Async Version
Public Sub StopSleep() As Task
Public Sub StopSleep(cancellationToken As CancellationToken) As Task

Remarks

Wake up from the sleep state and receive any messages which were buffered by the gateway during the sleep period. This method must be called before the end of the duration specified in the StartSleep method.

Once active, the client is once again subject to KeepAliveInterval supervision just like after connection.

Subscribe Method (MQTTSN Component)

Subscribes the component to the specified topic.

Syntax

public void Subscribe(string topicId, int topicIdType, int QOS);

Async Version
public async Task Subscribe(string topicId, int topicIdType, int QOS);
public async Task Subscribe(string topicId, int topicIdType, int QOS, CancellationToken cancellationToken);
Public Sub Subscribe(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer)

Async Version
Public Sub Subscribe(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer) As Task
Public Sub Subscribe(ByVal TopicId As String, ByVal TopicIdType As Integer, ByVal QOS As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method subscribes the component to the TopicId using the given QoS level.

TopicIdType indicates the category of value specified in TopicId and may have the following values:

  • 0: Topic name - a full topic name as described in RegisterTopic to be registered by the gateway.
  • 1: Pre-defined topic id - id whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.
  • 2: Short topic name - has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.

If the topic name option is used, the topic id returned with the SUBACK packet will be accessible in the SubscribedTopicId configuration setting. If a topic name with a wildcard character is used, SubscribedTopicId will be 0. When the gateway has a PUBLISH message with a topic name matching the wildcard to be sent to the client, it will follow the registration process described in TopicInfo.

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

Topic Filters

A topic filter is a string which can be passed to TopicId when TopicIdType is 0 and can match one or more topic names.

A topic filter is a case-sensitive string between 1 and 65535 characters long (per topic filter), and can include any character other than the null character. Certain characters have special meanings:

  • / - The topic level separator
  • # - The multi-level wildcard (zero or more levels)
  • + - The single-level wildcard (exactly one level)
  • Leading $ - Denotes a "system topic"

Note that both types of wildcards may be used in the same topic filter.

Topic Level Separators

The topic level separator, as its name implies, is used to separate a topic name (or in this case, filter) into "levels". This concept of topic names having levels is what allows topic filters to match multiple topics through the use of wildcards. For the examples in the next sections, assume the following topics exist:

  • home/floor1
  • home/floor1/livingRoom
  • home/floor1/livingRoom/temperature
  • home/floor1/kitchen/temperature
  • home/floor1/kitchen/fridge/temperature
  • home/floor2/bedroom1
  • home/floor2/bedroom1/temperature

Multi-level Wildcards

The multi-level wildcard character is used at the end of a topic filter to make it match an arbitrary number of successive levels. For example, the topic filter home/floor1/# would match the following topics:

  • home/floor1 (because it can match zero levels)
  • home/floor1/livingRoom
  • home/floor1/livingRoom/temperature
  • home/floor1/kitchen/temperature
  • home/floor1/kitchen/fridge/temperature

Here are some things to keep in mind when using a multi-level wildcard:

  • # must always be the last character in the topic filter (e.g., home/floor1/#/livingRoom is not valid)
  • # must always be preceded by a / (e.g., home/floor1# is not valid)
  • # by itself is a valid topic filter, and will match all topics except system topics

Single-level Wildcards

The single-level wildcard character is used between two /s in a topic filter to make it any single level. For example, the topic filter home/floor1/+/temperature would match the following topics:

  • home/floor1/livingRoom/temperature
  • home/floor1/kitchen/temperature

Any number of single-level wildcards are supported in a topic filter. For example, the topic filter home/+/+/temperature would match the following topics:

  • home/floor1/livingRoom/temperature
  • home/floor1/kitchen/temperature
  • home/floor2/bedroom1/temperature

Here are some things to keep in mind when using single-level wildcards:

  • + must always be separated from other levels using /s (e.g., home/floor1+ is invalid, but +/floor1/+ is valid)
  • + by itself is a valid topic filter, and will match all topics with exactly one level in their name except system topics
  • Remember, topic names with a leading / have a zero-length string as their first level. So a topic named /people would be matched by the topic filter +/+, but not by +
  • + must match exactly one level. So for example, the topic filter home/floor1/kitchen/+/temperature would match /home/floor1/kitchen/fridge/temperature, but not home/floor1/kitchen/temperature

QoS Values

QoS values set the service level for delivery of a message. For subscriptions, values range from 0 to 2 and have the following meanings:

QoS LevelDescription
-1 Simple publish - No connection, registration or subscription needed.
0 At most once - The published message is sent once, and if it does not arrive it is lost.
1 At least once - Guarantees that the published message arrives, but there may be duplicates.
2 Exactly once - Guarantees that the publish message arrives and that there are no duplicates.

A QoS value of -1 is not applicable to subscriptions.

Note that if this message is being resent, the SubscribeDUP configuration setting must be enabled. For more details on retransmission intervals and counts, see the MQTTSN specification.

Unsubscribe Method (MQTTSN Component)

Unsubscribes the component from the specified topic.

Syntax

public void Unsubscribe(string topicId, int topicIdType);

Async Version
public async Task Unsubscribe(string topicId, int topicIdType);
public async Task Unsubscribe(string topicId, int topicIdType, CancellationToken cancellationToken);
Public Sub Unsubscribe(ByVal TopicId As String, ByVal TopicIdType As Integer)

Async Version
Public Sub Unsubscribe(ByVal TopicId As String, ByVal TopicIdType As Integer) As Task
Public Sub Unsubscribe(ByVal TopicId As String, ByVal TopicIdType As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method unsubscribes the component to the TopicId.

TopicIdType indicates the category of value specified in TopicId and may have the following values:

  • 0: Topic name - a full topic name as described in RegisterTopic to be registered by the gateway.
  • 1: Pre-defined topic id - id whose mapping to a topic name is known in advance by both the client and the gateway - no registration is necessary.
  • 2: Short topic name - has a fixed length of two bytes and is short enough that no registration is necessary. To use one, simply set the correct TopicIdType and set the TopicId to a two-character string.

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

UpdateWillMessage Method (MQTTSN Component)

Update the will message stored in session state data by the server.

Syntax

public void UpdateWillMessage();

Async Version
public async Task UpdateWillMessage();
public async Task UpdateWillMessage(CancellationToken cancellationToken);
Public Sub UpdateWillMessage()

Async Version
Public Sub UpdateWillMessage() As Task
Public Sub UpdateWillMessage(cancellationToken As CancellationToken) As Task

Remarks

When this message is called, the value of WillMessage will be used to update the will message stored by the server.

This method may be called when this value is empty, in this case the server value will be cleared.

See UpdateWillTopic for more on updating will settings.

UpdateWillTopic Method (MQTTSN Component)

Update the will topic, will QoS and will retain flag stored in session state data by the server.

Syntax

public void UpdateWillTopic();

Async Version
public async Task UpdateWillTopic();
public async Task UpdateWillTopic(CancellationToken cancellationToken);
Public Sub UpdateWillTopic()

Async Version
Public Sub UpdateWillTopic() As Task
Public Sub UpdateWillTopic(cancellationToken As CancellationToken) As Task

Remarks

When this message is called, the value of WillTopic, WillQOS and WillRetain will be used to update the will message stored by the server.

This method may be called when these values are empty, in this case the server values will be cleared.

See UpdateWillMessage for more on updating will settings.

Connected Event (MQTTSN Component)

Fired after a MQTTSN connection completes (or fails).

Syntax

public event OnConnectedHandler OnConnected;

public delegate void OnConnectedHandler(object sender, MqttsnConnectedEventArgs e);

public class MqttsnConnectedEventArgs : EventArgs {
  public int StatusCode { get; }
  public string Description { get; }
}
Public Event OnConnected As OnConnectedHandler

Public Delegate Sub OnConnectedHandler(sender As Object, e As MqttsnConnectedEventArgs)

Public Class MqttsnConnectedEventArgs Inherits EventArgs
  Public ReadOnly Property StatusCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

If no will topic or message is set, this event will fire immediately. If a will topic and the will message are set, this event will be fired after the will packet exchange.

If the connection is made normally, StatusCode is 0 and Description is "OK".

Please refer to the Error Codes section for more information.

Refer to the Connected property for more information about MQTT-specific behavior.

Disconnected Event (MQTTSN Component)

Fired when a MQTTSN connection is closed.

Syntax

public event OnDisconnectedHandler OnDisconnected;

public delegate void OnDisconnectedHandler(object sender, MqttsnDisconnectedEventArgs e);

public class MqttsnDisconnectedEventArgs : EventArgs {
  public int StatusCode { get; }
  public string Description { get; }
}
Public Event OnDisconnected As OnDisconnectedHandler

Public Delegate Sub OnDisconnectedHandler(sender As Object, e As MqttsnDisconnectedEventArgs)

Public Class MqttsnDisconnectedEventArgs Inherits EventArgs
  Public ReadOnly Property StatusCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

If the connection is broken normally, StatusCode is 0 and Description is "OK".

Refer to the Connected property for more information about MQTT-specific behavior.

DiscoverRequest Event (MQTTSN Component)

Fired when the component receives a SEARCHGW packet from another client.

Syntax

public event OnDiscoverRequestHandler OnDiscoverRequest;

public delegate void OnDiscoverRequestHandler(object sender, MqttsnDiscoverRequestEventArgs e);

public class MqttsnDiscoverRequestEventArgs : EventArgs {
  public int Radius { get; }
  public int GatewayId { get; set; }
  public string GatewayAddress { get; set; }
  public bool Respond { get; set; }
}
Public Event OnDiscoverRequest As OnDiscoverRequestHandler

Public Delegate Sub OnDiscoverRequestHandler(sender As Object, e As MqttsnDiscoverRequestEventArgs)

Public Class MqttsnDiscoverRequestEventArgs Inherits EventArgs
  Public ReadOnly Property Radius As Integer
  Public Property GatewayId As Integer
  Public Property GatewayAddress As String
  Public Property Respond As Boolean
End Class

Remarks

This event allows the client to process the received gateway info and decide whether or not to respond to the search request.

If Respond is set to True, the component will respond with a GWINFO packet.

This functionality is not yet implemented.

Error Event (MQTTSN Component)

Information about errors during data delivery.

Syntax

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, MqttsnErrorEventArgs e);

public class MqttsnErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}
Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As MqttsnErrorEventArgs)

Public Class MqttsnErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

GatewayInfo Event (MQTTSN Component)

Fired when the component receives a GWINFO or ADVERTISE packet.

Syntax

public event OnGatewayInfoHandler OnGatewayInfo;

public delegate void OnGatewayInfoHandler(object sender, MqttsnGatewayInfoEventArgs e);

public class MqttsnGatewayInfoEventArgs : EventArgs {
  public string MessageType { get; }
  public int GatewayId { get; }
  public string GatewayAddress { get; }
  public int Interval { get; }
}
Public Event OnGatewayInfo As OnGatewayInfoHandler

Public Delegate Sub OnGatewayInfoHandler(sender As Object, e As MqttsnGatewayInfoEventArgs)

Public Class MqttsnGatewayInfoEventArgs Inherits EventArgs
  Public ReadOnly Property MessageType As String
  Public ReadOnly Property GatewayId As Integer
  Public ReadOnly Property GatewayAddress As String
  Public ReadOnly Property Interval As Integer
End Class

Remarks

This event allows packets containing gateway information to be processed. These packets could be received from regular gateway advertisements or gateway info requests from this or other clients. This gateway information is used to manage the client's list of active gateways.

The value of MessageType could be GWINFO or ADVERTISE.

GatewayAddress will be in format host:port.

If the gateway address field is not present in the received GWINFO packet, GatewayAddress will use the packet source IP address.

This functionality is not yet implemented.

Log Event (MQTTSN Component)

Fires once for each log message.

Syntax

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, MqttsnLogEventArgs e);

public class MqttsnLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}
Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As MqttsnLogEventArgs)

Public Class MqttsnLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event fires once for each log message generated by the component. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of the Message. Possible values are:

0 (None) No events are logged.
1 (Info - default) Informational events are logged.
2 (Verbose) Detailed data is logged.
3 (Debug) Debug data is logged.

LogType identifies the type of log entry. Possible values are:

  • Info: General information about the component.
  • Packet: Packet content logging.
  • Reconnect: Reconnection status messages.
  • Session: Session status messages.

MessageIn Event (MQTTSN Component)

Fired when an incoming message has been received and/or fully acknowledged.

Syntax

public event OnMessageInHandler OnMessageIn;

public delegate void OnMessageInHandler(object sender, MqttsnMessageInEventArgs e);

public class MqttsnMessageInEventArgs : EventArgs {
  public int MsgId { get; }
  public string TopicId { get; }
  public int TopicIdType { get; }
  public int QOS { get; }
  public string Message { get; }
public byte[] MessageB { get; } public bool Retained { get; } public bool Duplicate { get; } public int ReturnCode { get; set; } }
Public Event OnMessageIn As OnMessageInHandler

Public Delegate Sub OnMessageInHandler(sender As Object, e As MqttsnMessageInEventArgs)

Public Class MqttsnMessageInEventArgs Inherits EventArgs
  Public ReadOnly Property MsgId As Integer
  Public ReadOnly Property TopicId As String
  Public ReadOnly Property TopicIdType As Integer
  Public ReadOnly Property QOS As Integer
  Public ReadOnly Property Message As String
Public ReadOnly Property MessageB As Byte() Public ReadOnly Property Retained As Boolean Public ReadOnly Property Duplicate As Boolean Public Property ReturnCode As Integer End Class

Remarks

Fired on reception of a PUBLISH packet for QoS 0 and 1 messages, and reception of a PUBREL packet for QoS 2 messages.

  • MsgId: a unique (among currently unacknowledged incoming messages) identifier attached to messages of QoS 1 and 2. Otherwise value will be 0.
  • TopicId: topic id of type TopicIdType.
  • TopicIdType: 0 = registered topic id, 1 = pre-defined topic id, 2 = short topic name.
  • QOS: The message's QoS level.
  • Message: The message data.
  • Retained: Whether or not this message was received as a result of subscribing to a topic.
  • Duplicate: Whether or not the server has indicated that this message is a duplicate of another message sent previously.
  • ReturnCode: QoS 1 messages can be accepted or rejected by setting the ReturnCode to a value listed below.
    • 0: accepted
    • 1: rejected - congestion
    • 2: rejected - invalid topic id
    • 3: rejected - not supported

Inbound Message Processing

Incoming messages with a QoS of 1 follow these steps:

  1. The TopicInfo event is fired (if the gateway sends a REGISTER packet because it needs to inform the client name and assigned topic id it will use in a PUBLISH message).
  2. The component sends a REGACK (register acknowledgment) packet in response (if a REGISTER packet was received).
  3. The MessageIn event is fired.
  4. The component sends a PUBACK (publish acknowledgment) packet in response (with the return code from the MessageIn event if one is set).

Incoming messages with a QoS of 2 follow these steps:

  1. The TopicInfo event is fired (if the gateway sends a REGISTER packet because it needs to inform the client name and assigned topic id it will use in a PUBLISH message).
  2. The component sends a REGACK (register acknowledgment) packet in response (if a REGISTER packet was received).
  3. The component sends a PUBREC (publish received) packet in response.
  4. The component waits to receive a PUBREL (publish release) packet.
  5. The component sends a PUBCOMP (publish complete) packet in response.
  6. The MessageIn event is fired.

TopicInfo Event (MQTTSN Component)

Fired when the client receives a REGISTER packet from the gateway assigning a topic id to a topic name.

Syntax

public event OnTopicInfoHandler OnTopicInfo;

public delegate void OnTopicInfoHandler(object sender, MqttsnTopicInfoEventArgs e);

public class MqttsnTopicInfoEventArgs : EventArgs {
  public int TopicId { get; }
  public string TopicName { get; }
  public int ReturnCode { get; set; }
}
Public Event OnTopicInfo As OnTopicInfoHandler

Public Delegate Sub OnTopicInfoHandler(sender As Object, e As MqttsnTopicInfoEventArgs)

Public Class MqttsnTopicInfoEventArgs Inherits EventArgs
  Public ReadOnly Property TopicId As Integer
  Public ReadOnly Property TopicName As String
  Public Property ReturnCode As Integer
End Class

Remarks

A gateway sends a REGISTER packet to a client if it wants to inform that client about the topic name and the assigned topic id that it will use later on when sending PUBLISH messages of the corresponding topic name. The client must establish a new topic id mapping to the topic name indicated.

This happens for example when the client connects without starting a clean session or the client has subscribed to topic names that contain wildcard characters.

When a REGISTER packet is received, the component will respond with a REGACK packet. To set the value of the return code contained in the packet, set it to one of the below values.

  • 0: accepted
  • 1: rejected - congestion
  • 2: rejected - invalid topic id
  • 3: rejected - not supported

When a client subscribes to a topic with wildcard characters, the specific topic names it will receive messages on have not yet been registered to topic ids, so the first step in receiving such messages is the REGISTER packet. It can then receive incoming messages with that id. See MessageIn for more.

Config Settings (MQTTSN Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

MQTTSN Config Settings

ConnectionTimeout:   How long to wait for a connection attempt to succeed.

This setting controls how long the component will wait, in seconds, for connection attempt to succeed before timing out. The default is 60 seconds.

Duplicate:   Whether to set the Duplicate flag when publishing a message.

When enabled, the component will set the Duplicate flag when a message is published using PublishData or PublishMessage. See those methods for details on retransmission.

LogLevel:   The level of detail that is logged.

This setting controls the level of detail that is logged through the Log event. Possible values are:

0 (None) No events are logged.
1 (Info - default) Informational events are logged.
2 (Verbose) Detailed data is logged.
3 (Debug) Debug data is logged.

PingTimeout:   Length of time to wait for a PINGRESP packet.

This setting controls how long the component will wait, in seconds, for a response to a ping message before timing out. The default is 5 seconds.

Retain:   Whether to set the Retain flag when publishing a message.

When enabled, the component will set the Retain flag when a message is published using PublishData or PublishMessage. By default, this is disabled.

Publishing a non-empty message with the Retain flag set and a non-zero QoS will cause the server to store it (replacing any previously retained message in the process) so that it can be delivered to any clients which subscribe to the topic in the future. (If the QoS is 0, the server can store the message, but it is not required to do so indefinitely, if at all.)

If the component publishes an empty message with the Retain flag set, then (regardless of its QoS) the server will remove any previously retained message for the topic.

Note that messages with the Retain flag set are still processed by the server and delivered as usual to clients currently subscribed to the topic, regardless of whether they are empty or not. Also note that retained messages are not part of a session's state, they are retained until they are either removed or replaced by another retained message, regardless of whether or not the client connected with CleanSession set to True.

SubscribedTopicId:   Topic id assigned by the gateway when a topic name is used in a SUBSCRIBE message.

When the client uses a TopicIdType of 0 (topic name), this name must be registered to a topic id. In this scenario, the topic id assigned will be included in the SUBACK message and will be set here when it is received.

See Subscribe for more details.

SubscribeDUP:   Whether to set the Duplicate flag when subscribe to a topic.

When enabled, the component will set the Duplicate flag when Subscribe is called. See that method for details on retransmission.

WillQOS:   The QoS value to use for the Will message.

If WillTopic is set to a non-empty string when Connect is called, this is the QoS value that will be used for the Will message; possible values are 0 (default), 1, and 2. (Note that this setting is ignored if WillTopic is empty.)

Refer to WillTopic for more information.

WillRetain:   Whether the server should retain the Will message after publishing it.

If WillTopic is set to a non-empty string when Connect is called, this determines whether or not the server will treat the Will message as retained. By default, this is disabled. (Note that this setting is ignored if WillTopic is empty.)

See Retain for general information about how retained messages are handled by the server.

Refer to WillTopic for more information.

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Tells the component whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).
  • Last Valid Build: The last valid build number for which the license will work.
MaskSensitive:   Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.

This setting only works on these components: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

UseInternalSecurityAPI:   Tells the component whether or not to use the system security libraries or an internal implementation.

When set to false, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments this is not desirable. To use a completely managed security implementation set this setting to true.

Setting this setting to true tells the component to use the internal implementation instead of using the system security libraries.

On Windows, this setting is set to false by default. On Linux/macOS, this setting is set to true by default.

If using the .NET Standard Library, this setting will be true on all platforms. The .NET Standard library does not support using the system security libraries.

Note: This setting is static. The value set is applicable to all components used in the application.

When this value is set the product's system DLL is no longer required as a reference, as all unmanaged code is stored in that file.

Trappable Errors (MQTTSN Component)

UDP Errors

104   UDP is already Active.
106   You cannot change the LocalPort while the component is Active.
107   You cannot change the LocalHost at this time. A connection is in progress.
109   The component must be Active for this operation.
112   Cannot change MaxPacketSize while the component is Active.
113   Cannot change ShareLocalPort option while the component is Active.
114   Cannot change RemoteHost when UseConnection is set and the component Active.
115   Cannot change RemotePort when UseConnection is set and the component is Active.
116   RemotePort can't be zero when UseConnection is set. Please specify a valid service port number.
117   Cannot change UseConnection while the component is Active.
118   Message can't be longer than MaxPacketSize.
119   Message too short.
434   Unable to convert string to selected CodePage

SSL Errors

270   Cannot load specified security library.
271   Cannot open certificate store.
272   Cannot find specified certificate.
273   Cannot acquire security credentials.
274   Cannot find certificate chain.
275   Cannot verify certificate chain.
276   Error during handshake.
280   Error verifying certificate.
281   Could not find client certificate.
282   Could not find server certificate.
283   Error encrypting data.
284   Error decrypting data.

TCP/IP Errors

10004   [10004] Interrupted system call.
10009   [10009] Bad file number.
10013   [10013] Access denied.
10014   [10014] Bad address.
10022   [10022] Invalid argument.
10024   [10024] Too many open files.
10035   [10035] Operation would block.
10036   [10036] Operation now in progress.
10037   [10037] Operation already in progress.
10038   [10038] Socket operation on non-socket.
10039   [10039] Destination address required.
10040   [10040] Message too long.
10041   [10041] Protocol wrong type for socket.
10042   [10042] Bad protocol option.
10043   [10043] Protocol not supported.
10044   [10044] Socket type not supported.
10045   [10045] Operation not supported on socket.
10046   [10046] Protocol family not supported.
10047   [10047] Address family not supported by protocol family.
10048   [10048] Address already in use.
10049   [10049] Can't assign requested address.
10050   [10050] Network is down.
10051   [10051] Network is unreachable.
10052   [10052] Net dropped connection or reset.
10053   [10053] Software caused connection abort.
10054   [10054] Connection reset by peer.
10055   [10055] No buffer space available.
10056   [10056] Socket is already connected.
10057   [10057] Socket is not connected.
10058   [10058] Can't send after socket shutdown.
10059   [10059] Too many references, can't splice.
10060   [10060] Connection timed out.
10061   [10061] Connection refused.
10062   [10062] Too many levels of symbolic links.
10063   [10063] File name too long.
10064   [10064] Host is down.
10065   [10065] No route to host.
10066   [10066] Directory not empty
10067   [10067] Too many processes.
10068   [10068] Too many users.
10069   [10069] Disc Quota Exceeded.
10070   [10070] Stale NFS file handle.
10071   [10071] Too many levels of remote in path.
10091   [10091] Network subsystem is unavailable.
10092   [10092] WINSOCK DLL Version out of range.
10093   [10093] Winsock not loaded yet.
11001   [11001] Host not found.
11002   [11002] Non-authoritative 'Host not found' (try again or check DNS setup).
11003   [11003] Non-recoverable errors: FORMERR, REFUSED, NOTIMP.
11004   [11004] Valid name, no data record (check DNS setup).