ShunkoBot Gazebo Simulation

A comprehensive simulation environment for the ShunkoBot robot using ROS2 and Gazebo, with Docker support for easy deployment and development. This project provides a complete simulation platform for the ShunkoBot robot in 3D virtual environments using Gazebo. The simulation includes:

• Full robot model with accurate physics simulation
• Navigation and mapping capabilities
• Sensor simulation (LiDAR, cameras, IMU)
• Multiple environment scenarios
• Docker containerization for cross-platform compatibility

You can run the simulation either through Docker for quick setup or using a native ROS2 workspace for development.

SLAM: Mapping the environment using Cartographer

Navigation: Path planning and localization, respectively with AMCL and Cartographer

You can watch ShunkoBot in action in simulation on Youtube, by clicking on the following image:

Table of Contents

• Project Structure
• Requirements
  • For Docker Setup (Recommended)
  • For Native ROS2 Setup
• Installation
  • Option 1: Using Docker
  • Option 2: Native ROS2 Setup
• Development
  • Building After Changes
  • Adding Custom Worlds
  • Debugging
• Contributing
• Additional Info
• License
• Contact

Project Structure

ShunkoBot_GazeboSim/
├── docker_ws/                  # Docker configuration and setup
│   └── Dockerfile              # Container definition
├── ros_ws/                     # ROS2 workspace
│   ├── src/
│   │   ├── shk_description/    # Utilities
│   │   ├── shk_simulation/     # Simulation nodes and utilities
│   │   ├── shk_navigation/     # Navigation stack configuration
│   │   └── shk_cartographer/   # SLAM configuration
│   ├── build/                  # Build artifacts
│   └── install/                # Installation files
├── Makefile                    # Build and run automation
└── README.md                   # This file

Requirements

Tested on Fedora Linux 42 (Fedora Asahi Remix on Apple Silicon M1) and on Ubuntu 22.04 on a PC with Windows 11 using WSL, using Docker in all cases.

For Docker Setup (Recommended)

• Docker with GUI support
  Ensures a consistent environment across different systems, avoiding dependency and configuration issues.
• X11 server (Linux)
  Required for GUI applications.
• 8GB+ RAM
  Recommended to allow smooth execution of containers with GUI and compute-intensive tasks.

For Native ROS2 Setup

• ROS2 Jazzy
• Ignition Gazebo (aka Gazebo since Aprile 2022)

Installation

Option 1: Using Docker

1. Clone the repository:

   git clone https://github.com/simo1101/ShunkoBot_GazeboSim.git
   cd ShunkoBot_GazeboSim

2. Start Docker service (according to your operating system):

   # Example on Fedora
   sudo systemctl start docker

3. Build the Docker image:

   make build

4. Run the simulation:

   make run

   Inside the container:

   colcon build
   source install/setup.bash

5. Launch simulation:

   ros2 launch shk_simulation shk_house.launch.py

Command	Description
make build	Build the Docker image
make run	Start a new container with GUI support
make exec	Enter an existing running container
make x11_permissions	Grant X11 permissions for GUI apps
make x11_revoke	Revoke X11 permissions
make chown_me	Fix file ownership issues
make run_colcon	Run colcon build inside the container and exit immediately

Option 2: Native ROS2 Setup

1. Clone and build:

   git clone https://github.com/simo1101/ShunkoBot_GazeboSim.git
   cd ShunkoBot_GazeboSim/ros_ws
   colcon build
   source install/setup.bash

2. Launch simulation:

   ros2 launch shk_simulation shk_house.launch.py

Development

Note

Important Development Workflow

When making changes to the codebase, always remember to:

1. Save all modified files before building
2. Run colcon build to compile your changes
3. Source the workspace with source install/setup.bash
4. Test your changes before committing

This ensures that your modifications are properly compiled and available in the ROS2 environment.

Building After Changes

After modifying any package or configuration:

# In Docker container or native setup
colcon build
source install/setup.bash

or build once and exit

# In Docker container or native setup
make run_colcon

Adding Custom Worlds

1. Place your .world files in shk_simulation/worlds/
2. Create corresponding launch files in shk_simulation/launch/
3. Rebuild the workspace

Debugging

• No GUI in Docker: Check X11 permissions with make x11_permissions
• Build errors: Ensure all dependencies are installed
• File permissions: Use make chown_me to fix ownership issues (e.g., when removing folders created as root from terminal, such as build/ or log/ after a colcon build, which are otherwise inaccessible from the file explorer).

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Commit with clear messages: git commit -m "Add feature description"
5. Push and create a Pull Request

Additional Info

If you are interested in learning more, you can find detailed explanations in the READMEs of each module and in the full project report!

License

This project is distributed under a dual-license model:

Open Source License: AGPLv3

The source code is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

You are free to:

• Use the software for personal, educational, or research purposes
• Modify and redistribute the code
• Use it commercially, as long as you comply with the AGPLv3 terms — including making any modifications publicly available

AGPLv3 requires you to release your source code even if the software is used over a network (e.g., SaaS).

---

Commercial License

If you wish to use this software in a commercial context without being bound by the terms of AGPLv3 (for example:

• incorporating it into a proprietary product,
• offering commercial services without disclosing source code,
• avoiding copyleft obligations),

a paid commercial license is available.

For commercial licensing inquiries, please contact: shunkobotstmv@gmail.com

Using this software without complying with the AGPLv3 or without a valid commercial license is strictly prohibited
and may result in legal action for copyright infringement.

---

Third-Party Code

This project includes code from:

• ROBOTIS CO., LTD.
  Copyright (c) 2019 ROBOTIS CO., LTD.

• The Cartographer Authors Copyright (c) 2016 The Cartographer Authors

• Open Source Robotics Foundation (OSRF)
  Copyright (c) 2012 Open Source Robotics Foundation

All such files retain their original license and copyright notices.
You may use these files under the terms of the Apache License 2.0.

---

Contact

For commercial licensing inquiries or any questions regarding the use of this project, please contact us at: shunkobotstmv@gmail.com

---