162 lines
5.6 KiB
Markdown
162 lines
5.6 KiB
Markdown
# 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.
|