viam-mqtt-sensor is a module for Viam's Modular Registry that allows integration of Viam platform with MQTT brokers. It enables you to subscribe to a specific topic at an MQTT broker, and receive data conforming the Viam Sensor API. Essentially, it acts as an MQTT client wrapper for Paho MQTT client within the Viam Modular Registry sensor model.

• MQTT Integration: Connects to MQTT brokers and listens for specified topics.
• Data Mapping: Supports customizable data mapping to adapt MQTT payload structures to your needs.
• Configurability: Easily configurable through the Viam App with parameters like broker address, port, topic, and more.
• Client Parameters: Provides options for configuring MQTT client parameters like client ID, clean session, protocol, and transport.
• Authentication: Supports optional username and password for MQTT broker authentication.

This module uses rdk:component:sensor API

After creating your robot at Viam App, at your robots page, open Config -> Components -> Create Compoenent and search for "mqtt" and choose "sensor / mqtt" by tuzumkuru. Choose Add module and then Create after giving you component a custom name. Add proper configuration in attributes section of your newly added component. Configuration is explained below.

Below are all configuration parameters:

{
  "broker_address": "test.mosquitto.org",
  "broker_port": 1883,
  "mqtt_topic": "my_test_topic",
  "mqtt_qos": 0,
  "protocol" : 5,
  "transport" : "tcp",
  "client_id" : "<<client_id>>",
  "clean_session" : true,
  "client_username": "<<username>>",
  "client_password": "<<password>>",
  "mapping_dict": {
    "time": "timestamp",
    "temperature": "payload.temperature",
    "humidity": "payload.humidity"
  }
}

• broker_address: The address of the MQTT broker to connect to (e.g., "test.mosquitto.org").

• broker_port: The port number on the broker to establish the MQTT connection.

• mqtt_topic: The MQTT topic to subscribe to and receive messages.

• mqtt_qos: The Quality of Service (QoS) level for message delivery. Accepted values are 0, 1, or 2.

• protocol: The MQTT protocol version to use. Default is 5. Choose between MQTTv31 = 3, MQTTv311 = 4, MQTTv5 = 5.

• transport: The transport protocol for communication, either "tcp" or "websockets". Default is "tcp".

• client_id: The unique identifier for the MQTT client. Default is autogenerated.

• clean_session: A boolean indicating whether to start a clean session or resume an existing one. Default is true. client_id needs to be set if set to false

• client_username: The username for authenticating the MQTT client. Will try to authenticate if any of client_username or client_password are set.

• client_password: The password for authenticating the MQTT client. Will try to authenticate if any of client_username or client_password are set.

• mapping_dict: A dictionary for mapping incoming MQTT payloads to specific data fields. Keys will be returned as keys, values will be gathered from the message as provided.

The parameters are compatible to the ones used in Paho MQTT Client. You can check the details at https://github.com/eclipse/paho.mqtt.python

Below configuration subscribes to the "my_test_topic" topic at the "test.mosquitto.org" broker. It maps the timestamp to the timestamp field of incoming messages, temperature to the temperature field, and humidity to the humidity field of the payload.

{
  "broker_address": "test.mosquitto.org",
  "broker_port": 1883,
  "mqtt_topic": "my_test_topic",
  "mapping_dict": {
    "timestamp": "timestamp",
    "temperature": "payload.temperature",
    "humidity": "payload.humidity"
  }
}

Remove mapping_dict for a minimal configuration.

Pull requests, issues and all other contributions are welcome.

The following work need to be implemented for better user experience:

• JSON Configuration validation in code
• More compatibility to other authentication modules.
• More generic value mapping that enables data formatting.

Viam is a software platform to enable easy and rapid development of robotics or smart devices: https://www.viam.com

The Eclipse Paho project provides open source implementations of MQTT in a variety of programming languages: https://eclipse.dev/paho/