Updated participant protocol docs

Added new puml for state and update diagrams
Updated diagrams
Added table as csv - easier for updating later

Issue-ID: POLICY-4602
Change-Id: Iaca291057688b0a856192036816685d3b9676b4f
Signed-off-by: saul.gill <saul.gill@est.tech>

8 files changed, 184 insertions, 0 deletions

diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml b/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml
new file mode 100644
index 00000000..589e2cc3
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantDepriming.puml
@@ -0,0 +1,11 @@
+@startuml
+Commissioning_REST -> CLAMP_Runtime: De-Prime Automation Composition Type Definition
+alt Automation Composition Instances exist for Automation Composition Type
+	Commissioning_REST <- CLAMP_Runtime: Cannot decommission Automation Composition Type Definition
+else No Automation Composition Instances exist for Automation Composition Type
+	Participant <- CLAMP_Runtime: Participant Update\n[Remove Automation Composition Element Definitions\nfrom Participants in Automation Composition]
+	activate Participant
+	Participant -> Participant: Delete Automation Composition Element\nType Definitions and\nCommon Property Values
+	Participant -> CLAMP_Runtime: Participant Update Ack [from each Participant mentioned in Participant Update message]
+	deactivate Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml
new file mode 100644
index 00000000..8b6a18ea
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantDeregister.puml
@@ -0,0 +1,5 @@
+@startuml
+Participant -> CLAMP_Runtime: Participant Deregistration
+Participant <- CLAMP_Runtime: Participant Deregistration Ack
+Participant -> Participant: Shutdown Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml b/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml
new file mode 100644
index 00000000..8429c227
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantHandleStateChange.puml
@@ -0,0 +1,52 @@
+@startuml
+
+(*) --> "Process State Change Message"
+
+if "All Automation Composition Elements with my Participant ID processed?" then
+  --> [yes] "Send State Change Ack Message"
+  --> (*)
+else
+  --> [no] "Process next Automation Composition Element with my ID"
+  if "State Change Message Start Phase equals Automation Composition Element start phase" then
+    [true] if "Current State is DEPLOYED?" then
+     [true] if "Change to UNDEPLOYED?" then
+      --> [true] "Change Automation Composition Element to state UNDEPLOYED"
+      --> "Wait for DEPLOYED->UNDEPLOYED State Change to complete"
+      if "State Change?" then
+        --> [success] "Record Success for State Change Ack message"
+        --> "Process State Change Message"
+      else
+        --> [fail] "Record Error for State Change Ack message"
+        --> "Process State Change Message"
+      endif
+      else
+        --> [false] "Record Error for State Change Ack message"
+        --> "Process State Change Message"
+      endif
+    else
+      [false] if "Current State is UNDEPLOYED?" then
+        [true] if "Change to DEPLOYED?" then
+          --> [true] "Change Automation Composition Element to state DEPLOYED"
+          --> "Wait for UNDEPLOYED->DEPLOYED State Change to complete"
+          if "State Change?" then
+            --> [success] "Record Success for State Change Ack message"
+            --> "Process State Change Message"
+          else
+            --> [fail] "Record Error for State Change Ack message"
+            --> "Process State Change Message"
+          endif
+        else
+          --> [false] "Record Error for State Change Ack message"
+          --> "Process State Change Message"
+        endif
+      else
+        --> [false] "Record Error for State Change Ack message"
+        --> "Process State Change Message"
+      endif
+    endif
+  else
+    --> [false] "Skip Automation Composition Element"
+    --> "Process State Change Message"
+endif
+
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml b/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml
new file mode 100644
index 00000000..24f25d7c
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantMonitoring.puml
@@ -0,0 +1,3 @@
+@startuml
+Participant -> CLAMP_Runtime: Participant Status [periodically from each Participant in all Automation Compositions]
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml b/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml
new file mode 100644
index 00000000..064f913e
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantPriming.puml
@@ -0,0 +1,13 @@
+@startuml
+Commissioning_REST -> CLAMP_Runtime: Prime Automation Composition Type Defintions and\nset values of Common Properties
+activate CLAMP_Runtime
+loop over Participant Types in Automation Composition Type Definition
+	CLAMP_Runtime -> CLAMP_Runtime: Collect Automation Composition Element Type Definitions and\nCommon Property Values for Participant Type
+end
+Participant <- CLAMP_Runtime: Participant Update\n[Automation Composition Element Type Definitions and\nCommon Property Values for Participant Types]
+deactivate CLAMP_Runtime
+activate Participant
+Participant -> Participant: Store Automation Composition Element Type Definitions and\nCommon Property Values
+Participant -> CLAMP_Runtime: Participant Update Ack\n[from each Participant mentioned in Participant Update message]
+deactivate Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml
new file mode 100644
index 00000000..af42d571
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantRegister.puml
@@ -0,0 +1,17 @@
+@startuml
+activate Participant
+Participant -> Participant: Start Participant
+deactivate Participant
+Participant -> CLAMP_Runtime: Participant Registration
+Participant <- CLAMP_Runtime: Participant Registration Ack
+activate CLAMP_Runtime
+loop over Automation Composition Type Definitions
+	CLAMP_Runtime -> CLAMP_Runtime: Collect Automation Composition Element Type Definitions and\nCommon Property Values for\nParticipant Type of this Participant
+end
+deactivate CLAMP_Runtime
+Participant <- CLAMP_Runtime: Participant Update\n[Automation Composition Element Type Definitions and\nCommon Property Values for\nParticipant Type of Participant]
+activate Participant
+Participant -> Participant: Store Automation Composition Element Type Definitions and\nCommon Property Values
+Participant -> CLAMP_Runtime: Participant Update Ack
+deactivate Participant
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml b/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml
new file mode 100644
index 00000000..af8779da
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantStateChangeDialogue.puml
@@ -0,0 +1,35 @@
+@startuml
+
+activate CLAMP_Runtime
+CLAMP_Runtime -> CLAMP_Runtime: Build an ordered list of the Start Phases in the Automation Composition Instance
+deactivate CLAMP_Runtime
+
+alt "State Change UNDEPLOYED_to_DEPLOYED or LOCKED_to_UNLOCKED"
+  loop over Start Phases list in increasing order
+    CLAMP_Runtime -> Participant: Automation Composition State Change\n[to all Participants in Automation Composition with this Start Phase]
+    CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants
+    CLAMP_Runtime <- Participant: Automation Composition State Change Ack [from each Participant in this Start Phase of Automation Composition]
+    alt "State Change Ack reports success"
+      CLAMP_Runtime -> CLAMP_Runtime: Log success
+    else "State Change Ack reports an error"
+      CLAMP_Runtime -> CLAMP_Runtime: Log error
+      CLAMP_Runtime -> CLAMP_Runtime: Reset state of Automation Composition CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation
+    end
+  end
+else "State Change DEPLOYED_to_UNDEPLOYED or UNLOCKED_to_LOCKED"
+ loop over Start Phases list in decreasing order
+    CLAMP_Runtime -> Participant: Automation Composition State Change\n[to all Participants in Automation Composition with this Start Phase]
+    CLAMP_Runtime -> CLAMP_Runtime: Asynchronously wait for answers from Participants
+    CLAMP_Runtime <- Participant: Automation Composition State Change Ack [from each Participant in this Start Phase of Automation Composition]
+    alt "State Change Ack reports success"
+      CLAMP_Runtime -> CLAMP_Runtime: Log success
+    else "State Change Ack reports an error"
+      CLAMP_Runtime -> CLAMP_Runtime: Log error
+      CLAMP_Runtime -> CLAMP_Runtime: Reset state of Automation Composition CLAMP_Runtime -> CLAMP_Runtime: Abort State Change operation
+    end
+  end
+end
+
+CLAMP_Runtime -> CLAMP_Runtime: Set overall state of Automation Composition
+
+@enduml
diff --git a/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml b/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml
new file mode 100644
index 00000000..ccf7acc9
--- /dev/null
+++ b/docs/clamp/acm/api-protocol/puml/ParticipantUpdateMessage.puml
@@ -0,0 +1,48 @@
+@startuml
+
+(*) --> "Process Update Message"
+
+if "All Automation Composition Elements with my Participant ID processed?" then
+  --> [yes] "Send Update Ack Message"
+  --> (*)
+else
+  --> [no] "Process next Automation Composition Element with my ID"
+  if "New Automation Composition Element?" then
+	--> [yes] "Create Automation Composition Element"
+	--> "Set Automation Composition Element to state UNDEPLOYED/LOCKED"
+	--> "Order Deployment/Unlock of Automation Composition Element"
+	--> "Pass Parameters to Automation Composition Element"
+	--> "Wait for Deployment/Unlock to complete"
+	if "Automation Composition Element Deployed/Unlocked?" then
+      --> [success] "Record Success for Update Ack message"
+      --> "Process Update Message"
+    else
+      --> [fail] "Delete Automation Composition Element"
+      --> "Record Error for Update Ack message"
+      --> "Process Update Message"
+    endif
+  else
+  	--> [no] "Check Automation Composition Element State"
+  endif
+  if "DEPLOYED/UNLOCKED and Automation Composition Version change != patch?" then
+	--> [true] "Record Error for Update Ack message"
+    --> "Process Update Message"
+  else
+  	[false] if "NOT DEPLOYED/UNLOCKED and Automation Composition Version change == major?" then
+      --> [true] "Record Error for Update Ack message"
+      --> "Process Update Message"
+  else
+	--> [false] "Pass Changed Parameters to Automation Composition Element"
+	--> "Wait for reconfiguration to complete"
+    if "Automation Composition Element Reconfiguration?" then
+      --> [success] "Record Success for Update Ack message"
+      --> "Process Update Message"
+    else
+      --> [fail] "Roll back reconfiguration"
+      --> "Record Error for Update Ack message"
+      --> "Process Update Message"
+    endif
+  endif
+endif
+
+@enduml