Documentation

Topic	Link
Getting Started	Getting Started
Using the Simulator	Using the Simulator
Using Vehicles	Using Vehicles
Using Walkers	Using Walkers
Sensors	Sensors
Creating own maps	Creating own maps
Building from source on Linux	Building on Linux
Building from source on Windows	Building on Windows
Installing on Linux	Installing on Linux
Installing on Windows	Installing on Windows

Prerequisites

In this section, you will find essential information regarding the system requirements, software installations, and other dependencies necessary before starting the development of AGRARSENSE.

The project directory structure is as follows:

├── AGRARSENSE [root]
    └── Data (Automatically created when simulator is launched for the first time)
        ├── All data saved from the Simulator
    └── Docs
        ├── All documentation files
    └── Examples
        └── ExampleJsonFiles
        └── ROS1 Python examples
        └── ROS2 Python examples
    └── Utils
        ├── Build scripts for Agrarsense unreal project
    └── Unreal
        └── Agrarsense [Unreal project files]
            └── Content
                ├── All blueprints, models and other assets
            └── Plugins
                ├── Plugins C++ source
            └── Source
                ├── Agrarsense simulator C++ source
            ├── Compile.bat         - build script for compiling the project for Windows
            ├── OpenProject.bat     - build script for opening the project for Windows
            ├── CreatePackage.bat   - build script for creating packaged build for Windows
            ├── Update.bat          - Keep AGRARSENSE up to date

System Recommendation

9th gen Intel i5/i7/i9 or newer / 2nd gen AMD Ryzen 5/7/9 or newer
16+ GB RAM or more
NVIDIA RTX 3070/3080 or newer / AMD RX 6700 XT or newer
150+ GB disk space for source version
Ubuntu 20.04 / Windows 10 / Windows 11

Quick Guide

Install Unreal Engine 5.3 from Epic Games launcher or follow Unreal Engine section to install AGRARSENSE fork of the Engine.
Clone AGRARSENSE repository

git clone https://AMKFrostBit@dev.azure.com/AMKFrostBit/AGRARSENSE/_git/Agrarsense

Compile and open the project:

# Right click Agrarsense.uproject and click "Generate Visual Studio Project files"

# double click OpenProject.bat which compiles the project and then opens it in the Unreal Editor

Optional: Install ROS, follow ROS related installations section

Unreal related installations

Visual Studio

Get the Visual Studio 2022 from here. Choose Community for the free version. If you own Visual Studio Professional licence then use that instead. Use the Visual Studio Installer to install following elements:

__.NET dekstop Development. . In the Workloads section, choose __.NET dekstop Development__
Universal Wndows Platform Development. . In the Workloads section, choose __Universal Wndows Platform Development
Desktop development with C++. In the Workloads section, choose __Desktop development with C++
Game development with C++. In the Workloads section, choose __Game development with C++

You also need .NET 6.0 SDK, this might already be installed or may come installed with Visual Studio but in case it's not, .NET 6.0 SDK can be downloaded from Microsoft website Windows x64 installer

Unreal Engine

You can either install Unreal Engine 5.3 from Epic Games launcher, or you can install our fork of the Unreal Engine which is preferred.

We have made our own fork of the Unreal Engine where we have made few optimizations to the engine to improve sensors performance.

Note. Compiling engine from source takes ~1-5 hours depending on your hardware. If are just testing the Simulator quickly, download Unreal Engine 5.3 from the Epic Games launcher to save time and skip to Part Two: Build AGRARSENSE

To install our fork of the engine, you need to have a GitHub account linked to Unreal Engine's account.

To build the modified version of Unreal Engine:

1. Clone the repository

git clone -b AGRARSENSE https://github.com/frostbitunreal/unrealengine C:\UnrealEngine

Note: If you clone the engine to other than C:\UnrealEngine, you need to modify Compile.bat, OpenProject.bat and Package.bat scripts because these scripts assume the engine is located in C:\UnrealEngine. If you are using Unreal Engine from Epic Games launcher then you don't need to do anything.

2. Navigate to cloned folder:

cd C:\UnrealEngine

3. Run the configuration scripts::

Setup.bat && GenerateProjectFiles.bat

4. Compile the modified engine:

>1. Open the UE5.sln file inside the source folder with Visual Studio 2019.

>2. In the build bar ensure that you have selected 'Development Editor' and 'Win64' options.

>3. In the solution explorer, right-click UE5 and select Build.

Clone & Build AGRARSENSE

1. Clone the repository

git clone https://AMKFrostBit@dev.azure.com/AMKFrostBit/AGRARSENSE/_git/Agrarsense

2. Navigate to AGRARSENSE Unreal project folder (Command Prompt and File Explorer)

cd Agrarsense/Unreal/Agrarsense/

3. Generate Visual Studio project files

Right click Agrarsense.uproject file and click Generate Visual studio project files. Click yes to any prompts.

4. Build AGRARSENSE

To compile and open the Unreal Editor with one command. Requires Unreal Engine and Visual Studio 2022 to be installed.

OpenProject.bat

