3. Basic Concepts¶
This section introduces the various basic concepts of WRTD. These concepts are used throughout this document and are fundamental to understanding how WRTD works (and, by extension, how to use it).
Events represent inputs and outputs of a WRTD Node. Input Events received on a Node will result in an output Event to be generated (assuming that the relevant Rule exists to associate an input to an output). In that sense, inputs Events are the causes, while output Events are the effects.
3.2.1. Event ID¶
Every Event is represented by an ID.
Event IDs are 15-character, null-terminated (for a total length of 16) strings that uniquely identify an input or output Event.
Local Channel inputs always use an Event ID in the form of
LC-I<x>, where x is a number
starting from 1 (e.g.
Local Channel outputs always use an Event ID in the form of
LC-O<x>, where x is a number
starting from 1 (e.g.
An Alarm Event ID will always have a prefix of
ALARM, followed by any other
characters (always limited to 16 characters, including null-termination).
All other Event IDs are considered to refer to network messages.
An Event ID that is longer than 16 characters (including null-termination) or that is filled with null characters is invalid.
Rule 6.4.4 of the LXI Core Specification also defines some reserved Event IDs. These are:
LXI<x>with x being an integer between 0 and 7 (e.g.
LAN<x>with x being an integer between 0 and 7 (e.g.
Users are advised to not use these identifiers in their own applications.
3.2.2. Event Timestamp¶
Every Event has an associated Timestamp.
Timestamps are expressed using a 48-bit counter for seconds, a 32-bit counter for nanoseconds (which is reset every time the counter reaches 109) and a 16-bit counter for fractional nanoseconds (where every “tick” represents 2-16ns).
For most applications, the upper 16 bits of the seconds counter can be ignored/assumed to
be zero. A 32-bit seconds counter that was started on
00:00:00 Thursday, 1 January 1970 will
06:26:16 Sunday, 7 February 2106.
3.3. Event Log¶
The Event Log has a limited storage buffer. Newer entries will overwrite older, unread ones.
For an explanation of the fields of an Event Log entry, please refer to the documentation of the
3.4. Local Channel¶
Local Channels represent the connections of a Node to its environment. They can be either inputs or outputs.
A Local Channel input delivers input Events to the Node. Typical examples include the external trigger input of a digitiser, a Time to Digital Converter (TDC) or a TTL input channel on a digital I/O board.
A Local Channel output transmits output Events from the Node. Typical examples include a Fine Delay generator or a TTL output channel on a digital I/O board.
All Local Channels use specific IDs as described in Event IDs.
WRTD Event Messages (or, simply, Messages) follow the LXI Event Messaging format, as defined in Rule 4.3 of the LXI Event Messaging Extended Function specification.
To ensure compatibility and interoperability with LXI devices, WRTD Event Messages are transmitted
using multicast UDP on address
5044 (Rule 3.3.1 of the specification).
Each Message is transmitted as a single Ethernet frame, with a UDP header and a payload as shown in Fig. 3.1.
The contents of a WRTD Event Message are again based on LXI Event Messages, with the “Domain” and “Flag” fields (octets 3 and 36 respectively) fixed to zero.
The sequence counter can be used to detect lost or duplicate Messages.
Although there are currently no “Data Fields” defined (octets 37 and beyond), it should be highlighted that the LXI Event message format supports an arbitrary number of data fields, in the form of Type/Length/Value (TLV) triplets, which could be used to provide additional functionality to WRTD in the future.
Please refer to Section 4.3 of the LXI Event Messaging Extended Function specification for more details.
3.6. Repeated Capability¶
IVI uses the term Repeated Capability to express functionality that is duplicated in an instrument, with each instance potentially having different settings. A typical example of a Repeated Capability is a channel of an oscilloscope; the instrument has many channels, each one offering the exact same functionality, but each one with its own settings (Attributes).
Furthermore, IVI defines the API for accessing Repeated Capabilities in Section 12 of IVI-3.4: API Style Guide.
WRTD defines the following Repeated Capabilities for each Node:
3.6.1. Repeated Capability ID¶
An instance of a Repeated Capability is designated by a unique Repeated Capability ID.
WRTD uses the Parameter Style API, defined in Section 12.1 of IVI-3.4: API Style Guide, where each function related to a Repeated Capability expects the ID of the Repeated Capability instance as a parameter. This parameter is also called a Repeated Capability Selector in IVI terminology.
Similar to an Event ID, a Repeated Capability ID is limited to 16 characters, including null termination.
Section 4.4 of IVI-3.1: Driver Architecture Specification shows that a Selector can include groups of IDs, ranges, nested IDs and much more. For now, WRTD only supports simple selectors, allowing a single ID to be selected at a time, but this could change in future releases.
WRTD uses Attributes to represent the various settings of the Node and defines get/set functions to access them. This behaviour is identical to IVI.
Attributes can be of one of the following types:
- 32-bit Integer
- Timestamp (new type, does not exist in IVI)
Since global Attributes are not attached to any Repeated Capability, when using one of the
functions to get/set a global Attribute, a special Repeated Capability ID
WRTD_GLOBAL_REP_CAP_ID) must be passed to the function as the Selector.
Please refer to the Attribute Handling API for more details.
An Alarm is simply a user-defined moment to generate internally an input Event.
The Repeated Capability ID of an Alarm must always have a prefix of
followed by any other characters (always limited to 16 characters, including
A Node may be running one or more Applications (firmware). As an example, the SPEC150T-based FMC-ADC runs a single Application (to communicate with the ADC), while the SVEC-based TDC+FD runs two Applications (one for the TDC and one for the Fine Delay generator).
Unlike Rules and Alarms, users cannot declare or remove Applications. They can only get their (read-only) Attributes which provide information regarding firmware version, number and direction of Local Channels, etc.