% LICENSE: see LICENCE
\section{Usage Scenarios}
\subsection{Experimentation}
\subsubsection{Creation of Non-Realtime Multiplex}
The creation of a ETI file containing two programmes, one DAB and one
\dabplus{} is covered in section \ref{sec-files}.

\subsubsection{Modulation of ETI for Offline Processing}
The ETI file generated before can then be used with ODR-DabMod to produce a
file containing I/Q samples. Here, we must chose between using the command line
or the configuration file. For a very simple example, using the command line
makes sense, but for more advanced features it is preferable to use a
configuration file. For illustration, we will present both.

To modulate the file \texttt{myfirst.eti} into \texttt{myfirst.iq}, with the
default options, the command is simply

\begin{lstlisting}
odr-dabmod myfirst.eti -f myfirst.iq -n 1
\end{lstlisting}

This will create a file containing 32-bit interleaved I/Q at $2048000$ samples
per second. Where the maximal amplitude is bounded by 1.The transmission mode
is defined by the ETI file.

The equivalent configuration file would be
\begin{lstlisting}
[input]
transport=file
source=myfirst.eti

[output]
output=file

[fileoutput]
format=complexf
normalize=1
filename=myfirst.iq
\end{lstlisting}

This is a very minimal file that defines only the necessary settings equivalent
to the above command line options. The configuration file however supports more
options that the command line, and becomes easier to manager once the set
becomes more complex. It is best to use the example configuration available in
the \texttt{doc/} folder.

\subsection{Interfacing Hardware Devices}
\subsubsection{Ettus USRP}
ODR-DabMod integrates support for the UHD library that can interface with all
USRP devices from Ettus. The following configuration file \texttt{mod.ini}
illustrates how to send the \texttt{myfirst.eti} over a USRP B200 on channel
13C:

\begin{lstlisting}
[remotecontrol]
telnet=1
telnetport=2121

[input]
transport=file
source=myfirst.eti
loop=1

[modulator]
digital_gain=0.8

[firfilter]
enabled=1

[output]
output=uhd

[uhdoutput]
master_clock_rate=32768000
type=b200
txgain=40
channel=13C
\end{lstlisting}

This example also shows more options that the example for the file output:

\begin{itemize}
    \item \texttt{remotecontrol telnet=1} enables the Telnet server that can be
        used to set parameters while the modulator is running.
    \item \texttt{loop=1} rewinds the input file when the end is reached. The
        same ETI file will be transmitted over and over.
    \item \texttt{digital\_gain=0.8} reduces the output sample deviation, to
        reduce compression in the USRP.
    \item \texttt{firfilter enabled=1} enables the FIR filter to improve
        the spectrum mask. If you want to customise the filter used, you can
        create your own filter taps file using
        \texttt{ODR-DabMod/doc/fir-filter/generate-filter.py}.
    \item \texttt{master\_clock\_rate=32768000} sets the USRP internal clock to
        a multiple of $2048000$, which is required if we want to use the native
        DAB sample rate.
    \item \texttt{txgain=40} Sets the analog transmit gain of the USRP to 40dB,
        which is specific to the B200. If you go above 70dB you will start to
        see nonlinearities.
\end{itemize}

Some of these options are not necessary for the system to work, but they
improve the performance.

\paragraph{Remarks concerning the USRP B200}
\label{usrp_b200}
The USRP B200 depicted in figure~\ref{fig:usrp-b200} is the device we are using
most. It's performance is proven in a production environment, it supports the
transmit synchronisation necessary for SFN and is robust enough for 24/7
operation.

\begin{wrapfigure}{r}{13em}
    \centering
    \includegraphics[width=12em]{figures/USRP-B200.jpg}
    \caption{Ettus USRP B200}
    \label{fig:usrp-b200}
\end{wrapfigure}


However, care has to be taken about the host system, especially about the USB
controller. Using USB~2.0 is not a problem for a DAB transmission, both USB~2.0
and USB~3.0 host controllers can therefore be used. Since USB~2.0 has been
around for longer and is more mature, it is sometimes preferable because it
causes less USB errors. This heavily depends on the exact model of the USB
controller inside the host PC, and has to be tested for each system.

The txgain on the B200 varies between $0$dB and about $90$dB. Experience shows
that compression effects begin to appear at values around $85$dB. This might be
different from device to device and needs to measured.

Similarly, the digital gain must be optimised for a given setting. It is
important that there is no digital clipping in the chain, because that leads to
problematic spurious spectrum components, that can disturb or even damage a
power amplifier.

There are some performance measurements available on the Opendigitalradio
wiki.\footnote{\url{http://wiki.opendigitalradio.org/index.php/USRP\_B200\_Measurements}}

\paragraph{Remarks concerning other USRP models}
We have used the USRP1, the USRP2 and the USRP B100 with the tools. The WBX is
the most appropriate daughterboard for these models.

The txgain setting has another range, it is best to start at $0$dB, and increase
it in steps of $3$dB or smaller while measuring the output signal, until the
correct power is reached.

\subsubsection{SoapySDR}
\label{otherhardware}
ODR-DabMod supports other radio interfaces using the
SoapySDR\footnote{\url{https://github.com/pothosware/SoapySDR/wiki}}
vendor-neutral and platform independent library to drive SDR devices. It can be
used to drive the LimeSDR boards, the HackRF from Great Scott Gadgets and the
Fairwaves XTRX devices, among others. Installation dependencies are shown in the
\texttt{INSTALL} file, and an example configuration is in
\texttt{doc/example.mux}.

We are going to illustrate this with the HackRF.
The HackRF is an entry level yet versatile SDR which provides coverage between
$\approx10$MHz to $6$GHz, and DAB signals been successfully generated with it in
VHF Band III ($174$--$240$MHz), L-Band ($1462$--$1467.5$MHz) and even the worldwide ISM
Band ($2400$--$2500$MHz). The latter (subject to local regulations) is a licence exempt
band which may be useful for performing freely radiating tests at low power. Cheap
MMDS converters are currently available which helpfully provide a Band III IF output
providing a direct feed to the aerial input of a receiver. Before choosing a converter
it is important to pay close attention to the specifications. The local oscillator
phase noise performance, and the dynamic range (due to the heavy use of the band) are
both particularly important.

The HackRF has selectable baseband filters, however the lowest filter setting
($1.75$MHz) does not provide adequate image rejection at the native sampling rate of
$2048$k samples per second. An appropriate rate to start with is $4096$k, and for
some purposes this may well be adequate as this moves the image signals
generated within the radio far enough into the stop-band of filter to attenuate
them significantly. Since ODR-DabMod v1.0.1, the digital gain setting is not
be influenced by the sample rate anymore, and should be set below 1, with some
margin, to avoid digital clipping on modulation peaks.

Depending on the capabilities of the host computer, using higher sampling rates
($6144$k, and even $8192$k) may be possible. This oversampling is desirable as
it helps to produce a cleaner spectral output. At higher rates one needs to
ensure that samples are not being dropped on the USB and that CPU resources are
not being contended.

The shoulder performance has been measured with a value at a little
better than $35$dB, which is roughly equivalent to that obtained from first
generation commercial modulator equipment. This can be increased to a relatively
respectable $\approx 40$dB by enabling the FIR baseband filter in ODR-DabMod.
The maximum output power available to meet these performance figures is
approximately $-10$dBm RMS.

The following configuration file \texttt{mod.ini}
illustrates how to send the \texttt{myfirst.eti} over a HackRF on channel
13C:

\begin{lstlisting}
[remotecontrol]
telnet=1
telnetport=2121

[input]
transport=file
source=myfirst.eti
loop=1

[modulator]
digital_gain=0.8
rate=4096000

[firfilter]
enabled=1

[output]
output=soapysdr

[soapyoutput]
device=driver=hackrf
master_clock_rate=32768000
txgain=23
channel=13C
bandwidth=1750000
\end{lstlisting}


For other SoapySDR hardware, the available device-driver, sampling rates, the 
TX gain range and the antenna selection can be discovered using the 
\texttt{SoapySDRUtil --probe} command.

\subsubsection{Other hardware}
For devices that are not offering a SoapySDR device driver, the last resort is
to use standard output or a fifo to carry the IQ data from ODR-DabMod to a tool
that can drive the device.

Example of the settings in the \texttt{mod.ini} file suitable for use with Pipe:

\begin{lstlisting}
[remotecontrol]
telnet=1
telnetport=2121

[input]
transport=file
source=myfirst.eti
loop=1

[modulator]
digital_gain=0.8
rate=4096000

[firfilter]
enabled=1

[output]
output=file

[fileoutput]
format=complexf
filename=/tmp/ofdm.fifo

\end{lstlisting}

The output fifo has to be created beforehand.

Example of using ODR-DabMod with a Pipe-driven device transfer utiliy:

\begin{lstlisting}
mkfifo /tmp/ofdm.fifo
odr-dabmod mod.ini &
device-utility --arguments
\end{lstlisting}


\subsection{Audio Sources}
Preparing a DAB multiplex with different programmes requires that we are able to
read and encode several audio sources. We have seen in
section~\ref{sec:between_encoder_and_multiplexer} how the encoders can be
interfaced to the modulator. In this section we'll go through the different ways
to carry the audio data to the encoder.

\subsubsection{Local Audio Card}
It is possible to use an audio card connected to the computer as source. For
very simple scenarios, the ALSA input for ODR-AudioEnc is easiest to set up.
This however limits the usage of a single encoder per sound-card, and will not
scale well if more than one programme has to be encoded on the machine. It is
however ideal for dedicated encoding machines that can contribute the encoded
audio over an IP network.

An alternative to using ALSA is JACK\footnote{The JACK Audio Connection Kit is a
    virtual audio patch, \url{http://www.jack-audio.org}}
that can be used with a multi-channel sound card. JACK will expose every audio
input channel, and several encoders can be launched that also connect to JACK.
The input channels can be freely connected to the encoders thanks to the virtual
JACK patch panel.

\sidenote{It might be possible to use the libVLC input too, to be defined.}

\subsubsection{Using Existing Web-Streams}
\label{usingexistingwebstreams}
One common scenario is to transmit radio stations that already are available as
web-radio streams. For simplicity, it makes sense to get these web streams,
which are most often encoded in mp3 and available through HTTP, decode them, and
use them as audio source for the DAB or \dabplus encoder.

The advantage of this approach is that the radio itself does not need to setup a
new infrastructure if the stream is of good quality. The main disadvantage is
that the audio is encoded twice, and this coding cascading degrades the audio
quality.

Often, web-streams are encoded in mp3 at $44100$Hz sample-rate, whereas DAB
is most often $48000$Hz or sometimes $32000$Hz. A sample-rate conversion is
necessary in the stream decoder.

There are many different stream decoders, and gstreamer, mpg123 and mplayer have
been tested. By far the easiest way is to use the libVLC binding that can be
compiled for ODR-AudioEnc. This library has
the same features as the VLC audio player, but the audio data is directly passed
to the encoding routines. This allows the encoder to receive all network
sources VLC supports, not only HTTP web-streams but also less common setups
e.g.\ encoded audio inside multicast UDP MPEG-TS.
This is illustrated in ``Studio A'' in figure~\ref{fig:txchain-with-encoders}.

We have also achieved good results with mplayer, and the dab-scripts
repository\footnote{\url{http://github.com/Opendigitalradio/dab-scripts}}
contains the script \texttt{encode-jack.sh} that uses mplayer, and illustrates
how it is possible to encode a web-stream to \dabplus. JACK is used to
interconnect the stream decoder to the \dabplus encoder.
This is illustrated in ``Studio B''.

\begin{figure}[h]
    \includegraphics[width=\textwidth]{figures/txchain-with-encoders.pdf}
    \caption{Three common ways to encode a remote audio sources.}
    \label{fig:txchain-with-encoders}
\end{figure}


The scripts are designed for production use, and also contain automatic restart
logic in case of a failure. They send an email and write a message into the
system log.

\subsubsection{Encoders at Programme Originator Studios}
In order to avoid the unavoidable encoder cascading when using mp3 web-streams,
the DAB or \dabplus encoder has to be moved to the programme originator's
premises, and should directly encode the audio signal coming from the studios.
This is illustrated in ``Studio C'' in figure~\ref{fig:txchain-with-encoders}.

If ``Studio C'' is able to prepare slides for MOT Slideshow and text to be sent
as DLS, ODR-PadEnc can be used to prepare the PAD data for ODR-AudioEnc.


\subsection{Advanced Signal Processing}
\subsubsection{Crest Factor Reduction}
ODR-DabMod contains a prototype for crest factor reduction (CFR), which allows you to
reduce peak-to-average power ratio (PAPR), trading off with modulation error
rate (MER). The DAB OFDM signal has a very high PAPR, which directly translates
to a decrease in power amplifier efficiency. The power amplifier has to be
driven such that the peaks do not drive it into compression, but the overall
efficiency is calculated from the average power.
Reducing the PAPR makes it possible to drive the amplifier more.

The CFR algorithm works in the following way: all the generated OFDM samples go
through a limiter, which clips the amplitude to a configurable value. This
directly reduces PAPR, but impacts both amplitude and phase of the constellation
points, thereby degrading MER. To compensate for this, a second step of the
algorithm calculates the error vector for each constellation point, and clips
the error to some maximum amplitude. The clipped error is then subtracted from
the signal, which corrects part of the distortion created by the limiter.

To summarise: a low clipping value distorts the signal more; a high error
clipping value corrects the distortion again.
In the constellation plot view, the first is seen as an increase in spread of
the points; the second is visible because it pulls the constellation points back
into a circle of radius proportional to the error clipping value.

Settings and some statistics are available through the remote control.

\subsubsection{OFDM Symbol Windowing}
One technique to improve the shoulder performance is to avoid generating abrupt
transitions between the OFDM symbols, but apply cross-fading from one symbol to
the next using a windowing function.\footnote{As of ODR-DabMod v1.0.1, this feature is
still in the \texttt{next} development branch, and not part of a released
version.}

This feature can be enabled by setting the number of samples to use for
overlapping one symbol with the next one, the default value is $10$ (out of a
total symbol length of $2552$ samples in Transmission Mode I). Refer to the
parameter \verb+ofdmwindowing+ in the file \verb+doc/example.ini+ for
instructions.

As this windowing feature modifies samples that are in the guard interval, the
trade-off is reduced resilience against delayed reflections, reduced maximum
transmitter delay difference in an SFN scenario, and potentially diminished
robustness against Doppler spread.

\subsubsection{Digital Pre-Distortion}
An ongoing activity is the development of a method to characterise a power
amplifier and predistort the I/Q samples to invert the distortion behaviour of
the amplifier. More information about this work is in the \verb+dpd/README.md+
file in ODR-DabMod.

% vim: spl=en spell tw=80 et