Update README.md

README.md

@@ -1,3 +1,196 @@
----
-license: mit
----
+---
+license: cc-by-nc-4.0
+language:
+- en
+tags:
+- robotics
+- random-forest
+- pid-control
+- line-follower
+- raspberry-pi
+- sklearn
+- tabular-regression
+pipeline_tag: tabular-regression
+---
+
+# 🤖 pid-ml-follower-model
+
+**Random Forest Regressor** trained on 100 real robot runs to predict next-step
+line position error for a Hybrid PID + ML line following robot on Raspberry Pi.
+
+---
+
+## 📌 Model Overview
+
+This model predicts `next_error` — the PID line position error at time t+1 —
+using 15 basic sensor inputs available at time t. The prediction is used as a
+residual correction on top of a classical PID controller, forming a
+**Hybrid PID + ML control system**.
+
+| Property | Value |
+|----------|-------|
+| Algorithm | `RandomForestRegressor` (scikit-learn) |
+| Target | `next_error` = pid_error at t+1 |
+| Input features | 15 sensor + PID state columns |
+| Training rows | 166,053 |
+| Test rows | 42,930 |
+| Training runs | 80 robot runs |
+| Test runs | 20 robot runs (zero leakage) |
+
+---
+
+## 📊 Performance
+
+| Model | RMSE | MAE |
+|-------|------|-----|
+| Predict zero baseline | 0.4252 | 0.3678 |
+| Persist current error baseline | 0.0219 | 0.0124 |
+| Original RF (n=300, depth=15) | 0.018756 | — |
+| **This model (Optuna tuned)** | **0.018731** | **0.008295** |
+
+- **14.3% improvement** over persist-current-error baseline
+- Better than original RF on **13 / 20** test runs
+
+---
+
+## ⚙️ Hyperparameters
+
+| Parameter | Value |
+|-----------|-------|
+| `n_estimators` | 328 |
+| `max_depth` | 22 |
+| `min_samples_leaf` | 9 |
+| `max_features` | sqrt |
+| Tuning | Optuna — 50 trials, TPE sampler |
+
+---
+
+## 🔢 Input Features (exact order)
+
+```python
+features = [
+    "pid_error",        # current line position error
+    "pid_error_prev",   # error from previous tick
+    "pid_error_delta",  # error(t) - error(t-1)
+    "pid_derivative",   # derivative term computed by PID
+    "ir_centroid",      # weighted centre of IR readings
+    "ir_spread",        # width of line across sensors
+    "ir1_inv",          # IR sensor 1 (inverted)
+    "ir2_inv",          # IR sensor 2 (inverted)
+    "ir3_inv",          # IR sensor 3 (inverted)
+    "ir4_inv",          # IR sensor 4 (inverted)
+    "ir5_inv",          # IR sensor 5 (inverted)
+    "left_speed",       # left motor speed
+    "right_speed",      # right motor speed
+    "speed_diff",       # left_speed - right_speed
+    "loop_dt",          # time elapsed since last tick
+]
+```
+
+**Order is critical — must match exactly during inference.**
+
+---
+
+## 🚀 How to Use
+
+### Install
+
+```bash
+pip install scikit-learn numpy huggingface_hub
+```
+
+### Load Model
+
+```python
+import pickle
+from huggingface_hub import hf_hub_download
+
+# Download model
+model_path = hf_hub_download(
+    repo_id  = "satwikshreshth1/pid-ml-follower-model",
+    filename = "rf_model_tuned.pkl"
+)
+
+# Load
+with open(model_path, "rb") as f:
+    rf = pickle.load(f)
+```
+
+### Inference
+
+```python
+import numpy as np
+
+features = [pid_error, pid_error_prev, pid_error_delta, pid_derivative,
+            ir_centroid, ir_spread, ir1_inv, ir2_inv, ir3_inv, ir4_inv,
+            ir5_inv, left_speed, right_speed, speed_diff, loop_dt]
+
+predicted_next_error = rf.predict([features])[0]
+```
+
+### Hybrid Control Loop on Raspberry Pi
+
+```python
+# Alpha controls ML correction strength
+alpha = 0.6    # recommended starting value
+Kp    = 13.2   # must match your robot tuning
+
+ml_correction = -predicted_next_error * Kp * alpha
+ml_correction = np.clip(ml_correction, -10, 10)   # safety clip
+final_output  = pid_output + ml_correction
+```
+
+### Tuning Alpha
+
+| Alpha | Behaviour |
+|-------|-----------|
+| 0.0 | Pure PID — ML disabled |
+| 0.3 | Conservative hybrid |
+| 0.6 | Standard hybrid (recommended) |
+| 1.0 | Full ML correction |
+
+---
+
+## 📦 Files in This Repository
+
+| File | Description |
+|------|-------------|
+| `rf_model_tuned.pkl` | Trained Random Forest model (pickle) |
+| `model_meta.json` | Feature list, hyperparameters, metrics |
+
+---
+
+## 🗂️ Training Data
+
+- 100 real robot runs collected on 20 March 2026
+- 221,967 total rows — 208,983 after cleaning
+- Robot: IR-based line follower on Raspberry Pi
+- PID tuning: Kp=13.2, Ki=0.0, Kd=0.475 | Base speed: 40
+- Loop frequency: ~65–70 Hz
+
+**Full dataset on Kaggle:**
+[satwikshreshth01/path-error-data](https://www.kaggle.com/datasets/satwikshreshth01/path-error-data)
+
+---
+
+## 🔗 Related Links
+
+- **GitHub Repository:** [satwik-shreshth/pid-ml-follower](https://github.com/satwik-shreshth/pid-ml-follower)
+- **Training Notebook:** included in GitHub repo under `notebook/`
+- **Related Project:** [Tripathagamini-S_Auto](https://github.com/satwik-shreshth/Tripathagamini-S_Auto)
+
+---
+
+## 📜 License
+
+CC BY-NC 4.0 — Attribution required, non-commercial use only.
+https://creativecommons.org/licenses/by-nc/4.0/
+
+---
+
+## 👨‍💻 Author
+
+**Satwik Shreshth**  
+MCA (Final Year), Sikkim University  
+satwikshreshth2002@gmail.com  
+[@satwik-shreshth](https://github.com/satwik-shreshth)