summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Linke <christian.linke@bmw.de>2013-02-07 10:16:56 +0100
committerChristian Linke <christian.linke@bmw.de>2013-02-07 10:16:56 +0100
commit81f532ef9954dd61fcd975a2aaf3f1b86a320454 (patch)
tree871cefd9d98f4cfbab0771b8eb1e2e1818124644
parent196282dd153ecf292bae6b1c7e3cf6cfe35c5ce3 (diff)
downloadaudiomanager-81f532ef9954dd61fcd975a2aaf3f1b86a320454.tar.gz
* enhancing documentation
Signed-off-by: Christian Linke <christian.linke@bmw.de>
-rw-r--r--AudioManagerDaemon/docx/13_x_notifications.dox64
-rw-r--r--AudioManagerDaemon/docx/14_misc.dox19
-rw-r--r--AudioManagerDaemon/docx/14_u_last_user_mode.dox37
-rw-r--r--AudioManagerDaemon/docx/14_z_nodeStateManagement.dox8
-rw-r--r--AudioManagerDaemon/docx/14_zz_Startup_Rundown.dox30
-rwxr-xr-xAudioManagerDaemon/docx/images/CancelRundown.pngbin0 -> 61007 bytes
-rwxr-xr-xAudioManagerDaemon/docx/images/ChangeofAudioformatduringplaytime.pngbin0 -> 46422 bytes
-rwxr-xr-xAudioManagerDaemon/docx/images/LastUserModeHandlingExample.pngbin0 -> 49412 bytes
-rwxr-xr-xAudioManagerDaemon/docx/images/Notifications.pngbin0 -> 23940 bytes
-rwxr-xr-xAudioManagerDaemon/docx/images/Registrations.pngbin0 -> 38991 bytes
-rwxr-xr-xAudioManagerDaemon/docx/images/Rundown.pngbin0 -> 75612 bytes
-rwxr-xr-xAudioManagerDaemon/docx/images/Startup.pngbin0 -> 86887 bytes
-rwxr-xr-xAudioManagerDaemon/docx/images/StartupWithLastUserMode.pngbin0 -> 22247 bytes
13 files changed, 146 insertions, 12 deletions
diff --git a/AudioManagerDaemon/docx/13_x_notifications.dox b/AudioManagerDaemon/docx/13_x_notifications.dox
new file mode 100644
index 0000000..135d4a5
--- /dev/null
+++ b/AudioManagerDaemon/docx/13_x_notifications.dox
@@ -0,0 +1,64 @@
+ /*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \\author Christian Linke (christian.linke@bmw.de)
+ *
+ */
+ /*!
+\page notifi Notifications
+\section notifi_ex What are notifications?
+The notification feature can be used to gather information from sources or sinks periodically or on certain thresholds.It can be used to implement a graphical spectrum for example or other information need to be passed back from sources or sinks.
+
+\section notifi_overview Overview
+\image html Notifications.png
+
+\section notifi_command CommandInterface
+all this methods have to do with MainNotifications (Information level between command and control)
+- am::IAmCommandSend::cbSinkNotification
+- am::IAmCommandSend::cbSourceNotification
+- am::IAmCommandSend::cbMainSinkNotificationConfigurationChanged
+- am::IAmCommandSend::cbMainSourceNotificationConfigurationChanged
+- am::IAmCommandReceive::getListMainSourceNotificationConfigurations
+- am::IAmCommandReceive::getListMainSinkNotificationConfigurations
+- am::IAmCommandReceive::setMainSourceNotificationConfiguration
+- am::IAmCommandReceive::setMainSinkNotificationConfiguration
+\section notifi_control ControlInterface
+all this methods have to do with MainNotifications (Information level between command and control)
+- am::IAmControlSend::hookUserSetMainSinkNotificationConfiguration
+- am::IAmControlSend::hookUserSetMainSourceNotificationConfiguration
+- am::IAmControlReceive::changeMainSinkNotificationConfigurationDB
+- am::IAmControlReceive::changeMainSourceNotificationConfigurationDB
+- am::IAmControlReceive::sendMainSinkNotificationPayload
+- am::IAmControlReceive::sendMainSourceNotificationPayload
+
+all this methods have to do with notifications (Information level between cotrol and routing)
+- am::IAmControlSend::cbAckSetSinkNotificationConfiguration
+- am::IAmControlSend::cbAckSetSourceNotificationConfiguration
+- am::IAmControlSend::hookSinkNotificationDataChanged
+- am::IAmControlSend::hookSourceNotificationDataChanged
+- am::IAmControlReceive::setSinkNotificationConfiguration
+- am::IAmControlReceive::setSourceNotificationConfiguration
+\section notifi_routing RoutingInterface
+all this methods have to do with notifications (Information level between cotrol and routing)
+- am::IAmRoutingSend::asyncSetSinkNotificationConfiguration
+- am::IAmRoutingSend::asyncSetSourceNotificationConfiguration
+- am::IAmRoutingReceive::ackSinkNotificationConfiguration
+- am::IAmRoutingReceive::ackSourceNotificationConfiguration
+- am::IAmRoutingReceive::hookSinkNotificationDataChange
+- am::IAmRoutingReceive::hookSourceNotificationDataChange
+
+\section notifi_levels Notification Levels
+For notifications it's the same as for the soundproperties: there are two levels of information. One is between the Command Interface and the Control Interface
+here it is in the duty of the controller to handle the notification data. The other one is between Control and Routing Interface. This could be used for example
+to route the information from a source to the command interface.
+*/ \ No newline at end of file
diff --git a/AudioManagerDaemon/docx/14_misc.dox b/AudioManagerDaemon/docx/14_misc.dox
index eae0caf..7b3f950 100644
--- a/AudioManagerDaemon/docx/14_misc.dox
+++ b/AudioManagerDaemon/docx/14_misc.dox
@@ -17,21 +17,22 @@
/*!
\page misc Miscellaneous
-\section connfor Connection Formats
+\section misc_connfor Connection Formats
Every flow of audio is using a format to exchange data. The format that the source and the sink uses must match together in order to have an undisturbed
experience. It is common that sources and sinks are capable of supporting more than one audioformat.\n
So all sources and sinks register with a list of connectionFormats that they support and for each connection a format must be chosen that is then used
to transport the audio data. Gateways (and Soundconverters) have the information which connectionFormat can be transformed into another one.
-- am::am_ConnectionFormat_e has all formats listed.
+am::am_ConnectionFormat_e has all formats listed.\n
+There is a special usecase that is worth showing as an example in this regard: the change of a connectionFormat when switching from one song to another. Here is an
+example of how the project specific parts could handle this:
+\image html ChangeofAudioformatduringplaytime.png
-\section pers Persistence & Lifecycle
-Details of persistence can be done when the si-team have defined the components and interfaces in the Enterprise Architect model.
-So much is clear: the persistence will be based on POSIX interfaces that can be used to read and write data.\n
-Persistence is a very system specific topic: what needs to be remembered over lifecycles, what will be reset to default? So this needs to be done via the
-AudioMangerController. The Controller will then enter the values read from the persistence and write them to the daemon.
-The lifecycle itself will be handles by the daemon which will then fire hooks in the controller to make sure appropriate actions are taken.
-\section speed Speed dependent volume
+\section misc_pers Persistence
+The persistence client library is defined as an abstract component with a c-like library interface. Since the AudioManagerController is the only one to know
+what is to be made persistent, he is the one interfacing with that library. This is the reason why there is no specific interface for the persistence here.
+
+\section misc_speed Speed dependent volume
The adjustments for the speed are done product specific in the controller. The speed information itself is retrieved by the AudioManagerDaemon, sampled and
quantified and forwarded to the controller. The interface in not yet defined !\n
Turning speed controlled volume on/off and possible settings are achieved via SinkSoundProperty settings.
diff --git a/AudioManagerDaemon/docx/14_u_last_user_mode.dox b/AudioManagerDaemon/docx/14_u_last_user_mode.dox
new file mode 100644
index 0000000..0c90f89
--- /dev/null
+++ b/AudioManagerDaemon/docx/14_u_last_user_mode.dox
@@ -0,0 +1,37 @@
+ /*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \\author Christian Linke (christian.linke@bmw.de)
+ *
+ */
+
+/*!
+\page luc Last User Mode
+\section luc_concept Last User Mode concept
+In general last user modes are project specific. So it is not mandatory to do it like described here - it is just a suggestion how it could be implemented
+together with the LUC handler (Last User Concept). The LUC handler is a part of the NSC (Node State Controller) which is a GENIVI component. More information can be
+found within GENIVI.\n
+For implementing the suggested method here, the AudioManagerController has to take care of communicating with the LUC handler. The AudioManager is the
+component that knows the last heard source that should be started earlier than others in order to reduce the timespan until the customer can hear it's last
+source.\n
+In order to fullfull this, the controller has to keep a map that links sources to unit files. The sequence that shall be an example of how it could be realized.\n
+
+\section luc_rundown The handling in the rundown context:
+\image html LastUserModeHandlingExample.png
+
+\section luc_startup The next startup:
+\image html StartupWithLastUserMode.png
+
+
+
+ */
diff --git a/AudioManagerDaemon/docx/14_z_nodeStateManagement.dox b/AudioManagerDaemon/docx/14_z_nodeStateManagement.dox
index 4e7d3e3..216338a 100644
--- a/AudioManagerDaemon/docx/14_z_nodeStateManagement.dox
+++ b/AudioManagerDaemon/docx/14_z_nodeStateManagement.dox
@@ -26,10 +26,12 @@ It is the job of am::CAmNodeStateCommunicator to interact with the nodestatemana
The ControllerPlugin can register by the NSM to be informed when a shutdown will occour. For this, the Audiomanager presents an DBus interface, defined in LifeCycleConsumer.xml that will be called from the NSM during a shutdown,
but only after the Controller registered by the NSM via am::CAmNodeStateCommunicator::nsmRegisterShutdownClient.\n
The controller has to answer this request during the timeout with am::CAmNodeStateCommunicator::nsmSendLifecycleRequestComplete .
-For more information, check am::CAmNodeStateCommunicator and http://projects.genivi.org
-Here is an overview of the relations between AudioManager and NSM:
+For more information, check am::CAmNodeStateCommunicator and http://projects.genivi.org\n
+\section nsm_overview Overview of the relations between AudioManager and NSM:
\image html NodeStateManagementRelations.png
-Here is the sequence that is used to do handle the lifecyclerequests:
+\section nsm_reg Registering at startup
+\image html Registrations.png
+\section nsm_lifec Handling of Lifecyclerequests:
\image html Lifecylerequest.png
*/
diff --git a/AudioManagerDaemon/docx/14_zz_Startup_Rundown.dox b/AudioManagerDaemon/docx/14_zz_Startup_Rundown.dox
new file mode 100644
index 0000000..88f8dc6
--- /dev/null
+++ b/AudioManagerDaemon/docx/14_zz_Startup_Rundown.dox
@@ -0,0 +1,30 @@
+ /*
+ * Copyright (C) 2012, BMW AG
+ *
+ * This file is part of GENIVI Project AudioManager.
+ *
+ * Contributions are licensed to the GENIVI Alliance under one or more
+ * Contribution License Agreements.
+ *
+ * \copyright
+ * This Source Code Form is subject to the terms of the
+ * Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with
+ * this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * \\author Christian Linke (christian.linke@bmw.de)
+ *
+ */
+
+/*!
+\page start Startup and Rundown
+\section start_Start Startup
+This flow describes the startup of the AudioManager:
+\image html Startup.png
+\section start_Rundown Rundown
+This flow describes the rundown of the AudioManager:
+\image html Rundown.png
+\section start_Cancel Cancelled Rundown
+This flow describes the cancel rundown of the AudioManager:
+\image html CancelRundown.png
+
+ */
diff --git a/AudioManagerDaemon/docx/images/CancelRundown.png b/AudioManagerDaemon/docx/images/CancelRundown.png
new file mode 100755
index 0000000..889ed56
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/CancelRundown.png
Binary files differ
diff --git a/AudioManagerDaemon/docx/images/ChangeofAudioformatduringplaytime.png b/AudioManagerDaemon/docx/images/ChangeofAudioformatduringplaytime.png
new file mode 100755
index 0000000..2fa30a1
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/ChangeofAudioformatduringplaytime.png
Binary files differ
diff --git a/AudioManagerDaemon/docx/images/LastUserModeHandlingExample.png b/AudioManagerDaemon/docx/images/LastUserModeHandlingExample.png
new file mode 100755
index 0000000..fd34b4a
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/LastUserModeHandlingExample.png
Binary files differ
diff --git a/AudioManagerDaemon/docx/images/Notifications.png b/AudioManagerDaemon/docx/images/Notifications.png
new file mode 100755
index 0000000..d938d61
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/Notifications.png
Binary files differ
diff --git a/AudioManagerDaemon/docx/images/Registrations.png b/AudioManagerDaemon/docx/images/Registrations.png
new file mode 100755
index 0000000..b3abae9
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/Registrations.png
Binary files differ
diff --git a/AudioManagerDaemon/docx/images/Rundown.png b/AudioManagerDaemon/docx/images/Rundown.png
new file mode 100755
index 0000000..daa8470
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/Rundown.png
Binary files differ
diff --git a/AudioManagerDaemon/docx/images/Startup.png b/AudioManagerDaemon/docx/images/Startup.png
new file mode 100755
index 0000000..6fa84a5
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/Startup.png
Binary files differ
diff --git a/AudioManagerDaemon/docx/images/StartupWithLastUserMode.png b/AudioManagerDaemon/docx/images/StartupWithLastUserMode.png
new file mode 100755
index 0000000..a42ac2e
--- /dev/null
+++ b/AudioManagerDaemon/docx/images/StartupWithLastUserMode.png
Binary files differ