Pelix MQTT client service

Note

This reference card represents the current state of the MQTT service, which is subject to change.

Since the initial version of this service (in 2014), the usage and API of this service is not clear enough. Issue #18, created at that time, can be a place to discuss about enhancements or removal of this service.

Pelix provides a service to be notified of MQTT messages from different servers. It abstracts the underlying MQTT library (Eclipse Paho) to ensure the API stays the same despite library upgrades or changes.

MQTT service

The MQTT service provides the pelix.services.MqttConnectorFactory specification (named pelix.mqtt.factory).

You can use this service to publish a message to all connected brokers at once using its publish() method.

Configuring brokers

The Pelix MQTT service is configured using Configuration Admin, with the mqtt.connector factory PID.

The configuration can contain the following entries:

Property

Default

Description

host

Broker host name (mandatory)

port

1883

Broker port

keepalive

60

Connection keepalive (in seconds)

For now, the MQTT service doesn’t support other configuration properties. Issue #18 can be used to discuss about further developments of that service, for example to support TLS configuration, authentication, etc.

MQTT connections

The MQTT service registers a service of specification named pelix.mqtt.connection for each broker it connects to. This service allows to publish a message to its specific broker.

There is no public typed specification for that service yet as it depends on types from the Paho libary. The current protected specification is pelix.services.mqtt._MqttConnection and is subject to change.

Each service has the following properties:

Property

Type

Description

id

string

Broker configuration PID

host

string

Broker host name

port

int

Broker port

Setting up listeners

The MQTT service follows the whiteboard pattern: listeners are declared as services providing the pelix.services.MqttListener specification (name: pelix.mqtt.listener).

This service can hold the pelix.mqtt.topics containing either a string or a list of strings: the MQTT service will subscribe to those topics to all the brokers it is or will be connected to. The topics can be given as MQTT topic filter strings. The list can be updated dynamically: the MQTT service will un/subscribe accordingly.

API

class pelix.services.MqttConnectorFactory(*args, **kwargs)

Specification of an MQTT connector factory

publish(topic: str, payload: bytes, qos: int = 0, retain: bool = False, pid: str | None = None) → None

Publishes an MQTT message

Parameters:

  • topic – Message topic

  • payload – RAW message content

  • qos – MQTT quality of service (0 by default)

  • retain – Message must be retained

  • pid – Optional connection PID

Raises:

KeyError – Invalid PID

class pelix.services.MqttListener(*args, **kwargs)

Specification of an MQTT listener

handle_mqtt_message(topic: str, payload: bytes, qos: int) → None

Notification of a new message

Parameters:

  • topic – Message topic

  • payload – Raw message payload

  • qos – Message Quality of Service

class pelix.services.mqtt._MqttConnection

Represents a connection to a specific broker.

Warning

This API is subject to changes

publish(topic: str, payload: bytes, qos: int = 0, retain: bool = False) → paho.MQTTMessageInfo:

Publishes an MQTT message to the connected broker

Parameters:

  • topic – Topic to send the message on

  • payload – Raw message payload

  • qos – Message Quality of service:

  • retain – If true, ask the broker to retain the message for that topic

Returns:

A Paho message information