.. _basic_concepts:

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

.. _node:

Node
====

WRTD is made of Nodes, connected to each other over a WR network. Nodes receive input :ref:`Events
<event>` and send output :ref:`Events <event>`. See also :numref:`fig-wrtd-overview`.

Every Node has :ref:`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
:ref:`Messages <message>` to other Nodes.

.. _event:

Event
=====

Events represent inputs and outputs of a WRTD :ref:`node`. Input Events received on a :ref:`node`
will result in an output Event to be generated (assuming that the relevant :ref:`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 :ref:`local_channel`, an inbound network :ref:`message`, or an
:ref:`alarm`.

Output Events can be either a :ref:`local_channel`, or an outbound network :ref:`message`.

An Event is essentially a combination of an :ref:`event_id` (the "what") and a :ref:`timestamp` (the
"when").

.. _event_id:

Event ID
--------

Every :ref:`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.

:ref:`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``).

:ref:`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 :ref:`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).

An Event ID that is filled with null characters is invalid.

All other Event IDs are considered to refer to network :ref:`messages <message>`.

.. _timestamp:

Timestamp
---------

Every :ref:`event` has an associated Timestamp.

For an input :ref:`event`, the Timestamp typically represents the moment in time when the
:ref:`event` happened.

For an output :ref:`event`, the Timestamp typically represents the moment in time when the
:ref:`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 10\ :sup:`9`\ ) and a 16-bit counter for fractional
nanoseconds (where every "tick" represents 2\ :sup:`-16`\ ns).

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

.. _local_channel:

Local Channel
=============

Local Channels represent the connections of a :ref:`node` to its environment. They can be either
inputs or outputs.

A Local Channel input delivers input Events to the :ref:`node`. Typical examples include the
external trigger output of a digitiser, a Time to Digital Converter (TDC) or a TTL input channel on
a digital I/O board.

A Local Channel output receives output Events from the :ref:`node`. Typical examples include the
external trigger input of a digitiser, a Fine Delay generator or a TTL output channel on a digital
I/O board.

All Local Channels uses reserved :ref:`Event IDs <event_id>`.

.. _message:

Message
=======

WRTD Event Messages (or, simply, Messages) follow the LXI Event Messaging format, as defined in the
`LXI Event Messaging Extended Function specification`_, revision 1.0.

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
:numref:`fig-wrtd-message`.


.. figure:: graphics/wrtd_message.png
   :name: fig-wrtd-message
   :align: center
   :alt: alternate text
   :figclass: align-center

   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 :ref:`event_id`, a :ref:`timestamp` and a sequence number. The latter is a
counter that gets increased by one every time a new Event is generated, to help detect lost or
duplicate Messages.

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

.. _rep_cap:

Repeated Capability
===================

.. _attribute:

Attribute
=========

.. _rule:

Rule
====

.. figure:: graphics/wrtd_rule_rx.png
   :name: fig-wrtd-rule-rx
   :align: center
   :alt: alternate text
   :figclass: align-center

   RX path of a Rule

.. figure:: graphics/wrtd_rule_tx.png
   :name: fig-wrtd-rule-tx
   :align: center
   :alt: alternate text
   :figclass: align-center

   TX path of a Rule

.. _alarm:

Alarm
=====

An Alarm is simply a user-defined moment to generate internally an input :ref:`event`.

The :ref:`event_id` of an Alarm will always have a prefix of ``alarm`` or ``ALARM``, followed by any
other characters (always limited to 16 characters, including null-termination).

.. figure:: graphics/wrtd_alarm.png
   :name: fig-wrtd-alarm
   :align: center
   :alt: alternate text
   :figclass: align-center

   Anatomy of an Alarm

.. _LXI Event Messaging Extended Function specification: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Event%20Messaging%20Extended%20Function.pdf

.. _TAI time: https://en.wikipedia.org/wiki/International_Atomic_Time

.. _Unix Epoch time: https://en.wikipedia.org/wiki/Unix_time
