From 19863c15f9b19fb340cd687e679ad2e3d393233d Mon Sep 17 00:00:00 2001
From: Nathan Figueroa <nathan.figueroa@whoi.edu>
Date: Fri, 1 Mar 2024 17:46:25 -0500
Subject: [PATCH] docs: Architecture description and diagrams

---
 README.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 127 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e7a4828..80ca470 100644
--- a/README.md
+++ b/README.md
@@ -197,7 +197,7 @@ and
 docker exec -it phyto-arm start mock_arm_chanos /configs/config.yaml
 ```
 
-# Unit tests
+### Unit tests
 
 To run unit tests, execute
 ```bash
@@ -359,7 +359,7 @@ WantedBy=multi-user.target
 - [ ] When ready, run PhytO-ARM for a cycle to confirm no errors
 
 
-## Development
+# Development
 
 To develop in PhytO-ARM, it is recommended to use a development container with the provided development container configuration file. This can be done locally or on a remote machine (e.g. an IFCB).
 
@@ -374,6 +374,119 @@ The development container allows you to develop and test from an environment ide
 
 The `.git` repository folder is also mounted in the development container, making it possible to pull/commit/push as needed from within the container.
 
+### Architecture
+
+PhytO-ARM has evolved to handle multiple mission types and deployment configurations. Deployments so far include single-winch on a stationary platform, winchless on an autonomous surface vehicle, and multi-winch on a stationary platform.
+
+PhytO-ARM has been modularized to support any configuration of winch and scientific payload. Scientific payloads are isolated into distinct "arms", each of which may have a winch providing movement for that arm. All arms should implement `ArmBase`, an interface class which handles winch movement logic and coordinates movement between arms by communicating with a central `lock_manager` node. 
+
+`lock_manager` is primarily to limit how many winches can move concurrently, as configured by the parameter `/lock_manager/max_moving_winches`. This is primarily to accommodate missions which may require inter-arm coordination, or to prevent overdraw of power on battery-powered setups.
+
+PhytO-ARM comes with two arm implementations included, see `arm_ifcb.py` and `arm_chanos.py` in the `phyto_arm` package. Any number of arms is supported however, as illustrated below. Each box represents a set of nodes with an independent launch file.
+
+```mermaid
+graph TD
+    subgraph PhytO-ARM
+        subgraph Main
+            cameras(Cameras)
+            lm(Lock Manager) 
+            gps(GPS)
+        end
+        subgraph Arm1
+            w1(Winch1)
+            subgraph Payload1
+                ifcb(IFCB)
+                c1(AML CTD)
+            end
+        end
+        subgraph Arm2
+            w2(Winch2)
+            subgraph Payload2
+                chanos(Chanos)
+                c2(RBR CTD)
+            end
+        end
+        subgraph ArmN
+            w3(WinchN)
+            subgraph PayloadN
+                unknown(?)
+                c4(? CTD)
+            end
+        end
+    end
+
+lm <--> w1
+lm <--> w2
+lm <--> w3
+```
+
+### Mission Tasks
+
+Each arm implementing `ArmBase` must override `get_next_task`, which is where all decisions are made on which task to perform next. 
+
+```mermaid
+graph
+    subgraph Arm Execution Loop
+        subgraph Main
+            lm(Lock Manager)
+        end
+        subgraph ArmBase
+            loop
+            winch(send_winch_goal)
+            snt(start_next_task)
+            subgraph Arm Implementation
+                gnt(get_next_task)
+                cb(Task callback)
+            end
+        end
+    end
+
+loop -- Await clearance --> lm
+lm -- Get task --> gnt
+gnt -- Move to depth --> winch
+gnt -. Skip if no winch .-> cb
+winch -- Execute --> cb
+cb --> snt
+snt --> loop
+```
+
+### Hardware topology
+
+In all deployments thus far, we have used the IFCB as the primary host to run PhytO-ARM and coordinate movements and sampling. The hardware architecture diagram below illustrates this. 
+
+```mermaid
+graph
+    subgraph Platform
+        subgraph IFCB Arm
+            motor1(JVL motor)
+            aml(AML CTD)
+            subgraph IFCB
+                acquire{IFCB Acquire}
+                pa{PhytO-ARM}
+            end
+        end
+        subgraph Chanos Arm
+            pi(Rapsberry Pi)
+            motor2(JVL Motor)
+            chanos(Chanos)
+            rbr(RBR CTD)
+        end
+    end
+    subgraph Key
+        hw(Hardware)
+        sw{Software}
+    end
+
+pa -- Drive (TCP) --> motor1
+pa -- Drive (TCP) --> motor2
+aml -- Serial --> pa
+rbr -- Serial --> pi
+pi -- UDP --> pa
+chanos -- Timed sampling -->chanos
+pa -- Trigger (TCP) --> acquire
+```
+
+
 ## Node Inventory
 
 Note that ROS path conventions are used, such that paths beginning with `/` are absolute, paths beginning with `~` start at the node, and paths without a prefix are relative to their namespace. Global namespace is used for main nodes, while `arm_ifcb` and `arm_chanos` namespaces are used for the IFCB and Chanos arms, respectively.
@@ -527,6 +640,18 @@ These nodes provide functionality for recording data and connecting to other too
 
 
 
+## Style guide (beta)
+
+1. Place a blank newline before comment lines to make them easier to spot, e.g.
+```
+# First comment
+val1 = 'some value'
+
+# Second comment
+val2 = 'next value'
+```
+A style guide has not yet been rigorously defined, this section will expand as new policies are adopted.
+
 
 ## Observing with Foxglove Studio