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 client 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: Client devices 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 clients.

• Publish/Subscribe: Subscribes to messages from other MQTT clients and updates the hosted tag’s value when a message is received. This allows the MQTT JSON Publisher device to act as a client.

• Publish Only: Ignores messages from 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. Client 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), or "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.

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 part of its topic.

Server Name

Enter the name of server.

Application URI

Enter the Uniform Resource Identifier (URI) to locate the asset on a network.

Application Name

Name of the URI application.

Item

Description

Port

Assign a port number for the Data Sever.

Item

Description

Enable Encryption

Enables encryption for the server. Note that authentication will be disabled unless this option is enabled.

Generate Certificate

When enabled, a key pair will be automatically generated on the device once the project is run. When disabled, a user-specified key pair will be used instead.

Key Pair

Select a key pair to use for encryption. Key pairs can be edited in the Certificates Editor window.

Trust All Certificates

When enabled, all incoming certificates will be trusted. When disabled, only the certificates in the trust store will be trusted.

Trust Store

Specify a trust store of certificates to trust. Communication that is not encrypted by one of the certificates in the trust store will be rejected. Trust stores can be edited in the Certificates Editor window.

Item

Description

Allow Anonymous Authentication

Allows anonymous clients to connect to the server.

Allow Anonymous Browse

Allows anonymous clients to browse topics on the server.

Allow Anonymous Read

Allows anonymous clients to read tag values from the server.

Allow Anonymous Write

Allows anonymous clients to write tag values to the server.

Item

Description

Allow Username Authentication

When enabled, clients can be authenticated by providing a username and password. Only username/password combinations defined in the server list will be authenticated.

Each user may be configured to have different access permissions.

Username

Sets the username for the user.

Password

Sets the password for the user.

Allow Browse

When enabled, the user may browse topics on the server.

Allow Read

When enabled, the user may read tag values from the server.

Allow Write

When enabled, the user may write tag values to the server.

Add New User

Adds a new user to the list.

Removes the user from the list.

Item

Description

Allow Certificate Authentication

Allows clients to use certificates for authentication.

When “Trust All Certificates” is enabled, any certificate may be used for authentication. When “Trust All Certificates” is disabled, only certificates found in the trust store may be used.

Allow Certificate Browse

When enabled, clients authenticated using a certificate may browse topics on the server.

Allow Certificate Read

When enabled, clients authenticated using a certificate may read tag values from the server.

Allow Certificate Write

When enabled, clients authenticated using a certificate may write tag values to the server.

Item

Description

Match Endpoint Security Policy

When enabled, auth tokens will be encrypted using the same security policy as the endpoint they are attched to.

Allow Unencrypted Authentication

Allows clients to authenticate without encryption. Only used when “Match Endpoint Security Policy” is enabled.

Authentication Security Policy

Specifies the security policy to use for authenticating users. Only used when “Match Endpoint Security Policy” is disabled.

Item

Description

Server Layout

Determines the prefix structure for OPC UA tag topics.

• Basic: Tag topics will be direct children of the “Tags” topic.

• Device: tag topics will be children of topics which are named after their I/O Devices.

Example: for a tag with browse name “browseName“ and I/O device “deviceName“:

• If “Server Layout” is set to “Basic”, the topic will be Tags.browseName

• If “Server Layout is set to “Device”, the topic will be Tags.deviceName.browseName

Note: Client devices should use an address containing the prefix ns=2;s= in addition to the topic, for example ns=2;s=Tags.BrowseName

Default Allow Read

When enabled, tags hosted on the server will be readable by default. Individual tags may overwrite this option in the “Device Tag” tab.

Default Allow Write

When enabled, tags hosted on the server will be writable by default. Individual tags may overwrite this option in the “Device Tag” tab.