diff options
| -rw-r--r-- | .github/workflows/build-pdf.yml | 61 | ||||
| -rw-r--r-- | Makefile | 3 | ||||
| -rw-r--r-- | README.md | 10 | ||||
| -rw-r--r-- | appendix.tex | 10 | ||||
| -rw-r--r-- | introduction.tex | 20 | ||||
| -rw-r--r-- | mmbtools.tex | 7 | ||||
| -rw-r--r-- | sfn.tex | 3 | ||||
| -rw-r--r-- | systemenvironments.tex | 128 |
8 files changed, 90 insertions, 152 deletions
diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml new file mode 100644 index 0000000..036a55c --- /dev/null +++ b/.github/workflows/build-pdf.yml @@ -0,0 +1,61 @@ +name: build-pdf +on: + push: + branches: + - 'master' + paths-ignore: + - 'README.md' + - 'Makefile' + - 'LICENSE.txt' + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + # Checks-out the master branch of this repository + - uses: actions/checkout@v3 + with: + ref: master + path: master + + # Checks-out the gh-pages branch of this repository + - uses: actions/checkout@v3 + with: + ref: gh-pages + path: gh-pages + + # Build vc.tex + - name: build-vc + run: | + echo "%%% This file is generated by Makefile." > vc.tex + echo "%%% Do not edit this file!" >> vc.tex + echo "" >> vc.tex + git log -1 --format="format:\ + \\gdef\\GITAbrHash{%h}\ + \\gdef\\GITAuthorDate{%ad}\ + \\gdef\\GITAuthorName{%an}" >> vc.tex + working-directory: master + + # Build mmbtools.pdf + - name: build-pdf + uses: xu-cheng/latex-action@v2 + with: + working_directory: master + root_file: mmbtools.tex + post_compile: mv mmbtools.pdf ../gh-pages + + # Commit mmbtools.pdf + - name: commit-pdf + run: | + git config user.name "Open Digital Radio" + git config user.email github@opendigitalradio.org + git add -f mmbtools.pdf + git commit -m "generated by github action build-pdf" + working-directory: gh-pages + + - name: push-pdf + uses: ad-m/github-push-action@master + with: + directory: gh-pages + branch: gh-pages @@ -33,5 +33,4 @@ vc.tex: .git/logs/HEAD \\gdef\\GITAuthorName{%an}" >> vc.tex clean: - rm -f *.aux $(latexfile).{pdf,out,toc,log,bbl,blg} - + rm -f *.aux $(latexfile).{pdf,out,toc,log,bbl,blg} vc.tex @@ -9,6 +9,16 @@ global perspective. It also complements the opendigitalradio.org wiki. +How to build locally +-------------------- + +The pdf document will always be created automatically by the github repository upon a push. +However, it can be interesting to create the pdf on your host, in order to check the outcome of your changes prior to pushing them to the repository. + +On your debian-based host: +1. Install the packages: `make texlive texlive-fonts-extra texlive-latex-extra texlive-science cm-super` +1. Run the following command: `make clean && make` + Latest Version -------------- diff --git a/appendix.tex b/appendix.tex index 02da04e..e7f6dcf 100644 --- a/appendix.tex +++ b/appendix.tex @@ -9,7 +9,7 @@ The three formats are called \emph{framed}, \emph{streamed} and \emph{raw}. The \emph{framed} format is used for saving a finite ETI stream into a file. Each frame does not contain any padding, and the format can be described as follows: -\begin{lstlisting} +\begin{lstlisting}[language=C] uint32_t nbFrames // for each frame uint16_t frameSize @@ -18,7 +18,7 @@ uint32_t nbFrames When streaming data, in which case the number of frames is not known in advance, the \emph{streamed} format can be used. This format is identical to the first one except for the missing \texttt{nbFrames}. -\begin{lstlisting} +\begin{lstlisting}[language=C] // for each frame uint16_t frameSize uint8_t data[frameSize] @@ -26,7 +26,7 @@ This format is identical to the first one except for the missing \texttt{nbFrame The \emph{raw} format corresponds to ETI(NI), where each frame has a constant size of 6144 Bytes. The padding in this case is necessary. -\begin{lstlisting} +\begin{lstlisting}[language=C] // for each frame uint8_t data[6144] \end{lstlisting} @@ -40,7 +40,7 @@ In order to select the format, the following syntax for the \texttt{-O} option i ODR defined and uses two additional EDI TAGs, whose content is described here. ODR-AudioEnc inserts audio level metadata into the ``ODRa'' TAG. The TAG item is in the following format: -\begin{lstlisting} +\begin{lstlisting}[language=C] TAG Name="ODRa" [4 bytes] Length=4 [4 bytes] Left Audio Level [signed 16-bit integer] @@ -49,7 +49,7 @@ ODR-AudioEnc inserts audio level metadata into the ``ODRa'' TAG. The TAG item is The second EDI TAG ``ODRv'' contains version and uptime information for the EDI source. -\begin{lstlisting} +\begin{lstlisting}[language=C] TAG Name="ODRv" [4 bytes] Length=N+4 [4 bytes] Version [String of N bytes, UTF-8 encoded, not zero terminated] diff --git a/introduction.tex b/introduction.tex index 4b6627c..629d6ff 100644 --- a/introduction.tex +++ b/introduction.tex @@ -182,17 +182,9 @@ transmissions. There are 3 ways to install the tools. \subsection{Debian Binary Packages} -If your host is running a debian-Bullseye-based operating system and its -architecture is one of 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} - curl -fsSL http://debian.opendigitalradio.org/odr.asc | sudo tee /etc/apt/trusted.gpg.d/odr.asc 1>/dev/null - curl -fsSL http://debian.opendigitalradio.org/odr.list | sudo tee /etc/apt/sources.list.d/odr.list 1>/dev/null - apt update - sudo apt install --yes odr-audioenc odr-padenc odr-dabmux odr-dabmod -\end{lstlisting} +Packages will be available on the official debian repository from trixie (debian 13) onward. +If you are running bookworm (debian 12), please add the debian official bookworm-backports repository by +applying the instructions given on the debian wiki pages \footnoteurl{https://wiki.debian.org/Backports}. \paragraph{Remarks} The \texttt{odr-dabmux} and \texttt{odr-dabmod} packages do not include the web-based GUI Mux Manager @@ -215,15 +207,17 @@ Apply the following steps: sudo timedatectl set-timezone your_timezone cd ${HOME} git clone https://github.com/opendigitalradio/dab-scripts.git - bash ${HOME}/dab-scripts/install/mmbtools-get install + 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. +a live broadcasting of 2 dab+ programs. For more installation details, please +refer to the install/README.md file in the github repository. +\clearpage \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 diff --git a/mmbtools.tex b/mmbtools.tex index 6ff8924..a2b845b 100644 --- a/mmbtools.tex +++ b/mmbtools.tex @@ -109,11 +109,10 @@ Open-Source Software-Defined \dabplus Tools} \begin{document} \lstset{ -language=C, % Code langugage -basicstyle=\ttfamily, % Code font, Examples: \footnotesize, \ttfamily +basicstyle=\ttfamily,columns=flexible, % Code font, Examples: \footnotesize, \ttfamily keywordstyle=\color{OliveGreen}, % Keywords font ('*' = uppercase) commentstyle=\color{gray}, % Comments font -numbers=left, % Line nums position +numbers=none, % Line nums position numberstyle=\tiny, % Line-numbers fonts stepnumber=1, % Step between two line-numbers numbersep=5pt, % How far are line-numbers from code @@ -147,7 +146,7 @@ clock_config_t}, \begin{center} \Large - Opendigitalradio\\\href{http://opendigitalradio.org}{http://opendigitalradio.org}\\2014--2022 + Opendigitalradio\\\href{http://opendigitalradio.org}{http://opendigitalradio.org}\\2014--2025 \end{center} \vspace{\fill} \vspace*{\stretch{2}} @@ -52,12 +52,11 @@ general { ... outputs { - ; Accept connections on all interfaces, on port 13000 edi { destinations { tcp { protocol tcp - listenport 13000 + listenport 9201 } } enable_pft false diff --git a/systemenvironments.tex b/systemenvironments.tex index 6a2355f..320d41e 100644 --- a/systemenvironments.tex +++ b/systemenvironments.tex @@ -186,130 +186,6 @@ server, and the ZeroMQ remote control enabled on the ports give in the example configurations. -\subsection{Monitoring using Xymon} -The xymon monitoring tool\footnote{\url{http://xymon.sourceforge.net/}} is used -to monitor the health of many types of systems. It can present the results in -text, tables and/or graphs. It supports the basic health checks directly out of -the box, and can be extended with scripts to perform non-standard health checks. -The default mode of operation is that clients retrieve data and send it to the -xymon server, which interprets the results, displays them and generates alerts -if thresholds are exceeded. An alert can be send in an e-mail, an SMS or a -tweet. - -The Perl script \verb+retodrs.pl+\footnote{The script name stands for -''Retrieve Opendigitalradio Status``}, retrieves the status and -statistics of an Opendigitalradio service and it reports the results to xymon. -The information is retrieved from the management server within ODR-DabMux. The -information presented includes a table with the status of each sub-channel and -the underrun and overrun rates on the sub-channels. If needed an alert can be -generated depending on the subchannel status or a rate exceeding a threshold. - -The script needs to be installed on the same server running ODR-DabMux, as the -management service within it is only accessible from the same computer. This -implies that the xymon client software also needs to be installed on the same -machine. The client is configured to run the script. -The configuration and the scripts can typically be found in subdirectory -\verb+/usr/lib/xymon/client+, although that may depend on your distribution. - -Once the client is set up, it needs to connect to a xymon server, which may or -may not be on the same machine. -The server is configured to limit the altering to specific sub-channels, to -store the statistical data and to generate graphs. -The configuration and the scripts on a xymon server are usually stored in the -subdirectory \verb+/usr/lib/xymon/server+. - - -\subsubsection{Installation of the Xymon Client} - -The perl script has additional requirements: -\texttt{App::cpanminus}, \texttt{ZMQ::LibZMQ3}, and \texttt{JSON::PP}. They can -be installed through your distribution packages or using CPAN. - -Once the script has been copied to \verb+/usr/lib/xymon/client/ext+, the -configuration of the launcher within the xymon client needs to be extended. -Create a new file named \verb+odrmux.cfg+ in -\verb+/usr/lib/xymon/client/etc/clientlaunch.d+ containing the following lines: - -\begin{verbatim} -# -# Test odrmux checks the state and the statistics -# of the ODR-DabMux service. -# -[odrmux] - ENVFILE $XYMONCLIENTHOME/etc/xymonclient.cfg - CMD $XYMONCLIENTHOME/ext/retodrs.pl - LOGFILE $XYMONCLIENTLOGS/retodrs.plog - INTERVAL 5m -\end{verbatim} - -After a restart of the xymon client, the script \verb+retodrs.pl+ will -be invoked once every 5 minutes. - - -\subsubsection{Server Configuration} - -By default all subchannels will be monitored, and will raise alerts if the -status or the statistics are in outside of a valid operational range. The -alerting can be limited to a subset of the sub-channels by adding a tag to the -hosts-entry in the configuration file \verb+/usr/lib/xymon/server/etc/hosts.cfg+. -The additional tag is: - -\begin{verbatim} - ODR:select(<SubChannelName0>;<SubChannelName1>;...) -\end{verbatim} - -The sub-channels not named will still be shown, but no alerts will be generated -for those sub-channels. This is visible as the green/yellow/red icons are -missing for those sub-channels. - -Six statistic values are gathered by the script, namely -\texttt{BufferMin}, \texttt{BufferMax}, \texttt{PeakLeft}, \texttt{PeakRight}, -\texttt{UnderRun} and \texttt{OverRun}. It is found that only the latter two -seem to contain sensible values all the time, so those values are the only -ones shown in a graph. Note that those values retrieved by the script are -ever-increasing counters, showing the total number of over-runs or under-runs. -In the graph, the average number of over-runs or under-runs per second, averaged -over a period of 5 minutes, is shown. - -The first step is to have the collected statistics to be moved into a database, -a so-called \textit{Round Robin Database}. This is accomplished by adding a file -named \verb+odr.cfg+ in \verb+/usr/lib/xymon/server/etc/xymonserver.d+ -containing the following lines: - -\begin{verbatim} -TEST2RRD+=",odr_mux=devmon" -GRAPHS+=",odr_mux::1" -\end{verbatim} - -The next step is to define the layout of the graph. -Create a file named \verb+graphs.odr.cfg+ in -\verb+/usr/lib/xymon/server/etc/graphs.d+ containing the following lines: - -\begin{verbatim} -# -# Graphs to show the statistics collected from an -# Opendigitalradio DabMux server. -# -[odr_mux] - FNPATTERN ^odr_mux\.(.+)\.rrd$ - TITLE , Frame loss rate - YAXIS Rate [/s] - -l 0 - DEF:ur@RRDIDX@=@RRDFN@:Underrun:AVERAGE - DEF:or@RRDIDX@=@RRDFN@:Overrun:AVERAGE - LINE1:ur@RRDIDX@#FF0000:@RRDPARAM@ underrun - GPRINT:ur@RRDIDX@:MIN:Min \: %5.1lf %s - GPRINT:ur@RRDIDX@:MAX:Max \: %5.1lf %s - GPRINT:ur@RRDIDX@:AVERAGE:Avg \: %5.1lf %s - GPRINT:ur@RRDIDX@:LAST:Cur \: %5.1lf %s\n - LINE1:or@RRDIDX@#00FF00:@RRDPARAM@ overrun - GPRINT:or@RRDIDX@:MIN: Min \: %5.1lf %s - GPRINT:or@RRDIDX@:MAX:Max \: %5.1lf %s - GPRINT:or@RRDIDX@:AVERAGE:Avg \: %5.1lf %s - GPRINT:or@RRDIDX@:LAST:Cur \: %5.1lf %s\n -\end{verbatim} - - \subsection{Real-time Scheduling} As a general principle, it is prudent not to run tools (that do not need superuser privileges) as the \texttt{root} user. The same principle also applies to the @@ -344,14 +220,14 @@ protection has to be put in place to make sure the audio data cannot be altered by third parties. Usually, some form of VPN is set up for this case. { \footnotesize -\begin{verbatim} +\begin{lstlisting} #USRP1 SUBSYSTEMS=="usb", ATTRS{idVendor}=="fffe", ATTRS{idProduct}=="0002", MODE:="0666" #B100 SUBSYSTEMS=="usb", ATTRS{idVendor}=="2500", ATTRS{idProduct}=="0002", MODE:="0666" #B200 SUBSYSTEMS=="usb", ATTRS{idVendor}=="2500", ATTRS{idProduct}=="0020", MODE:="0666" -\end{verbatim} +\end{lstlisting} } % vim: spl=en spell tw=80 et |