Software /
code /
prosody-modules
Annotate
mod_pubsub_mqtt/README.markdown @ 5919:095030677ae6
mod_http_admin_api: Support storing free-form text note with invitations
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Mon, 29 Apr 2024 17:49:19 +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 ------- -------------- |