diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..b1473b3f63 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,4 @@ +- when asked to handle an issue you will need to create a new branch with which to work from +- When creating a PR no need to do created by claude code +- Please don't include the test plan in the PR +- Please always check when modifying files that we are updating the redirects and searching for links to any files that may be affected by changes we made \ No newline at end of file diff --git a/MISSING_PYTHON_EXAMPLES.md b/MISSING_PYTHON_EXAMPLES.md new file mode 100644 index 0000000000..4f5040b5a8 --- /dev/null +++ b/MISSING_PYTHON_EXAMPLES.md @@ -0,0 +1,202 @@ +# Files Missing Python Examples + +**For Issue #1818** - Adding Python examples throughout the documentation + +**Total files needing Python examples: 56** + +*Generated: 2025-10-07* + +--- + +## Summary by Category + +- **software/hardware-apis**: 11 files (HIGH PRIORITY) +- **software/commandbased**: 7 files (HIGH PRIORITY) +- **software/basic-programming**: 2 files (HIGH PRIORITY) +- **software/pathplanning**: 4 files (HIGH PRIORITY) +- **software/wpilib-tools**: 15 files (HIGH PRIORITY) +- **software/convenience-features**: 2 files +- **software/dashboards**: 4 files +- **software/advanced-controls**: 2 files +- **software/networktables**: 1 files +- **software/telemetry**: 2 files +- **software/vision-processing**: 1 files +- **software/vscode-overview**: 2 files +- **software/roborio-info**: 1 files +- **software/can-devices**: 1 files +- **yearly-overview/2020-Game-Data.rst**: 1 files + +--- + +## Detailed File List + + +### Software/Hardware-Apis :star: + +- `software/hardware-apis/misc/addressable-leds.rst` + - Present: Java (20 blocks), C++ (20 blocks) +- `software/hardware-apis/pneumatics/pressure.rst` + - Present: Java (6 blocks), C++ (6 blocks) +- `software/hardware-apis/pneumatics/solenoids.rst` + - Present: Java (3 blocks), C++ (3 blocks) +- `software/hardware-apis/sensors/accelerometers-software.rst` + - Present: Java (8 blocks), C++ (8 blocks) +- `software/hardware-apis/sensors/analog-inputs-software.rst` + - Present: Java (9 blocks) +- `software/hardware-apis/sensors/analog-potentiometers-software.rst` + - Present: Java (3 blocks), C++ (1 blocks) +- `software/hardware-apis/sensors/counters.rst` + - Present: Java (13 blocks), C++ (13 blocks) +- `software/hardware-apis/sensors/digital-inputs-software.rst` + - Present: Java (4 blocks) +- `software/hardware-apis/sensors/encoders-software.rst` + - Present: Java (18 blocks), C++ (1 blocks) +- `software/hardware-apis/sensors/limit-switch.rst` + - Present: Java (1 blocks) +- `software/hardware-apis/sensors/ultrasonics-software.rst` + - Present: Java (4 blocks), C++ (4 blocks) + +### Software/Commandbased :star: + +- `software/commandbased/binding-commands-to-triggers.rst` + - Present: Java (9 blocks), C++ (6 blocks) +- `software/commandbased/command-scheduler.rst` + - Present: Java (6 blocks), C++ (6 blocks) +- `software/commandbased/organizing-command-based.rst` + - Present: Java (12 blocks), C++ (12 blocks) +- `software/commandbased/pid-subsystems-commands.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/commandbased/profile-subsystems-commands.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/commandbased/profilepid-subsystems-commands.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/commandbased/structuring-command-based-project.rst` + - Present: Java (9 blocks), C++ (8 blocks) + +### Software/Basic-Programming :star: + +- `software/basic-programming/alliancecolor.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/basic-programming/reading-stacktraces.rst` + - Present: Java (4 blocks), C++ (4 blocks) + +### Software/Pathplanning :star: + +- `software/pathplanning/pathweaver/integrating-robot-program.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/pathplanning/trajectory-tutorial/creating-drive-subsystem.rst` + - Present: Java (11 blocks), C++ (11 blocks) +- `software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst` + - Present: Java (6 blocks), C++ (6 blocks) +- `software/pathplanning/trajectory-tutorial/entering-constants.rst` + - Present: Java (4 blocks) + +### Software/Wpilib-Tools :star: + +- `software/wpilib-tools/robot-simulation/device-sim.rst` + - Present: Java (5 blocks), C++ (5 blocks) +- `software/wpilib-tools/robot-simulation/drivesim-tutorial/drivetrain-model.rst` + - Present: Java (3 blocks), C++ (3 blocks) +- `software/wpilib-tools/robot-simulation/drivesim-tutorial/odometry-simgui.rst` + - Present: Java (3 blocks), C++ (3 blocks) +- `software/wpilib-tools/robot-simulation/drivesim-tutorial/simulation-instance.rst` + - Present: Java (2 blocks), C++ (2 blocks) +- `software/wpilib-tools/robot-simulation/drivesim-tutorial/updating-drivetrain-model.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/wpilib-tools/robot-simulation/physics-sim.rst` + - Present: Java (3 blocks), C++ (3 blocks) +- `software/wpilib-tools/robot-simulation/simulation-gui.rst` + - Present: Java (1 blocks) +- `software/wpilib-tools/robot-simulation/unit-testing.rst` + - Present: Java (2 blocks), C++ (2 blocks) +- `software/wpilib-tools/robotbuilder/advanced/robotbuilder-custom-components.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/wpilib-tools/robotbuilder/advanced/robotbuilder-writing-pidsubsystem-code.rst` + - Present: Java (3 blocks), C++ (3 blocks) +- `software/wpilib-tools/robotbuilder/introduction/robotbuilder-created-code.rst` + - Present: Java (4 blocks), C++ (4 blocks) +- `software/wpilib-tools/robotbuilder/introduction/robotbuilder-testing-with-shuffleboard.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/wpilib-tools/robotbuilder/writing-code/robotbuilder-drive-tank.rst` + - Present: C++ (2 blocks) +- `software/wpilib-tools/robotbuilder/writing-code/robotbuilder-writing-command-code.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/wpilib-tools/robotbuilder/writing-code/robotbuilder-writing-subsystem-code.rst` + - Present: Java (1 blocks), C++ (2 blocks) + +### Software/Convenience-Features + +- `software/convenience-features/event-based.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/convenience-features/scheduling-functions.rst` + - Present: Java (2 blocks), C++ (3 blocks) + +### Software/Dashboards + +- `software/dashboards/shuffleboard/custom-widgets/creating-a-new-widget.rst` + - Present: Java (7 blocks) +- `software/dashboards/shuffleboard/custom-widgets/creating-custom-data-types.rst` + - Present: Java (6 blocks) +- `software/dashboards/shuffleboard/custom-widgets/creating-plugins.rst` + - Present: Java (2 blocks) +- `software/dashboards/smartdashboard/smartdashboard-namespace.rst` + - Present: Java (2 blocks) + +### Software/Advanced-Controls + +- `software/advanced-controls/state-space/state-space-pose-estimators.rst` + - Present: Java (3 blocks) +- `software/advanced-controls/trajectories/troubleshooting.rst` + - Present: Java (4 blocks), C++ (3 blocks) + +### Software/Networktables + +- `software/networktables/custom-serialization.rst` + - Present: Java (12 blocks), C++ (3 blocks) + +### Software/Telemetry + +- `software/telemetry/robot-telemetry-with-annotations.rst` + - Present: Java (6 blocks) +- `software/telemetry/writing-sendable-classes.rst` + - Present: Java (2 blocks) + +### Software/Vision-Processing + +- `software/vision-processing/introduction/cameraserver-class.rst` + - Present: Java (2 blocks), C++ (2 blocks) + +### Software/Vscode-Overview + +- `software/vscode-overview/creating-robot-program.rst` + - Present: Java (1 blocks), C++ (1 blocks) +- `software/vscode-overview/debugging-robot-program.rst` + - Present: Java (1 blocks), C++ (1 blocks) + +### Software/Roborio-Info + +- `software/roborio-info/roborio-brownouts.rst` + - Present: Java (1 blocks), C++ (1 blocks) + +### Software/Can-Devices + +- `software/can-devices/can-addressing.rst` + - Present: C++ (1 blocks) + +### Yearly-Overview/2020-Game-Data.Rst + +- `yearly-overview/2020-Game-Data.rst` + - Present: Java (1 blocks), C++ (1 blocks) + +--- + +## Notes + +- Files marked with :star: are HIGH PRIORITY (core APIs and frameworks) +- The following language-specific files were excluded: + - `software/advanced-gradlerio/code-formatting.rst` - Java-specific code formatting (GradleRIO) + - `software/basic-programming/cpp-units.rst` - C++-specific units library documentation + - `software/basic-programming/functions-as-data.rst` - Language-specific feature comparison + - `software/basic-programming/java-gc.rst` - Java-specific garbage collection documentation + - `software/basic-programming/java-units.rst` - Java-specific units library documentation + - `software/commandbased/cpp-command-discussion.rst` - C++-specific technical discussion diff --git a/PYTHON_EXAMPLES_ANALYSIS.md b/PYTHON_EXAMPLES_ANALYSIS.md new file mode 100644 index 0000000000..de3736b674 --- /dev/null +++ b/PYTHON_EXAMPLES_ANALYSIS.md @@ -0,0 +1,272 @@ +# Python Examples Gap Analysis for FRC Documentation + +**Issue:** #1818 - Adding Python examples throughout the documentation +**Analysis Date:** October 7, 2025 +**Repository:** frc-docs + +--- + +## Executive Summary + +This analysis identified **56 RST files** in the frc-docs repository that contain Java and/or C++ code examples but are missing corresponding Python examples. These files span critical areas of the WPILib documentation including hardware APIs, command-based programming, path planning, and robot simulation. + +### Quick Stats +- **Total RST files analyzed:** 173 +- **Files with code examples:** 142 +- **Files missing Python examples:** 56 +- **Language-specific docs excluded:** 6 +- **High-priority files:** 39 (70% of missing files) + +--- + +## Priority Categories + +### High Priority (39 files) +Files in core APIs and frameworks that most teams will reference: + +1. **Hardware APIs** (11 files) - Fundamental sensor and actuator control +2. **Command-Based Framework** (7 files) - Core programming paradigm +3. **Path Planning** (4 files) - Autonomous trajectory following +4. **Robot Simulation** (15 files) - Testing and development tools +5. **Basic Programming** (2 files) - Foundational concepts + +### Medium Priority (17 files) +Supporting features and advanced topics: + +- Convenience Features (2 files) +- Dashboards (4 files) +- Advanced Controls (2 files) +- NetworkTables (1 file) +- Telemetry (2 files) +- Vision Processing (1 file) +- VS Code Overview (2 files) +- roboRIO Info (1 file) +- CAN Devices (1 file) +- Game Data (1 file) + +--- + +## Key Findings + +### Pattern 1: Hardware APIs Have the Largest Gap +The `software/hardware-apis` category has the most files missing Python examples: +- **11 files total** +- **Most comprehensive:** `addressable-leds.rst` (20 Java + 20 C++ blocks, 0 Python) +- **Sensor APIs heavily affected:** encoders, counters, accelerometers, digital inputs, analog inputs + +**Impact:** Teams using Python have limited guidance for basic hardware interaction. + +### Pattern 2: Command-Based Framework Inconsistency +The command-based programming documentation shows significant gaps: +- Core concepts like trigger binding, scheduling, and project structure lack Python examples +- 7 critical files need Python additions +- This is particularly impactful since command-based is the recommended framework + +### Pattern 3: Robot Simulation Documentation Incomplete +Robot simulation tools have 15 files missing Python examples: +- Physics simulation examples +- Device simulation +- Unit testing +- Drive simulation tutorial (4-part series) +- RobotBuilder integration (6 files) + +**Impact:** Python teams have less support for simulation-based development and testing. + +### Pattern 4: Some Files Have Many Examples +Several files have extensive code examples that need Python equivalents: +- `organizing-command-based.rst`: 12 Java + 12 C++ blocks +- `counters.rst`: 13 Java + 13 C++ blocks +- `encoders-software.rst`: 18 Java blocks +- `custom-serialization.rst`: 12 Java + 3 C++ blocks + +### Pattern 5: Dashboard/Shuffleboard Plugins +4 dashboard-related files are Java-only: +- Custom widget creation +- Custom data types +- Plugin development +- Namespace handling + +**Note:** Some of these may be intentionally Java-only if Python doesn't support the same extension mechanisms. + +--- + +## Files Excluded from Analysis + +The following 6 files were identified as language-specific documentation and should NOT have multi-language examples: + +1. `java-units.rst` - Java-specific units library +2. `cpp-units.rst` - C++-specific units library +3. `java-gc.rst` - Java garbage collection +4. `cpp-command-discussion.rst` - C++ technical implementation details +5. `code-formatting.rst` - Java/GradleRIO formatting +6. `functions-as-data.rst` - Language-specific feature comparison + +--- + +## Detailed Breakdown by Category + +### Software/Hardware-APIs (11 files) ⭐ HIGH PRIORITY + +**Sensors (8 files):** +- `encoders-software.rst` - 18 Java blocks, critical for drive trains +- `counters.rst` - 13 Java + 13 C++ blocks, extensive examples +- `accelerometers-software.rst` - 8 Java + 8 C++ blocks +- `analog-inputs-software.rst` - 9 Java blocks +- `analog-potentiometers-software.rst` - 3 Java + 1 C++ blocks +- `digital-inputs-software.rst` - 4 Java blocks +- `limit-switch.rst` - 1 Java block +- `ultrasonics-software.rst` - 4 Java + 4 C++ blocks + +**Pneumatics (2 files):** +- `pressure.rst` - 6 Java + 6 C++ blocks +- `solenoids.rst` - 3 Java + 3 C++ blocks + +**Miscellaneous (1 file):** +- `addressable-leds.rst` - 20 Java + 20 C++ blocks (MOST EXAMPLES!) + +### Software/CommandBased (7 files) ⭐ HIGH PRIORITY + +**Core Framework:** +- `binding-commands-to-triggers.rst` - 9 Java + 6 C++ blocks, fundamental to command-based +- `command-scheduler.rst` - 6 Java + 6 C++ blocks +- `organizing-command-based.rst` - 12 Java + 12 C++ blocks (EXTENSIVE!) +- `structuring-command-based-project.rst` - 9 Java + 8 C++ blocks + +**PID Integration:** +- `pid-subsystems-commands.rst` - 1 Java + 1 C++ block +- `profile-subsystems-commands.rst` - 1 Java + 1 C++ block +- `profilepid-subsystems-commands.rst` - 1 Java + 1 C++ block + +### Software/PathPlanning (4 files) ⭐ HIGH PRIORITY + +**Trajectory Tutorial Series:** +- `creating-drive-subsystem.rst` - 11 Java + 11 C++ blocks +- `creating-following-trajectory.rst` - 6 Java + 6 C++ blocks +- `entering-constants.rst` - 4 Java blocks +- `integrating-robot-program.rst` - 1 Java + 1 C++ block (PathWeaver) + +### Software/WPILib-Tools (15 files) ⭐ HIGH PRIORITY + +**Robot Simulation (8 files):** +- `physics-sim.rst` - 3 Java + 3 C++ blocks +- `device-sim.rst` - 5 Java + 5 C++ blocks +- `unit-testing.rst` - 2 Java + 2 C++ blocks +- `simulation-gui.rst` - 1 Java block + +**Drive Simulation Tutorial (4 files):** +- `drivetrain-model.rst` - 3 Java + 3 C++ blocks +- `simulation-instance.rst` - 2 Java + 2 C++ blocks +- `odometry-simgui.rst` - 3 Java + 3 C++ blocks +- `updating-drivetrain-model.rst` - 1 Java + 1 C++ block + +**RobotBuilder (6 files):** +- `robotbuilder-created-code.rst` - 4 Java + 4 C++ blocks +- `robotbuilder-writing-subsystem-code.rst` - 1 Java + 2 C++ blocks +- `robotbuilder-writing-command-code.rst` - 1 Java + 1 C++ block +- `robotbuilder-drive-tank.rst` - 2 C++ blocks +- `robotbuilder-writing-pidsubsystem-code.rst` - 3 Java + 3 C++ blocks +- `robotbuilder-custom-components.rst` - 1 Java + 1 C++ block + +--- + +## Observations & Patterns + +### Documentation Style Patterns + +1. **Tab-set-code blocks** are the most common pattern for multi-language examples +2. **Remote literal includes** pull examples from the allwpilib repository +3. Many files use **inline code blocks** with language specifiers (```java, ```c++) +4. Some files have **many small examples** (10-20 blocks) while others have fewer, larger examples + +### Coverage Patterns + +1. **Sensors and actuators** have the most comprehensive Java/C++ coverage +2. **Command-based framework** docs are thorough but Python-incomplete +3. **Advanced topics** (state-space, custom serialization) tend to be Java-heavy +4. **Tool-specific docs** (RobotBuilder, VS Code) need Python updates + +### Potential Challenges + +Some files may require special consideration: + +1. **RobotBuilder files** - Tool may not fully support Python +2. **Shuffleboard plugins** - Plugin API may be Java-specific +3. **Custom serialization** - Protobuf/struct serialization may differ in Python +4. **State-space controls** - Python implementation may vary from Java/C++ +5. **Units libraries** - Python units handling may differ from Java + +--- + +## Recommendations + +### Phase 1: Core APIs (Priority 1) +Focus on hardware APIs and command-based framework first: +- All 11 hardware-apis files +- All 7 commandbased files +- Target: ~18 files, estimated ~200 code blocks + +### Phase 2: Simulation & Path Planning (Priority 2) +Enable Python teams to use advanced tools: +- 4 path planning files +- 8 simulation files (excluding RobotBuilder for now) +- Target: ~12 files, estimated ~80 code blocks + +### Phase 3: Supporting Features (Priority 3) +Complete remaining documentation: +- Convenience features, telemetry, vision +- VS Code integration +- Target: ~10 files + +### Phase 4: Special Cases (Priority 4) +Review and document limitations: +- RobotBuilder integration +- Dashboard plugins +- Investigate if these should be Python-supported or documented as not applicable + +--- + +## Implementation Strategy + +### For Each File: +1. **Verify Python API exists** - Check that WPILib Python has equivalent functionality +2. **Create Python examples** - Write idiomatic Python code that matches Java/C++ functionality +3. **Add to tab-set-code blocks** - Use same pattern as existing examples +4. **Test examples** - Verify code compiles/runs with current WPILib version +5. **Link to Python API docs** - Add Python documentation links where appropriate + +### Code Example Guidelines: +- Use pythonic naming conventions (snake_case) +- Leverage Python-specific features where appropriate (context managers, decorators) +- Match the semantic meaning, not literal translation +- Keep examples simple and focused +- Include type hints where helpful +- Follow Python style guide (PEP 8) + +--- + +## Resources + +### Generated Files: +- `MISSING_PYTHON_EXAMPLES.md` - Detailed report with all file paths and block counts +- `missing_python_simple_list.txt` - Simple list of file paths for easy reference + +### Useful Links: +- Issue #1818: [Add Python examples throughout documentation] +- RobotPy Documentation: https://robotpy.readthedocs.io/ +- WPILib Python API: https://robotpy.readthedocs.io/projects/robotpy/en/stable/ + +--- + +## Next Steps + +1. **Validate findings** - Review with frc-docs maintainers to confirm priorities +2. **Check Python API coverage** - Ensure all Java/C++ features have Python equivalents +3. **Create example code** - Start with Phase 1 high-priority files +4. **Coordinate with RobotPy team** - Ensure examples align with recommended practices +5. **Track progress** - Use issue #1818 to coordinate multiple contributors + +--- + +**Analysis performed by:** Claude (AI Assistant) +**For:** frc-docs repository maintainers and contributors +**Purpose:** Supporting Issue #1818 - Adding Python examples throughout documentation diff --git a/missing_python_simple_list.txt b/missing_python_simple_list.txt new file mode 100644 index 0000000000..db0d4f98f6 --- /dev/null +++ b/missing_python_simple_list.txt @@ -0,0 +1,58 @@ +# Files needing Python examples (56 total) + +software/hardware-apis/misc/addressable-leds.rst +software/hardware-apis/pneumatics/pressure.rst +software/hardware-apis/pneumatics/solenoids.rst +software/hardware-apis/sensors/accelerometers-software.rst +software/hardware-apis/sensors/analog-inputs-software.rst +software/hardware-apis/sensors/analog-potentiometers-software.rst +software/hardware-apis/sensors/counters.rst +software/hardware-apis/sensors/digital-inputs-software.rst +software/hardware-apis/sensors/encoders-software.rst +software/hardware-apis/sensors/limit-switch.rst +software/hardware-apis/sensors/ultrasonics-software.rst +software/commandbased/binding-commands-to-triggers.rst +software/commandbased/command-scheduler.rst +software/commandbased/organizing-command-based.rst +software/commandbased/pid-subsystems-commands.rst +software/commandbased/profile-subsystems-commands.rst +software/commandbased/profilepid-subsystems-commands.rst +software/commandbased/structuring-command-based-project.rst +software/basic-programming/alliancecolor.rst +software/basic-programming/reading-stacktraces.rst +software/pathplanning/pathweaver/integrating-robot-program.rst +software/pathplanning/trajectory-tutorial/creating-drive-subsystem.rst +software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst +software/pathplanning/trajectory-tutorial/entering-constants.rst +software/wpilib-tools/robot-simulation/device-sim.rst +software/wpilib-tools/robot-simulation/drivesim-tutorial/drivetrain-model.rst +software/wpilib-tools/robot-simulation/drivesim-tutorial/odometry-simgui.rst +software/wpilib-tools/robot-simulation/drivesim-tutorial/simulation-instance.rst +software/wpilib-tools/robot-simulation/drivesim-tutorial/updating-drivetrain-model.rst +software/wpilib-tools/robot-simulation/physics-sim.rst +software/wpilib-tools/robot-simulation/simulation-gui.rst +software/wpilib-tools/robot-simulation/unit-testing.rst +software/wpilib-tools/robotbuilder/advanced/robotbuilder-custom-components.rst +software/wpilib-tools/robotbuilder/advanced/robotbuilder-writing-pidsubsystem-code.rst +software/wpilib-tools/robotbuilder/introduction/robotbuilder-created-code.rst +software/wpilib-tools/robotbuilder/introduction/robotbuilder-testing-with-shuffleboard.rst +software/wpilib-tools/robotbuilder/writing-code/robotbuilder-drive-tank.rst +software/wpilib-tools/robotbuilder/writing-code/robotbuilder-writing-command-code.rst +software/wpilib-tools/robotbuilder/writing-code/robotbuilder-writing-subsystem-code.rst +software/convenience-features/event-based.rst +software/convenience-features/scheduling-functions.rst +software/dashboards/shuffleboard/custom-widgets/creating-a-new-widget.rst +software/dashboards/shuffleboard/custom-widgets/creating-custom-data-types.rst +software/dashboards/shuffleboard/custom-widgets/creating-plugins.rst +software/dashboards/smartdashboard/smartdashboard-namespace.rst +software/advanced-controls/state-space/state-space-pose-estimators.rst +software/advanced-controls/trajectories/troubleshooting.rst +software/networktables/custom-serialization.rst +software/telemetry/robot-telemetry-with-annotations.rst +software/telemetry/writing-sendable-classes.rst +software/vision-processing/introduction/cameraserver-class.rst +software/vscode-overview/creating-robot-program.rst +software/vscode-overview/debugging-robot-program.rst +software/roborio-info/roborio-brownouts.rst +software/can-devices/can-addressing.rst +yearly-overview/2020-Game-Data.rst diff --git a/source/docs/software/advanced-controls/trajectories/ramsete.rst b/source/docs/software/advanced-controls/trajectories/ramsete.rst index 0f8f042e5f..69ff502c8a 100644 --- a/source/docs/software/advanced-controls/trajectories/ramsete.rst +++ b/source/docs/software/advanced-controls/trajectories/ramsete.rst @@ -94,5 +94,6 @@ The returned adjusted speeds can be converted to usable speeds using the kinemat Because these new left and right velocities are still speeds and not voltages, two PID Controllers, one for each side may be used to track these velocities. Either the WPILib PIDController ([C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html), [Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), :external:py:class:`Python `) can be used, or the Velocity PID feature on smart motor controllers such as the TalonSRX and the SPARK MAX can be used. ## Ramsete in the Command-Based Framework -For the sake of ease for users, a ``RamseteCommand`` class is built in to WPILib. For a full tutorial on implementing a path-following autonomous using RamseteCommand, see :ref:`docs/software/pathplanning/trajectory-tutorial/index:Trajectory Tutorial`. + +.. warning:: The ``RamseteCommand`` class has been removed from WPILib. Teams should use modern path planning tools like `PathPlanner `__ or `Choreo `__ instead. See :ref:`docs/software/pathplanning/trajectory-tutorial/index:Trajectory Tutorial` for guidance on using these tools. diff --git a/source/docs/software/commandbased/commands.rst b/source/docs/software/commandbased/commands.rst index 3e79f92b63..d1ea089ac0 100644 --- a/source/docs/software/commandbased/commands.rst +++ b/source/docs/software/commandbased/commands.rst @@ -312,7 +312,7 @@ There are commands for various control setups: - ``SwerveControllerCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/SwerveControllerCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_swerve_controller_command.html)) is useful for controlling swerve drivetrains. See API docs and the **SwerveControllerCommand** ([Java](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/swervecontrollercommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples/src/main/cpp/examples/SwerveControllerCommand)) example project for more info. -- ``RamseteCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/RamseteCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_ramsete_command.html)) is useful for path following with differential drivetrains ("tank drive"). See API docs and the :ref:`Trajectory Tutorial` for more info. +- ``RamseteCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/RamseteCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_ramsete_command.html)) was used for path following with differential drivetrains but has been deprecated. See :ref:`docs/software/pathplanning/trajectory-tutorial/index:Trajectory Tutorial` for modern path planning alternatives like PathPlanner and Choreo. ## Custom Command Classes diff --git a/source/docs/software/pathplanning/pathweaver/integrating-robot-program.rst b/source/docs/software/pathplanning/pathweaver/integrating-robot-program.rst index df723a536d..dbdbc292dc 100644 --- a/source/docs/software/pathplanning/pathweaver/integrating-robot-program.rst +++ b/source/docs/software/pathplanning/pathweaver/integrating-robot-program.rst @@ -4,7 +4,7 @@ The ``TrajectoryUtil`` class can be used to import a PathWeaver JSON into robot The ``fromPathweaverJson`` (Java) / ``FromPathweaverJson`` (C++) static methods in ``TrajectoryUtil`` can be used to create a trajectory from a JSON file stored on the roboRIO file system. -.. important:: To be compatible with the ``Field2d`` view in the simulator GUI, the coordinates for the exported JSON have changed. Previously (before 2021), the range of the y-coordinate was from -27 feet to 0 feet whereas now, the range of the y-coordinate is from 0 feet to 27 feet (with 0 being at the bottom of the screen and 27 feet being at the top). This should not affect teams who are correctly :ref:`resetting their odometry to the starting pose of the trajectory ` before path following. +.. important:: To be compatible with the ``Field2d`` view in the simulator GUI, the coordinates for the exported JSON have changed. Previously (before 2021), the range of the y-coordinate was from -27 feet to 0 feet whereas now, the range of the y-coordinate is from 0 feet to 27 feet (with 0 being at the bottom of the screen and 27 feet being at the top). This should not affect teams who are correctly resetting their odometry to the starting pose of the trajectory before path following. See the :ref:`Trajectory Tutorial ` for guidance on using modern path planning tools. .. note:: PathWeaver places JSON files in ``src/main/deploy/paths`` which will automatically be placed on the roboRIO file system in ``/home/lvuser/deploy/paths`` and can be accessed using getDeployDirectory as shown below. diff --git a/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst b/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst index 914c2d1d0f..f6689516b8 100644 --- a/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst +++ b/source/docs/software/pathplanning/trajectory-tutorial/creating-following-trajectory.rst @@ -1,179 +1,99 @@ -# Step 4: Creating and Following a Trajectory +# Step 4: Using Path Planning Tools -With our drive subsystem written, it is now time to generate a trajectory and write an autonomous command to follow it. +With your drive subsystem configured with odometry and characterized feedforward values, you're now ready to implement autonomous path following using a third-party path planning tool. -As per the :ref:`standard command-based project structure `, we will do this in the ``getAutonomousCommand`` method of the ``RobotContainer`` class. The full method from the RamseteCommand Example Project ([Java](https://github.com/wpilibsuite/allwpilib/tree/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand)) can be seen below. The rest of the article will break down the different parts of the method in more detail. +.. warning:: RamseteCommand has been deprecated and removed from WPILib. This page has been updated to guide teams toward modern path planning solutions. -.. tab-set:: +## Choosing a Path Planning Tool - .. tab-item:: Java - :sync: Java +WPILib no longer provides built-in command-based trajectory following. Instead, teams should use one of these proven third-party tools: - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand/RobotContainer.java - :language: java - :lines: 74-135 - :lineno-match: +### PathPlanner - .. tab-item:: C++ (Source) - :sync: C++ (Source) +`PathPlanner `__ is a popular graphical path planning tool with extensive features: +**Key Features:** +- Graphical path editor with Bézier curves +- Built-in automatic pathfinding (AD* algorithm) +- Event markers for triggering actions during paths +- Hot-reload paths without code redeployment +- Full command-based autonomous routine builder +- Real-time telemetry and path preview - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand/cpp/RobotContainer.cpp - :language: c++ - :lines: 45-94 - :lineno-match: +**Getting Started with PathPlanner:** -## Configuring the Trajectory Constraints +1. **Install PathPlannerLib** as a vendor dependency: -First, we must set some configuration parameters for the trajectory which will ensure that the generated trajectory is followable. + - In VS Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) + - Select "WPILib: Manage Vendor Libraries" + - Choose "Install new libraries (online)" + - Enter the URL: ``https://3015rangerrobotics.github.io/pathplannerlib/PathplannerLib.json`` -### Creating a Voltage Constraint +2. **Configure AutoBuilder** in your drive subsystem constructor: -The first piece of configuration we will need is a voltage constraint. This will ensure that the generated trajectory never commands the robot to go faster than it is capable of achieving with the given voltage supply: + Your drive subsystem needs these methods: -.. tab-set:: + - ``getPose()`` - Returns the current robot pose + - ``resetPose(Pose2d pose)`` - Resets odometry to a specific pose + - ``getRobotRelativeSpeeds()`` - Returns current ChassisSpeeds + - ``driveRobotRelative(ChassisSpeeds speeds)`` - Drives the robot - .. tab-item:: Java - :sync: Java +3. **Set up the path following controller:** - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand/RobotContainer.java - :language: java - :lines: 80-88 - :lineno-match: + - For differential drive: Use ``PPLTVController`` + - For swerve drive: Use ``PPHolonomicDriveController`` - .. tab-item:: C++ (Source) - :sync: C++ (Source) +4. **Learn more:** See the complete `PathPlanner documentation `__ +### Choreo - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand/cpp/RobotContainer.cpp - :language: c++ - :lines: 46-50 - :lineno-match: +`Choreo `__ is a time-optimized trajectory planner designed to maximize robot performance: -Notice that we set the maximum voltage to 10V, rather than the nominal battery voltage of 12V. This gives us some "headroom" to deal with "voltage sag" during operation. +**Key Features:** +- Time-optimized trajectories that respect robot dynamics +- Graphical interface with real-time playback +- Support for waypoints, constraints, and obstacles +- Cross-platform (Windows, macOS, Linux) +- Open source (BSD-3-Clause license) +- Designed to push robots to their physical limits safely -### Creating the Configuration +**Getting Started with Choreo:** -Now that we have our voltage constraint, we can create our ``TrajectoryConfig`` instance, which wraps together all of our path constraints: +1. **Install ChoreoLib** as a vendor dependency: -.. tab-set:: + - In VS Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) + - Select "WPILib: Manage Vendor Libraries" + - Choose "Install new libraries (online)" + - Enter the URL: ``https://lib.choreo.autos/dep/ChoreoLib2025.json`` - .. tab-item:: Java - :sync: Java +2. **Implement trajectory following** in your drive subsystem: + Unlike PathPlanner, Choreo leaves the trajectory following implementation to you. You'll need: - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand/RobotContainer.java - :language: java - :lines: 90-98 - :lineno-match: + - A method to get the robot's current pose + - PID controllers for position and heading correction + - A way to drive field-relatively (swerve) or calculate wheel speeds (differential) - .. tab-item:: C++ (Source) - :sync: C++ (Source) +3. **Learn more:** See the complete `Choreo documentation `__ +## What Happened to WPILib Trajectory Following? - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand/cpp/RobotContainer.cpp - :language: c++ - :lines: 52-58 - :lineno-match: +Prior to 2025, WPILib included ``RamseteCommand`` for trajectory following on differential drives. This has been deprecated and removed because: -## Generating the Trajectory +1. **Third-party tools are more capable** - PathPlanner and Choreo offer graphical interfaces, better tuning, and more features +2. **Easier to use** - Teams can design paths visually instead of specifying waypoints in code +3. **Better maintained** - These tools are actively developed by the FRC community +4. **Industry standard** - Most competitive teams use these tools -With our trajectory configuration in hand, we are now ready to generate our trajectory. For this example, we will be generating a "clamped cubic" trajectory - this means we will specify full robot poses at the endpoints, and positions only for interior waypoints (also known as "knot points"). As elsewhere, all distances are in meters. +The underlying WPILib trajectory generation and following classes (``TrajectoryGenerator``, ``LTVUnicycleController``) are still available for teams who want to implement custom solutions, but command-based wrappers have been removed. -.. tab-set:: +## Next Steps - .. tab-item:: Java - :sync: Java +After completing the previous tutorial steps (characterization, odometry setup, drive subsystem creation), you should: +1. Choose PathPlanner or Choreo based on your team's needs +2. Follow that tool's documentation to install and configure it +3. Design your autonomous paths using the graphical interface +4. Test your autonomous routines incrementally, starting with simple paths - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand/RobotContainer.java - :language: java - :lines: 100-110 - :lineno-match: - - .. tab-item:: C++ (Source) - :sync: C++ (Source) - - - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand/cpp/RobotContainer.cpp - :language: c++ - :lines: 60-69 - :lineno-match: - -.. note:: Instead of generating the trajectory on the roboRIO as outlined above, one can also :ref:`import a PathWeaver JSON `. - -## Creating the RamseteCommand - -We will first reset our robot's pose to the starting pose of the trajectory. This ensures that the robot's location on the coordinate system and the trajectory's starting position are the same. - -.. tab-set:: - - .. tab-item:: Java - :sync: Java - - - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand/RobotContainer.java - :language: java - :lines: 129-131 - :lineno-match: - - .. tab-item:: C++ (Source) - :sync: C++ (Source) - - - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand/cpp/RobotContainer.cpp - :language: c++ - :lines: 84-86 - :lineno-match: - - -It is very important that the initial robot pose match the first pose in the trajectory. For the purposes of our example, the robot will be reliably starting at a position of ``(0,0)`` with a heading of ``0``. In actual use, however, it is probably not desirable to base your coordinate system on the robot position, and so the starting position for both the robot and the trajectory should be set to some other value. If you wish to use a trajectory that has been defined in robot-centric coordinates in such a situation, you can transform it to be relative to the robot's current pose using the ``transformBy`` method ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/trajectory/Trajectory.html#transformBy(edu.wpi.first.math.geometry.Transform2d)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_trajectory.html#a8edfbd82347bbf32ddfb092679336cd8)). For more information about transforming trajectories, see :ref:`docs/software/advanced-controls/trajectories/transforming-trajectories:Transforming Trajectories`. - -Now that we have a trajectory, we can create a command that, when executed, will follow that trajectory. To do this, we use the ``RamseteCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/RamseteCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_ramsete_command.html)) - -.. tab-set:: - - .. tab-item:: Java - :sync: Java - - - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand/RobotContainer.java - :language: java - :lines: 112-127 - :lineno-match: - - .. tab-item:: C++ (Source) - :sync: C++ (Source) - - - .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand/cpp/RobotContainer.cpp - :language: c++ - :lines: 71-82 - :lineno-match: - -This declaration is fairly substantial, so we'll go through it argument-by-argument: - -1. The trajectory: This is the trajectory to be followed; accordingly, we pass the command the trajectory we just constructed in our earlier steps. -2. The pose supplier: This is a method reference (or lambda) to the :ref:`drive subsystem method that returns the pose `. The RAMSETE controller needs the current pose measurement to determine the required wheel outputs. -3. The RAMSETE controller: This is the ``RamseteController`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/RamseteController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_ramsete_controller.html)) that will perform the path-following computation that translates the current measured pose and trajectory state into a chassis speed setpoint. -4. The drive feedforward: This is a ``SimpleMotorFeedforward`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/SimpleMotorFeedforward.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_simple_motor_feedforward.html)) that will automatically perform the correct feedforward calculation with the feedforward gains (``kS``, ``kV``, and ``kA``) that we obtained from the drive identification tool. -5. The drive kinematics: This is the ``DifferentialDriveKinematics`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/kinematics/DifferentialDriveKinematics.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_differential_drive_kinematics.html)) that we constructed earlier in our constants file, and will be used to convert chassis speeds to wheel speeds. -6. The wheel speed supplier: This is a method reference (or lambda) to the :ref:`drive subsystem method that returns the wheel speeds ` -7. The left-side PIDController: This is the ``PIDController`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html)) that will track the left-side wheel speed setpoint, using the P gain that we obtained from the drive identification tool. -8. The right-side PIDController: This is the ``PIDController`` object ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html)) that will track the right-side wheel speed setpoint, using the P gain that we obtained from the drive identification tool. -9. The output consumer: This is a method reference (or lambda) to the :ref:`drive subsystem method that passes the voltage outputs to the drive motors `. -10. The robot drive: This is the drive subsystem itself, included to ensure the command does not operate on the drive at the same time as any other command that uses the drive. - -Finally, note that we append a final "stop" command in sequence after the path-following command, to ensure that the robot stops moving at the end of the trajectory. - -## Video - -If all has gone well, your robot's autonomous routine should look something like this: - -.. raw:: html - -
- -.. raw:: html - -
+Both tools have active communities on Chief Delphi and provide example code to help you get started. diff --git a/source/docs/software/pathplanning/trajectory-tutorial/index.rst b/source/docs/software/pathplanning/trajectory-tutorial/index.rst index 00c3bcb26e..4a5e50b604 100644 --- a/source/docs/software/pathplanning/trajectory-tutorial/index.rst +++ b/source/docs/software/pathplanning/trajectory-tutorial/index.rst @@ -1,6 +1,14 @@ # Trajectory Tutorial -This is full tutorial for implementing trajectory generation and following on a differential-drive robot. The full code used in this tutorial can be found in the RamseteCommand example project ([Java](https://github.com/wpilibsuite/allwpilib/tree/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand)). +.. warning:: RamseteCommand has been deprecated and removed. Teams should use `PathPlanner `__ or `Choreo `__ for autonomous path planning. + +This tutorial covers the **WPILib setup prerequisites** needed before using modern path planning tools. It will guide you through: + +1. Characterizing your drivetrain with SysId +2. Setting up pose estimation with odometry +3. Creating a drive subsystem compatible with path planning libraries + +After completing this tutorial, refer to the documentation for your chosen path planning tool to implement autonomous routines. .. toctree:: :maxdepth: 1 diff --git a/source/docs/software/pathplanning/trajectory-tutorial/trajectory-tutorial-overview.rst b/source/docs/software/pathplanning/trajectory-tutorial/trajectory-tutorial-overview.rst index 0cc9468537..7cd00d004f 100644 --- a/source/docs/software/pathplanning/trajectory-tutorial/trajectory-tutorial-overview.rst +++ b/source/docs/software/pathplanning/trajectory-tutorial/trajectory-tutorial-overview.rst @@ -2,22 +2,39 @@ # Trajectory Tutorial Overview -.. warning:: This tutorial uses the Ramsete Controller which has been :term:`deprecated`. The replacement is :doc:`LTV Unicycle Controller ` which has more intuitive tuning. We are looking for volunteers to [update this tutorial](https://github.com/wpilibsuite/frc-docs/issues/2651). +.. warning:: The Ramsete Controller and RamseteCommand have been :term:`deprecated` and removed from WPILib. **Teams are strongly recommended to use third-party path planning tools** like `PathPlanner `__ or `Choreo `__ instead of the built-in WPILib trajectory following. -.. note:: Before following this tutorial, it is helpful (but not strictly necessary) to have a baseline familiarity with WPILib's :ref:`PID control `, :ref:`feedforward `, and :ref:`trajectory ` features. +This tutorial focuses on the **WPILib prerequisites** needed before using modern path planning tools. By following this tutorial, readers will learn how to: -.. note:: The robot code in this tutorial uses the :ref:`command-based ` framework. The command-based framework is strongly recommended for beginning and intermediate teams. +1. Accurately characterize their robot's drivetrain to obtain accurate feedforward calculations. +2. Configure a drive subsystem to track the robot's pose using WPILib's odometry library. +3. Understand what robot capabilities are needed for path following. -The goal of this tutorial is to provide "end-to-end" instruction on implementing a trajectory-following autonomous routine for a differential-drive robot. By following this tutorial, readers will learn how to: +Once you've completed the setup steps in this tutorial, you'll be ready to use a path planning tool for autonomous routines. -1. Accurately characterize their robot's drivetrain to obtain accurate feedforward calculations and approximate feedback gains. -2. Configure a drive subsystem to track the robot's pose using WPILib's odometry library. -3. Generate a simple trajectory through a set of waypoints using WPILib's ``TrajectoryGenerator`` class. -4. Follow the generated trajectory in an autonomous routine using WPILib's ``RamseteCommand`` class with the calculated feedforward/feedback gains and pose. +## Recommended Path Planning Tools + +Modern FRC teams typically use one of these third-party tools for autonomous path planning: -This tutorial is intended to be approachable for teams without a great deal of programming expertise. While the WPILib library offers significant flexibility in the manner in which its trajectory-following features are implemented, closely following the implementation outlined in this tutorial should provide teams with a relatively-simple, clean, and repeatable solution for autonomous movement. +**PathPlanner** (`pathplanner.dev `__) + - Graphical path editor with Bézier curves + - Built-in automatic pathfinding (AD* algorithm) + - Event markers for triggering actions along paths + - Hot-reload paths without redeploying code + - Supports both differential and holonomic drivetrains + - Uses PPLTVController (differential) or PPHolonomicDriveController (swerve) + - See `PathPlanner Documentation `__ -The full robot code for this tutorial can be found in the RamseteCommand Example Project ([Java](https://github.com/wpilibsuite/allwpilib/tree/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteCommand)). +**Choreo** (`choreo.autos `__) + - Time-optimized trajectory planning + - Designed to maximize drivetrain performance + - Graphical interface with real-time playback + - Supports waypoints, constraints, and obstacles + - Cross-platform (Windows, macOS, Linux) + - Open source (BSD-3-Clause license) + - See `Choreo Documentation `__ + +Both tools handle trajectory generation and path following, allowing teams to focus on designing effective autonomous routines rather than implementing low-level control algorithms. ## Why Trajectory Following? @@ -27,17 +44,37 @@ While the "drive-turn-drive" approach is certainly functional, in recent years t Beginning in 2020, WPILib now supplies teams with working, advanced code solutions for trajectory generation and tracking, significantly lowering the "barrier-to-entry" for this kind of advanced and effective autonomous motion. -## Required Equipment +## Prerequisites for Path Planning + +To follow this tutorial and prepare your robot for path planning tools, you will need: -To follow this tutorial, you will need ready access to the following materials: +**Robot Hardware:** 1. A differential-drive robot (such as the [AndyMark AM14U5](https://www.andymark.com/products/am14u5-6-wheel-drop-center-robot-drive-base-first-kit-of-parts-chassis)), equipped with: -* Quadrature encoders for measuring the wheel rotation of each side of the drive. -* A gyroscope for measuring robot heading. + * Quadrature encoders for measuring the wheel rotation of each side of the drive + * A gyroscope for measuring robot heading (required for pose estimation) + +**Software:** 2. A driver-station computer configured with: -* :ref:`FRC Driver Station `. -* :ref:`WPILib `. -* :ref:`The System Identification Toolsuite `. + * :ref:`FRC Driver Station ` + * :ref:`WPILib ` + * :ref:`The System Identification Toolsuite ` + +3. Your chosen path planning tool: + + * `PathPlanner `__ (available on Microsoft Store or GitHub) + * `Choreo `__ (cross-platform desktop application) + +**Robot Code Requirements:** + +After completing this tutorial, your drive subsystem will need these capabilities for PathPlanner/Choreo: + +* ``getPose()`` - Returns current robot pose (x, y, heading) +* ``resetPose()`` - Resets odometry to a given pose +* ``getRobotRelativeSpeeds()`` or equivalent - Returns current chassis speeds +* ``driveRobotRelative()`` or equivalent - Drives using robot-relative chassis speeds + +These methods are standard for any pose-tracking drive subsystem and will be covered in this tutorial.