Update document

Update ApplicationGuide

Change-Id: I8a9c675adeb8997debaa553f0e45f736a2719010
Signed-off-by: Kazumasa Mitsunari <knimitz@witz-inc.co.jp>

1 files changed, 152 insertions, 110 deletions

diff --git a/doc/ApplicationGuide.md b/doc/ApplicationGuide.md
index a56a7b1..e8c57e7 100644
--- a/doc/ApplicationGuide.md
+++ b/doc/ApplicationGuide.md
@@ -1,13 +1,15 @@
 **Sound Manager Application Guide**

 ====

-<div align="right">Revision: 0.2Beta</div>

+<div align="right">Revision: 0.2Final</div>

 <div align="right">TOYOTA MOTOR CORPORATION</div>

 <div align="right">Advanced Driver Information Technology</div>

-<div align="right">2nd/Oct/2017</div>

+<div align="right">23rd/Oct/2017</div>

 

 * * *

 

-## **<div id="Table\ of\ content">Table of content</div>**

+<div id="Table\ of\ content"></div>

+

+## Table of content

 - [Target reader of this document](#Target\ reader\ of\ this\ document)

 - [Overview](#Overview)

 - [Getting Start](#Getting\ Start)

@@ -38,15 +40,20 @@
 

 * * *

 

-## **<div id="Target\ reader\ of\ this\ document">Target reader of this document</div>**

+<div id="Target\ reader\ of\ this\ document"></div>

+

+## Target reader of this document

+

 Application developer whose software uses sound output.

 

 * * *

 

-## **<div id="Overview">Overview</div>**

-The sound manager is the service which provides **sound-right management** for multiple sound sources.  

-This service based on GENIVI Audio Manager, and this package contains service binder and library for API calling.  

-The reason why this service based on GENIVI Audio Manager is because the sound manager supports highly strong and flexible sound-right management function.

+<div id="Overview"></div>

+

+## Overview

+The sound manager is the service which provides **sound-right management** for multiple sound sources. 

+This service is based on GENIVI Audio Manager, and this package contains service binding and library for API calling. 

+The reason why this service is based on GENIVI Audio Manager is because GENIVI Audio Manager supports highly strong and flexible sound-right management function.

 

 In order to understand, the below figure shows the one of typical usecases.

 In this example, there are four sound mode.

@@ -57,35 +64,41 @@ In this example, there are four sound mode.
 ![Figure: Typical usecase](parts/typical-usecase.png)

 

 The important points are:

-- **There is a priority for each sound source.**  

-	In this example, "Tel" and "TTS" is stronger than "MediaPlayer". Therefore when the system got incoming call, all four outputs of MediaPlayer are muted automatically by Sound Manager. And in this timing, Sound Manager will issue the event to Media Player, then Media Player can stop the music. (Because depends on OEM's requirement, "Stop" is required, not "Mute".)  

-    "Tel" and "TTS" have the same priority. So if TTS event happened on talking, each sound will output from independent speaker.  

+- **There is a priority for each sound source.**

+	In this example, the priority of "Tel" and "TTS" is higher than "MediaPlayer". Therefore when the system got incoming call, all four outputs of MediaPlayer are muted automatically by Sound Manager. And in this timing, Sound Manager will issue the event to Media Player, then Media Player can stop the music. (Because depending on OEM's requirement, "Stop" is required.) 

+    "Tel" and "TTS" have the same priority. So if TTS event happened on talking, each sound will output from independent speaker. 

     If on-hook button is touched, Sound Manager will resume previous sound mode. In this example, basically it's MediaPlayer sound. But if TTS still playing, three speaker will output MediaPlayer sound but one speaker will continue to output TTS sound.

-- **Sound mode transition should be done by Sound Manager not Applications.**  

+- **Sound mode transition should be done by Sound Manager not Applications.**

 	Actually application cannot recognize all sound source and its priority, so some centerized manager is required. Sound Manager provides this function. Sound Manager has a database for usecase and priority and in line with this policy Sound Manager controls proper sound mode.

 

 

 The below links show the example of Sound/Window mode transition.

-* [Single window application](Display_Audio_Transition1.md)  

+* [Single window application](Display_Audio_Transition1.html)

 	This transition assumes target IVI system support only one window on screen. It's a similar transition to CES2017 demo.

-* [Dual window application](Display_Audio_Transition2.md)  

+* [Dual window application](Display_Audio_Transition2.html)

 	This transition assumes target IVI system support two window (split screen) on screen.

 

 	Of course user can customize shortcut menu, but since it's too many states so this example limits shortcut menu as "Home", "MediaPlayer", "HVAC" and "Navigation".

 

 * * *

 

-## **<div id="Getting\ Start">Getting Start</div>**

+<div id="Getting\ Start"></div>

+

+## Getting Start

+

+<div id="Supported\ environment"></div>

+

+### Supported environment

 

-### **<div id="Supported\ environment">Supported environment</div>**

 | Item        | Description                       |

 |:------------|:----------------------------------|

-| AGL version | Daring Dab                        |

+| AGL version | Electric Eel                      |

 | Hardware    | Renesas R-Car Starter Kit Pro(M3) |

 

 

-### **<div id="Build">Build</div>**

+<div id="Build"></div>

 

+### Build

 You can make Sound Manager object files by the following two stage operations.

 

 **Download recipe**

@@ -93,26 +106,24 @@ If repo is already done, please start with git clone
 ```

 $ mkdir WORK

 $ cd WORK

-$ repo init -b dab -m dab_4.0.0_xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo

+$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo

 $ repo sync

-$ git clone https://gerrit.automotivelinux.org/gerrit/staging/meta-hmi-framework

 

 ```

 

-Then you can get the following recipe.

-* `meta-hmi-framework/agl-service-soundmanager-2017`

-

 

 **Bitbake**

 ```

-$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack hmi-framework

-$ bitbake agl-service-soundmanager-2017

+$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework

+$ bitbake agl-demo-platform

 ```

 

 

 * * *

 

-### **<div id="Configuring">Configuring</div>**

+<div id="Configuring"></div>

+

+### Configuring

 To use Sound Manager API, an application shall paste the following configuration definition into "config.xml" of application.

 ```

 <feature name="urn:AGL:widget:required-api">

@@ -122,19 +133,22 @@ To use Sound Manager API, an application shall paste the following configuration
 

 * * *

 

-### **<div id="Additional\ work">Additional work</div>**

+<div id="Additional\ work"></div>

 

+### Additional work

 **Add Policy file**

 

-To add Sound Manager Domain into policy, put the following file to /etc/audiomanager/control.

+To add Sound Manager Domain into policy, put the following file to /etc/audiomanager/control on the target rootfs.

+

+` ${SOUNDMANAGER_DIR}/conf/audiomanager-config-sample/configuration.xml`

 

-` soundmanager/conf/audiomanager-config-sample/configuration.xml`

+This is a sample configuration.

 

 

 **Remove Module router of Pulse Audio**

 

-Because the module rounter access to Audio manager for getting sound right instead of application in CES2017, after you changed your application code for Sound manager, you should remove the module router.  

-To do this, you have to comment out line.143 of /etc/pulse/default.pa as below.

+Because the module rounter accesses Audio manager for getting sound right instead of application in CES2017, after you changed your application code for Sound manager, you shall modify the configuration for puluse audio not to load module router. 

+To do this, you shall comment out line.143 of /etc/pulse/default.pa on the target rootfs as below.

 

 ```

 .ifexists module-router.so

@@ -146,9 +160,11 @@ To do this, you have to comment out line.143 of /etc/pulse/default.pa as below.
 

 * * *

 

-### **<div id="How\ to\ call\ Sound\ Manager\ APIs\ from\ your\ Application?">How to call Sound Manager APIs from your Application?</div>**

-Sound Manager provides a library which is called "libsoundmanager".  

-This library provides function style API calling interface. So you should include libsoundmanager.hpp headerfile, and should link this library.

+<div id="How\ to\ call\ Sound\ Manager\ APIs\ from\ your\ Application?"></div>

+

+### How to call Sound Manager APIs from your Application?

+Sound Manager provides a library which is called "libsoundmanager".

+This library provides function style API calling interface. So you can include libsoundmanager.hpp headerfile, and can link this library.

 Please also refer sample application and template.

 

 

@@ -159,7 +175,9 @@ See also our [Sample code](#Sample\ code).
 

 * * *

 

-## **<div id="Supported\ usecase">Supported usecase</div>**

+<div id="Supported\ usecase"></div>

+

+## Supported usecase

 1. Active source change

 	- When user choose different audio source with current one, IVI system stop or pause current source and activate new one.

 	- When user connect external device e.g. iPhone, USB memory IVI system change active source automatically to connected one.

@@ -183,31 +201,35 @@ See also our [Sample code](#Sample\ code).
 

 * * *

 

-## **<div id="Software\ Architecture">Software Architecture</div>**

-The architecture of Sound Manager is shown below.  

-Sound Manager is the service designed to be used by multiple applications.  

-Therefore Sound Manager framework consists on two binder layers. Please refer the following figure.  

-The upper binder is for application side security context for applications. The lower binder is for servide side security context.  

-Usually application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Sound Manager.  

-On the other hand, regarding lower binder there is only one module in the system. This binder receives all messages from multiple applications (in detail, it comes from upper layer binder).

+<div id="Software\ Architecture"></div>

 

-The communication protocols between libsoundmanager and upper binder, upper binder and lower binder, lower binder (soundmanager-binding) and AudioManager are WebSocket.

+## Software Architecture

+The architecture of Sound Manager is shown below.

+Sound Manager is the service designed to be used by multiple applications.

+Therefore Sound Manager framework consists of two binder layers. Please refer the following figure. 

+The upper binder is for application side security context. The lower binder is for server side security context. 

+Usually an application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Sound Manager. 

+On the other hand, regarding lower binder there is only one module in the system. This binder receives messages from multiple applications (in detail, it comes from upper layer binder).

+

+The communication protocols between libsoundmanager and upper binder, upper binder and lower binder,  are WebSocket. The protocols between lower binder (soundmanager-binding) and AudioManager is D-Bus.

 

 ![software-stack.png](parts/software-stack.png)

 

 * * *

 

-## **<div id="API\ reference">API reference</div>**

+<div id="API\ reference"></div>

+

+## API reference

 "libsoundmanager" and "soundmanager_binding" provides several kinds of APIs, and these APIs basically correspond to GENIVI Audio Manager API. (Some APIs are Sound Manager original functions.)

 

 For understanding, GENIVI Audio Manager stands for one core module and three plug-ins.

-1. AudioManagerDaemon  

+1. AudioManagerDaemon

 	This is a core module of Audio Manager.

-2. AudioManagerCommandPlugin  

+2. AudioManagerCommandPlugin

 	This is a command interface for Audio Manager.

-3. AudioManagerController  

+3. AudioManagerController

 	This plug-in can be used for sound-right management.

-4. AudioManagerRountingPlugin  

+4. AudioManagerRountingPlugin

 	This plug-in abstracts the hardware and software. And sometimes there may be multiple plug-ins.

 

 *) [See also GENIVI AudioManager Components](http://docs.projects.genivi.org/AudioManager/audiomanagercomponentspage.html)

@@ -216,81 +238,111 @@ For understanding, GENIVI Audio Manager stands for one core module and three plu
 (This figure was copied from GENIVI Web page.)

 

 

-### **<div id="APIs">APIs</div>**

+<div id="APIs"></div>

+

+### APIs

+- init(int port, const std::string& token)

+- registerSource(const std::string& sourceName)

+- connect(int sourceID, int sinkID)

+- connect(int sourceID, const std::string& sinkName)

+- disconnect(int connectionID)

+- ackSetSourceState(int handle, int err)

+- set_event_handler(enum EventType_SM et, handler_asyncSetSourceState f)

+- register_callback( void (*event_cb)(const std::string& event, struct json_object* event_contents), void (*reply_cb)(struct json_object* reply_contents), void (*hangup_cb)(void) = nullptr)

+- register_callback( void (*reply_cb)(struct json_object* reply_contents), void (*hangup_cb)(void) = nullptr) (overload)

+

+Regarding more detail, please refer doxygen documents.

 

-- [init(int port, const std::string& token)]()

-- [registerSource(const std::string& sourceName)](http://docs.projects.genivi.org/AudioManager/a00053.html#acadce23459d94cec496d17700cbde230)

-- [connect(int sourceID, int sinkID)](http://docs.projects.genivi.org/AudioManager/a00033.html#a62d8f5aee1e601d59f993c5a5561e234)

-- [connect(int sourceID, const std::string& sinkName = "default")](http://docs.projects.genivi.org/AudioManager/a00033.html#a62d8f5aee1e601d59f993c5a5561e234)

-- [disconnect(int connectionID)](http://docs.projects.genivi.org/AudioManager/a00033.html#aa24d0146f4e3c75e02d6c0152e246da1)

-- [ackSetSourceState(int sourceID, int handle, int errno)](http://docs.projects.genivi.org/AudioManager/a00053.html#a11f6b0378a50296a72107d6a1fa7ec21)

-- [LibSoundmanager ()](api-ref/html/class_lib_soundmanager.html#a8b51e9891813cb62dd12109c017ad106)

-- [set_event_handler(enum EventType_AsyncSetSourceState et, handler_asyncSetSourceState f)]()

-- [register_callback( void (*event_cb)(const std::string& event, struct json_object* event_contents), void (*reply_cb)(struct json_object* reply_contents), void (*hangup_cb)(void) = nullptr)]()

-- [register_callback( void (*reply_cb)(struct json_object* reply_contents), void (*hangup_cb)(void) = nullptr)]()

+<div id="Events"></div>

 

+### Events

 

-The below APIs will be available at RC2.

+"libsoundmanager" provides the feature which receives the events which an app subscribes with "subscribe" API.

+An application can get events to register a callback function with "register_callback" API.

 

-- [setVolume (const am_sinkID_t sinkID, const am_mainVolume_t volume)](http://docs.projects.genivi.org/AudioManager/a00033.html#a6d47bc67473d75495260abe8c666fc7e)

-- [volumeStep (const am_sinkID_t sinkID, const int16_t volumeStep)](http://docs.projects.genivi.org/AudioManager/a00033.html#ad7a4c1fe5a2ecfaae5484a14d8820e58)

-- [setSinkMuteState (const am_sinkID_t sinkID, const am_MuteState_e muteState)](http://docs.projects.genivi.org/AudioManager/a00033.html#afae22041843c5349be16a6593d3ebb9c)

-- [getListMainConnections (std::vector< am_MainConnectionType_s > &listConnections)](http://docs.projects.genivi.org/AudioManager/a00033.html#a59d10a7178e3227d0b8f415308c71179)

-- [confirmRoutingReady (const uint16_t handle, const am_Error_e error)](http://docs.projects.genivi.org/AudioManager/a00053.html#a1dd1b89cccffeaafb1a3c11cebd7e48c)

+or you can use "set_event_handler" API to designate the event enumlation.

 

+- Event_AsyncSetSourceState

 

-### **<div id="Events">Events</div>**

+The below events will be available at final version.

 

-- [EventType_AsyncSetSourceState]()

+- Event_NewMainConnection

+- Event_RemovedMainConnection

+- Event_MainConnectionStateChanged

+- Event_VolumeChanged

+- Event_SinkMuteStateChanged

+- Event_setRoutingReady

+- Event_asyncConnect

+- Event_asyncDisconnect

 

-The below Events will be available at RC2.

+But these events are not necessary.

 

-- [EventType_NewMainConnection](http://docs.projects.genivi.org/AudioManager/a00034.html#a69ada9e19c65c1d078d8a5f473d08586)

-- [EventType_RemovedMainConnection](http://docs.projects.genivi.org/AudioManager/a00034.html#aa3b5906bcf682cff155fb24d402efd89)

-- [EventType_MainConnectionStateChanged](http://docs.projects.genivi.org/AudioManager/a00034.html#a32aa8ab84632805a876e023a7aead810)

-- [EventType_VolumeChanged](http://docs.projects.genivi.org/AudioManager/a00034.html#a4494fdd835137e572f2cf4a3aceb6ae5)

-- [EventType_SinkMuteStateChanged](http://docs.projects.genivi.org/AudioManager/a00034.html#a6068ce59089fbdc63aec81e778aba238)

-- [EventType_setRoutingReady](http://docs.projects.genivi.org/AudioManager/a00054.html#a7a4d410e30df0e8240d25a57e3c72c6b)

-- [EventType_asyncConnect](http://docs.projects.genivi.org/AudioManager/a00054.html#a8a81297be9c64511e27d85444c59b0d6)

-- [EventType_asyncSetSourceState](http://docs.projects.genivi.org/AudioManager/a00054.html#ab02d93d54ee9cd98776a3f2d274ee24d)

-- [EventType_asyncDisconnect](http://docs.projects.genivi.org/AudioManager/a00054.html#a93ae95515730eb615ab5dfc1316d7862)

+Note:

+

+"asyncSetSourceState" is always subscribed in init phase because this is the most important event for audio policy management.

+

+Regarding more detail, please refer doxygen documents.

 

 * * *

 

-## **<div id="Sequence">Sequence</div>**

-### **<div id="StartUp">StartUp</div>**

+<div id="Sequence"></div>

+

+## Sequence

+<div id="StartUp"></div>

+

+### StartUp

 ![seq_startup.png](parts/seq_startup.svg)

 

-### **<div id="Registration">Registration</div>**

+<div id="Registration"></div>

+

+### Registration

 ![seq_registration.png](parts/seq_registration.svg)

 

-### **<div id="Request\ Sound\ Right">Request Sound Right</div>**

+<div id="Request\ Sound\ Right"></div>

+

+### Request Sound Right

 ![seq_requestsoundmode.png](parts/seq_requestsoundmode.svg)

 

-### **<div id="Connect\ Sound\ Route">Connect Sound Route</div>**

+<div id="Connect\ Sound\ Route"></div>

+

+### Connect Sound Route

 ![seq_connectsoundroute.png](parts/seq_connectsoundroute.svg)

 

-### **<div id="Start\ Sound\ Streaming">Start Sound Streaming</div>**

+<div id="Start\ Sound\ Streaming"></div>

+

+### Start Sound Streaming

 ![seq_startsoundstreaming.png](parts/seq_startsoundstreaming.svg)

 

-### **<div id="Stop\ Sound\ Streaming">Stop Sound Streaming</div>**

+<div id="Stop\ Sound\ Streaming"></div>

+

+### Stop Sound Streaming

 ![seq_stopsoundstreaming.png](parts/seq_stopsoundstreaming.svg)

 

-### **<div id="Disconnect\ Sound\ Route">Disconnect Sound Route</div>**

+<div id="Disconnect\ Sound\ Route"></div>

+

+### Disconnect Sound Route

 ![seq_disconnectsoundroute.png](parts/seq_disconnectsoundroute.svg)

 

-### **<div id="Change\ Volume">Change Volume</div>**

+<div id="Change\ Volume"></div>

+

+### Change Volume

 ![seq_changevolume.png](parts/seq_changevolume.svg)

 

-### **<div id="Set\ Mute\ State">Set Mute State</div>**

+<div id="Set\ Mute\ State"></div>

+

+### Set Mute State

 ![seq_setmutestate.png](parts/seq_setmutestate.svg)

 

-### **<div id="Release\ Sound\ Right">Release Sound Right</div>**

+<div id="Release\ Sound\ Right"></div>

+

+### Release Sound Right

 ![seq_releasesoundmode.png](parts/seq_releasesoundmode.svg)

 

 * * *

 

-### **<div id="Audio\ Domain">Audio Domain</div>**

+<div id="Audio\ Domain"></div>

+

+### Audio Domain

 

 One of the most important concept of Audio Manager is Audio Domain.

 To use GENIVI Audio Manager based system, it may be better to understand this concept.

@@ -301,30 +353,20 @@ The below document should bring good understanding.
 Although strongly recommended to read whole pages, but you can get quick understanding by page.10 to 14.

 

 

-# **<div id="Sample\ code">Sample code</div>**

-You can find sample implementation of Sound Manager as below.

-* `apps/agl-service-homescreen-2017/sample/template`  

-* `apps/agl-service-homescreen-2017/sample/radio`  

-* `apps/agl-service-homescreen-2017/sample/mediaplayer`  

+<div id="Sample\ code"></div>

+

+# Sample code

+You can find samples using Sound Manager as below.

+* `apps/agl-service-homescreen-2017/sample/template`

+* `apps/radio (branch=sandbox/knimitz/hmi-framework)`

 

 

+<div id="Limitation"></div>

 

-# **<div id="Limitation">Limitation</div>**

-* Minimum APIs and Events are prepared for RC1, the following APIs will be available for RC2.

+# Limitation

+* Minimum APIs and Events are prepared for RC2, the following APIs will be available for final version of EE.

 

-	* setVolume

-	* volumeStep

-	* setSinkMuteState

-	* getListMainConnections

-	* confirmRoutingReady

-	* EventType_NewMainConnection

-	* EventType_RemovedMainConnection

-	* EventType_MainConnectionStateChanged

-	* EventType_VolumeChanged

-	* EventType_SinkMuteStateChanged

-	* EventType_setRoutingReady

-	* EventType_asyncConnect

-	* EventType_asyncSetSourceState

-	* EventType_asyncDisconnect

+	* getListMainSinks

 

+* Sound of application is not automatically muted for now because Audio Manager doesn't automatically stop with current plugins.