[wpilib] Update GetMatchTime docs and units (#5232)

hal/src/main/native/include/hal/DriverStation.h

@@ -181,20 +181,25 @@ int32_t HAL_SetJoystickOutputs(int32_t joystickNum, int64_t outputs,
                                int32_t leftRumble, int32_t rightRumble);
 
 /**
- * Returns the approximate match time.
- *
- * The FMS does not send an official match time to the robots, but does send
- * an approximate match time. The value will count down the time remaining in
- * the current period (auto or teleop).
- *
+ * Return the approximate match time. The FMS does not send an official match
+ * time to the robots, but does send an approximate match time. The value will
+ * count down the time remaining in the current period (auto or teleop).
  * Warning: This is not an official time (so it cannot be used to dispute ref
  * calls or guarantee that a function will trigger before the match ends).
  *
- * The Practice Match function of the DS approximates the behavior seen on
- * the field.
+ * <p>When connected to the real field, this number only changes in full integer
+ * increments, and always counts down.
+ *
+ * <p>When the DS is in practice mode, this number is a floating point number,
+ * and counts down.
+ *
+ * <p>When the DS is in teleop or autonomous mode, this number is a floating
+ * point number, and counts up.
+ *
+ * <p>Simulation matches DS behavior without an FMS connected.
  *
  * @param[out] status the error code, or 0 for success
- * @return time remaining in current match period (auto or teleop)
+ * @return Time remaining in current match period (auto or teleop) in seconds
  */
 double HAL_GetMatchTime(int32_t* status);
 

wpilibc/src/main/native/cpp/DriverStation.cpp

@@ -582,9 +582,9 @@ bool DriverStation::WaitForDsConnection(units::second_t timeout) {
   return result;
 }
 
-double DriverStation::GetMatchTime() {
+units::second_t DriverStation::GetMatchTime() {
   int32_t status = 0;
-  return HAL_GetMatchTime(&status);
+  return units::second_t{HAL_GetMatchTime(&status)};
 }
 
 double DriverStation::GetBatteryVoltage() {

wpilibc/src/main/native/cpp/Timer.cpp

@@ -90,5 +90,5 @@ units::second_t Timer::GetFPGATimestamp() {
 }
 
 units::second_t Timer::GetMatchTime() {
-  return units::second_t{frc::DriverStation::GetMatchTime()};
+  return frc::DriverStation::GetMatchTime();
 }

wpilibc/src/main/native/include/frc/DriverStation.h

@@ -306,21 +306,26 @@ class DriverStation final {
   static bool WaitForDsConnection(units::second_t timeout);
 
   /**
-   * Return the approximate match time.
-   *
-   * The FMS does not send an official match time to the robots, but does send
-   * an approximate match time. The value will count down the time remaining in
-   * the current period (auto or teleop).
-   *
+   * Return the approximate match time. The FMS does not send an official match
+   * time to the robots, but does send an approximate match time. The value will
+   * count down the time remaining in the current period (auto or teleop).
    * Warning: This is not an official time (so it cannot be used to dispute ref
    * calls or guarantee that a function will trigger before the match ends).
    *
-   * The Practice Match function of the DS approximates the behavior seen on
-   * the field.
+   * <p>When connected to the real field, this number only changes in full
+   * integer increments, and always counts down.
    *
-   * @return Time remaining in current match period (auto or teleop)
+   * <p>When the DS is in practice mode, this number is a floating point number,
+   * and counts down.
+   *
+   * <p>When the DS is in teleop or autonomous mode, this number is a floating
+   * point number, and counts up.
+   *
+   * <p>Simulation matches DS behavior without an FMS connected.
+   *
+   * @return Time remaining in current match period (auto or teleop) in seconds
    */
-  static double GetMatchTime();
+  static units::second_t GetMatchTime();
 
   /**
    * Read the battery voltage.

wpilibc/src/test/native/cpp/simulation/DriverStationSimTest.cpp

@@ -230,7 +230,7 @@ TEST(DriverStationTest, MatchTime) {
   DriverStationSim::SetMatchTime(kTestTime);
   frc::sim::DriverStationSim::NotifyNewData();
   EXPECT_EQ(kTestTime, DriverStationSim::GetMatchTime());
-  EXPECT_EQ(kTestTime, DriverStation::GetMatchTime());
+  EXPECT_EQ(kTestTime, DriverStation::GetMatchTime().value());
   EXPECT_TRUE(callback.WasTriggered());
   EXPECT_EQ(kTestTime, callback.GetLastValue());
 }

wpilibcExamples/src/main/cpp/examples/DigitalCommunication/cpp/Robot.cpp

@@ -19,7 +19,7 @@ void Robot::RobotPeriodic() {
 
   // pull alert port high if match time remaining is between 30 and 25 seconds
   auto matchTime = frc::DriverStation::GetMatchTime();
-  m_alertOutput.Set(matchTime <= 30 && matchTime >= 25);
+  m_alertOutput.Set(matchTime <= 30_s && matchTime >= 25_s);
 }
 
 #ifndef RUNNING_FRC_TESTS

wpilibj/src/main/java/edu/wpi/first/wpilibj/DriverStation.java

@@ -1183,8 +1183,17 @@ public final class DriverStation {
    * Return the approximate match time. The FMS does not send an official match time to the robots,
    * but does send an approximate match time. The value will count down the time remaining in the
    * current period (auto or teleop). Warning: This is not an official time (so it cannot be used to
-   * dispute ref calls or guarantee that a function will trigger before the match ends) The Practice
-   * Match function of the DS approximates the behavior seen on the field.
+   * dispute ref calls or guarantee that a function will trigger before the match ends).
+   *
+   * <p>When connected to the real field, this number only changes in full integer increments, and
+   * always counts down.
+   *
+   * <p>When the DS is in practice mode, this number is a floating point number, and counts down.
+   *
+   * <p>When the DS is in teleop or autonomous mode, this number is a floating point number, and
+   * counts up.
+   *
+   * <p>Simulation matches DS behavior without an FMS connected.
    *
    * @return Time remaining in current match period (auto or teleop) in seconds
    */