A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
energy-source.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2010 Network Security Lab, University of Washington, Seattle.
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Sidharth Nabar <snabar@uw.edu>, He Wu <mdzz@u.washington.edu>
7 *
8 * Copyright (c) 2014 Wireless Communications and Networking Group (WCNG),
9 * University of Rochester, Rochester, NY, USA.
10 *
11 * Modifications made by: Cristiano Tapparello <cristiano.tapparello@rochester.edu>
12 */
13
14#ifndef ENERGY_SOURCE_H
15#define ENERGY_SOURCE_H
16
17#include "device-energy-model-container.h" // #include "device-energy-model.h"
18#include "energy-harvester.h"
19
20#include "ns3/node.h"
21#include "ns3/object.h"
22#include "ns3/ptr.h"
23#include "ns3/type-id.h"
24
25namespace ns3
26{
27namespace energy
28{
29
30class EnergyHarvester;
31
32/**
33 * @defgroup energy Energy Models
34 */
35
36/**
37 * @ingroup energy
38 * @ingroup tests
39 * @defgroup energy-tests Energy module tests
40 */
41
42/**
43 * @ingroup energy
44 *
45 * @brief Energy source base class.
46 *
47 * This is the base class for energy sources. Energy sources keep track of
48 * remaining energy. Device energy models will be updating the remaining energy
49 * in the energy source. The energy source itself does not update the remaining
50 * energy. Energy source also keeps a list of device energy models installed on
51 * the same node. When the remaining energy level reaches 0, the energy source
52 * will notify all device energy models stored in the list.
53 *
54 * EnergySource provides 2 types of interfaces for DeviceEnergyModels to update
55 * the remaining energy stored in EnergySource:
56 * -Direct energy update interface (Joules):
57 * DecreaseRemainingEnergy
58 * IncreaseRemainingEnergy
59 * -Indirect energy update interface (Current):
60 * UpdateEnergySource
61 * Direct energy update interface will decrease/increase energy from the source
62 * directly (in Joules). Direct energy update interface is typically used by
63 * simple DeviceEnergyModel which knows only average power consumption for each
64 * of its state.
65 * Indirect energy update interface uses the total current cumulated from all
66 * DeviceEnergyModel to calculate energy to decrease from the source. Indirect
67 * energy update interface is typically used by DeviceEnergyModel who knows its
68 * current draw for each of its states. Nonlinear EnergySource also uses this
69 * interface.
70 *
71 * Unit of energy is chosen as Joules since energy models typically calculate
72 * energy as (time in seconds * power in Watts). If the energy source stores
73 * energy in different units (eg. kWh), a simple converter function should
74 * suffice.
75 */
76class EnergySource : public Object
77{
78 public:
79 /**
80 * @brief Get the type ID.
81 * @return The object TypeId.
82 */
83 static TypeId GetTypeId();
85 ~EnergySource() override;
86
87 /**
88 * @returns Supply voltage of the energy source.
89 *
90 * Set method is to be defined in child class only if necessary. For sources
91 * with a fixed supply voltage, set method is not needed.
92 */
93 virtual double GetSupplyVoltage() const = 0;
94
95 /**
96 * @returns Initial energy (capacity) of the energy source.
97 *
98 * Set method is to be defined in child class only if necessary. For sources
99 * with a fixed initial energy (energy capacity), set method is not needed.
100 */
101 virtual double GetInitialEnergy() const = 0;
102
103 /**
104 * @returns Remaining energy at the energy source.
105 */
106 virtual double GetRemainingEnergy() = 0;
107
108 /**
109 * @return Energy fraction = remaining energy / initial energy [0, 1]
110 *
111 * This function returns the percentage of energy left in the energy source.
112 */
113 virtual double GetEnergyFraction() = 0;
114
115 /**
116 * This function goes through the list of DeviceEnergyModels to obtain total
117 * current draw at the energy source and updates remaining energy. Called by
118 * DeviceEnergyModels to inform EnergySource of a state change.
119 */
120 virtual void UpdateEnergySource() = 0;
121
122 /**
123 * @brief Sets pointer to node containing this EnergySource.
124 *
125 * @param node Pointer to node containing this EnergySource.
126 */
127 void SetNode(Ptr<Node> node);
128
129 /**
130 * @returns Pointer to node containing this EnergySource.
131 *
132 * When a subclass needs to get access to the underlying node base class to
133 * print the nodeId for example, it can invoke this method.
134 */
135 Ptr<Node> GetNode() const;
136
137 /**
138 * @param deviceEnergyModelPtr Pointer to device energy model.
139 *
140 * This function appends a device energy model to the end of a list of
141 * DeviceEnergyModelInfo structs.
142 */
143 void AppendDeviceEnergyModel(Ptr<DeviceEnergyModel> deviceEnergyModelPtr);
144
145 /**
146 * @param tid TypeId of the DeviceEnergyModel we are searching for.
147 * @returns List of pointers to DeviceEnergyModel objects installed on node.
148 */
150
151 /**
152 * @param name name of the DeviceEnergyModel we are searching for.
153 * @returns List of pointers to DeviceEnergyModel objects installed on node.
154 */
156
157 /**
158 * Calls Start () method of the device energy models. Device energy models are
159 * not aggregated to the node, therefore we need to manually start them here.
160 * Called by EnergySourceContainer, which is aggregated to the node.
161 */
163
164 /**
165 * Calls Dispose () method of the device energy models. Device energy models
166 * are not aggregated to the node, therefore we need to manually start them
167 * here. Called by EnergySourceContainer, which is aggregated to the node.
168 */
169 void DisposeDeviceModels();
170
171 /**
172 * @param energyHarvesterPtr Pointer to energy harvester.
173 *
174 * This function connect an energy harvester to the energy source. After the
175 * execution of this method, the pointer to the energy harvester is appended
176 * to the end of a vector of EnergyHarvester pointer.
177 * Note that the order in which different energy harvester are added to the
178 * energy source does not impact the simulation results.
179 */
180 void ConnectEnergyHarvester(Ptr<EnergyHarvester> energyHarvesterPtr);
181
182 private:
183 /**
184 * All child's implementation must call BreakDeviceEnergyModelRefCycle to
185 * ensure reference cycles to DeviceEnergyModel objects are broken.
186 *
187 * Defined in ns3::Object
188 */
189 void DoDispose() override;
190
191 private:
192 /**
193 * List of device energy models installed on the same node.
194 */
196
197 /**
198 * Pointer to node containing this EnergySource. Used by helper class to make
199 * sure device models are installed onto the corresponding node.
200 */
202
203 /**
204 * Vector of EnergyHarvester pointer connected to the same energy source.
205 * This vector is used by the CalculateTotalCurrent method to determine the
206 * total power provided by the energy harvesters connected to the energy source.
207 */
208 std::vector<Ptr<EnergyHarvester>> m_harvesters;
209
210 protected:
211 /**
212 * @returns Total current draw from all DeviceEnergyModels.
213 */
214 double CalculateTotalCurrent();
215
216 /**
217 * This function notifies all DeviceEnergyModel of energy depletion event. It
218 * is called by the child EnergySource class when energy depletion happens.
219 */
220 void NotifyEnergyDrained();
221
222 /**
223 * This function notifies all DeviceEnergyModel of energy recharged event. It
224 * is called by the child EnergySource class when energy source is recharged.
225 */
227
228 /**
229 * This function notifies all DeviceEnergyModel of energy changed event. It
230 * is called by the child EnergySource class when energy source is changed.
231 */
232 void NotifyEnergyChanged();
233
234 /**
235 * This function is called to break reference cycle between EnergySource and
236 * DeviceEnergyModel. Child of the EnergySource base class must call this
237 * function in their implementation of DoDispose to make sure the reference
238 * cycle is broken.
239 *
240 * Normally this work will be completed by the DoDispose function. However it
241 * will be overridden in the child class. Hence we introduced this function.
242 */
244};
245
246} // namespace energy
247} // namespace ns3
248
249#endif /* ENERGY_SOURCE_H */
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
a unique identifier for an interface.
Definition type-id.h:48
Holds a vector of ns3::DeviceEnergyModel pointers.
Energy source base class.
void BreakDeviceEnergyModelRefCycle()
This function is called to break reference cycle between EnergySource and DeviceEnergyModel.
void NotifyEnergyDrained()
This function notifies all DeviceEnergyModel of energy depletion event.
DeviceEnergyModelContainer FindDeviceEnergyModels(TypeId tid)
virtual double GetEnergyFraction()=0
void ConnectEnergyHarvester(Ptr< EnergyHarvester > energyHarvesterPtr)
void InitializeDeviceModels()
Calls Start () method of the device energy models.
void NotifyEnergyRecharged()
This function notifies all DeviceEnergyModel of energy recharged event.
std::vector< Ptr< EnergyHarvester > > m_harvesters
Vector of EnergyHarvester pointer connected to the same energy source.
DeviceEnergyModelContainer m_models
List of device energy models installed on the same node.
virtual double GetRemainingEnergy()=0
static TypeId GetTypeId()
Get the type ID.
void DoDispose() override
All child's implementation must call BreakDeviceEnergyModelRefCycle to ensure reference cycles to Dev...
Ptr< Node > m_node
Pointer to node containing this EnergySource.
virtual void UpdateEnergySource()=0
This function goes through the list of DeviceEnergyModels to obtain total current draw at the energy ...
void SetNode(Ptr< Node > node)
Sets pointer to node containing this EnergySource.
void NotifyEnergyChanged()
This function notifies all DeviceEnergyModel of energy changed event.
void AppendDeviceEnergyModel(Ptr< DeviceEnergyModel > deviceEnergyModelPtr)
virtual double GetSupplyVoltage() const =0
void DisposeDeviceModels()
Calls Dispose () method of the device energy models.
Ptr< Node > GetNode() const
virtual double GetInitialEnergy() const =0
Every class exported by the ns3 library is enclosed in the ns3 namespace.