From 1601de0ac4d25b85a4f1741e33602e7f20dbbef5 Mon Sep 17 00:00:00 2001
From: "Matthias P. Braendli" <matthias.braendli@mpb.li>
Date: Wed, 20 Jun 2018 16:18:01 +0200
Subject: Add chapter about external ensemble supervision

---
 supervision.tex | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 supervision.tex

(limited to 'supervision.tex')

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
-- 
cgit v1.2.3

