A Discrete-Event Network Simulator
API
ns3::GenericBatteryModel Class Reference

A generic battery model for Li-Ion, NiCd, NiMh and Lead acid batteries. More...

#include "generic-battery-model.h"

+ Inheritance diagram for ns3::GenericBatteryModel:
+ Collaboration diagram for ns3::GenericBatteryModel:

Public Member Functions

 GenericBatteryModel ()
 
 ~GenericBatteryModel () override
 
double GetDrainedCapacity () const
 Obtain the amount of drained capacity from the battery based on the integral of the current over time (Coulomb counting method). More...
 
double GetEnergyFraction () override
 Implements GetEnergyFraction. More...
 
Time GetEnergyUpdateInterval () const
 
double GetInitialEnergy () const override
 Implements GetInitialEnergy. More...
 
double GetRemainingEnergy () override
 Implements GetRemainingEnergy. More...
 
double GetStateOfCharge () const
 Calculates an estimate of the State of Charge (SoC). More...
 
double GetSupplyVoltage () const override
 Implements GetSupplyVoltage. More...
 
void SetDrainedCapacity (double drainedCapacity)
 This function is used to change the initial capacity in the battery. More...
 
void SetEnergyUpdateInterval (Time interval)
 This function sets the interval between each energy update. More...
 
void UpdateEnergySource () override
 Implements UpdateEnergySource. More...
 
- Public Member Functions inherited from ns3::EnergySource
 EnergySource ()
 
 ~EnergySource () override
 
void AppendDeviceEnergyModel (Ptr< DeviceEnergyModel > deviceEnergyModelPtr)
 
void ConnectEnergyHarvester (Ptr< EnergyHarvester > energyHarvesterPtr)
 
void DisposeDeviceModels ()
 Calls Dispose () method of the device energy models. More...
 
DeviceEnergyModelContainer FindDeviceEnergyModels (std::string name)
 
DeviceEnergyModelContainer FindDeviceEnergyModels (TypeId tid)
 
Ptr< NodeGetNode () const
 
void InitializeDeviceModels ()
 Calls Start () method of the device energy models. More...
 
void SetNode (Ptr< Node > node)
 Sets pointer to node containing this EnergySource. More...
 
- Public Member Functions inherited from ns3::Object
 Object ()
 Constructor. More...
 
 ~Object () override
 Destructor. More...
 
void AggregateObject (Ptr< Object > other)
 Aggregate two Objects together. More...
 
void Dispose ()
 Dispose of this Object. More...
 
AggregateIterator GetAggregateIterator () const
 Get an iterator to the Objects aggregated to this one. More...
 
TypeId GetInstanceTypeId () const override
 Get the most derived TypeId for this Object. More...
 
template<typename T >
Ptr< T > GetObject () const
 Get a pointer to the requested aggregated Object. More...
 
template<>
Ptr< ObjectGetObject () const
 Specialization of () for objects of type ns3::Object. More...
 
template<typename T >
Ptr< T > GetObject (TypeId tid) const
 Get a pointer to the requested aggregated Object by TypeId. More...
 
template<>
Ptr< ObjectGetObject (TypeId tid) const
 Specialization of (TypeId tid) for objects of type ns3::Object. More...
 
void Initialize ()
 Invoke DoInitialize on all Objects aggregated to this one. More...
 
bool IsInitialized () const
 Check if the object has been initialized. More...
 
- Public Member Functions inherited from ns3::SimpleRefCount< Object, ObjectBase, ObjectDeleter >
 SimpleRefCount ()
 Default constructor. More...
 
 SimpleRefCount (const SimpleRefCount &o[[maybe_unused]])
 Copy constructor. More...
 
uint32_t GetReferenceCount () const
 Get the reference count of the object. More...
 
SimpleRefCountoperator= (const SimpleRefCount &o[[maybe_unused]])
 Assignment operator. More...
 
