Network.MQTT

A MQTT client library.

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

>>> import Network.MQTT
>>> import Network.MQTT.Logger
>>> Just mqtt <- connect defaultConfig { cLogger = warnings stdLogger }
>>> let f t payload = putStrLn $ "A message was published to " ++ show t ++ ": " ++ show payload
>>> 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

Hostname of the broker.

cPort :: MQTTConfig -> PortNumber

Port of the broker.

cClean :: MQTTConfig -> Bool

Should the server forget subscriptions and other state on disconnects?

cWill :: MQTTConfig -> Maybe Will

Optional Will message.

cUsername :: MQTTConfig -> Maybe Text

Optional username used for authentication.

cPassword :: MQTTConfig -> Maybe Text

Optional password used for authentication.

cKeepAlive :: MQTTConfig -> Maybe Int

Maximum interval (in seconds) in which a message must be sent. 0 means no limit.

cClientID :: MQTTConfig -> Text

Client ID used by the server to identify clients.

cConnectTimeout :: MQTTConfig -> Maybe Int

Time in seconds after which waiting for a CONNACK is aborted. Nothing means no timeout.

cReconnPeriod :: MQTTConfig -> Maybe Int

Time in seconds to wait between reconnect attempts. Nothing means no reconnects are attempted.

cLogger :: MQTTConfig -> Logger

Functions for logging, see 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 Network.MQTT.Types