first

README.md

@@ -0,0 +1,96 @@
+# Drone MP-QUIC Measurement Testbed
+
+This testbed is designed to measure highly reliable (99.999%), ultra-low latency MP-QUIC communication between a Drone and a Ground Station over heterogeneous links (5G, Satellite, Mesh).
+
+## 1. Deployment Guide
+
+The testbed is split into two independent deployable units.
+
+### Prerequisites
+- **Go 1.20+**: To build the client and server applications.
+- **Python 3.x**: With `pandas`, `matplotlib`, and `seaborn` installed for analysis.
+- **Linux (Optional)**: If you wish to run the eBPF kernel tracing, you must be on a Linux machine with `bcc` installed and run the scripts as `root`.
+
+### Running the Ground Station (Server)
+Deploy the `server/` directory to the Ground Station machine.
+```bash
+# This automatically builds the Go code and starts listening on port 4242.
+# It logs the application-level delivery metrics (packet loss, latency) to ground_metrics.csv
+./server/scripts/run.sh --addr 0.0.0.0:4242 --output ground_metrics.csv
+```
+
+### Running the Drone (Client)
+Deploy the `client/` directory to the Drone machine.
+```bash
+# Blasts framed payloads to the ground station.
+# You can specify the scheduler, the duration in seconds, and the payload size in bytes.
+./client/scripts/run.sh \
+    --addr <GROUND_STATION_IP>:4242 \
+    --scheduler minrtt \
+    --duration 30 \
+    --payload-size 2048
+```
+
+### Analyzing the Results
+Once the test finishes, copy `ground_metrics.csv` to your laptop and run:
+```bash
+pip install pandas matplotlib seaborn
+python3 analysis/visualize.py --app ground_metrics.csv
+```
+This will print your exact **Reliability %** to the terminal and generate scatter plots of the jitter and glass-to-glass latency.
+
+---
+
+## 2. Developer Guide: Adding Custom Algorithms
+
+This testbed is designed to be highly modular so you can test custom Path Schedulers and Congestion Control algorithms.
+
+### How to Add a Custom Path Scheduler
+
+Path Schedulers dictate *which* link (5G, Mesh, Satellite) a packet should be sent over. The testbed uses a dynamic registry, meaning you never have to modify `client/main.go` to add a new scheduler.
+
+1. Navigate to the `client/scheduler/` directory.
+2. Copy the template file: `cp custom_example.go my_scheduler.go`.
+3. Open `my_scheduler.go` and implement the `quic.PathScheduler` interface, which requires three methods:
+   - `SelectPath(...)`: Contains your custom logic to choose a path.
+   - `UpdateQuota(...)`: Tracks how much data was sent.
+   - `Reset()`: Resets your internal metrics.
+4. At the bottom of `my_scheduler.go`, update the `init()` function to register your new scheduler:
+   ```go
+   func init() {
+       Register("my_custom_algo", func() quic.PathScheduler {
+           return &MyScheduler{}
+       })
+   }
+   ```
+5. Run `./client/scripts/run.sh --list-schedulers` and you will see `my_custom_algo` automatically available!
+
+### How to Add Custom Congestion Control
+
+Unlike Schedulers, **Congestion Control (CC) algorithms are deeply embedded inside the `mp-quic-go` library**. The library currently supports `CUBIC` and `OLIA`. 
+
+To write a completely new CC algorithm, you must modify the library itself. Here is the easiest workflow:
+
+**Step 1: Fork the Library Locally**
+Clone the underlying library to your machine:
+```bash
+cd ~
+git clone https://github.com/AeonDave/mp-quic-go.git
+```
+
+**Step 2: Tell Go to use your Local Copy**
+In this `drone` project, tell Go to use your local copy instead of downloading it from Github:
+```bash
+cd drone
+go mod edit -replace github.com/AeonDave/mp-quic-go=/path/to/your/local/mp-quic-go
+go mod tidy
+```
+
+**Step 3: Write your CC Algorithm**
+Open your local `mp-quic-go` code and implement the `congestion.SendAlgorithm` interface. 
+You can look at `internal/congestion/cubic_sender.go` inside the library as a template.
+
+**Step 4: Wire it into the Multipath Controller**
+Inside the library, open `multipath_controller.go`. You will need to modify the `MultipathController` to instantiate your new CC algorithm for new paths, similar to how it currently enables OLIA when `EnableOLIA()` is called.
+
+Once your custom library modifications are done, you simply run `./client/scripts/run.sh` inside the `drone` directory, and Go will automatically compile your local, modified library into the drone client!