A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
li-ion-energy-source.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2010 Andrea Sacco
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Andrea Sacco <andrea.sacco85@gmail.com>
7 */
8
9#ifndef LI_ION_ENERGY_SOURCE_H
10#define LI_ION_ENERGY_SOURCE_H
11
12#include "energy-source.h"
13
14#include "ns3/deprecated.h"
15#include "ns3/event-id.h"
16#include "ns3/nstime.h"
17#include "ns3/traced-value.h"
18
19namespace ns3
20{
21namespace energy
22{
23
24/**
25 * \ingroup energy
26 * \brief Model a generic Lithium Ion Battery basing on [1][2].
27 *
28 * The model can be fitted to any type of Li-Ion Battery, simply changing the
29 * model parameters.
30 * The default values are fitted for the Panasonic CGR18650DA Li-Ion Battery [3].
31 *
32 * The energy is drained as defined from the EnergySource interface but, this class
33 * consider the non-linear behaviour of Li-Ion cell. Each time energy is drained from
34 * the cell, the class evaluates the discharge curve to get the actual cell's voltage,
35 * accordingly to State of Charge (SOC) and current's drain.
36 *
37 * If the actual voltage of the cell goes below the minimum threshold voltage, the
38 * cell is considered depleted and the energy drained event fired up.
39 *
40 *
41 * The model requires several parameters to approximates the discharge curves:
42 * - InitialCellVoltage, maximum voltage of the fully charged cell
43 * - NominalCellVoltage, nominal cell's voltage, is used to determine the end of the
44 * nominal zone.
45 * - ExpCellVoltage, cell's voltage at the end of the exponential zone
46 * - RatedCapacity, rated capacity of the cell, in Ah
47 * - NomCapacity, cell's capacity at the end of the nominal zone, in Ah
48 * - ExpCapacity, cell's capacity at the end of the exponential zone, in Ah
49 * - InternalResistance, internal resistance of the cell, in Ohms
50 * - TypCurrent, typical discharge current value, used during the fitting process, in Ah
51 * - ThresholdVoltage, minimum threshold voltage below which the cell is considered
52 * depleted
53 *
54 * For a complete reference of the energy source model and model's fitting please refer
55 * to <a href="http://www.nsnam.org/wiki/GSOC2010UANFramework">UAN Framework</a>
56 * page and <a href="http://www.nsnam.org/wiki/Li-Ion_model_fitting">Li-Ion model
57 * fitting</a> page.
58 *
59 * References:
60 * [1] C. M. Shepherd, "Design of Primary and Secondary Cells - Part 3. Battery discharge equation,"
61 * U.S. Naval Research Laboratory, 1963 [2] Tremblay, O.; Dessaint, L.-A.; Dekkiche, A.-I., "A
62 * Generic Battery Model for the Dynamic Simulation of Hybrid Electric Vehicles," Ecole de
63 * Technologie Superieure, Universite du Quebec, 2007 [3]
64 * http://www.panasonic.com/industrial/includes/pdf/Panasonic_LiIon_CGR18650DA.pdf
65
66 */
67// clang-format off
68class
69NS_DEPRECATED_3_40("The LiIonEnergySource was deprecated in ns-3.40 "
70 "in favor of GenericBatteryModel, and will be removed "
71 "in a future release.")
73// clang-format on
74{
75 public:
76 /**
77 * \brief Get the type ID.
78 * \return The object TypeId.
79 */
80 static TypeId GetTypeId();
82 ~LiIonEnergySource() override;
83
84 /**
85 * \return Initial energy stored in energy source, in Joules.
86 *
87 * Implements GetInitialEnergy.
88 */
89 double GetInitialEnergy() const override;
90
91 /**
92 * \param initialEnergyJ Initial energy, in Joules
93 *
94 * Implements SetInitialEnergy. Note that initial energy is assumed to be set
95 * before simulation starts and is set only once per simulation.
96 */
97 void SetInitialEnergy(double initialEnergyJ);
98
99 /**
100 * \returns Supply voltage at the energy source.
101 *
102 * Implements GetSupplyVoltage.
103 */
104 double GetSupplyVoltage() const override;
105
106 /**
107 * \param supplyVoltageV Initial Supply voltage at the energy source, in Volts.
108 *
109 * Sets the initial supply voltage of the energy source.
110 * To be called only once.
111 */
112 void SetInitialSupplyVoltage(double supplyVoltageV);
113
114 /**
115 * \return Remaining energy in energy source, in Joules
116 *
117 * Implements GetRemainingEnergy.
118 */
119 double GetRemainingEnergy() override;
120
121 /**
122 * \returns Energy fraction.
123 *
124 * Implements GetEnergyFraction.
125 */
126 double GetEnergyFraction() override;
127
128 /**
129 * \param energyJ Amount of energy (in Joules) to decrease from energy source.
130 *
131 * Implements DecreaseRemainingEnergy.
132 */
133 NS_DEPRECATED_3_40("Use GenericBatteryModel instead")
134 virtual void DecreaseRemainingEnergy(double energyJ);
135
136 /**
137 * \param energyJ Amount of energy (in Joules) to increase from energy source.
138 *
139 * Implements IncreaseRemainingEnergy.
140 */
141 NS_DEPRECATED_3_40("Use GenericBatteryModel instead")
142 virtual void IncreaseRemainingEnergy(double energyJ);
143
144 /**
145 * Implements UpdateEnergySource.
146 */
147 void UpdateEnergySource() override;
148
149 /**
150 * \param interval Energy update interval.
151 *
152 * This function sets the interval between each energy update.
153 */
154 void SetEnergyUpdateInterval(Time interval);
155
156 /**
157 * \returns The interval between each energy update.
158 */
159 Time GetEnergyUpdateInterval() const;
160
161 private:
162 void DoInitialize() override;
163 void DoDispose() override;
164
165 /**
166 * Handles the remaining energy going to zero event. This function notifies
167 * all the energy models aggregated to the node about the energy being
168 * depleted. Each energy model is then responsible for its own handler.
169 */
170 void HandleEnergyDrainedEvent();
171
172 /**
173 * Calculates remaining energy. This function uses the total current from all
174 * device models to calculate the amount of energy to decrease. The energy to
175 * decrease is given by:
176 * energy to decrease = total current * supply voltage * time duration
177 * This function subtracts the calculated energy to decrease from remaining
178 * energy.
179 */
180 void CalculateRemainingEnergy();
181
182 /**
183 * Get the cell voltage in function of the discharge current.
184 * It consider different discharge curves for different discharge currents
185 * and the remaining energy of the cell.
186 *
187 * \param current the actual discharge current value.
188 * \return the cell voltage
189 */
190 double GetVoltage(double current) const;
191
192 private:
193 double m_initialEnergyJ; //!< initial energy, in Joules
194 TracedValue<double> m_remainingEnergyJ; //!< remaining energy, in Joules
195 double m_drainedCapacity; //!< capacity drained from the cell, in Ah
196 double m_supplyVoltageV; //!< actual voltage of the cell
197 double m_lowBatteryTh; //!< low battery threshold, as a fraction of the initial energy
198 EventId m_energyUpdateEvent; //!< energy update event
199 Time m_lastUpdateTime; //!< last update time
200 Time m_energyUpdateInterval; //!< energy update interval
201 double m_eFull; //!< initial voltage of the cell, in Volts
202 double m_eNom; //!< nominal voltage of the cell, in Volts
203 double m_eExp; //!< cell voltage at the end of the exponential zone, in Volts
204 double m_internalResistance; //!< internal resistance of the cell, in Ohms
205 double m_qRated; //!< rated capacity of the cell, in Ah
206 double m_qNom; //!< cell capacity at the end of the nominal zone, in Ah
207 double m_qExp; //!< capacity value at the end of the exponential zone, in Ah
208 double m_typCurrent; //!< typical discharge current used to fit the curves
209 double m_minVoltTh; //!< minimum threshold voltage to consider the battery depleted
210};
211
212} // namespace energy
213} // namespace ns3
214
215#endif /* LI_ION_ENERGY_SOURCE_H */
An identifier for simulation events.
Definition event-id.h:45
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Trace classes with value semantics.
a unique identifier for an interface.
Definition type-id.h:48
Energy source base class.
Model a generic Lithium Ion Battery basing on [1][2].
double m_minVoltTh
minimum threshold voltage to consider the battery depleted
double m_qNom
cell capacity at the end of the nominal zone, in Ah
EventId m_energyUpdateEvent
energy update event
double m_eNom
nominal voltage of the cell, in Volts
double m_qExp
capacity value at the end of the exponential zone, in Ah
double m_drainedCapacity
capacity drained from the cell, in Ah
TracedValue< double > m_remainingEnergyJ
remaining energy, in Joules
double m_internalResistance
internal resistance of the cell, in Ohms
double m_lowBatteryTh
low battery threshold, as a fraction of the initial energy
Time m_energyUpdateInterval
energy update interval
double m_typCurrent
typical discharge current used to fit the curves
double m_supplyVoltageV
actual voltage of the cell
double m_qRated
rated capacity of the cell, in Ah
double m_eFull
initial voltage of the cell, in Volts
double m_eExp
cell voltage at the end of the exponential zone, in Volts
double m_initialEnergyJ
initial energy, in Joules
#define NS_DEPRECATED_3_40(msg)
Tag for things deprecated in version ns-3.40.
Definition deprecated.h:112
Every class exported by the ns3 library is enclosed in the ns3 namespace.