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.

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.

Last will

The server won't publish a "last will" message on behalf of us when our connection's gone.

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

Pick your favourite OSI approved license :)

http://www.opensource.org/licenses/alphabetical

AUTHOR

Juerd Waalboer <juerd@tnx.nl>

SEE ALSO

Net::MQTT, Net::MQTT::Simple::SSL

cpanm Net::MQTT::Simple

perl -MCPAN -e shell
install Net::MQTT::Simple