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.
- 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}/).
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
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.
We recommend using Docker Desktop for Mac.
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.
- 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.
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.
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>
bash hako-install.bash opt all
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.
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
Start ROS-TCP-ENDPOINT with the following command.
# bash launch.bash
Start the ROS2 program with the following command.
# bash run.bash tb3 TB3RoboModel
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.
Each window in this video corresponds to the following.
- Upper right: Terminal A
- Lower right: Terminal B
- Left: Unity
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.
- Provide examples of how SLAM and Nav2 work (#19)
- 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.
It is released under TOPPERS license.
The copyright holder is TOPPERS Project Hakoniwa Working Group.
Please refer to LICENSE.md for details.