Installing Kria Robotics Stack on Ubuntu

A superset of the Robotics Operating System (ROS 2), the Kria Robotics Stack (KRS), is a set of libraries and utilities for hardware acceleration of robotics applications on the Kria SoM family of AMD-Xilinx chips. When you think about all of the cool machine learning and AI applications the Kria KV260 has become known for, one of the natural next steps to take those applications in are into the robotics world. What can that AI/ML do when it has physical access to the work by means of motors, servos, ping sensors, and any of your other favorite robotics hardware?

The KRS libraries/utilities are the hooks for motors and hardware to be integrated into the hardware accelerated development platform. KRS enables hardware acceleration in ROS2 by means of a combination of modern C++ and High-Level Synthesis (HLS). In simplistic terms, KRS is taking something like the motor controller library on Arduino and giving it an exponential speed/power boost by running it in the programmable logic of the Kria SoM (FPGA). It is very new so the installation is very manual, which makes it worth its own project post with a quick demo.

Note: This project assumes that you already have Vivado, Vitis, & PetaLinux 2021.2 already installed (see my install guide for these here).

Install ROS 2

There are currently two releases of KRS: alpha and beta. I chose to go with KRS beta. This is important to note here as it dictates which distribution of ROS 2 that needs to be installed. KRS alpha is built on ROS Foxy Fitzroy and KRS beta is built on Rolling Ridley.

First, verify that the locale on the host machine supports UTF-8:

~$ locale

The return should look something like this:

LANG=en_US.UTF-8
LANGUAGE=
LC_CTYPE="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
LC_COLLATE="en_US.UTF-8"
LC_MONETARY="en_US.UTF-8"
LC_MESSAGES="en_US.UTF-8"
LC_PAPER="en_US.UTF-8"
LC_NAME="en_US.UTF-8"
LC_ADDRESS="en_US.UTF-8"
LC_TELEPHONE="en_US.UTF-8"
LC_MEASUREMENT="en_US.UTF-8"
LC_IDENTIFICATION="en_US.UTF-8"
LC_ALL=

Next, enable the Universe repository in the Linux host machine:

~$ sudo apt install software-properties-common
~$ sudo add-apt-repository universe

Then add the ROS 2 Rolling apt repository and authorize the ROS GPG with apt:

~$ sudo apt update && sudo apt install curl gnupg lsb-release
~$ sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

Add the ROS 2 Rolling repository to the sources list:

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

Update the apt repository now that the ROS 2 Rolling repository has been added:

~$ sudo apt update

Then install the desktop version of ROS 2 Rolling:

~$ sudo apt install ros-rolling-desktop

For troubleshooting or how to uninstall ROS 2 Rolling, see here.

Install KRS Dependencies

Start the KRS installation by installing the required dependencies for KRS:

~$ sudo apt-get -y install curl build-essential libssl-dev git wget ocl-icd-* opencl-headers python3-vcstool python3-colcon-common-extensions python3-colcon-mixin kpartx u-boot-tools pv libgazebo11-dev

This will update any of the packages that you might already have installed as well as install the ones not currently installed.

Note: these dependencies also cover KRS alpha.

Create ROS 2 Workspace

Since KRS is a superset of libraries/utilities built on top of ROS 2, create a directory for a ROS 2 workspace to build KRS in and change directories into it:

~$ mkdir -p ~/krs_ws/src
~$ cd ~/krs_ws

As a high level overview: KRS will be installed in this krs_ws directory as a ROS overlay workspace. Since ROS 2 is installed in /opt/ros/ and thus owned by root, A ROS overlay workspace is a directory that is created somewhere in the home directory such that a user can make changes to source code, compile it, and add custom packages to it (KRS in this case) is necessary.

Create KRS Repo File

Since KRS is still pretty early on in development, we do have to make our own repository source file for it. Create a new file with your text editor of choice and copy the following into it:

