MqttWebsocketsApi Class Reference

Public Member Functions
	constructor (api_conf)
	Constructor. More...
async	query (cmd, value=true)
	Send a cmd-value query to the message broker and resolve with the response. More...
	send (cmd, value=true)
	Send a command to the broker without expecting return data. More...
async	reconnect ()
	Disconnect followed by reconnection to MQTT broker. More...
	connect ()
	Connect to confitured MQTT broker. More...
	disconnect ()
	Disconnect from MQTT broker. More...
	register_data_cb (data_subtopic, cb)
	Add a generic callback for messages arriving on {data_topic}. More...
	remove_data_cb (data_subtopic, cb_id)
	Remove callback for data topic. More...
	register_cmd_resp_cb (cmd_name, cb)
	Add a callback for a single command response. More...
	remove_cmd_resp_cb (cmd_name, cb_id)
	Remove callback for command response topic. More...
	register_on_connected_cb (cb)
	Register callback executed when connected to MQTT broker. More...
	register_on_connection_lost_cb (cb)
	Register callback executed when MQTT connection is lost. More...

Detailed Description

Async Query-Response Web API using MQTT over Websockets

See also Paho MQTT Javascript client documentation at: https://www.eclipse.org/paho/files/jsdoc/Paho.MQTT.Client.html

MQTT host/connection and channel/topic setup:

All settings are configured by passing a mandatory configuration object to the constructor, with the following fields:

const api_conf = {
    hosts: ["picalor.local", "169.254.207.204"],
    ports: [9001, 9001],
    path: "/mqtt",
    useSSL: false,
    timeout: 15,
    data_topic: "data/picalor/core",
    cmd_req_topic: "cmd/picalor/core/req",
    cmd_resp_topic: "cmd/picalor/core/resp",
    id_prefix: "picalor_gui_",
};

• Requests are sent using the command name as endpoint: "{cmd_req_topic}/{cmd-name}"
  Example topic for requests: "cmd/picalor/core/req/{cmd-name}"
• Responses arrive under an "ok" or "err" subtopic for success or failure results: "{cmd_resp_topic}/ok/{cmd-name}" for command success responses and "{cmd_resp_topic}/err/{cmd-name}" for command error responses.
  Example topic for responses: "cmd/picalor/core/resp/ok/{cmd-name}"
• For async or streaming results like telemetry data, callbacks can be registered on the data_topic channel, extended with a data subkey as endpoint: "{data_topic}/{data-key}"
  Example topic for telemetry data: "data/picalor/core/{data-key}"

Ulrich Lukas 2022-11-11

Member Function Documentation

connect()

MqttWebsocketsApi::connect ( )

inline

Connect to confitured MQTT broker.

Returns

Promise resolving with an array of all subscribed topics

constructor()

MqttWebsocketsApi::constructor (   api_conf )

inline

Constructor.

Parameters

api_conf

See class documentation for structure of the api_conf object

disconnect()

MqttWebsocketsApi::disconnect ( )

inline

Disconnect from MQTT broker.

Here, we do not want to trigger reconnects, so this does not reject or raise exceptions and error callbacks are not called.

Returns

Promise with empty resolution

query()

async MqttWebsocketsApi::query (   cmd,   value = true  )

inline

Send a cmd-value query to the message broker and resolve with the response.

The query is published on the {cmd_req_topic}/{cmd-name} topic, with a payload consisting of the value argument as a JSON string.

Each query is supposed to be answered or acknowledged with a response on the topic channel, i.e: {cmd_resp_topic}/ok/{cmd-name} or {cmd_resp_topic}/err/{cmd-name}.

The response is supposed to contain a non-empty JSON string as payload.

Parameters

cmd	String name of the command
value	Any Javascript object which can be sent as a JSON string

Returns

Promise resolving with the payload parsed as a Javascript object

reconnect()

async MqttWebsocketsApi::reconnect ( )

inline

Disconnect followed by reconnection to MQTT broker.

Returns

Promise resolving with an array of all subscribed topics

register_cmd_resp_cb()

MqttWebsocketsApi::register_cmd_resp_cb (   cmd_name,   cb  )

inline

Add a callback for a single command response.

Multiple callbacks can be registered for any data topic, these are identified by a numeric ID, which is only valid for the cmd_resp_cb registry.

Parameters

cmd_name	String name of the command. Used as topic endpoint.
cb	Callback function. Signature is: cmd_resp_cb(success, value)

Returns

Callback id number

register_data_cb()

MqttWebsocketsApi::register_data_cb (   data_subtopic,   cb  )

inline

Add a generic callback for messages arriving on {data_topic}.

Multiple callbacks can be registered for any data topic, these are identified by a numeric ID, which is only valid for the data_cb registry.

Parameters

data_subtopic	String key value identifying the data. Used as topic endpoint.
cb	Callback function. Signature is: data_cb(value)

Returns

Callback ID number (needed to un-register the cb)

register_on_connected_cb()

MqttWebsocketsApi::register_on_connected_cb (   cb )

inline

Register callback executed when connected to MQTT broker.

Parameters

cb	Callback function, called without arguments

Returns

Callback id number

register_on_connection_lost_cb()

MqttWebsocketsApi::register_on_connection_lost_cb (   cb )

inline

Register callback executed when MQTT connection is lost.

Parameters

cb	Callback function, called without arguments

Returns

Callback id number

remove_cmd_resp_cb()

MqttWebsocketsApi::remove_cmd_resp_cb (   cmd_name,   cb_id  )

inline

Remove callback for command response topic.

Parameters

cmd_name	String name as used for registration of the CB
cb_id	Callback ID number as returned by register_cmd_resp_cb()

remove_data_cb()

MqttWebsocketsApi::remove_data_cb (   data_subtopic,   cb_id  )

inline

Remove callback for data topic.

Parameters

data_subtopic	String key value as used for registration of the CB
cb_id	Callback ID number as returned by register_data_cb()

send()

MqttWebsocketsApi::send (   cmd,   value = true  )

inline

Send a command to the broker without expecting return data.

Parameters

cmd	String name of the command
value	Any Javascript object which can be sent as a JSON string

---

The documentation for this class was generated from the following file:

• src/api/mqtt_websockets_api.js