MQTT

A MQTT client library.

A simple example, assuming a broker is running on localhost (needs -XOverloadedStrings):

>>> import MQTT
>>> import MQTT.Logger
>>> Just mqtt <- connect defaultConfig { cLogger = warnings stdLogger }
>>> let f t payload = putStrLn $ "A message was published to " ++ show t ++ ": " ++ show pyload
>>> subscribe mqtt NoConfirm "#" f
NoConfirm
>>> publish mqtt Handshake False "some random/topic" "Some content!"
A message was published to "some random/topic": "Some content!"

Creating connections

connect :: MQTTConfig -> IO (Maybe MQTT)

Establish a connection. This might fail with an IOException or return Nothing if the server did not accept the connection.

data MQTT

Abstract type representing a connection to a broker.

disconnect :: MQTT -> IO ()

Close the connection to the server.

reconnect :: MQTT -> Int -> IO ()

Try creating a new connection with the same config (retrying after the specified amount of seconds has passed) and invoke the callback that is set with onReconnect once a new connection has been established.

Does not terminate the old connection.

onReconnect :: MQTT -> IO () -> IO ()

Register a callback that will be invoked when a reconnect has happened.

resubscribe :: MQTT -> IO [QoS]

Resubscribe to all topics. Returns the new list of granted QoS.

Connection settings

data MQTTConfig

The various options when establishing a connection.

defaultConfig :: MQTTConfig

Defaults for MQTTConfig, connects to a server running on localhost.

Field accessors

cHost :: MQTTConfig -> HostName

cPort :: MQTTConfig -> PortNumber

cClean :: MQTTConfig -> Bool

cWill :: MQTTConfig -> Maybe Will

cUsername :: MQTTConfig -> Maybe Text

cPassword :: MQTTConfig -> Maybe Text

cKeepAlive :: MQTTConfig -> Maybe Int

cClientID :: MQTTConfig -> Text

cConnectTimeout :: MQTTConfig -> Maybe Int

cReconnPeriod :: MQTTConfig -> Maybe Int

cLogger :: MQTTConfig -> Logger

Subscribing and publishing

subscribe :: MQTT -> QoS -> Topic -> (Topic -> ByteString -> IO ()) -> IO QoS

Subscribe to a Topic with the given QoS and invoke the callback whenever something is published to the Topic. Returns the QoS that was granted by the broker (lower or equal to the one requested).

The Topic may contain wildcars. The Topic passed to the callback is the fully expanded version where the message was actually published.

unsubscribe :: MQTT -> Topic -> IO ()

Unsubscribe from the given Topic and remove any handlers.

publish :: MQTT -> QoS -> Bool -> Topic -> ByteString -> IO ()

Publish a message to the given Topic at the requested QoS level. The payload can be any sequence of bytes, including none at all. The Bool parameter decides if the server should retain the message for future subscribers to the topic.

The Topic must not contain wildcards.

Sending and receiving Messages

send :: MQTT -> Message t -> IO ()

Send a Message to the server.

addHandler :: SingI t => MQTT -> (Message t -> IO ()) -> IO Unique

Register a callback that gets invoked whenever a Message of the expected MsgType is received. Returns the ID of the handler which can be passed to removeHandler.

removeHandler :: MQTT -> Unique -> IO ()

Remove the handler with the given ID.

awaitMsg :: SingI t => MQTT -> SMsgType t -> Maybe MsgID -> IO (Message t)

Block until a Message of the given type, optionally with the given MsgID, arrives.

Note this expects a singleton to guarantee the returned Message is of the MsgType that is being waited for. Singleton constructors are the MsgType constructors prefixed with a capital S, e.g. SPUBLISH.

awaitMsg' :: SingI t => MQTT -> Maybe MsgID -> IO (Message t)

A version of awaitMsg that infers the type of the Message that is expected.

Reexports

module MQTT.Types