aboutsummaryrefslogtreecommitdiffstats log msg author committer range
path: root/introduction.tex
blob: 6a6658cbe26c096c89120e477969c95fc5d9db93 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168  pre { line-height: 125%; margin: 0; } td.linenos pre { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; } span.linenos { color: #000000; background-color: #f0f0f0; padding: 0 5px 0 5px; } td.linenos pre.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; } span.linenos.special { color: #000000; background-color: #ffffc0; padding: 0 5px 0 5px; } .highlight .hll { background-color: #ffffcc } .highlight .c { color: #888888 } /* Comment */ .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ .highlight .k { color: #008800; font-weight: bold } /* Keyword */ .highlight .ch { color: #888888 } /* Comment.Hashbang */ .highlight .cm { color: #888888 } /* Comment.Multiline */ .highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */ .highlight .cpf { color: #888888 } /* Comment.PreprocFile */ .highlight .c1 { color: #888888 } /* Comment.Single */ .highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */ .highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */ .highlight .ge { font-style: italic } /* Generic.Emph */ .highlight .gr { color: #aa0000 } /* Generic.Error */ .highlight .gh { color: #333333 } /* Generic.Heading */ .highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */ .highlight .go { color: #888888 } /* Generic.Output */ .highlight .gp { color: #555555 } /* Generic.Prompt */ .highlight .gs { font-weight: bold } /* Generic.Strong */ .highlight .gu { color: #666666 } /* Generic.Subheading */ .highlight .gt { color: #aa0000 } /* Generic.Traceback */ .highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */ .highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */ .highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */ .highlight .kp { color: #008800 } /* Keyword.Pseudo */ .highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */ .highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */ .highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */ .highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */ .highlight .na { color: #336699 } /* Name.Attribute */ .highlight .nb { color: #003388 } /* Name.Builtin */ .highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */ .highlight .no { color: #003366; font-weight: bold } /* Name.Constant */ .highlight .nd { color: #555555 } /* Name.Decorator */ .highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */ .highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */ .highlight .nl { color: #336699; font-style: italic } /* Name.Label */ .highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */ .highlight .py { color: #336699; font-weight: bold } /* Name.Property */ .highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */ .highlight .nv { color: #336699 } /* Name.Variable */ .highlight .ow { color: #008800 } /* Operator.Word */ .highlight .w { color: #bbbbbb } /* Text.Whitespace */ .highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */ .highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */ .highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */ .highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */ .highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */ .highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */ .highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */ .highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */ .highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */ .highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */ .highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */ .highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */ .highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */ .highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */ .highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */ .highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */ .highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */ .highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */ .highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */ .highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */ .highlight .vc { color: #336699 } /* Name.Variable.Class */ .highlight .vg { color: #dd7700 } /* Name.Variable.Global */ .highlight .vi { color: #3333bb } /* Name.Variable.Instance */ .highlight .vm { color: #336699 } /* Name.Variable.Magic */ .highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */% LICENSE: see LICENCE \section{Introductions} 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 } \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{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. % vim: spl=en spell tw=80 et