This .bat script can be started either by double clicking it or running it from command line.

Alternatively if you just want to compile the C++ source and plugins:

Compile.bat

ROS related installations

Installing Ubuntu WSL on Windows

Ubuntu WSL is required for the project to be able to communicate between Unreal Engine and ROS.

AGRARSENSE Unreal project will work without a ROS installation but you cannot get or send any data to or from the simulator.

WSL can be installed either from the Microsoft Store (as of November 2022), or from the command line. If installing from the command line won't work, try installing from the Microsoft Store.

Install Ubuntu WSL by putting this command in command prompt.

```sh
wsl --install -d Ubuntu-20.04
```

You can now Launch Ubuntu WLS from start menu or with wsl command to command prompt

Install ROS noetic on WSL Ubuntu

When WSL installation is ready, follow this guide to install ROS.

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
 
sudo apt install curl
 
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
 
sudo apt update
 
sudo apt install ros-noetic-desktop-full -y
 
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
 
source ~/.bashrc

Install ROSBridge on WSL Ubuntu

https://github.com/code-iai/ROSIntegration states this:

The recommended way to install rosbridge is from source (requires the rosauth package) – Even though you could install rosbridge using apt, there have been numersous issues where these apt packages do not reflect the code in the ros1 branch. Hence, it is best to install from source.

Install from apt packages:

sudo apt-get install ros-noetic-rosauth
sudo apt-get install ros-noetic-rosbridge-suite
echo "alias ROS1='source /opt/ros/noetic/setup.bash'" >> ~/.bashrc

When launching ROS server, you can either launch it manually from Ubuntu WSL Terminal

roslaunch rosbridge_server rosbridge_tcp.launch bson_only_mode:=True

or in windows terminal

wsl -e bash -lic "roslaunch rosbridge_server rosbridge_tcp.launch bson_only_mode:=True

To run python scripts with ROS connection you need to install Python ROS packages:

sudo apt install python3-pip
pip install --extra-index-url https://rospypi.github.io/simple/ rospy
pip install --extra-index-url https://rospypi.github.io/simple/ tf2_ros

If connection doesn't go through from windows to Ubuntu WSL, you need to set **"ROS_IP"** in command prompt.

set ROS_IP=192.168.x.x

When ROS is installed follow this guide to install ROS2 (Foxy).

First, you need to install ROS2 without ros1_bridge.

First Launch new terminal and do following:

locale  # check for UTF-8
 
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
locale  # verify settings

sudo apt install software-properties-common

sudo add-apt-repository universe

sudo apt update && sudo apt install curl

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

sudo apt update && sudo apt install -y \
  libbullet-dev \
  python3-pip \
  python3-pytest-cov \
  ros-dev-tools
 
python3 -m pip install -U \
  argcomplete \
  flake8-blind-except \
  flake8-builtins \
  flake8-class-newline \
  flake8-comprehensions \
  flake8-deprecated \
  flake8-docstrings \
  flake8-import-order \
  flake8-quotes \
  pytest-repeat \
  pytest-rerunfailures \
  pytest
  
sudo apt install --no-install-recommends -y \
  libasio-dev \
  libtinyxml2-dev
  
sudo apt install --no-install-recommends -y \
  libcunit1-dev

mkdir -p ~/ros2_foxy/src
cd ~/ros2_foxy
vcs import --input https://raw.githubusercontent.com/ros2/ros2/foxy/ros2.repos src

sudo apt upgrade

sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -y --skip-keys "fastcdr rti-connext-dds-5.3.1 urdfdom_headers"

cd ~/ros2_foxy/

colcon build --symlink-install --packages-skip ros1_bridge

After ROS2 is build from source (without ros1_bridge), You need to 'source' both ROS1 and ROS2.

source /opt/ros/noetic/setup.bash

source ~/ros2_foxy/install/setup.bash

then build only ros1_bridge

cd ~/ros2_foxy/

colcon build --symlink-install --packages-select ros1_bridge --cmake-force-configure

NOTE: To use ROS1 rosbridge_server, you shouldn't add both ROS1 and ROS2 to ~.bashrc, since it mixes the packages. Instead, use ROS1 as intended and source ROS2 ONLY when needed

echo "alias ROS2='source ~/ros2_foxy/install/setup.bash'" >> ~/.bashrc

By typing ROS2 in terminal, it sources the ROS2 bash file and removes ROS2 alias

Custom ROS Messages

Clone AGRARSENSE ROS messages
cd ..

git clone https://AMKFrostBit@dev.azure.com/AMKFrostBit/AGRARSENSE/_git/AGRARSENSE_ROS_Messages
Build ROS1 messages

Type "ROS1" to launch ros2 build bash. (Alias made earlier in .bashrc)

ROS1
cd ~/AGRARSENSE_ROS_Messages/ros1ws/
catkin_make

when the ROS1 build is finished close the wsl windows

Open New Terminal

Type "ROS2" to launch ros2 build bash. (Alias made earlier in .bashrc)

ROS2
cd ~/AGRARSENSE_ROS_Messages/ros2ws/
colcon build

