Quickstart

Quickstart Guide: Your First Project

Welcome to the Genesys quickstart! 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:

1. Create a new, structured workspace.

2. Generate a ROS 2 package and a publisher node inside it.

3. Build your project with a single command.

4. Run your new node.

Let's get started!

Prerequisites

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

1. A ROS 2 Distribution: Genesys requires an installed ROS 2 distribution (like Humble or Iron).

2. ROS_DISTRO Environment Variable: Make sure this variable is set. You can check it with echo $ROS_DISTRO.

Let's get started!

Step 1: Installation and Setup

Before you can create a project, you need to install the Genesys CLI and ensure your environment is correctly configured.

1. 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).

2. 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

3. 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

4. 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!

---

Step 2: 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.

Step 3: 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.

Step 4: 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.

Step 5: 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

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.

Next Steps

• Explore the Generated Code: Open src/demo_pkg/demo_pkg/demo_pkg_node.py to see how the @node, @timer, and @publisher decorators work.

• Read the Core Concepts: Dive deeper into "The Genesys Way" to understand the design philosophy.

• Check the Command Reference: See what other powerful commands are available in the genesys CLI.