This documentation page provides the basics on how to access the MQTT endpoint of FarmMaps, using Python code for examples.
Even when using a different programming language, the same workflow can be followed (as long as there's a MQTT client and a Protobuf library for the language you are using). FarmMaps provides an MQTT endpoint to allow your application to send signals to FarmMaps, and listen for events. These signals are collected in a "message queue". If you are not familiar with MQTT or message queues in general, please see the short explanation below.
#### What is a message queue? (skip ahead if familiar)
A message queue is commonly used to make software programs able to send messages between eachother, and thereby making it easy for data to flow from one program into another. There are many variants of message queues, some popular names are Apache Kafka, MQTT and RabbitMQ.
In message queue systems there is usually one central "hub" called the broker or **"message broker"**. This broker holds all the messages. Usually, the messages are organised in groups called **"topics"**.
Now, there are two things that external services can do.
* An external service (like a sensor) could **publish a message to a certain topic**. For example, a temperature sensor would publish the temperature at a specific time and location to the "temperatureMeasurements" topic.
* An external service can **"subscribe" to this topic** by connecting to the broker. This service will then recieve every temperature measurement.
When the subscribed service temporarily disconnects from the broker, it will not recieve any messages, but the messages will remain stored at the broker. Depending on configuration, messages will be kept longer or shorter, or be deleted after they recieve the subscribers but the intent is always to ensure the messages get from the **publisher** to the **subscriber**.
Setting applications up like this makes things a lot more flexible than connecting systems directly and provides a central point to manage the communication between applications.
#### What is protobuf?
To quote the Google Documentation:
> Protocol buffers are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler.
> You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages.
More information can be found in the [protobuf documentation](https://developers.google.com/protocol-buffers/docs/overview)
### Prerequisites
To follow along with the examples, you need:
* Access to the FarmmMaps MQTT broker (user, password), these can be requested **here**
* To have Python 3.7 or higher installed.
* To come up with a unique identifier for your sensors.
Generally the URN is composed of the company or brand name and a device serial number like so: `urn:dev:<company/brand-name>:<device-serial-number>`
To run the python example code you also need to install the `paho-mqtt` and the `protobuf` modules.
These can be installed with the following commands:
