MQTT KEKW

MQTT Kekw is a Node.js MQTT TCP client.

Example usage

Install

npm i @mqtt-kekw/tcp-client

Use

const { kekwClient } = require("@mqtt-kekw/tcp-client");

const client = new kekwClient(
  { hostAddress: "localhost", port: 1883 },
  (message) => {
    console.log("Connection Failed", message);
  }
);

Client Props

hostAddress

• Type: string
• Default: localhost
• Description: Broker address

port

• Type: number
• Default: 1883
• Description: Broker port

timeout

• Type: number
• Default: 5000
• Description: Timeout in ms. If no broker response within this time, client will destroy its connection.

onFailure

• Type: function (optional)
• Description: Callback function. Called after timeout.

Sending connection packet

Send connection packet after TCP connection is ready

Example usage

client.on("ready", () => {
  console.log("Client Ready !!");
  client.connectionUp({
    clientID: "MQTT_CLIENT",
  });
});

connectionUp

• Type: function

• Description: Sends a Connection packet to the broker

• Arguments:

• flags (optional):

• Type: object

• Description: Consists of following

  Name	Type	Description
  username	string	If username exists, it will be present in the payload
  password	string	If password exists, it will be present in the payload
  willFlag	boolean	...more
  willQoS_1	number	...more
  willQoS_2	number	...more
  willRetain	boolean	...more
  cleanSession	boolean	If cleanSession is set to 0, resume communications with the client based on state from the current Session

• clientID (optional):

• Type: string

• Description: Client Identifier string. Part of the payload packet

• keepAlive (optional)::

• Type: object

• Description: How much longer should connection stay open between client and broker. Keep in mind that mosquitto broker adds +15 seconds to keepAlive

  Name	Type	Description
  hours	number	hours in number (0-23)
  minutes	number	minutes in number (0-60)
  seconds	number	seconds in number (0-60)

• will:

• Type: object

• Description: Specify will topic and will message if willFlag is set to true

  Name	Type	Description
  willTopic	string	Will Topic
  willMessage	string	Will Message

Emitted events

Events emitted with Node.js EventEmitter class. All events are created by following Oasis spesification @Docs-Oasis

Event Name	Description	Args & Types
connect	TCP connection starts	---
ready	TCP connection ready	---
close	TCP connection closed	hadError: boolean
end	TCP connection ended	---
error	TCP connection error	error: Error
timeout	TCP timeout	---
connectionAccepted	Connection acknowledged by the Broker	{returnCode: string, message: string}
connectionRefused	Connection did not acknowledged by the Broker	{returnCode: string, message: string}
pingresp	Broker pinged back	message:string
suback	Subscribe acknowledged by the Broker	{returnCodes: any[], packetID: number[]}
unsuback	Unsubscribe acknowledged by the Broker	{packetID: number[]}
puback	Publish acknowledged by the Broker(QoS = 1, At least once delivery)	{packetID: number[]}
pubrec	Publish acknowledged by the Broker(QoS = 2, At most once delivery)	{packetID: number[]}
received	Message from the Broker received	{topic: string, payload: string}

Functions

• ping

  client.ping();

  Description: Sends a ping packet to the broker. pingresp should be triggered after client receives a ping back data packet.

• disconnect

  client.disconnect();

  Description: Sends a disconnect packet to the broker. Client closes it's connection after receiving disconnect acknowledgement packet.

• subscribeTo({topic,requestedQoS})

  Description: Sends a subscribe packet to the broker with topic or topics and requestedQoS. Client should receive suback packet.

  Arguments:

  topic:

  • Type: string | string[]
  • Description: Topic can be a string or a array of strings. Payload calculated accordingly

  requestedQoS:

  • Type: number (either 0 or 1)
  • Description: Requested QoS.(more later)

  client.subscribeTo({
    topic: "home/+/humidity",
    requestedQoS: 0,
  });

• unsubscribeFrom({topic,requestedQoS})

  Description: Sends an unsubscribe packet to the broker with topic or topics and requestedQoS. Client should receive unsuback packet.

  Arguments:

  topic:

  • Type: string | string[]
  • Description: Topic can be a string or a array of strings. Payload calculated accordingly

  packetIdentifier:

  • Type: number[]
  • Description: Packet identifier should be same as the packet identifier that client received in suback event

  client.unsubscribeFrom({
    topic: "home/+/humidity",
    packetIdentifier,
  });

• publishTo({topic,message,dupFlag,QoS1,QoS2,retain})

  Description: Sends a publish packet to the broker with necessarry arguments. Client should received puback or pubrec accordingly.

  Arguments:

  topic:

  • Type: string
  • Description: Topic is a string. Defines which topic that message will be published to

  message:

  • Type: string
  • Description: Message data with the related topic

  dupFlag:

  • Type: number
  • Description: Duplication flag should be set to 0 if it's first occasion. If it's a duplication, it should be set to 1

  QoS1:

  • Type: number
  • Description: ...

  QoS2:

  • Type: number
  • Description: ...

  retain:

  • Type: number
  • Description: ...

  client.unsubscribeFrom({
    topic: "home",
    packetIdentifier,
  });

Subscribe & Unsubscribe Example

Single-Level Wildcard '+'

Example topics

• home/room1/temperature
• home/room2/temperature
• home/room3/temperature

Example usage Subscribe to all topics with home/${any_topic}/temperature format

client.subscribeTo({
  topic: "home/+/temperature",
  //requestedQoS: 0,
});

If you want to unsubscribe from a single level wildcard

client.unsubscribeFrom({
  topic: "home/+/temperature",
  //requestedQoS: 0,
});

Multi-Level Wildcard '#'

Example topics

• home/room1/temperature
• home/room1/humidity
• home/room1/voltage

Example usage

Subscribe to all topics with home/room1/${any_topic} format

client.subscribeTo({
  topic: "home/room1/#",
  //requestedQoS: 0,
});

If you want to unsubscribe from a multi level wildcard

client.unsubscribeFrom({
  topic: "home/room1/#",
  //requestedQoS: 0,
});

Subscribe to multiple topics

client.subscribeTo({
  topic: ["home/room1/temperature", "home/room1/temperature"],
  //requestedQoS: 0,
});

Unsubscribe from multiple topics

client.unsubscribeFrom({
  topic: ["home/room1/temperature", "home/room1/temperature"],
  //packetIdentifier here
});