README About the Usage of ODR-DabMod for
Synchronous Transmissions
========================================

Summary
-------
ODR-DabMux and ODR-DabMod have a basic support for timestamped transmission,
when the UHD output is used.  This README explains how this functionality
works, and how to set it up.

This feature is a prerequisite for the creation of a single-frequency
network.


Concept
-------
The goal of this functionality is to synchronise the transmission for
several transmitters.  This has been tested with the USRP B100 and the
USRP2, that both have the necessary REFCLK and 1PPS inputs.  Both are
required to synchronise two USRPs:
- The REFCLK is used in the USRP for timekeeping.  If we want two
  USRPs to stay synchronised, they both must have a precise 10MHz
  source at the REFCLK, otherwise their internal clocks will drift
  off.
- The 1PPS signal is used to set the time inside the USRPs.  The rising
  edge of the 1PPS signal has happen synchronously for all transmitters.
  Usually, GPS is used to drive this 1PPS.

For such a system, there will be one multiplexer, which will send the ETI
stream to several modulators. The ETI stream, in this case, is transported
over a TCP/IP.

Each modulator receives ETI frames that contain absolute timestamps, defining
the exact point in time when the frame has to be transmitted.  These in-band
timestamps are composed of two parts:
- The TIST field as defined in the ETI standard, giving an offset after the
  pulse per second signal;
- A time information transmitted using the MNSC, representing the precise time
  when the frame must be transmitted, with one-second resolution.

When ODR-DabMux is called with -s, the TIST is defined in each frame. The
Time is always encoded in the MNSC.

When the ETI stream is sent to several modulators using non-blocking I/O, it
is not possible to rely on a modulator to back-pressure the Ensemble multiplexer.
It is therefore necessary to throttle multiplexer output.  ODR-DabMux takes an
additional parameter -r to output one ETI frame every 24ms.

The tool eti_tcp.py can be used to send the ETI stream over TCP.
An example invocation is:
odr-dabmux <lots of options> | ./eti_tcp/eti_tcp.py 54540

Each modulator then receives the ETI stream through a TCP connection. Each frame
contains the complete timestamp, to which an per-modulator offset is added.
The sum is then given to the USRP. The offset can be specified in two ways:

using -o delay:
Adds a constant delay specified on the command line (see example 1 below).

using -O delayfile
Adds the delay specified in the given file. The file must contains a single
line containing a floating point number. This file is read each 50 frames, and
the modulator delay is updated.

In both cases, the units are seconds.

Example modulator invocation (for a B100 USRP supporting 2048Msps and with a
fixed delay of 2.3 seconds)
nc localhost 54001 | odr-dabmod /dev/stdin -g2 \
   -o 2.3 -l -u "master_clock_rate=32768000,type=b100" -F 234208000

Example modulator invocation (for an USRP2 requiring resampling and with a delay
specified in a separate file "moddelay")
nc localhost 54001 | odr-dabmod /dev/stdin -g2 \
    -O moddelay -l -r 4000000 -u "type=usrp2" -F 234208000

ODR-DabMod uses the UHD library to output modulated samples to the USRP device.
When started, it defines the USRP time using the local time and the PPS signal.
It is therefore important to synchronise computer time using NTP.

When a frame arrives with a timestamp that is in the past, the frame is dropped.
If the timestamp is too far in the future, the output module waits a short
delay.

Synchonisation can be verified by using an oscilloscope and a receiver. It is
very easy to see if the null symbols align.


Hardware requirements
---------------------
The following hardware is required to test the SFN patch to the CRC mmbTools:
- Two USRPs ;
- One or two computers with the mmbTools installed ;
- A network connection between the two computers ;
- A 10MHz refclk source ;
- A 1PPS source synchronised to the 10MHz ;
- An oscilloscope to check synchronisation.

When more than one USRP is plugged to one computer, the device string for the
-u option for ODR-DabMod must specify the device. (e.g.  -u "type=b100",
-u "type=usrp2" or -u "serial=ABC123")

It is possible to use signal generators as REFCLK source and 1PPS, if there is
no GPS-disciplined oscillator available. It is necessary to synchronise the
1PPS source to the 10MHz source.

The UHD Output module (C++) has to be modified if the USRP internal GPSDO option
is used.

###########
june 2012, initial version, Matthias P. Braendli
feb 2014, renamed crc-dabXYZ to odr-dabXYZ, mpb