Example sw diagram

docs/electrical_design.md

@@ -1,7 +1,6 @@
 # Electrical Design
 
-
-## System description
+## Description
 The trunk is actuated by 6 CIM 12V motors, each with a Talon SRX controller and an encoder. The CIM motors are powered by a 12V, 100A power supply. A 20A circuit breaker is in series with the positive terminal of each motor controller to protect from current spikes. Low level motor commands are handled with a Raspberry Pi 4, which has its own 5V power supply. CAN is the protocol used to communicate commands from the Raspberry Pi to the motor controllers, via a CANable 1.0 device. The gripper servo has its own 6V power supply. The grounds of all power supplies are connected to a common ground, which is connected to the frame. 
 
 ## Circuit diagram

docs/index.md

@@ -1,11 +1,10 @@
-# Welcome to the ASL Trunk robot documentation
+# Welcome to the ASL Trunk Robot documentation
 This documentation provides a detailed guide to the setup, configuration, and use of the Trunk Robot. It is intended for internal use by the team involved in the development, deployment, and maintenance of the robot.
 
-![Trunk robot](assets/trunk-closeup.jpg)
+![Trunk robot](assets/trunk-closeup.jpg){ align=right width=40% }
 
 ## Contents
-- Design: Documentation for full-system software, electrical, and mechanical design. Inlcudes BOM, CAD assets, circuit diagram, and design considerations.
-- Robot Setup: Instructions for setting up trunk hardware and software. This shall be referenced for repairs, upgrades, and new installations.
-- Usage: Description on how to use the trunk robot. 
-- Contributing: Guidelines for contributing to the development of the Trunk Robot project.
-
+- **Design**: Documentation for full-system software, electrical, and mechanical design. Inlcudes BOM, CAD assets, circuit diagram, and design considerations.
+- **Setup**: Instructions for setting up the hardware and software. This shall be referenced for repairs, upgrades, and new installations.
+- **Usage**: Description on how to use the Trunk Robot. 
+- **Contributing**: Guidelines for contributing to the development of the Trunk Robot project.

docs/mechanical_design.md

@@ -1,26 +1,28 @@
 # Mechanical Design
-The ASL Trunk robot is a low cost, highly customizable, open-source desktop soft robot hardware platform. The trunk is powered by 6 motors, which control 12 tendons that terminate at 3 disks along the length of the robot. Custom pretensioning mechanisms keep the antagonistc tendons in tension, and the actuation unit routes the tendons into the trunk. 
 
