Installation

Learn how to install ROS 2 and set up the Genesys Robotics Framework on your system.

This guide walks you through installing ROS 2 and setting up the Genesys Robotics Framework on your system.
Follow each step carefully to ensure a smooth setup experience.

Prerequisites

1

System Requirements

Genesys is built on top of ROS 2, so your system must meet the ROS 2 requirements:

  • Operating System:
    • Ubuntu 22.04 (recommended)
    • Ubuntu 24.04 (supported)
    • Windows & macOS (partial support through containers)
  • Processor: 64-bit Intel/AMD
  • RAM: Minimum 4GB (8GB recommended)
  • Disk Space: At least 5GB free

To check your OS version:

lsb_release -a
2

Git

Git is required to clone the Genesys framework repository.

Install Git:

sudo apt install git -y

Verify:

git --version
3

Code Editor

Recommended editors:

4

Required Knowledge

Before working with Genesys, you should have a basic understanding of:

  • ROS 2 Core Concepts (nodes, topics, services, actions)
  • Python or C++ (Genesys supports both)
  • Linux terminal usage
  • Robotics basics (optional but helpful)

Installing ROS 2

1

Setup Sources & Keys

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 repository:

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 $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
2

Install ROS 2 Humble (Ubuntu 22.04)

Recommended for Genesys:

sudo apt update
sudo apt install ros-humble-desktop-full
3

Setup Environment

Source ROS 2 automatically:

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

Verify installation:

ros2 --version

Genesys Installation

This guide will walk you through the "happy path" of creating a complete ROS 2 project from scratch. In just a few minutes, you will:

  • Create a new, structured workspace.
  • Generate a ROS 2 package and a publisher node inside it.
  • Build your project with a single command.
  • Run your new node.

Let's get started!

1

Prerequisites

Before you begin, please ensure you have the following set up:

  • A ROS 2 Distribution: Genesys requires an installed ROS 2 distribution (like Humble or Iron).
  • ROS_DISTRO Environment Variable: Make sure this variable is set. You can check it with echo $ROS_DISTRO.
2

Check ROS 2 Environment

First, make sure you have a ROS 2 distribution (like Humble or Iron) sourced and the ROS_DISTRO environment variable is set. You can check it with:

echo $ROS_DISTRO

If this command doesn't print your ROS 2 version (e.g., humble), you'll need to source your ROS 2 setup file (e.g., source /opt/ros/humble/setup.bash).

3

Install the Genesys CLI

Install the framework's command-line interface using pip. The setup.py file defines the package name genesys-framework-cli.

pip install genesys-framework-cli
4

Update Your PATH

The pip command often installs executables in a local directory that isn't in your system's PATH by default. To make the genesys command available everywhere, you need to add this directory to your PATH.

Run this command to add it for your current terminal session:

export PATH="$(python3 -m site --user-base)/bin:$PATH"

For a permanent change, add this line to your shell's startup file (e.g., .bashrc or .zshrc):

echo 'export PATH="$(python3 -m site --user-base)/bin:$PATH"' >> ~/.bashrc
5

Verify Your Setup

In a new terminal, run the Genesys doctor to check that everything is configured correctly:

genesys doctor

If all checks pass with a green light, you're ready to build your first project!

6

Create a New Workspace

Now that the CLI is installed, let's create a new project workspace. This command scaffolds a standard directory structure for you.

genesys new my_robot_ws
cd my_robot_ws

This creates a my_robot_ws directory containing src/, launch/, config/, and other standard ROS 2 folders.

7

Create a Package and a Node

Next, let's generate a Python package and a simple publisher node inside it. The --with-node flag tells Genesys to create a default node right after creating the package.

genesys make pkg demo_pkg --with-node

You will be prompted to choose the type of node; the default is a publisher node. For now, go with the publisher node.

The interactive wizard will guide you. When it's done, Genesys will have automatically:

  • Created a package directory at src/demo_pkg.
  • Generated the necessary package.xml and setup.py files.
  • Created a node file at src/demo_pkg/demo_pkg/demo_pkg_node.py.
  • Registered the node as an executable in setup.py.
  • Generated a launch file at launch/demo_pkg_launch.py to run your new node.
8

Build the Workspace

With our code generated, it's time to build the project. The build command is a powerful wrapper around the standard ROS 2 tools.

genesys build

This single command runs colcon build and automatically sources the install/setup.bash file, making your new executables available in your current terminal.

9

Run Your Node

Finally, let's run the node. With Genesys, you don't need to remember which package a node belongs to.

genesys run demo_pkg_node

You should see output in your terminal as the node publishes messages. To see the messages being published, open a new terminal and run:

genesys topic echo /chatter
10

Congratulations!

You have successfully installed Genesys, created, built, and run your first ROS 2 application. You've seen how the unified CLI and auto-generation tools can significantly speed up your development workflow.