Add chapter about external ensemble supervision

4 files changed, 95 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index 7055472..6ba128f 100644
--- a/Makefile
+++ b/Makefile
@@ -6,7 +6,8 @@ includes = introduction.tex \
 		   systemenvironments.tex \
 		   production.tex \
 		   datafeatures.tex \
-		   sfn.tex
+		   sfn.tex \
+		   supervision.tex
 
 bib = dab.bib
 
diff --git a/mmbtools.tex b/mmbtools.tex
index 89459b6..576e947 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--2017
+        Opendigitalradio\\\href{http://opendigitalradio.org}{http://opendigitalradio.org}\\2014--2018
     \end{center}
     \vspace{\fill}
     \vspace*{\stretch{2}}
@@ -205,6 +205,7 @@ clock_config_t},
 \include{systemenvironments}
 \include{production}
 \include{sfn}
+\include{supervision}
 \appendix
 \include{appendix}
 
diff --git a/supervision.tex b/supervision.tex
new file mode 100644
index 0000000..4c5923c
--- /dev/null
+++ b/supervision.tex
@@ -0,0 +1,90 @@
+% LICENSE: see LICENCE
+\section{Supervision of Transmitted Ensembles}
+\subsection{Introduction}
+We have seen a way to monitor the transmission infrastructure (or at least some
+of its essential parts) in chapter \ref{monitmunin} about munin monitoring.
+These monitoring elements give an indication about ODR-DabMux and ODR-DabMod
+health from within the infrastructure itself, and may not be able to inform you
+about some issues happening outside of the software tools.
+
+Monitoring the transmitted signal from an external place can complement the
+internal monitoring and broaden the supervision coverage. In the end, we can
+only consider the broadcast system being in an operational state if a receiver
+can play all programmes, and being able to verify this automatically by placing
+a receiver in the field is the only way to ensure this.
+
+In this chapter, we will see one way to achieve this.
+
+\subsection{Welle.io Software-Defined Receiver}
+The welle.io\footnote{Project page: \url{http://welle.io}, sources on:
+\url{https://github.com/AlbrechtL/welle.io}} project offers an SDR DAB receiver
+that can run both with a graphical user interface for ease of use, and as a
+command-line tool that can be used for automated systems.
+The command-line tool called \texttt{welle-cli} presents an HTTP API that makes
+ensemble parameters and audio content available to third party tools. Until this
+tool becomes part of a released version, checkout the \texttt{next} branch and
+compile it using CMake, as described in the readme. Execute it directly from the
+build folder, so that it also can access the \texttt{index.html} file.
+
+welle-cli can present the ensemble data in more than one way, but we will focus
+on the HTTP interface. It is enabled with the \texttt{-w 7979} option, which
+will run the HTTP server on port 7979. Select the channel to receive, e.g.~10A, with
+\texttt{-c 10A}.
+When you point your browser to \url{http://localhost:7979}, you will get a
+simple web-page that shows a subset of the data available through the API. When
+pressing a Play button, \texttt{welle-cli} will start decoding the selected
+sub-channel and stream it to the browser as an MP3 stream.\footnote{MP3 is used
+because it is the only compressed audio format that is supported in all
+browsers. The AAC or MP2 audio inside the ensemble is re-encoded by
+\texttt{welle-cli} using the LAME encoding library.}
+
+Several options are available for decoding the programmes: use \texttt{-D} to
+decode all audio and PAD simultaneously. This requires a powerful PC. Use
+\texttt{-C} to decode the audio in a carousel, i.e.~one-by-one. When using
+\texttt{-CP} the decoder remains up to 80s on a programme, but switches
+programmes once a slide was correctly decoded. Compared to \texttt{-C} alone,
+this improves the likelihood of decoding slideshow at the expense of a lower
+audio level update rate.
+
+While this web-page already has some utility as-is, it mainly serves as an
+illustration of what can be done with the API, where the real value of
+\texttt{welle-cli} resides. The API is, for the moment, quite simple:
+\begin{itemize}
+    \item \texttt{/mux.json} contains most information in JSON format. From
+        this JSON you can extract the list of services, the ensemble parameters,
+        TII decoding and other information.
+    \item \texttt{/mp3/SID} will give you a live mp3 stream of the primary
+        component of the given service id.
+    \item \texttt{/fic} will send a data stream containing the FIC. This can be
+        saved to file and analysed offline with other tools, among which
+        etisnoop (using its \texttt{-I} option). etisnoop is also able to do
+        live analysis of the FIC, e.g. with
+        \verb+curl -s http://localhost:7979/fic|etisnoop -I /dev/stdin+
+        whose YAML output can in turn be processed further.
+    \item \texttt{/channel} will return the currently tuned channel on
+        receiving a GET request, and set the channel and restart the receiver on
+        receiving a POST.
+\end{itemize}
+
+Other HTTP URLs give back information that needs to be processed further.
+See the script code inside \texttt{index.html} to understand how to work with
+it.
+
+\begin{itemize}
+    \item \texttt{/spectrum} will send a sequence of float values that
+        show the spectrum power density of the signal.
+    \item \texttt{/nullspectrum} will send a sequence of float values that
+        show the spectrum power density of the NULL symbol, where the TII
+        carriers are visible.
+    \item \texttt{/constellation} will send a sequence of complex float I/Q
+        values corresponding to the demodulated constellation points.
+    \item \texttt{/impulseresponse} will send a sequence of float values that
+        represent the measured channel impulse response.
+\end{itemize}
+
+An example integration into a monitoring system is given in the
+\texttt{welle-cli-munin.py} script. This munin plugin fetches the
+\texttt{mux.json} and converts the audio levels in a format that munin can
+graph. In this way, an entire ensemble can be monitored at once.
+
+% vim: spl=en spell tw=80 et
diff --git a/systemenvironments.tex b/systemenvironments.tex
index 62853b3..64aab2c 100644
--- a/systemenvironments.tex
+++ b/systemenvironments.tex
@@ -159,6 +159,7 @@ Please see \url{https://wiki.opendigitalradio.org/SNMP} for information about
 this effort.
 
 \subsection{Monitoring using munin}
+\label{monitmunin}
 The Munin\footnote{\url{http://munin-monitoring.org/}} monitoring tool can
 create graphs for essential system health parameters. It can also send emails
 if values transgress the defined bounds - this assists the operator in the