In this Quick Start guide, you’ll experience Heex using Resource and Data Automation (RDA). RDA allows you to monitor and capture data from ROS systems without writing a single line of code. You’ll use scripts to configure your system and datasource from a ROS bag, create triggers, then launch a Heex Agent inside a Docker container to generate events. With RDA, you don’t need to write custom implementations to listen to ROS messages.

​
Requirements

  • Ubuntu OS (20.04, 22.04, or 24.04) or a virtual machine running one of these versions
  • ROS2 installed

If you don’t have Ubuntu with ROS2 installed, you can use Multipass to create a VM:

# Launch an Ubuntu VM with ROS2 Jazzy pre-installed
multipass launch ros2-jazzy --name heex-demo

# Connect to the VM
multipass shell heex-demo

Once inside the VM, ROS2 Jazzy is already pre-installed and ready to use.

​
Get Your API Key

Before starting, you’ll need your Heex API key:

  1. Go to Account settings
  2. Create an API key
  3. Copy your API key for use in the next step

​
Configure Your System

​
Step 1: Download the Setup Script and the demo ROS Bag

​
Requirements

  • curl
  • jq

You have two script options:

  • Basic script: A simple script showing you an example of automating the Heex CLI. You need to have a local CLI installed to use this script.
  • Advanced script [Recommended if dependencies are not installed]: Offers more configuration options for a complete workspace setup. If you don’t have a local CLI installed, the script will download it for you.

Download your preferred script:

# Option 1: Basic script
curl -f "https://heex-public-bucket.s3.eu-central-1.amazonaws.com/get-started-scripts/simplifiedGetStartedRDA.sh" -o setup-heex-rda-basic.sh
chmod +x setup-heex-rda-basic.sh
# Download the CLI if you don't have it locally
curl -f "https://api.app.heex.io/v1/cli/download?operating_system=$(. /etc/os-release && echo ${ID}_${VERSION_ID}_$(uname -m))" -H "secret_key: YOUR_API_KEY" -o heex && chmod +x heex

# Option 2: Advanced script with more configuration options
curl -f "https://heex-public-bucket.s3.eu-central-1.amazonaws.com/get-started-scripts/getStartedRDA.sh" -o setup-heex-rda-advanced.sh
chmod +x setup-heex-rda-advanced.sh

​
Step 2: Execute the Setup Script

Run the script with the following command:

./setup-heex-rda-<basic|advanced>.sh --api-key YOUR_API_KEY [--no-clean]

# Check help for more options
./setup-heex-rda-<basic|advanced>.sh --help

This script will:

  1. Create a new system using the Heex CLI
  2. Read the ROS bag and transform it into a Heex datasource linked to your system
  3. Create a trigger that will generate events based on specific conditions
  4. Return the system UUID which you’ll need for the next steps

Note that while the script configures a trigger, RDA itself is what enables you to use these triggers without writing custom code implementations to listen to ROS messages.

​
Generate Events Using the RDA Agent

Now that your system is configured, you can generate events without coding implementations.

​
Step 1: Verify Docker Installation

Make sure Docker is installed and running:

docker --version
docker ps

If Docker isn’t installed, install it using:

sudo apt update
sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER
# Log out and back in for the group changes to take effect

​
Step 2: Download the Heex CLI and Replay the ROS Bag

First, download the Heex CLI:

curl --fail -X GET "https://api.app.heex.io/v1/cli/download?operating_system=$(. /etc/os-release && echo ${ID}_${VERSION_ID}_$(uname -m))" -H "secret_key: YOUR_API_KEY" -o heex && chmod +x heex

Now use the CLI to replay the ROS bag and generate events:

# Warning: The first time you run this command, it will take a while to pull the docker image.
./heex sdk replay --api-key YOUR_API_KEY --os-version Ubuntu_24.04 --system-id YOUR_SYSTEM_ID

Optionally, you can specify a custom bag path:

./heex sdk replay --api-key YOUR_API_KEY --os-version Ubuntu_24.04 --bag-path PATH_TO_YOUR_BAG --system-id YOUR_SYSTEM_ID

Replace YOUR_SYSTEM_ID with the system ID created in the previous step.

Available operating systems are: Ubuntu_20.04, Ubuntu_22.04, Ubuntu_24.04 (default) Available architectures are: x86 (default), arm

For more options, please check the help:

./heex sdk replay --help

The script will:

  1. Setup the Heex Agent
  2. Configure the agent to listen for signals from the ROS bag
  3. Replay the ROS bag as if it were data streaming from a real-time system

​
Step 3: View Your Events

If you have a Graphical Interface, a new terminal will open and poll for events every 30 seconds. You’ll see events arriving in real-time.

Otherwise, you can view the events in the Heex platform by navigating to the Smart Data section. Refresh the page to see events arriving in real-time.

The Docker container will generate events for a few minutes as it processes the ROS bag data.

​
Congratulations!

You’ve successfully:

  1. Configured a Heex system with a data source and trigger
  2. Generated events using RDA without writing any code
  3. Experienced how Heex can automatically monitor ROS messages and capture data without custom implementations

This approach demonstrates how Heex’s RDA capabilities allow you to quickly set up data capture scenarios for ROS-based systems without writing a single line of code to listen to ROS messages.

​
Next Steps