Merge branch 'main' into document-updater

choreolib/build.gradle

@@ -6,7 +6,7 @@ plugins {
     id 'java-library'
     id 'google-test'
     id 'edu.wpi.first.wpilib.repositories.WPILibRepositoriesPlugin' version '2020.2'
-    id 'edu.wpi.first.NativeUtils' version '2025.3.0'
+    id 'edu.wpi.first.NativeUtils' version '2025.6.0'
     id 'edu.wpi.first.GradleJni' version '1.1.0'
     id 'edu.wpi.first.GradleVsCode' version '2.1.0'
     id 'com.diffplug.spotless' version '6.25.0'
@@ -156,6 +156,10 @@ model {
     }
 }
 
+compileJava {
+    options.encoding = 'UTF-8'
+}
+
 spotless {
     java {
         target fileTree('.') {
@@ -228,5 +232,5 @@ test {
 apply from: 'publish.gradle'
 
 wrapper {
-    gradleVersion '8.5'
+    gradleVersion '8.11'
 }

choreolib/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

choreolib/gradlew

@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+# SPDX-License-Identifier: Apache-2.0
+#
 
 ##############################################################################
 #
@@ -55,7 +57,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -84,7 +86,8 @@ done
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
 # Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
-APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum

choreolib/gradlew.bat

@@ -13,6 +13,8 @@
 @rem See the License for the specific language governing permissions and
 @rem limitations under the License.
 @rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
 
 @if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
@@ -43,11 +45,11 @@ set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
 if %ERRORLEVEL% equ 0 goto execute
 
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 
@@ -57,11 +59,11 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
 if exist "%JAVA_EXE%" goto execute
 
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 

choreolib/py/choreo/__init__.py

@@ -1,6 +1,5 @@
 import json
 
-from choreo.spec_version import SPEC_VERSION
 from choreo.trajectory import (
     DifferentialSample,
     DifferentialTrajectory,
@@ -10,6 +9,8 @@
     load_event_marker,
 )
 
+SPEC_VERSION = "v2025.0.0"
+
 
 def load_differential_trajectory_string(
     trajectory_json_string: str,

choreolib/py/choreo/trajectory/__init__.py

@@ -4,7 +4,6 @@
 import math
 import os
 
-from choreo.spec_version import SPEC_VERSION
 from choreo.util import DEFAULT_YEAR, get_flipper_for_year
 from wpimath.geometry import Pose2d, Rotation2d
 from wpimath.kinematics import ChassisSpeeds
@@ -131,6 +130,7 @@ def get_chassis_speeds(self) -> ChassisSpeeds:
         """
         Returns the field-relative chassis speeds of this state.
         """
+        from choreo import SPEC_VERSION
         from wpilib import getDeployDirectory
 
         # Get only .chor file in deploy directory

choreolib/src/main/java/choreo/Choreo.java

@@ -92,7 +92,7 @@ public static ProjectFile getProjectFile() {
     } catch (FileNotFoundException ex) {
       throw new RuntimeException("Could not find project file", ex);
     } catch (IOException ex) {
-      throw new RuntimeException("Could not find project file", ex);
+      throw new RuntimeException("Could not close the project file", ex);
     }
     return LAZY_PROJECT_FILE.get();
   }

choreolib/src/main/java/choreo/auto/AutoChooser.java

@@ -13,13 +13,16 @@
 import java.util.function.Function;
 
 /**
- * An auto chooser that allows for the selection of auto routines at runtime.
+ * An Choreo specific {@code SendableChooser} that allows for the selection of {@link AutoRoutine}s
+ * at runtime via a <a
+ * href="https://docs.wpilib.org/en/stable/docs/software/dashboards/index.html#dashboards">Dashboard</a>.
  *
- * <p>This chooser takes a lazy loading approach to auto routines, only generating the auto routine
- * when it is selected. This approach has the benefit of not loading all autos on startup, but also
- * not loading the auto during auto start causing a delay.
+ * <p>This chooser takes a <a href="https://en.wikipedia.org/wiki/Lazy_loading">lazy loading</a>
+ * approach to {@link AutoRoutine}s, only generating the {@link AutoRoutine} when it is selected.
+ * This approach has the benefit of not loading all autos on startup, but also not loading the auto
+ * during auto start causing a delay.
  *
- * <p>Once the {@link AutoChooser} is made you can add auto routines to it using the {@link
+ * <p>Once the {@link AutoChooser} is made you can add {@link AutoRoutine}s to it using the {@link
  * #addAutoRoutine(String, AutoRoutineGenerator)} method. Unlike {@code SendableChooser} this
  * chooser has to be updated every cycle by calling the {@link #update()} method in your {@link
  * IterativeRobotBase#robotPeriodic()}.
@@ -48,16 +51,20 @@ public static interface AutoRoutineGenerator extends Function<AutoFactory, AutoR
   private AutoRoutine lastAutoRoutine = AutoRoutineGenerator.NONE.apply(null);
 
   /**
-   * Create a new auto chooser.
+   * Constructs a new {@link AutoChooser}.
    *
-   * @param factory The auto factory to use for auto routine generation.
-   * @param tableName The name of the network table to use for the chooser, passing in an empty
-   *     string will put this chooser at the root of the network tables.
+   * @param factory The auto factory to use for AutoRoutine creation.
+   * @param tableName The name of the network table to use for the chooser. Passing in an empty
+   *     string or null will put this chooser at the root of the network tables.
    */
   public AutoChooser(AutoFactory factory, String tableName) {
     this.factory = factory;
 
-    String path = NetworkTable.normalizeKey(tableName, true) + "/AutoChooser";
+    if (tableName == null) {
+      tableName = "";
+    }
+    String path =
+        (tableName.isEmpty()) ? NetworkTable.normalizeKey(tableName, true) : "" + "/AutoChooser";
     NetworkTable table = NetworkTableInstance.getDefault().getTable(path);
 
     selected = table.getStringTopic("selected").getEntry(NONE_NAME);
@@ -72,10 +79,14 @@ public AutoChooser(AutoFactory factory, String tableName) {
    * Update the auto chooser.
    *
    * <p>This method should be called every cycle in the {@link IterativeRobotBase#robotPeriodic()}.
-   * It will check if the selected auto routine has changed and update the active auto routine.
+   * It will check if the selected auto routine has changed and update the active AutoRoutine.
+   *
+   * <p>The AutoRoutine can only be updated when the robot is disabled. If the chooser in your
+   * dashboard says {@code BAD} the {@link AutoChooser} has not responded to the selection yet and
+   * you need to disable the robot to update it.
    */
   public void update() {
-    if (DriverStation.isDisabled() || IterativeRobotBase.isSimulation()) {
+    if (DriverStation.isDisabled()) {
       String selectStr = selected.get();
       if (selectStr.equals(lastAutoRoutineName)) return;
       if (!autoRoutines.containsKey(selectStr)) {
@@ -90,14 +101,33 @@ public void update() {
   }
 
   /**
-   * Add an auto routine to the chooser.
+   * Add an AutoRoutine to the chooser.
+   *
+   * <p>The options of the chooser are actually of type {@link AutoRoutineGenerator}. This is a
+   * function that takes an {@link AutoFactory} and returns a {@link AutoRoutine}. These functions
+   * can be static, a lambda or belong to a local variable.
+   *
+   * <p>This is done to load AutoRoutines when and only when they are selected, in order to save
+   * memory and file loading time for unused AutoRoutines.
    *
-   * <p>An auto routine is a function that takes an AutoFactory and returns a AutoRoutine. These
-   * functions can be static, a lambda or belong to a local variable.
+   * <p>One way to keep this clean is to make an `Autos` class that all of your subsystems/resources
+   * are <a href="https://en.wikipedia.org/wiki/Dependency_injection">dependency injected</a> into.
+   * Then create methods inside that class that take an {@link AutoFactory} and return an {@link
+   * AutoRoutine}.
    *
-   * <p>A good paradigm is making an `AutoRoutines` class that has a reference to all your
-   * subsystems and has helper methods for auto commands inside it. Then you crate methods inside
-   * that class that take an `AutoFactory` and return a `Command`.
+   * <h3>Example:</h3>
+   *
+   * <pre><code>
+   * AutoChooser chooser;
+   * Autos autos = new Autos(swerve, shooter, intake, feeder);
+   * Robot() {
+   *   chooser = new AutoChooser(Choreo.createAutoFactory(...), "/Choosers");
+   *   chooser.addAutoRoutine("4 Piece right", autos::fourPieceRight);
+   *   chooser.addAutoRoutine("4 Piece Left", autos::fourPieceLeft);
+   *   chooser.addAutoRoutine("3 Piece Close", autos::threePieceClose);
+   *   chooser.addAutoRoutine("Just Shoot", factory -> factory.commandAsAutoRoutine(shooter.shoot()));
+   * }
+   * </code></pre>
    *
    * @param name The name of the auto routine.
    * @param generator The function that generates the auto routine.
@@ -108,9 +138,40 @@ public void addAutoRoutine(String name, AutoRoutineGenerator generator) {
   }
 
   /**
-   * Get the currently selected auto routine.
+   * Get the currently selected {@link AutoRoutine}.
+   *
+   * <h3>Recommended Usage</h3>
+   *
+   * Scheduling it as a command.
+   *
+   * <pre><code>
+   * AutoChooser chooser = ...;
+   *
+   * public void autonomousInit() {
+   *   CommandScheduler.getInstance().schedule(chooser.getSelectedAutoRoutine().cmd());
+   * }
+   * </code></pre>
+   *
+   * Polling it yourself.
+   *
+   * <pre><code>
+   * AutoChooser chooser = ...;
+   * AutoRoutine routine = chooser.getSelectedAutoRoutine();
+   *
+   * public void autonomousInit() {
+   *   routine = chooser.getSelectedAutoRoutine();
+   * }
+   *
+   * public void autonomousPeriodic() {
+   *  routine.poll();
+   * }
+   *
+   * public void autonomousExit() {
+   *   routine.reset();
+   * }
+   * </code></pre>
    *
-   * @return The currently selected auto routine.
+   * @return The currently selected {@link AutoRoutine}.
    */
   public AutoRoutine getSelectedAutoRoutine() {
     return lastAutoRoutine;