Skip to content

Commit

Permalink
Improved ROS API (#66)
Browse files Browse the repository at this point in the history 
* Improved ROS API

* Update ROS_API.md

* clean up

* Add topic short description

* Create table

* ros api

* delete [] from type

* details type

* add DEV_GUIDE

* Update README.md

* double space bar and time between spawn

* Add comment

* update api
  • Loading branch information
@rafal-gorecki
rafal-gorecki authored Apr 17, 2024
1 parent be82e5e commit 8b25f50
Show file tree
Hide file tree
Showing 9 changed files with 264 additions and 228 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/industrial_ci.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ jobs:
- name: Leave only ROSbot tests
shell: bash
run: |
run: |
sed '/if(BUILD_TESTING)/,/endif()/d' src/diff_drive_controller/CMakeLists.txt -i
sed '/if(BUILD_TESTING)/,/endif()/d' src/imu_sensor_broadcaster/CMakeLists.txt -i
sed '/if(BUILD_TESTING)/,/endif()/d' src/micro_ros_msgs/CMakeLists.txt -i
Expand Down
46 changes: 46 additions & 0 deletions DEV_GUIDE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Developer guide

Description of useful tools and good practices to maintain code readability and reliability.

## Tools

### 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 pre-commit hooks
pre-commit run -a

# update revision
pre-commit autoupdate
```

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

### Run tests

```bash
# Run tests
colcon test

# Show results
colcon test-result --verbose
```

> [!NOTE]
> Command `colcon test` does not build the code. Remember to build your code after changes.
### Industrial CI

Download industrial package from [github](https://github.com/ros-industrial/industrial_ci/) build it and run following command to run industrial_ci tests locally.

```bash
ros2 run industrial_ci rerun_ci src/ ROS_DISTRO=humble
```
230 changes: 65 additions & 165 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,208 +2,108 @@

ROS2 packages for ROSbot XL

## ROS packages

### `rosbot_xl`

Metapackage that contains dependencies to other repositories. It is also used to define whether simulation dependencies should be used.

### `rosbot_xl_bringup`

Package that contains launch, which starts all base functionalities with the microros agent. Also configs for `robot_localization` and `laser_filters` are defined there.

### `rosbot_xl_description`

URDF model used for both simulation and as a source of transforms on physical robot. It was written to be compatible with ROS Industrial and preconfigured for ROS2 control.

Available models:

| Model | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rosbot_xl` | Final configuration of rosbot_xl with ability to attach external hardware. |
| `rosbot_xl_base` | Base of rosbot prepared to be included into preexisting configuration. Meant to be compatible with concept of ROS Industrial ability for manipulators to have interchangeable end effectors. |


### `rosbot_xl_gazebo`

Launch files for Ignition Gazebo working with ROS2 control.

### `rosbot_xl_controller`

ROS2 hardware controller for ROSbot XL. Inputs and outputs data from ROS2 control and forwards it via ROS topic to be read by microros.

### `rosbot_xl_utils`

This package contains the stable firmware version with the flash script.

## ROS API

Available in [ROS_API.md](./ROS_API.md)
You can find ROS API and detailed package description in [ROS_API.md](./ROS_API.md).

## Usage on hardware
## Prepare environment

To run the software on real ROSbot XL, also communication with Digital Board 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_xl_firmware repository](https://github.com/husarion/rosbot_xl_firmware).
1. **Install `ros-dev-tools` and `stm32flash`** (`stm32flash` is not in the ros index and should be installed manually).

## Prepare environment
```bash
sudo apt-get update
sudo apt-get install -y ros-dev-tools stm32flash
```

1. **Install `colcon`, `vsc` and `rosdep`**
```
sudo apt-get update
sudo apt-get install -y ros-dev-tools stm32flash
```
2. **Create workspace folder and clone `rosbot_xl_ros` repository.**

2. **Create workspace folder and clone `rosbot_xl_ros` repository:**
```
mkdir -p ros2_ws/src
cd ros2_ws
git clone https://github.com/husarion/rosbot_xl_ros src/
```
```bash
mkdir -p ros2_ws/src
cd ros2_ws
git clone https://github.com/husarion/rosbot_xl_ros src/
```

### Build and run on hardware

1. **Building**
```
export HUSARION_ROS_BUILD=hardware
source /opt/ros/$ROS_DISTRO/setup.bash

vcs import src < src/rosbot_xl/rosbot_xl_hardware.repos
```bash
export HUSARION_ROS_BUILD=hardware
# Remove tests from micro_ros_msgs
sed '/if(BUILD_TESTING)/,/endif()/d' src/micro_ros_msgs/CMakeLists.txt -i
source /opt/ros/$ROS_DISTRO/setup.bash
rm -r src/rosbot_xl_gazebo
vcs import src < src/rosbot_xl/rosbot_xl_hardware.repos
# Copy only diff_drive_controller and imu_sensor_broadcaster, waits for features from ros2-control
cp -r src/ros2_controllers/diff_drive_controller src/
cp -r src/ros2_controllers/imu_sensor_broadcaster src/
rm -rf src/ros2_controllers
# Remove tests from micro_ros_msgs
sed '/if(BUILD_TESTING)/,/endif()/d' src/micro_ros_msgs/CMakeLists.txt -i
# stm32flash is not in the ros index and should be installed manually
sudo apt install stm32flash
rm -r src/rosbot_xl_gazebo
rosdep init
rosdep update --rosdistro $ROS_DISTRO
rosdep install -i --from-path src --rosdistro $ROS_DISTRO -y
colcon build
```
# Copy only diff_drive_controller and imu_sensor_broadcaster, waits for features from ros2-control
cp -r src/ros2_controllers/diff_drive_controller src/
cp -r src/ros2_controllers/imu_sensor_broadcaster src/
rm -rf src/ros2_controllers
> [!NOTE]
> Before starting the software on the robot please make sure that you're using the latest firmware and run the `micro-ROS` agent as described in the [Usage on hardware](#usage-on-hardware) step.
rosdep init
rosdep update --rosdistro $ROS_DISTRO
rosdep install -i --from-path src --rosdistro $ROS_DISTRO -y
colcon build
```

2. **Running**

Flash firmware.
```bash
# Get admin permissions to flash firmware
sudo su
source install/setup.bash
ros2 run rosbot_xl_utils flash_firmware
exit
```

```
source install/setup.bash
ros2 launch rosbot_xl_bringup combined.launch.py
```
```bash
source install/setup.bash
ros2 launch rosbot_xl_bringup combined.launch.py
```

> [!IMPORTANT]
> Whenever the software version is changed, it is recommended to update the firmware version to ensure that the package version is compatible with the firmware version.
>
> ```bash
> sudo su # Get admin permissions to flash firmware
> source install/setup.bash
> ros2 run rosbot_xl_utils flash_firmware
> exit
> ```

### Build and run Gazebo simulation

1. **Building**
```
export HUSARION_ROS_BUILD=simulation
source /opt/ros/$ROS_DISTRO/setup.bash
vcs import src < src/rosbot_xl/rosbot_xl_hardware.repos
vcs import src < src/rosbot_xl/rosbot_xl_simulation.repos
# Remove tests from micro_ros_msgs
sed '/if(BUILD_TESTING)/,/endif()/d' src/micro_ros_msgs/CMakeLists.txt -i
# Copy only diff_drive_controller and imu_sensor_broadcaster, waits for features from ros2-control
cp -r src/ros2_controllers/diff_drive_controller src/
cp -r src/ros2_controllers/imu_sensor_broadcaster src/
rm -rf src/ros2_controllers
rosdep init
rosdep update --rosdistro $ROS_DISTRO
rosdep install -i --from-path src --rosdistro $ROS_DISTRO -y
colcon build
```

2. **Running**
```
source install/setup.bash
ros2 launch rosbot_xl_gazebo simulation.launch.py
```
## Testing package

### 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
```bash
export HUSARION_ROS_BUILD=simulation
# initialize pre-commit workspace
pre-commit install
source /opt/ros/$ROS_DISTRO/setup.bash
# manually run tests
pre-commit run -a
vcs import src < src/rosbot_xl/rosbot_xl_hardware.repos
vcs import src < src/rosbot_xl/rosbot_xl_simulation.repos
# update revision
pre-commit autoupdate
```
# Remove tests from micro_ros_msgs
sed '/if(BUILD_TESTING)/,/endif()/d' src/micro_ros_msgs/CMakeLists.txt -i
After initialization [pre-commit configuration](.pre-commit-config.yaml) will applied on every commit.
# Copy only diff_drive_controller and imu_sensor_broadcaster, waits for features from ros2-control
cp -r src/ros2_controllers/diff_drive_controller src/
cp -r src/ros2_controllers/imu_sensor_broadcaster src/
rm -rf src/ros2_controllers
### Industrial CI
```
colcon test
```
rosdep init
rosdep update --rosdistro $ROS_DISTRO
rosdep install -i --from-path src --rosdistro $ROS_DISTRO -y
colcon build
```

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

### Format python code with [Black](https://github.com/psf/black)
```
cd src/
black rosbot*
```


## Testing package

### Industrial CI
```
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:
```
colcon test-result --verbose
```
2. **Running**

### Format python code with [Black](https://github.com/psf/black)
```
cd src/
black rosbot*
```
```bash
source install/setup.bash
ros2 launch rosbot_xl_gazebo simulation.launch.py
```

## Demos

For further usage examples check out our other repositories:

* [`rosbot-xl-docker`](https://github.com/husarion/rosbot-xl-docker) - Dockerfiles for building hardware and simulation images
* [`rosbot-xl-gamepad`](https://github.com/husarion/rosbot-xl-gamepad) - simple teleoperation using a gamepad
* [`rosbot-xl-mapping`](https://github.com/husarion/rosbot-xl-mapping) - creating a map of the environment using slam_toolbox
Expand Down
Loading

0 comments on commit 8b25f50

Please sign in to comment.