Scripts for the time-tagging logic
==================================

On the time-tagging side, the following scripts exist:

getlatestts.py -- Read the latest timestamp registers (CHxLTS*R)
rdtb.py   -- Read samples of the tag buffer while they exist
tsdiff.py -- Output the difference between two time-stamps from the buffer
tsset.py  -- set TAI time stamp value, clearing the cycles counter in the
          process

While the last script is pretty straightforward, the first two need some
further notes on their functioning.

rdtb.py
---------

First, the rdtb.py script can be used to read the timetag ring buffer and output its
contents. The output can be the prompt (stdout), or a file if the user selects
it. When the script is started, it asks for the slot number (as usual), then
whether it should output to a file, and the filename if it should:

%> ./rdtb.py
Slot no.: 1
Output samples to file? (y/n) y
File name (with extension): myfile.txt

The last part of the output is -- no matter whether you selected to output to
a file or not -- the number of pulses stored to the timetag ring buffer on each channel,
calculated based on the number of times the channel mask was containing a '1'
for a particular channel.

The output file can be used by the tsdiff.py script to print the difference
between two timestamps on stdout. The format of the timetag ring buffer output is the
following:

(<USEDW>) <channel mask> : <TAI value>.<seconds value>

where
<USEDW>        -- the TBCSR.USED field
<channel mask> -- the TBMR.CHAN field
<TAI value>    -- TAI value obtained by concatenating the bit fields of the
               TBTLR and TBTHR registers
<seconds value> -- TBCYR * 8

tsdiff.py
---------

This script can be used to calculated the difference between consecutive
timestamps in the timetag ring buffer. It requires an output file from the rdtb.py script
and then retrieves the TAI and seconds value from the script's output,
printing the difference between one timestamp and the previous.

Additionally, the script calculates when the timestamp difference is less than
the pulse rejection period on the CONV-TTL-BLO and prints an extra warning to the
sample.

The output -- based on that of the rdtb.py output -- is:

(<channel mask>) <TAI difference>.<seconds difference>

Note that the first sample in the output is always the first timestamp value.

To run (considering the output file in the rdtb.py section):

%> ./tsdiff.py
Input file name (with extension): myfile.txt

