ROS-Dynamic-Executor-Experiments/ReadMe.md

# 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](https://github.com/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

```bash
# 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

```bash
./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`:

```bash
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.