Net::MQTT::Simple(3pm)

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

PUBLISHING MESSAGES

82       The two methods for publishing messages are the same, except for the
83       state of the "retain" flag.
84
85   retain(topic, message)
86       Publish the message with the "retain" flag on. Use this for sensor
87       values or anything else where the message indicates the current status
88       of something.
89
90       To discard a retained topic, provide an empty or undefined message.
91
92   publish(topic, message)
93       Publishes the message with the "retain" flag off. Use this for
94       ephemeral messages about events that occur (like that a button was
95       pressed).
96

SUBSCRIPTIONS

98   subscribe(topic, handler[, topic, handler, ...])
99       Subscribes to the given topic(s) and registers the callbacks. Note that
100       only the first matching handler will be called for every message, even
101       if filter patterns overlap.
102
103   unsubscribe(topic[, topic, ...]) {
104       Unsubscribes from the given topic(s) and unregisters the corresponding
105       callbacks. The given topics must exactly match topics that were
106       previously used with the "subscribe" method.
107
108   run(...)
109       Enters an infinite loop, which calls "tick" repeatedly. If any
110       arguments are given, they will be passed to "subscribe" first.
111
112   tick(timeout)
113       Test the socket to see if there's any incoming message, waiting at most
114       timeout seconds (can be fractional). Use a timeout of 0 to avoid
115       blocking, but note that blocking automatic reconnection may take place,
116       which may take much longer.
117
118       If "tick" returns false, this means that the socket was no longer
119       connected and that the next call will cause a reconnection attempt.
120       However, a true value does not necessarily mean that the socket is
121       still functional. The only way to reliably determine that a TCP stream
122       is still connected, is to actually communicate with the server, e.g.
123       with a ping, which is only done periodically.
124

UTILITY FUNCTIONS

126   Net::MQTT::Simple::filter_as_regex(topic_filter)
127       Given a valid MQTT topic filter, returns the corresponding regular
128       expression.
129

IPv6 PREREQUISITE

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

MANUAL INSTALLATION

137       If you can't use the CPAN installer, you can actually install this
138       module by creating a directory "Net/MQTT" and putting "Simple.pm" in
139       it. Please note that this method does not work for every Perl module
140       and should be used only as a last resort on systems where proper
141       installers are not available.
142
143       To view the list of @INC paths where Perl searches for modules, run
144       "perl -V". This list includes the current working directory (".").
145       Additional include paths can be specified in the "PERL5LIB" environment
146       variable; see perlenv.
147

NOT SUPPORTED

149       QoS (Quality of Service)
150           Every message is published at QoS level 0, that is, "at most once",
151           also known as "fire and forget".
152
153       DUP (Duplicate message)
154           Since QoS is not supported, no retransmissions are done, and no
155           message will indicate that it has already been sent before.
156
157       Authentication
158           No username and password are sent to the server.
159
160       Last will
161           The server won't publish a "last will" message on behalf of us when
162           our connection's gone.
163
164       Large data
165           Because everything is handled in memory and there's no way to
166           indicate to the server that large messages are not desired, the
167           connection is dropped as soon as the server announces a packet
168           larger than 2 megabytes.
169
170       Validation of server-to-client communication
171           The MQTT spec prescribes mandatory validation of all incoming data,
172           and disconnecting if anything (really, anything) is wrong with it.
173           However, this minimal implementation silently ignores anything it
174           doesn't specifically handle, which may result in weird behaviour if
175           the server sends out bad data.
176
177           Most clients do not adhere to this part of the specifications.
178

CAVEATS

180   Automatic reconnection
181       Connection and reconnection are handled automatically, but without
182       retries. If anything goes wrong, this will cause a single reconnection
183       attempt before the following action. For example, if sending a message
184       fails because of a disconnected socket, the message will not be resent,
185       but the next message might succeed. Only one new connection attempt is
186       done per approximately 5 seconds.  This behaviour is intended.
187
188   Unicode
189       This module uses the proper Perl Unicode abstractions for parts that
190       according to the MQTT specification are UTF-8 encoded. This includes
191       topics, but not messages. Published messages are binary data, which you
192       may have to encode and decode yourself.
193
194       This means that if you have UTF-8 encoded string literals in your code,
195       you should "use utf8;" and that any of those strings which is a message
196       will need to be encoded by you, for example with
197       "utf8::encode($message);".
198
199       It also means that a message should never contain any character with an
200       ordinal value of greater than 255, because those cannot be used in
201       binary communication. If you're passing non-ASCII text strings, encode
202       them before publishing, decode them after receiving. A character
203       greater than 255 results in a warning
204
205           Wide character in publish at yourfile.pl line 42.
206
207       while the UTF-8 encoded data is passed through. To get rid of the
208       warning, use "utf8::encode($message);".
209

LICENSE

211       Pick your favourite OSI approved license :)
212
213       http://www.opensource.org/licenses/alphabetical
214

AUTHOR

216       Juerd Waalboer <juerd@tnx.nl>
217