Documentation

PLEASE NOTE: This document applies to latest version and not to the latest stable release v2.21

Documentation for other releases can be found by using the version selector in the top right of any doc page.

mqtt

MQTT publish/subscribe messaging for IoT communication.

Publish and subscribe to MQTT topics with support for Quality of Service levels, message retention, and authentication. Essential for IoT device scripting, sensor data publishing, home automation, and edge computing.

Attributes

check_mode:
  support: full

Parameters

Parameter	Required	Type	Description
topic	true	string	MQTT topic to publish to or subscribe from.
payload		string	Message content to publish (required for state=publish).
qos		integer	Quality of Service level (0, 1, or 2). [default: `0`]
retain		boolean	Whether to retain the message on the broker. [default: `false`]
broker	true	string	MQTT broker hostname or IP address.
port		integer	MQTT broker port. [default: `1883`]
username		string	Username for MQTT authentication.
password		string	Password for MQTT authentication.
client_id		string	MQTT client identifier. [default: `rash-<uuid>`]
state			Operation state: publish or subscribe. [default: `publish`]
subscribe_timeout		integer	Timeout in seconds to wait for messages when subscribing. [default: `5`]
max_messages		integer	Maximum number of messages to collect when subscribing. [default: `1`]
tls		boolean	Enable TLS/SSL connection (use port 8883 for secure MQTT). [default: `false`]

Examples

- name: Publish sensor reading
  mqtt:
    topic: sensors/temperature
    payload: "22.5"
    broker: localhost

- name: Publish with QoS and retain
  mqtt:
    topic: devices/status
    payload: '{"online": true}'
    broker: mqtt.example.com
    port: 1883
    qos: 1
    retain: true

- name: Publish with authentication
  mqtt:
    topic: home/living_room/thermostat
    payload: "21.0"
    broker: mqtt.example.com
    username: "{{ mqtt_user }}"
    password: "{{ mqtt_pass }}"
    client_id: rash-thermostat

- name: Subscribe to a topic
  mqtt:
    topic: sensors/#
    broker: localhost
    state: subscribe
  register: mqtt_messages