repositories:
  ros2/ament_lint:
    type: git
    url: https://github.com/ament/ament_lint
    version: master
  ros2/launch:
    type: git
    url: https://github.com/ros2/launch
    version: master
  ros2/gazebo_ros_pkgs:
    type: git
    url: https://github.com/ros-simulation/gazebo_ros_pkgs
    version: da14a69e79502cd08064ccd261366ff023a9162a
  
  perception/image_common:
    type: git
    url: https://github.com/ros-perception/image_common
    version: 9729de81f7dff6156f644d6152b200f687360f1f
  perception/image_pipeline:
    type: git
    url: https://github.com/ros-acceleration/image_pipeline
    version: beta
  perception/vision_opencv:
    type: git
    url: https://github.com/ros-perception/vision_opencv
    version: 7bbc5ecc232e8faf36b45efaa2b6bc979b04157f

  tracing/ros2_tracing:
    type: git
    url: https://gitlab.com/ros-tracing/ros2_tracing.git
    version: master
  tracing/tracetools_acceleration:
    type: git
    url: https://github.com/ros-acceleration/tracetools_acceleration
    version: main

  acceleration/acceleration_firmware:
    type: git
    url: https://github.com/ros-acceleration/acceleration_firmware
    version: main
  acceleration/acceleration_firmware_kv260:
    type: zip
    url: https://github.com/ros-acceleration/acceleration_firmware_kv260/releases/download/v0.9.0/acceleration_firmware_kv260.zip
  acceleration/adaptive_component:
    type: git
    url: https://github.com/ros-acceleration/adaptive_component
    version: main
  acceleration/ament_acceleration:
    type: git
    url: https://github.com/ros-acceleration/ament_acceleration
    version: main
  acceleration/ament_vitis:
    type: git
    url: https://github.com/ros-acceleration/ament_vitis
    version: beta
  acceleration/colcon-acceleration:
    type: git
    url: https://github.com/ros-acceleration/colcon-acceleration
    version: main
  acceleration/ros2_kria:
    type: git
    url: https://github.com/ros-acceleration/ros2_kria
    version: main
  acceleration/ros2acceleration:
    type: git
    url: https://github.com/ros-acceleration/ros2acceleration
    version: main
  acceleration/vitis_common:
    type: git
    url: https://github.com/ros-acceleration/vitis_common
    version: master
  acceleration/acceleration_examples:
    type: git
    url: https://github.com/ros-acceleration/acceleration_examples
    version: beta

Save the file as krs_rolling.repos in ./krs_ws or create it directly from the command line:

cat << 'EOF' > krs_rolling.repos
repositories:
  ros2/ament_lint:
    type: git
    url: https://github.com/ament/ament_lint
    version: master
  ros2/launch:
    type: git
    url: https://github.com/ros2/launch
    version: master
  ros2/gazebo_ros_pkgs:
    type: git
    url: https://github.com/ros-simulation/gazebo_ros_pkgs
    version: da14a69e79502cd08064ccd261366ff023a9162a
  
  perception/image_common:
    type: git
    url: https://github.com/ros-perception/image_common
    version: 9729de81f7dff6156f644d6152b200f687360f1f
  perception/image_pipeline:
    type: git
    url: https://github.com/ros-acceleration/image_pipeline
    version: beta
  perception/vision_opencv:
    type: git
    url: https://github.com/ros-perception/vision_opencv
    version: 7bbc5ecc232e8faf36b45efaa2b6bc979b04157f

  tracing/ros2_tracing:
    type: git
    url: https://gitlab.com/ros-tracing/ros2_tracing.git
    version: master
  tracing/tracetools_acceleration:
    type: git
    url: https://github.com/ros-acceleration/tracetools_acceleration
    version: main

  acceleration/acceleration_firmware:
    type: git
    url: https://github.com/ros-acceleration/acceleration_firmware
    version: main
  acceleration/acceleration_firmware_kv260:
    type: zip
    url: https://github.com/ros-acceleration/acceleration_firmware_kv260/releases/download/v0.9.0/acceleration_firmware_kv260.zip
  acceleration/adaptive_component:
    type: git
    url: https://github.com/ros-acceleration/adaptive_component
    version: main
  acceleration/ament_acceleration:
    type: git
    url: https://github.com/ros-acceleration/ament_acceleration
    version: main
  acceleration/ament_vitis:
    type: git
    url: https://github.com/ros-acceleration/ament_vitis
    version: beta
  acceleration/colcon-acceleration:
    type: git
    url: https://github.com/ros-acceleration/colcon-acceleration
    version: main
  acceleration/ros2_kria:
    type: git
    url: https://github.com/ros-acceleration/ros2_kria
    version: main
  acceleration/ros2acceleration:
    type: git
    url: https://github.com/ros-acceleration/ros2acceleration
    version: main
  acceleration/vitis_common:
    type: git
    url: https://github.com/ros-acceleration/vitis_common
    version: master
  acceleration/acceleration_examples:
    type: git
    url: https://github.com/ros-acceleration/acceleration_examples
    version: beta

