Versions Compared

Old Version 20

changes.mady.by.user Wes Johnson

Saved on

compared with

New Version 21

changes.mady.by.user Chad Kienle

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Once in the configuration section there are three tabs: Servers, Advanced, and Namespaces.  Each of these tabs is described in detail in the following sections.

General

The first tab contains general settings which allows one to enable/disable the module, configure Application ID Filters, and Cirrus Link Chariot Access Settings.  The Chariot access settings settings are used in conjunction with a Cirrus Link Chariot deployment and will be provided when purchasing Chariot Cloud services.

Main

  • Enabled
    • Whether or not the MQTT Engine module is enabled and connecting to configured MQTT Servers

...

    • .
  • Primary Host ID
    • The primary host ID to use for 'state' checks.  These checks are used to ensure that the primary backend MQTT Engine client remains connected.  If the primary host ID is set, MQTT Engine will publish it's connection state on a topic that contains the Primary Host ID.  In the event that MQTT Engine becomes disconnected from the server, a death certificate will be published on the same topic, setting the state to 'offline'.  Any connecting client that subscribes on the state topic will then be notified of the MQTT Engine state and walk to the next server is MQTT Engine is offline.
  • Group ID Filters
    • A comma seperated list of group IDs to ignore.  If no group IDs are to be ignored, this should be left empty

Chariot Access

  • Chariot Cloud Access Key
    • If using Cirrus Link's Chariot platform, this is the provided Access Key
  • Chariot Cloud Secret Key
    • If using Cirrus Link's Chariot platform, this is the provided Secret Key

Miscellaneous

  • Block Node Commands
    • Whether or not to block outgoing commands from MQTT Engine to Edge Nodes. This is true by default and provides a security mechanism for preventing accidental outgoing commands from MQTT Engine.
  • Block Device Commands
    • Whether or not to block outgoing commands from MQTT Engine to Devices. This is true by default and provides a security mechanism for preventing accidental outgoing commands from MQTT Engine.
  • File Policy
    • The policy for handling Files contained within a Sparkplug payload.
      • Ignore: The default policy. The file will be ignored.
      • Store: The file will be stored to the local file system in the directory specified by the File Location field.  A Tag will be created with a String value representing the file URI.
  • File Location
    • The directory to store the files when using the Store policy described above.

Image Added

Servers

The second The first tab is a list of MQTT Servers that MQTT Engine should connect to.  By default, MQTT Engine is configured to connect to the local MQTT Distributor based MQTT Server.  It is set up to connect to localhost, port 1883, using the default username/password pair of admin/changeme.  Out of the box MQTT Engine will work with MQTT Distributor and its default configuration.  The connection status of each server can be seen in the 'Status' column.  Clicking on the 'Create new MQTT Server' link will bring up the following form for adding a new MQTT Server setting.

Image RemovedImage Added

Additional or alternative MQTT Servers can be configured in MQTT Engine.  Often times more than one will be configured to handle fail-over in redundant or geographically distributed systems.  The configuration options for servers are listed below.

Main

  • Name
    • This is the friendly name of the MQTT Server used to easily identify it
  • URL
    • This is the URL of the MQTT server.  Its format is as follows: [protocol]://[location]:[port].  Each of these are shown below
      • protocol - Either tcp or ssl
      • location - The server location.  e.g. localhost, myserver.chariot.io, mydomain.com, etc
      • port - The port the MQTT Server is listening on.  Generally this is 1883 if using TCP or 8883 if using SSL
  • Server Type
    • This is the type of MQTT Server to connect to
      • Chariot - If connecting to a Cirrus Link Chariot on-premise or Chariot cloud based MQTT Server
      • MQTT Distributor - If connecting to a Ignition MQTT Distributor server
      • Third Party - If connecting to a third party 3.1.1 compliant MQTT Server
    Client ID
    • Optional MQTT client ID to use.  If specified this will be used in the MQTT Engine connect packet when connecting to the server.  If left blank, a random client ID will be create of the form 'IgnitionTarget-xxxxxxxx-xxxx-xxxx
  • Username
    • Optional MQTT username to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it
  • Password
    • Optional MQTT password to use in the MQTT connect packet.  This is required if the MQTT Server to connect to requires it
  • Certificates
    • The server certificates to use if required.  These are generally only required when connecting using TLS and the MQTT server does not have a genuine certificate issued by a trusted certificate authority.

