diff options
| -rw-r--r-- | README.md | 159 |
1 files changed, 76 insertions, 83 deletions
@@ -7,7 +7,6 @@ * Author: Jonathan Aillet jonathan.aillet@iot.bzh * Date : June-2018 - ## Cloning repositories for RC1 version ### Cloning 4a-hal-generic rc1 version with its submodules @@ -18,19 +17,17 @@ git clone --recurse-submodules -b rc1 https://github.com/iotbzh/4a-hal-generic.g git clone --recurse-submodules -b hal-rc1-sandbox https://github.com/iotbzh/4a-softmixer.git - ## Quick introduction to how hal are handled with 4a-hal-generic * At startup of the 4a-hal binding, a new api called '4a-hal-manger' will be created. - This api is meant to provide verbs to list the loaded hal in your system and to now there current status. + This api is meant to provide verbs to list the loaded hals in your system and to know there current status. * The '4a-hal-manager' will also create a new hal for each audio configuration files found. - These configration files are used by the controller and are meant to be used with a mixer. + These configuration files are used by the controller and are meant to be used with a mixer. * External hal (e.g. loaded in another binding) can be loaded/unloaded into '4a-hal-manger' by reaching it - with this hal. It must provides information such as 'api' and 'uid' at loading. It must also provides - a subscription to an event that the '4a-hal-manager' will use to known this hal status. + with this hal. It must provide information such as 'api' and 'uid' at loading. It must also provide + a subscription to an event that the '4a-hal-manager' will use to know this hal status. WARNING: not fully implemented yet. - ## Preparation ### Install Alsa Loopback @@ -38,85 +35,82 @@ git clone --recurse-submodules -b hal-rc1-sandbox https://github.com/iotbzh/4a-s You must have snd-aloop enabled as a module in the running kernel. Check that this way on the target: -``` - zcat /proc/config.gz | grep CONFIG_SND_ALOOP - CONFIG_SND_ALOOP=m +```bash +zcat /proc/config.gz | grep CONFIG_SND_ALOOP +CONFIG_SND_ALOOP=m ``` -If it not the case, run menuconfig and enable it under: +If it is not the case, run menuconfig and enable it under: > Device Drivers > Sound card support > Advanced Linux Sound Architecture > Generic sound device - -``` - sudo modprobe snd-aloop +```bash +sudo modprobe snd-aloop ``` -### Create a new hal json configuration correponding to your audio hardware configuration +### Create a new hal json configuration corresponding to your audio hardware configuration #### Information about audio json configuration files -* All audio hardware configuration files are a json description of you audio device. +* All audio hardware configuration files are a json description of your audio devices. * They all must be in ./4a-hal-references-boards-cfg/ and must begin with 'hal-4a'. * You can found some examples of these configurations in this directory. * Each configuration file found at startup will create a new hal with its own api. -* At 'init-mixer' command of your hal, your +* At 'init-mixer' hal command, your mixer configuration will be sent. -#### What you need to set in this configuration file to make you audio work +#### What you need to set in this configuration file to make your audio work -* In 'metadata' section: - * The 'uid' field must be the path to your alsa audio device. - * The 'api' field should be changed to the desired application framework api of you hal -* For 'onload', 'controls', and 'events' sections, please look at the controller documentation +* In `metadata` section: + * The `uid` field must be the path to your alsa audio device. + * The `api` field should be changed to the desired application framework api of your hal +* For `onload`, `controls`, and `events` sections, please look at the controller documentation (In ./app-controller/README.md) -* In 'halcontrol' section: +* In `halcontrol` section: + * WARNING: use of this section is not yet implemented * This section is where you put controls which are alsa control calls * If a control is not available, it will be registered in alsa using '4a-alsa-core' - * Thsese controls will be available as verb for your hal api using 'card/' prefix - * WARNING: use of this section is not yet implemented -* In 'halmixer' section (what it is passed to the mixer):. - * The 'uid' field will be the name of the mixer correponding to your hal - * The 'mixerapi' field should contain the name of the api to call for reaching the mixer + * These controls will be available as verb for your hal api using 'card/' prefix +* In `halmixer` section (what it is passed to the mixer): + * The `uid` field will be the name of the mixer corresponding to your hal + * The `mixerapi` field should contain the name of the api to call for reaching the mixer (not need to be changed if you use '4a-softmixer'). - * The 'backend' section will contain your audio information (such as the path to you alsa audio device - and the configration of you device). - * In 'frontend' section: - * In 'ramps' section: will be defined the ramp that you can use in your mixer (ramps in example files can be used). - * In 'zones' section: (zones in example files can be used) - * You can defined the zones that you want for your mixer. - * You must defined which sink will be used in these zones. - * These zones will be used to defined streams. - * In 'streams' section: (streams in example files can be used) - * You can defined the streams that you want for your mixer. + * The `backend` section will contain your audio information (such as the path to you alsa audio device + and the configuration of your device). + * In `frontend` section: + * In `ramps` section: will be defined the ramp that you can use in your mixer (ramps in example files can be used). + * In `zones` section: (zones in example files can be used) + * You can define the zones that you want for your mixer. + * You must define which sink will be used in these zones. + * These zones will be used to define streams. + * In `streams` section: (streams in example files can be used) + * You can define the streams that you want for your mixer. * It must contain: - * A 'uid' field (which will be used to reach the stream). - * The 'zone' field must correspond to the wanted zone of the stream. - * The 'ramp' field must correspond to the wanted ramp of the stream. + * A `uid` field (which will be used to reach the stream). + * The `zone` field must correspond to the wanted zone of the stream. + * The `ramp` field must correspond to the wanted ramp of the stream. * Other fields are optionals - ## Compile (for each repositories) +```bash +mkdir build +cd build +cmake .. +make ``` - mkdir build - cd build - cmake .. - make -``` - ## Using '4a-hal' binder ### Run your binder from shell -``` -afb-daemon --name=afb-4a --workdir=/home/jon/work/agl-audio/4a-softmixer/build --binding=/home/jon/work/agl-audio/4a-softmixer/build/package/lib/softmixer-binding.so --binding=/home/jon/work/agl-audio/4a-hal-generic/build/4a-hal/4a-hal.so --roothttp=/home/jon/work/agl-audio/4a-softmixer/build/package/htdocs --no-ldpaths --port=1234 --token= -vvv +```bash +afb-daemon --name=afb-4a --workdir=$PATH_TO_4a-softmixer/build --binding=$$PATH_TO_4a-softmixer/build/package/lib/softmixer-binding.so --binding=$PATH_TO_4a-hal-generic/build/4a-hal/4a-hal.so --roothttp=$PATH_TO_4a-softmixer/build/package/htdocs --no-ldpaths --port=1234 --token= -vvv ``` ### Connect your binder Connect to your 4a binder using afb-client-demo -``` +```bash afb-client-demo ws://localhost:1234/api?token= ``` @@ -126,72 +120,72 @@ In the connected client, try to list the loaded hal: ```4a-hal-manager loaded``` -And now with more informations: +And now with more information: ```4a-hal-manager loaded { "verbose" : 1 }``` ### Play with an 'internal' hal (described in a json configuration file) -#### Initalize an internal hal +#### Initialize an internal hal Use an api name obtain in the previous command to initialize mixer of the wanted hal: ```4a-hal-*halapiname* init-mixer``` -#### Get streams informations +#### Get streams information -Now, you can obtain streams information of your initalized internal hal: +Now, you can obtain streams information of your initialized internal hal: ```4a-hal-*halapiname* list``` -All the streams listed are available as a verb of the hal api using 'name' field. -You can also get the corresponding card id of the stream in 'cardId' field. -The card id of a stream is 'hw:X,X,X' format and can be used to play music. +All the streams listed are available as a verb of the hal api using `name` field. +You can also get the corresponding card id of the stream in `cardId` field. +The card id format of a stream is `hw:X,X,X` and can be used to play music. #### Play some music into a stream -WARNING: Current version does not handle audio rate conversion, using gstreamer or equivalent to match with audio hardware params is mandatory. +WARNING: Current version does not handle audio rate conversion, using gstreamer +or equivalent with audio hardware params is mandatory. -Use the previously obtain card if to play audio in the selected stream: +Use the previously obtain card id to play audio in the selected stream: -```gst123 --audio-output alsa=hw:X,X,X your_audio_file.mp3``` +`gst123 --audio-output alsa=hw:X,X,X your_audio_file.mp3` #### During playing, try the stream commands to change/ramp volume -Now you can use your hal api to send command to mixer. This way, you can change/ramp volume : - -``` 4a-hal-*halapiname* *selected_stream* { "volume" : "+10" }``` +Now you can use your hal api to send commands to mixer. This way, you can change/ramp volume : -``` 4a-hal-*halapiname* *selected_stream* { "volume" : 70 }``` +`4a-hal-*halapiname* *selected_stream* { "volume" : "+10" }` -``` 4a-hal-*halapiname* *selected_stream* { "ramp" : "-10" }``` +`4a-hal-*halapiname* *selected_stream* { "volume" : 70 }` -``` 4a-hal-*halapiname* *selected_stream* { "ramp" : 100 }``` +`4a-hal-*halapiname* *selected_stream* { "ramp" : "-10" }` +`4a-hal-*halapiname* *selected_stream* { "ramp" : 100 }` #### Warning -Alsa try top automatically store current state into /var/lib/alsa/asound.state when developing/testing this may create impossible -situation. In order to clean up your Alsa snd-aloop config, a simple "rmmod" might not be enough in some case you may have to delete -/var/lib/alsa/asound.state before applying "modprobe". +Alsa try to automatically store current state into `/var/lib/alsa/asound.state` +that may result to odd situation during development/testing. In order to clean +up your Alsa snd-aloop config, a simple `rmmod` might not be enough in some case +you may have to delete `/var/lib/alsa/asound.state` before applying `modprobe`. -In case of doubt check with folling command that you start from a clear green field +In case of doubt, check with following command that you start from a clear green field +```bash +rmmod snd-aloop && modprobe --first-time snd-aloop && amixer -D hw:Loopback controls | grep vol ``` -rmmod snd-aloop && modprobe --first-time snd-aloop && amixer -D hw:Loopback controls | grep vol -``` - ### Load an 'external' hal To load an external to '4a-hal-manger', you need to you use an 'api_call' from you hal binding. -With this 'api_call' you must sent a json descition of your api: +With this 'api_call' you must sent a json description of your api: -``` +```json { "api" : mandatory, string that is your hal binding api "uid" : mandatory, string that specify your hal uid (usually the device used by your hal) - "info" : optional, string that describe your hal + "info" : optional, string that describes your hal "author" : optional, string that says who is the author of your hal "version" : optional, string that says what is the version of your hal "date" : optional, string that says the date of your hal @@ -200,17 +194,16 @@ With this 'api_call' you must sent a json descition of your api: Your hal must also have a 'subscribe' verb available and event name 'hal_status'. -At external hal loading, the '4a-hal-manager' will subscibe to this event. +At external hal loading, the '4a-hal-manager' will subscribe to this event. Within your hal, you must generate an event each time the status of your hal changes. - ## What is missing in RC1 version -* Check that external really exist at loading +* Check that external hal really exist at loading * Handling external hal status events. * Handling 'halcontrol' section in configuration files. -* Generation of an event of '4a-hal-manager' when a hal status change. +* Generation of an '4a-hal-manager' event when a hal status change. * Checking that the specified device in configuration file is present ('4a-alsa-core' binding will be needed). -* Actualization of the internal hal status after mixer initialization. +* Update internal hal status after mixer initialization. * At mixer initialization, check that the specified device is not already used by another hal. -* Dynamic handling of USB devices.
\ No newline at end of file +* Dynamic handling of USB devices. |