Add new Raspberry Pi documentation for ALSA settings

README.md

@@ -147,6 +147,138 @@ A default config file looks like this, annotated:
 }
 ```
 
+## ALSA Driver HOW-TO on Raspberry Pi
+
+The default config above is generated assuming a PulseAudio setup, but the
+current Raspbian images for Raspberry Pi prefer ALSA by default. Here are some
+steps to identify your sound card and edit sonar.json accordingly.
+
+### List ALSA Devices
+
+The `alsa-utils` package provides a handful of commands you might already
+have pre-installed.
+
+In my use case, I had a USB audio device attached to my Raspberry Pi that
+shows up in ALSA as a separate hardware device:
+
+```bash
+$ aplay -l
+**** List of PLAYBACK Hardware Devices ****
+card 0: ALSA [bcm2835 ALSA], device 0: bcm2835 ALSA [bcm2835 ALSA]
+  Subdevices: 7/7
+  Subdevice #0: subdevice #0
+  Subdevice #1: subdevice #1
+  Subdevice #2: subdevice #2
+  Subdevice #3: subdevice #3
+  Subdevice #4: subdevice #4
+  Subdevice #5: subdevice #5
+  Subdevice #6: subdevice #6
+card 0: ALSA [bcm2835 ALSA], device 1: bcm2835 ALSA [bcm2835 IEC958/HDMI]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+card 1: Device [USB2.0 Device], device 0: USB Audio [USB Audio]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+```
+
+The `aplay -l` command lists your ALSA devices.
+
+Another command to know is `alsamixer` which presents a graphical CLI
+program to adjust the volume and show sound card details.
+
+### Volume Control with ALSA
+
+The `amixer` command can adjust volume settings. For simple setups you
+can use commands like:
+
+```bash
+# Increase or decrease volume by 10% at a time, respectively
+$ amixer set Master 10%+
+$ amixer set Master 10%-
+
+# Toggle mute on or off
+$ amixer set Master toggle
+
+# Get the current volume setting
+$ awk -F"[][]" '/dB/ { print $2 }' <(amixer sget Master)
+100%
+```
+
+In my case I needed to also specify the sound card device
+(`-c 1`) because I'm not using the default, and my output channel is named
+PCM instead of Master on that device:
+
+```bash
+$ amixer -c 1 set PCM 10%+
+$ amixer -c 1 set PCM 10%-
+$ amixer -c 1 set PCM toggle
+$ awk -F"[][]" '/dB/ { print $2 }' <(amixer -c 1 sget PCM)
+```
+
+### MPlayer with ALSA Devices
+
+I also needed to sort out the `mplayer` command to tell it to use my
+ALSA device:
+
+```bash
+$ mplayer -ao alsa:device=hw=1.0 <filename>
+```
+
+### Example ALSA Config File
+
+My sonar.json config now looks like:
+
+```json
+{
+  "cookieName": "session",
+  "mediaPath": "/home/kirsle/Music/watts",
+  "mediaCommand": [
+    "mplayer",
+    "-ao",
+    "alsa:device=hw=1.0",
+    "%s"
+  ],
+  "volUpCommand": [
+    "amixer",
+    "-c",
+    "1",
+    "set",
+    "PCM",
+    "10%+"
+  ],
+  "volDnCommand": [
+    "amixer",
+    "-c",
+    "1",
+    "set",
+    "PCM",
+    "10%-"
+  ],
+  "volMuteCommand": [
+    "amixer",
+    "-c",
+    "1",
+    "set",
+    "PCM",
+    "toggle"
+  ],
+  "volStatusCommand": [
+    "bash",
+    "-c",
+    "awk -F\"[][]\" '/dB/ { print $2 }' \u003c(amixer -c 1 sget PCM) egrep -o '([0-9]+)%' | head -1"
+  ],
+  "hour": 6,
+  "minute": 30,
+  "days": [
+    "1",
+    "2",
+    "3",
+    "4",
+    "5"
+  ]
+}
+```
+
 ## Cross Compile for Raspberry Pi
 
 Use the `make pi` command to build a distribution for Raspberry Pi.