This guide covers configuring a basic MQTT broker on your Linux server, as well as configuring an AutoPi device to use MQTT as a data returner.
This step covers installing and configuring a broker on your server instance. This guide uses a 3-rd party hosted Virtual Machine running Debian 11.
Install the broker:
$ sudo apt install mosquitto mosquitto-clients
Set up the broker to allow non-protected connections. When releasing to production, make sure to change these settings, as running an open MQTT broker is a major security risk.
$ sudo echo -e 'allow_anonymous true\nlistener 1883 0.0.0.0' > /etc/mosquitto/conf.d/mosquitto.conf
Restart to load new configuration
$ sudo systemctl restart mosquitto.service
Test the configuration locally. Subscribe to the local broker and check if you can see the messages.
In terminal 1:
$ mosquitto_sub -h localhost -t test/my_topic/#
In terminal 2:
$ mosquitto_pub -h localhost -t test/my_topic -m "Test data from a local source"
Generally, there are 2 ways in which you might be setting up your device. Either in direct-connect mode, or in broker-bridge mode. Direct-connect mode is what you might imagine a basic client-server setup, where a client sends/publishes data to a server. Broker-bridge mode is a bit more complicated, since it includes another MQTT broker running on the device, connected to your server through a bridge.
While direct-connect mode is easier to set up, it's worth noting that in case the device loses internet connectivity, the data generated during that time will be lost. This is not the case with the broker-bridge mode, which will buffer the data, until the connectivity is restored.
On the AutoPi cloud portal (my.autopi.io for private customers, <company_name>.autopi.io for business customers) go to [Advanced > Settings > MQTT]. Modify the following settings:
- Returner > Enabled: True
- Returner > host: <host>
- Returner > port: <port>
Now set up an mqtt returner on a data point you know you're getting data from (voltage readings or GPS for example). See below on how to do this. After you've done this, you should be seeing data on your MQTT broker.
On the AutoPi cloud portal (my.autopi.io for private customers, <company_name>.autopi.io for business customers) go to [Advanced > Settings > MQTT]. Note that the settings under [Broker > ...] effect only the broker, and not the client, so if you are trying to set up direct-connect mode, these are not the settings you are looking for. Modify the following settings:
- Broker > Install: Mosquitto v1.x (Or newer if available)
- Broker > Custom > Configuration:
- connection <connection_name>
- address <host>:<port>
- topic # out 1 "" <topic_name>/
- bridge_attempt_unsubscribe false
- keepalive_interval 15
- notifications false
- restart_timeout 10
- cleansession false
- max_queued_messages 10000
- autosave_interval 300
- queue_qos0_messages true
- try_private false
- bridge_protocol_version mqttv311
- max_inflight_messages 10
- Returner > Enabled: True
Some of these settings are not a necessity, but these are the settings we've seen provide best reliability and performance. The meaning of these settings can be found on the Eclipse Mosquitto website. The settings you add in [Broker > Custom > Configuration] go directly into a Mosquitto configuration file: /etc/mosquitto/conf.d/custom.conf.
Save and sync. Once synced, test if the connection has been made correctly. Run the following command in the cloud terminal:
$ cmd.run 'mosquitto_pub -h localhost -t test/my_topic -m "my test data"'
If the data can be seen in the shell where you've subscribed to the topic, then the bridge has been configured correctly.
If the command is not found, it can be installed from apt (it is not used outside of this test).
$ cmd.run "apt install -y mosquitto-clients"
This section covers adding the MQTT returner to the 3 main data sources: loggers, services and jobs. Which data points can be retrieved from each source can be seen in the following table.
|Data point||Source||MQTT Topic|
Go to [Car Explorer > Loggers]
For each logger of Type "OBD-II PID" add the mqtt returner by selecting the logger, clicking Advanced, and selecting mqtt in the Returner dropdown. Then click save.
A service can serve as a data source in 2 ways: through workers and through reactors. Most commonly you'll want to retrieve CAN data. For this, go to [Advanced > Services] and add the mqtt returner to the obd_manager's can_logger worker, as shown below:
The other Service sourced data points and their locations can be found in the following table. The steps described for CAN data can be repeated for each of these.
|CAN data||obd_manager > workers > can_logger|
|GPS location||gnss_manager > workers > poll_logger|
|Accelerometer readings||acc_manager > workers > xyz_logger|
|Voltage||spm_manager > workers > _battery_checker|
|Events||event_reactor > reactors > cache_events|
Go to [Advanced > Jobs] and set returner to each job as mqtt. As of time of writing, it is only possible to to have a single returner per job, so it's not possible to send the data to both MQTT and the AutoPi Cloud.
If everything is working correctly, you should be receiving data on your broker now: