Software / code / prosody-modules
Annotate
mod_pubsub_mqtt/README.markdown @ 5931:d194d1012fd3
Updating dox for mod_rest. Ideas expressed / clarified:
1) Making clear that mod_rest isn't to be installed under VirtualHosts AND as a component.
2) Understanding some of the implications of this choice:
A) Changes to user authentication
B) How it affects subdomains
3) More consistent use of domain names for clarity.
4) Using different heading sizes to show scope of section.
Essentially, I added all the tidbits I had to clarify in getting this to work in my
own example.
| author | Ben Smith <bens@effortlessis.com> |
|---|---|
| date | Mon, 13 May 2024 13:25:13 -0700 |
| 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 ------- -------------- |