Clicking on the 'Create new MQTT Server...' link will bring up the following form to add a new Server.

Image Removed

Advanced

...

Settings

...

  • Client ID
    • Optional MQTT client ID to use.  If specified this will be used in the MQTT Engine connect packet when connecting to the server.  If left blank, a random client ID will be create of the form 'IgnitionTarget-xxxxxxxx-xxxx-xxxx
  • Keep Alive
    • The MQTT client keep alive time (in seconds).


Clicking on the 'Create new MQTT Server...' link will bring up the following form to add a new Server.

Image Added

These are the advanced settings:

  • Primary Host ID
    • The primary host ID to use for 'state' checks.  These checks are used to ensure that the primary backend MQTT Engine client remains connected.  If the primary host ID is set, MQTT Engine will publish it's connection state on a topic that contains the Primary Host ID.  In the event that MQTT Engine becomes disconnected from the server, a death certificate will be published on the same topic, setting the state to 'offline'.  Any connecting client that subscribes on the state topic will then be notified of the MQTT Engine state and walk to the next server is MQTT Engine is offline.
  • Group ID Filters
    • A comma seperated list of group IDs to ignore.  If no group IDs are to be ignored, this should be left empty
  • Chariot Cloud Access Key
    • If using Cirrus Link's Chariot platform, this is the provided Access Key
  • Chariot Cloud Secret Key
    • If using Cirrus Link's Chariot platform, this is the provided Secret Key
  • Block Node Commands
    • Whether or not to block outgoing commands from MQTT Engine to Edge Nodes. This is true by default and provides a security mechanism for preventing accidental outgoing commands from MQTT Engine.
  • Block Device Commands
    • Whether or not to block outgoing commands from MQTT Engine to Devices. This is true by default and provides a security mechanism for preventing accidental outgoing commands from MQTT Engine.
  • File Policy
    • The policy for handling Files contained within a Sparkplug payload.
      • Ignore: The default policy. The file will be ignored.
      • Store: The file will be stored to the local file system in the directory specified by the File Location field.  A Tag will be created with a String value representing the file URI.
  • File Location
    • The directory to store the files when using the Store policy described above.

...

Namespaces

The third tab is used for configuring namespaces.  Each namespace configuration represents a family of devices and/or data that MQTT Engine will support.  A namespace defines the topics that each MQTT Engine client will subscribe on as well as indicates how the payload will be handled.  There are two types of namespaces: Default and Custom.  

...

If a namespace is enabled, MQTT Engine will subscribe to the topics necessary to provide support for devices and data associated with that namespace.  If a namespace is disabled, MQTT Engine will unsubscribe from those topics and no longer support the devices and data associated with that namespace.

Image RemovedImage AddedCustom Namespaces

Custom namespaces are used to provide support for generic MQTT messages with string based payloads.  If a custom namespace is configured MQTT Engine will convert all messages received to tags.  The topic of each message will directly translate into the tag's path.  The payload of the message will be that tag's value.   

Image RemovedImage Added

Each custom namespace has the following properties:

...

Main

  • Name
    • A friendly name of the namespace to easily identify it.
  • Subscriptions
    • A comma separated list of subscriptions.

Optional

...

  • Root Tag Folder
    • A name of a folder where all tags will be stored.  If configured, this folder will be the base folder where all tag paths will start.
  • Tag Name
    • A tag name to be used for all tags.  If not configured, the last token in the topic will represent the tag.
  • JSON Payload
    • A flag to indicate that the content of the string based payload is a JSON object.


Note: if a Tag Name is not specified, care must be taken so that published messages do not end up overwriting previous tags. 

...