Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@rafal-gorecki
rafal-gorecki committed Dec 5, 2024
1 parent db0ad25 commit 482a944
Show file tree
Hide file tree
Showing 6 changed files with 261 additions and 160 deletions.
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ repos:
stages: [commit]
entry: ament_copyright
language: system
exclude: ^.*\.md$

- repo: https://github.com/PyCQA/doc8
rev: v1.1.2
Expand Down
59 changes: 59 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Developer info and tools

## USB-A connection

You can connect to the robot hardware on your own computer. To establish a connection, connect your computer to the robot using a USB-A cable. Then build the code locally and specify via the serial_port argument which processor should be used to establish the connection.

```bash
ros2 launch rosbot_bringup bringup.launch.py serial_port:=/dev/ttyUSB0
```

The hardware checks the connection via USB-A only during initialization and when btn1 or btn2 is pressed, so while executing the above command, hold down the reset button together with bnt1/bnt2 and release the reset button. After establishing a connection, you can release bnt1/bnt2.

## pre-commit

[pre-commit configuration](.pre-commit-config.yaml) prepares plenty of tests helping for developing and contributing. Usage:

```bash
# install pre-commit
pip install pre-commit

# initialize pre-commit workspace
pre-commit install

# manually run tests
pre-commit run -a
```

After initialization [pre-commit configuration](.pre-commit-config.yaml) will applied on every commit.

## Industrial CI

```bash
colcon test
```

> [!NOTE]
> Command `colcon test` does not build the code. Remember to build your code after changes.
If tests finish with errors print logs:

``` bash
colcon test-result --verbose
```


### Testing `.github/workflows/industrial_ci.yaml` Locally

