Version 1.2 (#45)

Humble, custom messages with custom messages, ubuntu standalone

Author: pijaro

README-UBUNTU.md

@@ -4,22 +4,48 @@ This readme contains information specific to Ubuntu 20.04. For general informati
 
 ## Building
 
+We assume that working directory is `~/ros2-for-unity` and we are using `ROS2 galactic` (replace with `foxy` or `humble` where applicable).
+
 ### Prerequisites
 
 Start with installation of dependencies. Make sure to complete each step of `ros2cs` [Prerequisites section](https://github.com/RobotecAI/ros2cs/blob/master/README-UBUNTU.md#prerequisites).
 
 ### Steps
 
-*  Clone this project.
-*  You need to source your ROS2 installation (`source /opt/ros/foxy/setup.bash`) before you proceed, for each new open terminal. It is convenient to include this command in your `~/.profile` file.
-*  Run `pull_repositories.sh`. This will pull `ros2cs` as well as your custom messages. You might be asked for gitlab credentials. Remember to **pull this repository with each update** (e.g. with `vcs pull`).
-*  Run `build.sh` script.
-    * You can build tests by adding `--with-tests` argument to `build` command.
-    * You can build with `--clean-install` to make sure your installation directory is cleaned before deploying.
-    * It invokes `colcon_build` with `--merge-install` argument to simplify libraries installation.
-    * It deploys built plugins into the Asset directory. Note that only plugins built for the current platform will be deployed (there is no cross-compilation).
-    * It prepares Unity Asset that is ready to import into your Unity project (`install/asset/` directory).
-* Run `create_unity_package.sh -u <your-path-to-unity-editor-executable>` to generate .unitypackage file in `install/unity_package`
+* Clone this project.
+    ```bash
+    git clone [email protected]:RobotecAI/ros2-for-unity.git ~/ros2-for-unity
+    ```
+* You need to source your ROS2 installation before you proceed, for each new open terminal. It is convenient to include this command in your `~/.profile` file.
+    ```bash
+    # galactic
+    . /opt/ros/galactic/setup.bash
+    ```
+* Enter `Ros2ForUnity` working directory.
+    ```bash
+    cd ~/ros2-for-unity
+    ```
+* Set up you custom messages in `ros2_for_unity_custom_messages.repos`
+* Import necessary and custom messages repositories.
+    ```bash
+    ./pull_repositories.sh
+    ```
+    > *NOTE* `pull_repositories.sh` script doesn't update already existing repositories, you have to remove `src/ros2cs` folder to re-import new versions.
+* Build `Ros2ForUnty`. You can build it in standalone or overlay mode.
+    ```bash
+    # standalone mode
+    ./build.sh --standalone
+    
+    # overlay mode
+    ./build.sh
+    ```
+    * You can add `--clean-install` flag to make sure your installation directory is cleaned before deploying.
+* Unity Asset is ready to import into your Unity project. You can find it in `install/asset/` directory.
+* (optionally) To create `.unitypackage` in `install/unity_package`
+    ```bash
+    create_unity_package.sh -u <your-path-to-unity-editor-executable>
+    ```
+    > *NOTE* Unity license is required. 
 
 ## OS-Specific usage remarks
 
@@ -30,5 +56,13 @@ Running Unity Editor through Unity Hub is also supported.
 
 ## Usage troubleshooting
 
+**No ROS environment sourced. You need to source your ROS2 (..)**
+
 * If you see `"No ROS environment sourced. You need to source your ROS2 (..)"` message in Unity3D Editor, it means your environment was not sourced properly. This could happen if you run Unity but it redirects to Hub and ignores your console environment variables (this behavior can depend on Unity3D version). In such case, run project directly with `-projectPath` or add ros2 sourcing to your `~/.profile` file (you need to re-log for it to take effect).
+
 * Keep in mind that `UnityHub` stays in the background after its first launch and Unity Editor launch without `-projectPath` will redirect to it and the Hub will start Unity Editor. Since environment variables for the process are set on launch and inherited by child processes, your sourced ros2 environment in the console launching the Editor this way won't be applied. To make sure it applies (and to change between different ros2 distributions), make sure to terminate existing UnityHub process and run it with the correct ros2 distribution sourced.
+
+**There are no errors but I can't see topics published by Ros2ForUnity**
+
+* Make sure your dds config is correct.
+* Sometimes ROS2 daemon brakes up when changing network interfaces or ROS2 version. Try to stop it forcefully (`pkill -9 _ros2_daemon`) and restart (`ros2 daemon start`).

README-WINDOWS.md

@@ -1,10 +1,10 @@
 # ROS2 For Unity - Windows 10
 
-This readme contains information specific to Window 10. For general information, please see README.md
+This readme contains information specific to Window 10. For general information, please see [README.md](README.md).
 
 ## Building
 
-We assume working directory is `C:\dev` and we are using `ROS2 foxy` (replace with `Galactic` where applicable).
+We assume that working directory is `C:\dev` and we are using `ROS2 galactic` (replace with `foxy` or `humble` where applicable).
 
 ### Prerequisites
 
@@ -15,22 +15,39 @@ It is necessary to complete all the steps for `ros2cs` [Prerequisites](https://g
 * Make sure [long paths on Windows are enabled](https://github.com/RobotecAI/ros2cs/blob/master/README-WINDOWS.md#important-notices)
 * Make sure you open [`Developer PowerShell for VS` with administrator privileges](https://github.com/RobotecAI/ros2cs/blob/master/README-WINDOWS.md#important-notices)
 * For `ros2 galactic` distribution, it is best to [create a `C:\ci\ws\install\include` directory](https://github.com/RobotecAI/ros2cs/blob/master/README-WINDOWS.md#important-notices)
-* Clone this repository.
+* Clone this project.
+  ```powershell
+  git clone [email protected]:RobotecAI/ros2-for-unity.git C:\dev\ros2-for-unity
+  ```
 * Source your ROS2 installation (`C:\dev\ros2_foxy\local_setup.ps1`) in the terminal before you proceed.
-* Run `pull_repositories.ps1`. This will pull `ros2cs` as well as your custom messages. You might be asked for github credentials.
-* Run `build.ps1` script.
-  * Optionally, you can build tests by adding `-with_tests` argument to `build` command.
+  ```
+  C:\dev\ros2_foxy\local_setup.ps1
+  ```
+* Enter `Ros2ForUnity` working directory.
+    ```powershell
+    cd C:\dev\ros2-for-unity
+    ```
+* Set up you custom messages in `ros2_for_unity_custom_messages.repos`
+* Import necessary and custom messages repositories.
+    ```powershell
+    .\pull_repositories.ps1
+    ```
+    > *NOTE* `pull_repositories.ps1` script doesn't update already existing repositories, you have to remove `src\ros2cs` folder to re-import new versions.
+* Build `Ros2ForUnty`. You can build it in standalone or overlay mode.
+    ```powershell
+    # standalone mode
+    ./build.ps1 -standalone
+    
+    # overlay mode
+    ./build.ps1
+    ```
   * You can build with `-clean_install` to make sure your installation directory is cleaned before deploying.
-  * This ivokes `colcon_build` with `--merge-install` argument to simplify libraries installation.
-  * It deploys built plugins into the Asset directory. Note that only plugins built for the current platform will be deployed (there is no cross-compilation).
-  * It prepares Unity Asset that is ready to import into your Unity project (`install/asset/` directory).
-  * Currently Windows OS supports standalone build only.
-* In order to generate `Ros2ForUnity.unitypackage` please run `create_unity_package.ps1`. Please provide path to your Unity executable when prompted.
-  * Asset can be found in `install\unity_package` directory
-  * In case your Unity license has expired, the `create_unity_package.ps1` won't throw any errors but `Ros2ForUnity.unitypackage` won't be generated too.
-* At this moment you have two valid forms of the Asset.
-  * One is available as `src\Ros2ForUnity` folder which you can simply copy to Unity3D `Assets` directory.
-  * Second one is `Ros2ForUnity.unitypackage` which you can import in Unity3D.
+* Unity Asset is ready to import into your Unity project. You can find it in `install/asset/` directory.
+* (optionally) To create `.unitypackage` in `install/unity_package`
+  ```powershell
+  create_unity_package.ps1
+  ```
+  > *NOTE* Please provide path to your Unity executable when prompted. Unity license is required. In case your Unity license has expired, the `create_unity_package.ps1` won't throw any errors but `Ros2ForUnity.unitypackage` won't be generated too.
 
 ## Build troubleshooting
 
@@ -59,7 +76,7 @@ Please execute `Set-ExecutionPolicy Bypass -Scope Process` in PS shell session t
 >     [4.469s]   C:/dev/ros2_foxy/share/rosidl_cmake/cmake/rosidl_generate_interfaces.cmake:286 (ament_execute_extensions)
 >     [4.484s]   CMakeLists.txt:16 (rosidl_generate_interfaces)
 Please reinstall `numpy` package from python by typing:
-```bash
+```powershell
 pip uninstall numpy
 pip install numpy
 ```

README.md

@@ -6,7 +6,7 @@ Advantages of this module include:
 - High performance - higher throughput and considerably lower latencies comparing to bridging solutions.
 - Your simulation entities are real ROS2 nodes / publishers / subscribers. They will behave correctly with e.g. command line tools such as `ros2 topic`. They will respect QoS settings and can use ROS2 native time.
 - The module supplies abstractions and tools to use in your Unity project, including transformations, sensor interface, a clock, spinning loop wrapped in a MonoBehavior, handling initialization and shutdown.
-- Supports all standard ROS2 messages
+- Supports all standard ROS2 messages.
 - Custom messages are generated automatically with build, using standard ROS2 way. It is straightforward to generate and use them without having to define `.cs` equivalents by hand.
 - The module is wrapped as a Unity asset.
 
@@ -16,18 +16,22 @@ Supported OSes:
 - Ubuntu 20.04 (bash)
 - Windows 10 (powershell)
 
+> **Notice:** Currently, ros2 humble is only supported on Ubuntu 20.04. You have to build it from sources since it is not available in `apt`.
+
 Supported ROS2 distributions:
 - Foxy
 - Galactic
+- Humble
 
 Supported Unity3d:
 - 2020+
 
 Older versions of Unity3d may work, but the editor executable most probably won't be detected properly by deployment script. This would require user confirmation for using unsupported version.
 
-For Windows, this asset can be prepared in standalone mode only (no ROS2 installation required on target machine, e.g. your Unity3D simulation server). All required dependencies are installed and can be used e.g. as a complete set of Unity3D plugins.
+This asset can be prepared in two flavours:
 
-For Ubuntu, this asset can be prepared in overlay mode only (assuming existing (supported) ROS2 installation on target machine). Only asset libraries and generated messages are installed.
+- standalone mode, where no ROS2 installation required on target machine, e.g. your Unity3D simulation server. All required dependencies are installed and can be used e.g. as a complete set of Unity3D plugins.
+- overlay mode, where the ROS2 installation is required on target machine. Only asset libraries and generated messages are installed therefore ROS2 instance must be sourced.
 
 ## Releases
 
@@ -37,25 +41,98 @@ You can download pre-built [releases](https://github.com/RobotecAI/ros2-for-unit
 
 ## Building
 
-Note: The project will pull `ros2cs` into the workspace, which also functions independently as it is a more general project aimed at any `C# / .Net` environment.
+> **Note:** The project will pull `ros2cs` into the workspace, which also functions independently as it is a more general project aimed at any `C# / .Net` environment.
 It has its own README and scripting, but for building the Unity Asset, please use instructions and scripting in this document instead, unless you also wish to run tests or examples for `ros2cs`.
 
 Please see OS-specific instructions:
 - [Instructions for Ubuntu 20.04](README-UBUNTU.md)
 - [Instructions for Windows 10](README-WINDOWS.md)
 
-## Usage
+## Custom messages
+
+Custom messages can be included in the build by either:
+* list them in `ros2_for_unity_custom_messages.repos` file, or
+* manually inserting them in `src/ros2cs` directory. If the folder doesn't exist, you must pull repositories first (see building steps for each OS).
 
-1. Perform building steps described in the OS-specific readme or download pre-built Unity package. Do not source ros2-for-unity nor ros2cs.
-2. Open or create Unity project.
-3. Go to Assets in the menu bar (at the top of the Unity Window).
-4. Select `Import Package` → `Custom Package`. Make sure that the asset name is Ros2ForUnity and it is directly in the Assets folder.
-5. In the file browser, select the .unitypackage file built by `create_unity_package` script (by default located in `install/unity_package`) and follow the instructions on the screen.
-6. Create a top-level object containing `ROS2UnityComponent.cs`. This is the central Monobehavior for `ROS2 For Unity` that manages all the nodes. Refer to class documentation for details.
-7. Add example script to any object in the hierarchy tab, e.g. by dragging `ROS2TalkerExample.cs` to the object in the inspector tab.
-8. Select another object in the hierarchy tab and add repeat the previous step using `ROS2ListenerExample.cs`.
-9. Once you start the project in Unity, you should be able to see two nodes talking with each other in  Unity Editor's console or use `ros2 node list` and `ros2 topic echo /chatter` to verify ros2 communication.
+## Installation
+
+1. Perform building steps described in the OS-specific readme or download pre-built Unity package. Do not source `ros2-for-unity` nor `ros2cs` project into ROS2 workspace.
+1. Open or create Unity project.
+1. Import asset into project:
+    1. copy `install/asset/Ros2ForUnity` into your project `Assets` folder, or
+    1. if you have deployed an `.unitypackage` - import it in Unity Editor by selecting `Import Package` → `Custom Package`
+
+## Usage
 
+**Prerequisites**
+
+* If your build was prepared with `--standalone` flag then you are fine, and all you have to do is run the editor
+
+otherwise
+
+* source ROS2 which matches the `Ros2ForUnity` version, then run the editor from within the very same terminal/console.
+
+**Initializing Ros2ForUnity**
+
+1. Initialize `Ros2ForUnity` by creating a "hook" object which will be your wrapper around ROS2. You have two options:
+    1. `ROS2UnityComponent` based on `MonoBehaviour` which must be attached to a `GameObject` somewhere in the scene, then:
+        ```c#
+        using ROS2;
+        ...
+        // Example method of getting component, if ROS2UnityComponent lives in different GameObject, just use different get component methods.
+        ROS2UnityComponent ros2Unity = GetComponent<ROS2UnityComponent>();
+        ```
+    1. or `ROS2UnityCore` which is a standard class that can be created anywhere
+        ```c#
+        using ROS2;
+        ...
+        ROS2UnityCore ros2Unity = new ROS2UnityCore();
+        ```
+1. Create a node. You must first check if `Ros2ForUnity` is initialized correctly:
+    ```c#
+    private ROS2Node ros2Node;
+    ...
+    if (ros2Unity.Ok()) {
+        ros2Node = ros2Unity.CreateNode("ROS2UnityListenerNode");
+    }
+    ```
+
+**Publishing messages:**
+
+1. Create publisher
+    ```c#
+    private IPublisher<std_msgs.msg.String> chatter_pub;
+    ...
+    if (ros2Unity.Ok()){
+        chatter_pub = ros2Node.CreatePublisher<std_msgs.msg.String>("chatter"); 
+    }
+    ```
+1. Send messages
+    ```c#
+    std_msgs.msg.String msg = new std_msgs.msg.String();
+    msg.Data = "Hello Ros2ForUnity!";
+    chatter_pub.Publish(msg);
+    ```
+
+**Subscribing to a topic**
+
+1. Create subscriber:
+    ```c#
+    private ISubscription<std_msgs.msg.String> chatter_sub;
+    ...
+    if (ros2Unity.Ok()) {
+        chatter_sub = ros2Node.CreateSubscription<std_msgs.msg.String>(
+            "chatter", msg => Debug.Log("Unity listener heard: [" + msg.Data + "]"));
+    }
+    ```
+
+### Examples
+
+1. Create a top-level object containing `ROS2UnityComponent.cs`. This is the central `Monobehavior` for `Ros2ForUnity` that manages all the nodes. Refer to class documentation for details.
+1. Add `ROS2TalkerExample.cs` script to the very same game object.
+1. Add `ROS2ListenerExample.cs` script to the very same game object.
+    > **Note:** Each example script looks for `ROS2UnityComponent` in its own game object. However, this is not a requirement, just example implementation.
+1. Once you start the project in Unity, you should be able to see two nodes talking with each other in  Unity Editor's console or use `ros2 node list` and `ros2 topic echo /chatter` to verify ros2 communication.
 ## Acknowledgements 
 
 Open-source release of ROS2 For Unity was made possible through cooperation with [Tier IV](https://tier4.jp). Thanks to encouragement, support and requirements driven by Tier IV the project was significantly improved in terms of portability, stability, core structure and user-friendliness.

build.ps1

@@ -13,7 +13,7 @@
 #>
 Param (
     [Parameter(Mandatory=$false)][switch]$with_tests=$false,
-    [Parameter(Mandatory=$false)][switch]$standalone=$true,
+    [Parameter(Mandatory=$false)][switch]$standalone=$false,
     [Parameter(Mandatory=$false)][switch]$clean_install=$false
 )
 
@@ -50,7 +50,7 @@ if($?) {
     Write-Host "Deploying build to $plugin_path" -ForegroundColor Green
     & "$scriptPath\deploy_unity_plugins.ps1" $plugin_path
 
-    Copy-Item -Path $scriptPath\src\Ros2ForUnity\metadata_ros2cs.xml -Destination $scriptPath\install\asset\Ros2ForUnity\Plugins\Linux\x86_64\
+    Copy-Item -Path $scriptPath\src\Ros2ForUnity\metadata_ros2cs.xml -Destination $scriptPath\install\asset\Ros2ForUnity\Plugins\Windows\x86_64\
     Copy-Item -Path $scriptPath\src\Ros2ForUnity\metadata_ros2cs.xml -Destination $scriptPath\install\asset\Ros2ForUnity\Plugins\
 } else {
     Write-Host "Ros2cs build failed!" -ForegroundColor Red

deploy_unity_plugins.ps1

@@ -18,15 +18,21 @@ if (([string]::IsNullOrEmpty($pluginDir)) -Or $args[0] -eq "--help" -Or $args[0]
 
 if (Test-Path -Path $pluginDir) {
     Write-Host "Copying plugins to to: '$pluginDir' ..."
-    (Copy-Item -verbose -Path $scriptPath\install\lib\dotnet\* -Destination ${pluginDir} 4>&1).Message
+    Get-ChildItem $scriptPath\install\lib\dotnet\ -Recurse -Exclude @('*.pdb') | Copy-Item -Destination ${pluginDir}
     Write-Host "Plugins copied to: '$pluginDir'" -ForegroundColor Green
     if(-not (Test-Path -Path $pluginDir\Windows\x86_64\)) {
         mkdir ${pluginDir}\Windows\x86_64\
     }
     Write-Host "Copying libraries to: '$pluginDir\Windows\x86_64\' ..."
-    (Copy-Item -verbose -Path $scriptPath\install\bin\*.dll -Destination ${pluginDir}\Windows\x86_64\ 4>&1).Message
-    (Copy-Item -verbose -Path $scriptPath\install\standalone\*.dll -Destination ${pluginDir}\Windows\x86_64\ 4>&1).Message
-    (Copy-Item -verbose -Path $scriptPath\install\resources\*.dll -Destination ${pluginDir}\Windows\x86_64\ 4>&1).Message
+    Get-ChildItem $scriptPath\install\bin\ -Recurse -Exclude @('*_py.dll', '*_python.dll') | Copy-Item -Destination ${pluginDir}\Windows\x86_64\
+    if(-not (Test-Path -Path $scriptPath\install\standalone\)) {
+        mkdir $scriptPath\install\standalone
+    }
+    (Copy-Item -Path $scriptPath\install\standalone\*.dll -Destination ${pluginDir}\Windows\x86_64\ 4>&1).Message
+    if(-not (Test-Path -Path $scriptPath\install\resources\)) {
+        mkdir $scriptPath\install\resources
+    }
+    (Copy-Item -Path $scriptPath\install\resources\*.dll -Destination ${pluginDir}\Windows\x86_64\ 4>&1).Message
     Write-Host "Libraries copied to '${pluginDir}\Windows\x86_64\'" -ForegroundColor Green
 } else {
     Write-Host "Plugins directory: '$pluginDir' doesn't exist. Please create it first manually." -ForegroundColor Red

deploy_unity_plugins.sh

@@ -14,7 +14,7 @@ fi
 pluginDir=$1
 
 mkdir -p  ${pluginDir}/Linux/x86_64/
-cp $SCRIPTPATH/install/lib/dotnet/* ${pluginDir}
+find install/lib/dotnet/ -maxdepth 1 -not -name "*.pdb" -type f -exec cp {} ${pluginDir} \;
 cp $SCRIPTPATH/install/standalone/* ${pluginDir}/Linux/x86_64/
-cp $SCRIPTPATH/install/lib/*.so ${pluginDir}/Linux/x86_64/
+find install/lib/ -maxdepth 1 -not -name "*_python.so" -type f -exec cp {} ${pluginDir}/Linux/x86_64/ \;
 cp $SCRIPTPATH/install/resources/*.so ${pluginDir}/Linux/x86_64/