Ubuntu Manpage: Net::MQTT::Simple - Minimal MQTT version 3 interface

Provided by: libnet-mqtt-simple-perl_1.29-2_all

NAME

       Net::MQTT::Simple - Minimal MQTT version 3 interface

SYNOPSIS

           # One-liner that publishes sensor values from STDIN

           perl -MNet::MQTT::Simple=mosquitto.example.org \
                -nle'retain "topic/here" => $_'

           # Functional (single server only)

           use Net::MQTT::Simple "mosquitto.example.org";

           publish "topic/here" => "Message here";
           retain  "topic/here" => "Retained message here";

           # Object oriented (supports subscribing to topics)

           use Net::MQTT::Simple;

           my $mqtt = Net::MQTT::Simple->new("mosquitto.example.org");

           $mqtt->publish("topic/here" => "Message here");
           $mqtt->retain( "topic/here" => "Message here");

           $mqtt->run(
               "sensors/+/temperature" => sub {
                   my ($topic, $message) = @_;
                   die "The building's on fire" if $message > 150;
               },
               "#" => sub {
                   my ($topic, $message) = @_;
                   print "[$topic] $message\n";
               },
           );

DESCRIPTION

This module consists of only one file and has no dependencies except core Perl modules,
making it suitable for embedded installations where CPAN installers are unavailable and
resources are limited.

Only basic MQTT functionality is provided; if you need more, you'll have to use the full-
featured Net::MQTT instead.

Connections are set up on demand, automatically reconnecting to the server if a previous
connection had been lost.

