Add MQTT publish example README

diff --git a/mqtt_pub/README b/mqtt_pub/README
new file mode 100644 (file)
index 0000000..181b390
--- /dev/null
+++ b/mqtt_pub/README
@@ -0,0 +1,48 @@
+MQTT protocol example, Publisher part
+
+Copyright 2019 Nathael Pajani <nathael.pajani@ed3l.fr>
+
+
+/* ****************************************************************************
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ *************************************************************************** */
+
+This example shows the support of the publisher part ot he MQTT protocol
+implementation provided in lib/protocols/mqtt.c
+
+This implementation has been designed to implement only the MQTT packet
+building and decoding, as specified by the MQTT protocol specification, and
+leave all the MQTT message flow implementation to the application, as it is not
+part of the MQTT protocol specification and is application dependent.
+
+One can thus implement either a simple "single in-flight packet" mechanism for
+very lightweight applications or complex multi-packet mechanisms.
+
+This example uses the simple "single in-flight packet" mechanism to publish
+the temperature read from the onboard temperature sensor.
+
+As MQTT requires a lossless, ordered, addressable transport protocol, we used a
+simple protocol over serial communication, which would allow communication of
+multiple "clients" over an RS485 serial link.
+This protocol is decoded by the bridge example provided in host/mqtt_bridge,
+which simply transfers the MQTT part of received packets on a TCP socket
+connected to an MQTT message broker, and encapsulate MQTT packets received on
+ths socket in our simple protocol before sending them on the serial link.
+
+This implementation is very simple, and does not try to resend packets which
+did not get acked (QoS 0) even if they are sent with a QoS of 1 in order to
+test and demonstrate the acknowledge part of publish messages.
+It will be improved some day in order to implement full QoS support and test
+QoS level 2.