Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

MQTT library for Erlang *JUST USABLE*

branch: master

Supplied client ID and disabling the clean session flag

The mosquitto_{pub,sub} command line options are odd. For example,
`-c` means *disable* the clean session flag. Not sure how long I will
continue to emulate them.
latest commit 80ca22b93d
Michael Bridgen authored April 20, 2014
Octocat-spinner-32 include Specs for the public API February 18, 2014
Octocat-spinner-32 src
Octocat-spinner-32 test Add public API (erlmqtt) and rename other src files February 18, 2014
Octocat-spinner-32 .gitignore Bring tests up to date and add properties January 04, 2014
Octocat-spinner-32 Makefile Add PropEr as dependency and only test erlmqtt April 13, 2014
Octocat-spinner-32 README.md Mention erlmqtt_pub and erlmqtt_sub April 11, 2014
Octocat-spinner-32 erlmqtt_pub Reorder opts by theme April 20, 2014
Octocat-spinner-32 erlmqtt_sub Supplied client ID and disabling the clean session flag April 20, 2014
Octocat-spinner-32 rebar.config
README.md

erlmqtt

An Erlang client library for MQTT 3.1 (but not for MQTT 3.1.1, yet).

Building

$ make

Testing

$ make test && make dialyse

Trying out

This API may change, especially with respect to receiving messages.

(Assuming RabbitMQ or another MQTT broker is running on localhost:1883)

$ erl -pa ebin

Opening a connection and subscribing

1> {ok, C} = erlmqtt:open_clean("localhost", []).
{ok,<0.35.0>}
2> {ok, _} = erlmqtt:subscribe(C, [{"topic/#", at_most_once}]).
{ok,[at_most_once]}

open_clean starts a fresh connection that doesn't keep state around when disconnected. The second argument is a proplist of options, for example, [{keep_alive, 600}].

Also exported are open/2 and open/3, which start connections with persistent state (though resumption of those after disconnection is not fully implemented yet).

Publishing messages

3> erlmqtt:publish(C, "topic/a/b", <<"payload">>).
ok

There's also a publish/4 which accepts a proplist of options, e.g., [retain, at_least_once], and publish_sync/4 and publish_sync/5, which publish a message using guaranteed delivery and return when the message has been delivered (or in the case of publish_sync/5, if it has timed out).

4> erlmqtt:publish_sync(C, "/dev/null", <<"payload">>, at_least_once).
ok

Currently, using "quality of service" (guaranteed delivery) other than at_most_once does not get you a lot; the connection will enact the correct protocol, but if it crashes you will still lose the state.

Receiving messages

5> erlmqtt:recv_message(1000).
{<<"topic/a/b">>,<<"payload">>}
6> erlmqtt:recv_message(1000).
timeout
7> erlmqtt:publish(C, "topic/foo", <<"payload">>).
8> erlmqtt:poll_message().
{<<"topic/foo">>,<<"payload">>}
9> erlmqtt:poll_message().
none

When a connection is opened, the calling process is volunteered as the message consumer. This means the connection will deliver messages to its mailbox. recv_message/0 and recv_message/1 wait for a message to arrive (in the latter case, for a limited time) and return it as a pair of topic and payload. poll_message/0 returns a pair of topic and payload if a message is available in the mailbox now, otherwise 'none'.

Examples

The scripts erlmqtt_pub and erlmqtt_sub give examples of publishing and subscribing respectively. Presently they must be run from the repository directory. Use the argument --help with either to see its usage.

Something went wrong with that request. Please try again.