# FRC PathPlanner

> PathPlanner 是一套圖形化軌跡規劃工具，搭配 WPILib 可讓你的機器人在 Autonomous 模式下精確行走預先規劃的路徑。

---

## PathPlanner 是什麼？

PathPlanner 是 FRC 社群開發的軟體，可讓你：
- 透過 GUI 畫出機器人移動路徑
- 自動處理機器人加減速、曲線、旋轉角度
- 支援 *Event markers* (標記比賽影片或即時控制流程中的關鍵事件（如得分、犯規、物件拾取），方便賽後回顧與分析)、*Choreo* (進階路徑規劃工具) 整合、Alliance Flipping (自動將路徑或座標依據紅藍方進行鏡像轉換，確保相同程式碼在不同聯盟中也能正確運行，減少重複開發與錯誤風險) 等功能
- 與 WPILib 完美整合，支援 Swerve、Tank驅動

---

## 安裝與使用

### 安裝 PathPlanner
- 前往 GitHub Release (或microsoft store) 下載最新版：
[https://github.com/mjansen4857/pathplanner/releases](https://github.com/mjansen4857/pathplanner/releases)
- 解壓縮後打開 `PathPlanner.exe`（Windows）或執行對應平台的檔案

---

### 基本操作教學

- **新增路徑**：點選左側 `New Path`
- **控制點（Waypoint）**：點選畫面新增，拖曳調整位置
- **機器人朝向**：控制點上的綠色箭頭為面朝方向，可拖動調整
- **事件標記（Event Marker）**：可用於自動執行指定命令（例如吸入、射出等）
- **儲存路徑**：路徑會儲存在 `/src/main/deploy/pathplanner` 資料夾下（JSON）

---

## Java 專案整合教學（2025 WPILib）

### `build.gradle` 加入 PathPlanner Library

#### 確認 `build.gradle` 有包含以下依賴 ( 通常會自動有 )：

dependencies {
    implementation 'com.pathplanner.lib:pathplanner-lib:2024.2.2' // 確認為最新版
}

然後重新同步 Gradle。

#### 新增路徑與事件命令
- 路徑載入

import com.pathplanner.lib.auto.AutoBuilder;
import com.pathplanner.lib.path.PathPlannerPath;
import com.pathplanner.lib.commands.PathPlannerAuto;
// 單一路徑
PathPlannerPath path = PathPlannerPath.fromPathFile("TestPath");
Command followPath = AutoBuilder.followPath(path);

- 多段 + 事件點（推薦使用 AutoBuilder）

// 將 GUI 中指定的事件名稱與 Command 連結起來
AutoBuilder.configureEventCommands(Map.of(
    "Shoot", new ShootCommand(),
    "Intake", new IntakeCommand()
), /* requireAll */ true);

// 從路徑名稱建立完整 Autonomous Command
Command auto = new PathPlannerAuto("Center4NoteAuto");
auto.schedule();

## AutoBuilder 快速整合 Swerve（以 SwerveDrivePoseEstimator 為例）

AutoBuilder.configureHolonomic(
    this::getPose,     // 回傳目前機器人 Pose2d
    this::resetPose,   // 設定 Pose2d
    this::getSpeeds,   // 回傳 ChassisSpeeds
    this::drive,       // 控制輸出 ChassisSpeeds
    new HolonomicPathFollowerConfig(
        new PIDConstants(5.0, 0.0, 0.0),    // Translation PID
        new PIDConstants(3.0, 0.0, 0.0),    // Rotation PID
        4.5, // Max module speed (m/s)
        0.5, // Drive base radius (m)
        ReplanningConfig.defaultConfig()
    ),
    () -> DriverStation.getAlliance().orElse(Alliance.Red) == Alliance.Red,
    this
);

---
## 檔案位置與命名規則
- 路徑通常在：`src/main/deploy/pathplanner/<your-path>.path`(為自動創建的)
- 自動模式名稱建議：以 XNoteAuto、Left3Piece 等命名清楚表示功能
- 路徑名稱建議：依照官方/自訂的場地/遊戲物件代號命名，例如CoralStation_ReefK (CS_RK)
- 不需手動加進 Java 專案，PathPlannerAuto 會自動讀取

---
## 實作範例（Swerve）

@Override
public void autonomousInit() {
    Command auto = new PathPlannerAuto("Center4NoteAuto");
    if (auto != null) auto.schedule();
}

或搭配 Shuffleboard 選擇面板：

SendableChooser<Command> autoChooser = AutoBuilder.buildAutoChooser();
SmartDashboard.putData("Auto Mode", autoChooser);

---
### 學習資源與教學

#### 官方:
Pathplanner Doc:
https://pathplanner.dev/home.html
#### YouTube：
PathPlanner AutoBuilder 教學:
https://www.youtube.com/watch?v=8dF20oKuVJo

---
### 常見錯誤排除
|問題 |解法|
|----|----|
|無法讀取路徑| 確認 JSON 檔放在 src/main/deploy/pathplanner|
|機器人位置不準 |確保使用 Pose Estimation + 正確 IMU/Encoder 數據|
自動指令沒執行 |檢查 Event Marker 名稱拼寫是否與程式對應|
移動異常抖動| PID 設定過高、模組最大速度填錯或電池電壓不足|

---

### <font color="#f50"> ! 都看完了，我要回家 ! </font>

## [好](https://hackmd.io/ACI3uWclSO6rAX9mMNIxcQ)