Update page 'Message Queue Endpoint'

Message-Queue-Endpoint.md

@@ -51,11 +51,117 @@ For preparing the message, we'll use the following settings:
 
 All settings are required except for the `META_DATA_URL`, this parameter is optional.
 
+### Connecting to the MQTT Broker
+First, we will create a MQTT client to connect to the FarmMaps MQTT broker:  
+```python
+#import mqtt client
+from farmmaps import mqtt 
+
+#MQTT connection settings
+CLIENT_ID = 'trekkerdata'
+USER = "trekkerdata"
+PWD = "<your password here>"
+HOST = "farmmaps.awtest.nl"
+PORT = 1883
+KEEPALIVE = 60
+TOPIC = "trekkerdata/sensors"
+
+#set up MQTT client
+mqtt_client = mqtt.create_client(CLIENT_ID, USER, PWD, HOST, PORT, KEEPALIVE)
+```
+
 
 ### Example: Pushing Live Tractor Data
 To create messages and connect to the broker we will need the following settings: 
 
 
+#### Preparing your data as a protobuf message
+Farmmaps uses protobuf to specify a structure for the messages published in MQTT.  
+Protobuf provides a fast way of serializing and unserializing objects, reducing bandwith usage.  
+More information on protobuf can be found at [Google Developer Documentation](https://developers.google.com/protocol-buffers/docs/overview).  
+Python objects can easily be converted to protobuf messages and back (when recieving messages from the broker). 
+
+The message structure for the data can be found in `farmmaps/farmmaps.proto`, and is shown below:
+
+```
+syntax = "proto2";
+
+package farmmaps;
+
+message DataPoint {
+  required string machine_id = 1;
+
+  required int64 ts = 2;
+  required float lat = 3;
+  required float lon = 4;
+  optional float altitude = 5;
+  optional float heading = 6;
+  optional float speed = 7;
+
+  message SensorType {
+    required string key = 1;
+    required float value = 2;
+  }
+
+  repeated SensorType sensors = 8;
+
+  optional string metadata_url = 9;
+}
+```
+This `.proto` file is processed by protobuf and converted to a python class.
+This class can be found in `farmmaps/farmmaps_pb2.py` and should not be edited directly.  
+Edit the proto file and regenerate when you need to change the format.
+In our code we can then use the protobuff class like so:
+
+```python
+#import protobuf class
+from farmmaps import farmmaps_pb2 
+
+# message settings
+META_DATA_URL = 'http://68.183.9.30:8082/v3/meta/sensors'
+BASE_DEV_URN = 'urn:dev:nl.trekkerdata:%s'
+
+#create sample data for message 
+device_id = "ib017"
+timestamp = 1582731928 #epoch timestamp
+longitude = 6.07206584
+latitude = 52.959456183
+altitude = 7.3
+heading = 94.8534
+speed = 0.026
+sensordata = {"spn_898": 0, "spn_518": 0, "spn_513": 50, "spn_190": 1000}
+
+# create empty protobuf message
+msg = farmmaps_pb2.DataPoint()
+
+# assign values to message properties
+msg.machine_id = BASE_DEV_URN % (device_id)
+msg.ts = timestamp
+msg.lon = longitude
+msg.lat = latitude
+msg.altitude = altitude
+msg.heading = heading
+msg.speed = speed
+
+for key, value in sensordata.items():
+    measurement = msg.sensors.add()
+    measurement.key = key
+    measurement.value = value
+
+```
+
+
+In case you want to modify the structure of the object, the `.proto` can be modified, and the python module needs to be regenerated.
+For now, we'll stick with the pregenerated protobuf class: `
+
+
+
+
+## References
+
+*[Protobuf documentation](https://developers.google.com/protocol-buffers/docs/overview)
+*[Paho MQTT documentation](https://www.eclipse.org/paho/clients/python/docs/)
+
 ## [FAQ](#faq) 
 #### How do I install the required Python modules?
 This tutorial requires the `paho-mqtt` and `protobuf` modules.