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>