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).

3.1. Node

WRTD is made of Nodes, connected to each other over a WR network. Nodes receive input Events and send output Events. See also Fig. 1.1.

Every Node has Local Channel inputs and/or outputs allowing it to interact with its environment. It also has a connection to a WR network, allowing it to send and/or receive Messages to other Nodes.

3.2. Event

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.

Input Events can be either a Local Channel, an inbound network Message, or an Alarm.

Output Events can be either a Local Channel, or an outbound network Message.

An Event is essentially a combination of an Event ID (the “what”) and an Event Timestamp (the “when”).

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. LC-I1).

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. LC-O1).

An Alarm Event ID will always have a prefix of alarm or 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.

Attention

An Event ID that is longer than 16 characters (including null-termination) or that is filled with null characters is invalid.

Note

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. LXI5)
  • LAN<x> with x being an integer between 0 and 7 (e.g. LAN3)
  • LXIERROR

Users are advised to not use these identifiers in their own applications.

3.2.2. Event Timestamp

Every Event has an associated Timestamp.

For an input Event, the Timestamp typically represents the moment in time when the Event happened.

For an output Event, the Timestamp typically represents the moment in time when the Event should happen.

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).

Hint

All Timestamps represent TAI time since 00:00:00 Thursday, 1 January 1970 (Unix Epoch time).

Hint

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 overflow on 06:26:16 Sunday, 7 February 2106.

3.3. Event Log

The Event Log records information about all received and transmitted Events, as well as information regarding any discarded Event, along with the reason for discarding it.

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 wrtd_get_next_event_log_entry() function.

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.

3.5. Message

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 224.0.23.159, port 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.

alternate text

Fig. 3.1 Contents of a WRTD Event Message

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.

Each Message contains an Event ID, an Event Timestamp and a sequence number. The latter is a counter that gets increased by one every time a new Event is generated.

Hint

The sequence counter can be used to detect lost or duplicate Messages.

Hint

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.

Note

Similar to an Event ID, a Repeated Capability ID is limited to 16 characters, including null termination.

Hint

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.

3.7. Attribute

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:

  • Boolean
  • 32-bit Integer
  • String
  • Timestamp (new type, does not exist in IVI)

Attributes can be attached to a Repeated Capability, or they can be “global” (apply to the whole Node).

Note

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.

3.8. Rule

A Rule is a Repeated Capability instance inside a Node that links input to output Events.

Rules are declared (and deleted) using the Rules API. Their configuration is controlled via Attributes that can be manipulated using the Attribute Handling API.

When an input Event is received by a Node, WRTD tries to match it with any declared (and enabled) Rule. The process that is followed for each input Event is depicted in Fig. 3.2.

alternate text

Fig. 3.2 Rule processing for incoming Events. The red hexagons represent Attributes.

Once an input Event has been matched and all delays have been applied to it, it is forwarded to the next processing block that generates the preconfigured output Event. This is depicted in Fig. 3.3.

alternate text

Fig. 3.3 Rule processing for outgoing Events. The red hexagons represent Attributes.

Hint

There are actually more Attributes than the ones shown in Fig. 3.2 and Fig. 3.3. Please refer to the Attribute Handling API for the complete list, as well as an explanation of each Attribute.

3.9. Alarm

An Alarm is simply a user-defined moment to generate internally an input Event.

Similar to a Rule, an Alarm is a Repeated Capability instance inside a Node

Alarms are declared (and deleted) using the Alarms API. Their configuration is controlled via Attributes that can be manipulated using the Attribute Handling API.

Note

The Repeated Capability ID of an Alarm must always have a prefix of alarm or ALARM, followed by any other characters (always limited to 16 characters, including null-termination).

The Event ID of the input Event generated by an Alarm will match its Repeated Capability ID.

Every Node checks periodically if any of the declared (and enabled) Alarms need to be triggered, following the process depicted in Fig. 3.4.

alternate text

Fig. 3.4 Alarm processing.

Hint

There are actually more Attributes than the ones shown in Fig. 3.4. Please refer to the Attribute Handling API for the complete list, as well as an explanation of each Attribute.

3.10. Application

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).

As such, an Application is also a Repeated Capability instance inside a Node.

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.

Please refer to the Attribute Handling API for the complete list of Application-related Attributes. The Repeated Capability ID of each Application can be retrieved using the Applications API.