annotate mod_pubsub_mqtt.wiki @ 506:ad9071a3062c

Created wiki page through web user interface.
author NKNeumann@gmail.com
date Fri, 20 Feb 2015 18:30:17 +0000
parents bec04c8c56f1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
405
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
1 #summary MQTT interface to Prosody's pubsub
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
2 #labels Stage-Beta
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
3
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
4 = Introduction =
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
5
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
6 [http://mqtt.org/ MQTT] is a lightweight binary pubsub protocol suited to embedded devices. This module provides a way for MQTT clients to connect to Prosody and publish or subscribe to local pubsub nodes.
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
7
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
8 = Details =
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
9
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
10 MQTT has the concept of 'topics' (similar to XMPP's pubsub 'nodes'). mod_pubsub_mqtt maps pubsub nodes to MQTT topics of the form `HOST/NODE', e.g. `pubsub.example.org/mynode`.
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
11
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
12 == Limitations ==
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
13 The current implementation is quite basic, and in particular:
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
14
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
15 * Authentication is not supported
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
16 * SSL/TLS is not supported
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
17 * Only QoS level 0 is supported
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
18
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
19 == Payloads ==
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
20 XMPP payloads are always XML, but MQTT does not define a payload format. Therefore mod_pubsub_mqtt will attempt to convert data of certain recognised payload types. Currently supported:
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
21
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
22 * JSON (see [http://xmpp.org/extensions/xep-0335.html XEP-0335] for the format)
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
23 * Plain UTF-8 text (wrapped inside `<data xmlns="https://prosody.im/protocol/mqtt"/>`)
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
24
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
25 All other XMPP payload types are sent to the client directly as XML. Data published by MQTT clients is currently never translated, and always treated as UTF-8 text.
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
26
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
27 = Configuration =
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
28
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
29 There is no special configuration for this module. Simply load it on your pubsub host like so:
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
30
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
31 {{{
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
32 Component "pubsub.example.org" "pubsub"
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
33 modules_enabled = { "pubsub_mqtt" }
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
34 }}}
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
35
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
36 You may also configure which port(s) mod_pubsub_mqtt listens on using Prosody's standard config directives, such as `mqtt_ports`. Network settings *must* be specified in the global section of the config file, not under any particular pubsub component. The default port is 1883 (MQTT's standard port number).
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
37
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
38 = Compatibility =
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
39 || trunk || Works ||
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
40 || 0.9 || Works ||
bec04c8c56f1 Created wiki page through web user interface.
MWild1@gmail.com
parents:
diff changeset
41 || 0.8 || Doesn't work ||