Full Topology Experimentation Framework

This repository contains the experimentation code used for my master's thesis on semantic scheduling for multi-modal sensor data in ROS 2. It implements and evaluates multiple executor configurations (ROS 2 default, dynamic EDF) on a fixed test topology, with automated tracing and batch experiment execution.

Audience: This version is intended for thesis reviewers. For the eventual open-source release, setup and dependency instructions will be expanded.

---

Repository structure

Key files and directories:

src/full_topology/
 ├── CMakeLists.txt        # CMake config, passes macro switches
 ├── package.xml           # ROS 2 package manifest
 ├── launch/
 │    └── trace_full_topology.launch.py  # Starts topology with tracing
 ├── src/
 │    ├── full_topology.cpp # Main implementation with macro-controlled behavior
 │    ├── simple.cpp        # Minimal setup to explore one-chain starvation
 │    └── nodes.hpp         # Node type definitions
src/cyclonedds/            # Submodule: Cyclone DDS
src/rcl/                   # Submodule: ROS 2 rcl
src/rclcpp/                # Submodule: ROS 2 rclcpp
src/rmw_cyclonedds/         # Submodule: RMW layer
src/ros2_tracing/           # Submodule: ros2_tracing framework
src/ros_edf/                # Submodule: EDF executor implementation (Arafat et al.)
src/tracetools_analysis/    # Submodule: trace analysis tools
init.sh
build.sh
build_run_copy.sh
batch_run.sh
setup-venv.sh

---

Platform & prerequisites

• ROS 2 distribution: Foxy (required)
• Test environment: Raspberry Pi 4 (4 GB) with Ubuntu 20.04 LTS, PREEMPT_RT kernel, LTTng 2.13, 2 isolated CPU cores at fixed frequency (as in ros-realtime/reference-system)
• Python: 3.8 (used via setup-venv.sh)
• RMW: rmw_cyclonedds_cpp (mandatory , the only implementation with our modifications)
• Build concurrency: limited to -j1 to avoid overloading the Pi’s non-isolated cores.

System dependencies were installed via apt.

---

Macro options and their flow

Experiment configurations are set at build time via CMake options, which build_run_copy.sh sets based on its arguments:

CMake Option	Compile Definition	Meaning
ROS_DEFAULT_EXECUTOR	ROS_DEFAULT_EXECUTOR	Use ROS 2 default executor
EDF_PRIORITY_EXECUTOR	EDF_PRIORITY_EXECUTOR	Use EDF executor (Arafat et al.)
MULTI_THREADED	MULTI_THREADED	Multi-threaded executor
USE_TIMER_IN_FUSION_NODES	USE_TIMER_IN_FUSION_NODES	Enable internal timers in fusion nodes
BOOSTED=<ms>	BOOSTED=<ms>	Reduce chain deadlines to this value; 1000 = disabled

Flow: batch_run.sh → calls build_run_copy.sh with args → sets CMake options → CMakeLists.txt adds compile definitions → full_topology.cpp selects behavior via #ifdef.

---

Quick start

# 1. Source ROS 2 Foxy environment
source /opt/ros/foxy/setup.bash

# 2. Source init script (sets RMW, build flags, venv, etc.)
source init.sh

# 3. Build & run a single timed, single-threaded ROS 2 default executor run
./build_run_copy.sh ros single timed 1000

# or: run the full batch (takes multiple hours)
./batch_run.sh

---

Launch file: trace_full_topology.launch.py

• Declares a length argument (seconds; default: 60.0).
• Starts an LTTng tracing session trace_full_topology in analysis/tracing/.
• Traces UST events from DDS, ROS 2 layers, RMW, rclcpp callbacks & executors.
• Launches full_topology node executable.
• Automatically shuts down after length seconds.

---

Running experiments

build_run_copy.sh arguments

./build_run_copy.sh <scheduler> <threading> <timer> [boost] [no_rebuild]

• scheduler: ros (ROS 2 default) or edf (EDF executor)
• threading: single or multi
• timer: timed or direct (thesis uses timed)
• boost: integer (ms) deadline; 1000 = disabled boost
• no_rebuild: skip rebuilding (useful for repeated runs in same config)

Each run takes ~30–45 s (20 s experiment time + launch/stop/convert/copy).

---

batch_run.sh defaults

Runs a full matrix:

• Timer modes: direct, timed
• Threading: single, multi
• Schedulers:
  • ROS default (ros)
  • EDF with boosts {1000, 500, 100, 50, 10}
• Iterations: ITERATIONS=49 per configuration, thus with the one that did the rebuild, a total of 50

---

Trace files

Traces are renamed after run completion (boost only when applicable):

<scheduler>_<threading>_<timer>_<runtime>_<boost>-<timestamp>

Example:

edf_multi_timed_20_boosted_500-20250301T101530

---

Remote copy

After renaming, traces are optionally copied to a remote location via scp:

REMOTE_USER=user
REMOTE_HOST=host
REMOTE_PATH=/path/to/store/traces

Warning: Update these in build_run_copy.sh before use. If unset or inaccessible, copying will fail (local trace is still kept).

---

Disclaimer

Research code, provided as is. See thesis for methodology, hardware setup, and complete experiment design.
This repository reflects the full development history of the thesis work. Some commits represent intermediate or WIP states. For traceability, commit hashes referenced in the thesis remain valid.