supervision.tex

% LICENSE: see LICENCE
\section{Supervision of Transmitted Ensembles}
\subsection{Introduction} 
We have previously 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 at a remote site within the coverage area 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 see 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