gemqtt

gemqtt provides an MQTT client for Gleam projects running on the BEAM. It does so by wrapping the emqx/emqtt library written in Erlang.

NOTE

At the time of writing (March 19th, 2024), this package is stuck on emqtt version 1.2 due to a dependency issue. That version of the underlying emqx/emqtt library only works with Erlang OTP version 25.x, not 26+.

Status

This package is a work in progress. If it is missing an emqtt feature you need, please send a PR.

General features

• Connect to unencrypted MQTT servers over TCP
• Connect to TLS encrypted MQTT servers over TCP
• Connect to unencrypted MQTT servers over websocket
• Connect to TLS encrypted MQTT servers over websocket
• Supports emqtt properties for connect, publish, and subscribe

Connect options

• User + password authentication
• Message auto acknowledgement
• Clean start
• Client ID
• Connect timeout
• Erlang server name
• Owner PID (for disconnect notifications)
• Port number
• TLS enable + raw options
• TCP options
• Websocket path
• Bridge mode
• Proto version
• Keep alive
• Max in-flight
• Retry interval
• Will topic
• Will payload
• Will retain
• Will QoS
• Will properties
• Ack timeout
• Force ping

Publish options

• QoS
• Retain

Subscribe options

• Local Echo
• QoS
• Retain as published
• Retain handling

Example Usage

gleam add gleam_erlang
gleam add gemqtt

import gemqtt
import gemqtt/publisher
import gemqtt/subscriber
import gleam/bit_array
import gleam/erlang/process
import gleam/io

pub fn main() {
 let topic = "gemqtt/readme/example"

 // Create a client and connect to the test server.
 let assert Ok(client) =
   gemqtt.new("test.mosquitto.org")
   |> gemqtt.start_link
 let assert Ok(_) = gemqtt.connect(client)

 io.println("Connected.")

 // Subscribe to messages from the topic.
 let assert Ok(_) =
   client
   |> subscriber.new
   |> subscriber.add(topics: [topic])

 io.println("Subscribed.")

 // Publish a test message to the topic.
 let assert Ok(_) =
   publisher.new(client, topic)
   |> publisher.publish(bit_array.from_string("Hello from Gleam!"))

 io.println("Sent message.")

 // Attempt to receive a message from the topic.
 let assert Ok(got_msg) =
   process.new_selector()
   |> subscriber.selecting_mqtt_messages(Ok)
   |> process.select_forever

 io.println("Received message:")
 io.debug(got_msg)

 let assert Ok(_) = subscriber.remove(client, [topic])
 let assert Ok(_) = gemqtt.disconnect(client)
}

Further documentation can be found at https://hexdocs.pm/gemqtt.

Development

gleam test  # Run the tests
gleam shell # Run an Erlang shell