Broker API reference

The Broker class provides a complete MQTT 3.1.1 broker implementation. This class allows Python developers to embed a MQTT broker in their own applications.

Usage example

The following example shows how to start a broker using the default configuration:

import logging
import asyncio
import os
from hbmqtt.broker import Broker


@asyncio.coroutine
def broker_coro():
    broker = Broker()
    yield from broker.start()


if __name__ == '__main__':
    formatter = "[%(asctime)s] :: %(levelname)s :: %(name)s :: %(message)s"
    logging.basicConfig(level=logging.INFO, format=formatter)
    asyncio.get_event_loop().run_until_complete(broker_coro())
    asyncio.get_event_loop().run_forever()

When executed, this script gets the default event loop and asks it to run the broker_coro until it completes. broker_coro creates Broker instance and then start() the broker for serving. Once completed, the loop is ran forever, making this script never stop …

Reference

Broker API

class hbmqtt.broker.Broker(config=None, loop=None, plugin_namespace=None)

MQTT 3.1.1 compliant broker implementation

Parameters:

• config – Example Yaml config
• loop – asyncio loop to use. Defaults to asyncio.get_event_loop() if none is given
• plugin_namespace – Plugin namespace to use when loading plugin entry_points. Defaults to hbmqtt.broker.plugins

start()

Start the broker to serve with the given configuration

Start method opens network sockets and will start listening for incoming connections.

This method is a coroutine.

shutdown()

Stop broker instance.

Closes all connected session, stop listening on network socket and free resources.

Broker configuration

The Broker __init__ method accepts a config parameter which allow to setup some behaviour and defaults settings. This argument must be a Python dict object. For convinience, it is presented below as a YAML file [1].

listeners:
    default:
        max-connections: 50000
        type: tcp
    my-tcp-1:
        bind: 127.0.0.1:1883
    my-tcp-2:
        bind: 1.2.3.4:1884
        max-connections: 1000
    my-tcp-ssl-1:
        bind: 127.0.0.1:8885
        ssl: on
        cafile: /some/cafile
        capath: /some/folder
        capath: certificate data
        certfile: /some/certfile
        keyfile: /some/key
    my-ws-1:
        bind: 0.0.0.0:8080
        type: ws
timeout-disconnect-delay: 2
auth:
    plugins: ['auth.anonymous'] #List of plugins to activate for authentication among all registered plugins
    allow-anonymous: true / false
    password-file: /some/passwd_file

The listeners section allows to define network listeners which must be started by the Broker. Several listeners can be setup. default subsection defines common attributes for all listeners. Each listener can have the following settings:

• bind: IP address and port binding.
• max-connections: Set maximum number of active connection for the listener. 0 means no limit.
• type: transport protocol type; can be tcp for classic TCP listener or ws for MQTT over websocket.
• ssl enables (on) or disable secured connection over the transport protocol.
• cafile, cadata, certfile and keyfile : mandatory parameters for SSL secured connections.

The auth section setup authentication behaviour:

• plugins: defines the list of activated plugins. Note the plugins must be defined in the hbmqtt.broker.plugins entry point.
• allow-anonymous : used by the internal hbmqtt.plugins.authentication.AnonymousAuthPlugin plugin. This parameter enables (on) or disable anonymous connection, ie. connection without username.
• password-file : used by the internal hbmqtt.plugins.authentication.FileAuthPlugin plugin. This parameter gives to path of the password file to load for authenticating users.

[1]	See PyYAML for loading YAML files as Python dict.