Skip to main content

​
ROS2 Getting Started

This guide walks you through connecting a ROS2 robot to Roboticks. Your existing ROS2 code stays unchanged - Roboticks manages it.

​
Prerequisites

  • Device with ROS2 installed (Humble, Iron, or Jazzy)
  • Device Manager installed (Installation Guide)
  • Your ROS2 package built and tested

​
Step 1: Create a Roboticks Module

A Roboticks module wraps your ROS2 node, handling lifecycle and monitoring. Create a simple configuration file: 
# my-ros2-module.yaml
name: MyRos2Module
version: 1.0.0
description: "My ROS2 application managed by Roboticks"

update_rate_hz: 10

custom:
  ros2:
    # Your existing ROS2 package and executable
    package: "my_robot_package"
    executable: "my_robot_node"

    # Optional: pass parameters
    message: "Hello from my robot!"
    rate_hz: 1.0

    # Process management
    auto_restart: true
    restart_delay_ms: 1000

  # Optional: automatic rosbag recording
  rosbag:
    enabled: true
    output_dir: "/var/roboticks/ros2/bags"
    topics: "/my_robot/status, /my_robot/sensor_data"

​
Step 2: Create a Composition

A composition defines which modules run together. Create a simple composition: 
# my-robot-composition.yaml
name: MyRobotComposition
version: 1.0.0
description: "My ROS2 robot application"

modes:
  - name: prod
    description: "Production mode"
    processes:
      - MyRos2Module

processes:
  - name: MyRos2Module
    type: module
    binary: "MyRos2Module/MyRos2Module"
    config: "MyRos2Module/config/my-ros2-module.yaml"
    restart_policy: on_failure

​
Step 3: Deploy to Your Device

Copy your module and composition to the device: 
# On your device
sudo mkdir -p /var/roboticks/compositions/MyRobotComposition
sudo cp my-robot-composition.yaml /var/roboticks/compositions/MyRobotComposition/

​
Step 4: Start a Session

From the Roboticks dashboard or CLI: 
# Using the CLI
roboticks session start --device my-robot --composition MyRobotComposition --mode prod
Or from the web dashboard:
  1. Navigate to your device
  2. Click “Start Session”
  3. Select your composition and mode
  4. Click “Start”

​
Step 5: Monitor Your Robot

Once running, you can:
  • View logs in real-time from the dashboard
  • Download rosbags captured during the session
  • Stop remotely when testing is complete

​
What Just Happened?

  1. The Device Manager received the session start command
  2. It loaded your composition configuration
  3. Your ROS2 node was launched with the specified parameters
  4. Logs and rosbags are being captured and uploaded
  5. You can monitor everything from the dashboard

​
Key Concepts

​
Modules vs Compositions

ConceptPurpose
ModuleWraps a single ROS2 node with lifecycle management
CompositionGroups modules that should run together

​
Session Lifecycle

START → Module loaded → ROS2 node launched → Running → STOP → Cleanup → Done
During a session:
  • Logs are streamed to the cloud
  • Rosbags are recorded (if enabled)
  • Health is monitored
  • Crashes trigger automatic restart (if configured)

​
Troubleshooting

Check that your ROS2 workspace is sourced and the package is installed:
source /opt/ros/humble/setup.bash
ros2 pkg list | grep my_robot_package
Ensure your workspace is built and the install path is accessible:
# Build your workspace
cd ~/ros2_ws
colcon build

# The module will look for packages in /opt/roboticks/ros2_ws
sudo cp -r ~/ros2_ws/install /opt/roboticks/ros2_ws/
Verify the topics exist and the output directory is writable:
# Check topics
ros2 topic list

# Check directory permissions
sudo mkdir -p /var/roboticks/ros2/bags
sudo chown $USER:$USER /var/roboticks/ros2/bags

​
Next Steps

Examples

See complete working examples

Dashboard

Learn about the web dashboard