English | 日本語

Hakoniwa ROS Simulator

The TOPPERS Project Hokoniwa WG develops "Hakoniwa," a virtual simulation environment for the age of IoT/Cloud Robotics.

This repository provides an environment where you can quickly try simulations of ROS 2 programs on Hakoniwa.

Requirements

• Windows: Windows 10/11
  • Ubuntu 20.04 LTS on WSL2/WSLg
• Linux: Ubuntu 20.04 LTS
• MacOS: macOS Catalina ver.10.15.7

In the Windows environment, we assume that you will perform all operations on the WSL2/Linux shell. Please execute under the Windows file system (under /mnt/c/), not under the WSL2 file system (under /home/${USER}/).

Preparations

Clone this repository

The latest version is v1.1.4. See also "version information/update history" (the version number corresponds to tag/release in Git/GitHub and Docker Hub tag number.

Clone this repository with the following command in the terminal.

git clone --recursive -b v1.1.4 https://github.com/toppers/hakoniwa-ros2sim.git

Install Docker Engine

This simulator uses Docker.

Note: We experimentally try to run the simulator in native Linux environments (including WSL2). Please refer to appendix/native.md for the procedure to run in the native environment.

For Mac

We recommend using Docker Desktop for Mac.

For Windows/WSL2 and Linux

The simulator requires the Docker Engine to be installed on WSL2. If the following command outputs the same result in the terminal of WSL2, it has already been installed (the line starting with $ indicates the command to be executed).

$ which docker
/usr/bin/docker
$ service --status-all |& grep docker
 [ + ]  docker   # or " [ - ]  docker "
$ service docker status
 * Docker is running   # or " * Docker is not running "

Since the Docker Engine installation procedure is a bit complicated, we summarized it in docker/install-docker.bash in "toppersjp/hakoniwa-single_robot" repository by referring the official manual. If you have any trouble to execute this script, please follow the official manual to install Docker.
Install Docker Engine on Ubuntu | Docker Documentation

Execute as follows to install Docker with our script.

wget https://raw.githubusercontent.com/toppers/hakoniwa-single_robot/main/docker/install-docker.bash
bash install-docker.bash

If the service docker status is * Docker is not running, start Docker.

sudo service docker start

If the output is as follows, Docker is running.

 * Starting Docker: docker                           [ OK ] 

This procedure requires the user to be a member of the docker group. Otherwise, execute the following command.

sudo gpasswd -a $USER docker
sudo chgrp docker /var/run/docker.sock
sudo service docker restart

The results of the above command execution will take effect after you re-login to the terminal.

Install Unity

• Unity Hub 3.1.1 or later
• Unity Editor 2021.3.0f1
  • If you do not see this version on the "Installs > Install Editor" screen of Unity Hub, you can install it by clicking on "Unity Hub" in the Unity Dowonload Archive.

Simulator Installation Procedure

Deploy Docker images

The simulator execution environment is available as a pre-built Docker image on the Docker Hub.

https://hub.docker.com/r/toppersjp/hakoniwa-ros2sim

Execute the following command to launch Docker, pull and deploy the image.

bash docker/pull-image.bash

[Tips for Developer] There is a docker/create-image.bash for creating Docker images.

run Docker

We recommend using two terminals to run this simulator. Please change to the directory of this repository (hakoniwa-ros2sim/) on all terminals.

Start the docker container with the following command in Terminal A.

bash docker/run.bash

In a Mac environment, you need to specify the network port name (e.g., "en0") as an argument. You can check the port name with the ifconfig command.

bash docker/run.bash <port>

Install the Hakoniwa ROS environment on the launched docker container

bash hako-install.bash opt all

Open Unity project

Start Unity Hub, click "Open" in the upper right corner, and specify the following directory.

Path：ros2/unity/tb3

The following screen will be displayed when started.

And then, select "Assets/Scenes" in the "Project View" at the bottom left of the screen, and double-click the scene "Toppers_Course" at the bottom of the screen.

Then you will see the course as follows.

Simulator Running Procedure

I will illustrate the procedure with the following example.

• ROS control program: src/tb3/src/tb3ctrl.cpp
• Unity application: TB3RoboModel

Execute docker containers in both terminals A and B.

If you have terminated the Docker container on terminal A, please start it again.

bash docker/run.bash

And, on terminal B, you exec the following command.

bash docker/attach.bash

Operations on Terminal A

Start ROS-TCP-ENDPOINT with the following command.

# bash launch.bash

Operations on Terminal B

Start the ROS2 program with the following command.

# bash run.bash tb3 TB3RoboModel

Start Unity simulation.

Click the Start Simulation button in Unity and see the following startup screen.

Clicking the "Start" button on the Unity starts the Hakoniwa simulation, and TurtleBot3 begins to move.

Running

Each window in this video corresponds to the following.

• Upper right: Terminal A
• Lower right: Terminal B
• Left: Unity

Contributing

Please let us know your comments and suggestions for improvement of the "Hakoniwa ROS Simulator" in the GitHub Discussions. We also welcome Pull Requests for modification proposals.

TODO

• Provide examples of how SLAM and Nav2 work (#19)

Acknowledgments

• We thank Associate Professor Akio YOSHIOKA and undergraduate students Ryoji SUGISAKI and Akemi KIMURA of Takarazuka University school of media art in Tokyo for their cooperation in designing the Unity package for TurtleBot3
• TurtleBot3 Unity assets are based on data provided by Robotiz, Inc. We deeply appreciate their cooperation.

Licenses

It is released under TOPPERS license.
The copyright holder is TOPPERS Project Hakoniwa Working Group. Please refer to LICENSE.md for details.