From 560e2fda9901031b73b743c0470889225c86d1b7 Mon Sep 17 00:00:00 2001
From: Dale LaBossiere <dlaboss@us.ibm.com>
Date: Tue, 28 Feb 2017 14:13:32 -0500
Subject: [PATCH 1/2] [Edgent-176] document MqttDevice's MQTT messsage format.

---
 .../connectors/mqtt/iot/MqttDevice.java       | 35 ++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java b/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java
index f2836075..24d26ba6 100644
--- a/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java
+++ b/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java
@@ -43,9 +43,14 @@ Licensed to the Apache Software Foundation (ASF) under one
  * the {@link MqttStreams} connector.
  * <p>
  * The connector doesn't presume a particular pattern for 
- * Device MQTT "event" topic and "command" topics though default
+ * Device MQTT "event" and "command" topics though default
  * patterns are provided.
  * <p>
+ * The MQTT message content for device events and device messages must be JSON,
+ * but the contents of the JSON are under the control of the collaborating MQTT clients.
+ * See {@link #commands(String...)} and {@link #events(TStream, String, int) events()}
+ * for a description of how MQTT messages are converted to and from stream tuples.
+ * <p>
  * Connector configuration Properties fall into two categories:
  * <ul>
  * <li>MQTT Device abstraction properties</li>
@@ -207,6 +212,15 @@ public MqttConfig getMqttConfig() {
         return mqttConfig;
     }
 
+    /**
+     * {@inheritDoc}
+     * 
+     * <p>The event is published to the configured MQTT {@code mqttDevice.event.topic.pattern},
+     * as described in the above class documentation, substituting the value returned
+     * by the {@code eventId} function for "{EVENTID}" in the pattern.
+     * The MQTT message's payload is the JSON representation
+     * of the JsonObject stream tuple.
+     */
     @Override
     public TSink<JsonObject> events(TStream<JsonObject> stream, Function<JsonObject, String> eventId,
             UnaryOperator<JsonObject> payload, Function<JsonObject, Integer> qos) {
@@ -218,11 +232,30 @@ public TSink<JsonObject> events(TStream<JsonObject> stream, Function<JsonObject,
         return connector.publish(stream, topic, payloadFn, qos, jo -> retainEvents);
     }
 
+    /**
+     * {@inheritDoc}
+     * 
+     * <p>The event is published to the configured MQTT {@code mqttDevice.event.topic.pattern},
+     * as described in the above class documentation, substituting the {@code eventId} for 
+     * "{EVENTID}" in the pattern.
+     * The MQTT message's payload is the JSON representation
+     * of the JsonObject stream tuple.
+     */
     @Override
     public TSink<JsonObject> events(TStream<JsonObject> stream, String eventId, int qos) {
         return events(stream, jo -> eventId, jo -> jo, jo -> qos);
     }
 
+    /**
+     * {@inheritDoc}
+     * 
+     * <p>
+     * Subscribes to the configured MQTT {@code mqttDevice.command.topic.pattern}
+     * as described in the above class documentation.
+     * The received MQTT message's payload is required to be JSON.  
+     * The message's JSON payload is converted to a JsonObject and
+     * set as the {@code payload} key's value in the stream tuple JsonObject.
+     */
     @Override
     public TStream<JsonObject> commands(String... commands) {
         TStream<JsonObject> all = allCommands();

From c97ee1e2c8dba09a8075a92ec64da1bb1be641ad Mon Sep 17 00:00:00 2001
From: Dale LaBossiere <dlaboss@us.ibm.com>
Date: Tue, 28 Feb 2017 14:22:14 -0500
Subject: [PATCH 2/2] more tweaks

---
 .../org/apache/edgent/connectors/mqtt/iot/MqttDevice.java   | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java b/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java
index 24d26ba6..c0383273 100644
--- a/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java
+++ b/connectors/mqtt/src/main/java/org/apache/edgent/connectors/mqtt/iot/MqttDevice.java
@@ -46,8 +46,10 @@ Licensed to the Apache Software Foundation (ASF) under one
  * Device MQTT "event" and "command" topics though default
  * patterns are provided.
  * <p>
- * The MQTT message content for device events and device messages must be JSON,
- * but the contents of the JSON are under the control of the collaborating MQTT clients.
+ * The MQTT message content for device events and device commands must be JSON.
+ * The contents of the JSON are under the control of the collaborating MQTT clients.
+ * Typically a device to defines its event and command schemas
+ * and the other clients to adapt accordingly.
  * See {@link #commands(String...)} and {@link #events(TStream, String, int) events()}
  * for a description of how MQTT messages are converted to and from stream tuples.
  * <p>