Jackalope (jackalope v0.7.3) View Source
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.
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.
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor.
Get the current MQTT connection status
Publish a message to the MQTT broker
Request the MQTT client to reconnect to the broker
Start a Jackalope session
Link to this section Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
Specs
connection_status() :: :offline | :online
Get the current MQTT connection status
Specs
publish(String.t(), any(), options) :: :ok | {:error, :invalid_qos} when options: [qos: 0..2, retain: boolean(), ttl: non_neg_integer()]
Publish a message to the MQTT broker
The payload
will get published on topic
. Jackalope
will keep
the message in a queue until we got a connection, at which point it
will dispatch the publish. This of course present us with a problem:
what if we place a publish request to "unlock the front door" while
the client is offline? We don't want to receive a message that the
front door has been unlocked two hours later when the MQTT client
reconnect; To solve that problem we have a ttl
option we can
specify on the publish.
Jackalope.publish("doors/front_door", %{action: "unlock"}, qos: 1, ttl: 5_000)
The available publish options are:
qos
(default1
) sets the quality of service of the message delivery; Notice that only quality of service 0 an 1 are supported by AWS IoT.retain
(defaultfalse
) sets whether the broker should retain the message. Note that AWS IoT does not support this feature.ttl
(default3_600_000
) sets how long (in msecs) publishing the message will be retried until it has expired.
Specs
reconnect() :: :ok
Request the MQTT client to reconnect to the broker
This can be useful on devices that has multiple network interfaces.
Specs
start_link(keyword()) :: Supervisor.on_start()
Start a Jackalope session
This will start a supervised group of processes; part of the group
will keep track of the topic filter subscription state, and hold a
list of yet to be published messages, as well as the requested
subscription changes; the other part of the process tree will keep
the MQTT connection specific parts, making sure we got a
connection. See the main documentation on the Jackalope
module for
more information on the process architecture.
Jackalope.start_link/1
takes a keyword list containing option
values, that configure the instance, as an argument. The available
options and their defaults are:
client_id
(default: "jackalope"), string that will be used as the client_id of the MQTT connection; seet Tortoise311.client_id
for more information on valid client ids. Notice that the client_id needs to be unique on the server, so two clients may not have the same client_id.user_name
(optional) specifies the MQTT Username.password
(optional) specifies the MQTT Password. Google cloud IOT requires a JWT for this field.initial_topics
(optional) specifies a list of topic_filters Jackalope should connect to when a connection has been established. Notice that this list is also used should a reconnect happen later in the life-cycle. Note that Jackalope does not support dynamic subscriptions or unsubscribing. This is the only mechanism for subscribing.clean_session
(default: true), a flag bit that controls the life cycle of the session state. The MQTT session lasts only as long as the network connection between client and server. When the session ends, all session state in the server is deleted.handler
(default:Jackalope.Handler.Logger
) specifies the module implementing the callbacks (implementingJackalope.Handler
behaviour) to use. This module reacts to the events Jackalope communicates about the connection life-cycle, including receiving a message on a subscribed topic filter. Read the documentation forJackalope.Handler
for more information on the events and callbacks.server
(default: {Tortoise311.Transport.Tcp, [host: "localhost", port: 1883]}) specifies the connection type, and its options, to use when connecting to the MQTT server. The default specification will attempt to connect to a broker running on localhost:1883, on an insecure connection. This value should only be used for testing and development.Server options for use with AWS IoT: [ verify: :verify_peer, host: mqtt_host(), # must return the full name, without wild cards, for e.g. "abcdefghijklmo-ats.iot.us-east-1.amazonaws.com" port: mqtt_port(), # must return the correct port, e.g. 443 alpn_advertised_protocols: ["x-amzn-mqtt-ca"], server_name_indication: to_charlist(mqtt_host()), cert: cert, # the device's X509 certificate in DER format key: key, # the device's private key in DER format cacerts: [signer_cert] ++ aws_ca_certs(), # the device's signer cert, plus AWS IoT CA certs in DER format to be returned by aws_ca_certs() versions: [:"tlsv1.2"], customize_hostname_check: [match_fun: :public_key.pkix_verify_hostname_match_fun(:https)] ]
work_list_mod
names the module implementing the Jackalope WorkList protocol that will be used to manage the publish commands sent to Tortoise by the Jackalope Session. The module must also implement the function@spec new(function(), function(), non_neg_integer(), Keyword.t()) :: any()
. See Jackalope.TransientWorkList (the default) for examples.max_work_list_size
(default: 100) specifies the maximum number of unexpired work orders Jackalope will retain in its work list (the commands yet to be sent to the MQTT server). When the maximum is reached, the oldest work order is dropped before adding a new work order.last_will
(default: nil) specifies the last will message that should get published on the MQTT broker if the connection is closed or dropped unexpectedly. If we want to specify a last will topic we should define a keyword list containing the following:topic
(Required) the topic to post the last will message to; this should be specified as a string and it should be a valid MQTT topic; consultt Tortoise311.topic
for more info on valid MQTT topics.payload
(default: nil) the payload of the last will message;qos
(default: 0) either 0 or 1, denoting the quality of service the last will message should get published with; note that QoS=2 is not supported by AWS IoT.
backoff
(default: [min_interval: 1_000, max_interval: 30_000]) gives the bounds of an exponential backoff algorithm used when retrying from failed connections.