Data Groups
With few exceptions, data groups must be defined in a device template file in order for them to be available for use on a remote device. Which data groups are defined by a device template file depends on protocol, device type, and unique configuration.
CygNet distributes sample device template files for its EIEs, each of which typically serves one or more hardware models along with applicable firmware. Therefore, the data groups described in the table below are only those data groups defined by CygNet in sample device template file(s). Your template(s) might not include some of the data groups described below. Device template files exist to enable users to customize device configurations; however, CygNet is not responsible for changes made by users.
For information about data group definitions and device template files, see Device Template Files.
IoT CygNet Link EIE Data Groups
The data groups and UIS commands on the CygNet Enterprise (IoT CygNet Link EIE) device, in the Weatherford Link payload, and on the CygNet Edge (other CygNet EIE) device must be identical and standard.
Mirrored Data Groups
Most data groups in the CygNet Enterprise (IoT CygNet Link EIE) device template file must contain an attribute dgCat="mirrorDg" indicating that the data group is mirrored or paired with a data group in the source CygNet instance. If dgCat="mirrorDg" is not specified the Get from RTU button is hidden on the View Data dialog box.
See the data groups topics for the appropriate EIE for the CygNet on the Edge remote device for a list of all possible data groups.
|
<DynaCard niceName="Dynagraph Card" maxCnt="7" dgCat="mirrorDg" canSend="false" canRecv="true" uccSend="false" uccRecv="true"> |
| Data Group Type | Usage Notes |
|---|---|
|
CmdDev |
The "Command - Device" data group writes a value to a device-level MQTT topic. Note: The data group category attribute for the CmdDev data group is always |
|
CmdNode |
The "Command - Edge Node" data group writes a value to a node-level MQTT topic. Note: The data group category attribute for the CmdNode data group is always |
|
<other data groups> |
The IoT CygNet Link device template file must contain any other data groups for which you want to get or send data to the remote device. Every data group on the CygNet Enterprise (IoT CygNet Link EIE) device must have a corresponding data group on the CygNet Edge device and in the Weatherford Link data payload. The data group category attribute must be |
Point Processing
The following information describes point processing for the IoT Sparkplug EIE and the IoT CygNet Link EIE. Message and data processing is handled in the same way on both EIEs.
Compression
The EIE supports reading compressed or uncompressed Sparkplug B payloads, including Sparkplug-formatted DynaCards, published from Link. It supports gzip and zlib data compression formats.
Alias Support
The EIE supports the use of optional aliases for Sparkplug metric names, which reduces overall message size for MQTT subscriptions.
When a payload on a birth message is received, each "metric" (the data item in the payload) can have an optional alias assigned. This is to reduce the number of bytes on future data payloads. For example, a metric name could equal "flow_meter_4_differential_pressure-northern_lot_5428_section2" with alias "2004" (representing a significant fewer number of bytes on every published payload). Optional aliases are supported in both templated and configurable data groups.
An alias is an unsigned 64-bit integer representing an optional alias for a Sparkplug B payload. If supplied in an NBIRTH or DBIRTH it must be a unique number across this EoN node's entire set of metrics. In other words, no two metrics for the same EoN node can have the same alias. Upon being defined in the NBIRTH or DBIRTH, subsequent messages can supply only the alias instead of the metric friendly name to reduce overall message size.
Timestamps
A payload file may include a timestamp for each data item, a timestamp for the entire payload, or no timestamp at all. When processing points, CygNet will assign timestamps in this order:
- the timestamp associated with the data item if it exists.
- the timestamp for the payload if it exists.
- the current time.
The timestamp locations are defined in the Sparkplug specification.
Lost Connection
When payload data indicates the connection between the MQTT server and the remote device has been lost, CygNet can be configured to set all points associated with the topic to unreliable. This feature is enabled in the device template file for each data group using the setUnreliableOnLostConnection attribute. If true, all CygNet points associated with the topic are set to unreliable. Otherwise the point status is unchanged.
The Sparkplug node and device DEATH messages are used to indicate a lost connection.
ReBIRTH Request
The EIE driver automatically requests a rebirth if it receives data for an alias that was not defined in the most recent BIRTH message. When an unknown alias is received, the mapping from alias to item is considered unreliable, so no data from the payload is processed.
A user can request a rebirth manually through the CmdDev "Command – Device" or CmdNode "Command – Edge Node" data group using the data group editor or via a UIS command. See Command-Type Data Groups for more information.
NDEATH and NBIRTH Messages
When an NDEATH or NBIRTH message is received, all device-level points mapped to data groups that are subscribed to that node will be marked as unreliable (true, if the topic is subscribed just to the node level topic or any child device-level topic of that same node) per the Sparkplug specification (section 7.1.2). NDEATH implies DDEATH for all devices on that node. Points go unreliable with a NDEATH or DDEATH message (those can be sent separately).
bdSeq Matching
The EIE supports bdSeq matching. The bdSeq is used to track the overall session of a Sparkplug client and is present in the NBIRTH and NDEATH messages. A bdSeq metric is used to match a NDEATH message (published by the MQTT Server on behalf of a disconnected Sparkplug client) with a previously published NBIRTH message to indicate the Sparkplug client is offline. This is important because the Sparkplug client might lose its connection, reconnect, and publish a new NBIRTH before the MQTT server publishes an NDEATH message from the previous session. If this happens the new NBIRTH message will contain a new bdSeq number and any subsequent NDEATH messages with old bdSeq numbers can be ignored. When a device data group receives a node birth and/or death payload, the EIE will process the messages for any bdSeq number matches, and ignore old NDEATH messages.
strictBdSeqMatch
An attribute strictBdSeqMatch is available in the root <deviceDefinition> element in the sample device template file(s) to determine how to handle NDEATH messages with respect to matched or mismatched BIRTH and NDEATH bdSeq numbers.
- If strictBdSeqMatch is set to "true", the NDEATH message is processed only when the bdSeq number in the BIRTH payload and the bdSeq number in the NDEATH payload is an exact match.
- If strictBdSeqMatch is set to "false", the NDEATH message is processed only when the bdSeq number in the NDEATH payload is equal to or greater than the bdSeq number in the BIRTH payload. The default value is "false".
While the strictBdSeqMatch attribute and its default value changes how NDEATH messages are handled by the EIE, it is important to note that mismatched sequence numbers may indicate a problem and should not be ignored.
