1Net::MQTT::Simple(3) User Contributed Perl Documentation Net::MQTT::Simple(3)
2
6 Net::MQTT::Simple - Minimal MQTT version 3 interface
7
9 # One-liner that publishes sensor values from STDIN
10 perl -MNet::MQTT::Simple=mosquitto.example.org \
12 -nle'retain "topic/here" => $_'
13 # Functional (single server only)
16 use Net::MQTT::Simple "mosquitto.example.org";
18 publish "topic/here" => "Message here";
20 retain "topic/here" => "Retained message here";
21 # Object oriented (supports subscribing to topics)
24 use Net::MQTT::Simple;
26 my $mqtt = Net::MQTT::Simple->new("mosquitto.example.org");
28 $mqtt->publish("topic/here" => "Message here");
30 $mqtt->retain( "topic/here" => "Message here");
31 $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
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 Only basic MQTT functionality is provided; if you need more, you'll
49 have to use the full-featured Net::MQTT instead.
50 Connections are set up on demand, automatically reconnecting to the
52 server if a previous connection had been lost.
53 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 Please refer to Net::MQTT::Simple::SSL for more information about
59 encrypted and authenticated connections.
60 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 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 Object oriented interface
72 new(server[, sockopts])
73 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 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 last_will([$topic, $message[, $retain]])
82 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 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 Without arguments, returns the current values without changing the
92 active configuration.
93 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 Returns a list of the three values in the same order as the arguments.
101 login($username[, $password])
103 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 The username is text, the password is binary.
109 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 Returns the username.
115
117 disconnect
118 Performs a graceful disconnect, which ensures that the server does NOT
119 send the registered "Last Will" message.
120 Subsequent calls that require a connection, will cause a new connection
122 to be set up.
123
125 The two methods for publishing messages are the same, except for the
126 state of the "retain" flag.
127 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 To discard a retained topic, provide an empty or undefined message.
134 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
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 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 run(...)
152 Enters an infinite loop, which calls "tick" repeatedly. If any
153 arguments are given, they will be passed to "subscribe" first.
154 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 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
169 Net::MQTT::Simple::filter_as_regex(topic_filter)
170 Given a valid MQTT topic filter, returns the corresponding regular
171 expression.
172
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
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 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
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 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 Authentication
201 No username and password are sent to the server.
202 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 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 Most clients do not adhere to this part of the specifications.
217
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 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 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 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 Wide character in publish at yourfile.pl line 42.
245 while the UTF-8 encoded data is passed through. To get rid of the
247 warning, use "utf8::encode($message);".
248
250 Pick your favourite OSI approved license :)
251 http://www.opensource.org/licenses/alphabetical
253
255 Juerd Waalboer <juerd@tnx.nl>
256
258 Net::MQTT, Net::MQTT::Simple::SSL
259perl v5.32.0 2020-07-28 Net::MQTT::Simple(3)