Add a custom ROS2 message
If you want to use custom message in AWSIM, you need to generate the appropriate files, to do this you have to build ROS2ForUnity
yourself - please follow the steps below. Remember to start with prerequisities though.
ROS2ForUnity role
For a better understanding of the role of ROS2ForUnity
and the messages used, we encourage you to read this section.
custom_msgs
In order to simplify this tutorial, the name of the package containing the custom message is assumed to be custom_msgs
- remember to replace it with the name of your package.
Prerequisites
ROS2ForUnity
depends on a ros2cs - a C# .NET library for ROS2.
This library is already included so you don't need to install it, but there are a few prerequisites that must be resolved first.
Please select your system and resolve all prerequisites:
ros2cs
prerequisites for Ubuntu- Git - is installed - instructions can be found here.
- ROS2 version is
humble
and is located in/opt/ros/humble
- Your package with custom message is located in the home directory
~/custom_msgs
or is hosted on git repository. - Shell - commands have to be executed from the
bash
shell
-
ros2cs
prerequisites for WindowsQuestion
Tests are not working (
'charmap'
codec can't decode byte) on Windows - look at troubleshooting here -
Git - is installed - instructions can be found here
- ROS2 version is
humble
and is located inC:\ros2_humble
- Your package with custom message package is located in the home directory
C:\custom_msgs
or is hosted on git repository. - Shell - commands should be executed from the
powershell
shell
1. Workspace preparation
-
Clone
ROS2ForUnity
repository by execute command:git clone https://github.com/RobotecAI/ros2-for-unity ~/
Warning
The cloned
ROS 2 For Unity
repository must be located in the home directory~/
.git clone https://github.com/RobotecAI/ros2-for-unity /C
Warning
The cloned
ROS 2 For Unity
repository must be located in the home directoryC:\
. -
Pull dependent repositories by execute commands:
cd ~/ros2-for-unity . /opt/ros/humble/setup.bash ./pull_repositories.sh
cd C:\ros2-for-unity C:\ros2_humble\local_setup.ps1 .\pull_repositories.ps1
2. Setup custom_msgs
package
The method to add a custom package to build depends on where it is located. The package can be on your local machine or just be hosted on a git repository.
Please, choose the appropriate option and follow the instructions.
2.1. Package contained on local machine
-
Copy the
custom_msgs
package with custom message to the folder tosrc/ros2cs/custom_messages
directorycp -r ~/custom_msgs ~/ros2-for-unity/src/ros2cs/custom_messages/
Copy-Item 'C:\custom_msgs' -Destination 'C:\ros2-for-unity\src\custom_messages'
2.2. Package hosted on git repository
- Open
ros2-for-unity/ros2_for_unity_custom_messages.repos
file in editor. -
Modify the contents of the file shown below, uncomment and set:
<package_name>
- to your package name - so in this casecustom_msgs
,<repo_url>
- to repository address,<repo_branch>
- to desired branch.repositories: # src/ros2cs/custom_messages/<package_name>: # type: git # url: <repo_url> # version: <repo_branch>
Example
Below is an example of a file configured to pull 2 packages (
custom_msgs
,autoware_auto_msgs
) of messages hosted on a git repository.# NOTE: Use this file if you want to build with custom messages that reside in a separate remote repo. # NOTE: use the following format repositories: src/ros2cs/custom_messages/custom_msgs: type: git url: https://github.com/tier4/custom_msgs.git version: main src/ros2cs/custom_messages/autoware_auto_msgs: type: git url: https://github.com/tier4/autoware_auto_msgs.git version: tier4/main
-
Now pull the repositories again (also the
custom_msgs
package repository)cd ~/ros2-for-unity ./pull_repositories.sh
cd C:\ros2-for-unity .\pull_repositories.ps1
3. Build ROS 2 For Unity
Build ROS2ForUnity
with custom message packages using the following commands:
cd ~/ros2-for-unity
./build.sh --standalone
cd C:\ros2-for-unity
.\build.ps1 -standalone
4. Install custom_msgs
to AWSIM
New ROS2ForUnity
build, which you just made in step 3, contains multiple libraries that already exist in the AWSIM.
To install custom_msgs
and not copy all other unnecessary files, you should get the custom_msgs
related libraries only.
You can find them in following directories and simply copy to the analogous directories in AWSIM/Assets/Ros2ForUnity
folder, or use the script described here.
ros2-for-unity/install/asset/Ros2ForUnity/Plugins
which names matchescustom_msgs_*
ros2-for-unity/install/asset/Ros2ForUnity/Plugins/Linux/x86_64/
which names matcheslibcustom_msgs_*
ros2-for-unity/install/asset/Ros2ForUnity/Plugins
which names matchescustom_msgs_*
ros2-for-unity/install/asset/Ros2ForUnity/Plugins/Windows/x86_64/
which names matchescustom_msgs_*
Automation of copying message files
To automate the process, you can use a script that copies all files related to your custom_msgs
package.
- Create a file named
copy_custom_msgs.sh
in directory~/ros2-for-unity/
and paste the following content into it.#!/bin/bash echo "CUSTOM_MSGS_PACKAGE_NAME: $1" echo "AWSIM_DIR_PATH: $2" find ./install/asset/Ros2ForUnity/Plugins -maxdepth 1 -name "$1*" -type f -exec cp {} $2/Assets/Ros2ForUnity/Plugins \; find ./install/asset/Ros2ForUnity/Plugins/Linux/x86_64 -maxdepth 1 -name "lib$1*" -type f -exec cp {} $2/Assets/Ros2ForUnity/Plugins/Linux/x86_64 \;
- Save the file and give it executable rights with the command:
chmod a+x copy_msgs.sh
-
Run the script with two arguments:
./copy_custom_msgs.sh <CUSTOM_MSGS_PACKAGE_NAME> <AWSIM_DIR_PATH>
-
<CUSTOM_MSGS_PACKAGE_NAME>
- the first one which is the name of the package with messages - in this casecustom_msgs
, <AWSIM_DIR_PATH>
- the second which is the path to the cloned AWSIM repository.
Example
./copy_custom_msgs.sh custom_msgs ~/unity/AWSIM/
To automate the process, you can use these commands with changed:
<CUSTOM_MSGS_PACKAGE_NAME>
- the name of your package with messages - in this casecustom_msgs
,<AWSIM_DIR_PATH>
- to path to the cloned AWSIM repositoryGet-ChildItem C:\ros2-for-unity\install\asset\Ros2ForUnity\Plugins\* -Include @('<CUSTOM_MSGS_PACKAGE_NAME>*') | Copy-Item -Destination <AWSIM_DIR_PATH>\Assets\Ros2ForUnity\Plugins Get-ChildItem C:\ros2-for-unity\install\asset\Ros2ForUnity\Plugins\Windows\x86_64\* -Include @('<CUSTOM_MSGS_PACKAGE_NAME>*') | Copy-Item -Destination <AWSIM_DIR_PATH>\Assets\Ros2ForUnity\Plugins\Windows\x86_64
Example
Get-ChildItem C:\ros2-for-unity\install\asset\Ros2ForUnity\Plugins\* -Include @('custom_msgs*') | Copy-Item -Destination C:\unity\AWSIM\Assets\Ros2ForUnity\Plugins
Get-ChildItem C:\ros2-for-unity\install\asset\Ros2ForUnity\Plugins\Windows\x86_64\* -Include @('custom_msgs*') | Copy-Item -Destination C:\unity\AWSIM\Assets\Ros2ForUnity\Plugins\Windows\x86_64
5. Test
Make sure that the package files custom_msgs
have been properly copied to the AWSIM/Assets/Ros2ForUnity
.
Then try to create a message object as described in this section and check in the console of Unity Editor if it compiles without errors.