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.
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 the socket was no longer connected. 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 write data, 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, which mean that arguments for topic and message are Unicode text strings, not UTF-8 encoded binary data. Encoding and decoding is handled transparently within this module.
For you, this means that if you use any literal UTF-8 in your code, you need to use utf8;, and that if you read or write data on filehandles, you must inform Perl about this fact first (e.g. with binmode STDOUT, ":encoding(utf8)";.
LICENSE
Pick your favourite OSI approved license :)
http://www.opensource.org/licenses/alphabetical
AUTHOR
Juerd Waalboer <juerd@tnx.nl>