when the ROS2 build is finished close the wsl windows

Rebuild ROS1_Bridge again

Launch new Terminal and Source both ROS1 and ROS2 and both workspaces:

ROS1 && ROS2
source ~/AGRARSENSE_ROS_Messages/ros1ws/devel/setup.bash
source ~/AGRARSENSE_ROS_Messages/ros2ws/install/setup.bash

Next navigate to ros2_foxy directory and rebuild bridge

cd ~/ros2_foxy/

colcon build --packages-select ros1_bridge --cmake-force-configure

After the bridge has successfully built

echo "'source ~/AGRARSENSE_ROS_Messages/ros1ws/devel/setup.bash'" >> ~/.bashrc

You should now be able to launch the ROS1 bridge that Simulator uses to communicate with ROS1.

sudo apt install python3-roslaunch
 
ROS1 && roslaunch rosbridge_server rosbridge_tcp.launch bson_only_mode:=True

Using & testing AGRARSENSE

To test everything works correctly you can the following:

Note. On Windows steps 2 and 3 might be redundant as the Simulator will attempt to launch both ROS1 and ROS2 automatically but you can also start the ROS1 and ROS2 yourself and keep the them active all the time. This allows Simulator to conencted to ROS faster.

Launch Unreal Editor with below command.

OpenProject.bat

Start ROS1 in Ubuntu WSL

roslaunch rosbridge_server rosbridge_tcp.launch bson_only_mode:=True

Start ROS1 to ROS2 Bridge with new Ubuntu WSL terminal

ROS2 && ros2 run ros1_bridge dynamic_bridge --bridge-all-topics

In Unreal Editor navigate to Content/Agrarsense/Maps/SensorShowCase and open SensorShowCaseMap
Press play
Spawn wanted sensors through the user interface
Open new Ubuntu WSL terminal and type following command to see all current ROS topics

rostopic list

if you see sensors creating new ROS topics then everything is working correctly.

Visualizing sensor output with rviz

rviz is short for ROS Visualization. It's easy way visualize ROS messages, for example camera images and Lidar pointclouds.

First follow Testing AGRARSENSE
Open new Ubuntu WSL and launch rviz

rviz

If you get 'Could not connect to any X display' error, you may need to install Xming.

First download and install Xming. After installing start the Xming program.

Now open new Windows termianl and type

ipconfig

Now go back to Ubuntu WSL terminal and type

export DISPLAY=<Windows-IP>:0.0

Where <Windows-IP> is your computer IP. For example:

export DISPLAY=192.168.1.100:0.0

After setting the IP, you should be able to launch rviz with

rviz

Now that rviz is open click 'Add' from the bottom left corner. This opens new window. In the window click 'By topic' tab. This tab should show all topics that rviz is able to visualize. For example if you have Lidar sensor active in the simulation, you should see /Agrarsense/Sensors/Lidar0/PointCloud2. Select that and click ok.
Click 'Fixed Frame' and rename it to world and you should now see Lidar sensor pointcloud being visualized.

Screenshot

Creating packaged build

To create packaged shipping build, you can either:

A. Create package without opening the Unreal Editor with following command. This script packages the project into ./Build folder

CreatePackage.bat

B. Or launch the Unreal Editor with following command and create the package in the Unreal Editor.

OpenProject.bat

Maps to include in the packaged build is defined in DefaultGame.ini file.

Modifying AGRARSENSE source

When modifying Blueprints or Widget Blueprints in Unreal Editor, simply click compile and save in the Unreal Editor as in with any Unreal project.

When modifying AGRARSENSE Unreal project C++ source or plugins C++ source, you must close the Unreal Editor, compile C++ and then open the Unreal Editor again or else changes will not take effect. This can be done with same scripts as above.

Note. Unreal Engine does support compiling C++ in Unreal Editor through Live Coding but your experience may vary depending what piece of code you work on.

To compile and open the Unreal Editor with one command:

OpenProject.bat

To just compile C++ source and plugins

Compile.bat

Compiling in Visual Studio

Open Agrarsense.sln with Visual Studio, right click Agrarsense in the Solution Explorer and click Build.

Keeping AGRARSENSE updated

To keep AGRARSENSE updated, open file explorer at Agrarsense/Unreal/Agrarsense/ and double clickUpdate.bat or open terminal at that location and type:

Update.bat

This bat script simply pulls the git repository. You can achieve the same by opening command line at Agrarsense root directory and typing git pull or use any Git GUI application such as Github Desktop and keep repository updated through it.

Table of Contents

Documentation

Prerequisites

System Recommendation

Quick Guide

Unreal related installations

Visual Studio

Unreal Engine

Clone & Build AGRARSENSE

ROS related installations

Installing Ubuntu WSL on Windows

Install ROS noetic on WSL Ubuntu

Install ROSBridge on WSL Ubuntu

Custom ROS Messages

Using & testing AGRARSENSE

Visualizing sensor output with rviz

Creating packaged build

Modifying AGRARSENSE source

Keeping AGRARSENSE updated