From 9f92de9dcd391dc214d89a9e187d2ee57684950e Mon Sep 17 00:00:00 2001 From: Alberto Gallegos Ramonet Date: Tue, 12 Nov 2024 14:44:08 +0900 Subject: [PATCH] energy: Update energy documentation (datasheets) --- src/energy/doc/energy.rst | 149 ++++++++++++++++++++------------------ 1 file changed, 78 insertions(+), 71 deletions(-) diff --git a/src/energy/doc/energy.rst b/src/energy/doc/energy.rst index 1f470ac29..d036b6d1b 100644 --- a/src/energy/doc/energy.rst +++ b/src/energy/doc/energy.rst @@ -35,11 +35,11 @@ The |ns3| energy framework is composed of 3 essential parts: Scope and Limitations --------------------- -* In the ``GenericBatteryModel`` charging behavior (voltage as a function of SoC) is included but is not been thoroughly tested. Testing requires the implementation of a harvesting device (A charger) capable of providing a CCCV charging method typically used in batteries. +* In the ``GenericBatteryModel`` charging behavior (voltage as a function of SoC) is included but is not been thoroughly tested. Testing requires the implementation of a harvesting device (A charger) capable of providing a CCCV charging method (typical of rechargeable batteries). * In the ``GenericBatteryModel`` impedance (battery resistance) is constant, battery aging or temperature effects are not considered. -* The Rv battery model has some reported issues (See: issue `#164 `_) -* The harvesting mode can only be used with basic energy sources because it does not consider the current capacity or voltage of the battery. - +* The Rv battery model has some reported issues (See: issue `#164 `_). +* The harvesting model can only be used with a ``BasicEnergySource`` because it does not consider the current capacity or voltage of the battery. +* The is no energy sources or energy models others than the ones mentioned in this document. Support for other communication devices (lr-wpan, WiMax, etc) and other pieces of hardware (UAV, sensors, CPU) is required. Energy Source Models -------------------- @@ -119,48 +119,24 @@ be obtained by inferring its value from the discharged curves shown in datasheet the behavior of a new battery, it is important to chose values that satisfies more than one curve, trial an error adjustments might be necessary to obtain the desired results. -Attributes: - -* ``FullVoltage``: Represents the :math:`V_{full}` value. -* ``MaxCapacity``: Represents the :math:`Q` value. -* ``ExponentialVoltage``: Represents the :math:`V_{exp}` value. -* ``ExponentialCapacity``: Represents the :math:`Q_{exp}` value. -* ``NominalVoltage``: Represents the :math:`V_{nom}` value. -* ``NominalCapacity``: Represents the :math:`Q_{nom}` value. -* ``InternalResistance``: Represents the :math:`R` value. -* ``TypicalDischargeCurrent``: Represents the :math:`i_{typical}` value. -* ``CutoffVoltage``: The voltage where the battery is considered depleted. -* ``BatteryType``: Indicates the battery type used. -* ``PeriodicEnergyUpdateInterval``: Indicates how often the update values are obtained. -* ``LowBatteryThreshold``: Additional voltage threshold to indicate when the battery has low energy. - The process described above can be simplified by installing batteries presents of previously tested batteries using helpers. Details on helpers usage are detailed in the following sections. -RV Battery Model + +Rv Energy Source ~~~~~~~~~~~~~~~~ -Attributes: - -* ``RvBatteryModelPeriodicEnergyUpdateInterval``: RV battery model sampling - interval. -* ``RvBatteryModelOpenCircuitVoltage``: RV battery model open circuit voltage. -* ``RvBatteryModelCutoffVoltage``: RV battery model cutoff voltage. -* ``RvBatteryModelAlphaValue``: RV battery model alpha value. -* ``RvBatteryModelBetaValue``: RV battery model beta value. -* ``RvBatteryModelNumOfTerms``: The number of terms of the infinite sum for estimating battery level. +The Rakhmatov (Rv) energy source model is the first implementation of a non-linear Li-Ion energy source model for ns-3. +Originally created for ns-2, it was later on ported to ns-3 by Wu et al. The Rv model requires some real batteries experiments apriori +in order to obtain the attribute values required by the model. For more information read the original author's paper. Basic Energy Source ~~~~~~~~~~~~~~~~~~~ -Attributes: - -* ``BasicEnergySourceInitialEnergyJ``: Initial energy stored in - basic energy source. -* ``BasicEnergySupplyVoltageV``: Initial supply voltage for basic energy source. -* ``PeriodicEnergyUpdateInterval``: Time between two consecutive periodic energy updates. - +The Basic energy source represents an "ideal" linear energy source. +Its straightforward design makes it useful for testing and designing energy models. +However, users should consider utilizing different energy sources for testing realistic energy consumption scenarios, as the basic energy source is not reflective of most existing energy sources, such as the non-linear nature of energy sources such as batteries. Energy Consumption Models ------------------------- @@ -213,15 +189,6 @@ used to install the model on a device, a callback is implicitly made so that the Wifi PHY is resumed from the OFF mode when the energy source is recharged. -Attributes - -* ``IdleCurrentA``: The default radio Idle current in Ampere. -* ``CcaBusyCurrentA``: The default radio CCA Busy State current in Ampere. -* ``TxCurrentA``: The radio Tx current in Ampere. -* ``RxCurrentA``: The radio Rx current in Ampere. -* ``SwitchingCurrentA``: The default radio Channel Switch current in Ampere. -* ``SleepCurrentA``: The radio Sleep current in Ampere. -* ``TxCurrentModel``: A pointer to the attached tx current model. Energy Harvesting Models ------------------------ @@ -332,21 +299,70 @@ Another option is to manually configure the values that makes the preset: Usage of both of these type of configurations are shown in ``generic-battery-discharge-example.cc``. The following table is a list of the available presents in |ns3|: +.. table:: + :align: left + :widths: auto -+---------------------------+-------------------------------------------------+ -| Preset Name | Description | -+===========================+=================================================+ -| PANASONIC_CGR18650DA_LION | Panasonic Li-Ion (3.6V, 2450Ah, Size A) | -+---------------------------+-------------------------------------------------+ -| PANASONIC_HHR650D_NIMH | Panasonic NiMh HHR550D (1.2V 6.5Ah, Size D) | -+---------------------------+-------------------------------------------------+ -| CSB_GP1272_LEADACID | CSB Lead Acid GP1272 (12V,7.2Ah) | -+---------------------------+-------------------------------------------------+ -| PANASONIC_N700AAC_NICD | Panasonic NiCd N-700AAC (1.2V 700mAh, Size: AA) | -+---------------------------+-------------------------------------------------+ -| RSPRO_LGP12100_LEADACID | Rs Pro Lead Acid LGP12100 (12V, 100Ah) | -+---------------------------+-------------------------------------------------+ + +------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------+ + | Preset Name | Description | + +==============================================================================================================================+=================================================+ + | `PANASONIC_CGR18650DA_LION `_ | Panasonic Li-Ion (3.6V, 2450Ah, Size A) | + +------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------+ + | `PANASONIC_HHR650D_NIMH `_ | Panasonic NiMh HHR550D (1.2V 6.5Ah, Size D) | + +------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------+ + | `CSB_GP1272_LEADACID `_ | CSB Lead Acid GP1272 (12V,7.2Ah) | + +------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------+ + | `PANASONIC_N700AAC_NICD `_ | Panasonic NiCd N-700AAC (1.2V 700mAh, Size: AA) | + +------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------+ + | `RSPRO_LGP12100_LEADACID `_ | Rs Pro Lead Acid LGP12100 (12V, 100Ah) | + +------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------+ +All the |ns3| available presets have been created by carefully choosing the batteries attribute values based on the information found on each battery datasheet. + +Attributes +~~~~~~~~~~ + +Besides using established presets, users can create their own energy sources by using the **Generic Battery Model** attributes to create their own energy sources (i.e. batteries): + +* ``FullVoltage``: Represents the :math:`V_{full}` value. +* ``MaxCapacity``: Represents the :math:`Q` value. +* ``ExponentialVoltage``: Represents the :math:`V_{exp}` value. +* ``ExponentialCapacity``: Represents the :math:`Q_{exp}` value. +* ``NominalVoltage``: Represents the :math:`V_{nom}` value. +* ``NominalCapacity``: Represents the :math:`Q_{nom}` value. +* ``InternalResistance``: Represents the :math:`R` value. +* ``TypicalDischargeCurrent``: Represents the :math:`i_{typical}` value. +* ``CutoffVoltage``: The voltage where the battery is considered depleted. +* ``BatteryType``: Indicates the battery type used. +* ``PeriodicEnergyUpdateInterval``: Indicates how often the update values are obtained. +* ``LowBatteryThreshold``: Additional voltage threshold to indicate when the battery has low energy. + +**Rv Energy source** attributes: + +* ``RvBatteryModelPeriodicEnergyUpdateInterval``: RV battery model sampling interval. +* ``RvBatteryModelOpenCircuitVoltage``: RV battery model open circuit voltage. +* ``RvBatteryModelCutoffVoltage``: RV battery model cutoff voltage. +* ``RvBatteryModelAlphaValue``: RV battery model alpha value. +* ``RvBatteryModelBetaValue``: RV battery model beta value. +* ``RvBatteryModelNumOfTerms``: The number of terms of the infinite sum for estimating battery level. + +**Basic Energy source** attributes: + +* ``BasicEnergySourceInitialEnergyJ``: Initial energy stored in + basic energy source. +* ``BasicEnergySupplyVoltageV``: Initial supply voltage for basic energy source. +* ``PeriodicEnergyUpdateInterval``: Time between two consecutive periodic energy updates. + + +**Wifi Radio Energy model** attributes: + +* ``IdleCurrentA``: The default radio Idle current in Ampere. +* ``CcaBusyCurrentA``: The default radio CCA Busy State current in Ampere. +* ``TxCurrentA``: The radio Tx current in Ampere. +* ``RxCurrentA``: The radio Rx current in Ampere. +* ``SwitchingCurrentA``: The default radio Channel Switch current in Ampere. +* ``SleepCurrentA``: The radio Sleep current in Ampere. +* ``TxCurrentModel``: A pointer to the attached tx current model. Traces ~~~~~~ @@ -389,7 +405,7 @@ Examples in ``src/energy/examples``: Examples in ``examples/energy``: * ``energy-model-example.cc`` -* ``energy-model-with-harvesting-example.cc``: Shows the harvesting model usage. Only usable with basicEnergySources. +* ``energy-model-with-harvesting-example.cc``: Shows the harvesting model usage. Only usable with ``BasicEnergySource``. The following tests have been written, which can be found in ``src/energy/tests/``: @@ -428,19 +444,10 @@ The RV battery model is validated by comparing results with what was presented i NiMH battery discharge curve (Panasonic HHR650D) - -Future Work ------------ - -* Support of device energy models for PHY layers (lr-wpan, WiMax, etc) and other pieces of hardware (UAV, sensors, CPU). -* Support for realistic charging batteries in the ``GenericBatteryModule``. -* Support for device capable of charging batteries (e.g. chargers with CCCV capabilities). -* Implement an energy harvester that recharges the energy sources according to the power levels defined in a user customizable dataset of real measurements. - References ---------- -Energy source models and energy consumption models: +**Energy source models and energy consumption models**: [`1 `_] H. Wu, S. Nabar and R. Poovendran. An Energy Framework for the Network Simulator 3 (ns-3). @@ -456,12 +463,12 @@ Energy source models and energy consumption models: [`7 `_] MatWorks SimuLink Generic Battery Model -[8] C. M. Shepherd. 1965. Design of Primary and Secondary Cells: II . An Equation Describing Battery Discharge. Journal of The Electrochemical Society 112, 7 (jul 1965), 657. https://doi.org/10.1149/1.2423659 +[`8 `_] C. M. Shepherd. 1965. Design of Primary and Secondary Cells: II . An Equation Describing Battery Discharge. Journal of The Electrochemical Society 112, 7 (jul 1965), 657. https://doi.org/10.1149/1.2423659 [`9 `_] Alberto Gallegos Ramonet, Alexander Guzman Urbina, and Kazuhiko Kinoshita. 2023. Evaluation and Extension of ns-3 Battery Framework. In Proceedings of the 2023 Workshop on ns-3 (WNS3 '23). Association for Computing Machinery, New York, NY, USA, 102–108. https://doi.org/10.1145/3592149.3592156 -Energy Harvesting Models: +**Energy harvesting models:** [10] C. Tapparello, H. Ayatollahi and W. Heinzelman. Extending the Energy Framework for Network Simulator 3 (ns-3). Workshop on ns-3 (WNS3), Poster Session, Atlanta, GA, USA. May, 2014.