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

Model a generic Lithium Ion Battery basing on [1][2]. More...

#include "li-ion-energy-source.h"

+ Inheritance diagram for ns3::LiIonEnergySource:
+ Collaboration diagram for ns3::LiIonEnergySource:

Public Member Functions

 LiIonEnergySource ()
 
 ~LiIonEnergySource () override
 
virtual void DecreaseRemainingEnergy (double energyJ)
 
double GetEnergyFraction () override
 
Time GetEnergyUpdateInterval () const
 
double GetInitialEnergy () const override
 
double GetRemainingEnergy () override
 
double GetSupplyVoltage () const override
 
virtual void IncreaseRemainingEnergy (double energyJ)
 
void SetEnergyUpdateInterval (Time interval)
 
void SetInitialEnergy (double initialEnergyJ)
 
void SetInitialSupplyVoltage (double supplyVoltageV)
 
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 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 GetVoltage (double current) const
 Get the cell voltage in function of the discharge current. More...
 
void HandleEnergyDrainedEvent ()
 Handles the remaining energy going to zero event. More...
 

Private Attributes

double m_drainedCapacity
 capacity drained from the cell, in Ah More...
 
double m_eExp
 cell voltage at the end of the exponential zone, in Volts More...
 
double m_eFull
 initial voltage of the cell, in Volts More...
 
EventId m_energyUpdateEvent
 energy update event More...
 
Time m_energyUpdateInterval
 energy update interval More...
 
double m_eNom
 nominal voltage of the cell, in Volts More...
 
double m_initialEnergyJ
 initial energy, in Joules More...
 
double m_internalResistance
 internal resistance of the cell, 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_minVoltTh
 minimum threshold voltage to consider the battery depleted More...
 
double m_qExp
 capacity value at the end of the exponential zone, in Ah More...
 
double m_qNom
 cell capacity at the end of the nominal zone, in Ah More...
 
double m_qRated
 rated capacity of the cell, in Ah More...
 
TracedValue< double > m_remainingEnergyJ
 remaining energy, in Joules More...
 
double m_supplyVoltageV
 actual voltage of the cell More...
 
double m_typCurrent
 typical discharge current used to fit the curves 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

Model a generic Lithium Ion Battery basing on [1][2].

Deprecated:
The LiIonEnergySource was deprecated in ns-3.40 in favor of GenericBatteryModel, and will be removed in a future release.

The model can be fitted to any type of Li-Ion Battery, simply changing the model parameters. The default values are fitted for the Panasonic CGR18650DA Li-Ion Battery [3].

The energy is drained as defined from the EnergySource interface but, this class consider the non-linear behaviour of Li-Ion cell. Each time energy is drained from the cell, the class evaluates the discharge curve to get the actual cell's voltage, accordingly to State of Charge (SOC) and current's drain.

If the actual voltage of the cell goes below the minimum threshold voltage, the cell is considered depleted and the energy drained event fired up.

The model requires several parameters to approximates the discharge curves:

  • InitialCellVoltage, maximum voltage of the fully charged cell
  • NominalCellVoltage, nominal cell's voltage, is used to determine the end of the nominal zone.
  • ExpCellVoltage, cell's voltage at the end of the exponential zone
  • RatedCapacity, rated capacity of the cell, in Ah
  • NomCapacity, cell's capacity at the end of the nominal zone, in Ah
  • ExpCapacity, cell's capacity at the end of the exponential zone, in Ah
  • InternalResistance, internal resistance of the cell, in Ohms
  • TypCurrent, typical discharge current value, used during the fitting process, in Ah
  • ThresholdVoltage, minimum threshold voltage below which the cell is considered depleted

For a complete reference of the energy source model and model's fitting please refer to UAN Framework page and Li-Ion model fitting page.

References: [1] C. M. Shepherd, "Design of Primary and Secondary Cells - Part 3. Battery discharge equation," U.S. Naval Research Laboratory, 1963 [2] Tremblay, O.; Dessaint, L.-A.; Dekkiche, A.-I., "A Generic Battery Model for the Dynamic Simulation of Hybrid Electric Vehicles," Ecole de Technologie Superieure, Universite du Quebec, 2007 [3] http://www.panasonic.com/industrial/includes/pdf/Panasonic_LiIon_CGR18650DA.pdf

Definition at line 79 of file li-ion-energy-source.h.

Constructor & Destructor Documentation

◆ LiIonEnergySource()

ns3::LiIonEnergySource::LiIonEnergySource ( )

Definition at line 115 of file li-ion-energy-source.cc.

References NS_LOG_FUNCTION.

◆ ~LiIonEnergySource()

ns3::LiIonEnergySource::~LiIonEnergySource ( )
override

Definition at line 122 of file li-ion-energy-source.cc.

