Software / code / prosody-modules
Annotate
mod_pubsub_mqtt/README.markdown @ 5877:97c9b76867ca
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.
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Sun, 03 Mar 2024 11:23:40 +0100 |
| parent | 5857:58df53eefa28 |
| rev | line source |
|---|---|
| 1803 | 1 --- |
| 2 labels: | |
| 3 - 'Stage-Beta' | |
| 4 summary: 'MQTT interface to Prosody''s pubsub' | |
| 5 ... | |
| 6 | |
| 7 Introduction | |
| 8 ------------ | |
| 9 | |
| 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 | |
| 12 connect to Prosody and publish or subscribe to local pubsub nodes. | |
| 13 | |
|
5857
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
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:
3320
diff
changeset
|
15 |
| 1803 | 16 Details |
| 17 ------- | |
| 18 | |
| 19 MQTT has the concept of 'topics' (similar to XMPP's pubsub 'nodes'). | |
| 20 mod\_pubsub\_mqtt maps pubsub nodes to MQTT topics of the form | |
|
5857
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
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:
3320
diff
changeset
|
22 |
|
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
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:
3320
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:
3320
diff
changeset
|
25 'Payloads' section below. |
| 1803 | 26 |
| 27 ### Limitations | |
| 28 | |
| 29 The current implementation is quite basic, and in particular: | |
| 30 | |
| 31 - Authentication is not supported | |
| 32 - Only QoS level 0 is supported | |
| 33 | |
| 34 ### Payloads | |
| 35 | |
| 36 XMPP payloads are always XML, but MQTT does not define a payload format. | |
|
5857
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
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:
3320
diff
changeset
|
38 |
|
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
diff
changeset
|
39 Currently supported data types: |
| 1803 | 40 |
|
5857
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
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:
3320
diff
changeset
|
42 the format. |
|
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
diff
changeset
|
43 - `utf8`: Plain UTF-8 text (wrapped inside |
| 1803 | 44 `<data xmlns="https://prosody.im/protocol/mqtt"/>`) |
|
5857
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
diff
changeset
|
45 - `atom_title`: Returns the title of an Atom entry as UTF-8 data |
| 1803 | 46 |
| 47 Configuration | |
| 48 ------------- | |
| 49 | |
| 50 There is no special configuration for this module. Simply load it on | |
| 51 your pubsub host like so: | |
| 52 | |
| 53 Component "pubsub.example.org" "pubsub" | |
| 54 modules_enabled = { "pubsub_mqtt" } | |
| 55 | |
| 56 You may also configure which port(s) mod\_pubsub\_mqtt listens on using | |
|
5857
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
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:
3320
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:
3320
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:
3320
diff
changeset
|
60 port is 1883 (MQTT's standard port number) and 8883 for TLS connections. |
| 1803 | 61 |
| 62 Compatibility | |
| 63 ------------- | |
| 64 | |
| 65 ------- -------------- | |
| 66 trunk Works | |
|
5857
58df53eefa28
mod_pubsub_mqtt: Update to MQTT 3.1.1
Matthew Wild <mwild1@gmail.com>
parents:
3320
diff
changeset
|
67 0.12 Works |
| 1803 | 68 ------- -------------- |
