Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@SimonR99
SimonR99 committed Dec 31, 2024
1 parent 6ea0073 commit 2134934
Show file tree
Hide file tree
Showing 2 changed files with 152 additions and 125 deletions.
267 changes: 143 additions & 124 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,177 +1,196 @@
# Rove

Rove is a robot developed by the Capra team at ÉTS. Utilizing ROS2 Humble, Rove is designed for advanced applications in search and rescue robotics.

## Work in a docker container (Preferred)

Working in a dev container will allow you to have the same environment as the CI and make sure that your code will work on another computer. It will also allow you to easily switch package version and test things without breaking your computer.

### Windows docker installation

1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
2. Install [Visual Studio Code](https://code.visualstudio.com/)
3. Install Xserver (We recommend [VcXsrv](https://sourceforge.net/projects/vcxsrv/))
4. Install the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension in VSCode
5. Clone and open the repository
6. Click on the green button in the bottom left corner of VSCode and select "Remote-Containers: Reopen in Container" or use the command palette to do it.
7. Wait for the container to build
8. Start Xserver with the ```-nowgl``` option (double click on the shortcut to open it if you use VcXsrv)

### Linux docker installation

Same as the windows installation, step 3 and 8 can be skipped.

Replace the DISPLAY environment variable in the .env file
Rove is a robot developed by the Capra team at ÉTS, designed for advanced applications in search and rescue robotics using ROS2 Humble.

## Table of Contents
- [Rove](#rove)
- [Table of Contents](#table-of-contents)
- [Installation Options](#installation-options)
- [Docker Container (Recommended)](#docker-container-recommended)
- [Windows Setup](#windows-setup)
- [Linux Setup](#linux-setup)
- [Native/WSL Installation](#nativewsl-installation)
- [Running Rove](#running-rove)
- [Simulation](#simulation)
- [Real-World launch](#real-world-launch)
- [Controller Setup](#controller-setup)
- [Additional Components (Need hardware installation)](#additional-components-need-hardware-installation)
- [VectorNav](#vectornav)
- [Robotiq Gripper (Need hardware installation)](#robotiq-gripper-need-hardware-installation)
- [Foxglove Interface](#foxglove-interface)
- [Development Guide](#development-guide)
- [Each time you push to the repository, you need to ensure that black formatting is applied to all new files.](#each-time-you-push-to-the-repository-you-need-to-ensure-that-black-formatting-is-applied-to-all-new-files)
- [Adding New Packages](#adding-new-packages)
- [Updating Packages](#updating-packages)
- [Architecture](#architecture)
- [Package Structure](#package-structure)
- [Docker Architecture](#docker-architecture)

## Installation Options

### Docker Container (Recommended)

Using a dev container ensures consistent environments across development and CI/CD pipelines.

#### Windows Setup
1. Install required software:
- [Docker Desktop](https://www.docker.com/products/docker-desktop)
- [Visual Studio Code](https://code.visualstudio.com/)
- [VcXsrv](https://sourceforge.net/projects/vcxsrv/) (Xserver)
- VSCode [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension

2. Setup steps:
- Clone and open the repository
- Click the green button in VSCode's bottom left corner
- Select "Remote-Containers: Reopen in Container"
- Start Xserver with the **-nowgl** option

#### Linux Setup
Follow the same steps as Windows, excluding Xserver installation. Additionally:

1. Update DISPLAY environment variable in .env:
```bash
echo DISPLAY=$DISPLAY
```

2. Configure controller node permissions:
```bash
cat /dev/input/event0
```

**Note:** Consider [configuring Docker for non-root usage](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)

### Native/WSL Installation

Requires Ubuntu 22.04 LTS.

1. Install prerequisites:
- [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html) (use `ros-humble-desktop-full`)
- [Gazebo Harmonic](https://gazebosim.org/docs/harmonic/install_ubuntu/#binary-installation-on-ubuntu)

2. Setup workspace:
```bash
git clone https://github.com/clubcapra/rove.git
cd rove
vcs import src < rove.repos
echo "export GZ_VERSION=harmonic" >> ~/.bashrc && source ~/.bashrc
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash
```

3. (Optional) Hardware package installation:
```bash
vcs import src < rove_hw.repos
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash
```

## Running Rove

### Simulation
For WSL users:
```bash
echo DISPLAY=$DISPLAY
```

To be able to use the controller node, the user need read/write permissions on the inputs.
Example:
```bash
cat /dev/input/event0
```

**Suggestion:** Configure docker to be able to run as non-root user https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user

## Native/WSL installation (Ubuntu 22.04 LTS, other distros not supported)

To install ROS2 and vcs natively: https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html

Note: At the step `sudo apt install ros-humble-desktop` do `sudo apt install ros-humble-desktop-full` instead.

Before installing the robot software, you need to install the simulator : https://gazebosim.org/docs/harmonic/install_ubuntu/#binary-installation-on-ubuntu

```bash
git clone https://github.com/clubcapra/rove.git
cd rove
vcs import src < rove.repos
echo "export GZ_VERSION=harmonic" >> ~/.bashrc && source ~/.bashrc
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash
export LIBGL_ALWAYS_INDIRECT=0 export LIBGL_ALWAYS_SOFTWARE=1
```

If you intend to control the robot you might need to add the hardware package to the build (If you aren't sure, you probably don't need it):

Launch simulation:
```bash
vcs import src < rove_hw.repos
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash
ros2 launch rove_bringup sim.launch.py
```


## Running Rove in simulation

IF YOU ARE RUNNING IN WSL: do this command
You can also launch the simulation with Ovis using the following command:
```bash
export LIBGL_ALWAYS_INDIRECT=0 export LIBGL_ALWAYS_SOFTWARE=1
ros2 launch rove_bringup sim.launch.py with_ovis:=true
```

Do this command to run the gazebo simulation with physics enabled :
### Real-World launch

You can launch the real-world robot using the following command:
```bash
ros2 launch rove_bringup sim.launch.py
ros2 launch rove_bringup real.launch.py
```

## Running the controller with a usb cable

### Controller Setup
USB connection:
```bash
source install/setup.bash
ros2 launch rove_bringup rove_controller_usb.launch.py
```

## Running the controller with bluetooth

Bluetooth connection:
```bash
source install/setup.bash
ros2 launch rove_bringup rove_controller_bluetooth.launch.py
```

## Launch VectorNav node
### Additional Components (Need hardware installation)

#### VectorNav
```bash
ros2 launch rove_bringup vectornav.launch.py
```

## Using the Robotiq gripper
Launch the gripper controller:
#### Robotiq Gripper (Need hardware installation)
```bash
# Launch controller
ros2 launch robotiq_description robotiq_control.launch.py
```

Close the gripper (set to 1m to reduce command lenght):
```bash
# Control commands
# Close gripper
ros2 action send_goal /robotiq_gripper_controller/gripper_cmd control_msgs/action/GripperCommand "{command:{position: 1, max_effort: 1.0}}"
```

Open the gripper:
```bash
# Open gripper
ros2 action send_goal /robotiq_gripper_controller/gripper_cmd control_msgs/action/GripperCommand "{command:{position: 0, max_effort: 1.0}}"
```

View the gripper in RViz:
```bash
# View in RViz
ros2 launch robotiq_description view_gripper.launch.py
```

## Foxglove usage (user interface)
### Foxglove Interface

You can find the json configuration file in utils/ui/capra_ui.json. You need to load it into foxglove. On the device that you want to be connected (a.k.a. the jetson), you need to run the following command :
1. Install as service:
```bash
./utils/install.sh
```

2. Or launch manually:
```bash
ros2 launch rove_launch_handler launch_handler.py
```

You can make it as a service and start at boot :
Configuration file location: `utils/ui/capra_ui.json`

```bash
./utils/install.sh
```

Otherwise, to start use the user interface with a development laptop, you can run it by only launching the launchfile :
## Development Guide

### Each time you push to the repository, you need to ensure that black formatting is applied to all new files.
```bash
ros2 launch rove_launch_handler launch_handler.py
black .
```

### Adding New Packages
1. Create using ROS2 package creation commands
2. Name Rove-specific packages with `rove_` prefix
3. External packages should be added to `rove.repos`

## Adding New Packages

To add a package for Rove, create it using the ROS2 command ([Creating Your First ROS2 Package](https://docs.ros.org/en/foxy/Tutorials/Beginner-Client-Libraries/Creating-Your-First-ROS2-Package.html)). Name it starting with `rove_` to ensure Git tracking. For non-Rove specific packages, create a separate repository and add it to `rove.repos`.

## Updating Packages

Update Rove-specific packages directly in this repository. For Capra-related or external packages, update their references in `rove.repos`. Change the Git branch in `rove.repos` as needed and apply updates with `vcs import src < rove.repos`.

## Package structure

**Bringup:**
This essential package is responsible for initializing the rover in real-world settings. It activates all necessary subsidiary packages tailored for specific operational scenarios.

**Description:**
This package is specifically designed for detailing the rover's structure in URDF (Unified Robot Description Format).

**Gazebo:**
This package facilitates the simulation of the rover within the Gazebo environment, providing a virtual testing ground.

**Hardware:**
Dedicated to initializing all sensors and actuators on the rover, this package is pivotal for operational readiness. It is specifically designed for use with the actual hardware and is not suitable for development machines.

**Navigation:**
This is a wrapper package that integrates navigation functionalities, primarily based on the nav2 framework.

**NLP (Natural Language Processing):**
This package manages the deployment of the NLP server and chatbot, facilitating advanced communication and processing capabilities.

**SLAM (Simultaneous Localization and Mapping):**
This package serves as a comprehensive wrapper for SLAM operations, incorporating tools like slam_toolbox, rtab map, and sensor filters for effective environment mapping and rover localization.
### Updating Packages
- Rove packages: Update directly in repository
- External packages: Update references in `rove.repos`
- Apply updates: `vcs import src < rove.repos`

## Docker architecture
## Architecture

It's possible to run the entire project into multiple docker containers. Each container can be run independently and are built using the following structure :
### Package Structure

![Docker structure](https://www.plantuml.com/plantuml/svg/VP71Ri8m38RlUOgezwvZq8vnc3XmsLDKJkgLGEj4JbfjU_gr0QgWJHoGVjl_xtouUn-0mz1tyc3r6Ldwm8CE0wCGmOGEPNOTVFJGeZoWGsgGj46V2S6e0r0xszgZvYTZ2zqDIeDZA5huGMLtH-3Uaj6P12zlHPfawulfjpiElUemRz2VWtNHFhNhQ_qWCSbSWSSbCXUfdyOB6uscCL0O3w3ZWgzjLLURUS5BVLbMA_rPhak4jNfhLXLiomq0gjNhymfK2TigFdB2u2tLbWs9Ux1n_WEZjXJ0479qJmtihEkHGhrC_iGOl5F8_9qx4sFip0Fx1I6V4HAa922IPsMUlzyTCz5njdoNcuZT_y55jg3A2NLsBbUNOb6nxSnTy8G-M98HEXhIGoOwdINvFL8pz9tu1G00 "Docker structure")
- **Bringup**: Initializes rover in real-world settings
- **Description**: Contains URDF robot description
- **Gazebo**: Handles simulation environment
- **Navigation**: Integrates nav2 framework
- **SLAM**: Handles mapping and localization

# Documentation
### Docker Architecture
![Docker structure](https://www.plantuml.com/plantuml/svg/VP71Ri8m38RlUOgezwvZq8vnc3XmsLDKJkgLGEj4JbfjU_gr0QgWJHoGVjl_xtouUn-0mz1tyc3r6Ldwm8CE0wCGmOGEPNOTVFJGeZoWGsgGj46V2S6e0r0xszgZvYTZ2zqDIeDZA5huGMLtH-3Uaj6P12zlHPfawulfjpiElUemRz2VWtNHFhNhQ_qWCSbSWSSbCXUfdyOB6uscCL0O3w3ZWgzjLLURUS5BVLbMA_rPhak4jNfhLXLiomq0gjNhymfK2TigFdB2u2tLbWs9Ux1n_WEZjXJ0479qJmtihEkHGhrC_iGOl5F8_9qx4sFip0Fx1I6V4HAa922IPsMUlzyTCz5njdoNcuZT_y55jg3A2NLsBbUNOb6nxSnTy8G-M98HEXhIGoOwdINvFL8pz9tu1G00)

To update the UML diagram, create a new encoded link on the PlantUML website. Copy the existing UML, make your changes, and then update the Markdown file with the new link.
10 changes: 9 additions & 1 deletion src/rove_bringup/launch/sim.launch.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@ def generate_launch_description():
description='Set to "true" to use the small house world.',
)

declare_with_ovis_arg = DeclareLaunchArgument(
"with_ovis",
default_value="false",
description='Set to "true" to use Ovis.',
)

# Get the launch directory
pkg_rove_bringup = get_package_share_directory("rove_bringup")
pkg_rove_description = get_package_share_directory("rove_description")
Expand Down Expand Up @@ -153,12 +159,14 @@ def generate_launch_description():
"with_joy": "false",
"ovis_base_origin": "0.22 0 0.38 0 0 3.14",
}.items(),
condition=IfCondition(LaunchConfiguration("with_ovis")),
)

return LaunchDescription(
[
SetEnvironmentVariable("GZ_SIM_RESOURCE_PATH", model_path),
declare_small_house_arg,
declare_with_ovis_arg,
gz_sim,
gz_sim_house,
bridge,
Expand All @@ -167,6 +175,6 @@ def generate_launch_description():
spawn_rove,
common,
# human_tracker,
# ovis,
ovis,
]
)

0 comments on commit 2134934

Please sign in to comment.