At fist install [act](https://github.com/nektos/act):

```bash
cd /
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
```

And test the workflow with:

```bash
act -W .github/workflows/industrial_ci.yaml
```
169 changes: 45 additions & 124 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,35 @@
# Rosbot ROS

ROS2 packages for ROSbot 2R and ROSbot 2 PRO.
ROS 2 packages for Husarion ROSbot series.

## ROS packages
![ROSbot](https://husarion.com/assets/images/2r_colour_perspective-14e3679e451eb9fe4e79eeecf7b82e65.png)

### `rosbot`
## 📚 ROS API

Metapackage that contains dependencies to other repositories.
Documentation is available in ROS_API.md.

### `rosbot_bringup`
## 🚀 Quick Start

Package that contains launch, which starts all base functionalities. Also configuration for [robot_localization](https://github.com/cra-ros-pkg/robot_localization) and [ros2_controllers](https://github.com/ros-controls/ros2_controllers) are defined there.
### ⚙️ Prerequisites

### `rosbot_description`
1. Install all necessary tools:

URDF model used as a source of transforms on the physical robot. It was written to be compatible with ROS Industrial and preconfigured for ROS2 control.
```bash
sudo apt-get update
sudo apt-get install -y python3-pip ros-dev-tools stm32flash
```

### `rosbot_gazebo`
2. Create a workspace folder and clone the rosbot_ros repository:

Launch files for Ignition Gazebo working with ROS2 control.
```bash
mkdir -p ros2_ws
cd ros2_ws
git clone https://github.com/husarion/rosbot_ros src/rosbot_ros
```

### `rosbot_controller`
### 🤖 Hardware

ROS2 hardware controllers configuration for ROSbots.

## ROS API

Available in [ROS_API.md](./ROS_API.md)

## Usage on hardware

To run the software on real ROSbot 2R, 2 PRO, also communication with the CORE2 will be necessary.
First update your firmware to make sure that you use the latest version, then run the `micro-ROS` agent.
For detailed instructions refer to the [rosbot_ros2_firmware repository](https://github.com/husarion/rosbot_ros2_firmware).

## Source build

### Prerequisites

Install all necessary tools:

```bash
sudo apt-get update
sudo apt-get install -y python3-pip ros-dev-tools stm32flash
```

Create workspace folder and clone `rosbot_ros` repository:

```bash
mkdir -p ros2_ws
cd ros2_ws
git clone https://github.com/husarion/rosbot_ros src/rosbot_ros
```

### Build and run on hardware

Building:
#### Building

```bash
export HUSARION_ROS_BUILD_TYPE=hardware
Expand All @@ -72,25 +46,30 @@ rosdep install -i --from-path src --rosdistro $ROS_DISTRO -y
colcon build --symlink-install --packages-up-to rosbot --cmake-args -DCMAKE_BUILD_TYPE=Release
```

Flash firmware:
#### Run the Robot

```bash
sudo su
source install/setup.bash
ros2 run rosbot_utils flash_firmware
exit
```
1. Flash the firmware:

Running:
```bash
sudo su
source install/setup.bash
ros2 run rosbot_utils flash_firmware
exit
```

```bash
source install/setup.bash
ros2 launch rosbot_bringup combined.launch.py
```
> [!NOTE]
> To run the software on real ROSbots, communication with the CORE2 is required. Ensure the firmware is updated before running the micro-ROS agent. For detailed instructions, refer to the rosbot_ros2_firmware repository.

2. Launch the robot:

```bash
source install/setup.bash
ros2 launch rosbot_bringup bringup.launch.py
```

### Build and run Gazebo simulation
### 🖥️ Simulation

Building:
#### Building

```bash
export HUSARION_ROS_BUILD_TYPE=simulation
Expand All @@ -109,76 +88,18 @@ rosdep install -i --from-path src --rosdistro $ROS_DISTRO -y
colcon build --symlink-install --packages-up-to rosbot --cmake-args -DCMAKE_BUILD_TYPE=Release
```

Running:
#### Run the Simulation

```bash
source install/setup.bash
ros2 launch rosbot_gazebo simulation.launch.py
```

## Developer info

### pre-commit

[pre-commit configuration](.pre-commit-config.yaml) prepares plenty of tests helping for developing and contributing. Usage:

```bash
# install pre-commit
pip install pre-commit

# initialize pre-commit workspace
pre-commit install

# manually run tests
pre-commit run -a
```

After initialization [pre-commit configuration](.pre-commit-config.yaml) will applied on every commit.

### Industrial CI

```bash
colcon test
```

> [!NOTE]
> Command `colcon test` does not build the code. Remember to build your code after changes.
If tests finish with errors print logs:

``` bash
colcon test-result --verbose
```

### Format python code with [Black](https://github.com/psf/black)

```bash
cd src/rosbot_ros
black rosbot*
```

### Testing `.github/workflows/industrial_ci.yaml` Locally

At fist install [act](https://github.com/nektos/act):

```bash
cd /
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
```

And test the workflow with:

```bash
act -W .github/workflows/industrial_ci.yaml
```
## 🕹️ Demo

## Demo
Explore demos showcasing the capabilities of ROSbots:

Below you can find demos with ROSbots:
| link | description |
| - | - |
| [rosbot-docker](https://github.com/husarion/rosbot-docker/tree/ros2) | Simple example how to drive ROSbot with `teleop_twist_keyboard` using docker |
| [rosbot-sensors](https://github.com/husarion/rosbot-sensors) | Visualize all ROSbot sensors |
| [rosbot-gamepad](https://github.com/husarion/rosbot-gamepad) | Stream a live video from Orbbec Astra to a window on your PC. Control the robot using `teleop-twist-keyboard` |
| [rosbot-telepresence](https://github.com/husarion/rosbot-telepresence) | Stream a live video from Orbbec Astra to a window on your PC. Control the robot using `teleop-twist-keyboard` |
| [rosbot-autonomy](https://github.com/husarion/rosbot-autonomy) | A combination of `mapping` and `navigation` projects allowing simultaneous mapping and navigation in unknown environments. |
| 📎 Link | 📖 Description |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [rosbot-telepresence](https://github.com/husarion/rosbot-telepresence) | Stream live video from Orbbec Astra to a PC and control the robot using `teleop-twist-keyboard` |
| [rosbot-autonomy](https://github.com/husarion/rosbot-autonomy) | Enables simultaneous mapping and navigation, allowing the robot to move in unknown environments. |
Loading

0 comments on commit 482a944

Please sign in to comment.