diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst
index a5c2c3b57..6eb76cae5 100644
--- a/doc/manual/source/index.rst
+++ b/doc/manual/source/index.rst
@@ -10,8 +10,8 @@ available in five forms:
* Tutorial, Manual *(this document)*, and Model Library for the `latest release `_ and `development tree `_
* `ns-3 wiki `_
-This document is written in `reStructuredText `_ for `Sphinx `_ and is maintained in the
-``doc/manual`` directory of ns-3's source code.
+Contents
+--------
.. toctree::
:maxdepth: 2
@@ -34,3 +34,10 @@ This document is written in `reStructuredText `_ for `Sphinx `_ and is maintained in the
+``doc/manual`` directory of ns-3's source code.
+
diff --git a/doc/manual/source/new-modules.rst b/doc/manual/source/new-modules.rst
index a0eca4eec..4ee246eda 100644
--- a/doc/manual/source/new-modules.rst
+++ b/doc/manual/source/new-modules.rst
@@ -11,14 +11,15 @@ used with existing |ns3| modules and by other researchers.
This chapter walks you through the steps necessary to add a new module
to |ns3|.
-Step 1 - Familiarize yourself with the module layout
-****************************************************
+.. _Step-0:
+
+Step 0 - Module Layout
+**********************
All modules can be found in the ``src`` directory. Each module can be
found in a directory that has the same name as the module. For
-example, the spectrum module can be found here: ::
-
- src/spectrum
+example, the ``spectrum`` module can be found here: ``src/spectrum``.
+We'll be quoting from the ``spectrum`` module for illustration.
A prototypical module has the following directory structure and
required files:
@@ -26,129 +27,164 @@ required files:
.. sourcecode:: text
src/
- module-name/
- bindings/
- doc/
- examples/
- wscript
- helper/
- model/
- test/
- examples-to-run.py
- wscript
+ module-name/
+ bindings/
+ doc/
+ examples/
+ wscript
+ helper/
+ model/
+ test/
+ examples-to-run.py
+ wscript
Not all directories will be present in each module.
-Step 2 - Create your new module based on the template module
-************************************************************
+Step 1 - Create a Module Skeleton
+*********************************
-A python program is provided in the source directory that will create a skeleton for a new module
-
-.. sourcecode:: bash
-
- $ src/create-module.py
-
-For the purposes of this discussion we will assume that your new module is called "new-module". From the ``src`` directory, do the following to create the new module:
+A python program is provided in the source directory that
+will create a skeleton for a new module. For the purposes
+of this discussion we will assume that your new module
+is called ``new-module``. From the ``src`` directory, do the following
+to create the new module:
.. sourcecode:: bash
$ ./create-module.py new-module
-Next, cd into ``new-module``; you will find this directory layout:
+Next, ``cd`` into ``new-module``; you will find this directory layout:
.. sourcecode:: text
- $ examples helper model test wscript
+ $ cd new-module
+ $ ls
+ doc examples helper model test wscript
-We next walk through how to customize this module. All |ns3| modules
-depend on the 'core' module and usually on other modules. This
-dependency is specified in the wscript file.
-Let's assume that 'new-module' depends on the internet,
-mobility, and aodv modules. Then the call to the function that will
-create this module should look like this before editing:
+In more detail, the ``create-module.py`` script will create the
+directories as well as initial skeleton ``wscript``, ``.h``, ``.cc``
+and ``.rst`` files. The complete module with skeleton files looks like this:
+
+.. sourcecode:: text
+
+ src/
+ new-module/
+ doc/
+ new-module.rst
+ examples/
+ new-module-example.cc
+ wscript
+ helper/
+ new-module-helper.cc
+ new-module-helper.h
+ model/
+ new-module.cc
+ new-module.h
+ test/
+ new-module-test-suite.cc
+ wscript
+
+(If required the ``bindings/`` directory listed in
+:ref:`Step-0 ` will be created automatically during
+the build.)
+
+We next walk through how to customize this module. Informing ``waf``
+about the files which make up your module is done by editing the two
+``wscript`` files. We will walk through the main steps in this chapter.
+
+All |ns3| modules depend on the ``core`` module and usually on
+other modules. This dependency is specified in the ``wscript`` file
+(at the top level of the module, not the separate ``wscript`` file
+in the ``examples`` directory!). In the skeleton ``wscript``
+the call that will declare your new module to ``waf`` will look
+like this (before editing):
.. sourcecode:: python
def build(bld):
module = bld.create_ns3_module('new-module', ['core'])
-and after editing:
+Let's assume that ``new-module`` depends on the ``internet``,
+``mobility``, and ``aodv`` modules. After editing it the ``wscript`` file
+should look like:
.. sourcecode:: python
def build(bld):
module = bld.create_ns3_module('new-module', ['internet', 'mobility', 'aodv'])
-Your module will most likely have model source files. Initial skeletons (which will compile successfully) are created in ``model/new-module.cc`` and ``model/new-module.h``.
+Note that only first level module dependencies should be listed, which
+is why we removed ``core``; the ``internet`` module in turn depends on
+``core``.
-If your module will have helper source files, then they will go into the helper/ directory; again, initial skeletons are created in that directory.
+Your module will most likely have model source files. Initial skeletons
+(which will compile successfully) are created in ``model/new-module.cc``
+and ``model/new-module.h``.
-Finally, it is good practice to write tests. A skeleton test suite and test case is created in the test/ directory. The below constructor specifies that it will be a unit test named 'new-module': ::
+If your module will have helper source files, then they will go into
+the ``helper/`` directory; again, initial skeletons are created
+in that directory.
- New-moduleTestSuite::New-moduleTestSuite ()
+Finally, it is good practice to write tests and examples. These will
+almost certainly be required for new modules to be accepted into
+the official |ns3| source tree. A skeleton
+test suite and test case is created in the ``test/`` directory.
+The skeleton test suite will contain the below constructor,
+which declares a new unit test named ``new-module``,
+with a single test case consisting of the class ``NewModuleTestCase1``::
+
+ NewModuleTestSuite::NewModuleTestSuite ()
: TestSuite ("new-module", UNIT)
{
- AddTestCase (new New-moduleTestCase1);
+ AddTestCase (new NewModuleTestCase1);
}
-Step 3 - Adding to your module's source files
-*********************************************
+Step 3 - Declare Source Files
+*****************************
-If your new module has model and/or helper source files, then they
-must be specified in your
+The public header and source code files for your new module
+should be specified in the ``wscript`` file by modifying it with
+your text editor.
-.. sourcecode:: text
-
- src/new-module/wscript
-
-file by modifying it with your text editor.
-
-As an example, the source files for the spectrum module are specified
-in
-
-.. sourcecode:: text
-
- src/spectrum/wscript
-
-with the following list of source files:
+As an example, after declaring the ``spectrum`` module,
+the ``src/spectrum/wscript`` specifies the source code files
+with the following list:
.. sourcecode:: python
- module.source = [
- 'model/spectrum-model.cc',
- 'model/spectrum-value.cc',
+ def build(bld):
+
+ module = bld.create_ns3_module('spectrum', ['internet', 'propagation', 'antenna', 'applications'])
+
+ module.source = [
+ 'model/spectrum-model.cc',
+ 'model/spectrum-value.cc',
.
.
.
- 'model/microwave-oven-spectrum-value-helper.cc',
- 'helper/spectrum-helper.cc',
- 'helper/adhoc-aloha-noack-ideal-phy-helper.cc',
- 'helper/waveform-generator-helper.cc',
- 'helper/spectrum-analyzer-helper.cc',
- ]
+ 'model/microwave-oven-spectrum-value-helper.cc',
+ 'helper/spectrum-helper.cc',
+ 'helper/adhoc-aloha-noack-ideal-phy-helper.cc',
+ 'helper/waveform-generator-helper.cc',
+ 'helper/spectrum-analyzer-helper.cc',
+ ]
-Step 4 - Specify your module's header files
-*******************************************
+The objects resulting from compiling these sources will be assembled
+into a link library, which will be linked to any programs relying on this
+module.
-If your new module has model and/or helper header files, then they
-must be specified in your
+But how do such programs learn the public API of our new module? Read on!
-.. sourcecode:: text
+Step 4 - Declare Public Header Files
+************************************
- src/new-module/wscript
+The header files defining the public API of your model and helpers
+also should be specified in the ``wscript`` file.
-file by modifying it with your text editor.
-
-As an example, the header files for the spectrum module are specified
-in
-
-.. sourcecode:: text
-
- src/spectrum/wscript
-
-with the following function call, module name, and list of header
-files. Note that the argument for the function new_task_gen() tells
-waf to install this module's headers with the other |ns3| headers:
+Continuing with the ``spectrum`` model illustration,
+the public header files are specified with the following stanza.
+(Note that the argument to the ``bld`` function tells
+``waf`` to install this module's headers with the other |ns3| headers):
.. sourcecode:: python
@@ -169,24 +205,29 @@ waf to install this module's headers with the other |ns3| headers:
'helper/spectrum-analyzer-helper.h',
]
-Step 5 - Specify your module's tests
-************************************
+Headers made public in this way will be accessible to users of your model
+with include statements like
+
+.. sourcecode:: cpp
+
+ #include "ns3/spectrum-model.h"
+
+Headers used strictly internally in your implementation should not
+be included here. They are still accessible to your implemenation by
+include statements like
+
+.. sourcecode:: cpp
+
+ #include "my-module-implementation.h"
+
+
+Step 5 - Declare Tests
+**********************
If your new module has tests, then they must be specified in your
+``wscript`` file by modifying it with your text editor.
-.. sourcecode:: text
-
- src/new-module/wscript
-
-file by modifying it with your text editor.
-
-As an example, the tests for the spectrum module are specified in
-
-.. sourcecode:: text
-
- src/spectrum/wscript
-
-with the following function call and list of test suites:
+The ``spectrum`` model tests are specified with the following stanza:
.. sourcecode:: python
@@ -197,62 +238,62 @@ with the following function call and list of test suites:
'test/spectrum-value-test.cc',
]
+See :doc:`Tests ` for more information on how to write test cases.
-Step 6 - Specify your module's examples
-***************************************
+Step 6 - Declare Examples
+*************************
If your new module has examples, then they must be specified in your
+``examples/wscript`` file. (The skeleton top-level ``wscript`` will
+recursively include ``examples/wscript`` only if the examples were
+enabled at configure time.)
-.. sourcecode:: text
-
- src/new-module/examples/wscript
-
-file by modifying it with your text editor.
-
-As an example, the examples for the core module are specified in
-
-.. sourcecode:: text
-
- src/core/examples/wscript
-
-The core module's C++ examples are specified using the following
-function calls and source file names. Note that the second argument
-for the function ``create_ns3_program()`` is the list of modules that the
-program being created depends on:
+The ``spectrum`` model defines it's first example in
+``src/spectrum/examples/wscript`` with
.. sourcecode:: python
- obj = bld.create_ns3_program('main-callback', ['core'])
- obj.source = 'main-callback.cc'
+ def build(bld):
+ obj = bld.create_ns3_program('adhoc-aloha-ideal-phy',
+ ['spectrum', 'mobility'])
+ obj.source = 'adhoc-aloha-ideal-phy.cc'
- obj = bld.create_ns3_program('sample-simulator', ['core'])
- obj.source = 'sample-simulator.cc'
+Note that the second argument to the function ``create_ns3_program()``
+is the list of modules that the program being created depends on; again,
+don't forget to include ``new-module`` in the list. It's best practice
+to list only the direct module dependencies, and let ``waf`` deduce
+the full dependency tree.
-The core module's Python examples are specified using the following
+Occasionally, for clarity, you may want to split the implementation
+for your example among several source files. In this case, just
+include those files as additional explicit sources of the example:
+
+.. sourcecode:: python
+
+ obj = bld.create_ns3_program('new-module-example', [new-module])
+ obj.source = ['new-module-example.cc', 'new-module-example-part.cc']
+
+Python examples are specified using the following
function call. Note that the second argument for the function
-register_ns3_script() is the list of modules that the Python example
+``register_ns3_script()`` is the list of modules that the Python example
depends on:
.. sourcecode:: python
- bld.register_ns3_script('sample-simulator.py', ['core'])
+ bld.register_ns3_script('new-module-example.py', ['new-module'])
-Step 7 - Specify which of your module's examples should be run as tests
-***********************************************************************
+Step 7 - Examples Run as Tests
+******************************
-The test framework can also be instrumented to run example programs to
+In addition to running explicit test code, the test framework
+can also be instrumented to run full example programs to
try to catch regressions in the examples. However, not all examples
-are suitable for regression tests. A file called ``examples-to-run.py``
-that exists in each module's test directory can control the invocation
-of the examples when the test framework runs.
+are suitable for regression tests. The file ``test/examples-to-run.py``
+controls the invocation of the examples when the test framework runs.
-As an example, the examples that are run by ``test.py`` for the core module are specified in
-
-.. sourcecode:: text
-
- src/core/test/examples-to-run.py
-
-using the following two lists of C++ and Python examples:
+The ``spectrum`` model examples run by ``test.py`` are specified in
+``src/spectrum/test/examples-to-run.py`` using the following
+two lists of C++ and Python examples:
.. sourcecode:: python
@@ -263,12 +304,9 @@ using the following two lists of C++ and Python examples:
#
# See test.py for more information.
cpp_examples = [
- ("main-attribute-value", "True", "True"),
- ("main-callback", "True", "True"),
- ("sample-simulator", "True", "True"),
- ("main-ptr", "True", "True"),
- ("main-random-variable", "True", "True"),
- ("sample-random-variable", "True", "True"),
+ ("adhoc-aloha-ideal-phy", "True", "True"),
+ ("adhoc-aloha-ideal-phy-with-microwave-oven", "True", "True"),
+ ("adhoc-aloha-ideal-phy-matrix-propagation-loss-model", "True", "True"),
]
# A list of Python examples to run in order to ensure that they remain
@@ -281,57 +319,43 @@ using the following two lists of C++ and Python examples:
("sample-simulator.py", "True"),
]
-Each tuple in the C++ list of examples to run contains
+As indicated in the comment, each entry in the C++ list of examples to run
+contains the tuple ``(example_name, do_run, do_valgrind_run)``, where
-.. sourcecode:: python
-
- (example_name, do_run, do_valgrind_run)
-
-where example_name is the executable to be run, do_run is a
-condition under which to run the example, and do_valgrind_run is
-a condition under which to run the example under valgrind. This
-is needed because NSC causes illegal instruction crashes with
-some tests when they are run under valgrind.
+ * ``example_name`` is the executable to be run,
+ * ``do_run`` is a condition under which to run the example, and
+ * ``do_valgrind_run`` is a condition under which to run the example
+ under valgrind. (This is needed because NSC causes illegal instruction
+ crashes with some tests when they are run under valgrind.)
Note that the two conditions are Python statements that
-can depend on waf configuration variables. For example,
+can depend on ``waf`` configuration variables. For example,
.. sourcecode:: python
("tcp-nsc-lfn", "NSC_ENABLED == True", "NSC_ENABLED == False"),
-Each tuple in the Python list of examples to run contains
+Each entry in the Python list of examples to run contains the tuple
+``(example_name, do_run)``, where, as for the C++ examples,
-.. sourcecode:: python
+ * ``example_name`` is the Python script to be run, and
+ * ``do_run`` is a condition under which to run the example.
- (example_name, do_run)
-
-where example_name is the Python script to be run and
-do_run is a condition under which to run the example.
-
-Note that the condition is a Python statement that can
-depend on waf configuration variables. For example,
+Again, the condition is a Python statement that can
+depend on ``waf`` configuration variables. For example,
.. sourcecode:: python
("realtime-udp-echo.py", "ENABLE_REAL_TIME == False"),
-If your new module has examples, then you must specify which of them
-should be run in your
-.. sourcecode:: text
+Step 8 - Configure and Build
+****************************
- src/new-module/test/examples-to-run.py
-
-file by modifying it with your text editor. These examples are run by
-test.py.
-
-Step 8 - Build and test your new module
-***************************************
-
-You can now build and test your module as normal. You must reconfigure
-the project as a first step or else your new module will not be included
-in the build.
+You can now configure, build and test your module as normal.
+You must reconfigure the project as a first step so that ``waf``
+caches the new information in your ``wscript`` files,
+or else your new module will not be included in the build.
.. sourcecode:: bash
@@ -339,9 +363,11 @@ in the build.
$ ./waf build
$ ./test.py
-and look for your new module's test suite (and example programs, if enabled) in the test output.
+Look for your new module's test suite (and example programs,
+if your module has any enabled) in the test output.
-Step 9 - Python bindings
+
+Step 9 - Python Bindings
************************
Adding Python bindings to your module is optional, and the step is
diff --git a/src/energy/doc/energy.rst b/src/energy/doc/energy.rst
index a14a49c87..ca7201b29 100644
--- a/src/energy/doc/energy.rst
+++ b/src/energy/doc/energy.rst
@@ -1,7 +1,16 @@
Energy Framework
----------------
-Energy consumption is a key issue for wireless devices, and wireless network researchers often need to investigate the energy consumption at a node or in the overall network while running network simulations in ns-3. This requires ns-3 to support energy consumption modeling. Further, as concepts such as fuel cells and energy scavenging are becoming viable for low power wireless devices, incorporating the effect of these emerging technologies into simulations requires support for modeling diverse energy sources in ns-3. The ns-3 Energy Framework provides the basis for energy consumption, energy source and energy harvesting modeling.
+Energy consumption is a key issue for wireless devices, and wireless
+network researchers often need to investigate the energy consumption
+at a node or in the overall network while running network simulations
+in ns-3. This requires ns-3 to support energy consumption
+modeling. Further, as concepts such as fuel cells and energy
+scavenging are becoming viable for low power wireless devices,
+incorporating the effect of these emerging technologies into
+simulations requires support for modeling diverse energy sources in
+ns-3. The ns-3 Energy Framework provides the basis for energy
+consumption, energy source and energy harvesting modeling.
Model Description
@@ -12,76 +21,197 @@ The source code for the Energy Framework is currently at: ``src/energy``.
Design
******
-The ns-3 Energy Framework is composed of 3 parts: Energy Source, Device Energy Model and Energy Harvester.
-The framework is implemented into the ``src/energy/models`` folder.
+The ns-3 Energy Framework is composed of 3 parts: Energy Source,
+Device Energy Model and Energy Harvester. The framework is
+implemented into the ``src/energy/models`` folder.
Energy Source
#############
-The Energy Source represents the power supply on each node. A node can have one or more energy sources, and each energy source can be connected to multiple device energy models. Connecting an energy source to a device energy model implies that the corresponding device draws power from the source. The basic functionality of the Energy Source is to provide energy for devices on the node. When energy is completely drained from the Energy Source, it notifies the devices on node such that each device can react to this event. Further, each node can access the Energy Source Objects for information such as remaining energy or energy fraction (battery level). This enables the implementation of energy aware protocols in ns-3.
+The Energy Source represents the power supply on each node. A node can
+have one or more energy sources, and each energy source can be
+connected to multiple device energy models. Connecting an energy
+source to a device energy model implies that the corresponding device
+draws power from the source. The basic functionality of the Energy
+Source is to provide energy for devices on the node. When energy is
+completely drained from the Energy Source, it notifies the devices on
+node such that each device can react to this event. Further, each node
+can access the Energy Source Objects for information such as remaining
+energy or energy fraction (battery level). This enables the
+implementation of energy aware protocols in ns-3.
-In order to model a wide range of power supplies such as batteries, the Energy Source must be able to capture characteristics of these supplies. There are 2 important characteristics or effects related to practical batteries:
+In order to model a wide range of power supplies such as batteries,
+the Energy Source must be able to capture characteristics of these
+supplies. There are 2 important characteristics or effects related to
+practical batteries:
-* Rate Capacity Effect: Decrease of battery lifetime when the current draw is higher than the rated value of the battery.
-* Recovery Effect: Increase of battery lifetime when the battery is alternating between discharge and idle states.
+Rate Capacity Effect
+ Decrease of battery lifetime when the current draw is higher
+ than the rated value of the battery.
+
+Recovery Effect
+ Increase of battery lifetime when the battery is alternating
+ between discharge and idle states.
-In order to incorporate the Rate Capacity Effect, the Energy Source uses current draw from all the devices on the same node to calculate energy consumption. Moreover, multiple Energy Harvesters can be connected to the Energy Source in order to replenish its energy. The Energy Source periodically polls all the devices and energy harvesters on the same node to calculate the total current drain and hence the energy consumption. When a device changes state, its corresponding Device Energy Model will notify the Energy Source of this change and new total current draw will be calculated. Similarly, every Energy Harvester update triggers an update to the connected Energy Source.
+In order to incorporate the Rate Capacity Effect, the Energy Source
+uses current draw from all the devices on the same node to calculate
+energy consumption. Moreover, multiple Energy Harvesters can be
+connected to the Energy Source in order to replenish its energy. The
+Energy Source periodically polls all the devices and energy harvesters
+on the same node to calculate the total current drain and hence the
+energy consumption. When a device changes state, its corresponding
+Device Energy Model will notify the Energy Source of this change and
+new total current draw will be calculated. Similarly, every Energy
+Harvester update triggers an update to the connected Energy Source.
-The Energy Source base class keeps a list of devices (Device Energy Model objects) and energy harvesters (Energy Harvester objects) that are using the particular Energy Source as power supply. When energy is completely drained, the Energy Source will notify all devices on this list. Each device can then handle this event independently, based on the desired behavior that should be followed in case of power outage.
+The Energy Source base class keeps a list of devices (Device Energy
+Model objects) and energy harvesters (Energy Harvester objects) that
+are using the particular Energy Source as power supply. When energy is
+completely drained, the Energy Source will notify all devices on this
+list. Each device can then handle this event independently, based on
+the desired behavior that should be followed in case of power outage.
Device Energy Model
###################
-The Device Energy Model is the energy consumption model of a device installed on the node. It is designed to be a state based model where each device is assumed to have a number of states, and each state is associated with a power consumption value. Whenever the state of the device changes, the corresponding Device Energy Model will notify the Energy Source of the new current draw of the device. The Energy Source will then calculate the new total current draw and update the remaining energy.
+The Device Energy Model is the energy consumption model of a device
+installed on the node. It is designed to be a state based model where
+each device is assumed to have a number of states, and each state is
+associated with a power consumption value. Whenever the state of the
+device changes, the corresponding Device Energy Model will notify the
+Energy Source of the new current draw of the device. The Energy Source
+will then calculate the new total current draw and update the
+remaining energy.
-The Device Energy Model can also be used for devices that do not have finite number of states. For example, in an electric vehicle, the current draw of the motor is determined by its speed. Since the vehicle's speed can take continuous values within a certain range, it is infeasible to define a set of discrete states of operation. However, by converting the speed value into current directly, the same set of Device Energy Model APIs can still be used.
+The Device Energy Model can also be used for devices that do not have
+finite number of states. For example, in an electric vehicle, the
+current draw of the motor is determined by its speed. Since the
+vehicle's speed can take continuous values within a certain range, it
+is infeasible to define a set of discrete states of
+operation. However, by converting the speed value into current
+directly, the same set of Device Energy Model APIs can still be used.
Energy Harvester
-#############
+################
-The energy harvester represents the elements that harvest energy from the environment and recharge the Energy Source to which it is connected. The energy harvester includes the complete implementation of the actual energy harvesting device (e.g., a solar panel) and the environment (e.g., the solar radiation). This means that in implementing an energy harvester, the energy contribution of the environment and the additional energy requirements of the energy harvesting device such as the conversion efficiency and the internal power consumption of the device needs to be jointly modeled.
+The energy harvester represents the elements that harvest energy from
+the environment and recharge the Energy Source to which it is
+connected. The energy harvester includes the complete implementation
+of the actual energy harvesting device (e.g., a solar panel) and the
+environment (e.g., the solar radiation). This means that in
+implementing an energy harvester, the energy contribution of the
+environment and the additional energy requirements of the energy
+harvesting device such as the conversion efficiency and the internal
+power consumption of the device needs to be jointly modeled.
WiFi Radio Energy Model
#######################
-The WiFi Radio Energy Model is the energy consumption model of a Wifi net device. It provides a state for each of the available states of the PHY layer: Idle, CcaBusy, Tx, Rx, ChannelSwitch, Sleep. Each of such states is associated with a value (in Ampere) of the current draw (see below for the corresponding attribute names). A Wifi Radio Energy Model PHY Listener is registered to the Wifi PHY in order to be notified of every Wifi PHY state transition. At every transition, the energy consumed in the previous state is computed and the energy source is notified in order to update its remaining energy.
+The WiFi Radio Energy Model is the energy consumption model of a Wifi
+net device. It provides a state for each of the available states of
+the PHY layer: Idle, CcaBusy, Tx, Rx, ChannelSwitch, Sleep. Each of
+such states is associated with a value (in Ampere) of the current draw
+(see below for the corresponding attribute names). A Wifi Radio Energy
+Model PHY Listener is registered to the Wifi PHY in order to be
+notified of every Wifi PHY state transition. At every transition, the
+energy consumed in the previous state is computed and the energy
+source is notified in order to update its remaining energy.
-The Wifi Tx Current Model gives the possibility to compute the current draw in the transmit state as a function of the nominal tx power (in dBm), as observed in several experimental measurements. To this purpose, the Wifi Radio Energy Model PHY Listener is notified of the nominal tx power used to transmit the current frame and passes such a value to the Wifi Tx Current Model which takes care of updating the current draw in the Tx state. Hence, the energy consumption is correctly computed even if the Wifi Remote Station Manager performs per-frame power control. Currently, a Linear Wifi Tx Current Model is implemented which computes the tx current as a linear function (according to parameters that can be specified by the user) of the nominal tx power in dBm.
+The Wifi Tx Current Model gives the possibility to compute the current
+draw in the transmit state as a function of the nominal tx power (in
+dBm), as observed in several experimental measurements. To this
+purpose, the Wifi Radio Energy Model PHY Listener is notified of the
+nominal tx power used to transmit the current frame and passes such a
+value to the Wifi Tx Current Model which takes care of updating the
+current draw in the Tx state. Hence, the energy consumption is
+correctly computed even if the Wifi Remote Station Manager performs
+per-frame power control. Currently, a Linear Wifi Tx Current Model is
+implemented which computes the tx current as a linear function
+(according to parameters that can be specified by the user) of the
+nominal tx power in dBm.
-The Wifi Radio Energy Model offers the possibility to specify a callback that is invoked when the energy source is depleted. If such a callback is not specified when the Wifi Radio Energy Model Helper is used to install the model on a device, a callback is implicitly made so that the Wifi PHY is put in the SLEEP mode (hence no frame is transmitted nor received afterwards) when the energy source is depleted. Likewise, it is possible to specify a callback that is invoked when the energy source is recharged (which might occur in case an energy harvester is connected to the energy source). If such a callback is not specified when the Wifi Radio Energy Model Helper is used to install the model on a device, a callback is implicitly made so that the Wifi PHY is resumed from the SLEEP mode when the energy source is recharged.
+The Wifi Radio Energy Model offers the possibility to specify a
+callback that is invoked when the energy source is depleted. If such a
+callback is not specified when the Wifi Radio Energy Model Helper is
+used to install the model on a device, a callback is implicitly made
+so that the Wifi PHY is put in the SLEEP mode (hence no frame is
+transmitted nor received afterwards) when the energy source is
+depleted. Likewise, it is possible to specify a callback that is
+invoked when the energy source is recharged (which might occur in case
+an energy harvester is connected to the energy source). If such a
+callback is not specified when the Wifi Radio Energy Model Helper is
+used to install the model on a device, a callback is implicitly made
+so that the Wifi PHY is resumed from the SLEEP mode when the energy
+source is recharged.
Future Work
***********
-For Device Energy Models, we are planning to include support for other PHY layer models provided in ns-3 such as WiMAX, and to model the energy consumptions of other non communicating devices, like a generic sensor and a CPU. For Energy Sources, we are planning to included new types of Energy Sources such as Supercapacitor and NickelÐMetal Hydride (Ni-MH) battery. For the Energy Harvesters, we are planning to implement an energy harvester that recharges the energy sources according to the power levels defined in a user customizable dataset of real measurements.
+For Device Energy Models, we are planning to include support for other
+PHY layer models provided in ns-3 such as WiMAX, and to model the
+energy consumptions of other non communicating devices, like a generic
+sensor and a CPU. For Energy Sources, we are planning to included new
+types of Energy Sources such as Supercapacitor and Nickel-Metal
+Hydride (Ni-MH) battery. For the Energy Harvesters, we are planning to
+implement an energy harvester that recharges the energy sources
+according to the power levels defined in a user customizable dataset
+of real measurements.
References
**********
-.. [1] ns-2 Energy model: http://www.cubinlab.ee.unimelb.edu.au/~jrid/Docs/Manuel-NS2/node204.html
-.. [2] H. Wu, S. Nabar and R. Poovendran. An Energy Framework for the Network Simulator 3 (ns-3).
-.. [3] M. Handy and D. Timmermann. Simulation of mobile wireless networks with accurate
- modelling of non-linear battery effects. In Proc. of Applied simulation and Modeling
- (ASM), 2003.
-.. [4] D. N. Rakhmatov and S. B. Vrudhula. An analytical high-level battery model for use in energy
- management of portable electronic systems. In Proc. of IEEE/ACM International Conference on
- Computer Aided Design (ICCAD'01), pages 488-493, November 2001.
-.. [5] D. N. Rakhmatov, S. B. Vrudhula, and D. A. Wallach. Battery lifetime prediction for
- energy-aware computing. In Proc. of the 2002 International Symposium on Low Power
- Electronics and Design (ISLPED'02), pages 154-159, 2002.
-.. [6] 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.
+.. [1] ns-2 Energy model:
+ http://www.cubinlab.ee.unimelb.edu.au/~jrid/Docs/Manuel-NS2/node204.html
+
+.. [2] H. Wu, S. Nabar and R. Poovendran. An Energy Framework for the
+ Network Simulator 3 (ns-3).
+
+.. [3] M. Handy and D. Timmermann. Simulation of mobile wireless
+ networks with accurate modelling of non-linear battery effects. In
+ Proc. of Applied simulation and Modeling (ASM), 2003.
+
+.. [4] D. N. Rakhmatov and S. B. Vrudhula. An analytical high-level
+ battery model for use in energy management of portable electronic
+ systems. In Proc. of IEEE/ACM International Conference on Computer
+ Aided Design (ICCAD'01), pages 488-493, November 2001.
+
+.. [5] D. N. Rakhmatov, S. B. Vrudhula, and D. A. Wallach. Battery
+ lifetime prediction for energy-aware computing. In Proc. of the 2002
+ International Symposium on Low Power Electronics and Design
+ (ISLPED'02), pages 154-159, 2002.
+
+.. [6] 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.
Usage
=====
-The main way that ns-3 users will typically interact with the Energy Framework is through the helper API and through the publicly visible attributes of the framework. The helper API is defined in ``src/energy/helper/*.h``.
+The main way that ns-3 users will typically interact with the Energy
+Framework is through the helper API and through the publicly visible
+attributes of the framework. The helper API is defined in
+``src/energy/helper/*.h``.
-In order to use the energy framework, the user must install an Energy Source for the node of interest, the corresponding Device Energy Model for the network devices and, if necessary, the one or more Energy Harvester. Energy Source (objects) are aggregated onto each node by the Energy Source Helper. In order to allow multiple energy sources per node, we aggregate an Energy Source Container rather than directly aggregating a source object.
+In order to use the energy framework, the user must install an Energy
+Source for the node of interest, the corresponding Device Energy Model
+for the network devices and, if necessary, the one or more Energy
+Harvester. Energy Source (objects) are aggregated onto each node by
+the Energy Source Helper. In order to allow multiple energy sources
+per node, we aggregate an Energy Source Container rather than directly
+aggregating a source object.
-The Energy Source object keeps a list of Device Energy Model and Energy Harvester objects using the source as power supply. Device Energy Model objects are installed onto the Energy Source by the Device Energy Model Helper, while Energy Harvester object are installed by the Energy Harvester Helper. User can access the Device Energy Model objects through the Energy Source object to obtain energy consumption information of individual devices. Moreover, the user can access to the Energy Harvester objects in order to gather information regarding the current harvestable power and the total energy harvested by the harvester.
+The Energy Source object keeps a list of Device Energy Model and
+Energy Harvester objects using the source as power supply. Device
+Energy Model objects are installed onto the Energy Source by the
+Device Energy Model Helper, while Energy Harvester object are
+installed by the Energy Harvester Helper. User can access the Device
+Energy Model objects through the Energy Source object to obtain energy
+consumption information of individual devices. Moreover, the user can
+access to the Energy Harvester objects in order to gather information
+regarding the current harvestable power and the total energy harvested
+by the harvester.
Examples
@@ -97,35 +227,48 @@ Helpers
Energy Source Helper
####################
-Base helper class for Energy Source objects, this helper Aggregates Energy Source object onto a node. Child implementation of this class creates the actual Energy Source object.
+Base helper class for Energy Source objects, this helper Aggregates
+Energy Source object onto a node. Child implementation of this class
+creates the actual Energy Source object.
Device Energy Model Helper
##########################
-Base helper class for Device Energy Model objects, this helper attaches Device Energy Model objects onto Energy Source objects. Child implementation of this class creates the actual Device Energy Model object.
+Base helper class for Device Energy Model objects, this helper
+attaches Device Energy Model objects onto Energy Source objects. Child
+implementation of this class creates the actual Device Energy Model
+object.
Energy Harvesting Helper
##########################
-Base helper class for Energy Harvester objects, this helper attaches Energy Harvester objects onto Energy Source objects. Child implementation of this class creates the actual Energy Harvester object.
+Base helper class for Energy Harvester objects, this helper attaches
+Energy Harvester objects onto Energy Source objects. Child
+implementation of this class creates the actual Energy Harvester
+object.
Attributes
**********
-Attributes differ between Energy Sources, Devices Energy Models and Energy Harvesters implementations, please look at the specific child class for details.
+Attributes differ between Energy Sources, Devices Energy Models and
+Energy Harvesters implementations, please look at the specific child
+class for details.
Basic Energy Source
###################
-* ``BasicEnergySourceInitialEnergyJ``: Initial energy stored in basic energy source.
+* ``BasicEnergySourceInitialEnergyJ``: Initial energy stored in
+ basic energy source.
* ``BasicEnergySupplyVoltageV``: Initial supply voltage for basic energy source.
-* ``PeriodicEnergyUpdateInterval``: Time between two consecutive periodic energy updates.
+* ``PeriodicEnergyUpdateInterval``: Time between two consecutive periodic
+ energy updates.
RV Battery Model
################
-* ``RvBatteryModelPeriodicEnergyUpdateInterval``: RV battery model sampling interval.
+* ``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.
@@ -146,13 +289,17 @@ WiFi Radio Energy Model
Basic Energy Harvester
#######################
-* ``PeriodicHarvestedPowerUpdateInterval``: Time between two consecutive periodic updates of the harvested power.
-* ``HarvestablePower``: Random variables that represents the amount of power that is provided by the energy harvester.
+* ``PeriodicHarvestedPowerUpdateInterval``: Time between two consecutive
+ periodic updates of the harvested power.
+* ``HarvestablePower``: Random variables that represents the amount of power
+ that is provided by the energy harvester.
Tracing
*******
-Traced values differ between Energy Sources, Devices Energy Models and Energy Harvesters implementations, please look at the specific child class for details.
+Traced values differ between Energy Sources, Devices Energy Models and
+Energy Harvesters implementations, please look at the specific child
+class for details.
Basic Energy Source
###################
@@ -180,4 +327,8 @@ Basic Energy Harvester
Validation
**********
-Comparison of the Energy Framework against actual devices have not been performed. Current implementation of the Energy Framework is checked numerically for computation errors. The RV battery model is validated by comparing results with what was presented in the original RV battery model paper.
+Comparison of the Energy Framework against actual devices have not
+been performed. Current implementation of the Energy Framework is
+checked numerically for computation errors. The RV battery model is
+validated by comparing results with what was presented in the original
+RV battery model paper.