Because sensor scripts often run unattended, connection failures will result in warnings
(on STDERR if you didn't override that) without throwing an exception.

Please refer to Net::MQTT::Simple::SSL for more information about encrypted and
authenticated connections.

Functional interface
This will suffice for most simple sensor scripts. A socket is kept open for reuse until
the script has finished. The functional interface cannot be used for subscriptions, only
for publishing.

Instead of requesting symbols to be imported, provide the MQTT server on the "use
Net::MQTT::Simple" line. A non-standard port can be specified with a colon. The functions
"publish" and "retain" will be exported.

Object oriented interface
new(server[, sockopts])

Specify the server (possibly with a colon and port number) to the constructor,
"Net::MQTT::Simple->new". The socket is disconnected when the object goes out of scope.

Optionally, a reference to a hash of socket options can be passed. Options specified in
this hash are passed on to the socket constructor.

last_will([$topic, $message[, $retain]])

Set a "Last Will and Testament", to be used on subsequent connections. Note that the last
will cannot be updated for a connection that is already established.

A last will is a message that is published by the broker on behalf of the client, if the
connection is dropped without an explicit call to "disconnect".

Without arguments, returns the current values without changing the active configuration.

When the given topic and message are both undef, the last will is deconfigured. In other
cases, only arguments which are "defined" are updated with the given value. For the first
setting, the topic is mandatory, the message defaults to an empty string, and the retain
flag defaults to false.

Returns a list of the three values in the same order as the arguments.

Sets authentication credentials, to be used on subsequent connections. Note that the
credentials cannot be updated for a connection that is already established.

The username is text, the password is binary.

See Net::MQTT::Simple::SSL for information about secure connections. To enable insecure
password authenticated connections, set the environment variable
MQTT_SIMPLE_ALLOW_INSECURE_LOGIN to a true value.

Returns the username.

DISCONNECTING GRACEFULLY

   disconnect
       Performs a graceful disconnect, which ensures that the server does NOT send the registered
       "Last Will" message.

       Subsequent calls that require a connection, will cause a new connection to be set up.

PUBLISHING MESSAGES

       The two methods for publishing messages are the same, except for the state of the "retain"
       flag.

   retain(topic, message)
       Publish the message with the "retain" flag on. Use this for sensor values or anything else
       where the message indicates the current status of something.

       To discard a retained topic, provide an empty or undefined message.

   publish(topic, message)
       Publishes the message with the "retain" flag off. Use this for ephemeral messages about
       events that occur (like that a button was pressed).

SUBSCRIPTIONS

   subscribe(topic, handler[, topic, handler, ...])
       Subscribes to the given topic(s) and registers the callbacks. Note that only the first
       matching handler will be called for every message, even if filter patterns overlap.

   unsubscribe(topic[, topic, ...])
       Unsubscribes from the given topic(s) and unregisters the corresponding callbacks. The
       given topics must exactly match topics that were previously used with the "subscribe"
       method.

   run(...)
       Enters an infinite loop, which calls "tick" repeatedly. If any arguments are given, they
       will be passed to "subscribe" first.

   tick(timeout)
       Test the socket to see if there's any incoming message, waiting at most timeout seconds
       (can be fractional). Use a timeout of 0 to avoid blocking, but note that blocking
       automatic reconnection may take place, which may take much longer.

       If "tick" returns false, this means that the socket was no longer connected and that the
       next call will cause a reconnection attempt. However, a true value does not necessarily
       mean that the socket is still functional. The only way to reliably determine that a TCP
       stream is still connected, is to actually communicate with the server, e.g. with a ping,
       which is only done periodically.

UTILITY FUNCTIONS

   Net::MQTT::Simple::filter_as_regex(topic_filter)
       Given a valid MQTT topic filter, returns the corresponding regular expression.

IPv6 PREREQUISITE

       For IPv6 support, the module IO::Socket::IP needs to be installed. It comes with Perl 5.20
       and is available from CPAN for older Perls. If this module is not available, the older
       IO::Socket::INET will be used, which only supports Legacy IP (IPv4).

MANUAL INSTALLATION

       If you can't use the CPAN installer, you can actually install this module by creating a
       directory "Net/MQTT" and putting "Simple.pm" in it. Please note that this method does not
       work for every Perl module and should be used only as a last resort on systems where
       proper installers are not available.

       To view the list of @INC paths where Perl searches for modules, run "perl -V". This list
       includes the current working directory ("."). Additional include paths can be specified in
       the "PERL5LIB" environment variable; see perlenv.

NOT SUPPORTED

       QoS (Quality of Service)
           Every message is published at QoS level 0, that is, "at most once", also known as
           "fire and forget".

       DUP (Duplicate message)
           Since QoS is not supported, no retransmissions are done, and no message will indicate
           that it has already been sent before.

       Authentication
           No username and password are sent to the server.

       Large data
           Because everything is handled in memory and there's no way to indicate to the server
           that large messages are not desired, the connection is dropped as soon as the server
           announces a packet larger than 2 megabytes.

       Validation of server-to-client communication
           The MQTT spec prescribes mandatory validation of all incoming data, and disconnecting
           if anything (really, anything) is wrong with it. However, this minimal implementation
           silently ignores anything it doesn't specifically handle, which may result in weird
           behaviour if the server sends out bad data.

           Most clients do not adhere to this part of the specifications.

CAVEATS

Automatic reconnection
Connection and reconnection are handled automatically, but without retries. If anything
goes wrong, this will cause a single reconnection attempt before the following action. For
example, if sending a message fails because of a disconnected socket, the message will not
be resent, but the next message might succeed. Only one new connection attempt is done per
approximately 5 seconds. This behaviour is intended.

Unicode
This module uses the proper Perl Unicode abstractions for parts that according to the MQTT
specification are UTF-8 encoded. This includes topics, but not messages. Published
messages are binary data, which you may have to encode and decode yourself.

This means that if you have UTF-8 encoded string literals in your code, you should "use
utf8;" and that any of those strings which is a message will need to be encoded by you,
for example with "utf8::encode($message);".

It also means that a message should never contain any character with an ordinal value of
greater than 255, because those cannot be used in binary communication. If you're passing
non-ASCII text strings, encode them before publishing, decode them after receiving. A
character greater than 255 results in a warning

Wide character in publish at yourfile.pl line 42.

while the UTF-8 encoded data is passed through. To get rid of the warning, use
"utf8::encode($message);".

LICENSE

       This software may be redistributed under the terms of the GPL, LGPL, modified BSD, or
       Artistic license, or any of the other OSI approved licenses listed at
       http://www.opensource.org/licenses/alphabetical. Distribution is allowed under all of
       these these licenses, or any smaller subset of multiple or just one of these licenses.

       When using a packaged version, please refer to the package metadata to see under which
       license terms it was distributed. Alternatively, a distributor may choose to replace the
       LICENSE section of the documentation and/or include a LICENSE file to reflect the
       license(s) they chose to redistribute under.

AUTHOR

       Juerd Waalboer <juerd@tnx.nl>