Skip to content

Commit 7eb2868

Browse files
at669at669
authored
AIRO-355: Tutorial reorganization (#87)
* AIRO-356: Tutorial Updates (#88) * Update tutorial to Robotics menu option, ROSConnect instructions * PR feedback: IP troubleshooting, gripper value swap * Reimported niryo for completed scene * PR feedback: bring TCP-connector up to dev
1 parent 6d5c7e2 commit 7eb2868

34 files changed

Lines changed: 14108 additions & 14152 deletions

‎tutorials/pick_and_place/0_ros_setup.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Pick-and-Place Tutorial: Part 0
2+
3+
This part provides two options for setting up your ROS workspace: using Docker, or manually setting up a catkin workspace.
4+
5+
**Table of Contents**
6+
- [Option A: Use Docker](#option-a-use-docker)
7+
- [Option B: Manual Setup](#option-b-manual-setup)
8+
- [Troubleshooting](#troubleshooting)
9+
- [Resources](#resources)
10+
- [Proceed to Part 1](#proceed-to-part-1)
11+
12+
---
13+
14+
If you have not already cloned this project to your local machine, do so now:
15+
16+
```bash
17+
git clone --recurse-submodules https://github.com/Unity-Technologies/Unity-Robotics-Hub.git
18+
```
19+
20+
## Option A: Use Docker
21+
22+
> The Docker-related files (Dockerfile, setup scripts) are located in the [`docker/`](docker/) directory.
23+
24+
1. Follow the steps to install [Docker Engine](https://docs.docker.com/engine/install/) for your platform if it is not already installed.
25+
26+
1. Start the Docker daemon.
27+
> Note: The system-independent `docker info` command can verify whether or not Docker is running. This command will throw a `Server: ERROR` if the Docker daemon is not currently running, and will print the appropriate [system-wide information](https://docs.docker.com/engine/reference/commandline/info/) otherwise.
28+
29+
1. Build the provided ROS Docker image:
30+
31+
```bash
32+
cd /PATH/TO/Unity-Robotics-Hub/tutorials/pick_and_place &&
33+
git submodule update --init --recursive &&
34+
docker build -t unity-robotics:pick-and-place -f docker/Dockerfile .
35+
```
36+
37+
> Note: The provided Dockerfile uses the [ROS Melodic base Image](https://hub.docker.com/_/ros/). Building the image will install the necessary packages, copy the [provided ROS packages and submodules](ROS/) to the container, and build the catkin workspace.
38+
39+
1. Start the newly built Docker container:
40+
41+
```docker
42+
docker run -it --rm -p 10000:10000 -p 5005:5005 unity-robotics:pick-and-place
43+
```
44+
45+
When this is complete, it will print: `Successfully tagged unity-robotics:pick-and-place`. This console should open into a bash shell at the ROS workspace root, e.g. `root@8d88ed579657:/catkin_ws#`.
46+
47+
1. Source your ROS workspace:
48+
49+
```bash
50+
source devel/setup.bash
51+
```
52+
53+
The ROS workspace is now ready to accept commands!
54+
55+
---
56+
57+
## Option B: Manual Setup
58+
59+
1. Navigate to the `/PATH/TO/Unity-Robotics-Hub/tutorials/pick_and_place/ROS` directory of this downloaded repo.
60+
- This directory will be used as the [ROS catkin workspace](http://wiki.ros.org/catkin/Tutorials/using_a_workspace).
61+
- If you cloned the project and forgot to use `--recurse-submodules`, or if any submodule in this directory doesn't have content, you can run the command `git submodule update --init --recursive` to download packages for Git submodules.
62+
- Copy or download this directory to your ROS operating system if you are doing ROS operations in another machine, VM, or container.
63+
> Note: This contains the ROS packages for the pick-and-place task, including [ROS TCP Endpoint](https://github.com/Unity-Technologies/ROS-TCP-Endpoint), [Niryo One ROS stack](https://github.com/NiryoRobotics/niryo_one_ros), [MoveIt Msgs](https://github.com/ros-planning/moveit_msgs), `niryo_moveit`, and `niryo_one_urdf`.
64+
65+
1. The provided files require the following packages to be installed. ROS Melodic users should run the following commands if the packages are not already present:
66+
67+
```bash
68+
sudo apt-get update && sudo apt-get upgrade
69+
sudo apt-get install python-pip ros-melodic-robot-state-publisher ros-melodic-moveit ros-melodic-rosbridge-suite ros-melodic-joy ros-melodic-ros-control ros-melodic-ros-controllers ros-melodic-tf2-web-republisher
70+
sudo -H pip install rospkg jsonpickle
71+
```
72+
73+
ROS Noetic users should run:
74+
75+
```bash
76+
sudo apt-get update && sudo apt-get upgrade
77+
sudo apt-get install python3-pip ros-noetic-robot-state-publisher ros-noetic-moveit ros-noetic-rosbridge-suite ros-noetic-joy ros-noetic-ros-control ros-noetic-ros-controllers
78+
sudo -H pip3 install rospkg jsonpickle
79+
```
80+
81+
1. If you have not already built and sourced the ROS workspace since importing the new ROS packages, navigate to your ROS workplace, and run `catkin_make && source devel/setup.bash`. Ensure there are no errors.
82+
83+
1. The ROS parameters will need to be set to your configuration in order to allow the server endpoint to fetch values for the TCP connection, stored in `src/niryo_moveit/config/params.yaml`. From your ROS workspace, assign the ROS IP in this `yaml` file:
84+
85+
```bash
86+
echo "ROS_IP: $(hostname -I)" > src/niryo_moveit/config/params.yaml
87+
```
88+
89+
> Note: You can also manually assign this value by navigating to the `params.yaml` file and opening it for editing.
90+
91+
```yaml
92+
ROS_IP: <your ROS IP>
93+
```
94+
95+
e.g.
96+
97+
```yaml
98+
ROS_IP: 192.168.50.149
99+
```
100+
101+
The ROS workspace is now ready to accept commands!
102+
103+
---
104+
105+
## Troubleshooting
106+
- Building the Docker image may throw an `Could not find a package configuration file provided by...` exception if one or more of the directories in ROS/ appears empty. Try downloading the submodules again via `git submodule update --init --recursive`.
107+
108+
- `...failed because unknown error handler name 'rosmsg'` This is due to a bug in an outdated package version. Try running `sudo apt-get update && sudo apt-get upgrade` to upgrade packages.
109+
110+
- If the ROS TCP handshake fails (e.g. `ROS-Unity server listening...` printed on the Unity side but no `ROS-Unity Handshake received` on the ROS side), the ROS IP may not have been set correctly in the params.yaml file. Try running `echo "ROS_IP: $(hostname -I)" > src/niryo_moveit/config/params.yaml` in a terminal from your ROS workspace.
111+
112+
---
113+
114+
## Resources
115+
- [Getting started with Docker](https://docs.docker.com/get-started/)
116+
- Setting up a ROS workspace:
117+
118+
> Note: this tutorial has been tested with ROS Melodic as well as ROS Noetic.
119+
- http://wiki.ros.org/ROS/Installation
120+
- http://wiki.ros.org/ROS/Tutorials/InstallingandConfiguringROSEnvironment
121+
- http://wiki.ros.org/catkin/Tutorials/create_a_workspace
122+
123+
---
124+
125+
126+
### Proceed to [Part 1](1_urdf.md).

‎tutorials/pick_and_place/1_urdf.md‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Pick-and-Place Tutorial: Part 1
22

33
This part includes downloading and installing the Unity Editor, setting up a basic Unity scene, and importing a robot using the URDF Importer.
4-
> Note: If you are familiar with Unity and the URDF Importer, or just want to skip directly to setting up ROS, you can do so by opening Assets/Scenes/Part1Done and going directly to [Part 2](2_ros_tcp.md).
4+
> Note: If you are familiar with Unity and the URDF Importer, or just want to skip directly to setting up ROS, you can do so by opening the `Assets/Scenes/Part1Done` scene and going directly to [Part 2](2_ros_tcp.md).
55
66
**Table of Contents**
77
- [Setting up the Unity Scene](#setting-up-the-unity-scene)
@@ -13,7 +13,9 @@ This part includes downloading and installing the Unity Editor, setting up a bas
1313
---
1414

1515
## Setting up the Unity Scene
16-
1. Clone this repo to a location on your local machine:
16+
17+
1. If you have not already cloned this project to your local machine, do so now:
18+
1719
```bash
1820
git clone --recurse-submodules https://github.com/Unity-Technologies/Unity-Robotics-Hub.git
1921
```
@@ -22,28 +24,34 @@ This part includes downloading and installing the Unity Editor, setting up a bas
2224

2325
1. Go to the [Unity 2020.2 Beta website](https://unity3d.com/unity/beta/2020.2.0b9) to install this project's version of Unity: **2020.2.0b9**.
2426
25-
1. Click the "Add" button in the top right of the "Projects" tab on Unity Hub, and navigate to and select the PickAndPlaceProject directory (`./Unity-Robotics-Hub/tutorials/pick_and_place/PickAndPlaceProject/`) to add the tutorial project to your Hub.
27+
1. Click the "Add" button in the top right of the "Projects" tab on Unity Hub, and navigate to and select the PickAndPlaceProject directory within this cloned repository (`/PATH/TO/Unity-Robotics-Hub/tutorials/pick_and_place/PickAndPlaceProject/`) to add the tutorial project to your Hub.
2628
2729
![](img/hub_addproject.png)
2830
2931
1. Click the newly added project to open it.
3032
31-
5. Unity should open the project to a scene titled `EmptyScene`. If it did not, you can find it in the Project browser in the Assets/Scenes directory, and double-click to open it now.
33+
1. Unity should open the project to a scene titled `EmptyScene`. If it did not, you can find it in the Project window in the Assets/Scenes directory, and double-click to open it now.
3234
> Note: If you have some experience with Unity and would like to skip the scene setup portion, you can open the scene named `TutorialScene` now and skip ahead to [Setting up the robot](#setting-up-the-robot).
3335
3436
> Note: Only one Unity scene should be open at a time. If you see multiple scenes open in the Hierarchy view, double-click the desired scene, e.g. `Assets/Scenes/EmptyScene`, to open it and close the other scenes.
3537
36-
6. In the Unity Project window, navigate to `Assets/Prefabs`. Select the Table prefab, and click and drag it into the Hierarchy window. The table should appear in the Scene view. Then, select and drag the Target into the Hierarchy window, as well as the TargetPlacement. They should appear to sit on the table.
38+
> The Hierarchy, Scene View, Game View, Play/Pause/Step toolbar, Inspector, Project, and Console windows of the Unity Editor have been highlighted below for reference, based on the default layout. Custom Unity Editor layouts may vary slightly. A top menu bar option is available to re-open any of these windows: Window > General.
39+
![](img/0_unity.png)
40+
41+
1. In the Unity Project window, navigate to `Assets/Prefabs`. Select the Table prefab, and click and drag it into the Hierarchy window. The table should appear in the Scene view. Then, select and drag the Target into the Hierarchy window, as well as the TargetPlacement. They should appear to sit on the table.
3742
3843
![](img/1_cube.png)
3944
40-
7. Select the `Main Camera` in the Hierarchy. Move the camera to a more convenient location for viewing the robot by assigning the `Main Camera`'s Position to `(0, 1.4, -0.7)`, and the Rotation to `(45, 0, 0)` in the Inspector.
45+
46+
1. Select the `Main Camera` in the Hierarchy. Move the camera to a more convenient location for viewing the robot by assigning the `Main Camera`'s Position to `(0, 1.4, -0.7)`, and the Rotation to `(45, 0, 0)` in the Inspector, which can be found in the Transform component.
47+
48+
![](img/1_camera.png)
4149

4250
## Setting Up the Robot
4351

44-
> Note: Presumably when you opened this project, the Package Manager automatically checked out and built the URDF-Importer package for you. You can double-check this now by looking for `Packages/URDF-Importer` in the Project Browser or by opening the Package Manager window. See the [Quick Setup](../quick_setup.md) steps for adding this package to your own project.
52+
> Note: Presumably when you opened this project, the Package Manager automatically checked out and built the URDF-Importer package for you. You can double-check this now by looking for `Packages/URDF-Importer` in the Project window or by opening the Package Manager window. See the [Quick Setup](../quick_setup.md) steps for adding this package to your own project.
4553

46-
1. Open the Physics Project Settings (Edit > Project Settings > Physics) and ensure the `Solver Type` is set to `Temporal Gauss Seidel`. This prevents erratic behavior in the joints that may be caused by the default solver.
54+
1. Open the Physics Project Settings (in the top menu bar, Edit > Project Settings > Physics) and ensure the `Solver Type` is set to `Temporal Gauss Seidel`. This prevents erratic behavior in the joints that may be caused by the default solver.
4755

4856
![](img/1_physics.png)
4957

@@ -68,7 +76,7 @@ This part includes downloading and installing the Unity Editor, setting up a bas
6876

6977
> Note: Going from Unity world space to ROS world space requires a conversion. Unity's `(x,y,z)` is equivalent to the ROS `(z,-x,y)` coordinate.
7078
71-
1. On the Controller script of the top-level `niryo_one` object, set the Stiffness to `10000` ,the Damping to `100` and `Force Limit` to `1000`. Set the Speed to `30` and the Acceleration to `10`.
79+
1. Select the newly imported `niryo_one` object in the Scene Hierarchy, and from the Inspector window, find the Controller (Script) component. Set the Stiffness to `10000`, the Damping to `100` and `Force Limit` to `1000`. Set the Speed to `30` and the Acceleration to `10`.
7280
> Note: You can find information on how these parameters are used in calculations by articulation bodies by referencing [this](https://github.com/Unity-Technologies/Unity-Robotics-Hub/blob/master/tutorials/urdf_importer/urdf_appendix.md#guide-to-write-your-own-controller) technical guide for writing a custom controller. For our purposes, these settings will allow the robot to stay in position without the joints slipping.
7381
7482
![](img/1_controller.png)
@@ -79,9 +87,9 @@ This part includes downloading and installing the Unity Editor, setting up a bas
7987
8088
> Note: A controller is pre-built in the Unity URDF Importer to help showcase the movement of the Niryo. The Controller script is added to the imported URDF by default. This will add FKrobot and Joint Control components at runtime. The Controller script can be found in the project at `Assets/Packages/URDF Importer/Runtime/Controller/Controller.cs`.
8189
82-
1. Press Play. If everything imported correctly, no errors should appear in the Console window. The robot arm should stay “mounted” to the table, and nothing should fall through the floor.
90+
1. Press the Play button at the top of the Unity Editor to enter Play Mode. If everything imported correctly, no errors should appear in the Console window. The robot arm should stay “mounted” to the table, and nothing should fall through the floor.
8391
84-
> Note: Using the Controller, joints can be selected using the arrow keys. Use the left/right arrow keys to navigate through the joints, where the selected index will be highlighted in red. Use the up/down arrow keys to control the selected joint movement. The Controller script on the niryo_one object will describe the actively `Selected Index` as well as the `Joint Name`.
92+
Using the Controller, joints can be selected using the arrow keys. Use the left/right arrow keys to navigate through the joints, where the selected index will be highlighted in red. Use the up/down arrow keys to control the selected joint movement. The Controller script on the niryo_one object will describe the actively `Selected Index` as well as the `Joint Name`.
8593
8694
![](img/1_end.gif)
8795

0 commit comments

Comments
 (0)