doc: ucm - more volume notes

Signed-off-by: Jaroslav Kysela <perex@perex.cz>

3 files changed, 72 insertions, 13 deletions

diff --git a/doc/pictures/ucm-volume.puml b/doc/pictures/ucm-volume.puml
new file mode 100644
index 00000000..a698b316
--- /dev/null
+++ b/doc/pictures/ucm-volume.puml
@@ -0,0 +1,19 @@
+@startuml
+title "UCM volume"
+
+start
+if (Card state (/var/lib/alsa/asound.state)) then (not present)
+  :UCM: BootSequence;
+else (present)
+  :alsactl: Restore state (from asound.state);
+endif
+:UCM application:set device volume;
+note right
+  The application uses (Playback|Capture)MixerElem or
+  (Playback/Capture)(Volume/Switch) values to get
+  the controls.
+end note
+:alsactl: Store state (to asound.state);
+stop
+
+@enduml
diff --git a/doc/pictures/ucm-volume.svg b/doc/pictures/ucm-volume.svg
new file mode 100644
index 00000000..d07b2dc2
--- /dev/null
+++ b/doc/pictures/ucm-volume.svg
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="357px" preserveAspectRatio="none" style="width:724px;height:357px;background:#FFFFFF;" version="1.1" viewBox="0 0 724 357" width="724px" zoomAndPan="magnify"><defs/><g><rect height="26.2969" style="stroke:#00000000;stroke-width:1.0;fill:none;" width="107" x="307.25" y="15"/><text fill="#000000" font-family="sans-serif" font-size="14" font-weight="bold" lengthAdjust="spacing" textLength="97" x="312.25" y="32.9951">UCM volume</text><ellipse cx="215.5" cy="57.2969" fill="#222222" rx="10" ry="10" style="stroke:#222222;stroke-width:1.0;"/><polygon fill="#F1F1F1" points="106.5,87.2969,324.5,87.2969,336.5,99.2969,324.5,111.2969,106.5,111.2969,94.5,99.2969,106.5,87.2969" style="stroke:#181818;stroke-width:0.5;"/><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacing" textLength="218" x="106.5" y="103.105">Card state (/var/lib/alsa/asound.state)</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacing" textLength="66" x="28.5" y="96.7026">not present</text><text fill="#000000" font-family="sans-serif" font-size="11" lengthAdjust="spacing" textLength="44" x="336.5" y="96.7026">present</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="147" x="11" y="121.2969"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="127" x="21" y="142.4355">UCM: BootSequence</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="285" x="204" y="121.2969"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="265" x="214" y="142.4355">alsactl: Restore state (from asound.state)</text><polygon fill="#F1F1F1" points="215.5,161.2656,227.5,173.2656,215.5,185.2656,203.5,173.2656,215.5,161.2656" style="stroke:#181818;stroke-width:0.5;"/><path d="M353.5,195.2656 L353.5,218.9648 L333.5,222.9648 L353.5,226.9648 L353.5,250.6641 A0,0 0 0 0 353.5,250.6641 L712.5,250.6641 A0,0 0 0 0 712.5,250.6641 L712.5,205.2656 L702.5,195.2656 L353.5,195.2656 A0,0 0 0 0 353.5,195.2656 " fill="#FEFFDD" style="stroke:#181818;stroke-width:0.5;"/><path d="M702.5,195.2656 L702.5,205.2656 L712.5,205.2656 L702.5,195.2656 " fill="#FEFFDD" style="stroke:#181818;stroke-width:0.5;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="338" x="359.5" y="212.3325">The application uses (Playback|Capture)MixerElem or</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="312" x="359.5" y="227.4653">(Playback/Capture)(Volume/Switch) values to get</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="80" x="359.5" y="242.5981">the controls.</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="236" x="97.5" y="205.9805"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="216" x="107.5" y="227.1191">UCM application:set device volume</text><rect fill="#F1F1F1" height="33.9688" rx="12.5" ry="12.5" style="stroke:#181818;stroke-width:0.5;" width="255" x="88" y="270.6641"/><text fill="#000000" font-family="sans-serif" font-size="12" lengthAdjust="spacing" textLength="235" x="98" y="291.8027">alsactl: Store state (to asound.state)</text><ellipse cx="215.5" cy="335.6328" rx="11" ry="11" style="stroke:#222222;stroke-width:1.0;fill:none;"/><ellipse cx="215.5" cy="335.6328" fill="#222222" rx="6" ry="6" style="stroke:#111111;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="94.5" x2="84.5" y1="99.2969" y2="99.2969"/><line style="stroke:#181818;stroke-width:1.0;" x1="84.5" x2="84.5" y1="99.2969" y2="121.2969"/><polygon fill="#181818" points="80.5,111.2969,84.5,121.2969,88.5,111.2969,84.5,115.2969" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="336.5" x2="346.5" y1="99.2969" y2="99.2969"/><line style="stroke:#181818;stroke-width:1.0;" x1="346.5" x2="346.5" y1="99.2969" y2="121.2969"/><polygon fill="#181818" points="342.5,111.2969,346.5,121.2969,350.5,111.2969,346.5,115.2969" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="84.5" x2="84.5" y1="155.2656" y2="173.2656"/><line style="stroke:#181818;stroke-width:1.0;" x1="84.5" x2="203.5" y1="173.2656" y2="173.2656"/><polygon fill="#181818" points="193.5,169.2656,203.5,173.2656,193.5,177.2656,197.5,173.2656" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="346.5" x2="346.5" y1="155.2656" y2="173.2656"/><line style="stroke:#181818;stroke-width:1.0;" x1="346.5" x2="227.5" y1="173.2656" y2="173.2656"/><polygon fill="#181818" points="237.5,169.2656,227.5,173.2656,237.5,177.2656,233.5,173.2656" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="67.2969" y2="87.2969"/><polygon fill="#181818" points="211.5,77.2969,215.5,87.2969,219.5,77.2969,215.5,81.2969" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="185.2656" y2="205.9805"/><polygon fill="#181818" points="211.5,195.9805,215.5,205.9805,219.5,195.9805,215.5,199.9805" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="239.9492" y2="270.6641"/><polygon fill="#181818" points="211.5,260.6641,215.5,270.6641,219.5,260.6641,215.5,264.6641" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="215.5" x2="215.5" y1="304.6328" y2="324.6328"/><polygon fill="#181818" points="211.5,314.6328,215.5,324.6328,219.5,314.6328,215.5,318.6328" style="stroke:#181818;stroke-width:1.0;"/><!--MD5=[3a7c61dd4ff8304ea95eeb2e154d1932]
+@startuml

