Perl Modul Net::MQTT::Simple

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).

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();

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";
}

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";
}

If you only want to get a message from a topic once, you have to use a temporarely subscription. Getting a message once isn't implemented in MQTT (in fact MQTT does only know full subscriptions). Note that this only works for topics with the retained flag set!

use Net::MQTT::Simple;
use Time::HiRes qw ( sleep );
 
# 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->retain("loxberry/myplugin/temperature", "26.5");
 
my $received = 0;
my $value;
$mqtt->subscribe("loxberry/myplugin/temperature", \&received);
# Wait a maximum of 1 sec.
for (my $i = 0; $i < 10; $i++) {
    last if ($received);
    $mqtt->tick();
    sleep (0.1);
}
$mqtt->unsubscribe("loxberry/myplugin/temperature");
 
print "The message I have received is: $value\n";
 
$mqtt->disconnect();
exit;
 
# This is the callback function, when a message arrives for the subscribed topic
sub received 
{
    $received = 1;
    my ($topic, $message) = @_;
    print STDERR "Incoming message on topic $topic is: $message\n";
    $value = $message if ($message);
}

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.

• 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