sravan/RRRobot
1
0
Fork 0
mirror of https://github.com/EECS-467-W20-RRRobot-Project/RRRobot.git synced 2025-08-13 13:38:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation Updates

Browse Source 
- Add page links at the top of each website page
- Add link to draft video to home.md
- Fix links that don't point to files in the docs folder to point to file in GitHub repo
- Add instructions for using run_all.sh script to gear.md
- Add documentation.md to describe file structure and what each of the files are for
This commit is contained in:
Sravan Balaji
2020-04-27 12:35:02 -04:00
parent 271222645d
commit 1490e427bd
3 changed files with 159 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/documentation.md Normal file
View File

@@ -0,0 +1,78 @@
# Documentation <!-- omit in toc -->
## Page Links <!-- omit in toc -->
- [Home](home.md)
- [Documentation](documentation.md)
- [GEAR](gear.md)
## Table of Contents <!-- omit in toc -->
- [Directory Structure](#directory-structure)
- [docker_env](#dockerenv)
- [docs](#docs)
- [src](#src)
- [src/rrrobot_ws/src/gazebo_models](#srcrrrobotwssrcgazebomodels)
- [src/rrrobot_ws/src/rrrobot](#srcrrrobotwssrcrrrobot)
- [src/rrrobot_ws/world](#srcrrrobotwsworld)
- [utils](#utils)
## Directory Structure
In the RRRobot folder of our repository we have the following folders.
### docker_env
This contains the [docker-compose.yml](https://github.com/EECS-467-W20-RRRobot-Project/RRRobot/blob/master/docker_env/docker-compose.yml) file and folders for each docker service described in the [home](home.md) page. **gear** is the docker image used for our final simulation.
### docs
This contains the markdown files used to generate the project website pages and project documents like the poster and proposal.
### src
This contains the rrrobot_ws catkin workspace for our ROS development. Inside the `rrrobot_ws` folder is a [run_all.sh](https://github.com/EECS-467-W20-RRRobot-Project/RRRobot/blob/master/src/rrrobot_ws/run_all.sh) that will run the final simulation. See the [GEAR](gear.md) page for full instructions on using this.
In `rrrobot_ws/src`, we have a `gazebo_models` and `rrrobot` folder.
#### src/rrrobot_ws/src/gazebo_models
`gazebo_models`, as the name implies, contains 3D models we used in our testing. These include a fanuc robot arm with gripper, paper bag, plastic bottle, pop can, etc. For our final simulation, we decided to use simple cubes to represent trash (red) and recycling (green) items to make the ur10 arm's vacuum suction gripper work well. We also have the images that are passed to the CV model for classification in the `recycling_images` and `trash_images` folders. `model_mappings.txt` defines the model to use, location of image, and ground truth classification in a comma separated format.
#### src/rrrobot_ws/src/rrrobot
Our ROS package contains several folders.
`config` contains the configuration `.yaml` files that we use to overwrite ARIAC's default configuration. These files remove a bunch of the parts that we don't need and specify that we only need 1 depth camera.
`include` contains the header files for the names of topics that are used by our ROS nodes and the class definition for `ArmRepresentation`.
`launch` contains the launch file that we use to overwrite ARIAC's default launch file.
`msg` contains the definitions for the custom ROS messages used by our nodes.
`scripts` contains the bash scripts we used throughout testing. These include sending the arm to the home position, publishing a test message for the arm controller to listen to, and running the modified version of the GEAR simulation environment.
`src` contains the source code for our ROS nodes.
- `arm_controller_node.cpp` receives a pose from rrrobot_node to pick up the object, then uses inverse kinematics to determine the joint positions that will achieve the desired end-effector pose.
- `arm_representation_node.cpp` interfaces with [KDL](http://docs.ros.org/melodic/api/orocos_kdl/html/index.html) to perform inverse and forward kinematics on our ur10 robot arm model.
- `cv_model.py` uses `pytorch_pretrain_model.pt` to classify images that it receives and send the classification to rrrobot_node.
- `depth_camera_node.cpp` takes depth camera information and determines an end-effector pose for the robot arm to reach so it can pick up the object.
- `image_display.py` is a test script that uses [matplotlib](https://matplotlib.org/) to display images.
- `model_insertion_plugin.cpp` and `object_spawner_node.cpp` interface with gazebo to spawn the items in the simulation so the arm can sort them.
- `rrrobot_node.cpp` is the main node that handles interactions between the different nodes.
`test` contains some ROS nodes that we created to test forward and inverse kinematics.
`CMakeLists.txt` is used by our build system, [CMake](https://cmake.org), to build and compile our ROS package.
`package.xml` defines the metadata for our ROS package.
#### src/rrrobot_ws/world
This folder contains the world files that we use to overwrite ARIAC's defaults.
In `gear.py` we have disabled all but two of the bins as we only need to classify recycling and trash.
### utils
This contains config.xlaunch which is used by VcXsrv to automatically start the server with the desired settings (see [home](home.md) page for more information).

71
docs/gear.md
View File

@@ -1,30 +1,44 @@
# GEAR Simulation
# GEAR Simulation <!-- omit in toc -->
## Page Links <!-- omit in toc -->
- [Home](home.md)
- [Documentation](documentation.md)
- [GEAR](gear.md)
## Table of Contents <!-- omit in toc -->
- [Running GEAR Container](#running-gear-container)
- [Building & Running Simulation](#building--running-simulation)
- [Controlling Sample Environment](#controlling-sample-environment)
- [Start Competition](#start-competition)
- [Controlling Arms](#controlling-arms)
- [Running Full Simulation](#running-full-simulation)
- [Manual Process for Testing](#manual-process-for-testing)
- [Semi-Automated Process](#semi-automated-process)
## Running GEAR Container
1. Go to `docker_env` folder
1. On your local system, go to `docker_env` folder
- `cd /PATH/TO/RRRobot/docker_env`
2. Start GEAR docker container
- `docker-compose run --rm gear`
## Building & Running Sample Environment
## Building & Running Simulation
1. Source ROS Setup
- `source /opt/ros/melodic/setup.bash`
<!-- 2. Go to rrrobot_ws folder in container
- `cd /app/rrrobot_ws`
3. Build package
- `catkin_make clean`
- `catkin_make`
- `catkin_make install` -->
2. Run sample environment
- `roslaunch osrf_gear sample_environment.launch`
2. Run Simulation
- Sample Environment
- `roslaunch osrf_gear sample_environment.launch`
- See [controlling sample environment](#controlling-sample-environment) for more information.
- Final Simulation
- See [running full simulation](#running-full-simulation) for more information.
## Controlling Sample Environment
While sample environment is running, open a new terminal (see tips & tricks section of [home](./home.md)) on the running docker container. The following sections provide a brief overview of the commands that can be used to control various aspects of the simulation. For a full list, check out the [ARIAC 2019 Wiki](https://bitbucket.org/osrf/ariac/wiki/2019/tutorials/gear_interface).
While sample environment is running, open a new terminal (see tips & tricks section of [home](home.md)) on the running docker container. The following sections provide a brief overview of the commands that can be used to control various aspects of the simulation. For a full list, check out the [ARIAC 2019 Wiki](https://bitbucket.org/osrf/ariac/wiki/2019/tutorials/gear_interface).
[sample_run.sh](../rrrobot_ws/src/gear/sample_run.sh) moves arm 1 over the gasket part, picks it up, moves it to AGV1's tray, drops it, and moves back to the starting position.
[sample_run.sh](https://github.com/EECS-467-W20-RRRobot-Project/RRRobot/blob/master/src/rrrobot_ws/src/rrrobot/scripts/sample_run.sh) moves arm 1 over the gasket part, picks it up, moves it to AGV1's tray, drops it, and moves back to the starting position.
### Start Competition
@@ -32,14 +46,14 @@ While sample environment is running, open a new terminal (see tips & tricks sect
### Controlling Arms
#### Gripper
#### Gripper <!-- omit in toc -->
- Turn gripper suction on
- `rosservice call /ariac/arm1/gripper/control "enable: true"`
- Turn gripper suction off
- `rosservice call /ariac/arm1/gripper/control "enable: false"`
#### Joints
#### Joints <!-- omit in toc -->
Move `arm1` over a gasket part
@@ -86,12 +100,14 @@ rostopic pub /ariac/arm1/arm/command trajectory_msgs/JointTrajectory "{joint_
## Running Full Simulation
### Terminal 1: ARIAC Environment
### Manual Process for Testing
#### Terminal 1: ARIAC Environment <!-- omit in toc -->
- `cd /app/rrrobot_ws/src/rrrobot/scripts`
- `./rrrobot_run_no_build.sh`
### Terminal 2: Build RRRobot Package & Arm Controller Node
#### Terminal 2: Build RRRobot Package & Arm Controller Node <!-- omit in toc -->
- `cd /app/rrrobot_ws`
- `catkin_make clean`
@@ -99,25 +115,38 @@ rostopic pub /ariac/arm1/arm/command trajectory_msgs/JointTrajectory "{joint_
- `source devel/setup.bash`
- `rosrun rrrobot arm_controller_node`
### Terminal 3: CV Model
#### Terminal 3: CV Model <!-- omit in toc -->
- `cd /app/rrrobot_ws/src/rrrobot/src/`
- `python3 cv_model.py`
### Terminal 4: Depth Camera Node (for getting pick up location)
#### Terminal 4: Depth Camera Node (for getting pick up location) <!-- omit in toc -->
- `cd /app/rrrobot_ws/`
- `source devel/setup.bash`
- `rosrun rrrobot depth_camera_node`
### Terminal 5: Run the main rrrobot node
#### Terminal 5: Run the main rrrobot node <!-- omit in toc -->
- `cd /app/rrrobot_ws/`
- `source devel/setup.bash`
- `rosrun rrrobot rrrobot_node`
### Terminal 6: Run the node to spawn random objects onto the conveyor belt
#### Terminal 6: Run the node to spawn random objects onto the conveyor belt <!-- omit in toc -->
- `cd /app/rrrobot_ws/`
- `source devel/setup.bash`
- `rosrun rrrobot object_spawner_node`
### Semi-Automated Process
#### Terminal 1 <!-- omit in toc -->
In terminal 1, run the script that will build all components and run the nodes. You may need to adjust the sleep times in [run_all.sh](https://github.com/EECS-467-W20-RRRobot-Project/RRRobot/blob/master/src/rrrobot_ws/run_all.sh) based on your system's performance such that there is enough time for each component to finish before proceeding.
- `cd /app/rrrobot_ws/`
- `./run_all.sh`
#### Terminal 2 <!-- omit in toc -->
When a new item is spawned after the arm drops off the previous item, the conveyor belt must be manually started again using `rosservice call /ariac/conveyor/control "power: 100"` so that the item moves to the depth camera and the process can continue. You can do this in a new terminal since terminal 1 is running all of the simulation nodes.

42
docs/home.md
View File

@@ -1,5 +1,10 @@
# RRRobot! <!-- omit in toc -->
## Page Links <!-- omit in toc -->
- [Home](home.md)
- [Documentation](documentation.md)
- [GEAR](gear.md)
## Table of Contents <!-- omit in toc -->
- [Contributors](#contributors)
- [Documents](#documents)
@@ -8,9 +13,10 @@
- [Docker Compose Services](#docker-compose-services)
- [GUI Support](#gui-support)
- [Running Docker Containers](#running-docker-containers)
- [Gazebo Grasping Simulation (Testing)](#gazebo-grasping-simulation-testing)
- [GEAR Simulation (Final)](#gear-simulation-final)
- [Gazebo Grasping Simulation](#gazebo-grasping-simulation)
- [Tips & Tricks](#tips--tricks)
- [Source Code Documentation](#source-code-documentation)
- [GEAR Final Simulation](#gear-final-simulation)
## Contributors
@@ -31,7 +37,8 @@
1. [Project Poster](1.%20Project%20Poster.pdf)
2. [Project Proposal](2.%20Project%20Proposal.pdf)
3. [Final Project - Overleaf (Read-Only)](https://www.overleaf.com/read/ncvksrzpvbmr)
3. [Final Project Report - Overleaf (Read-Only)](https://www.overleaf.com/read/ncvksrzpvbmr)
4. [Draft Video](https://youtu.be/powEVDPQNEY)
## Introduction
@@ -39,6 +46,10 @@ Repository for UMICH EECS 467: Autonomous Robotics (W20) RRRobot! project.
To get started, you will need to install Docker on your system. Information on what Docker is, how to install it, and how to use it can be found in [Getting Started with Docker](https://sravanbalaji.com/Web%20Pages/blog_docker.html).
Once installed, you can run our final simulation by following the instructions on the [GEAR](gear.md) page.
Information about our source code can be found on the [Documentation](documentation.md) page.
## Development Guide
At this point, you should have Docker Desktop, Toolbox, or Engine setup on your host system. In this section, you will find a list of the different docker-compose services available and how to run them.
@@ -67,7 +78,7 @@ The GEAR container includes the Gazebo Environment for Agile Robotics from the A
### GUI Support
If using VcXsrv for Windows to enable GUI applications, run XLaunch using [config.xlaunch](utils/config.xlaunch). This will enable the following settings:
If using VcXsrv for Windows to enable GUI applications, run XLaunch using [config.xlaunch](https://github.com/EECS-467-W20-RRRobot-Project/RRRobot/blob/master/utils/config.xlaunch). This will enable the following settings:
- Display Settings
- Multiple Windows
@@ -91,7 +102,12 @@ libGL error: failed to load driver: swrast
As mentioned in [No libGL libraries when running Gazebo from ROS](https://github.com/microsoft/WSL/issues/3644#issuecomment-434556680), this can be resolved by disabling `No native OpenGL` in the VcXsrv configuration.
Additionally, be sure to update the `IP_ADDRESS` variable in [.env](src/.env) with your computer's IP Address to enable X forwarding.
You will need to update your environment variable with your IP Address to enable X forwarding. You can create a file called **.env** in the same directory as the docker-compose.yml file with your IP address as shown below. You can also edit the [docker-compose.yml](https://github.com/EECS-467-W20-RRRobot-Project/RRRobot/blob/master/docker_env/docker-compose.yml) to remove the dependence on the `IP_ADDRESS` environment variable.
```
# .env for docker-compose
IP_ADDRESS=<IP Address Here>
```
### Running Docker Containers
@@ -103,10 +119,10 @@ Additionally, be sure to update the `IP_ADDRESS` variable in [.env](src/.env) wi
- Other: `docker-machine env`
3. Navigate to src folder
- `cd /PATH/TO/rrrobot/src`
4. Use Docker Compose to run a service (refer to [docker-compose.yml](src/docker-compose.yml) or [Docker Compose Services](#docker-compose-services))
4. Use Docker Compose to run a service (refer to [docker-compose.yml](https://github.com/EECS-467-W20-RRRobot-Project/RRRobot/blob/master/docker_env/docker-compose.yml) or [Docker Compose Services](#docker-compose-services))
- `docker-compose run --rm <service_name>`
### Gazebo Grasping Simulation (Testing)
### Gazebo Grasping Simulation
1. Source ROS Setup
- `source /opt/ros/melodic/setup.bash`
@@ -119,10 +135,6 @@ Additionally, be sure to update the `IP_ADDRESS` variable in [.env](src/.env) wi
- `gazebo /app/rrrobot_src/world/rrrobot.world`
5. Run control and perception programs
### GEAR Simulation (Final)
Instructions for working in the GEAR Simulation can be found on the [GEAR](gear.md) page.
### Tips & Tricks
- Clear space on docker machine
@@ -131,3 +143,11 @@ Instructions for working in the GEAR Simulation can be found on the [GEAR](gear.
- `docker ps`
- Attach a new terminal to a running container
- `docker exec -it -u root <container> bash`
## Source Code Documentation
Documentation on our source code can be found on the [Documentation](documentation.md) page.
## GEAR Final Simulation
Instructions for running our final GEAR simulation can be found on the [GEAR](gear.md) page.