NAME

Beekeeper::MQTT - Asynchronous MQTT 5.0 client.

VERSION

Version 0.03

SYNOPSIS

my $mqtt = Beekeeper::MQTT->new(
    host     => 'localhost',
    username => 'guest',
    password => 'guest',
);

$mqtt->connect( 
    blocking => 1,
    on_connack => sub {
        my ($success, $properties) = @_;
        die $properties->{reason_string} unless $success;
    },
);

$mqtt->subscribe(
    topic => 'foo/bar',
    on_publish => sub {
        my ($payload, $properties) = @_;
        print "Got a message: $$payload";
    },
);

$mqtt->publish(
    topic   => 'foo/bar',
    payload => 'Hello',
);

$mqtt->unsubscribe(
    topic => 'foo/bar',
);

$mqtt->disconnect;

Most methods allows to send arbitrary properties along with commands.

Except for trivial cases, error checking is delegated to the server.

The MQTT specification can be found at https://mqtt.org/mqtt-specification

TODO

- Keep Alive

CONSTRUCTOR

new ( %options )

host

Hostname or IP address of the MQTT server. It also accepts an array of adresses which conforms a cluster, in which case the connection will be stablished against a randomly choosen node of the cluster.

port

Port of the MQTT server. If not specified use the MQTT default of 1883.

tls

Enable the use of TLS for MQTT connections.

username

Username used to authenticate against the server.

password

Password used to authenticate against the server.

timeout

Connection timeout in fractional seconds before giving up. Default is 30 seconds. If set to zero the connection to server it retried forever.

on_error => $cb->( $errmsg )

Optional callback which is executed when an error condition occurs. If not specified, the default is to die with $errmsg. Usually the server has already closed the connection when this is called.

METHODS

connect ( %options )

Connect to the MQTT server and do handshake. On failure retries until timeout.

blocking => $bool

When set to true this method acts as a blocking call: it does not return until a connection has been established and handshake has been completed.

on_connack => $cb->( $success, \%properties )

Callback which is executed after the server accepted the connection.

disconnect ( %args )

A client can disconnect from the server at anytime by closing the socket but there is no guarantee that the previously sent packets have been received by the server. This method should be called to do a graceful shutdown, where the client is assured that all previous packets have been received by the server.

$reason_code

Disconnect Reason Code as stated in the chapter 3.14.2.1 of the specification. Default is zero, meaning normal disconnection.

subscribe ( %args )

Create a subscription to a topic (or a list of topics). When a message is received, it will be passed to given on_publish callback:

$mqtt->subscribe(
    topic       => 'topic/foo',
    maximum_qos => 1,
    on_publish  => sub {
        my ($payload, \%properties) = @_;
        print "Got message from topic/foo : $$payload";
    },
);

topics => \@topics

List of topics to which the client wants to subscribe.

on_publish => $cb->( \$payload, \%properties )

Required callback which is executed when a message matching any of the subscription topics is received.

on_suback => $cb->( $success, \%properties, ... )

Optional callback which is executed after subscription is acknowledged by the server with a SUBACK packet.

User properties

Any other argument other than maximum_qos, no_local, retain_as_published or retain_handling is sent as an "User Property" (a key-value pair of utf8 strings).

unsubscribe ( %params )

Cancel an existing subscription, the client will no longer receive messages from that topic. Example:

$mqtt->unsubscribe( 
    topics => ['topic/foo','topic/bar']
);

topics => \@topics

The destination of an existing subscription.

on_unsuback => $cb->()

Optional user defined callback which is called after unsubscription is completed.

publish ( %args )

Sends a message to a topic. Example:

$mqtt->publish(
    topic     => 'foo/bar',
    payload   => 'Hello!',
    qos       => 1,
    on_puback => sub {
       my ($reason_code) = @_;
       print "Message was sent";
    }
);

topic => $str

Utf8 string containing the topic name.

payload => \$data

Scalar or scalar reference containing either an utf8 string or a binary blob which conforms the payload of the message. It is allowed to publish messages without payload.

qos => $bool

Quality of service level (QoS). Only levels 0 and 1 are supported. Default is 0.

duplicate => $bool

Must be set to a true value to indicate a message retransmission.

retain => $bool

When true sets the message retain flag.

message_expiry_interval => $int

Expiration period in seconds. The server will discard retained messages after this period has ellapsed.

response_topic => $str

Utf8 string containing the response topic name.

on_puback => $cb->($reason_code)

Optional callback which is executed after the server answers with a PUBACK packet, acknowledging that it has received it. Allowed only for messages published with QoS 1.

User properties

Any aditional argument will be sent as an "User Property", this is as a key-value pair of utf8 strings.

puback ( %args )

Used to acknowledge the receipt of a message received from a subscription with QoS 1. The server should resend the message until it is acknowledged.

packet_id => $int

reason_code => $int

If not specified it will default to zero, signaling success.

flush_buffer

Send several packets into a single socket write. This is more efficient than individual send() calls because Nagle's algorithm is disabled.

discard_buffer

Discard buffered packets.

AUTHOR

José Micó, jose.mico@gmail.com

COPYRIGHT AND LICENSE

Copyright 2021 José Micó.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language itself.

This software is distributed in the hope that it will be useful, but it is provided “as is” and without any express or implied warranties. For details, see the full text of the license in the file LICENSE.

cpanm Beekeeper

perl -MCPAN -e shell
install Beekeeper