# Jackalope
[](https://circleci.com/gh/smartrent/jackalope)
[](https://hex.pm/packages/jackalope)
<!-- MDOC !-->
`Jackalope` is an opinionated MQTT library that simplifies the use of
[`Tortoise311 MQTT`](https://hex.pm/packages/tortoise311) 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.
Subscriptions are static only and are set as part of the connection options
provided to Jackalope.
- `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.
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.
<!-- MDOC !-->
## Installation
If [available in Hex](https://hex.pm/docs/publish), the package can be
installed by adding `jackalope` to your list of dependencies in
`mix.exs`:
```elixir
def deps do
[
{:jackalope, "~> 0.6.0"}
]
end
```
