introduction.tex

% LICENSE: see LICENCE
\section{Introduction}
This is the official documentation for the \mmbtools. These tools can be used to
experiment with digital audio broadcasting (DAB) modulation, to learn the
techniques behind it, and to set up a DAB or \dabplus transmitter.

This documentation assumes that you are already familiar with the basic concepts
of the DAB system. Understanding how the DAB transmission chain is structured is
a prerequisite for getting started with the \mmbtools. The ``DAB Bible'' by Hoeg
and Lauterbach~\cite{hoeg}, and the ``Guide to DAB standards'' from the
ETSI~\cite{etsidabguide} can be used as a starting point.

In this document, the terms ``DAB'' and ``\dabplus'' are used somewhat
interchangeably, since many parts of the transmission chain are identical
between the two variants. In most cases, ``DAB'' will be used, and ``\dabplus''
when talking about specific details about the newer version of the standard.


\section{Purpose}
The individual programs that make up the \mmbtools each have their own
documentation for command-line options and configuration settings, and the
opendigitalradio.org wiki\footnoteurl{http://opendigitalradio.org} contains many
explanations and pointers, but there is no single source of documentation
available for the whole toolset.

This document aims to fill this gap, by first outlining general concepts, then
presenting different usage scenarios, and finally, detailing a complete
transmission setup.
With this document in hand, you should be able to understand all of the elements
which go into the \mmbtools transmission chain, and how to set one up.

Please refer to the bibliography for references on any individual topic that may need
clarification, to the README files in the repositories of the tools that are
going to be presented in this guide, and if you have further questions, get in
touch with us through the mailing-list mentioned on our website.

\section{Presentation of the Tools}
\subsection{Origins}
Before we begin with technical details, first a word about the history of
the mmbTools.
In 2002, Communications Research Centre Canada\footnoteurl{http://crc.ca}
started developing a DAB multiplexer. This effort evolved through the years, and
was published in September 2009 as \mbox{CRC-DabMux} under the GPL
open-source licence.

CRC also developed a DAB modulator, called \mbox{CRC-DABMOD}, which was able to create
baseband complex quadrature (I/Q) samples from files or
streams in the ETI format. This I/Q data could then be sent to a hardware device
(for broadcast or laboratory RF measurements) using another tool. For driving
the universal software-defined radio peripherals (USRP) made by the company
Ettus Research, a ``wave player'' script was necessary to interface with GNURadio.
Only DAB Transmission Mode 2 was supported. \mbox{CRC-DABMOD} was also released
under the GPL in early 2010.

As encoders, toolame could be used for DAB, and CRC developed a closed-source
\mbox{CRC-DABPLUS} \dabplus encoder.

These three CRC-tools, and some additional services available on the now
unreachable website\footnote{There are some snapshots of the website available
    on \url{http://archive.org}.}
\url{http://mmbtools.crc.ca} were part of the \mbox{CRC-mmbTools}. These tools
made it possible to set up the first DAB transmission experiments.

In 2012, these tools received experimental support for single-frequency
networks, a functionality that has been developed by Matthias P. Brändli during
his Master's thesis\footnote{The corresponding report is available at
    \url{http://mpb.li/report.pdf}}.
Because SFNs are mainly used in TM 1, CRC subsequently released a patch to
\mbox{CRC-DABMOD} that enabled all four transmission modes.

At that point, involvement from CRC started to decline. The SFN patch was
ultimately never included in the \mbox{CRC-mmbTools}, and as time passed, the
de-facto fork on \url{http://mpb.li} was receiving more and more features.
Having two different programs with the same name made things complicated, and
so, with the approval of CRC, the tools were officially forked in February 2014,
and given the new name \mbox{ODR-mmbTools}. They are now developed by the
Opendigitalradio association.

In April 2014, the official \mbox{CRC-mmbTools} website went offline, and it has
become very difficult, if not impossible, to acquire licences for the
\mbox{CRC-DABPLUS} encoder. Luckily there is an open-source replacement
available, which was part of Google's Android source. This encoder has been
extended with the necessary \dabplus{}-specific requirements (960-transform,
error correction, framing, etc.), and now exists under the name
\mbox{fdk-aac}. The encoder \mbox{ODR-AudioEnc} can use this library to encode for
\dabplus{}.

\subsection{Included Tools}
The \mmbtools are composed of several software projects:
\mbox{ODR-DabMux}, \mbox{ODR-DabMod},
\mbox{ODR-AudioEnc}, \mbox{ODR-PadEnc}, and other scripts, bits and pieces
that are useful when setting up a transmission chain.

\begin{figure}[H]
    \centering
    \smartdiagram[bubble diagram]{
        ODR-\\ mmbTools,
        ODR-DabMux,
        ODR-DabMod,
        ODR-PadEnc,
        etisnoop,
        ODR-\\ AudioEnc,
        ODR-\\ SourceCompanion,
        ODR-\\ EncoderManager
    }
    \caption{The family of ODR-mmbTools}
    \label{fig:family_mmbTools}
\end{figure}

\subsubsection{ODR-DabMux}
ODR-DabMux implements a DAB multiplexer that combines all audio and data inputs
and outputs them in the form of a file in ETI format. This can be used offline
(i.e.~not in real time) to generate ETI data for processing later, or for use in
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 (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
ODR-DabMux repository.


\subsubsection{ODR-DabMod}
ODR-DabMod is a software-defined DAB modulator that receives or reads ETI data
in streams or from files, and generates modulated I/Q data which can be used for
transmission.

This I/Q data which is encoded as complex floats (32bits per complex sample) can
be written to a file or pipe, sent to a USRP device using the integrated
output for the open-source USRP Hardware Driver (UHD) or to other
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 network connection.

\subsubsection{ODR-AudioEnc}
The ODR-AudioEnc encoder can be used to encode for DAB and \dabplus. It includes
a TooLAME-based MPEG encoder, and uses the \mbox{fdk-aac} library as an external
dependency to encode \dabplus{}.

The integrated TooLAME library is an MPEG-1 Layer II audio encoder that is used
to encode audio for the DAB standard.
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 EDI protocol,
and the input from Advanced Linux Sound Architecture (ALSA) were then added by
different parties.

\subsubsection{ODR-PadEnc}
This encoder is able to generate programme-associated data (PAD) that can be
injected into ODR-AudioEnc. It supports reading and encoding Dynamic Label
Segment (DLS) from a text file, and reads images from a folder for MOT Slideshow.

\subsubsection{ODR-EncoderManager}
The ODR-EncoderManager presents a web-based interface that allows the user to
create, manage and run audio and PAD encoders, and presents a HTTP API to update
Dynamic Label Segment and Slides. One instance can handle several audio encoders
simultaneously, and offers a simpler way to manage the audio encoding part of
the \dabplus transmission chain.

\subsubsection{ODR-SourceCompanion}
This tool allows using third party audio encoders with the ODR-mmbTools.

\subsubsection{etisnoop}
Etisnoop is not used in the broadcasting chain directly, but is an analysis tool
for ETI, described in the ETSI standard~\cite{etsidabeti}. ODR-DabMux can write
an ETI file that can be analysed with etisnoop. The tool can be used to verify
the multiplex signalling, the presence of data in the subchannels, and it can
decode audio into files.

Additionally, it can output statistics in YAML format, which is useful in
combination with an RTLSDR receiver and the \verb+dab2eti+ tool to monitor
transmissions.

\clearpage
\section{Installing the Tools}
There are 3 ways to install the tools.

\subsection{Debian Binary Packages}
If your host is running a debian-based operating system and its
architecture is either amd64, arm64 or arm/v7, then you can easily install
ODR-AudioEnc, ODR-PadEnc, ODR-DabMux and ODR-DabMod
from the ODR package repository by applying the following steps:

\begin{lstlisting}
    #replace bullseye (debian-11) with bookworm (debian-12) if applicable
    curl -fsSL http://debian.opendigitalradio.org/opendigitalradio-bullseye.sources > /etc/apt/sources.list.d/opendigitalradio-bullseye.sources
    curl -fsSL http://debian.opendigitalradio.org/opendigitalradio.asc | gpg --dearmor > /etc/apt/trusted.gpg.d/opendigitalradio.gpg
    apt update
    sudo apt install --yes odr-audioenc odr-padenc odr-dabmux odr-dabmod
\end{lstlisting}

\paragraph{Remarks}
The \texttt{odr-dabmux} and \texttt{odr-dabmod} packages do not include the web-based GUI Mux Manager
and the GUI and Digital Predistortion Computation engine. If you need those, then you
should look at the other 2 installation options below.

\subsection{Opendigitalradio-provided Installation Script}
This option allows you to compile and install:
\begin{itemize}
    \item the above 4 main components of the tools

    \item the web-based ODR-EncoderManager, GUI Mux Manager and GUI and Digital
        Predistortion Computation engine
    \item sample configuration files for a live broadcast
\end{itemize}

Apply the following steps:
\begin{lstlisting}
    sudo apt update && sudo apt upgrade --yes
    sudo timedatectl set-timezone your_timezone
    cd ${HOME}
    git clone https://github.com/opendigitalradio/dab-scripts.git
    sudo bash ${HOME}/dab-scripts/install/mmbtools-get install
\end{lstlisting}

\paragraph{Remarks}
The installation script will compile the tools with all the possible features
in order to give you the greatest configuration flexibility. It will also
install the \texttt{supervisord} package with the configuration files for
a live broadcasting of 2 dab+ programs. For more installation details, please
refer to the install/README.md file in the github repository.

\subsection{Manual Compilation}
If you wish to compile and install some tools only and reduce disk usage by
selecting the needed features, then you should follow the instructions given
with each tool:

\begin{itemize}
    \item \texttt{odr-audioenc} https://github.com/opendigitalradio/odr-audioenc
    \item \texttt{odr-padenc} https://github.com/opendigitalradio/odr-padenc
    \item \texttt{odr-dabmux} https://github.com/opendigitalradio/odr-dabmux
    \item \texttt{odr-dabmod} https://github.com/opendigitalradio/odr-dabmod
\end{itemize}

% vim: spl=en spell tw=80 et