MQTT Broker
The MQTT Broker is a server that allows publishing and subscribing to MQTT topics.
It's meant for sensors and devices at Protospace to communicate publicly and for fun.
Theory
MQTT is a lightweight, publish-subscribe network protocol that transports messages between devices[1]. It's low power and ideal for microcontrollers hooked up to sensors and devices.
Messages are just strings of text like "hello world" or "12.3".
Messages are sent to arbitrary topics like pets/dogs/charlie. By convention slashes separate levels of category that we all agree on.
When a message is sent to a topic, all devices that are subscribed to that topic receive the message.
Topics aren't really created, they just exist as soon as a message is sent to them.
Normally messages aren't stored anywhere. They just get sent out and received by whoever happens to be listening to the same topic. However, we automatically log messages to the sensors/ topics using Telegraf + InfluxDB.
Topics
MQTT topics consist of categories separated by slashes. Here are some topics currently in use:
- sensors/air/0/temp
- sensors/air/0/pm25
- sensors/air/1/temp
- sensors/air/1/pm25
You can use + as a wildcard to match a single hierarchy when subscribing. For example, sensors/air/+/temp will subscribe to all air temperature sensors.
You can use # as a wildcard to match all remaining hierarchies. It must be the last character. For example, sensors/# will subscribe to all sensors.
Access
Server / host: webhost.protospace.ca
Port: 8883
Reading
Anyone can read any topic. Don't send anything private to the broker.
- username: reader
- password: cf503b99ba8cb0103da8884f09694fcd60ba1f2d
Writing
Ask Tanner for write access to the broker. We want to make sure you don't accidentally screw up sensor data.
- username: writer
- password: [ask Tanner]
Usage
Please send messages to a topic starting with test/ or firstname/ while developing. This makes sure you don't screw up logged sensor data. For example:
- test/air/2/temp
- tanner/air/2/temp
After testing your device, show Tanner and we can make sure it's ready and add the data to the Protospace IoT API so others can use it.
The last thing you do should be to change the topic to the real one before deploying the device. Make sure you don't commit this code change to prevent others from screwing up your logged sensor data if they run your code.
Please don't send values more than once per minute to prevent filling up the database.
CLI Example
These examples use the mosquitto client program.
Reading:
$ mosquitto_sub --capath /etc/ssl/certs/ -h webhost.protospace.ca -p 8883 -u reader -P cf503b99ba8cb0103da8884f09694fcd60ba1f2d -t sensors/air/0/temp
... wait 60 seconds and a number should appear.
Writing:
$ mosquitto_pub --capath /etc/ssl/certs/ -h webhost.protospace.ca -p 8883 -u writer -P [ask Tanner] -t test -m 'hello world'
On MacOS, you might need to copy /etc/ssl/certs/ from a Linux computer to somewhere on your machine.
Arduino Example
Please see https://github.com/Protospace/telemetry/blob/master/air_quality/air_quality.ino for example MQTT sensor code.
Technical Info
The MQTT Broker is hosted on the Webhost VPS managed by Tanner. The same one that's running the main Website and the Wiki.