HBMQTT Documentation

HBMQTT is an open-source MQTT client and broker implementation built on Python's asyncio framework. It uses coroutines to handle high concurrency and implements the full MQTT 3.1.1 protocol specification.

Key features include:

• Support for QoS 0, QoS 1, and QoS 2 message flows.
• Automatic client reconnection upon network loss.
• Authentication via password files (extensible via a plugin system).
• Support for $SYS topics.
• Support for TCP and WebSockets.
• SSL support over both TCP and WebSockets.
• A plugin system for extending functionality.

HBMQTT provides different entry points depending on your use case:

• Running a client or broker via console scripts: Use the provided console scripts for quick deployment or testing.
• Developing a custom MQTT client: Use the HBMQTT API to programmatically connect, publish, and subscribe to a broker.
• Embedding a broker in a Python application: Use the broker reference API to run an MQTT broker directly inside your own Python code.

HBMQTT is an asynchronous MQTT client and broker implementation built on asyncio. It implements the full MQTT 3.1.1 protocol and supports:

• Message Flows: QoS 0, QoS 1, and QoS 2.
• Connectivity: TCP and WebSocket support, including SSL support for both.
• Reliability: Client auto-reconnection on network loss.
• Security: Authentication via password files (extensible via a plugin system).
• Extensibility: A plugin system for adding features like new authentication methods.
• Monitoring: Basic $SYS topics.

HBMQTT provides several standalone console scripts for interacting with MQTT brokers without writing custom code:

• hbmqtt_pub: An MQTT client used for publishing messages to a broker.
• hbmqtt_sub: An MQTT client used for subscribing to topics and retrieving published messages.
• hbmqtt: An autonomous MQTT broker that can be run as a standalone service.

hbmqtt_pub is a command-line MQTT client used to publish messages to a specific topic on an MQTT broker. It follows a syntax similar to mosquitto_pub.

Basic Usage Pattern: hbmqtt_pub --url <BROKER_URL> -t <TOPIC> [MESSAGE_OPTION] [OTHER_OPTIONS]

Message Input Options:

• -m MESSAGE: Send a single message string from the command line.
• -f FILE: Send the contents of a file. The file is read line by line, and a message is published for each line.
• -l: Send messages read from stdin. Each line is a separate message; blank lines are ignored.
• -s: Send the entire content of stdin as a single message.
• -n: Send a null (zero length) message.

hbmqtt_pub --url mqtt://localhost -t sensors/temperature -m 32 -q 1

Install HBMQTT and its associated console scripts (hbmqtt_pub, hbmqtt_sub, and hbmqtt) using pip. These scripts allow you to publish messages, subscribe to topics, and run an autonomous MQTT broker from the command line.

pip install hbmqtt

Use the hbmqtt_sub command-line tool to subscribe to one or more topic patterns and print received messages to standard output. The process runs indefinitely unless stopped.

Key arguments:

• --url: The broker URL.
• -t or --topic: The topic or topic pattern (e.g., /test/#) to subscribe to.
• -n or --number: The maximum number of messages to receive before the tool exits.

Example:

hbmqtt_sub --url mqtt://localhost -t /test/#

HBMQTT is best installed within a Python virtual environment to avoid conflicts with system packages. It requires Python 3.4.3 or Python 3.5.0 (recommended).

(venv) $ pip install hbmqtt

HBMQTT can be installed from PyPI using the standard Python package manager pip.

$ pip install hbmqtt

The hbmqtt command-line script is used to run an MQTT 3.1.1 broker. You can run it with default settings or provide a custom YAML configuration file using the -c flag.

# Run with default configuration
hbmqtt

# Run with a specific YAML configuration file
hbmqtt -c my_config.yaml

The hbmqtt_sub command is a CLI tool used to subscribe to MQTT topics and output received message data. It follows a syntax similar to mosquitto_sub.

To use it, you must provide a broker URL via --url and at least one topic via -t. You can optionally limit the number of messages received using -n or specify the Quality of Service (QoS) using -q or --qos.

# Subscribe to all messages under $SYS/ with QoS 0
hbmqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0

# Subscribe to 10 messages with QoS 2 from /#
hbmqtt_sub --url mqtt://localhost -t /# -q 2 -n 10