\section{Introduction}
This is the official documentation for the \mmbtools. These tools can be used to
experiment with DAB modulation, learn the techniques behind it and setup a DAB
or \dabplus transmitter.

This documentation assumes that you are already familiar with base concepts of
the DAB system. To get started with the \mmbtools, understanding how the DAB
transmission chain is structured is a prerequisite. 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 different programs that are part of the \mmbtools each have their own
documentation regarding 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 tool-set.

This document aims to solve this, by first outlining general concepts,
presenting different usage scenarios and detailing a complete transmission
setup.

With this document in hand, you should be able to understand all elements
composing a \mmbtools transmission chain, and how to set one up.

\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 could create
baseband I/Q samples from an ETI file. This I/Q data could then be set to
a hardware device using another tool. For the Ettus USRPs, a ``wave player''
script was necessary to interface to 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
finally never included in the \mbox{CRC-mmbTools}, and as time passed by, 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
the tools were officially forked with the approval of CRC 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 sources. 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-DABplus}.

\subsection{Included Tools}
The \mmbtools are composed of several software projects:
\mbox{ODR-DabMux}, \mbox{ODR-DabMod},
\mbox{Toolame-DAB}, \mbox{FDK-AAC-DABplus}, and other scripts, bits and pieces
that are useful for the setup of a transmission chain.

\subsubsection{ODR-DabMux}
ODR-DabMux implements a DAB multiplexer that combines all audio and data inputs
into an ETI output. It can be used off-line (i.e.~not real-time) to generate ETI
data for later processing, or in a real-time streaming scenario (e.g.~in a
transmitter).

It can read input audio or data from files (``.mp2'' for DAB, ``.dabp'' for
\dabplus), FIFOs (also called ``named pipes'') or a network connection. The
network connection can use UDP or ZeroMQ. The CURVE authentication mechanism
from ZeroMQ can also be used to authenticate the encoder, in order to avoid that
a third-party can disrupt or hijack a programme.

The ensemble configuration can be specified on the command line using the
options described in the manpage, or using a configuration file. The command
line options are kept to be compatible with CRC-DABMUX, but using the
configuration file is preferred, because it supports more options.


\subsubsection{ODR-DabMod}
ODR-DabMod is a software-defined DAB modulator that receives or reads ETI, and
generates modulated I/Q data usable for transmission.

This I/Q data which is encoded as complex floats (32bits per complex sample) can
be written to a file or pipe, or sent to a USRP device using the integrated UHD
output. Other SDR platforms can be used if they are able to accept the I/Q data.
The output of the modulator can also be used in GNURadio if format conversion or
graphical analysis (spectrum) is to be done.

\subsubsection{Toolame-DAB}
TooLAME is a MPEG-1 Layer II audio encoder that is used to encode audio for the
DAB standard. The original project has been unmaintained since 2003, but the
twolame fork that pursues the development removed the DAB framing. Because of
this, twolame is not suitable for DAB.

The Toolame-DAB fork includes the ZeroMQ output and PAD insertion support, but
the audio coder is the same as the one in tooLAME.

\subsubsection{FDK-AAC-DABplus}
The FDK-AAC-DABplus encoder can be used to encode for \dabplus. The encoder
itself comes from the Android sources, and was written by Fraunhofer.

The necessary framing and error-correction that \dabplus mandates, the PAD
insertion, the ZeroMQ output and the ALSA input were then added by different
parties.



% vim: spl=en spell tw=80 et
