mod_pubsub_mqtt/README.markdown
author Kim Alvefur <zash@zash.se>
Sun, 03 Mar 2024 11:23:40 +0100
changeset 5857 97c9b76867ca
parent 5837 58df53eefa28
permissions -rw-r--r--
mod_log_ringbuffer: Detach event handlers on logging reload (thanks Menel) Otherwise the global event handlers accumulate, one added each time logging is reoladed, and each invocation of the signal or event triggers one dump of each created ringbuffer.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     1
---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     2
labels:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     3
- 'Stage-Beta'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     4
summary: 'MQTT interface to Prosody''s pubsub'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     5
...
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     6
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     7
Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     8
------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
     9
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    10
[MQTT](http://mqtt.org/) is a lightweight binary pubsub protocol suited
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    11
to embedded devices. This module provides a way for MQTT clients to
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    12
connect to Prosody and publish or subscribe to local pubsub nodes.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    13
5837
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    14
The module currently implements MQTT version 3.1.1.
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    15
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    16
Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    17
-------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    18
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    19
MQTT has the concept of 'topics' (similar to XMPP's pubsub 'nodes').
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    20
mod\_pubsub\_mqtt maps pubsub nodes to MQTT topics of the form
5837
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    21
`<HOST>/<TYPE>/<NODE>`, e.g.`pubsub.example.org/json/mynode`.
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    22
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    23
The 'TYPE' parameter in the topic allows the client to choose the payload
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    24
format it will send/receive. For the supported values of 'TYPE' see the
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    25
'Payloads' section below.
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    26
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    27
### Limitations
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    28
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    29
The current implementation is quite basic, and in particular:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    30
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    31
-   Authentication is not supported
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    32
-   Only QoS level 0 is supported
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    33
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    34
### Payloads
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    35
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    36
XMPP payloads are always XML, but MQTT does not define a payload format.
5837
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    37
Therefore mod\_pubsub\_mqtt has some built-in data format translators.
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    38
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    39
Currently supported data types:
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    40
5837
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    41
-   `json`: See [XEP-0335](http://xmpp.org/extensions/xep-0335.html) for
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    42
    the format.
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    43
-   `utf8`: Plain UTF-8 text (wrapped inside
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    44
    `<data xmlns="https://prosody.im/protocol/mqtt"/>`)
5837
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    45
-   `atom_title`: Returns the title of an Atom entry as UTF-8 data
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    46
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    47
Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    48
-------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    49
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    50
There is no special configuration for this module. Simply load it on
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    51
your pubsub host like so:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    52
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    53
    Component "pubsub.example.org" "pubsub"
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    54
        modules_enabled = { "pubsub_mqtt" }
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    55
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    56
You may also configure which port(s) mod\_pubsub\_mqtt listens on using
5837
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    57
Prosody's standard config directives, such as `mqtt_ports` and
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    58
`mqtt_tls_ports`. Network settings **must** be specified in the global section
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    59
of the config file, not under any particular pubsub component. The default
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    60
port is 1883 (MQTT's standard port number) and 8883 for TLS connections.
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    61
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    62
Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    63
-------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    64
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    65
  ------- --------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    66
  trunk   Works
5837
58df53eefa28 mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents: 3324
diff changeset
    67
  0.12    Works
1807
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
    68
  ------- --------------