Item

Description

Device Name

Allows the user to assign a name for the selected data server device.

Device Protocol

Allows the user to select a protocol for a device.

Host

Assign an IP Address for the Data Server

Port

Assign a port number for the Data Sever. Default is 502.

Unit ID

Assign a unit ID to the server. This is typically only used in Ethernet-serial conversion setups. Default 0.

String Encoding

Specifies the string encoding method that external devices will see when accessing tag data.

Note that this option is separate from the string encoding option used by tags in the Tag Editor. This setting cannot be overridden by individual tags.

String Encoding Method

When an invalid character is encountered in a hosted tag’s value, the gateway will use one of the following options:

• Replace: Replace the character with the question mark character ?.

• Skip: Skip the character and continue with the next one.

• Stop: End the string at the previous character and truncate any remaining characters.

Note that this option is separate from the string encoding method option used by tags in the Tag Editor. This setting cannot be overridden by individual tags.

Item

Description

Device Name

Allows the user to assign a name for the selected data server device.

Device Protocol

Allows the user to select a protocol for a device.

Use All Tags

Allows the user to

host all of the tags in the project file

on the data server.

Uses each tag’s path as its ID and/or topic, depending on the payload type.

Item

Description

Broker Address

IPv4 address or hostname for the MQTT broker. Note that all Xpanel devices run an MQTT broker by default. The default address of 0.0.0.0 will use this built-in broker.

Port

Port number used by the MQTT broker.

Client ID

Assign an optional client ID for publishing and subscribing.

Use Clean Session

Enables connecting to the MQTT broker using a clean session, or a non-persistent connection.

Keep Alive

Denotes the keepalive time used by the mqtt client in seconds.

Use SSL

Enables SSL encryption when communicating with the broker.

Key Pair

Select a key pair to use for the SSL encryption feature. These can be edited in the Certificates Editor window.

Trust Store

Select a trust store to use for the SSL encryption feature. These can be edited in the Certificates Editor window.

Use MQTT Passwords

When this property is enabled, a username and password will be used when connecting to the MQTT broker.

MQTT Username

Choose the MQTT username for connecting to the broker

MQTT Password

Choose an MQTT password for connecting to the broker

Item

Description

Use Message Queue

Denotes whether the client should use a message queue, which will store messages while the client is disconnected.

Message Queue Size

Denotes the maximum number of messages to be held in the message queue. Values can range from 20 to 10000. Default 1000.

Message Queue Publish Rate Limit

The minimum time (ms) between publishes, with 0 being as fast as possible. Maximum value 10000. This can be used to reduce network bandwidth, at the cost of slow response times.

Use Message Queue Age Limit

When enabled, the publisher will impose an age limit on queued messages.

Message Queue Age Limit (s)

The maximum age in seconds of a message that will be published, older messages will be discarded.

Item

Description

Running Mode

Sets the criteria for when to publish a payload. Default “On Change Any”.

• On Change Any: publishes a message each time any tag value updates.

• On Scan Delta: publishes after each scan, but only generates messages for tag values that have changed.

• On Scan All: publishes all tag values after each scan, even if no tag values have changed.

Polling Rate (ms)

Determines the rate (ms) for polling tag changes when “Running Mode” is set to “On Scan Delta” or “On Scan All”.

Item

Description

Publish Payload Format

Selects one of several built-in payload formats for publishing.

Note: external devices will must to be configured to listen for payloads with a matching format.

The payload can be set to include data from a single tag or multiple tags:

• Single: each payload contains data for only a single tag

• Multi: each payload can contain data from multiple tags

Each format type uses a separate JSON object to store each tag’s data. This “tag value object” can embedded within the payload structure in different ways:

• No Wrap: The payload root object is the tag value object, and all tag properties are direct children of the root object. Only available for “Single” payloads.

  • Example: {"Value": 1}

• Wrap: Uses the tag ID as the property name for the value object. Available for both “Single” and “Multi” payloads.

  • Example: {"tag1": {"Value": 1}, "tag2": {"Value": 2}}

