IPWorks IoT 2020 Node.js Edition

Questions / Feedback?

PublishMessage Method

Publishes a message with a string payload.

Syntax

mqttsn.publishMessage(topicId, topicIdType, QOS, message, [callback])

Callback

The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).

The callback for this method is defined as:

function(err){ }

'err' is the error that occurred. If there was no error, then 'err' is 'null'.

'err' has 2 properties which hold detailed information:

err.code
err.message

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 class 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.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks IoT 2020 Node.js Edition - Version 20.0 [Build 8265]