Additions to audio HAT set up and configuration

Give specific mention to the presence of pwr indication when installing
a HAT. Provide some guidance on the usage of .soundrc and offer advice
on messages that can occur upon invocation of alsactl to load state
files. Removal of set -e will ensure alsactl won't cause the example
rc.local to exit prematurely with non-zero.

Author: learmj

documentation/asciidoc/accessories/audio/configuration.adoc

@@ -37,7 +37,7 @@ All the necessary mounting hardware including spacers, screws and connectors is
 
 === Hardware versions
 
-There are multiple versions of the audio cards, and the version that you possess determines the actions required to configure it. Older IQaudIO-marked boards (black PCB) are electrically equivalent to the Raspberry Pi-branded boards (green PCB) but have different EEPROM contents. The following command can be used to confirm which version you have:
+There are multiple versions of the audio cards, and the version that you possess determines the actions required to configure it. Older IQaudIO-marked boards (black PCB) are electrically equivalent to the Raspberry Pi-branded boards (green PCB) but have different EEPROM contents. After attaching the HAT and applying power, if your audio card has an LED to indicate power make sure it is illuminated (for example, the PWR LED on the Codec Zero must be on). After establishing the card has power, the following command can be used to confirm which version you have:
 
 [source,console]
 ----
@@ -98,6 +98,8 @@ The following command will set your device to use the on-board MEMS microphone a
 $ sudo alsactl restore -f /home/<username>/Pi-Codec/Codec_Zero_OnboardMIC_record_and_SPK_playback.state
 ----
 
+It's possible that this command may result in erroneous messages such as "failed to import hw" or "No state is present for card". In most cases, these are just harmless warnings. Other errors such as "Remote I/O error" need to be given more attention because they are usually indicative of a hardware problem. In Linux I2C, a "Remote I/O error" (```REMOTEIO```) means the kernel can't communicate with an I2C device.
+
 In order for your project to operate with your required settings when it is powered on, edit the `/etc/rc.local` file. The contents of this file are run at the end of every boot process, so it is ideal for this purpose. Edit the file:
 
 [source,console]
@@ -109,7 +111,7 @@ Add the chosen script command above the exit 0 line and then *Ctrl X*, *Y* and *
 
 [source,bash]
 ----
-#!/bin/sh -e
+#!/bin/sh
 #
 # rc.local
 #
@@ -152,6 +154,8 @@ pcm.!default {
 
 Press `Ctrl+X`, then the `Y` key, then *Enter* to save. Reboot once more to complete the configuration:
 
+The desktop environment in modern Linux distributions such as Raspberry Pi OS will typically use PulseAudio or PipeWire for audio control. These frameworks are capable of mixing and switching audio from multiple sources and they provide a high level API for audio applications to use. Out of the box, a lot of audio apps use these frameworks by default which removes the need for them to interact directly with ALSA. Creating ```~/.asoundrc``` is only recommended if audio applications are communicating directly with ALSA or running in an environment where PulseAudio or PipeWire are not present. Usage of this file is not recommended if running the Raspberry Pi OS desktop environment because it can interfere with the UI's view of the underlying audio resources. The UI may take action to automatically clean up and remove this file if it exists so careful use of it is recommended, especially if it's intended to set any ALSA defaults.
+
 [source,console]
 ----
 $ sudo reboot