Rework to prefer EDI over ZeroMQ

7 files changed, 125 insertions, 66 deletions

diff --git a/appendix.tex b/appendix.tex
index 6792f65..02da04e 100644
--- a/appendix.tex
+++ b/appendix.tex
@@ -35,6 +35,28 @@ In order to select the format, the following syntax for the \texttt{-O} option i
 \texttt{-O file://filename?type=format}, where \texttt{format} is one of \verb+framed+, \verb+streamed+ or
 \verb+raw+.
 
+
+\section{Additional EDI TAGs used}
+ODR defined and uses two additional EDI TAGs, whose content is described here.
+
+ODR-AudioEnc inserts audio level metadata into the ``ODRa'' TAG. The TAG item is in the following format:
+\begin{lstlisting}
+  TAG Name="ODRa" [4 bytes]
+  Length=4 [4 bytes]
+  Left Audio Level [signed 16-bit integer]
+  Right Audio Level [signed 16-bit integer]
+\end{lstlisting}
+
+
+The second EDI TAG ``ODRv'' contains version and uptime information for the EDI source.
+\begin{lstlisting}
+  TAG Name="ODRv" [4 bytes]
+  Length=N+4 [4 bytes]
+  Version [String of N bytes, UTF-8 encoded, not zero terminated]
+  Uptime [unsigned 32-bit integer representing number of seconds since program start]
+\end{lstlisting}
+
+
 \section{Bibliography}
 \bibliographystyle{acm}
 \bibliography{dab}
diff --git a/interfaces.tex b/interfaces.tex
index ad9abe9..72f9651 100644
--- a/interfaces.tex
+++ b/interfaces.tex
@@ -113,25 +113,34 @@ the tools have to run at the native rate, it is not possible to use files
 anymore to interconnect the tools. For this usage, a network interconnection is
 available between the tools.
 
-This network connection is based on ZeroMQ, a library that permits the creation
-of a socket connection with automatic connection management (connection,
-disconnection, error handling).  ZeroMQ uses a TCP/IP connection, and can
-therefore be used over any kind of IP networks.
-
-This connection makes it possible to put the different tools on different
-computers, but it is not necessary. It is also possible, and even encouraged to
-use this interconnection locally on the same machine.
+The standard protocol to carry both contribution (From audio encoder to
+multiplexer) and distribution (from multiplexer to modulators) is
+EDI, specified by ETSI~\cite{etsits102693}
+\footnote{For a summary about the ZeroMQ interface used before EDI, see the
+section~\ref{sec:zeromq} below.}.
+
+EDI can be carried over UDP or other unreliable links, and offers a protection
+layer to correct bit-errors. Over network connections where the occasional
+congestion can occur, EDI can also be carried over TCP, which will ensure lost
+packets get retransmit. Unless you are able to reserve bandwidth for the EDI
+traffic, using TCP is the safer option.
+
+While the main reason to use EDI is to put the different tools on different
+computers, it is not necessary to do so.
+It is possible, and even encouraged to use this interconnection locally on the
+same machine, for increased flexibility.
 
 \subsubsection{Between Encoder and Multiplexer}
 \label{sec:between_encoder_and_multiplexer}
 
-Between ODR-AudioEnc and ODR-DabMux, the ZeroMQ connection transmits AAC
-superframes, with additional metadata that contains the audio level indication
-for monitoring purposes. The multiplexer cannot easily derive the audio level
-from the AAC bitstream without decoding it, so it makes more sense to calculate
-this in the encoder.
+Between ODR-AudioEnc and ODR-DabMux, the EDI protocol carries \dabplus{}
+superframes or DAB frames, with additional metadata that contains the audio
+level indication for monitoring purposes.
+The multiplexer cannot easily derive the audio level from the encoded bitstream
+without decoding it, so it makes more sense to calculate this in the encoder and
+carry it along the encoded data.
 
-On the multiplexer, the subchannel must be configured for ZeroMQ as follows:
+On the multiplexer, the subchannel must be configured for EDI as follows:
 \begin{lstlisting}
 sub-fb {
     type dabplus
@@ -139,29 +148,41 @@ sub-fb {
     id 24
     protection 3
 
-    inputfile "tcp://*:9001"
-    zmq-buffer 40
-    zmq-prebuffering 20
+    inputproto edi
+    inputuri "tcp://*:7002"
+    buffer-management prebuffering
 }
 \end{lstlisting}
 
-The ZeroMQ input supports several options in addition to the ones of a
+The EDI input supports several options in addition to the ones of a
 subchannel that uses a file input. The options are:
 
 \begin{itemize}
-    \item \texttt{inputfile}: This defines the interface and port on which to
+    \item \texttt{inputuri}: This defines the interface and port on which to
         listen for incoming data. It must be of the form
-        \texttt{tcp://*:<port>}. Support for the \texttt{pgm://} protocol is
-        experimental, please see the \texttt{zmq\_bind} manpage for more
-        information about the protocols.
-    \item \texttt{zmq-buffer}: The ZeroMQ input handles an internal buffer for
+        \texttt{<proto>://*:<port>}, with \texttt{proto} may be either
+        \texttt{tcp} or \texttt{udp}.
+
+    \item \texttt{buffer-management}: Two buffer management approaches are
+        possible with EDI:
+        The other option \texttt{timestamped} will take
+        into account the timestamps carried in EDI, inserting the audio into the
+        ETI frame associated to that same time stamp.
+        \texttt{prebuffering} ignores timestamps and
+        pre-buffers some data before it starts streaming. This allows to
+        compensate for network jitter.
+
+    \item \texttt{buffer}: (Both buffer management settings)
+        The input contains an internal buffer for
         incoming data. The maximum buffer size is given by this option, the
-        units are AAC frames ($24$\ms). Therefore, with a value of $40$, you
+        units are frames ($24$\ms). Therefore, with a value of $40$, you
         will have a buffer of $40 * 24 = 960$\ms. The multiplexer will never
-        buffer more than this value, and will discard data one AAC superframe
-        ($5$ frames $= 100$\ms) when the buffer is full.
-    \item \texttt{zmq-prebuffering}: When the buffer is empty, the multiplexer
-        waits until this amount of AAC frames are available in the buffer
+        buffer more than this value, and will discard data when the buffer is
+        full.
+
+    \item \texttt{prebuffering}: (Only in buffer management \texttt{prebuffering})
+        When the buffer is empty, the multiplexer
+        waits until this amount of frames are available in the buffer
         before it starts to consume data.
 \end{itemize}
 
@@ -169,8 +190,12 @@ The goal of having a buffer in the input of the multiplexer is to be able to
 absorb network latency jitter: Because IP does not guarantee anything about the
 latency, some packets will reach the encoder faster than others. The buffer can
 then be used to avoid disruptions in these cases, and its size should be
-adapted to the network connection. This has to be done in an empirical way, and
-is a trade-off between absolute delay and robustness.
+adapted to the network connection.
+In both buffer management techniques, it is a trade-off between absolute delay
+and robustness. When using pre-buffering, you directly control size of the
+buffer, and you set it to a value depending on your network delays. When using
+timestamped buffer management, the size of the input buffer is a consequence of
+the effective delay you set in the timestamps.
 
 If the encoder is running remotely on a machine, encoding from a sound card, it
 will encode at the rate defined by the sound card clock. This clock will, if no
@@ -178,8 +203,8 @@ special precautions are taken, be slightly off frequency. The multiplexer
 however runs on a machine where the system time is synchronised over NTP, and
 will not show any drift or offset. Two situations can occur:
 
-Either the sound card clock is a bit slow, in which case the ZeroMQ buffer in
-the multiplexer will fill up to the amount given by \texttt{zmq-prebuffering},
+Either the sound card clock is a bit slow, in which case the input buffer in
+the multiplexer will fill up to the amount given by \texttt{prebuffering},
 and then start streaming data. Because the multiplexer will be a bit faster
 than the encoder, the amount of buffered data will slowly decrease, until the
 buffer is empty. Then the multiplexer will enter prebuffering, and wait again
@@ -188,7 +213,7 @@ whose length corresponds to the prebuffering.
 
 Or the sound card clock is a bit fast, and the buffer will be filled up faster
 than data is consumed by the multiplexer. At some point, the buffer will hit
-the maximum size, and one superframe will be discarded. This also creates an
+the maximum size, and one frame will be discarded. This also creates an
 audible glitch.
 
 Consumer grade sound cards have clocks of varying quality. While these glitches
@@ -198,7 +223,7 @@ behaviour in intervals that are not acceptable, e.g. more than once per hour.
 Both situations are suboptimal, because they lead to audio glitches, and also
 degrade the ability to compensate for network latency changes. It is preferable
 to use the drift compensation feature available in ODR-AudioEnc, which
-insures that the encoder outputs the AAC bitstream at the nominal rate, aligned
+insures that the encoder outputs the encoded bitstream at the nominal rate, aligned
 to the NTP-synchronised system time, and not to the sound card clock. The sound
 card clock error is compensated for inside the encoder.
 
@@ -209,26 +234,31 @@ In order to be able to use the Internet as contribution network, some form of
 protection has to be put in place to make sure the audio data cannot be altered
 by third parties. Usually, some form of VPN is set up for this case.
 
-Alternatively, the encryption mechanism ZeroMQ offers can also be used. To do
-this, it is necessary to set up keys and to distribute them to the encoder and
-the multiplexer.
+% Previous versions described the ZeroMQ encryption functionality here.
 
-\begin{lstlisting}
-    encryption 1
-    secret-key "keys/mux.sec"
-    public-key "keys/mux.pub"
-    encoder-key "keys/encoder1.pub"
-\end{lstlisting}
+\subsubsection{Between Multiplexer and Modulator}
 
-\sidenote{Add configuration example}
+The EDI protocol can also carry data of a complete ensemble from ODR-DabMux to
+one or more instanced of ODR-DabMod.
 
-\subsubsection{Between Multiplexer and Modulator}
+\subsection{ZeroMQ}
+\label{sec:zeromq}
+Previous versions of this guide described an IP protocol based on
+ZeroMQ, a library that permits the creation
+of a socket connection with automatic connection management (connection,
+disconnection, error handling). This has now been deprecated in favour of
+the standards compliant EDI, which, when carried over TCP, can also be
+used over congested networks like the Internet.
+
+ZeroMQ was used both between for encoded audio contribution and for distribution
+of ensemble data, and was a custom, non-specified protocol. It was created
+before EDI got implemented in the ODR-mmbTools, and because carrying ETI inside
+IP was not sufficient for carrying complete timestamps, and because there was no
+other obvious option for audio contribution besides inventing a custom protocol.
 
-The ZeroMQ connection can also be used to connect ODR-DabMux to one or more
-instances of ODR-DabMod.  One ZeroMQ frame contains four ETI frames, which
-guarantees that the modulator always assembles the transmission frame in a
-correct way, even in Transmission Mode I, where four ETI frames are used
-together.
+Now that it is proven that EDI-over-TCP can work satisfactorily over congested
+networks, there is no reason for a protocol that is not conforming to ETSI
+specifications to exist anymore.
 
 \subsection{Pipes}
 
@@ -237,6 +267,6 @@ multiplexer on the same machine. It uses the same configuration as the file
 input but instead of using files, FIFOs, also called ``named pipes'' are
 created first using \texttt{mkfifo}.
 
-This setup is deprecated in favour of the ZeroMQ interface.
+This setup is deprecated in favour of EDI.
 
 % vim: spl=en spell tw=80 et
diff --git a/introduction.tex b/introduction.tex
index ff6357b..6a6658c 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -113,9 +113,7 @@ a real-time streaming scenario (e.g.~in a transmitter).
 
 ODR-DabMux can read input audio or data from files (``.mp2'' for DAB, ``.dabp'' for
 \dabplus), FIFOs (also called ``named pipes''), or from a network connection. This
-network connection can use UDP or ZeroMQ. The CURVE authentication mechanism
-from ZeroMQ can also be used to authenticate the encoder, in order to prevent
-third parties from disrupting or hijacking programmes.
+network connection can use UDP (STI-D) or EDI.
 
 The configuration of the multiplexer is given in a configuration file, whose
 format is defined in the example files in the \verb+doc/+ folder inside the
@@ -134,7 +132,7 @@ software-defined radio (SDR) devices using the
 SoapySDR\footnoteurl{https://github.com/pothosware/SoapySDR/wiki} library.
 
 The output of the modulator can also be sent to a GNURadio flow-graph for
-further processing, conversion or analysis using a ZeroMQ interface.
+further processing, conversion or analysis using a ZeroMQ network connection.
 
 \subsubsection{ODR-AudioEnc}
 The ODR-AudioEnc encoder can be used to encode for DAB and \dabplus. It includes
@@ -147,7 +145,7 @@ Another encoder called twolame is not compatible with DAB even though it is more
 recent than TooLAME, and cannot be used for our application.
 
 The framing and error correction which are needed for \dabplus{}, as well as the
-programme-associated data (PAD) insertion, the output to the ZeroMQ interface,
+programme-associated data (PAD) insertion, the output EDI protocol,
 and the input from Advanced Linux Sound Architecture (ALSA) were then added by
 different parties.
 
diff --git a/mmbtools.tex b/mmbtools.tex
index 576e947..af600b7 100644
--- a/mmbtools.tex
+++ b/mmbtools.tex
@@ -146,7 +146,7 @@ clock_config_t},
 
     \begin{center}
         \Large
-        Opendigitalradio\\\href{http://opendigitalradio.org}{http://opendigitalradio.org}\\2014--2018
+        Opendigitalradio\\\href{http://opendigitalradio.org}{http://opendigitalradio.org}\\2014--2019
     \end{center}
     \vspace{\fill}
     \vspace*{\stretch{2}}
diff --git a/production.tex b/production.tex
index 51430b5..af0a073 100644
--- a/production.tex
+++ b/production.tex
@@ -15,8 +15,8 @@ First, let us outline what our desired setup shall include:
         encoders;
     \item One machine is used for audio encoding web-streams, multiplexing and
         modulation;
-    \item ODR-AudioEnc instances will connect over ZeroMQ to ODR-DabMux,
-        ODR-DabMod will use a TCP connection ODR-DabMux;
+    \item ODR-AudioEnc instances will connect over EDI to ODR-DabMux,
+        ODR-DabMod will use EDI to connecto to ODR-DabMux;
     \item All audio encoders will insert PAD with DLS, and optionally slideshow;
     \item We are transmitting using a USRP B200, driving a power amplifier;
     \item We enable both telnet and zmq remote control interfaces for management
diff --git a/sfn.tex b/sfn.tex
index 8b243c3..d2eda4d 100644
--- a/sfn.tex
+++ b/sfn.tex
@@ -37,10 +37,10 @@ an SFN setup.
 Most importantly, the timestamp feature must be enabled using the ``tist'' option in
 the ``general'' section.
 
-Furthermore, it is recommended to use the ZeroMQ transport between the
+Furthermore, it is recommended to use the EDI transport between the
 multiplexer and the modulators, which can be enabled in the ``outputs'' section.
 Care has to be taken to have an output that slows ODR-DabMux down to nominal
-rate. The ZeroMQ output alone does not enforce this. The following listing shows
+rate. The EDI output alone does not enforce this. The following listing shows
 the relevant options we just covered.
 
 \begin{lstlisting}
@@ -52,8 +52,16 @@ general {
 ...
 
 outputs {
-    ; Accept connections on all interfaces, on port 9100
-    zmq  "zmq+tcp://*:9100"
+    ; Accept connections on all interfaces, on port 13000
+    edi {
+        destinations {
+            tcp {
+                protocol tcp
+                listenport 13000
+            }
+        }
+        enable_pft  false
+    }
     ; This throttles muxing down to nominal rate
     throttle "simul://"
 }
diff --git a/systemenvironments.tex b/systemenvironments.tex
index 64aab2c..1267c0d 100644
--- a/systemenvironments.tex
+++ b/systemenvironments.tex
@@ -169,9 +169,10 @@ In addition to basic system measurements like CPU, RAM and disk usage, NTP
 synchronisation, disk and network performance, there are custom data sources
 available for ODR-DabMux and ODR-DabMod.
 
-The ODR-DabMux data sources include ZMQ input buffer monitoring (buffer level,
-underruns and overruns) and the peak audio input levels (mono, or stereo). The
-plugin for ODR-DabMod can monitor SDR device statistics among others.
+The ODR-DabMux data sources include EDI and ZMQ input buffer monitoring (buffer
+level, underruns and overruns) and the peak audio input levels (mono, or
+stereo). The plugin for ODR-DabMod can monitor SDR device statistics among
+others.
 
 The plugins are written in python and are located in the \verb+doc+ folder in
 the repositories. Copy them to \texttt{/etc/munin/plugins.d} and restart