Home - Forestry-Robotics-UC/fruc_dataset_apparatus GitHub Wiki

Getting Started

The FRUC Dataset Apparatus is a ROS2-based multi-sensor recording system designed to capture synchronized data from various sensors for robotics research. This system uses containerized deployments to manage different sensor drivers and recording pipelines.

Container Runtime: The system uses Docker on desktop/workstation systems and Podman on SteamDeck. Both are fully compatible and interchangeable for this system.

Quick Navigation

New to the system? Start here:

Prerequisites

  1. Install Container Runtime:

  2. Clone the Repository: Download the repository containing the necessary files for recording:

    git clone <repository-url>
cd fruc_dataset_apparatus

  3. Initialize Git Submodules (if applicable):

    git submodule init
git submodule update

System Architecture

The recording system is built on ROS2 (Jazzy distribution) and uses containerized sensor drivers for modular deployment:

  • Time Synchronization: A Raspberry Pi Pico coordinates hardware time synchronization across sensors
  • Xsens IMU Container: Captures inertial measurement unit data (time-synced via RPi Pico)
  • Realsense Container: Manages Intel Realsense D435i depth camera (time-synced via RPi Pico)
  • Ouster Container: Interfaces with Ouster LiDAR sensors (time-synced via RPi Pico)
  • Emlid Container: Handles GNSS positioning data
  • Recording Container: Captures selected topics to rosbag files
  • Visualization Container: Provides real-time data visualization via Foxglove Bridge

Launching the System

Using Interactive GUI (Recommended for Desktop/SteamDeck)

From the repository root, run:

./launch-system.sh  # Works on both Docker (desktop) and Podman (SteamDeck)

This will:

  1. Generate a unique recording name with a timestamp and random adjectives
  2. Present an interactive checklist of available ROS2 topics
  3. Build and start all enabled Docker containers
  4. Begin recording the selected topics

Using GNOME Desktop Environment

If running on a GNOME desktop system:

./gnome-launch-system.sh

Using Docker Compose Directly

Please note, this will only launch the sensor drivers. Recording will not automatically start with this command.

Navigate to the docker/ directory:

cd docker
docker-compose up

Available Recording Topics

The system publishes data on the following topics:

IMU Data:

  • /imu/data - Main IMU measurements
  • /imu/mag - Magnetometer data
  • /heading - Computed heading from IMU

LiDAR Data:

  • /ouster/lidar_packets - Raw lidar packets
  • /ouster/imu_packets - LiDAR internal IMU packets
  • /ouster/metadata - LiDAR metadata
  • /ouster/points - Point cloud (if enabled)
  • /ouster/imu - Internal IMU measurements (if enabled)

Camera Data:

  • /camera/color/image_raw - Realsense color image
  • /camera/color/camera_info - Realsense color camera info
  • /camera/aligned_depth_to_color/image_raw - Depth data aligned to color
  • /camera/aligned_depth_to_color/camera_info - Aligned depth camera info
  • /camera/color/metadata - Color frame metadata
  • /camera/depth/metadata - Depth frame metadata

GNSS Data:

  • /fix - GPS position fix

System Data:

  • /tf - Transform frames
  • /tf_static - Static transforms
  • /robot_description - URDF robot model

Stopping the System

To stop the recording:

./stop-system.sh

Or if you're using GNOME desktop:

./gnome-stop-system.sh

Rosbag files will be saved to the rosbags/ directory in the repository root.

Documentation Map

For Users

For Developers

System Setup Guides

System Architecture Summary

Sensors

The recording system incorporates various sensors to capture data from the environment. These sensors enable perception, localization, and environmental awareness within the ROS ecosystem. The following sensors are utilized in the system:

  1. Xsens IMU: Measures acceleration, angular velocity, and magnetic fields for orientation estimation and motion tracking. Time-synchronized via RPi Pico.

  2. Intel Realsense D435i Camera: Depth camera combining stereo vision with an infrared projector. Captures RGB images and depth information for 3D reconstruction and object tracking. Time-synchronized via RPi Pico.

  3. Ouster LiDAR: Light Detection and Ranging sensor that creates high-resolution 3D point cloud representations of the environment for mapping and localization. Time-synchronized via RPi Pico.

  4. Emlid Receiver: GNSS positioning receiver for accurate global positioning data.

These sensors are integrated as separate ROS2 node containers that publish data to a shared ROS2 network.

Time Synchronization

A Raspberry Pi Pico acts as a time synchronization hub for the Xsens IMU, Intel Realsense camera, and Ouster LiDAR. This ensures that data from these three sensors shares a common, synchronized time reference, which is critical for accurate sensor fusion and data analysis. The RPi Pico communicates timing information to each sensor via dedicated connections.

Key Features

Multi-Sensor Integration - Support for IMU, LiDAR, depth camera, and GNSS
Hardware Time Synchronization - RPi Pico-based sync across sensors
Flexible Recording Configuration - Select topics, set split size/duration, choose compression
Docker-Based Architecture - Modular, reproducible container setup
ROS2 Jazzy - Latest LTS distribution with modern ROS2 features
Interactive GUI - Easy-to-use kdialog and zenity interfaces
Comprehensive Rosbag Output - With metadata and info files
extensible Design - Add new sensors with Dockerfile modifications

System Requirements

  • OS: Ubuntu 22.04 LTS or later
  • CPU: Quad-core minimum (8-core recommended)
  • RAM: 8 GB minimum (16 GB recommended)
  • Storage: 500 GB+ fast SSD
  • Network: Gigabit Ethernet for Ouster link-local

For detailed requirements, see Installation & Setup

Quick Start

  1. Install: Follow Installation & Setup
  2. Verify: Run ./docker/pre_recording_test.sh
  3. Record: Execute ./launch-system.sh
  4. Process: See Post-Recording Procedure

Support & Resources

Last Updated: 2026-03-30
Want to contribute? See Developer Guide