MENU
    How To Build Your First MQTT Connector
    • 30 Jul 2024
    • 5 Minutes to read
    • Contributors

    How To Build Your First MQTT Connector


    Article summary

    How To Build Your First MQTT Connector

    Use this guide to learn how to bring MQTT Topics into Tulip

    In this guide, you will learn:

    • How to set up a MQTT Data source in Tulip

    If you have a functioning MQTT broker that you would like to connect to Tulip, then you are ready to set up an MQTT data source and create your first machine monitoring app.

    Setting Up A MQTT Connection

    MQTT connectors can be created from the connectors page, or machine data source page. The setup process doesn't differ, and a connection created in one place will show up in the other.

    More details on the creation of connectors can be found here: How to Configure a Connector

    Setup as a machine data source

    1. Click into the Machines option under the Shop Floor tab on the Menu Bar.

    image.png

    1. Then, click Machine Data Sources from the left side drawer.

    image.png

    1. Then, click Create Machine Data Source from the Machine Data Sources page.

    image.png

    1. Name your data source, select a Connector Host, select MQTT, and your desired MQTT version.

    image.png

    1. Add the connection details to connect to your broker.

    image.png

    Configuring the MQTT Connection

    Runs On

    Runs on represents the Connector Host that will be responsible for handling the connection to your broker. If your broker is not accessible to the wider internet, an On-Prem Connector Host will be required to access your MQTT broker. Please review the folllowing version requirements prior to testing the Connector Host.

    On Prem Connector Host Version

    Only On Prem Connector Hosts of version 261 (LTS11) or higher support MQTT data sources.
    Only Edge Devices on OS56 or higher Support MQTT data sources.

    MQTT vs. MQTTs

    MQTTs is simply MQTT, with an added layer of security. When MQTTs is selected, SSL/TLS wll be used for communication from the client to the broker. Additionally, MQTTs supports Private Keys, Certificates, and or Trusted CA tokens. With just MQTT selected, only authentication through username and password, or username by client ID are available.

    Client ID

    Client ID is how the Tulip client will identify itself to your MQTT broker. At the simplest level, this is often used for authentication and access control. This can be set to a static value, or set to a random value with the "Auto-generate" flag flipped.

    Keep Alive

    The keep alive is the maximum time, in seconds, that the client would like to keep communication open with the broker. If no messages have been passed from broker to client in that duration, the client will send a message to the broker indicating it is still alive.

    MQTTs Cert Information

    Private Key

    Updates the key property in the Node.js authentication configuration.

    Private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with options.passphrase. Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form. The object form can only occur in an array. object.passphrase is optional. Encrypted keys will be decrypted with object.passphrase if provided, or options.passphrase if it is not.

    Certificate

    Updates the cert property in the Node.js authentication configuration.

    Cert chains in PEM format. One cert chain should be provided per private key. Each cert chain should consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, see ca). When providing multiple cert chains, they do not have to be in the same order as their private keys in key. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.

    Trusted CA

    Updates the ca property in the Node.js authentication configuration.

    Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CAs are explicitly specified using this option. The value can be a string or Buffer, or an Array of strings and/or Buffers. Any string or Buffer can contain multiple PEM CAs concatenated together. The peer's certificate must be chainable to a CA trusted by the server for the connection to be authenticated. When using certificates that are not chainable to a well-known CA, the certificate's CA must be explicitly specified as a trusted or the connection will fail to authenticate. If the peer uses a certificate that doesn't match or chain to one of the default CAs, use the ca option to provide a CA certificate that the peer's certificate can match or chain to. For self-signed certificates, the certificate is its own CA, and must be provided. For PEM encoded certificates, supported types are "TRUSTED CERTIFICATE", "X509 CERTIFICATE", and "CERTIFICATE". See also tls.rootCertificates.

    Testing your Connection

    Hit Test to see if you can successfully connect to the broker.

    image.png

    If the test is successful, then you are ready to set up a machine. Click Save, and then go to the Machine Types page to set up your first category of machines.


    Did you find what you were looking for?

    You can also head to community.tulip.co to post your question or see if others have faced a similar question!


    Was this article helpful?