• Array Wrap: Stores an array of tag value objects named "Tags". The tag ID property is included in the tag value object.

  • Example: {"Tags": [{"ID": "tag1, "Value": 1}, {"ID": "tag2", "Value": 123.456}]}

There are also two pre-made payload options: “Basic” and “Full”:

• Basic: Includes the following properties:

  • "Value": the tag's value

  • "Value Time": a 64-bit integer timestamp

Publish QOS

Choose the Quality of Service to use when publishing. Determines how many times each message will be sent in the event of packet loss.

• 0: The message will be sent at most once.

• 1: The message will be sent at least once (but may be sent multiple times).

• 2: The message will be sent exactly once.

In general, a higher value means the data will be more accurate, but this will also require more handshakes and bandwidth consumption.

Publish Retain Messages

When enabled, the last known value for each topic will be retained by the broker. When a new client subscribes to a topic, the retained value will be published to the client by the broker. The broker will only retain up to one value per topic.

Publish Topic Prefix

Sets a prefix string to include in all publish topics. Note that this does not automatically add a / level separator to the full topic.

For example, with a prefix of prefix and a tag named New Tag, the default topic will be prefixNew Tag.

Publish Topic Suffix

Sets a suffix string to include in all publish topics. Note that this does not automatically add a / level separator to the full topic.

For example, with a suffix of suffix and a tag named New Tag, the default topic will be New Tagsuffix.

Access Type

The MQTT JSON Publisher server device always publishes MQTT messages when a hosted tag’s value updates. This setting lets you choose whether the device also subscribes to MQTT messages from external clients.

• Publish/Subscribe: Subscribes to messages from other MQTT clients and updates the hosted tag’s value when a message is received.

• Publish Only: Ignores messages from external MQTT clients. This effectively makes the tags read-only to other clients.

Subscribe Payload Format

Selects one of several built-in payload formats for subscribing.

Note: This property only changes the expected payload format for subscribing. External devices must be configured to publish payloads use a matching format. Any subscribed messages and properties that do not match the specified format will be ignored.

The payload can be set to include data from a single tag or multiple tags:

• Single: Each payload contains data for only a single tag

• Multi: Each payload can contain data from multiple tags

Each format type uses a separate JSON object to store each tag’s data. This “tag value object” can embedded within the payload structure in different ways:

• No Wrap: The payload root object is the tag value object, and all tag properties are direct children of the root object. Only available for “Single” payloads.

  • Example: {"Value": 1}

• Wrap: Uses the tag ID as the property name for the value object. Available for both “Single” and “Multi” payloads.

  • Example: {"tag1": {"Value": 1}, "tag2": {"Value": 2}}

• Array Wrap: Stores an array of tag value objects named "Tags". The tag ID property is included in the tag value object.

  • Example: {"Tags": [{"ID": "tag1, "Value": 1}, {"ID": "tag2", "Value": 123.456}]}

There are also two pre-made payload options which allow you to specify which properties to include: “Basic” and “Full”.

• Basic: Includes the following properties:

  • "Value": The tag's value

  • "Value Time": A datetime string for when the tag value was updated by the host device.

• Full: Includes all of the “Basic” properties, as well as the following properties:

  • “Type”: the tag’s data type. This will be one of:

    • "boolean" (BOOL)

    • "float" (FLOAT32)

    • "double" (FLOAT64)

    • "byte" (INT8)

    • "short" (INT16)

    • "int" (INT32)

    • "long" (INT64)

    • "unsignedByte" (UINT8)

    • "unsignedShort" (UINT16)

    • "unsignedInt" (UINT32)

    • "unsignedLong" (UINT64)

    • "string" (STRING)

  • "Read Time": A datetime string for when the tag value was last read.

  • "Device": The client I/O device of the tag.

  • "Quality": The quality of the tag. One of “Active” or “

Note: All datetime strings use the format “yyyy-MM-ddTHH:mm:ss”.

Subscribe QOS

Choose the Quality of Service to use when subscribing. Determines how many times each message will be sent in the event of packet loss.

• 0: The message will be sent at most once.

• 1: The message will be sent at least once (but may be sent multiple times).

• 2: The message will be sent exactly once.

In general, a higher value means communication will be more reliable, but also requires more handshakes and bandwidth consumption.

Subscribe Tag Identifier Type

• Topic: Identifies which tag(s) each message is for based on the message topic. The subscribe topic must match what is defined in the “Device Tag” tab.

• Payload: Identifies tags using an identifier within the payload.

Subscribe Clamp Method

Sets how provided values will be clamped to the tag’s data type.

• Reject: values outside of the data type range will be rejected.

• Clamp: values outside of the data type range will be clamped to the data type range.

• Overflow: values outside of the data type range will overflow.

Subscribe Topic Prefix

Sets a prefix string to include in all subscribe topics. Note that this does not automatically add a / level separator to the full topic.

For example, with a prefix of prefix and a tag named New Tag, the default topic will be prefixNew Tag.

Subscribe Topic Suffix

Sets a suffix string to include in all subscribe topics. Note that this does not automatically add a / level separator to the full topic.

For example, with a suffix of suffix and a tag named New Tag, the default topic will be New Tagsuffix.