Class BatterySim

java.lang.Object
yams.core.motorcontrollers.simulation.BatterySim
public class BatterySim extends Object
Battery Simulation that takes the entirety of the robot into account by storing all currently used currents on the robot.

Thread safe: every method synchronizes on this class, so mechanisms can run their simulation in their own Notifiers while sharing the one battery.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    calculateVoltage(UUID id, double current)
    Calculate the voltage based on the currents used by the robot.
    static double
    calculateVoltage(UUID id, org.wpilib.units.measure.Current current)
    Calculate the voltage based on the currents used by the robot.
    static void
    disableDischarge()
    Disable battery discharge simulation, reverting to a constant batteryVoltage and batteryResistance.
    static void
    enableDischarge(double batteryCapacityAmpHours, org.wpilib.units.measure.Voltage nomVoltage, org.wpilib.units.measure.Resistance nomResistance)
    Enable realistic battery discharge simulation.
    static double
    getStateOfCharge()
    Get the simulated state of charge of the battery, from 0 (empty) to 1 (full).
    static void
    removeCurrent(UUID id)
    Stop counting the given simulation's current draw towards the shared battery load, e.g.
    static void
    replaceCapacityDerating(org.wpilib.math.interpolation.InterpolatingDoubleTreeMap currentToCapacityFraction)
    Replace the default discharge current → capacity fraction interpolation table used to derate the battery's usable amp-hour capacity at high discharge rates (the Peukert effect).
    static void
    replaceSOCInterpolation(org.wpilib.math.interpolation.InterpolatingDoubleTreeMap socToVoltage)
    Replace the default state-of-charge → open circuit voltage interpolation table used when discharge simulation is enabled with enableDischarge(double, Voltage, Resistance).
    static void
    reset()
    Clear every tracked per-consumer current draw and reset discharge simulation to a fresh, fully-charged, disabled state.
    static void
    resetDischarge()
    Reset the simulated battery back to a full charge.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • replaceSOCInterpolation

      public static void replaceSOCInterpolation(org.wpilib.math.interpolation.InterpolatingDoubleTreeMap socToVoltage)
      Replace the default state-of-charge → open circuit voltage interpolation table used when discharge simulation is enabled with enableDischarge(double, Voltage, Resistance).

      Not every battery discharges like YAMS's built-in sealed lead-acid curve. Reach for this method when you want to model something different, for example:

      • A well-used competition battery that sags earlier and harder than a fresh one.
      • Matching a curve you measured from an actual battery on a load tester, for the most accurate brownout predictions possible. 
      // Model a well-used competition battery that sags earlier and more severely than a new one.
InterpolatingDoubleTreeMap wornBatteryCurve = new InterpolatingDoubleTreeMap();
wornBatteryCurve.put(0.00, 8.0);
wornBatteryCurve.put(0.05, 9.5);
wornBatteryCurve.put(0.10, 10.5);
wornBatteryCurve.put(0.20, 11.2);
wornBatteryCurve.put(0.40, 11.6);
wornBatteryCurve.put(0.60, 11.9);
wornBatteryCurve.put(0.80, 12.2);
wornBatteryCurve.put(0.90, 12.4);
wornBatteryCurve.put(1.00, 12.6);

BatterySim.replaceSOCInterpolation(wornBatteryCurve);
// Pair with a reduced usable capacity and higher resistance to match a worn battery.
BatterySim.enableDischarge(15.0, Volts.of(12.6), MilliOhms.of(28));
      Parameters:
      socToVoltage - Interpolation table mapping state of charge [0, 1] to open circuit voltage. Call this before enableDischarge(double, Voltage, Resistance) so discharge simulation uses the new curve from the start.

    • replaceCapacityDerating

      public static void replaceCapacityDerating(org.wpilib.math.interpolation.InterpolatingDoubleTreeMap currentToCapacityFraction)
      Replace the default discharge current → capacity fraction interpolation table used to derate the battery's usable amp-hour capacity at high discharge rates (the Peukert effect).

      Reach for this if you have measured discharge-rate-vs-capacity data for your specific battery, for example from a load tester, rather than the averaged multi-manufacturer defaults.

      Parameters:
      currentToCapacityFraction - Interpolation table mapping discharge current in Amps to the fraction (0 to 1) of the nominal amp-hour capacity delivered at that current. Call this before enableDischarge(double, Voltage, Resistance) so discharge simulation uses the new curve from the start.

    • enableDischarge

      public static void enableDischarge(double batteryCapacityAmpHours, org.wpilib.units.measure.Voltage nomVoltage, org.wpilib.units.measure.Resistance nomResistance)
      Enable realistic battery discharge simulation. As current is drawn from the battery over time its state of charge will drop, reducing the open circuit voltage and increasing the internal resistance to more realistically model a depleted battery.
      Parameters:
      batteryCapacityAmpHours - Capacity of the battery in amp-hours (Ah). A typical FRC battery is around 18 Ah.
      nomVoltage - Nominal (fully charged) open circuit voltage of the battery.
      nomResistance - Nominal internal resistance of the battery.

    • disableDischarge

      public static void disableDischarge()
      Disable battery discharge simulation, reverting to a constant batteryVoltage and batteryResistance.

    • resetDischarge

      public static void resetDischarge()
      Reset the simulated battery back to a full charge.

    • removeCurrent

      public static void removeCurrent(UUID id)
      Stop counting the given simulation's current draw towards the shared battery load, e.g. once its SmartMotorController has been closed. Without this, a closed simulation's last-known current draw would linger in currents indefinitely.
      Parameters:
      id - UUID of the simulation to remove.

    • reset

      public static void reset()
      Clear every tracked per-consumer current draw and reset discharge simulation to a fresh, fully-charged, disabled state.

    • getStateOfCharge

      public static double getStateOfCharge()
      Get the simulated state of charge of the battery, from 0 (empty) to 1 (full).
      Returns:
      State of charge of the battery.

    • calculateVoltage

      public static double calculateVoltage(UUID id, double current)
      Calculate the voltage based on the currents used by the robot.
      Parameters:
      id - UUID of the simulation to calculate the voltage for.
      current - Amps used by the robot.
      Returns:
      Voltage of the robot.

    • calculateVoltage

      public static double calculateVoltage(UUID id, org.wpilib.units.measure.Current current)
      Calculate the voltage based on the currents used by the robot.
      Parameters:
      id - UUID of the simulation to calculate the voltage for.
      current - Amps used by the robot.
      Returns:
      Voltage of the robot.