Adding info on Audio configuration

1 files changed, 61 insertions, 0 deletions

diff --git a/getting-started/troubleshooting.md b/getting-started/troubleshooting.md
index d1d47ba..90b4c07 100644
--- a/getting-started/troubleshooting.md
+++ b/getting-started/troubleshooting.md
@@ -103,3 +103,64 @@ The current supported format is OGG. Please convert your files to ogg to play wi
 In case you want to store music in another place, modify the `/usr/lib/systemd/user/lightmediascanner.service` file and change the `--directory` parameter to the path of that folder.
 
 If you don’t want to touch the ligthmediascanner service, you can also add a folder named "Music" under `/home/root` and put your music files there.
+
+## Configuring the Audio hardware
+AGL uses alsa as Audio configuration master. If the correct HW is not setup, the Audio system will fail to start what will also fails the demo Home Screen launch.
+You need to configure Audio in 2 places
+ - alsa
+ - 4A HAL
+ 
+ ### alsa
+ The file /etc/asound.conf (at the beginning) tells which hardware will be used.
+ For example on an Intel Minnow or UP board your need to enter the following configuration.
+ ```
+ pcm.Speakers {
+    type dmix
+    slave {pcm "hw:PCH,3"}
+    ipc_key 1001          # ipc_key should be unique to each dmix
+}
+ ```
+The correct value (here hw:PCH,3) can be obtained with the command:
+```
+aplay -l
+**** List of PLAYBACK Hardware Devices ****
+card 0: PCH [HDA Intel PCH], device 3: HDMI 0 [HDMI 0]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+card 0: PCH [HDA Intel PCH], device 7: HDMI 1 [HDMI 1]
+  Subdevices: 1/1
+  Subdevice #0: subdevice #0
+```
+Using hw:PCH rather than hw:0 will avoid you many trouble.<br>
+NOTE that the device number is not always 0. If you give no device number, alsa will assume device 0 (and the not the first available device), what can fail your configuration.<br>
+As the default is hw:0 (card 0 device 0), it will always fail on a Minnow or UP board.
+
+For info HW device for common configuration are:
+- for USB Audio -> hw:AUDIO,0
+- for Intel Analog output -> hw:PCH,0 (not available on Minnow, Joule, Up boards, ...)
+- for Intel via -> HDMI hw:PCH,3
+- for MOST Unicens -> hw:ep016ch,0
+
+### 4A HAL configuration
+AGL 4A needs to know which HAL shall be used. This is configured in the file:
+```
+/usr/agl-service-audio-4a/ahl-agl-service-audio-4a-config.json
+```
+At the beginning of that file you will find the slected HAL (note the there is no correct default value).
+```
+{
+    "version": "0.2.0",
+    "policy_module": "AudioPolicy_v1",
+    "description": "High-level binding configuration file",
+    "note": "Devices and routings are always listed in order of priority (for device selection rules)",
+    "hal_list": ["intel-minnow"],
+    "audio_roles": [
+```
+Here you see "intel-minnow" but common values are:
+- Intel laptop -> intel-pc
+- Intel via HDMI -> intel-minnow
+- Renesas -> Rcar-M3
+- USB Audio Speaker -> usb-audio
+- MOSTS Unicens -> hal-most-unicens
+
+More HAL can be found on Gerrit (search projects named as 4a-hal*)