Home

Awesome

Logo

ioBroker MQTT

Number of Installations Number of Installations NPM version

Test and Release Translation status Downloads

This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.

MQ Telemetry Transport for ioBroker (MQTT).

MQTT (formerly Message Queue Telemetry Transport) is a publish-subscribe based "light weight" messaging protocol for use on top of the TCP/IP protocol. It is designed for connections with remote locations where a "small code footprint" is required and/or network bandwidth is limited. The Publish-Subscribe messaging pattern requires a message broker. The broker is responsible for distributing messages to interested clients based on the topic of a message. Historically, the 'MQ' in 'MQTT' came from IBM's MQ message queuing product line.

This adapter uses the MQTT.js library from https://github.com/adamvr/MQTT.js/

Configuration

Server settings

The ioBroker MQTT-Broker in server mode only simulates the behavior of real MQTT-Broker (like Mosquitto), but it is not the same. Real MQTT-Broker normally does not save the values of the topics and just forwards the message to other subscribed clients.

To force real MQTT-Broker to behave like ioBroker MQTT-Broker, all messages must be sent with "retain" flag. In this case, the values will be stored too.

ioBroker MQTT-Broker always saves the values into the States-DB, so it can be processed by other adapters. Because of that, the messages are always published with a retain flag.

If your client has problems with retained messages, you can force ioBroker MQTT-Broker to send messages without a retain flag with Publish messages without "retain" flag option. In this case, the messages will be stored in States-DB anyway.

If the option Send states (ack=true) too is not activated, so you can clear the value of the topic (state) with ack=true and the update will not be sent to subscribed clients. And when the client connects next time, it will not get the last command again.

The JS-Code should look like this:

await setStateAsync('mqtt.0.valetudo.vale.BasicControlCapability.operation.set', 'cleanStart'); // ack=false
await setStateAsync('mqtt.0.valetudo.vale.BasicControlCapability.operation.set', '', true); // ack=true to clear the command

Client settings

Usage

How to test mqtt client:

Sending messages

You may send / publish messages on topics using sendTo method from your adapter via MQTT adapter, e.g.:

/*
 * @param {string}  MQTT instance     Specify MQTT instance to send message through (may be either server or client)
 * @param {string}  action            Action to use (always 'sendMessage2Client' for sending plain messages)
 * @param {object}  payload         
 * @param {string}  payload.topic     Topic to publish message on
 * @param {string}  payload.message   Message to be published on specified topic
 *
 */
adapter.sendTo('mqtt.0', 'sendMessage2Client', { topic: 'your/topic/here', message: 'your message', retain: true });

Examples of using wildcards

The following examples on the use of wildcards, builds on the example provided in topic strings.

If you want to subscribe to all Tennis topics, you can use the number sign '#', or the plus sign '+'.

For JMS topics, if you want to subscribe to all Finals topics, you can use the number sign '#', or the plus sign '+'.

For MQTT topics, if you want to subscribe to all Finals topics, you can use the plus sign '+'.

Sport/+/Finals

Binary messages

With version 4.x, there is a possibility to send and receive binary messages. Send works only with js-controller@4.2 or newer.

You can change manually the common.type of existing objects to file and they will be processed as binary states.

Or you can set the options All new topics will be processed as binary* in the instance settings to force all new topics will have automatically common.type="file".

Tests

The broker was tested with the following clients:

Todo

<!-- Placeholder for the next version (at the beginning of the line): ### **WORK IN PROGRESS** -->

Changelog

6.0.0 (2024-07-13)

5.2.0 (2024-01-08)

5.1.0 (2023-10-11)

5.0.0 (2023-09-18)

4.1.1 (2023-03-22)

License

The MIT License (MIT)

Copyright (c) 2014-2024, bluefox dogafox@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.