NAME

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

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 multiple servers)

    use Net::MQTT::Simple;

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

    for my $server ($mqtt1, $mqtt2) {
        $server->publish("topic/here" => "Message here");
        $server->retain( "topic/here" => "Message here");
    }

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 the most basic MQTT publishing functionality is supported; 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.

Functional interface

This will suffice for most simple sensor scripts. A socket is kept open for reuse until the script has finished.

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

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.

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

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, encryption

No username and password are sent to the server and the connection will be set up without TLS or SSL.

Subscriptions

This is a write-only implementation, meant for sensor equipment.

Last will

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

Keep-alives

You'll have to wait for the TCP timeout instead.

LICENSE

Pick your favourite OSI approved license :)

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

AUTHOR

Juerd Waalboer <juerd@tnx.nl>

SEE ALSO

Net::MQTT

cpanm Net::MQTT::Simple

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