From 27c2557c21cae2af48b9ba298149c6fe9cceb96f Mon Sep 17 00:00:00 2001
From: xengineering <me@xengineering.eu>
Date: Sat, 6 Jan 2024 10:50:09 +0100
Subject: doc: Add Alpine Linux config guide

Configuring the Alpine Linux operating system correctly for soundbox is
not trivial. Since it is very important it has to be documented in
detail.
---
 doc/documentation.tex | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

(limited to 'doc/documentation.tex')

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 53452ee..ddade37 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -54,7 +54,7 @@ devices..
 
 %\section{Device setup}
 
-\section{Playing audio}
+\section{Playing audio} \label{playing-audio}
 
 For a simple audio streaming test the following commands from the FFmpeg
 streaming
@@ -179,6 +179,74 @@ lbu commit -d
 
 With this setup the Alpine Linux installation is completed.
 
+\section{Configure Alpine Linux for soundbox}
+
+soundbox requires packages from the Alpine Linux community package repository.
+Since this is not enabled by default it has to be done manually. This can be
+done by editing the \texttt{/etc/apk/repositories} file with an editor like
+\texttt{vi}. The hash sign \texttt{\#} in front of the URL to the community
+repository has to be removed. Instead also \texttt{sed} can remove this sign on
+a fresh installation quite easily since the community repository is the only
+one with such a sign in front of it.
+
+\begin{verbatim}
+sed -i 's/^#//g' /etc/apk/repositories
+\end{verbatim}
+
+With an enabled community repository all required packages for soundbox can be
+installed. The list with required packages can be written to the
+\texttt{/etc/apk/world} file with \texttt{echo}. Running \texttt{apk add} after
+it will install all of these packages including their dependencies and removes
+everything else. This makes sure that always exactly the same set of packages
+is used for a soundbox device.
+
+\begin{verbatim}
+echo 'alpine-base
+alsa-utils
+alsaconf
+busybox-mdev-openrc
+chrony
+ffplay
+iw
+openssh
+openssl
+wpa_supplicant' > /etc/apk/world
+
+apk add
+\end{verbatim}
+
+The only user on a soundbox device is \texttt{root}. Even that super user has
+to be added to the \texttt{audio} group to be able to play sound via ALSA. This
+can be achieved with \texttt{addgroup}.
+
+\begin{verbatim}
+addgroup root audio
+\end{verbatim}
+
+soundbox uses the HiFiBerry shield to output high-quality audio. This shield
+needs to be enabled as an audio output by specifying a Devicetree overlay in
+the Raspberry Pi configuration file with \texttt{echo}. Since this file is
+stored on the SD card only which is mounted as read-only it has to be remounted
+with the read-write option first.
+
+\begin{verbatim}
+mount -o remount,rw /media/mmcblk0p1
+echo 'dtoverlay=hifiberry-dac' >> /media/mmcblk0p1/config.txt
+\end{verbatim}
+
+Since a diskless Alpine Linux installation is preferred for soundbox the
+changes have to be made persistent with \texttt{lbu}. Rebooting after it makes
+sure the SD card is again mounted in read-only mode and all Kernel-affecting
+changes can be applied.
+
+\begin{verbatim}
+lbu commit -d
+reboot
+\end{verbatim}
+
+After this reboot the soundbox device should be able to play audio like
+described in section~\ref{playing-audio}.
+
 %\section{Final assembly}
 
 %\chapter{Device internals}
-- 
cgit v1.2.3-70-g09d2

