Configuring MQTT

Contents

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.

Setting up Your Endpoint Broker

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 sh -c "echo '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"

Expected result:

Device Setup

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.

Direct-Connect Mode

On the AutoPi cloud portal (my.autopi.io for private customers, <company_name>.autopi.io for business customers) go to Device > 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.

Broker-Bridge Mode

On the AutoPi cloud portal (my.autopi.io for private customers, <company_name>.autopi.io for business customers) go to Device > 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

note

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.

Example:

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.

note

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"

Adding MQTT As a Returner to Data Sources

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
PID data	Loggers	obd/<LOGGER_NAME>
CAN data	Service	obd/<LOGGER_NAME>
GPS location	Service	track/pos
Accelerometer readings	Service	acc/xyz
Voltage	Service	spm/bat
Events	Service	reactor
Device Temperature	Job	rpi/temp

Loggers

Go to Device > 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.

Services

A service can serve as a data source in 2 ways: through workers and through reactors. Most commonly you will want to retrieve CAN data. For this, go to Device > 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.

Data point	Source
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

Jobs

Go to Device > 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.

Final Result

If everything is working correctly, you should be receiving data on your broker now: