A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
generic-battery-model.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2010 Andrea Sacco: Li-Ion battery
3 * Copyright (c) 2023 Tokushima University, Japan:
4 * NiMh,NiCd,LeaAcid batteries and preset and multi-cell extensions.
5 *
6 * SPDX-License-Identifier: GPL-2.0-only
7 *
8 * Author: Andrea Sacco <andrea.sacco85@gmail.com>
9 * Alberto Gallegos Ramonet <alramonet@is.tokushima-u.ac.jp>
10 */
11
12#ifndef GENERIC_BATTERY_MODEL_H
13#define GENERIC_BATTERY_MODEL_H
14
15#include "energy-source.h"
16
17#include <ns3/event-id.h>
18#include <ns3/nstime.h>
19#include <ns3/traced-value.h>
20
21namespace ns3
22{
23namespace energy
24{
25
26/**
27 * \ingroup energy
28 *
29 * Battery types.
30 * These are grouped according to their chemical characteristics
31 * present during a charge/discharge curve.
32 */
34{
35 LION_LIPO = 0, //!< Lithium-ion and Lithium-polymer batteries
36 NIMH_NICD = 1, //!< Nickel-metal hydride and Nickel cadmium batteries
37 LEADACID = 2 //!< Lead Acid Batteries
38};
39
40/**
41 * \ingroup energy
42 *
43 * Battery models that described the parameters of the the battery presets.
44 */
46{
47 PANASONIC_HHR650D_NIMH = 0, //!< Panasonic HHR650D NiMh battery
48 CSB_GP1272_LEADACID = 1, //!< CSB GP1272 Lead acid battery
49 PANASONIC_CGR18650DA_LION = 2, //!< Panasonic CGR18650DA Li-Ion battery
50 RSPRO_LGP12100_LEADACID = 3, //!< RS Pro LGP12100 Lead acid battery
51 PANASONIC_N700AAC_NICD = 4 //!< Panasonic N700AAC NiCd battery
52};
53
54/**
55 * \ingroup energy
56 *
57 * The structure containing the the parameter values that describe a
58 * battery preset.
59 */
61{
62 GenericBatteryType batteryType; //!< The type of battery used in the preset.
63 std::string description; //!< Additional information about the battery.
64 double vFull; //!< Initial voltage of the battery, in Volts
65 double qMax; //!< The maximum capacity of the battery, in Ah
66 double vNom; //!< Nominal voltage of the battery, in Volts
67 double qNom; //!< Battery capacity at the end of the nominal zone, in Ah
68 double vExp; //!< Battery voltage at the end of the exponential zone, in Volts
69 double qExp; //!< Capacity value at the end of the exponential zone, in Ah
70 double internalResistance; //!< Internal resistance of the battery, in Ohms
71 double typicalCurrent; //!< Typical discharge current used to fit the curves
72 double cuttoffVoltage; //!< The threshold voltage where the battery is considered depleted
73};
74
75/**
76 * \ingroup energy
77 *
78 * Contains the values that form the battery presents available in this module.
79 */
81 "Panasonic HHR650D | NiMH | 1.2V 6.5Ah | Size: D",
82 1.39,
83 7.0,
84 1.18,
85 6.25,
86 1.28,
87 1.3,
88 0.0046,
89 1.3,
90 1.0},
91 {LEADACID,
92 "CSB GP1272 | Lead Acid | 12V 7.2Ah",
93 12.8,
94 7.2,
95 11.5,
96 4.5,
97 12.5,
98 2,
99 0.056,
100 0.36,
101 8.0},
102 {LION_LIPO,
103 "Panasonic CGR18650DA | Li-Ion | 3.6V 2.45Ah | Size: A",
104 4.17,
105 2.33,
106 3.57,
107 2.14,
108 3.714,
109 1.74,
110 0.0830,
111 0.466,
112 3.0},
113 {LEADACID,
114 "Rs PRO LGP12100 | Lead Acid | 12V 100Ah",
115 12.60,
116 130,
117 12.44,
118 12.3,
119 12.52,
120 12,
121 0.00069,
122 5,
123 11},
124 {NIMH_NICD,
125 "PANASONIC N-700AAC | NiCd | 1.2V 700mAh | Size: AA",
126 1.38,
127 0.790,
128 1.17,
129 0.60,
130 1.25,
131 0.24,
132 0.016,
133 0.7,
134 0.8}};
135
136/**
137 * \ingroup energy
138 * \brief A generic battery model for Li-Ion, NiCd, NiMh and Lead acid batteries
139 *
140 * The generic battery model can be used to describe the discharge behavior of
141 * the battery chemestries supported by the model.
142 */
144{
145 public:
146 /**
147 * \brief Get the type ID.
148 * \return The object TypeId.
149 */
150 static TypeId GetTypeId();
151
153
154 ~GenericBatteryModel() override;
155
156 /**
157 * Implements GetInitialEnergy. It returns the amount of energy in Joules stored in the
158 * battery when fully charged. This energy is different to the total amount of usable energy
159 * in the battery. This is because the battery cannot be used until Voltage = 0, only until
160 * it reaches the cutoff voltage.
161 *
162 * \return The initial energy stored in the fully charged battery, in Joules.
163 */
164 double GetInitialEnergy() const override;
165
166 /**
167 * Implements GetSupplyVoltage.
168 *
169 * \return Supply voltage at the energy source.
170 */
171 double GetSupplyVoltage() const override;
172
173 /**
174 * Implements GetRemainingEnergy.
175 *
176 * \return Remaining energy in energy source, in Joules
177 */
178 double GetRemainingEnergy() override;
179
180 /**
181 * Implements GetEnergyFraction. For the generic battery model, energy fraction
182 * is equivalent to the remaining usable capacity (i.e. The SoC).
183 *
184 * \return Energy fraction.
185 */
186 double GetEnergyFraction() override;
187
188 /**
189 * Implements UpdateEnergySource.
190 */
191 void UpdateEnergySource() override;
192
193 /**
194 * This function sets the interval between each energy update.
195 *
196 * \param interval Energy update interval.
197 */
198 void SetEnergyUpdateInterval(Time interval);
199
200 /**
201 * This function is used to change the initial capacity in the battery.
202 * A value of 0 means that the battery is fully charged. The value cannot
203 * be set to a value bigger than the rated capacity (fully discharged) or
204 * less than 0 (fully charged).
205 *
206 * \param drainedCapacity The capacity drained so far in the battery.
207 */
208 void SetDrainedCapacity(double drainedCapacity);
209
210 /**
211 * Obtain the amount of drained capacity from the battery based on the
212 * integral of the current over time (Coulomb counting method).
213 *
214 * \return The drainedCapacity (Ah)
215 */
216 double GetDrainedCapacity() const;
217
218 /**
219 * Calculates an estimate of the State of Charge (SoC).
220 * In essence, the amount of usable capacity remaining in the battery (%).
221 *
222 * \return The percentage of usable capacity remaining in the battery.
223 */
224 double GetStateOfCharge() const;
225
226 /**
227 * \return The interval between each energy update.
228 */
230
231 private:
232 void DoInitialize() override;
233 void DoDispose() override;
234
235 /**
236 * Handles the battery reaching its cutoff voltage. This function notifies
237 * all the energy models aggregated to the node about the usable energy in the
238 * battery has being depleted. Each energy model is then responsible for its own handler.
239 */
241
242 /**
243 * Handles the battery reaching its full voltage. This function notifies
244 * all the energy models aggregated to the node about the battery reaching its
245 * full energy charge.
246 */
247 void BatteryChargedEvent();
248
249 /**
250 * Calculates remaining energy. This function uses the total current from all
251 * device models to calculate the amount of energy to decrease. The energy to
252 * decrease is given by:
253 * energy to decrease = total current * supply voltage * time duration
254 * This function subtracts the calculated energy to decrease from remaining
255 * energy.
256 */
258
259 /**
260 * Get the battery voltage in function of the discharge current.
261 * It consider different discharge curves for different discharge currents
262 * and the remaining energy of the battery.
263 *
264 * \param current The actual discharge current value (+i).
265 * \return The voltage of the battery.
266 */
267 double GetVoltage(double current);
268
269 /**
270 * Obtain the battery voltage as a result of a charge current.
271 *
272 * \param current The actual charge current value (-i).
273 * \return The voltage of the battery.
274 */
275 double GetChargeVoltage(double current);
276
277 private:
278 TracedValue<double> m_remainingEnergyJ; //!< Remaining energy, in Joules
279 double m_drainedCapacity; //!< Capacity drained from the battery, in Ah
280 double m_currentFiltered; //!< The step response (a.k.a. low pass filter)
281 double m_entn; //!< The previous value of the exponential zone
282 //!< in NiMh,NiCd and LeadAcid.
283 double m_expZone; //!< Voltage value of the exponential zone
284 Time m_energyUpdateLapseTime; //!< The lapse of time between the last battery energy update and
285 //!< the current time.
286 double m_supplyVoltageV; //!< Actual voltage of the battery
287 double m_lowBatteryTh; //!< Low battery threshold, as a fraction of the initial energy
288 EventId m_energyUpdateEvent; //!< Energy update event
289 Time m_lastUpdateTime; //!< Last update time
290 Time m_energyUpdateInterval; //!< Energy update interval
291 double m_vFull; //!< Initial voltage of the battery, in Volts
292 double m_vNom; //!< Nominal voltage of the battery, in Volts
293 double m_vExp; //!< Battery voltage at the end of the exponential zone, in Volts
294 double m_internalResistance; //!< Internal resistance of the battery, in Ohms
295 double m_qMax; //!< The maximum capacity of the battery, in Ah
296 double m_qNom; //!< Battery capacity at the end of the nominal zone, in Ah
297 double m_qExp; //!< Capacity value at the end of the exponential zone, in Ah
298 double m_typicalCurrent; //!< Typical discharge current used to fit the curves
299 double m_cutoffVoltage; //!< The threshold voltage where the battery is considered depleted
300 GenericBatteryType m_batteryType; //!< Indicates the battery type used by the model
301};
302
303} // namespace energy
304} // namespace ns3
305
306#endif /* GENERIC_BATTERY_MODEL_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.
A generic battery model for Li-Ion, NiCd, NiMh and Lead acid batteries.
void DoDispose() override
All child's implementation must call BreakDeviceEnergyModelRefCycle to ensure reference cycles to Dev...
double m_expZone
Voltage value of the exponential zone.
double m_cutoffVoltage
The threshold voltage where the battery is considered depleted.
double GetChargeVoltage(double current)
Obtain the battery voltage as a result of a charge current.
static TypeId GetTypeId()
Get the type ID.
void BatteryChargedEvent()
Handles the battery reaching its full voltage.
double GetEnergyFraction() override
Implements GetEnergyFraction.
EventId m_energyUpdateEvent
Energy update event.
double m_lowBatteryTh
Low battery threshold, as a fraction of the initial energy.
double m_currentFiltered
The step response (a.k.a.
Time m_energyUpdateLapseTime
The lapse of time between the last battery energy update and the current time.
double m_qMax
The maximum capacity of the battery, in Ah.
double m_supplyVoltageV
Actual voltage of the battery.
double m_qNom
Battery capacity at the end of the nominal zone, in Ah.
double m_drainedCapacity
Capacity drained from the battery, in Ah.
double m_vFull
Initial voltage of the battery, in Volts.
double m_entn
The previous value of the exponential zone in NiMh,NiCd and LeadAcid.
double m_qExp
Capacity value at the end of the exponential zone, in Ah.
void SetDrainedCapacity(double drainedCapacity)
This function is used to change the initial capacity in the battery.
double GetSupplyVoltage() const override
Implements GetSupplyVoltage.
TracedValue< double > m_remainingEnergyJ
Remaining energy, in Joules.
double GetRemainingEnergy() override
Implements GetRemainingEnergy.
void BatteryDepletedEvent()
Handles the battery reaching its cutoff voltage.
double GetVoltage(double current)
Get the battery voltage in function of the discharge current.
double m_typicalCurrent
Typical discharge current used to fit the curves.
GenericBatteryType m_batteryType
Indicates the battery type used by the model.
void DoInitialize() override
Initialize() implementation.
double GetStateOfCharge() const
Calculates an estimate of the State of Charge (SoC).
double GetInitialEnergy() const override
Implements GetInitialEnergy.
double m_vNom
Nominal voltage of the battery, in Volts.
double GetDrainedCapacity() const
Obtain the amount of drained capacity from the battery based on the integral of the current over time...
void CalculateRemainingEnergy()
Calculates remaining energy.
void UpdateEnergySource() override
Implements UpdateEnergySource.
double m_vExp
Battery voltage at the end of the exponential zone, in Volts.
void SetEnergyUpdateInterval(Time interval)
This function sets the interval between each energy update.
double m_internalResistance
Internal resistance of the battery, in Ohms.
Time m_energyUpdateInterval
Energy update interval.
static BatteryPresets g_batteryPreset[]
Contains the values that form the battery presents available in this module.
BatteryModel
Battery models that described the parameters of the the battery presets.
GenericBatteryType
Battery types.
@ PANASONIC_HHR650D_NIMH
Panasonic HHR650D NiMh battery.
@ CSB_GP1272_LEADACID
CSB GP1272 Lead acid battery.
@ PANASONIC_CGR18650DA_LION
Panasonic CGR18650DA Li-Ion battery.
@ PANASONIC_N700AAC_NICD
Panasonic N700AAC NiCd battery.
@ RSPRO_LGP12100_LEADACID
RS Pro LGP12100 Lead acid battery.
@ LEADACID
Lead Acid Batteries.
@ NIMH_NICD
Nickel-metal hydride and Nickel cadmium batteries.
@ LION_LIPO
Lithium-ion and Lithium-polymer batteries.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
The structure containing the the parameter values that describe a battery preset.
GenericBatteryType batteryType
The type of battery used in the preset.
double qMax
The maximum capacity of the battery, in Ah.
std::string description
Additional information about the battery.
double cuttoffVoltage
The threshold voltage where the battery is considered depleted.
double qExp
Capacity value at the end of the exponential zone, in Ah.
double typicalCurrent
Typical discharge current used to fit the curves.
double internalResistance
Internal resistance of the battery, in Ohms.
double qNom
Battery capacity at the end of the nominal zone, in Ah.
double vFull
Initial voltage of the battery, in Volts.
double vExp
Battery voltage at the end of the exponential zone, in Volts.
double vNom
Nominal voltage of the battery, in Volts.