diff --git a/docs/electrical_design.md b/docs/electrical_design.md index cf48751..833abad 100644 --- a/docs/electrical_design.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index 9924da1..c371857 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/mechanical_design.md b/docs/mechanical_design.md index 6eb96ba..d703c0c 100644 --- a/docs/mechanical_design.md +++ b/docs/mechanical_design.md @@ -1,7 +1,9 @@ # 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) . @@ -9,12 +11,12 @@ The full working bill of materials is available [here](https://docs.google.com/s ## Full CAD -## 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). ## 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. ## Pretensioning Mechanism (PTM) @@ -22,5 +24,5 @@ The pretensioning mechanism is heavily inspired by [Yeshmukhametov et al., 2019] ## 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. - \ No newline at end of file +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. + diff --git a/docs/software_design.md b/docs/software_design.md index de041d6..af1ac9c 100644 --- a/docs/software_design.md +++ b/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
geometry_msgs/msg/Twist]):::topic +/turtle1color_sensor([/turtle1color_sensor
turtlesim/msg/Color]):::bugged +/turtle1pose([/turtle1pose
turtlesim/msg/Pose]):::bugged +/clear[//clear
std_srvs/srv/Empty\]:::bugged +/kill[//kill
turtlesim/srv/Kill\]:::bugged +/reset[//reset
std_srvs/srv/Empty\]:::bugged +/spawn[//spawn
turtlesim/srv/Spawn\]:::bugged +/turtle1set_pen[//turtle1set_pen
turtlesim/srv/SetPen\]:::bugged +/turtle1teleport_absolute[//turtle1teleport_absolute
turtlesim/srv/TeleportAbsolute\]:::bugged +/turtle1teleport_relative[//turtle1teleport_relative
turtlesim/srv/TeleportRelative\]:::bugged +/turtle1/rotate_absolute{{/turtle1/rotate_absolute
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[Keys] +subgraph nodes[] +topicb((No connected)):::bugged +main_node:::main_node +end +subgraph connection[] +node1:::node +node2:::node +node1 o-. to server .-o service[/Service
service/Type\]:::service +service <-. to client .-> node2 +node1 -- publish --> topic([Topic
topic/Type]):::topic +topic -- subscribe --> node2 +node1 o== to server ==o action{{/Action
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. diff --git a/mkdocs.yml b/mkdocs.yml index dbf0cb2..c9bdaaf 100644 --- a/mkdocs.yml +++ b/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: