added crc-dabmod patch

1 files changed, 111 insertions, 0 deletions

diff --git a/doc/README-SFN b/doc/README-SFN
new file mode 100644
index 0000000..d0c75f9
--- /dev/null
+++ b/doc/README-SFN
@@ -0,0 +1,111 @@
+README About the Usage of CRC-DABMOD for
+Synchronous Transmissions
+========================================
+
+Summary
+-------
+CRC-DABMUX and CRC-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 CRC-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.  CRC-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:
+crc-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 | crc-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 | crc-dabmod /dev/stdin -g2 \
+    -O moddelay -l -r 4000000 -u "type=usrp2" -F 234208000
+
+CRC-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 CRC-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, Matthias P. Braendli