Skip to content

Latest commit

 

History

History
85 lines (61 loc) · 3.15 KB

README.md

File metadata and controls

85 lines (61 loc) · 3.15 KB
Raw

Jackalope

CircleCI Hex version

Jackalope is an opinionated MQTT library that simplifies the use of Tortoise311 MQTT with cloud IoT services.

Jackalope aims to make an interface that:

  • Ensure that important messages are delivered to the broker, by having a local "post office" and tracking the in flight messages, and implementing a concept of ttl (time to live) on the messages placed in the mailbox; ensuring the "request to unlock the door" won't happen two hours later when the MQTT connection finally reconnects. This allows Jackalope to accept publish requests while the connection is down.

Besides this Jackalope aims to provide helpers for local testing, allowing you to test your application without having a connection to AWS; Jackalope should take care of that.

Usage

The Jackalope module implements a start_link/1 function; use this to start Jackalope as part of your application supervision tree. If properly supervised it will allow you to start and stop Jackalope with the part the application that needs MQTT connectivity. Jackalope is configured using a keyword list, consult the Jackalope.start_link/1 documentation for information on the available option values.

Once Jackalope is running it is possible to publish messages to the broker; in addition to this there are some connection specific functionality is exposed, allowing us to ask for the connection status, and request a connection reconnect.

  • Jackalope.publish(topic, payload) will publish a message to the MQTT broker;

  • Jackalope.reconnect() will disconnect from the broker and reconnect; this is useful if the device changes network connection.

Subscriptions can be set as part of the connection options provided to Jackalope or added later on.

  • Jackalope.subscribe(topic) subscribes to a topic

  • Jackalope.unsubscribe(topic) unsubscribes from a topic

Please see the documentation for each of the functions for more information on usage; publish functions accept options such as setting quality of service and time to live.

Configuration

Jackalope puts the publish commands on a work list before it sends them to Tortoise311. The work list moves the commands from waiting to be sent, to pending (sent and waiting for a response), to discarded when confirmed by Tortoise311 as processed or when they are expired.

The work list has a maximum size which defaults to 100. Only a maximum number of publish commands can wait, should Tortoise311 be temporarily disconnected, to be forwarded to Tortoise311.

You can set the Jackalope.start_link/1 :work_list_mod option to the desired work list implementation. See the documentation for module Jackalope.

Installation

If available in Hex, the package can be installed by adding jackalope to your list of dependencies in mix.exs:

def deps do
  [
    {:jackalope, "~> 0.7.2"}
  ]
end