-[//]: # (TODO: self-link on this page and add citation, add BOM)
+## Description
+The ASL Trunk Robot is a low cost, highly customizable, open-source desktop soft robot platform.
+The Trunk is powered by 6 motors, which control 12 tendons that terminate at 3 disks along the length of the robot.
+Custom pretensioning mechanisms keep the antagonistc tendons in tension, and the actuation unit routes the tendons into the trunk. 
 
 ## Full BOM
 The full working bill of materials is available [here](https://docs.google.com/spreadsheets/d/1P72TMokWnYh4jPumQLBwXQ3-0UVnGI-0Cx1MCqVu7Cc/edit?usp=sharing) . 
 
 ## Full CAD
 <iframe src="https://stanford2289.autodesk360.com/shares/public/SH30dd5QT870c25f12fcd9883a938c317f7f?mode=embed" width="1024" height="768" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"  frameborder="0"></iframe>
 
-## Trunk
-The flexible body of the trunk is a standard vacuum hose, which was cut to length for our application. 3 custom 3d printed disks, which each have 12 radially symmetric channels, divide the trunk into 3 equal-length segments. At each disk, 4 tendons terminate. Each disk also has a unique arrangment of motion capture markers, so OptiTrack Motive can easily distinguish them from each other for pose estimation. A custom parallel jaw gripper, adapted from [this design](https://www.youtube.com/watch?v=Qfd0ikdnAsg), is mounted on the end effector, driven by a small servo housed within the trunk body. The jaws of the gripper are easily swappable for different applications, including carrying large amounts of weight (up to 600g).
+## Trunk Body
+The flexible body of the trunk is a standard vacuum hose, which was cut to length for our application. 3 custom 3D printed disks, which each have 12 radially symmetric channels, divide the trunk into 3 equal-length segments. At each disk, 4 tendons terminate. Each disk also has a unique arrangment of motion capture markers, so OptiTrack Motive can easily distinguish them from each other for pose estimation. A custom parallel jaw gripper, adapted from [this design](https://www.youtube.com/watch?v=Qfd0ikdnAsg), is mounted on the end effector, driven by a small servo housed within the trunk body. The jaws of the gripper are easily swappable for different applications, including carrying large amounts of weight (up to 600g).
 <iframe src="https://stanford2289.autodesk360.com/shares/public/SH30dd5QT870c25f12fcc3451d73cc86f268?mode=embed" width="1024" height="768" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"  frameborder="0"></iframe>
 
 ## Actuation Unit
-The actuation unit routes 12 tendons from their respective pretensioning mechanisms to the trunk. The main structure is a custom 3d printed mount, which connects to the frame. 6 entry holes with 6 corresponding shafts hold 12 small pulleys which route the tendons with minimal friction and no overlap. The bottom of the actuation unit has a snap-fit attachment for the top of the trunk.
+The actuation unit routes 12 tendons from their respective pretensioning mechanisms to the trunk. The main structure is a custom 3D printed mount, which connects to the frame. 6 entry holes with 6 corresponding shafts hold 12 small pulleys which route the tendons with minimal friction and no overlap. The bottom of the actuation unit has a snap-fit attachment for the top of the trunk.
 <iframe src="https://stanford2289.autodesk360.com/shares/public/SH30dd5QT870c25f12fc22629b72247d4398?mode=embed" width="1024" height="768" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"  frameborder="0"></iframe>
 
 ## Pretensioning Mechanism (PTM)
 The pretensioning mechanism is heavily inspired by [Yeshmukhametov et al., 2019](https://doi.org/10.3390/robotics8030051). A pretensioning mechanism is necessary to drive two antagonistic cables with the same motor, such that when one is pulled by the motor, the other does not go slack. Our design consists of a "sled" that passively tensions a tendon using two compression springs in series on the lower linear rail.
 <iframe src="https://stanford2289.autodesk360.com/shares/public/SH30dd5QT870c25f12fc3f4bc1ea84dd9bed?mode=embed" width="800" height="600" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"  frameborder="0"></iframe>
 
 ## Motor Assemblies
-Each motor assembly is centered around a CIM 12V motor. We use the CIM12V mount along with a custom 3d printed mount to securely attach the motor and Talon SRX controller to the frame. A custom 3d printed pulley is connected to the motor shaft using a shaft key, and the tendons are secured to the top of the pulley. The Talon encoder is mounted to the frame using a custom 3d printed mount.
-<iframe src="https://stanford2289.autodesk360.com/shares/public/SH30dd5QT870c25f12fca5cfc22cb92d7282?mode=embed" width="1024" height="768" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"  frameborder="0"></iframe>
+Each motor assembly is centered around a CIM-12V motor. We use the CIM-12V mount along with a custom 3D printed mount to securely attach the motor and Talon SRX controller to the frame. A custom 3D printed pulley is connected to the motor shaft using a shaft key, and the tendons are secured to the top of the pulley. The Talon encoder is mounted to the frame using a custom 3D printed mount.
+<iframe src="https://stanford2289.autodesk360.com/shares/public/SH30dd5QT870c25f12fca5cfc22cb92d7282?mode=embed" width="1024" height="768" allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"  frameborder="0"></iframe>

docs/software_design.md

@@ -1,11 +1,70 @@
 # Software Design
 
+## Description
+
 ## ROS Graph
+Generated using [ros2_graph](https://github.com/kiwicampus/ros2_graph/).
+
+```mermaid
+flowchart LR
+
+/turtlesim:::main
+/teleop_turtle:::node
+/turtle1cmd_vel([/turtle1cmd_vel<br>geometry_msgs/msg/Twist]):::topic
+/turtle1color_sensor([/turtle1color_sensor<br>turtlesim/msg/Color]):::bugged
+/turtle1pose([/turtle1pose<br>turtlesim/msg/Pose]):::bugged
+/clear[//clear<br>std_srvs/srv/Empty\]:::bugged
+/kill[//kill<br>turtlesim/srv/Kill\]:::bugged
+/reset[//reset<br>std_srvs/srv/Empty\]:::bugged
+/spawn[//spawn<br>turtlesim/srv/Spawn\]:::bugged
+/turtle1set_pen[//turtle1set_pen<br>turtlesim/srv/SetPen\]:::bugged
+/turtle1teleport_absolute[//turtle1teleport_absolute<br>turtlesim/srv/TeleportAbsolute\]:::bugged
+/turtle1teleport_relative[//turtle1teleport_relative<br>turtlesim/srv/TeleportRelative\]:::bugged
+/turtle1/rotate_absolute{{/turtle1/rotate_absolute<br>turtlesim/action/RotateAbsolute}}:::action
+/clear o-.-o /turtlesim
+/kill o-.-o /turtlesim
+/reset o-.-o /turtlesim
+/spawn o-.-o /turtlesim
+/turtle1set_pen o-.-o /turtlesim
+/turtle1teleport_absolute o-.-o /turtlesim
+/turtle1teleport_relative o-.-o /turtlesim
+/teleop_turtle <==> /turtle1/rotate_absolute
+/turtle1/rotate_absolute o==o /turtlesim
+/turtle1cmd_vel --> /turtlesim
+/turtlesim --> /turtle1color_sensor
+/turtlesim --> /turtle1pose
+/teleop_turtle --> /turtle1cmd_vel
+subgraph keys[<b>Keys<b/>]
+subgraph nodes[<b><b/>]
+topicb((No connected)):::bugged
+main_node:::main_node
+end
+subgraph connection[<b><b/>]
+node1:::node
+node2:::node
+node1 o-. to server .-o service[/Service<br>service/Type\]:::service
+service <-. to client .-> node2
+node1 -- publish --> topic([Topic<br>topic/Type]):::topic
+topic -- subscribe --> node2
+node1 o== to server ==o action{{/Action<br>action/Type/}}:::action
+action <== to client ==> node2
+end
+end
+classDef node opacity:0.9,fill:#2A0,stroke:#391,stroke-width:4px,color:#fff
+classDef action opacity:0.9,fill:#66A,stroke:#225,stroke-width:2px,color:#fff
+classDef service opacity:0.9,fill:#3B8062,stroke:#3B6062,stroke-width:2px,color:#fff
+classDef topic opacity:0.9,fill:#852,stroke:#CCC,stroke-width:2px,color:#fff
+classDef main opacity:0.9,fill:#059,stroke:#09F,stroke-width:4px,color:#fff
+classDef bugged opacity:0.9,fill:#933,stroke:#800,stroke-width:2px,color:#fff
+style keys opacity:0.15,fill:#FFF
+style nodes opacity:0.15,fill:#FFF
+style connection opacity:0.15,fill:#FFF
+```
 
 ## Teleoperation
 
 ### Overview
-The trunk robot is teleoperated by a user wearing an Apple Vision Pro. We designed an augmented reality app written in Swift which initializes a virtual 3d, 3-link spherical pendulum overlayed on the real-world view of the user. Once the virtual trunk is initialized, the user can calibrate the position and orientation of the virtual trunk to the hardware system. After calibration, the user can look at one of the disks on the trunk, which then lights up to denote its selection. The user can pinch their thumb and forefinger to select the disk, then the position of the virtual disk will mirror the position of their hand. The virtual disk positions can optionally be streamed over WiFi to a ROS listener, which publishes the 3d positions of the 3 disks on the trunk to the desired positions topic. A controller node subscribes to this topic and calculates the motor outputs necessary to attain that pose. The updated motor outputs are published to the motors, which causes the hardware trunk to mirror the virtual trunk. Streaming of desired trunk positions is done at 10Hz, and all of the other ROS functions run at 100Hz.
+The trunk robot can be teleoperated by a user wearing an Apple Vision Pro. We designed an augmented reality app written in Swift which initializes a virtual 3D, 3-link spherical pendulum overlayed on the real-world view of the user. Once the virtual trunk is initialized, the user can calibrate the position and orientation of the virtual trunk to the hardware system. After calibration, the user can look at one of the disks on the trunk, which then lights up to denote its selection. The user can pinch their thumb and forefinger to select the disk, then the position of the virtual disk will mirror the position of their hand. The virtual disk positions can optionally be streamed over WiFi to a ROS2 listener, which publishes the 3D positions of the 3 disks on the trunk to the desired positions topic. A controller node subscribes to this topic and calculates the motor outputs necessary to attain that pose. The updated motor outputs are published to the motors, which causes the hardware trunk to mirror the virtual trunk. Streaming of desired trunk positions is done at 10Hz, and all of the other ROS2 functions run at 100Hz.
 
 ### Swift App Design
 The Apple Vision Pro teleoperation app was written in Swift 5 using XCode Beta 16 for VisionOS 2.0 Beta. Beta versions of XCode and VisionOS were used since some functionality necessary for our app was only available in beta versions. 

mkdocs.yml

@@ -1,5 +1,5 @@
-site_name: ASL Trunk robot
-site_description: ASL Trunk robot documentation
+site_name: ASL Trunk Robot
+site_description: ASL Trunk Robot documentation
 site_url: https://stanfordasl.github.io/trunk-stack
 
 repo_url: https://github.com/StanfordASL/trunk-stack
@@ -22,7 +22,7 @@ nav:
     - Mechanical: mechanical_design.md 
     - Electrical: electrical_design.md 
     - Software: software_design.md 
-  - Robot Setup:
+  - Setup:
     - 3D Printing: 3dprinting.md 
     - OpiTrack System: optitrack.md 
   - Usage:
@@ -37,13 +37,18 @@ nav:
 
 markdown_extensions:
   - attr_list
+  - md_in_html
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+            - name: mermaid
+              class: mermaid
+              format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.arithmatex:
       generic: true
 extra_javascript: