yams::motorcontrollers::simulation::BatterySim Class Reference

#include <BatterySim.hpp>

Static Public Member Functions
static wpi::units::volt_t	CalculateVoltage (const void *id, wpi::units::ampere_t current)
static void	ReplaceSOCInterpolation (const std::map< double, double > &socToVoltage)
static void	ReplaceCapacityDerating (const std::map< double, double > &currentToCapacityFraction)
static void	EnableDischarge (double batteryCapacityAmpHours, wpi::units::volt_t nominalVoltage, wpi::units::ohm_t nominalResistance)
static void	DisableDischarge ()
static void	ResetDischarge ()
static double	GetStateOfCharge ()
static void	RemoveCurrent (const void *id)
static void	Reset ()
static bool	HasCurrent (const void *id)

Static Public Attributes
static wpi::units::volt_t	BatteryVoltage
static wpi::units::ohm_t	BatteryResistance

Detailed Description

Battery Simulation that takes the entirety of the robot into account by storing all currently used currents on the robot.

Each simulated mechanism should call CalculateVoltage() every simulation iteration with a stable, unique identity (e.g. the address of its SimSupplier instance) and its own current draw. The result accounts for the combined current draw of every registered mechanism, and should be fed into wpi::sim::RoboRioSim::SetVInVoltage().

Thread safe: every method locks one shared mutex, so mechanisms can run their simulation in their own wpi::Notifier while sharing the one battery. BatteryVoltage and BatteryResistance are read under that lock, so set them before the simulation threads start, or through EnableDischarge().

Member Function Documentation

CalculateVoltage()

static wpi::units::volt_t yams::motorcontrollers::simulation::BatterySim::CalculateVoltage ( const void *  id, wpi::units::ampere_t  current  )

static

Calculate the voltage based on the currents used by the robot.

Parameters

id	Stable, unique identity of the simulation to calculate the voltage for.
current	Current used by the robot.

Returns

Loaded voltage of the robot.

DisableDischarge()

static void yams::motorcontrollers::simulation::BatterySim::DisableDischarge ( )

static

Disable battery discharge simulation, reverting to a constant BatteryVoltage and BatteryResistance.

EnableDischarge()

static void yams::motorcontrollers::simulation::BatterySim::EnableDischarge ( double  batteryCapacityAmpHours, wpi::units::volt_t  nominalVoltage, wpi::units::ohm_t  nominalResistance  )

static

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.
nominalVoltage	Nominal (fully charged) open circuit voltage of the battery.
nominalResistance	Nominal internal resistance of the battery.

GetStateOfCharge()

static double yams::motorcontrollers::simulation::BatterySim::GetStateOfCharge ( )

static

Get the simulated state of charge of the battery, from 0 (empty) to 1 (full).

Returns

State of charge of the battery.

HasCurrent()

static bool yams::motorcontrollers::simulation::BatterySim::HasCurrent ( const void *  id )

static

Whether a current draw is tracked for the given consumer.

Parameters

id	Key the consumer's current was registered under.

Returns

true if a current is tracked for id.

RemoveCurrent()

static void yams::motorcontrollers::simulation::BatterySim::RemoveCurrent ( const void *  id )

static

Stop counting the given consumer's current draw towards the shared battery load, e.g. once its SmartMotorController has been closed.

Parameters

id	Key the consumer's current was registered under (the SmartMotorController).

ReplaceCapacityDerating()

static void yams::motorcontrollers::simulation::BatterySim::ReplaceCapacityDerating ( const std::map< double, double > &  currentToCapacityFraction )

static

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() so discharge simulation uses the new curve from the start.

ReplaceSOCInterpolation()

static void yams::motorcontrollers::simulation::BatterySim::ReplaceSOCInterpolation ( const std::map< double, double > &  socToVoltage )

static

Replace the default state-of-charge -> open circuit voltage interpolation table used when discharge simulation is enabled with EnableDischarge().

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.
std::map<double, double> wornBatteryCurve{
    {0.00, 8.0},  {0.05, 9.5},  {0.10, 10.5}, {0.20, 11.2}, {0.40, 11.6},
    {0.60, 11.9}, {0.80, 12.2}, {0.90, 12.4}, {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, wpi::units::volt_t{12.6}, wpi::units::ohm_t{0.028});

Parameters

socToVoltage

Interpolation table mapping state of charge [0, 1] to open circuit voltage. Call this before EnableDischarge() so discharge simulation uses the new curve from the start.

Reset()

static void yams::motorcontrollers::simulation::BatterySim::Reset ( )

static

Clear every tracked current draw and reset discharge simulation to a fresh, fully-charged, disabled state.

ResetDischarge()

static void yams::motorcontrollers::simulation::BatterySim::ResetDischarge ( )

static

Reset the simulated battery back to a full charge.

Member Data Documentation

BatteryResistance

wpi::units::ohm_t yams::motorcontrollers::simulation::BatterySim::BatteryResistance

static

Battery internal resistance, used when discharge simulation is disabled.

BatteryVoltage

wpi::units::volt_t yams::motorcontrollers::simulation::BatterySim::BatteryVoltage

static

Battery open circuit voltage, used when discharge simulation is disabled.

---

The documentation for this class was generated from the following file:

• /home/runner/work/YAMS/YAMS/yams/cpp/include/yams/motorcontrollers/simulation/BatterySim.hpp