Updated documentation

Updated documentation up to date and using the gitbook format.

Change-Id: Ie5d6a3bb489b9a9a95e21f5edd05bdd77bff5816
Signed-off-by: Loïc Collignon <loic.collignon@iot.bzh>

7 files changed, 294 insertions, 0 deletions

diff --git a/docs/high-level-api/TipsAndTricks/4aTools.md b/docs/high-level-api/TipsAndTricks/4aTools.md
new file mode 100644
index 0000000..f1bff4b
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/4aTools.md
@@ -0,0 +1,198 @@
+# 4a-tools
+
+4a-tools is a set of simple scripts that can be used to test and troubleshoot
+4a framework.
+
+## 4a-status
+
+4a-status gives a diagnostic whether 4a-framework is supposed to be working or
+not.
+
+```bash
+user@machine$ 4a-status
+---- Audio cards detected ----
+card 0: Loopback
+card 1: Intel
+
+---- snd-aloop driver availability ----
+SUCCESS: Built into the kernel
+
+---- 4a service status ----
+SUCCESS: Service is currently running!
+```
+
+If any error is shown then there is no way that 4a-framework can work.
+Not running services do trigger only a warning because you may have started the
+service's binding manually and the script cannot detect this.
+If you don't, this must be considered as an error, because 4a-framework
+obviously cannot work when bindings are not running.
+
+```bash
+---- Audio cards detected ----
+card 0: Loopback
+card 1: Intel
+
+---- snd-aloop driver availability ----
+SUCCESS: Built into the kernel
+
+---- 4a service status ----
+WARNING: Service is not currently running!
+It can be started using the following command:
+systemctl restart *agl-service-audio-4a*.service
+```
+
+## 4a-api
+
+This script lets you call 4a's APIs to test bindings and get some infos.
+
+### Ping API
+
+Pinging an API let you know that the binding providing this API is running and
+ready.
+
+```bash
+user@machine$ 4a-api api smixer ping
+Detected systemd unit file!
+Port detected: 1025
+ON-REPLY 1:smixer/ping: OK
+{
+    "response":3,
+    "jtype":"afb-reply",
+    "request":{
+        "status":"success"
+    }
+}
+```
+
+### List HALs
+
+You can list availables HALs using the following command:
+
+```bash
+user@machine$ 4a-api hals
+Detected systemd unit file!
+Port detected: 1025
+ON-REPLY 1:4a-hal-manager/loaded: OK
+{
+    "response":[
+        "4a-hal-intel-qemu"
+    ],
+    "jtype":"afb-reply",
+    "request":{
+        "status":"success",
+        "info":"Requested data"
+    }
+}
+```
+
+If the returned list is empty, this means that no HAL is loaded and ready. In
+such a case you won't be able to use 4a-framework because this means that there
+is no device to play audio on.
+
+To get more information about a HAL, you can call its **info** verb:
+
+```bash
+user@machine$ 4a-api api 4a-hal-intel-qemu info
+Detected systemd unit file!
+Port detected: 1025
+ON-REPLY 1:4a-hal-intel-qemu/info: OK
+{
+    "response":{
+        "streams":[
+            {
+                "name":"multimedia",
+                "cardId":"hw:0,0,2"
+            },
+            {
+                "name":"navigation",
+                "cardId":"hw:0,0,3"
+            },
+            {
+                "name":"emergency",
+                "cardId":"hw:0,0,4"
+            }
+        ],
+        "playbacks":[
+            {
+                "name":"playback",
+                "mixer-name":"INTEL-QEMU:playback"
+            }
+        ],
+        "captures":[
+            {
+                "name":"capture",
+                "mixer-name":"INTEL-QEMU:capture"
+            }
+        ]
+    },
+    "jtype":"afb-reply",
+    "request":{
+        "status":"success",
+        "info":"Requested data"
+    }
+}
+```
+
+This allows you to get which device is bound to which stream.
+Please note these are stream names, not roles names.
+In addition, multiples HALs can provide the same stream.
+In the current implementation, it results in a race condition: 4a-framework
+will be using the first HAL providing the stream.
+
+### List roles
+
+This lets you get the list of available audio roles.
+Only roles with a bound device are listed here, because roles without a device
+are pretty much unusable.
+
+```bash
+user@machine$ 4a-api roles
+Detected systemd unit file!
+Port detected: 1025
+ON-REPLY 1:ahl-4a/get_roles: OK
+{
+    "response":[
+        "radio",
+        "multimedia",
+        "emergency",
+        "navigation"
+    ],
+    "jtype":"afb-reply",
+    "request": {
+        "status":"success"
+    }
+}
+```
+
+## 4a-play
+
+4a-play lets you play some audio file on a specified device, with an optional
+audio role.
+
+```bash
+4a-play <file> [<device> [<role>]]
+```
+
+Where *file* is the path to the file to play, *device* is the device to play on
+and and *role* is the 4a audio role to open (multimedia for example).
+
+The specified role should be the one that is bound to the specified device,
+however the script is not able to detect it so there is no control about this.
+The role is opened before playing the audio file, and closed after playing is
+over.
+
+So for example:
+
+```bash
+4a-play Happy_MBB_75.ogg hw:2,0,0 multimedia
+```
+
+>**NOTE**: For now you have to specify the device and the role. Future versions
+>of this script may detect devices and roles relations so that you will be able
+>to omit either role or device.
+>
+>The device that usually matches "multimedia" is "hw:0,0,2" (for more details
+>please read the [HALs](HALs.md) section).
+
+>**NOTE**: Some media files (WAV, MP3 and OGG) are provided with 4a-tools for
+>testing purpose and can be used as reference assets. 
diff --git a/docs/high-level-api/TipsAndTricks/AdjustVolumes.md b/docs/high-level-api/TipsAndTricks/AdjustVolumes.md
new file mode 100644
index 0000000..2d8fca2
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/AdjustVolumes.md
@@ -0,0 +1,9 @@
+# Adjust volumes
+
+On the main menu, hit the "Mixer" icon.
+
+![Main Menu Interface](images/MixerBaseMenu.png)
+
+Then drag the cursor to change the sound volume of the corresponding role.
+
+![Mixer Interface](images/changeSound.png)
diff --git a/docs/high-level-api/TipsAndTricks/Devices.md b/docs/high-level-api/TipsAndTricks/Devices.md
new file mode 100644
index 0000000..9e1c0cd
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/Devices.md
@@ -0,0 +1,32 @@
+# List available devices
+
+To list the available devices, as well as their subdevices, you can use the
+**aplay** command.
+
+```bash
+user@machine$ aplay -l
+**** List of PLAYBACK Hardware Devices ****
+card 0: Loopback [Loopback], device 0: Loopback PCM [Loopback PCM]
+  Subdevices: 8/8
+  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
+  Subdevice #7: subdevice #7
+card 0: Loopback [Loopback], device 1: Loopback PCM [Loopback PCM]
+  Subdevices: 8/8
+  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
+  Subdevice #7: subdevice #7
+card 1: Intel [HDA Intel], device 0: Generic Analog [Generic Analog]
+  Subdevices: 0/1
+  Subdevice #0: subdevice #0
+```
diff --git a/docs/high-level-api/TipsAndTricks/HALs.md b/docs/high-level-api/TipsAndTricks/HALs.md
new file mode 100644
index 0000000..4c2ead6
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/HALs.md
@@ -0,0 +1,46 @@
+# HALs
+
+HALs are known as json files in 4a, they are stored in
+**/usr/libexec/agl/4a-hal**.
+
+Enabled HALs can be found in the **etc** subfolder, and disabled HALs in
+**etc.available**.
+
+You can enable and disable HALs just by moving the corresponding json file from
+one folder to the other.
+
+Example:
+
+```bash
+user@machine$ ls etc etc.available/
+etc:
+hal-4a-csl-cm106-8ch-usb.json
+
+etc.available/:
+hal-4a-2ch-generic-usb.json  hal-4a-intel.json
+hal-4a-ensoniq.json          hal-4a-jabra.json
+hal-4a-intel-minnow.json     hal-4a-rcar-m3.json
+hal-4a-intel-qemu.json       hal-4a-rcar-m3kf.json
+
+user@machine$ mv etc/hal-4a-csl-cm106-8ch-usb.json  etc.available
+user@machine$ mv etc.available/hal-4a-2ch-generic-usb.json etc
+
+user@machine$ ls etc etc.available/
+etc:
+hal-4a-2ch-generic-usb.json
+
+etc.available/:
+hal-4a-csl-cm106-8ch-usb.json  hal-4a-intel.json
+hal-4a-ensoniq.json            hal-4a-jabra.json
+hal-4a-intel-minnow.json       hal-4a-rcar-m3.json
+hal-4a-intel-qemu.json         hal-4a-rcar-m3kf.json
+
+user@machine$ sync
+user@machine$ reboot
+```
+
+>NOTE: Even if multiple HAL are allowed, you have to make sure that they don't
+>provide the same streams, because it will cause a race condition in the high
+>level API. The first HAL providing the stream is used, any other are ignored.
+>
+>Also, the hardware used by enabled HALs should be available.
diff --git a/docs/high-level-api/TipsAndTricks/SUMMARY.md b/docs/high-level-api/TipsAndTricks/SUMMARY.md
new file mode 100644
index 0000000..6ae5ff6
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/SUMMARY.md
@@ -0,0 +1,9 @@
+# Tips & Tricks
+
+In this section you'll find useful tips and tricks to help you in case of
+trouble.
+
+* [Adjust Volumes](AdjustVolumes.md)
+* [4a-tools](4aTools.md)
+* [Devices](Devices.md)
+* [HALs](HALs.md)
\ No newline at end of file
diff --git a/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png
new file mode 100644
index 0000000..e2e6fe6
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.png
diff --git a/docs/high-level-api/TipsAndTricks/images/changeSound.png b/docs/high-level-api/TipsAndTricks/images/changeSound.png
new file mode 100644
index 0000000..504f8ce
--- /dev/null
+++ b/docs/high-level-api/TipsAndTricks/images/changeSound.png