void Ref () const
 Increment the reference count. More...
 
void Unref () const
 Decrement the reference count. More...
 
- Public Member Functions inherited from ns3::ObjectBase
virtual ~ObjectBase ()
 Virtual destructor. More...
 
void GetAttribute (std::string name, AttributeValue &value) const
 Get the value of an attribute, raising fatal errors if unsuccessful. More...
 
bool GetAttributeFailSafe (std::string name, AttributeValue &value) const
 Get the value of an attribute without raising errors. More...
 
void SetAttribute (std::string name, const AttributeValue &value)
 Set a single attribute, raising fatal errors if unsuccessful. More...
 
bool SetAttributeFailSafe (std::string name, const AttributeValue &value)
 Set a single attribute without raising errors. More...
 
bool TraceConnect (std::string name, std::string context, const CallbackBase &cb)
 Connect a TraceSource to a Callback with a context. More...
 
bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb)
 Connect a TraceSource to a Callback without a context. More...
 
bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected with a context. More...
 
bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb)
 Disconnect from a TraceSource a Callback previously connected without a context. More...
 

Static Public Member Functions

static TypeId GetTypeId ()
 Get the type ID. More...
 
- Static Public Member Functions inherited from ns3::EnergySource
static TypeId GetTypeId ()
 Get the type ID. More...
 
- Static Public Member Functions inherited from ns3::Object
static TypeId GetTypeId ()
 Register this type. More...
 
- Static Public Member Functions inherited from ns3::ObjectBase
static TypeId GetTypeId ()
 Get the type ID. More...
 

Private Member Functions

void BatteryChargedEvent ()
 Handles the battery reaching its full voltage. More...
 
void BatteryDepletedEvent ()
 Handles the battery reaching its cutoff voltage. More...
 
void CalculateRemainingEnergy ()
 Calculates remaining energy. More...
 
void DoDispose () override
 All child's implementation must call BreakDeviceEnergyModelRefCycle to ensure reference cycles to DeviceEnergyModel objects are broken. More...
 
void DoInitialize () override
 Initialize() implementation. More...
 
double GetChargeVoltage (double current)
 Obtain the battery voltage as a result of a charge current. More...
 
double GetVoltage (double current)
 Get the battery voltage in function of the discharge current. More...
 

Private Attributes

GenericBatteryType m_batteryType
 Indicates the battery type used by the model. More...
 
