Zum Ende der Metadaten springen
Zum Anfang der Metadaten

LoxBerry Compatibility

This module is available starting with LoxBerry 1.4.1. If you use this module, set your lb_minimum version in your plugin.cfg.

Customized LoxBerry Module

This module is based on the original module Net::MQTT::Simple, but is an especially customized version for LoxBerry regarding to MQTT authentication and TLS support. For authentication, read the documentation in this wiki article. (thanks to Juerd, who implemented the enhancements on our demand).

The Net::MQTT::Simple library is an easy way to connect to an MQTT broker. 

In your plugin user interface, you need to allow users to configure the MQTT broker hostname/address and broker port, the username and the password. You should require LoxBerry's SecurePIN before transferring and displaying the broker credentials.

It is recommended to eval { }; the mqtt method calls to implement error handling on connection, authentication or subscription errors.


If you want it more easy and avoid to scamble around with broker address, broker port and credentials, you may try the MQTT Gateway - HTTP- und UDP-Interface (requires the MQTT Gateway plugin to be installed).

Publishing only

Use this example code, to connect only for publishing messages (with or without retain).

use Net::MQTT::Simple;

# Allow unencrypted connection with credentials
$ENV{MQTT_SIMPLE_ALLOW_INSECURE_LOGIN} = 1;

# Connect to broker
my $mqtt = Net::MQTT::Simple->new('localhost:1883');

# Depending if authentication is required, login to the broker
if($mqtt_username and $mqtt_password) {
	$mqtt->login($mqtt_username, $mqtt_password);
}

# Publish a message
$mqtt->publish("loxberry/myplugin/temperature", "26.5");

# Publish a message with retain flag
$mqtt->retain("loxberry/myplugin/temperature", "26.5");

$mqtt->disconnect();


Subscribe and listen to topics

Only wait for messages (blocking)

This example subscribes to a topic, and then only waits for a message to arrive. It is blocking.

use Net::MQTT::Simple;

# Allow unencrypted connection with credentials
$ENV{MQTT_SIMPLE_ALLOW_INSECURE_LOGIN} = 1;

# Connect to broker
my $mqtt = Net::MQTT::Simple->new('localhost:1883');

# Depending if authentication is required, login to the broker
if($mqtt_username and $mqtt_password) {
	$mqtt->login($mqtt_username, $mqtt_password);
}

$mqtt->subscribe("loxberry/myplugin/command", \&received);

# This call blocks, and runs the callback, when a message arrives
$mqtt->run();

$mqtt->disconnect();

# This is the callback function, when a message arrives for the subscribed topic
sub received 
{
	my ($topic, $message) = @_;
	print STDERR "Incoming message on topic $topic is: $message\n";
}

Non-blocking subscriptions

With this example, the method ->tick is called, that checks for message. Inside of a loop, you can do other stuff in between.

use Net::MQTT::Simple;

# Allow unencrypted connection with credentials
$ENV{MQTT_SIMPLE_ALLOW_INSECURE_LOGIN} = 1;

# Connect to broker
my $mqtt = Net::MQTT::Simple->new('localhost:1883');

# Depending if authentication is required, login to the broker
if($mqtt_username and $mqtt_password) {
	$mqtt->login($mqtt_username, $mqtt_password);
}

$mqtt->subscribe("loxberry/myplugin/command", \&received);

while(1) {
	$mqtt->tick();

	# Now do other stuff
	sleep(1);
	
	# For fast response, use
	use Time::HiRes;
	Time::Hires::sleep(50/1000); # 50/1000 = 50ms
}

$mqtt->disconnect();

# This is the callback function, when a message arrives for the subscribed topic
sub received 
{
	my ($topic, $message) = @_;
	print STDERR "Incoming message on topic $topic is: $message\n";
}

Last Will and Testament (LWT)

To set LWT, set the LWT message after successfully connecting:

$mqtt->last_will("loxberry/myplugin/status", "Disconnected", 1);

The last will message is automatically sent by the broker, if the connection is lost, or your script dies (or is killed).

If the connection is cleanly closed by the $mqtt->disconnect() call, the LWT is not sent.

Best practices

  • eval { }; all the $mqtt calls for error handling.
  • If you use your own topic path, do not statically use "loxberry" as your base, but use the result of lbhostname() - this is an mqtt recommendation to use unique device names, and your plugin may conflict on multiple LoxBerry installations.
  • On an invalid subscription (e.g. syntax error), the broker immediately will disconnect your connection. 
  • The lib does an automatic reconnect. 
  • For further details on the lib, see Net::MQTT::Simple


  • Keine Stichwörter