Update ReadMe for submission

ReadMe.md

@@ -0,0 +1,162 @@
+# 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.