EOF

Download KRS Beta Release

Import the KRS beta release repositories:

~/krs_ws$ vcs import src --recursive < krs_rolling.repos

This will take a few minutes depending on the configuration of the host PC.

Build KRS Workspace

To build the KRS workspace, start by sourcing the Vitis and ROS 2 environments:

~/krs_ws$ source /tools/Xilinx/Vitis/2021.2/settings64.sh
~/krs_ws$ source /opt/ros/rolling/setup.bash

Export to the system path:

~/krs_ws$ export PATH="/usr/bin":$PATH

Then use the ROS build tool, colcon, to build and install KRS (again, this will take a few minutes depending on the configuration of the host PC):

~/krs_ws$ colcon build --merge-install

I got a few warnings on the outputs, a few about unused variables which is nothing to worry about. But I did get a few warnings about obsolete headers which may cause me some heartburn in the future but we'll see. If so, I can simply install ROS Foxy Fitzroy (see installation instructions here) then create a new ROS workspace to install KRS alpha to:

~$ mkdir -p ~/krs_ws_alpha/src
~$ cd ~/krs_ws_alpha

Follow my same steps above for KRS alpha except use the following for the repo file:

cat << 'EOF' > krs_alpha.repos
repositories:
  acceleration/acceleration_firmware:
    type: git
    url: https://github.com/ros-acceleration/acceleration_firmware
    version: 0.4.0
  acceleration/acceleration_firmware_kv260:
    type: zip
    url: https://www.xilinx.com/bin/public/openDownload?filename=acceleration_firmware_kv260.zip
  acceleration/colcon-acceleration:
    type: git
    url: https://github.com/ros-acceleration/colcon-acceleration
    version: 0.3.0
  acceleration/ros2acceleration:
    type: git
    url: https://github.com/ros-acceleration/ros2acceleration
    version: 0.2.0
  acceleration/ament_vitis:
    type: git
    url: https://github.com/ros-acceleration/ament_vitis
    version: 0.5.0
  acceleration/vitis_common:
    type: git
    url: https://github.com/ros-acceleration/vitis_common
    version: 0.1.0
EOF

Then download the alpha version of KRS using the alpha repo file:

~/krs_ws_alpha$ vcs import src --recursive < krs_alpha.repos

KRS alpha should still work with Vitis and PetaLinux 2021.2 so the only difference in sourcing the environment to use it is sourcing ROS Foxy instead of ROS Rolling:

~/krs_ws_alpha$ source /tools/Xilinx/Vitis/2021.2/settings64.sh
~/krs_ws_alpha$ source /opt/ros/foxy/setup.bash

Then add to path and build alpha the same as with beta:

~/krs_ws_alpha$ export PATH="/usr/bin":$PATH
~/krs_ws_alpha$ colcon build --merge-install

It is worth noting that with KRS beta, since it's being installed on ROS2 Rolling distribution, build warnings/errors should be expected to be dynamic since Rolling is a development distribution that is updating at some regular interval.

Source Overlay

When a ROS workspace is built, a setup bash script is created that must be called when you want to use that workspace. Thus, to use KRS after installing it, call its setup bash script:

~/krs_ws$ source install/setup.bash

Read more about ROS overlays here.

But that's all for the KRS install. Next will be using KRS to build for the Kria SoM!