.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::MQTT::Simple 3pm"
.TH Net::MQTT::Simple 3pm "2023-10-30" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::MQTT::Simple \- Minimal MQTT version 3 interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # One\-liner that publishes sensor values from STDIN
\&
\&    perl \-MNet::MQTT::Simple=mosquitto.example.org \e
\&         \-nle\*(Aqretain "topic/here" => $_\*(Aq
\&
\&
\&    # 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\*(Aqs on fire" if $message > 150;
\&        },
\&        "#" => sub {
\&            my ($topic, $message) = @_;
\&            print "[$topic] $message\en";
\&        },
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module consists of only one file and has no dependencies except core Perl
modules, making it suitable for embedded installations where \s-1CPAN\s0 installers
are unavailable and resources are limited.
.PP
Only basic \s-1MQTT\s0 functionality is provided; if you need more, you'll have to
use the full-featured Net::MQTT instead.
.PP
Connections are set up on demand, automatically reconnecting to the server if a
previous connection had been lost.
.PP
Because sensor scripts often run unattended, connection failures will result in
warnings (on \s-1STDERR\s0 if you didn't override that) without throwing an exception.
.PP
Please refer to Net::MQTT::Simple::SSL for more information about encrypted
and authenticated connections.
.SS "Functional interface"
.IX Subsection "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.
.PP
Instead of requesting symbols to be imported, provide the \s-1MQTT\s0 server on the
\&\f(CW\*(C`use Net::MQTT::Simple\*(C'\fR line. A non-standard port can be specified with a
colon. The functions \f(CW\*(C`publish\*(C'\fR and \f(CW\*(C`retain\*(C'\fR will be exported.
.SS "Object oriented interface"
.IX Subsection "Object oriented interface"
\fInew(server[, sockopts])\fR
.IX Subsection "new(server[, sockopts])"
.PP
Specify the server (possibly with a colon and port number) to the constructor,
\&\f(CW\*(C`Net::MQTT::Simple\->new\*(C'\fR. The socket is disconnected when the object goes
out of scope.
.PP
Optionally, a reference to a hash of socket options can be passed. Options
specified in this hash are passed on to the socket constructor.
.PP
\fIlast_will([$topic, \f(CI$message\fI[, \f(CI$retain\fI]])\fR
.IX Subsection "last_will([$topic, $message[, $retain]])"
.PP
Set a \*(L"Last Will and Testament\*(R", to be used on subsequent connections. Note
that the last will cannot be updated for a connection that is already
established.
.PP
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 \f(CW\*(C`disconnect\*(C'\fR.
.PP
Without arguments, returns the current values without changing the
active configuration.
.PP
When the given topic and message are both undef, the last will is deconfigured.
In other cases, only arguments which are \f(CW\*(C`defined\*(C'\fR 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.
.PP
Returns a list of the three values in the same order as the arguments.
.PP
\fIlogin($username[, \f(CI$password\fI])\fR
.IX Subsection "login($username[, $password])"
.PP
Sets authentication credentials, to be used on subsequent connections. Note
that the credentials cannot be updated for a connection that is already
established.
.PP
The username is text, the password is binary.
.PP
See Net::MQTT::Simple::SSL for information about secure connections. To
enable insecure password authenticated connections, set the environment
variable \s-1MQTT_SIMPLE_ALLOW_INSECURE_LOGIN\s0 to a true value.
.PP
Returns the username.
.SH "DISCONNECTING GRACEFULLY"
.IX Header "DISCONNECTING GRACEFULLY"
.SS "disconnect"
.IX Subsection "disconnect"
Performs a graceful disconnect, which ensures that the server does \s-1NOT\s0 send
the registered \*(L"Last Will\*(R" message.
.PP
Subsequent calls that require a connection, will cause a new connection to be
set up.
.SH "PUBLISHING MESSAGES"
.IX Header "PUBLISHING MESSAGES"
The two methods for publishing messages are the same, except for the state of
the \f(CW\*(C`retain\*(C'\fR flag.
.SS "retain(topic, message)"
.IX Subsection "retain(topic, message)"
Publish the message with the \f(CW\*(C`retain\*(C'\fR flag on. Use this for sensor values or
anything else where the message indicates the current status of something.
.PP
To discard a retained topic, provide an empty or undefined message.
.SS "publish(topic, message)"
.IX Subsection "publish(topic, message)"
Publishes the message with the \f(CW\*(C`retain\*(C'\fR flag off. Use this for ephemeral
messages about events that occur (like that a button was pressed).
.SH "SUBSCRIPTIONS"
.IX Header "SUBSCRIPTIONS"
.SS "subscribe(topic, handler[, topic, handler, ...])"
.IX Subsection "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.
.SS "unsubscribe(topic[, topic, ...])"
.IX Subsection "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 \f(CW\*(C`subscribe\*(C'\fR method.
.SS "run(...)"
.IX Subsection "run(...)"
Enters an infinite loop, which calls \f(CW\*(C`tick\*(C'\fR repeatedly. If any arguments
are given, they will be passed to \f(CW\*(C`subscribe\*(C'\fR first.
.SS "tick(timeout)"
.IX Subsection "tick(timeout)"
Test the socket to see if there's any incoming message, waiting at most
\&\fItimeout\fR seconds (can be fractional). Use a timeout of \f(CW0\fR to avoid
blocking, but note that blocking automatic reconnection may take place, which
may take much longer.
.PP
If \f(CW\*(C`tick\*(C'\fR 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 \s-1TCP\s0 stream is still connected, is to actually
communicate with the server, e.g. with a ping, which is only done periodically.
.SH "UTILITY FUNCTIONS"
.IX Header "UTILITY FUNCTIONS"
.SS "Net::MQTT::Simple::filter_as_regex(topic_filter)"
.IX Subsection "Net::MQTT::Simple::filter_as_regex(topic_filter)"
Given a valid \s-1MQTT\s0 topic filter, returns the corresponding regular expression.
.SH "IPv6 PREREQUISITE"
.IX Header "IPv6 PREREQUISITE"
For IPv6 support, the module IO::Socket::IP needs to be installed. It comes
with Perl 5.20 and is available from \s-1CPAN\s0 for older Perls. If this module is
not available, the older IO::Socket::INET will be used, which only supports
Legacy \s-1IP\s0 (IPv4).
.SH "MANUAL INSTALLATION"
.IX Header "MANUAL INSTALLATION"
If you can't use the \s-1CPAN\s0 installer, you can actually install this module by
creating a directory \f(CW\*(C`Net/MQTT\*(C'\fR and putting \f(CW\*(C`Simple.pm\*(C'\fR 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.
.PP
To view the list of \f(CW@INC\fR paths where Perl searches for modules, run \f(CW\*(C`perl
\&\-V\*(C'\fR. This list includes the current working directory (\f(CW\*(C`.\*(C'\fR). Additional
include paths can be specified in the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable; see
perlenv.
.SH "NOT SUPPORTED"
.IX Header "NOT SUPPORTED"
.IP "QoS (Quality of Service)" 4
.IX Item "QoS (Quality of Service)"
Every message is published at QoS level 0, that is, \*(L"at most once\*(R", also known
as \*(L"fire and forget\*(R".
.IP "\s-1DUP\s0 (Duplicate message)" 4
.IX Item "DUP (Duplicate message)"
Since QoS is not supported, no retransmissions are done, and no message will
indicate that it has already been sent before.
.IP "Authentication" 4
.IX Item "Authentication"
No username and password are sent to the server.
.IP "Large data" 4
.IX Item "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.
.IP "Validation of server-to-client communication" 4
.IX Item "Validation of server-to-client communication"
The \s-1MQTT\s0 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.
.Sp
Most clients do not adhere to this part of the specifications.
.SH "CAVEATS"
.IX Header "CAVEATS"
.SS "Automatic reconnection"
.IX Subsection "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.
.SS "Unicode"
.IX Subsection "Unicode"
This module uses the proper Perl Unicode abstractions for parts that according
to the \s-1MQTT\s0 specification are \s-1UTF\-8\s0 encoded. This includes \fItopic\fRs, but not
\&\fImessage\fRs. Published messages are binary data, which you may have to encode
and decode yourself.
.PP
This means that if you have \s-1UTF\-8\s0 encoded string literals in your code, you
should \f(CW\*(C`use utf8;\*(C'\fR and that any of those strings which is a \fImessage\fR will
need to be encoded by you, for example with \f(CW\*(C`utf8::encode($message);\*(C'\fR.
.PP
It also means that a \fImessage\fR 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
.PP
.Vb 1
\&    Wide character in publish at yourfile.pl line 42.
.Ve
.PP
while the \s-1UTF\-8\s0 encoded data is passed through. To get rid of the warning, use
\&\f(CW\*(C`utf8::encode($message);\*(C'\fR.
.SH "LICENSE"
.IX Header "LICENSE"
This software may be redistributed under the terms of the \s-1GPL, LGPL,\s0 modified
\&\s-1BSD,\s0 or Artistic license, or any of the other \s-1OSI\s0 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.
.PP
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 \s-1LICENSE\s0 section of the documentation and/or include a
\&\s-1LICENSE\s0 file to reflect the license(s) they chose to redistribute under.
.SH "AUTHOR"
.IX Header "AUTHOR"
Juerd Waalboer <juerd@tnx.nl>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::MQTT, Net::MQTT::Simple::SSL