emqttc_minimal_project.md

Here is a guide on how to get running a minimal project using emqttc.

1. Install rebar3 (https://www.rebar3.org). You may look for it in your distribution or just install it from the website.
2. Create a project. We will create a library project, which is good for experimenting. Later, when you want to build an actual application, you should create an app project or a release project.

$ rebar3 new lib emqtcc_minimal_project

This will create a directory emqtcc_minimal_project in your CWD with project structure in it. 3. cd to the directory and edit rebar.config. Add the following element to the list after deps ,: {emqttc, {git, "https://github.com/emqtt/emqttc.git", {ref, "815ebeca103025bbb5eb8e4b2f6a5f79e1236d4c"}}}. By this, you declare that emqttc is your dependency, and that you want to fetch the version identified by the specified hash from the git repo. 4. To fetch the dependencies, run:

$ rebar3 upgrade

5. Run rebar shell and check if a simple emqttc example works

$ rebar3 shell

This will give you an Erlang shell with the dependencies available.

Eshell V7.3.1  (abort with ^G)
1> {ok, C} = emqttc:start_link([{host, "localhost"}, {client_id, <<"simpleClient">>}]).

This should print some debug info about connecting if you have mosquitto running on your localhost.

[info] [Client <0.91.0>]: connecting to localhost:1883
{ok,<0.91.0>}
[debug] [simpleClient@127.0.0.1:61357] SENT: CONNECT(Q0, R0, D0, ClientId=simpleClient, ProtoName=MQTT, ProtoVsn=4, CleanSess=true, KeepAlive=90, Username=undefined, Password=undefined)
[debug] [simpleClient@127.0.0.1:61357] SENT: <<16,24,0,4,77,81,84,84,4,2,0,90,
                                               0,12,115,105,109,112,108,101,67,
                                               108,105,101,110,116>>
[info] [Client <0.91.0>] connected with localhost:1883
[info] [Client <0.91.0>] RECV: CONNACK_ACCEPT

Now you can subscribe to a topic

2> emqttc:subscribe(C, <<"TopicA">>, qos0).
[debug] [simpleClient@127.0.0.1:61357] SENT: SUBSCRIBE(Q1, R0, D0, PacketId=1, TopicTable=[{<<"TopicA">>,0}])
ok
[debug] [simpleClient@127.0.0.1:61357] SENT: <<130,11,0,1,0,6,84,111,112,105,
                                               99,65,0>>
[debug] [Client <0.91.0>] RECV: SUBACK(Q0, R0, D0, PacketId=1, QosTable=[0])

And after that start waiting for a message.

3> receive {publish, Topic, Payload} -> {publish, Topic, Payload} end.

Then, you can publish a message using mosquitto_pub:

$ mosquitto_pub -t "TopicA" -m "abc123"

And receive it in the Erlang shell:

[debug] [simpleClient@127.0.0.1:61357] SENT: PINGREQ(Q0, R0, D0)
[debug] [simpleClient@127.0.0.1:61357] SENT: <<192,0>>
[debug] [Client <0.91.0>] RECV: PINGRESP(Q0, R0, D0)
[debug] [Client <0.91.0>] RECV: PUBLISH(Q0, R0, D0, TopicName=TopicA, PacketId=undefined, Payload=<<"abc123">>)
{publish,<<"TopicA">>,<<"abc123">>}

After validating that you can publish a message and receive it in the Erlang shell, you can quit it.

4> q().
ok
5>

6. Now you can put your code in src/emqtcc_minimal_project.erl, run rebar3 shell again, and be able to execute the functions that you defined. If you want to reload your code without quitting your shell, just perform rebar3 compile and then l(mqtcc_minimal_project) (or any other module) in the Erlang shell.