IPWorks IoT 2020 JavaScript Edition

Questions / Feedback?

PublishMessage Method

Publishes a message with a string payload.

Syntax

async mqttsn.publishMessage(topicId : string, topicIdType : number, QOS : number, message : string): Promise<void>

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 JavaScript Edition - Version 20.0 [Build 8265]