Configuring Edge Data Recording

Create a recording configuration for ROS 2 edge data capture on NVIDIA Jetson devices. By the end of this recipe, you will have a validated YAML configuration controlling topic selection, compression, episode triggers, and disk monitoring.

NOTE

This recipe covers configuration authoring. The recording service that executes these configurations is part of the edge deployment (see Data Pipeline).

📋 Prerequisites

Requirement	Details
NVIDIA Jetson	JetPack 6.0+ installed
ROS 2	Humble or later with rosbag2 packages
Storage	Sufficient disk space for recording sessions (SSD recommended)
IDE	VS Code or any editor with YAML support (optional: JSON Schema validation)

🚀 Steps

Step 1: Start from a platform example

The repository includes platform-specific examples. Copy one as your starting point:

# For a UR10E robotic arm
cp data-pipeline/capture/config/examples/ur10e-6dof-arm.yaml my-recording-config.yaml

# For a mobile manipulator
cp data-pipeline/capture/config/examples/mobile-manipulator.yaml my-recording-config.yaml

Step 2: Configure topics

Edit the topics section to match your robot's ROS 2 topic namespace. Each entry specifies the topic name, recording frequency, and compression algorithm:

topics:
  - name: /joint_states
    frequency_hz: 100.0
    compression: lz4

  - name: /camera/color/image_raw
    frequency_hz: 30.0
    compression: zstd

  - name: /imu/data
    frequency_hz: 200.0
    compression: lz4

Choose compression based on data characteristics:

Algorithm	Ratio	CPU Overhead	Best For
none	1x	0%	Debugging, maximum write speed
lz4	2-3x	<10%	High-frequency numeric data (joints, IMU)
zstd	3-5x	20-30%	Images and low-frequency data

Step 3: Configure episode triggers

Set the trigger type that controls episode start/stop:

# GPIO trigger — physical button on Jetson GPIO header
trigger:
  type: gpio
  pin: 17
  active_high: true

# ROS 2 service trigger — start/stop via service calls
trigger:
  type: service
  start_service: /recording/start
  stop_service: /recording/stop

# Timer trigger — fixed-duration episodes
trigger:
  type: timer
  duration_sec: 60.0

Step 4: Configure disk monitoring

Prevent storage exhaustion during long recording sessions:

disk_thresholds:
  warning_percent: 80
  critical_percent: 95

The recording service logs a warning at 80% disk usage and stops recording at 95% to prevent data corruption.

Step 5: Configure gap detection

Detect missing messages that indicate data quality issues:

gap_detection:
  threshold_ms: 100.0
  severity: warning

A threshold of 100ms balances sensitivity with false positives for most robotic platforms. Lower the threshold for safety-critical applications.

Step 6: Set the output directory

output_dir: /data/recordings

Use an SSD-backed path for reliable high-throughput recording.

Step 7: Enable JSON Schema validation (optional)

Add the schema reference to the first line of your config for IDE autocomplete and inline validation:

# yaml-language-server: $schema=./recording_config.schema.json

The schema file is at data-pipeline/capture/config/recording_config.schema.json.

✅ Verify

Validate the configuration against the Pydantic models:

cd data-pipeline/capture
python -c "
from models.config_models import RecordingConfig
import yaml

with open('../../my-recording-config.yaml') as f:
    config = RecordingConfig(**yaml.safe_load(f))
print(f'Valid config: {len(config.topics)} topics, trigger={config.trigger.type}')
"

A successful validation prints the topic count and trigger type without errors.

⚙️ Configuration Reference

Section	Field	Type	Required	Description
topics[]	name	string	yes	ROS 2 topic path starting with /
topics[]	frequency_hz	float	yes	Target recording frequency (0, 1000]
topics[]	compression	string	no	none, lz4, or zstd (default: none)
trigger	type	string	yes	gpio, service, or timer
disk_thresholds	warning_percent	int	no	Disk usage warning threshold
disk_thresholds	critical_percent	int	no	Disk usage stop threshold
gap_detection	threshold_ms	float	no	Missing message detection threshold
output_dir	—	string	no	Recording output directory

See Chunking and Compression Configuration for advanced bag splitting options.

🔗 Related Recipes

• Preparing Datasets for Training — process recorded data for training
• Your First LeRobot Training Job — train a policy with collected data

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.