1Net::MQTT::Simple(3)  User Contributed Perl Documentation Net::MQTT::Simple(3)
2
3
4

NAME

6       Net::MQTT::Simple - Minimal MQTT version 3 interface
7

SYNOPSIS

9           # One-liner that publishes sensor values from STDIN
10
11           perl -MNet::MQTT::Simple=mosquitto.example.org \
12                -nle'retain "topic/here" => $_'
13
14
15           # Functional (single server only)
16
17           use Net::MQTT::Simple "mosquitto.example.org";
18
19           publish "topic/here" => "Message here";
20           retain  "topic/here" => "Retained message here";
21
22
23           # Object oriented (supports subscribing to topics)
24
25           use Net::MQTT::Simple;
26
27           my $mqtt = Net::MQTT::Simple->new("mosquitto.example.org");
28
29           $mqtt->publish("topic/here" => "Message here");
30           $mqtt->retain( "topic/here" => "Message here");
31
32           $mqtt->run(
33               "sensors/+/temperature" => sub {
34                   my ($topic, $message) = @_;
35                   die "The building's on fire" if $message > 150;
36               },
37               "#" => sub {
38                   my ($topic, $message) = @_;
39                   print "[$topic] $message\n";
40               },
41           );
42

DESCRIPTION

44       This module consists of only one file and has no dependencies except
45       core Perl modules, making it suitable for embedded installations where
46       CPAN installers are unavailable and resources are limited.
47
48       Only basic MQTT functionality is provided; if you need more, you'll
49       have to use the full-featured Net::MQTT instead.
50
51       Connections are set up on demand, automatically reconnecting to the
52       server if a previous connection had been lost.
53
54       Because sensor scripts often run unattended, connection failures will
55       result in warnings (on STDERR if you didn't override that) without
56       throwing an exception.
57
58       Please refer to Net::MQTT::Simple::SSL for more information about
59       encrypted and authenticated connections.
60
61   Functional interface
62       This will suffice for most simple sensor scripts. A socket is kept open
63       for reuse until the script has finished. The functional interface
64       cannot be used for subscriptions, only for publishing.
65
66       Instead of requesting symbols to be imported, provide the MQTT server
67       on the "use Net::MQTT::Simple" line. A non-standard port can be
68       specified with a colon. The functions "publish" and "retain" will be
69       exported.
70
71   Object oriented interface
72       new(server[, sockopts])
73
74       Specify the server (possibly with a colon and port number) to the
75       constructor, "Net::MQTT::Simple->new". The socket is disconnected when
76       the object goes out of scope.
77
78       Optionally, a reference to a hash of socket options can be passed.
79       Options specified in this hash are passed on to the socket constructor.
80
81       last_will([$topic, $message[, $retain]])
82
83       Set a "Last Will and Testament", to be used on subsequent connections.
84       Note that the last will cannot be updated for a connection that is
85       already established.
86
87       A last will is a message that is published by the broker on behalf of
88       the client, if the connection is dropped without an explicit call to
89       "disconnect".
90
91       Without arguments, returns the current values without changing the
92       active configuration.
93
94       When the given topic and message are both undef, the last will is
95       deconfigured.  In other cases, only arguments which are "defined" are
96       updated with the given value. For the first setting, the topic is
97       mandatory, the message defaults to an empty string, and the retain flag
98       defaults to false.
99
100       Returns a list of the three values in the same order as the arguments.
101
102       login($username[, $password])
103
104       Sets authentication credentials, to be used on subsequent connections.
105       Note that the credentials cannot be updated for a connection that is
106       already established.
107
108       The username is text, the password is binary.
109
110       See Net::MQTT::Simple::SSL for information about secure connections. To
111       enable insecure password authenticated connections, set the environment
112       variable MQTT_SIMPLE_ALLOW_INSECURE_LOGIN to a true value.
113
114       Returns the username.
115

DISCONNECTING GRACEFULLY

117   disconnect
118       Performs a graceful disconnect, which ensures that the server does NOT
119       send the registered "Last Will" message.
120
121       Subsequent calls that require a connection, will cause a new connection
122       to be set up.
123

PUBLISHING MESSAGES

125       The two methods for publishing messages are the same, except for the
126       state of the "retain" flag.
127
128   retain(topic, message)
129       Publish the message with the "retain" flag on. Use this for sensor
130       values or anything else where the message indicates the current status
131       of something.
132
133       To discard a retained topic, provide an empty or undefined message.
134
135   publish(topic, message)
136       Publishes the message with the "retain" flag off. Use this for
137       ephemeral messages about events that occur (like that a button was
138       pressed).
139

SUBSCRIPTIONS

141   subscribe(topic, handler[, topic, handler, ...])
142       Subscribes to the given topic(s) and registers the callbacks. Note that
143       only the first matching handler will be called for every message, even
144       if filter patterns overlap.
145
146   unsubscribe(topic[, topic, ...])
147       Unsubscribes from the given topic(s) and unregisters the corresponding
148       callbacks. The given topics must exactly match topics that were
149       previously used with the "subscribe" method.
150
151   run(...)
152       Enters an infinite loop, which calls "tick" repeatedly. If any
153       arguments are given, they will be passed to "subscribe" first.
154
155   tick(timeout)
156       Test the socket to see if there's any incoming message, waiting at most
157       timeout seconds (can be fractional). Use a timeout of 0 to avoid
158       blocking, but note that blocking automatic reconnection may take place,
159       which may take much longer.
160
161       If "tick" returns false, this means that the socket was no longer
162       connected and that the next call will cause a reconnection attempt.
163       However, a true value does not necessarily mean that the socket is
164       still functional. The only way to reliably determine that a TCP stream
165       is still connected, is to actually communicate with the server, e.g.
166       with a ping, which is only done periodically.
167

UTILITY FUNCTIONS

169   Net::MQTT::Simple::filter_as_regex(topic_filter)
170       Given a valid MQTT topic filter, returns the corresponding regular
171       expression.
172

IPv6 PREREQUISITE

174       For IPv6 support, the module IO::Socket::IP needs to be installed. It
175       comes with Perl 5.20 and is available from CPAN for older Perls. If
176       this module is not available, the older IO::Socket::INET will be used,
177       which only supports Legacy IP (IPv4).
178

MANUAL INSTALLATION

180       If you can't use the CPAN installer, you can actually install this
181       module by creating a directory "Net/MQTT" and putting "Simple.pm" in
182       it. Please note that this method does not work for every Perl module
183       and should be used only as a last resort on systems where proper
184       installers are not available.
185
186       To view the list of @INC paths where Perl searches for modules, run
187       "perl -V". This list includes the current working directory (".").
188       Additional include paths can be specified in the "PERL5LIB" environment
189       variable; see perlenv.
190

NOT SUPPORTED

192       QoS (Quality of Service)
193           Every message is published at QoS level 0, that is, "at most once",
194           also known as "fire and forget".
195
196       DUP (Duplicate message)
197           Since QoS is not supported, no retransmissions are done, and no
198           message will indicate that it has already been sent before.
199
200       Authentication
201           No username and password are sent to the server.
202
203       Large data
204           Because everything is handled in memory and there's no way to
205           indicate to the server that large messages are not desired, the
206           connection is dropped as soon as the server announces a packet
207           larger than 2 megabytes.
208
209       Validation of server-to-client communication
210           The MQTT spec prescribes mandatory validation of all incoming data,
211           and disconnecting if anything (really, anything) is wrong with it.
212           However, this minimal implementation silently ignores anything it
213           doesn't specifically handle, which may result in weird behaviour if
214           the server sends out bad data.
215
216           Most clients do not adhere to this part of the specifications.
217

CAVEATS

219   Automatic reconnection
220       Connection and reconnection are handled automatically, but without
221       retries. If anything goes wrong, this will cause a single reconnection
222       attempt before the following action. For example, if sending a message
223       fails because of a disconnected socket, the message will not be resent,
224       but the next message might succeed. Only one new connection attempt is
225       done per approximately 5 seconds.  This behaviour is intended.
226
227   Unicode
228       This module uses the proper Perl Unicode abstractions for parts that
229       according to the MQTT specification are UTF-8 encoded. This includes
230       topics, but not messages. Published messages are binary data, which you
231       may have to encode and decode yourself.
232
233       This means that if you have UTF-8 encoded string literals in your code,
234       you should "use utf8;" and that any of those strings which is a message
235       will need to be encoded by you, for example with
236       "utf8::encode($message);".
237
238       It also means that a message should never contain any character with an
239       ordinal value of greater than 255, because those cannot be used in
240       binary communication. If you're passing non-ASCII text strings, encode
241       them before publishing, decode them after receiving. A character
242       greater than 255 results in a warning
243
244           Wide character in publish at yourfile.pl line 42.
245
246       while the UTF-8 encoded data is passed through. To get rid of the
247       warning, use "utf8::encode($message);".
248

LICENSE

250       Pick your favourite OSI approved license :)
251
252       http://www.opensource.org/licenses/alphabetical
253

AUTHOR

255       Juerd Waalboer <juerd@tnx.nl>
256

SEE ALSO

258       Net::MQTT, Net::MQTT::Simple::SSL
259
260
261
262perl v5.38.0                      2023-07-21              Net::MQTT::Simple(3)
Impressum