mqtt: add new experimental protocol

Closes #5173

1 files changed, 61 insertions, 0 deletions

diff --git a/docs/MQTT.md b/docs/MQTT.md
new file mode 100644
index 000000000..1c7b678aa
--- /dev/null
+++ b/docs/MQTT.md
@@ -0,0 +1,61 @@
+# MQTT in curl
+
+## Experimental!
+
+MQTT support in curl is considered **EXPERIMENTAL** until further notice. It
+needs to be enabled at build-time. See below.
+
+After the initial merge, further development and tweaking of the MQTT support
+in curl will happen in the master branch using pull-requests, just like
+ordinary changes.
+
+Experimental support for MQTT means that we **do not guarantee** that the
+current protocol functionality will remain or remain this way going forward.
+There are no API or ABI promises for experimental features as for regular curl
+features.
+
+Do not ship anything with this enabled.
+
+## Build
+
+    ./configure --enable-mqtt
+
+## Usage
+
+A plain "GET" subscribes to the topic and prints all published messages.
+Doing a "POST" publishes the post data to the topic and exits.
+
+Example subscribe:
+
+    curl mqtt://host/home/bedroom/temp
+
+Example publish:
+
+    curl -d 80 mqtt://host/home/bedroom/dimmer
+
+## What does curl deliver as a response to a subscribe
+
+It outputs two bytes topic length (MSB | LSB), the topic followed by the
+payload.
+
+## Caveats
+
+Remaining limitations:
+ - No username support
+ - Only QoS level 0 is implemented for publish
+ - No way to set retain flag for publish
+ - No username/password support
+ - No TLS (mqtts) support
+ - Naive EAGAIN handling won't handle split messages
+
+## Work
+
+1. Write a mqtt server for the test suite
+2. Create a few tests verifying the existing mqtt functionality
+3. Work on fixing some of the worst limitations - with accompanying tests
+4. Consider replacing the client-side MQTT code with wolfMQTT
+
+## Credits
+
+The initial MQTT patch was authored by Björn Stenberg. This work is built upon
+that patch and has been expanded since.