summaryrefslogtreecommitdiffstats
path: root/docs/high-level-api/TipsAndTricks
diff options
context:
space:
mode:
authorLoïc Collignon <loic.collignon@iot.bzh>2018-09-10 10:36:46 +0200
committerLoïc Collignon <loic.collignon@iot.bzh>2018-10-01 15:46:43 +0200
commit75e26b091f6aae38c9edb069c173bcb04ae3ffd1 (patch)
treeac31716b5bdd2ad0236559d141cdcca8f9696332 /docs/high-level-api/TipsAndTricks
parentfe834167fd205e9a38c986bfb9dfde4265e9cc45 (diff)
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>
Diffstat (limited to 'docs/high-level-api/TipsAndTricks')
-rw-r--r--docs/high-level-api/TipsAndTricks/4aTools.md198
-rw-r--r--docs/high-level-api/TipsAndTricks/AdjustVolumes.md9
-rw-r--r--docs/high-level-api/TipsAndTricks/Devices.md32
-rw-r--r--docs/high-level-api/TipsAndTricks/HALs.md46
-rw-r--r--docs/high-level-api/TipsAndTricks/SUMMARY.md9
-rw-r--r--docs/high-level-api/TipsAndTricks/images/MixerBaseMenu.pngbin0 -> 170421 bytes
-rw-r--r--docs/high-level-api/TipsAndTricks/images/changeSound.pngbin0 -> 123509 bytes
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
Binary files differ
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
Binary files differ