References NS_LOG_FUNCTION.

Member Function Documentation

◆ CalculateRemainingEnergy()

void ns3::LiIonEnergySource::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 267 of file li-ion-energy-source.cc.

References ns3::EnergySource::CalculateTotalCurrent(), ns3::Time::GetSeconds(), GetVoltage(), m_drainedCapacity, m_lastUpdateTime, m_remainingEnergyJ, m_supplyVoltageV, ns3::Simulator::Now(), NS_ASSERT, NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by UpdateEnergySource().

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

◆ DecreaseRemainingEnergy()

void ns3::LiIonEnergySource::DecreaseRemainingEnergy ( double  energyJ)
virtual
Parameters
energyJAmount of energy (in Joules) to decrease from energy source.

Implements DecreaseRemainingEnergy.

Definition at line 192 of file li-ion-energy-source.cc.

References HandleEnergyDrainedEvent(), m_minVoltTh, m_remainingEnergyJ, m_supplyVoltageV, NS_ASSERT, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ DoDispose()

void ns3::LiIonEnergySource::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 252 of file li-ion-energy-source.cc.

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

+ Here is the call graph for this function:

◆ DoInitialize()

void ns3::LiIonEnergySource::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 245 of file li-ion-energy-source.cc.

References NS_LOG_FUNCTION, and UpdateEnergySource().

+ Here is the call graph for this function:

◆ GetEnergyFraction()

double ns3::LiIonEnergySource::GetEnergyFraction ( )
overridevirtual
Returns
Energy fraction.

Implements GetEnergyFraction.

Implements ns3::EnergySource.

Definition at line 183 of file li-ion-energy-source.cc.

References m_initialEnergyJ, m_remainingEnergyJ, NS_LOG_FUNCTION, and UpdateEnergySource().

+ Here is the call graph for this function:

◆ GetEnergyUpdateInterval()

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

Definition at line 167 of file li-ion-energy-source.cc.

References m_energyUpdateInterval, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ GetInitialEnergy()

double ns3::LiIonEnergySource::GetInitialEnergy ( ) const
overridevirtual
Returns
Initial energy stored in energy source, in Joules.

Implements GetInitialEnergy.

Implements ns3::EnergySource.

Definition at line 138 of file li-ion-energy-source.cc.

References m_initialEnergyJ, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ GetRemainingEnergy()

double ns3::LiIonEnergySource::GetRemainingEnergy ( )
overridevirtual
Returns
Remaining energy in energy source, in Joules

Implements GetRemainingEnergy.

Implements ns3::EnergySource.

Definition at line 174 of file li-ion-energy-source.cc.

References m_remainingEnergyJ, NS_LOG_FUNCTION, and UpdateEnergySource().

+ Here is the call graph for this function:

◆ GetSupplyVoltage()

double ns3::LiIonEnergySource::GetSupplyVoltage ( ) const
overridevirtual
Returns
Supply voltage at the energy source.

Implements GetSupplyVoltage.

Implements ns3::EnergySource.

Definition at line 153 of file li-ion-energy-source.cc.

References m_supplyVoltageV, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ GetTypeId()

◆ GetVoltage()

double ns3::LiIonEnergySource::GetVoltage ( double  current) const
private

Get the cell voltage in function of the discharge current.

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

Parameters
currentthe actual discharge current value.
Returns
the cell voltage

Definition at line 292 of file li-ion-energy-source.cc.

References E, m_drainedCapacity, m_eExp, m_eFull, m_eNom, m_internalResistance, m_qExp, m_qNom, m_qRated, m_typCurrent, NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by CalculateRemainingEnergy().

+ Here is the caller graph for this function:

◆ HandleEnergyDrainedEvent()

void ns3::LiIonEnergySource::HandleEnergyDrainedEvent ( )
private

Handles the remaining energy going to zero event.

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

Definition at line 259 of file li-ion-energy-source.cc.

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

Referenced by DecreaseRemainingEnergy(), and UpdateEnergySource().

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

◆ IncreaseRemainingEnergy()

void ns3::LiIonEnergySource::IncreaseRemainingEnergy ( double  energyJ)
virtual
Parameters
energyJAmount of energy (in Joules) to increase from energy source.

Implements IncreaseRemainingEnergy.

Definition at line 206 of file li-ion-energy-source.cc.

References m_remainingEnergyJ, NS_ASSERT, and NS_LOG_FUNCTION.

◆ SetEnergyUpdateInterval()

void ns3::LiIonEnergySource::SetEnergyUpdateInterval ( Time  interval)
Parameters
intervalEnergy update interval.

This function sets the interval between each energy update.

Definition at line 160 of file li-ion-energy-source.cc.

References m_energyUpdateInterval, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ SetInitialEnergy()

void ns3::LiIonEnergySource::SetInitialEnergy ( double  initialEnergyJ)
Parameters
initialEnergyJInitial energy, in Joules

Implements SetInitialEnergy. Note that initial energy is assumed to be set before simulation starts and is set only once per simulation.

Definition at line 128 of file li-ion-energy-source.cc.

References m_initialEnergyJ, m_remainingEnergyJ, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ SetInitialSupplyVoltage()

void ns3::LiIonEnergySource::SetInitialSupplyVoltage ( double  supplyVoltageV)
Parameters
supplyVoltageVInitial Supply voltage at the energy source, in Volts.

Sets the initial supply voltage of the energy source. To be called only once.

Definition at line 145 of file li-ion-energy-source.cc.

References m_eFull, m_supplyVoltageV, and NS_LOG_FUNCTION.

Referenced by GetTypeId().

+ Here is the caller graph for this function:

◆ UpdateEnergySource()

void ns3::LiIonEnergySource::UpdateEnergySource ( )
overridevirtual

Member Data Documentation

◆ m_drainedCapacity

double ns3::LiIonEnergySource::m_drainedCapacity
private

capacity drained from the cell, in Ah

Definition at line 201 of file li-ion-energy-source.h.

Referenced by CalculateRemainingEnergy(), and GetVoltage().

◆ m_eExp

double ns3::LiIonEnergySource::m_eExp
private

cell voltage at the end of the exponential zone, in Volts

Definition at line 209 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and GetVoltage().

◆ m_eFull

double ns3::LiIonEnergySource::m_eFull
private

initial voltage of the cell, in Volts

Definition at line 207 of file li-ion-energy-source.h.

Referenced by GetVoltage(), and SetInitialSupplyVoltage().

◆ m_energyUpdateEvent

EventId ns3::LiIonEnergySource::m_energyUpdateEvent
private

energy update event

Definition at line 204 of file li-ion-energy-source.h.

Referenced by UpdateEnergySource().

◆ m_energyUpdateInterval

Time ns3::LiIonEnergySource::m_energyUpdateInterval
private

energy update interval

Definition at line 206 of file li-ion-energy-source.h.

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

◆ m_eNom

double ns3::LiIonEnergySource::m_eNom
private

nominal voltage of the cell, in Volts

Definition at line 208 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and GetVoltage().

◆ m_initialEnergyJ

double ns3::LiIonEnergySource::m_initialEnergyJ
private

initial energy, in Joules

Definition at line 199 of file li-ion-energy-source.h.

Referenced by GetEnergyFraction(), GetInitialEnergy(), SetInitialEnergy(), and UpdateEnergySource().

◆ m_internalResistance

double ns3::LiIonEnergySource::m_internalResistance
private

internal resistance of the cell, in Ohms

Definition at line 210 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and GetVoltage().

◆ m_lastUpdateTime

Time ns3::LiIonEnergySource::m_lastUpdateTime
private

last update time

Definition at line 205 of file li-ion-energy-source.h.

Referenced by CalculateRemainingEnergy(), and UpdateEnergySource().

◆ m_lowBatteryTh

double ns3::LiIonEnergySource::m_lowBatteryTh
private

low battery threshold, as a fraction of the initial energy

Definition at line 203 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and UpdateEnergySource().

◆ m_minVoltTh

double ns3::LiIonEnergySource::m_minVoltTh
private

minimum threshold voltage to consider the battery depleted

Definition at line 215 of file li-ion-energy-source.h.

Referenced by DecreaseRemainingEnergy(), and GetTypeId().

◆ m_qExp

double ns3::LiIonEnergySource::m_qExp
private

capacity value at the end of the exponential zone, in Ah

Definition at line 213 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and GetVoltage().

◆ m_qNom

double ns3::LiIonEnergySource::m_qNom
private

cell capacity at the end of the nominal zone, in Ah

Definition at line 212 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and GetVoltage().

◆ m_qRated

double ns3::LiIonEnergySource::m_qRated
private

rated capacity of the cell, in Ah

Definition at line 211 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and GetVoltage().

◆ m_remainingEnergyJ

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

◆ m_supplyVoltageV

double ns3::LiIonEnergySource::m_supplyVoltageV
private

actual voltage of the cell

Definition at line 202 of file li-ion-energy-source.h.

Referenced by CalculateRemainingEnergy(), DecreaseRemainingEnergy(), GetSupplyVoltage(), and SetInitialSupplyVoltage().

◆ m_typCurrent

double ns3::LiIonEnergySource::m_typCurrent
private

typical discharge current used to fit the curves

Definition at line 214 of file li-ion-energy-source.h.

Referenced by GetTypeId(), and GetVoltage().


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