double m_currentFiltered
 The step response (a.k.a. More...
 
double m_cutoffVoltage
 The threshold voltage where the battery is considered depleted. More...
 
double m_drainedCapacity
 Capacity drained from the battery, in Ah. More...
 
EventId m_energyUpdateEvent
 Energy update event. More...
 
Time m_energyUpdateInterval
 Energy update interval. More...
 
Time m_energyUpdateLapseTime
 The lapse of time between the last battery energy update and the current time. More...
 
double m_entn
 The previous value of the exponential zone in NiMh,NiCd and LeadAcid. More...
 
double m_expZone
 Voltage value of the exponential zone. More...
 
double m_internalResistance
 Internal resistance of the battery, in Ohms. More...
 
Time m_lastUpdateTime
 Last update time. More...
 
double m_lowBatteryTh
 Low battery threshold, as a fraction of the initial energy. More...
 
double m_qExp
 Capacity value at the end of the exponential zone, in Ah. More...
 
double m_qMax
 The maximum capacity of the battery, in Ah. More...
 
double m_qNom
 Battery capacity at the end of the nominal zone, in Ah. More...
 
TracedValue< double > m_remainingEnergyJ
 Remaining energy, in Joules. More...
 
double m_supplyVoltageV
 Actual voltage of the battery. More...
 
double m_typicalCurrent
 Typical discharge current used to fit the curves. More...
 
double m_vExp
 Battery voltage at the end of the exponential zone, in Volts. More...
 
double m_vFull
 Initial voltage of the battery, in Volts. More...
 
double m_vNom
 Nominal voltage of the battery, in Volts. More...
 

Additional Inherited Members

- Protected Member Functions inherited from ns3::EnergySource
void BreakDeviceEnergyModelRefCycle ()
 This function is called to break reference cycle between EnergySource and DeviceEnergyModel. More...
 
double CalculateTotalCurrent ()
 
void NotifyEnergyChanged ()
 This function notifies all DeviceEnergyModel of energy changed event. More...
 
void NotifyEnergyDrained ()
 This function notifies all DeviceEnergyModel of energy depletion event. More...
 
void NotifyEnergyRecharged ()
 This function notifies all DeviceEnergyModel of energy recharged event. More...
 
- Protected Member Functions inherited from ns3::Object
 Object (const Object &o)
 Copy an Object. More...
 
virtual void NotifyNewAggregate ()
 Notify all Objects aggregated to this one of a new Object being aggregated. More...
 
- Protected Member Functions inherited from ns3::ObjectBase
void ConstructSelf (const AttributeConstructionList &attributes)
 Complete construction of ObjectBase; invoked by derived classes. More...
 
virtual void NotifyConstructionCompleted ()
 Notifier called once the ObjectBase is fully constructed. More...
 

Detailed Description

A generic battery model for Li-Ion, NiCd, NiMh and Lead acid batteries.

The generic battery model can be used to describe the discharge behavior of the battery chemestries supported by the model.

Definition at line 152 of file generic-battery-model.h.

Constructor & Destructor Documentation

◆ GenericBatteryModel()

ns3::GenericBatteryModel::GenericBatteryModel ( )

Definition at line 121 of file generic-battery-model.cc.

References NS_LOG_FUNCTION.

◆ ~GenericBatteryModel()

ns3::GenericBatteryModel::~GenericBatteryModel ( )
override

Definition at line 131 of file generic-battery-model.cc.

References NS_LOG_FUNCTION.

Member Function Documentation

◆ BatteryChargedEvent()

void ns3::GenericBatteryModel::BatteryChargedEvent ( )
private

Handles the battery reaching its full voltage.

This function notifies all the energy models aggregated to the node about the battery reaching its full energy charge.

Definition at line 255 of file generic-battery-model.cc.

References ns3::EnergySource::NotifyEnergyRecharged(), and NS_LOG_FUNCTION.

Referenced by UpdateEnergySource().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ BatteryDepletedEvent()

void ns3::GenericBatteryModel::BatteryDepletedEvent ( )
private

Handles the battery reaching its cutoff voltage.

This function notifies all the energy models aggregated to the node about the usable energy in the battery has being depleted. Each energy model is then responsible for its own handler.

Definition at line 246 of file generic-battery-model.cc.

References ns3::EnergySource::NotifyEnergyDrained(), and NS_LOG_FUNCTION.

Referenced by UpdateEnergySource().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ CalculateRemainingEnergy()

void ns3::GenericBatteryModel::CalculateRemainingEnergy ( )
private

Calculates remaining energy.

This function uses the total current from all device models to calculate the amount of energy to decrease. The energy to decrease is given by: energy to decrease = total current * supply voltage * time duration This function subtracts the calculated energy to decrease from remaining energy.

Definition at line 264 of file generic-battery-model.cc.

References ns3::EnergySource::CalculateTotalCurrent(), GetChargeVoltage(), ns3::Time::GetSeconds(), GetVoltage(), m_currentFiltered, m_drainedCapacity, m_energyUpdateLapseTime, m_lastUpdateTime, m_supplyVoltageV, ns3::Simulator::Now(), NS_ASSERT, NS_LOG_FUNCTION, and ns3::Seconds().

Referenced by UpdateEnergySource().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ DoDispose()

void ns3::GenericBatteryModel::DoDispose ( void  )
overrideprivatevirtual

All child's implementation must call BreakDeviceEnergyModelRefCycle to ensure reference cycles to DeviceEnergyModel objects are broken.

Defined in ns3::Object

Reimplemented from ns3::EnergySource.

Definition at line 239 of file generic-battery-model.cc.

References ns3::EnergySource::BreakDeviceEnergyModelRefCycle(), and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ DoInitialize()

void ns3::GenericBatteryModel::DoInitialize ( void  )
overrideprivatevirtual

Initialize() implementation.

This method is called only once by Initialize(). If the user calls Initialize() multiple times, DoInitialize() is called only the first time.

Subclasses are expected to override this method and chain up to their parent's implementation once they are done. It is safe to call GetObject() and AggregateObject() from within this method.

Reimplemented from ns3::Object.

Definition at line 233 of file generic-battery-model.cc.

References NS_LOG_FUNCTION.

◆ GetChargeVoltage()

double ns3::GenericBatteryModel::GetChargeVoltage ( double  current)
private

Obtain the battery voltage as a result of a charge current.

Parameters
currentThe actual charge current value (-i).
Returns
The voltage of the battery.

Definition at line 300 of file generic-battery-model.cc.

References GetStateOfCharge(), ns3::LEADACID, ns3::LION_LIPO, m_batteryType, m_currentFiltered, m_drainedCapacity, m_energyUpdateLapseTime, m_entn, m_expZone, m_internalResistance, m_qExp, m_qMax, m_qNom, m_remainingEnergyJ, m_typicalCurrent, m_vExp, m_vFull, m_vNom, ns3::NIMH_NICD, ns3::Simulator::Now(), NS_LOG_DEBUG, and ns3::Time::S.

Referenced by CalculateRemainingEnergy().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetDrainedCapacity()

double ns3::GenericBatteryModel::GetDrainedCapacity ( ) const

Obtain the amount of drained capacity from the battery based on the integral of the current over time (Coulomb counting method).

Returns
The drainedCapacity (Ah)

Definition at line 164 of file generic-battery-model.cc.

References m_drainedCapacity.

◆ GetEnergyFraction()

double ns3::GenericBatteryModel::GetEnergyFraction ( )
overridevirtual

Implements GetEnergyFraction.

For the generic battery model, energy fraction is equivalent to the remaining usable capacity (i.e. The SoC).

Returns
Energy fraction.

Implements ns3::EnergySource.

Definition at line 192 of file generic-battery-model.cc.

References GetStateOfCharge(), and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ GetEnergyUpdateInterval()

Time ns3::GenericBatteryModel::GetEnergyUpdateInterval ( ) const
Returns
The interval between each energy update.

Definition at line 177 of file generic-battery-model.cc.

References m_energyUpdateInterval, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ GetInitialEnergy()

double ns3::GenericBatteryModel::GetInitialEnergy ( ) const
overridevirtual

Implements GetInitialEnergy.

It returns the amount of energy in Joules stored in the battery when fully charged. This energy is different to the total amount of usable energy in the battery. This is because the battery cannot be used until Voltage = 0, only until it reaches the cutoff voltage.

Returns
The initial energy stored in the fully charged battery, in Joules.

Implements ns3::EnergySource.

Definition at line 137 of file generic-battery-model.cc.

References m_qMax, and m_vFull.

◆ GetRemainingEnergy()

double ns3::GenericBatteryModel::GetRemainingEnergy ( )
overridevirtual

Implements GetRemainingEnergy.

Returns
Remaining energy in energy source, in Joules

Implements ns3::EnergySource.

Definition at line 184 of file generic-battery-model.cc.

References m_remainingEnergyJ, NS_LOG_FUNCTION, and UpdateEnergySource().

+ Here is the call graph for this function:

◆ GetStateOfCharge()

double ns3::GenericBatteryModel::GetStateOfCharge ( ) const

Calculates an estimate of the State of Charge (SoC).

In essence, the amount of usable capacity remaining in the battery (%).

Returns
The percentage of usable capacity remaining in the battery.

Definition at line 170 of file generic-battery-model.cc.

References m_drainedCapacity, and m_qMax.

Referenced by GetChargeVoltage(), GetEnergyFraction(), and GetVoltage().

+ Here is the caller graph for this function:

◆ GetSupplyVoltage()

double ns3::GenericBatteryModel::GetSupplyVoltage ( ) const
overridevirtual

Implements GetSupplyVoltage.

Returns
Supply voltage at the energy source.

Implements ns3::EnergySource.

Definition at line 144 of file generic-battery-model.cc.

References m_supplyVoltageV.

◆ GetTypeId()

◆ GetVoltage()

double ns3::GenericBatteryModel::GetVoltage ( double  current)
private

Get the battery voltage in function of the discharge current.

It consider different discharge curves for different discharge currents and the remaining energy of the battery.

Parameters
currentThe actual discharge current value (+i).
Returns
The voltage of the battery.

Definition at line 376 of file generic-battery-model.cc.

References GetStateOfCharge(), ns3::LEADACID, ns3::LION_LIPO, m_batteryType, m_currentFiltered, m_drainedCapacity, m_energyUpdateLapseTime, m_entn, m_expZone, m_internalResistance, m_qExp, m_qMax, m_qNom, m_remainingEnergyJ, m_typicalCurrent, m_vExp, m_vFull, m_vNom, ns3::NIMH_NICD, ns3::Simulator::Now(), NS_ASSERT, NS_LOG_DEBUG, NS_LOG_FUNCTION, and ns3::Time::S.

Referenced by CalculateRemainingEnergy().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ SetDrainedCapacity()

void ns3::GenericBatteryModel::SetDrainedCapacity ( double  drainedCapacity)

This function is used to change the initial capacity in the battery.

A value of 0 means that the battery is fully charged. The value cannot be set to a value bigger than the rated capacity (fully discharged) or less than 0 (fully charged).

Parameters
drainedCapacityThe capacity drained so far in the battery.

Definition at line 157 of file generic-battery-model.cc.

References m_drainedCapacity, m_qMax, and NS_ASSERT.

◆ SetEnergyUpdateInterval()

void ns3::GenericBatteryModel::SetEnergyUpdateInterval ( Time  interval)

This function sets the interval between each energy update.

Parameters
intervalEnergy update interval.

Definition at line 150 of file generic-battery-model.cc.

References m_energyUpdateInterval, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ UpdateEnergySource()

void ns3::GenericBatteryModel::UpdateEnergySource ( )
overridevirtual

Member Data Documentation

◆ m_batteryType

GenericBatteryType ns3::GenericBatteryModel::m_batteryType
private

Indicates the battery type used by the model.

Definition at line 309 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetTypeId(), and GetVoltage().

◆ m_currentFiltered

double ns3::GenericBatteryModel::m_currentFiltered
private

The step response (a.k.a.

low pass filter)

Definition at line 289 of file generic-battery-model.h.

Referenced by CalculateRemainingEnergy(), GetChargeVoltage(), and GetVoltage().

◆ m_cutoffVoltage

double ns3::GenericBatteryModel::m_cutoffVoltage
private

The threshold voltage where the battery is considered depleted.

Definition at line 308 of file generic-battery-model.h.

Referenced by GetTypeId(), and UpdateEnergySource().

◆ m_drainedCapacity

double ns3::GenericBatteryModel::m_drainedCapacity
private

Capacity drained from the battery, in Ah.

Definition at line 288 of file generic-battery-model.h.

Referenced by CalculateRemainingEnergy(), GetChargeVoltage(), GetDrainedCapacity(), GetStateOfCharge(), GetVoltage(), and SetDrainedCapacity().

◆ m_energyUpdateEvent

EventId ns3::GenericBatteryModel::m_energyUpdateEvent
private

Energy update event.

Definition at line 297 of file generic-battery-model.h.

Referenced by UpdateEnergySource().

◆ m_energyUpdateInterval

Time ns3::GenericBatteryModel::m_energyUpdateInterval
private

Energy update interval.

Definition at line 299 of file generic-battery-model.h.

Referenced by GetEnergyUpdateInterval(), SetEnergyUpdateInterval(), and UpdateEnergySource().

◆ m_energyUpdateLapseTime

Time ns3::GenericBatteryModel::m_energyUpdateLapseTime
private

The lapse of time between the last battery energy update and the current time.

Definition at line 293 of file generic-battery-model.h.

Referenced by CalculateRemainingEnergy(), GetChargeVoltage(), and GetVoltage().

◆ m_entn

double ns3::GenericBatteryModel::m_entn
private

The previous value of the exponential zone in NiMh,NiCd and LeadAcid.

Definition at line 290 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), and GetVoltage().

◆ m_expZone

double ns3::GenericBatteryModel::m_expZone
private

Voltage value of the exponential zone.

Definition at line 292 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), and GetVoltage().

◆ m_internalResistance

double ns3::GenericBatteryModel::m_internalResistance
private

Internal resistance of the battery, in Ohms.

Definition at line 303 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetTypeId(), and GetVoltage().

◆ m_lastUpdateTime

Time ns3::GenericBatteryModel::m_lastUpdateTime
private

Last update time.

Definition at line 298 of file generic-battery-model.h.

Referenced by CalculateRemainingEnergy(), and UpdateEnergySource().

◆ m_lowBatteryTh

double ns3::GenericBatteryModel::m_lowBatteryTh
private

Low battery threshold, as a fraction of the initial energy.

Definition at line 296 of file generic-battery-model.h.

Referenced by GetTypeId().

◆ m_qExp

double ns3::GenericBatteryModel::m_qExp
private

Capacity value at the end of the exponential zone, in Ah.

Definition at line 306 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetTypeId(), and GetVoltage().

◆ m_qMax

double ns3::GenericBatteryModel::m_qMax
private

The maximum capacity of the battery, in Ah.

Definition at line 304 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetInitialEnergy(), GetStateOfCharge(), GetTypeId(), GetVoltage(), and SetDrainedCapacity().