+title "UCM volume"

+

+start

+if (Card state (/var/lib/alsa/asound.state)) then (not present)

+  :UCM: BootSequence;

+else (present)

+  :alsactl: Restore state (from asound.state);

+endif

+:UCM application:set device volume;

+note right

+  The application uses (Playback|Capture)MixerElem or

+  (Playback/Capture)(Volume/Switch) values to get

+  the controls.

+end note

+:alsactl: Store state (to asound.state);

+stop

+

+@enduml

+
+PlantUML version 1.2022.5(Sat Apr 30 12:55:52 CEST 2022)
+(LGPL source distribution)
+Java Runtime: OpenJDK Runtime Environment
+JVM: OpenJDK 64-Bit Server VM
+Default Encoding: UTF-8
+Language: cs
+Country: CZ
+--></g></svg>
\ No newline at end of file
diff --git a/src/ucm/ucm_confdoc.h b/src/ucm/ucm_confdoc.h
index cf928c67..d8948b80 100644
--- a/src/ucm/ucm_confdoc.h
+++ b/src/ucm/ucm_confdoc.h
@@ -63,6 +63,8 @@ use case verbs for that sound card. i.e.:
 # Example master file for blah sound card
 # By Joe Blogs <joe@bloggs.org>
 
+Syntax 6
+
 # Use Case name for user interface
 Comment "Nice Abstracted Soundcard"
 
@@ -91,7 +93,11 @@ ValueDefaults {
 # ALSA card controls which may be modified by user after initial settings.
 
 BootSequence [
-  cset "name='My control' on"
+  cset "name='Master Playback Switch',index=2 0,0"
+  cset "name='Master Playback Volume',index=2 25,25"
+  msleep 50
+  cset "name='Master Playback Switch',index=2 1,1"
+  cset "name='Master Playback Volume',index=2 50,50"
 ]
 
 # Define fixed boot sequence
@@ -117,23 +123,16 @@ SectionVerb {
 
   # enable and disable sequences are compulsory
   EnableSequence [
-    cset "name='Master Playback Switch',index=2 0,0"
-    cset "name='Master Playback Volume',index=2 25,25"
-    msleep 50
-    cset "name='Master Playback Switch',index=2 1,1"
-    cset "name='Master Playback Volume',index=2 50,50"
+    disdevall ""	# run DisableSequence for all devices
   ]
 
   DisableSequence [
-    cset "name='Master Playback Switch',index=2 0,0"
-    cset "name='Master Playback Volume',index=2 25,25"
-    msleep 50
-    cset "name='Master Playback Switch',index=2 1,1"
-    cset "name='Master Playback Volume',index=2 50,50"
+    cset "name='Power Save' on"
   ]
 
   # Optional transition verb
   TransitionSequence."ToCaseName" [
+    disdevall ""	# run DisableSequence for all devices
     msleep 1
   ]
 
@@ -212,6 +211,7 @@ SectionModifier."Capture Voice" {
   Value {
     TQ Voice
     CapturePCM "hw:${CardId},11"
+    PlaybackMixerElem "Master"
     PlaybackVolume "name='Master Playback Volume',index=2"
     PlaybackSwitch "name='Master Playback Switch',index=2"
   }
@@ -288,9 +288,20 @@ boot).
 ### Device volume
 
 It is expected that the applications handle the volume settings. It is not recommended
-to set the fixed values for the volume settings to the Enable / Disable sequences for
+to set the fixed values for the volume settings in the Enable / Disable sequences for
 verbs or devices, if the device exports the hardware volume (MixerElem or Volume/Switch
-values). The default volume settings should be set in the *BootSequence*.
+values). The default volume settings should be set in the *BootSequence*. The purpose
+for this scheme is to allow users to override defaults using the alsactl sound card
+state management.
+
+Checklist:
+
+1. Set default volume in BootSequence
+2. Verb's EnableSequence should ensure that all devices are turned off (mixer paths)
+   to avoid simultaneous device use - the previous state is unknown (see *disdevall*
+   and *disdev2* commands or create a new custom command sequence)
+
+\image html ucm-volume.svg
 
 ### Dynamic configuration tree