White Rabbit Trigger Distribution (WRTD) is a generic framework for distributing triggers (Events) over a White Rabbit (WR) network.
As can be seen in Fig. 1.1, WRTD Nodes receive “input” Events and distribute them to other Nodes over WR in the form of network Messages that are used to transfer the Timestamp of the input Event. The receiving Nodes are programmed to execute some “output” Event (action) upon reception of a particular Message, potentially with some fixed delay added to the Timestamp.
There are two main categories of WRTD applications:
- A “source” Node receives an input Event, adds a fixed delay to its Timestamp and distributes it to other Nodes. As long as the fixed delay added is greater than the upper-bound latency of the network (a fundamental feature of WR itself), all receiving nodes will receive the Message before the programmed time and will execute simultaneously their action (thanks to the sub-ns synchronisation provided by WR).
- The receiving Nodes are “recording” devices (e.g. digitisers), capable of storing data in a recording buffer. The source Node transmits the Message, with or without a fixed delay. When one of the destination Nodes receives the Message, it stops recording and rolls-back its buffer to the moment specified by the Timestamp in the received Message (provided that it has a large enough buffer to compensate for the latency). Thus, all Nodes will deliver recorded data from the moment in the past when the input Event was originally received at the source Node.
Of course, the above list is not exhaustive, there are many other potential applications but they are usually permutations of one of the above scenarios.
In WRTD, the programming of Events, Messages and associated actions is done by defining Rules. A Rule simply declares a relationship between an input (cause) and an output (effect) Event. A Rule can state that when a specific Event is received a Message should be transmitted or, that when a Message is received an output Event should be generated. This is depicted in Fig. 1.2.
Section 3 provides a more elaborate discussion on the various basic concepts of WRTD.
1.1. Relation to IVI and LXI¶
LAN eXtensions for Instrumentation (LXI) is a standard, defining a communication protocol for the remote control of instrumentation over an Ethernet-based LAN.
Version 1.5 of the LXI standard splits the specification in two parts:
- The LXI Core Specification, to which all LXI Devices must conform.
- A set of optional Extended Functions, to which vendors may choose to conform.
Among these “Extended Functions”, several are related to the synchronisation (via IEEE-1588 PTP) and exchange of real-time event messages between instruments. These include:
- LXI Event Log Extended Function
- LXI Timestamped Data Extended Function
- LXI Clock Synchronization Extended Function
- LXI Event Messaging Extended Function
The core specification requires (Rule 6.1) that all LXI devices provide an Interchangeable Virtual Instruments (IVI) driver. Furthermore, it requires (Rule 6.1.1) that all LXI devices supporting the exchange of event messages, do so by providing an API that conforms to the IVI-3.15 IviLxiSync Specification.
Since the LXI event exchanging mechanism is conceptually very close to WRTD, it was decided to design WRTD to be as close to LXI as possible. In particular:
- WRTD uses the same Message format. This already allows LXI and WRTD devices on the same network to exchange events, even if the API for programming these events is different.
- the WRTD library API mimics that of an IVI driver, with a strong influence from the IVI-3.15 IviLxiSync Specification, even if several of the Repeated Capabilities and Attributes are different.
Do not worry if you do not understand some of the terminology yet. It will be explained in Section 3.
In the future, and with White Rabbit being standardised within the next release of IEEE-1588, it is foreseen to try to merge WRTD with IVI/LXI. A possible way to do this would be to add a new IVI specification, similar to IVI-3.15, describing the API to control WRTD-enabled devices. This API would be an extension, allowing any instrument with an IVI driver and a WR interface to exchange event messages with any other WRTD node.
1.2. Document Structure¶
The following is a description of how the remainder of this document is structured (in reverse order).
- Section 6 provides guidelines on how to develop a WRTD Node, including hardware (Section 6.2), gateware (Section 6.3) and firmware (Section 6.4).
- Before you embark however on a new design, please have a look first at the existing reference designs; it could be that one of them is appropriate for your task. Section 5 presents the currently available reference WRTD Nodes that come pre-programmed with their gateware and firmware.
- Whether you develop your own Node or use one of the reference Nodes, Section 4 describes how to access and control your Node. Section 4.1 provides all the details on how to use the C library to develop your own applications. Alternatively, Section 4.2 presents a Python wrapper to the C library that can be used to develop Python-based applications. Section 4.3 describes the generic tools that are built using the Python wrapper and that provide access to a WRTD node without the need to develop any application.
- Section 3 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).
- Last but not least, Section 2 takes you through the necessary steps to setup the hardware and install the necessary software.