◆ m_qNom

double ns3::GenericBatteryModel::m_qNom
private

Battery capacity at the end of the nominal zone, in Ah.

Definition at line 305 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetTypeId(), and GetVoltage().

◆ m_remainingEnergyJ

TracedValue<double> ns3::GenericBatteryModel::m_remainingEnergyJ
private

Remaining energy, in Joules.

Definition at line 287 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetRemainingEnergy(), GetTypeId(), and GetVoltage().

◆ m_supplyVoltageV

double ns3::GenericBatteryModel::m_supplyVoltageV
private

Actual voltage of the battery.

Definition at line 295 of file generic-battery-model.h.

Referenced by CalculateRemainingEnergy(), GetSupplyVoltage(), and UpdateEnergySource().

◆ m_typicalCurrent

double ns3::GenericBatteryModel::m_typicalCurrent
private

Typical discharge current used to fit the curves.

Definition at line 307 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetTypeId(), and GetVoltage().

◆ m_vExp

double ns3::GenericBatteryModel::m_vExp
private

Battery voltage at the end of the exponential zone, in Volts.

Definition at line 302 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetTypeId(), and GetVoltage().

◆ m_vFull

double ns3::GenericBatteryModel::m_vFull
private

Initial voltage of the battery, in Volts.

Definition at line 300 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetInitialEnergy(), GetTypeId(), GetVoltage(), and UpdateEnergySource().

◆ m_vNom

double ns3::GenericBatteryModel::m_vNom
private

Nominal voltage of the battery, in Volts.

Definition at line 301 of file generic-battery-model.h.

Referenced by GetChargeVoltage(), GetTypeId(), and GetVoltage().


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