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";
my $value = mqtt_get "topic/here";
my @values = mqtt_get [ "topic/one", "topic/two" ];
# Object oriented (supports subscribing to topics)
use Net::MQTT::Simple;
my $mqtt = Net::MQTT::Simple->new("mosquitto.example.org");
my $value = $mqtt->get("topic/here");
my @values = $mqtt->get([ "topic/one", "topic/two" ]);
$mqtt->publish("topic/here" => "Message here");
$mqtt->retain( "topic/here" => "Message here");
$mqtt->subscribe("topic/here" => sub {
my ($topic, $message) = @_;
...
});
$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, retain, and mqtt_get will be exported, that will call the methods publish, retain, and get.
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.
login($username[, $password])
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
Note that any one topic should be used with subscribe, once, or get, but not multiple methods simultaneously.
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.
once(topic, handler)
Subscribes to a topic, and unsubscribes from that topic after the first message that matches the topic has been received and the handler has been called.
get(topics[, timeout])
Returns the first message received for one or more topics. Specifically useful when combined with retained messages.
When given a single topic (string), returns the single message.
When given multiple topics (reference to an array of strings), returns a reference to an array of messages in scalar context, or the messages themselves in list context.
The timeout is expressed in whole seconds and defaults to 1. The actual time waited may be up to 1 second longer than specified.
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.
- 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 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>