prosody-modules
58df53eefa28
mod_pubsub_mqtt/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_pubsub_mqtt/README.markdown @ 5857:58df53eefa28

mod_pubsub_mqtt: Update to MQTT 3.1.1
author Matthew Wild <mwild1@gmail.com>
date Wed, 07 Feb 2024 11:57:30 +0000
parent 3320:2333e384409d
comparison
equal deleted inserted replaced
5855:5afc8273c5ef 5857:58df53eefa28
9 9
10 [MQTT](http://mqtt.org/) is a lightweight binary pubsub protocol suited 10 [MQTT](http://mqtt.org/) is a lightweight binary pubsub protocol suited
11 to embedded devices. This module provides a way for MQTT clients to 11 to embedded devices. This module provides a way for MQTT clients to
12 connect to Prosody and publish or subscribe to local pubsub nodes. 12 connect to Prosody and publish or subscribe to local pubsub nodes.
13 13
14 The module currently implements MQTT version 3.1.1.
15
14 Details 16 Details
15 ------- 17 -------
16 18
17 MQTT has the concept of 'topics' (similar to XMPP's pubsub 'nodes'). 19 MQTT has the concept of 'topics' (similar to XMPP's pubsub 'nodes').
18 mod\_pubsub\_mqtt maps pubsub nodes to MQTT topics of the form 20 mod\_pubsub\_mqtt maps pubsub nodes to MQTT topics of the form
19 `HOST/NODE`, e.g.`pubsub.example.org/mynode`. 21 `<HOST>/<TYPE>/<NODE>`, e.g.`pubsub.example.org/json/mynode`.
22
23 The 'TYPE' parameter in the topic allows the client to choose the payload
24 format it will send/receive. For the supported values of 'TYPE' see the
25 'Payloads' section below.
20 26
21 ### Limitations 27 ### Limitations
22 28
23 The current implementation is quite basic, and in particular: 29 The current implementation is quite basic, and in particular:
24 30
25 - Authentication is not supported 31 - Authentication is not supported
26 - SSL/TLS is not supported
27 - Only QoS level 0 is supported 32 - Only QoS level 0 is supported
28 33
29 ### Payloads 34 ### Payloads
30 35
31 XMPP payloads are always XML, but MQTT does not define a payload format. 36 XMPP payloads are always XML, but MQTT does not define a payload format.
32 Therefore mod\_pubsub\_mqtt will attempt to convert data of certain 37 Therefore mod\_pubsub\_mqtt has some built-in data format translators.
33 recognised payload types. Currently supported:
34 38
35 - JSON (see [XEP-0335](http://xmpp.org/extensions/xep-0335.html) for 39 Currently supported data types:
36 the format) 40
37 - Plain UTF-8 text (wrapped inside 41 - `json`: See [XEP-0335](http://xmpp.org/extensions/xep-0335.html) for
42 the format.
43 - `utf8`: Plain UTF-8 text (wrapped inside
38 `<data xmlns="https://prosody.im/protocol/mqtt"/>`) 44 `<data xmlns="https://prosody.im/protocol/mqtt"/>`)
39 45 - `atom_title`: Returns the title of an Atom entry as UTF-8 data
40 All other XMPP payload types are sent to the client directly as XML.
41 Data published by MQTT clients is currently never translated, and always
42 treated as UTF-8 text.
43 46
44 Configuration 47 Configuration
45 ------------- 48 -------------
46 49
47 There is no special configuration for this module. Simply load it on 50 There is no special configuration for this module. Simply load it on
49 52
50 Component "pubsub.example.org" "pubsub" 53 Component "pubsub.example.org" "pubsub"
51 modules_enabled = { "pubsub_mqtt" } 54 modules_enabled = { "pubsub_mqtt" }
52 55
53 You may also configure which port(s) mod\_pubsub\_mqtt listens on using 56 You may also configure which port(s) mod\_pubsub\_mqtt listens on using
54 Prosody's standard config directives, such as `mqtt_ports`. Network 57 Prosody's standard config directives, such as `mqtt_ports` and
55 settings **must** be specified in the global section of the config file, 58 `mqtt_tls_ports`. Network settings **must** be specified in the global section
56 not under any particular pubsub component. The default port is 1883 59 of the config file, not under any particular pubsub component. The default
57 (MQTT's standard port number). 60 port is 1883 (MQTT's standard port number) and 8883 for TLS connections.
58 61
59 Compatibility 62 Compatibility
60 ------------- 63 -------------
61 64
62 ------- -------------- 65 ------- --------------
63 trunk Works 66 trunk Works
64 0.9 Works 67 0.12 Works
65 0.8 Doesn't work
66 ------- -------------- 68 ------- --------------