KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

jackalope

★ 32 Open GitHub ↗

An opinionated MQTT client library based on Tortoise MQTT

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Jackalope

[![CircleCI](https://circleci.com/gh/smartrent/jackalope.svg?style=svg)](https://circleci.com/gh/smartrent/jackalope)
[![Hex version](https://img.shields.io/hexpm/v/jackalope.svg "Hex version")](https://hex.pm/packages/jackalope)

`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.

## Development Setup

Install [mise](https://mise.jdx.dev) (requires >= 2026.4.8):

```sh
brew install mise
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
```

Then install project tools:

```sh
mise trust mise.toml && mise install
```

## 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](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.7.2"}
  ]
end
```

jackalope

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README