https://www.nsnam.org/mediawiki/api.php?action=feedcontributions&user=Uwnsl&feedformat=atomNsnam - User contributions [en]2024-03-29T07:15:20ZUser contributionsMediaWiki 1.24.1https://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_device_energy_model.PNG&diff=5248File:Ns-3 device energy model.PNG2011-02-25T00:46:20Z<p>Uwnsl: uploaded a new version of "File:Ns-3 device energy model.PNG"</p>
<hr />
<div>ns-3 device energy model.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_device_energy_model.PNG&diff=5247File:Ns-3 device energy model.PNG2011-02-25T00:41:02Z<p>Uwnsl: uploaded a new version of "File:Ns-3 device energy model.PNG":&#32;Reverted to version as of 01:22, 9 August 2010</p>
<hr />
<div>ns-3 device energy model.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_device_energy_model.PNG&diff=5246File:Ns-3 device energy model.PNG2011-02-25T00:40:37Z<p>Uwnsl: uploaded a new version of "File:Ns-3 device energy model.PNG"</p>
<hr />
<div>ns-3 device energy model.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_energy_source.PNG&diff=5245File:Ns-3 energy source.PNG2011-02-25T00:38:30Z<p>Uwnsl: uploaded a new version of "File:Ns-3 energy source.PNG"</p>
<hr />
<div>Class structure of ns-3 energy source.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=5244Wireless jamming model2011-02-25T00:04:45Z<p>Uwnsl: /* Schedule */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - now : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010 : Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''StopJammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_wireless_module_utility_flow.PNG|thumb|Wireless Module Utility work flow.]]<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
jammerHelper.Set ("ReactiveJammerReactionStrategy",<br />
UintegerValue(ReactiveJammer::FIXED_PROBABILITY));<br />
// enable jammer reaction to jamming mitigation<br />
jammerHelper.Set ("ReactiveJammerReactToMitigation", UintegerValue(true));<br />
// install jammer<br />
JammerContainer jammers = jammerHelper.Install (c.Get (4));<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer from jammer container */<br />
Ptr<Jammer> jammerPtr = jammers.Get (0);<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopChannelHopDelay",<br />
TimeValue (Seconds (0.0)));<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionMethod",<br />
UintegerValue (MitigateByChannelHop::PDR_AND_RSS));<br />
// install mitigation on honest nodes<br />
JammingMitigationContainer mitigators = mitigationHelper.Install (honestNodes);<br />
// get pointer to mitigation object from jamming mitigation container<br />
Ptr<JammingMitigation> mitigationPtr = mitigators.Get (0);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install WirelessModuleUtility */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set inclusion/exclusion list for all nodes<br />
std::vector<std::string> AllInclusionList;<br />
AllInclusionList.push_back ("ns3::UdpHeader"); // record only UdpHeader<br />
std::vector<std::string> AllExclusionList;<br />
AllExclusionList.push_back ("ns3::olsr::PacketHeader"); // ignore all olsr headers/trailers<br />
// assign lists to helper<br />
utilityHelper.SetInclusionList (AllInclusionList);<br />
utilityHelper.SetExclusionList (AllExclusionList);<br />
// install on all nodes<br />
WirelessModuleUtilityContainer utilities = utilityHelper.InstallAll ();</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5243Energy model2011-02-24T23:57:11Z<p>Uwnsl: /* Wifi Radio Energy Model */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*03/24/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" presentation at the [http://www.simutools.org/2011/Programme/Schedule SIMUTOOLS 2011] conference.<br />
*01/13/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" accepted by the [http://www.simutools.org/2011/ SIMUTOOLS 2011] conference.<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
These states are defined in the WifiPhy class of ns-3.<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
The WifiRadioEnergyModel class fully supports the ns-3 built-in WiFi PHY class (YansWifiPhy). A sample simulation script of using the energy model is available in the "examples/energy" folder of ns-3.10.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5242Energy model2011-02-24T23:55:41Z<p>Uwnsl: /* Usage */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*03/24/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" presentation at the [http://www.simutools.org/2011/Programme/Schedule SIMUTOOLS 2011] conference.<br />
*01/13/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" accepted by the [http://www.simutools.org/2011/ SIMUTOOLS 2011] conference.<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
The WifiRadioEnergyModel class fully supports the ns-3 built-in WiFi PHY class (YansWifiPhy). A sample simulation script of using the energy model is available in the "examples/energy" folder of ns-3.10.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5241Energy model2011-02-24T23:55:02Z<p>Uwnsl: /* Usage */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*03/24/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" presentation at the [http://www.simutools.org/2011/Programme/Schedule SIMUTOOLS 2011] conference.<br />
*01/13/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" accepted by the [http://www.simutools.org/2011/ SIMUTOOLS 2011] conference.<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
The WifiRadioEnergyModel class fully supports the ns-3 built-in WiFi PHY class (YansWifiPhy). A sample code of using the energy model is available in the /examples/energy folder of ns-3.10.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5240Energy model2011-02-24T23:52:39Z<p>Uwnsl: /* Usage */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*03/24/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" presentation at the [http://www.simutools.org/2011/Programme/Schedule SIMUTOOLS 2011] conference.<br />
*01/13/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" accepted by the [http://www.simutools.org/2011/ SIMUTOOLS 2011] conference.<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
The WifiRadioEnergyModel class fully supports the ns-3 built-in WiFi PHY class (YansWifiPhy).<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5239Energy model2011-02-24T23:37:21Z<p>Uwnsl: /* Schedule */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*03/24/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" presentation at the [http://www.simutools.org/2011/Programme/Schedule SIMUTOOLS 2011] conference.<br />
*01/13/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" accepted by the [http://www.simutools.org/2011/ SIMUTOOLS 2011] conference.<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5238Energy model2011-02-24T23:35:48Z<p>Uwnsl: /* Schedule */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*01/13/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" was accepted by the [http://www.simutools.org/2011/ SIMUTOOLS 2011] conference.<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5237Energy model2011-02-24T23:34:58Z<p>Uwnsl: /* Schedule */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*01/13/2011 : Paper "An Energy Framework for the Network Simulator 3 (ns-3)" was accepted by the SIMUTOOLS 2011 conference.<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=5236Energy model2011-02-24T23:26:29Z<p>Uwnsl: /* Schedule */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*01/05/2011 : Code update released with ns-3.10 in src/contrib/energy<br />
*08/20/2010 - 01/04/2011: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4991Energy model2010-10-24T20:55:05Z<p>Uwnsl: /* Schedule */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*08/20/2010 - now: Public review. Code available at: http://codereview.appspot.com/1008043/show<br />
*08/20/2010 : Released with ns-3.9 in src/contrib/energy.<br />
*04/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4990Energy model2010-10-24T20:51:28Z<p>Uwnsl: /* Device Energy Model */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4989Energy model2010-10-24T20:50:09Z<p>Uwnsl: /* Energy Source */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Rakhmatov-Vrudhula non-linear battery model.<br />
**Non-linear battery model capable of capturing Rate Capacity Effect and Recovery Effect.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4988Energy model2010-10-24T20:48:11Z<p>Uwnsl: Undo revision 4987 by Uwnsl (Talk)</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4987Energy model2010-10-24T20:46:39Z<p>Uwnsl: /* Public APIs */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where DeviceEnergyModel is installed.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where DeviceEnergyModel is installed.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4986Energy model2010-10-24T20:46:19Z<p>Uwnsl: /* Wifi Radio Energy Model */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with states:<br />
*IDLE<br />
*CCA_BUSY<br />
*TX<br />
*RX<br />
*SWITCHING<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where DeviceEnergyModel is installed.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where DeviceEnergyModel is installed.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4957Wireless jamming model2010-09-17T20:08:16Z<p>Uwnsl: /* Jamming Mitigation */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''StopJammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_wireless_module_utility_flow.PNG|thumb|Wireless Module Utility work flow.]]<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
jammerHelper.Set ("ReactiveJammerReactionStrategy",<br />
UintegerValue(ReactiveJammer::FIXED_PROBABILITY));<br />
// enable jammer reaction to jamming mitigation<br />
jammerHelper.Set ("ReactiveJammerReactToMitigation", UintegerValue(true));<br />
// install jammer<br />
JammerContainer jammers = jammerHelper.Install (c.Get (4));<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer from jammer container */<br />
Ptr<Jammer> jammerPtr = jammers.Get (0);<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopChannelHopDelay",<br />
TimeValue (Seconds (0.0)));<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionMethod",<br />
UintegerValue (MitigateByChannelHop::PDR_AND_RSS));<br />
// install mitigation on honest nodes<br />
JammingMitigationContainer mitigators = mitigationHelper.Install (honestNodes);<br />
// get pointer to mitigation object from jamming mitigation container<br />
Ptr<JammingMitigation> mitigationPtr = mitigators.Get (0);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install WirelessModuleUtility */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set inclusion/exclusion list for all nodes<br />
std::vector<std::string> AllInclusionList;<br />
AllInclusionList.push_back ("ns3::UdpHeader"); // record only UdpHeader<br />
std::vector<std::string> AllExclusionList;<br />
AllExclusionList.push_back ("ns3::olsr::PacketHeader"); // ignore all olsr headers/trailers<br />
// assign lists to helper<br />
utilityHelper.SetInclusionList (AllInclusionList);<br />
utilityHelper.SetExclusionList (AllExclusionList);<br />
// install on all nodes<br />
WirelessModuleUtilityContainer utilities = utilityHelper.InstallAll ();</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4956Wireless jamming model2010-09-17T20:07:41Z<p>Uwnsl: /* Wireless Module Utility */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''StopJammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_wireless_module_utility_flow.PNG|thumb|Wireless Module Utility work flow.]]<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
jammerHelper.Set ("ReactiveJammerReactionStrategy",<br />
UintegerValue(ReactiveJammer::FIXED_PROBABILITY));<br />
// enable jammer reaction to jamming mitigation<br />
jammerHelper.Set ("ReactiveJammerReactToMitigation", UintegerValue(true));<br />
// install jammer<br />
JammerContainer jammers = jammerHelper.Install (c.Get (4));<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer from jammer container */<br />
Ptr<Jammer> jammerPtr = jammers.Get (0);<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install WirelessModuleUtility */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set inclusion/exclusion list for all nodes<br />
std::vector<std::string> AllInclusionList;<br />
AllInclusionList.push_back ("ns3::UdpHeader"); // record only UdpHeader<br />
std::vector<std::string> AllExclusionList;<br />
AllExclusionList.push_back ("ns3::olsr::PacketHeader"); // ignore all olsr headers/trailers<br />
// assign lists to helper<br />
utilityHelper.SetInclusionList (AllInclusionList);<br />
utilityHelper.SetExclusionList (AllExclusionList);<br />
// install on all nodes<br />
WirelessModuleUtilityContainer utilities = utilityHelper.InstallAll ();</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4955Wireless jamming model2010-09-17T20:07:23Z<p>Uwnsl: /* Jammer */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''StopJammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_wireless_module_utility_flow.PNG|thumb|Wireless Module Utility work flow.]]<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
jammerHelper.Set ("ReactiveJammerReactionStrategy",<br />
UintegerValue(ReactiveJammer::FIXED_PROBABILITY));<br />
// enable jammer reaction to jamming mitigation<br />
jammerHelper.Set ("ReactiveJammerReactToMitigation", UintegerValue(true));<br />
// install jammer<br />
JammerContainer jammers = jammerHelper.Install (c.Get (4));<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer from jammer container */<br />
Ptr<Jammer> jammerPtr = jammers.Get (0);<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4954Wireless jamming model2010-09-17T20:07:07Z<p>Uwnsl: /* Jammer */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''StopJammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_wireless_module_utility_flow.PNG|thumb|Wireless Module Utility work flow.]]<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
jammerHelper.Set ("ReactiveJammerReactionStrategy",<br />
UintegerValue(ReactiveJammer::FIXED_PROBABILITY));<br />
// enable jammer reaction to jamming mitigation<br />
jammerHelper.Set ("ReactiveJammerReactToMitigation", UintegerValue(true));<br />
// install jammer<br />
JammerContainer jammers = jammerHelper.Install (c.Get (4));<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
/* install WirelessModuleUtility */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set inclusion/exclusion list for all nodes<br />
std::vector<std::string> AllInclusionList;<br />
AllInclusionList.push_back ("ns3::UdpHeader"); // record only UdpHeader<br />
std::vector<std::string> AllExclusionList;<br />
AllExclusionList.push_back ("ns3::olsr::PacketHeader"); // ignore all olsr headers/trailers<br />
// assign lists to helper<br />
utilityHelper.SetInclusionList (AllInclusionList);<br />
utilityHelper.SetExclusionList (AllExclusionList);<br />
// install on all nodes<br />
WirelessModuleUtilityContainer utilities = utilityHelper.InstallAll ();<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer from jammer container */<br />
Ptr<Jammer> jammerPtr = jammers.Get (0);<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_device_energy_model.PNG&diff=4779File:Ns-3 device energy model.PNG2010-08-09T01:22:39Z<p>Uwnsl: uploaded a new version of "File:Ns-3 device energy model.PNG"</p>
<hr />
<div>ns-3 device energy model.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_device_energy_model.PNG&diff=4778File:Ns-3 device energy model.PNG2010-08-09T01:13:59Z<p>Uwnsl: uploaded a new version of "File:Ns-3 device energy model.PNG"</p>
<hr />
<div>ns-3 device energy model.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4777Energy model2010-08-09T00:53:39Z<p>Uwnsl: /* Public APIs */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with operating states:<br />
*Idle<br />
*Tx<br />
*Rx<br />
*Sleep<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where DeviceEnergyModel is installed.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where DeviceEnergyModel is installed.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
* '''GetTotalEnergyConsumption:'''<br />
** Returns total energy consumed by the device.<br />
<br />
* '''ChangeState:'''<br />
** Notifies DeviceEnergyModel of a state change.<br />
** Input parameter can be the state number or a value used internally by the DeviceEnergyModel.<br />
<br />
* '''GetCurretA:'''<br />
** Returns the current draw, in Ampere of the DeviceEnergyModel, at its current state.<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4776Energy model2010-08-09T00:42:14Z<p>Uwnsl: /* Protected APIs */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with operating states:<br />
*Idle<br />
*Tx<br />
*Rx<br />
*Sleep<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''CalculateTotalCurrent:'''<br />
** Returns total current draw from all DeviceEnergyModel objects.<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4775Energy model2010-08-09T00:38:57Z<p>Uwnsl: /* Public APIs */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with operating states:<br />
*Idle<br />
*Tx<br />
*Rx<br />
*Sleep<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetSupplyVoltage:'''<br />
** Returns the supply voltage of the energy source.<br />
** Must be implemented by child classes.<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''UpdateEnergySource:'''<br />
** Notifies EnergySource of stage changes in DeviceEnergyModels. Typically called by DeviceEnergyModels to inform EnergySource of a state change.<br />
** This interface is used to implement non-linear energy update.<br />
<br />
* '''SetNode:'''<br />
** Sets reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''GetNode:'''<br />
** Returns reference (pointer) to node where EnergySource is installed on.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a DeviceEnergyModelContainer containing a list of device energy models installed on the node. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4774Energy model2010-08-09T00:28:06Z<p>Uwnsl: /* Usage */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with operating states:<br />
*Idle<br />
*Tx<br />
*Rx<br />
*Sleep<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a WifiRadioEnergyModel onto each node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
// install source<br />
EnergySourceContainer sources = basicSourceHelper.Install (c);<br />
/* device energy model */<br />
WifiRadioEnergyModelHelper radioEnergyHelper;<br />
// configure radio energy model<br />
radioEnergyHelper.Set ("TxCurrentA", DoubleValue (0.0174));<br />
// install device model<br />
DeviceEnergyModelContainer deviceModels = radioEnergyHelper.Install (devices, sources);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a list of device energy models of specified type. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4773Energy model2010-08-08T23:43:02Z<p>Uwnsl: /* Examples */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with operating states:<br />
*Idle<br />
*Tx<br />
*Rx<br />
*Sleep<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a radio energy model (BasicRadioEnergyModel) onto a node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
<br />
/* device energy model */<br />
RadioEnergyHelper radioEnergyHelper;<br />
// configure radio energy model (optional, radio energy model is configured with parameters of CC2420).<br />
radioEnergyHelper.Set ("TxPowerW", DoubleValue (0.0435));<br />
radioEnergyHelper.Set ("RxPowerW", DoubleValue (0.047));<br />
radioEnergyHelper.Set ("IdlePowerW", DoubleValue (0.001065));<br />
radioEnergyHelper.Set ("SleepPowerW", DoubleValue (0.00005));<br />
<br />
/* energy model helper */<br />
EnergyModelHelper energyHelper;<br />
// install on all nodes<br />
energyHelper.Install (basicSourceHelper, radioEnergyHelper, c);<br />
<br />
The radio energy model keeps track of the current radio state (Tx, Rx, Idle, Sleep). It has to be notified (with the destination state) whenever the radio switches state. Modification to a PHY layer class is needed so that the radio energy model can record energy consumption correctly. The following code snippet shows how to modify existing PHY object to make use of the energy model (using YansWifiPhy class as an example):<br />
<br />
#include "ns3/radio-energy-model.h"<br />
#include "ns3/energy-source.h"<br />
<br />
/* obtain pointer to energy source */<br />
Ptr<EnergySource> energySource = m_nodePtr->GetObject<EnergySource> ();<br />
<br />
/* obtain list of RadioEnergyModel objects installed from the energy source */<br />
EnergySource::DeviceEnergyModelList modelList = energySource->FindDeviceEnergyModels ("ns3::RadioEnergyModel");<br />
<br />
/* obtain a pointer from the list */<br />
if (!modelList.empty ())<br />
{<br />
Ptr<RadioEnergyModel>m_energyPtr = DynamicCast<RadioEnergyModel> (modelList[0]);<br />
}<br />
<br />
/* update energy state for TX, insert at SendPacket */<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::TX);<br />
// wait/schedule till end of TX<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::IDLE);<br />
<br />
/* update energy state for RX, insert at StartReceivePacket and EndRx */<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::RX);<br />
// wait/schedule till end of RX<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::IDLE);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a list of device energy models of specified type. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource class implementation for how the interfaces are used.<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4772Energy model2010-08-08T23:42:49Z<p>Uwnsl: /* Examples */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with operating states:<br />
*Idle<br />
*Tx<br />
*Rx<br />
*Sleep<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a radio energy model (BasicRadioEnergyModel) onto a node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
<br />
/* device energy model */<br />
RadioEnergyHelper radioEnergyHelper;<br />
// configure radio energy model (optional, radio energy model is configured with parameters of CC2420).<br />
radioEnergyHelper.Set ("TxPowerW", DoubleValue (0.0435));<br />
radioEnergyHelper.Set ("RxPowerW", DoubleValue (0.047));<br />
radioEnergyHelper.Set ("IdlePowerW", DoubleValue (0.001065));<br />
radioEnergyHelper.Set ("SleepPowerW", DoubleValue (0.00005));<br />
<br />
/* energy model helper */<br />
EnergyModelHelper energyHelper;<br />
// install on all nodes<br />
energyHelper.Install (basicSourceHelper, radioEnergyHelper, c);<br />
<br />
The radio energy model keeps track of the current radio state (Tx, Rx, Idle, Sleep). It has to be notified (with the destination state) whenever the radio switches state. Modification to a PHY layer class is needed so that the radio energy model can record energy consumption correctly. The following code snippet shows how to modify existing PHY object to make use of the energy model (using YansWifiPhy class as an example):<br />
<br />
#include "ns3/radio-energy-model.h"<br />
#include "ns3/energy-source.h"<br />
<br />
/* obtain pointer to energy source */<br />
Ptr<EnergySource> energySource = m_nodePtr->GetObject<EnergySource> ();<br />
<br />
/* obtain list of RadioEnergyModel objects installed from the energy source */<br />
EnergySource::DeviceEnergyModelList modelList = energySource->FindDeviceEnergyModels ("ns3::RadioEnergyModel");<br />
<br />
/* obtain a pointer from the list */<br />
if (!modelList.empty ())<br />
{<br />
Ptr<RadioEnergyModel>m_energyPtr = DynamicCast<RadioEnergyModel> (modelList[0]);<br />
}<br />
<br />
/* update energy state for TX, insert at SendPacket */<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::TX);<br />
// wait/schedule till end of TX<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::IDLE);<br />
<br />
/* update energy state for RX, insert at StartReceivePacket and EndRx */<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::RX);<br />
// wait/schedule till end of RX<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::IDLE);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a list of device energy models of specified type. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource and BasicRadioEnergySource class implementation for how the interfaces are used.<br />
<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the WifiRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Energy_model&diff=4771Energy model2010-08-08T23:29:13Z<p>Uwnsl: /* Wifi Radio Energy Model */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab (NSL)], University of Washington, Seattle has begun work on an generic energy model for ns3. The goal is to simulate an energy source and keep track of energy consumptions of various devices in the node. Current version focuses on radio energy consumption.<br />
<br />
= Background =<br />
<br />
Energy modeling is a key element in wireless network simulation. In several simulation scenarios, the energy consumption at a particular node, or at a particular component of a node, is of interest. Further, energy consumption is an important metric for evaluating the performance of wireless network protocols. Also, if a protocol is energy-aware, i.e. its operation depends on the energy level, it cannot be effectively simulated without an energy model. An energy model has been implemented in ns2 ([http://www.isi.edu/nsnam/ns/doc/node224.html ns2 energy model]) but is yet to be implemented in ns3.<br />
<br />
= Project Goals =<br />
<br />
In this project, we aim to provide the basic structures for modeling energy sources and energy consumption of various devices on the node. The energy source class will enable the modeling of batteries, discharging models, etc. while the energy consumption models are used to represent the energy consumed by various components of a node. The energy model will provide the following components:<br />
*Energy source model.<br />
**Battery.<br />
**etc.<br />
*Device energy consumption model.<br />
**Radio.<br />
**etc.<br />
<br />
= Schedule =<br />
<br />
*4/26/2010 - : Public review of energy model. Code available at: http://codereview.appspot.com/1008043/show<br />
*4/19/2010 - 4/23/2010: Private review of radio energy model.<br />
<br />
= Energy Model Hierarchy =<br />
<br />
[[File:Ns-3_energy_model_data_flow.PNG|thumb|Energy model information flow]]<br />
<br />
The energy model consists of 2 major components:<br />
*Energy source.<br />
*Device energy model.<br />
<br />
Only a single energy source will exist on a node, representing the total energy reserve at the node. Multiple device energy models can exist on a single node, representing different devices. Each device energy model will notify the energy source of the energy consumed by that device, and thus update the remaining energy of the source. When energy is completely drained, the energy source will notify all device energy models connected to it.<br />
<br />
== Energy Source ==<br />
<br />
[[File:Ns-3_energy_source.PNG|thumb|Energy source class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is an abstract base class that provides interfaces for for updating/recording total energy consumption on the node. It also issues a notification when the remaining energy goes to zero.<br />
<br />
Child classes of the energy source class implement a specific type of energy source, eg. a battery. Some typical child classes are:<br />
*Basic energy source.<br />
**Provides basic functionalities such as keeping track of remaining energy, decrease remaining energy, notify device energy models on complete depletion of energy.<br />
*Battery energy source (Not included in initial release).<br />
**Models the effect of energy consumption on the battery voltage, provides optional interfaces to provide recharging functionality, etc.<br />
<br />
== Device Energy Model ==<br />
<br />
[[File:Ns-3_device_energy_model.PNG|thumb|Device energy model class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
This is a base class and its main function is to monitor the state of a device, and accordingly calculate its energy consumption. It provides interfaces for updating remaining energy in the energy source and handles the notification from the energy source when node energy is depleted. It also maintains a record of the total energy consumption of the device.<br />
<br />
Child classes of the device energy consumption class implement energy consumption schemes of specific devices, eg. a radio device. Multiple device models can exist on a node, representing energy consumption due to its different components. Further, multiple objects of the same device model class can also be used in a node. eg. a node could have multiple radios, and hence will have multiple radio energy consumption models.<br />
<br />
A typical child implementation of this class is the radio energy model class.<br />
<br />
=== Wifi Radio Energy Model ===<br />
<br />
This class represents energy model for Wifi radio devices with operating states:<br />
*Idle<br />
*Tx<br />
*Rx<br />
*Sleep<br />
<br />
= Usage =<br />
<br />
The following code snippet installs an energy source (BasicEnergySource) and a radio energy model (BasicRadioEnergyModel) onto a node.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* energy source */<br />
BasicEnergySourceHelper basicSourceHelper;<br />
// configure energy source<br />
basicSourceHelper.Set ("BasicEnergySourceInitialEnergyJ", DoubleValue (0.1));<br />
<br />
/* device energy model */<br />
RadioEnergyHelper radioEnergyHelper;<br />
// configure radio energy model (optional, radio energy model is configured with parameters of CC2420).<br />
radioEnergyHelper.Set ("TxPowerW", DoubleValue (0.0435));<br />
radioEnergyHelper.Set ("RxPowerW", DoubleValue (0.047));<br />
radioEnergyHelper.Set ("IdlePowerW", DoubleValue (0.001065));<br />
radioEnergyHelper.Set ("SleepPowerW", DoubleValue (0.00005));<br />
<br />
/* energy model helper */<br />
EnergyModelHelper energyHelper;<br />
// install on all nodes<br />
energyHelper.Install (basicSourceHelper, radioEnergyHelper, c);<br />
<br />
The radio energy model keeps track of the current radio state (Tx, Rx, Idle, Sleep). It has to be notified (with the destination state) whenever the radio switches state. Modification to a PHY layer class is needed so that the radio energy model can record energy consumption correctly. The following code snippet shows how to modify existing PHY object to make use of the energy model (using YansWifiPhy class as an example):<br />
<br />
#include "ns3/radio-energy-model.h"<br />
#include "ns3/energy-source.h"<br />
<br />
/* obtain pointer to energy source */<br />
Ptr<EnergySource> energySource = m_nodePtr->GetObject<EnergySource> ();<br />
<br />
/* obtain list of RadioEnergyModel objects installed from the energy source */<br />
EnergySource::DeviceEnergyModelList modelList = energySource->FindDeviceEnergyModels ("ns3::RadioEnergyModel");<br />
<br />
/* obtain a pointer from the list */<br />
if (!modelList.empty ())<br />
{<br />
Ptr<RadioEnergyModel>m_energyPtr = DynamicCast<RadioEnergyModel> (modelList[0]);<br />
}<br />
<br />
/* update energy state for TX, insert at SendPacket */<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::TX);<br />
// wait/schedule till end of TX<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::IDLE);<br />
<br />
/* update energy state for RX, insert at StartReceivePacket and EndRx */<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::RX);<br />
// wait/schedule till end of RX<br />
m_energyPtr->UpdateRemainingEnergy (RadioEnergyModel::IDLE);<br />
<br />
A modified version of YansWifiPhy, called NslWifiPhy is available in the [http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model jamming model]. NslWifiPhy provides complete support for the radio energy model.<br />
<br />
= Expending the Energy Model =<br />
<br />
Initial release of the energy model only includes implementations of a basic energy source and a basic radio energy model. However, developers can use the interfaces provided to model a wide variety of energy sources and devices. <br />
<br />
== Energy Source ==<br />
<br />
=== Public APIs ===<br />
<br />
The energy source base class provides the following interfaces:<br />
<br />
* '''GetInitialEnergy:'''<br />
** Returns the initial energy (capacity) stored in the energy source.<br />
** The initial energy (capacity) of a energy source is specific to each implementation. Therefore we do not enforce a "SetInitialEnergy" interface in the base class.<br />
<br />
* '''GetRemainingEnergy:'''<br />
** Returns the remaining energy stored in the energy source.<br />
<br />
* '''GetEnergyFraction:'''<br />
** Returns the energy fraction [0,1] at the energy source. Energy fraction is defined as (remaining energy) / (initial energy).<br />
<br />
* '''DecreaseRemainingEnergy:'''<br />
** Decreases remaining energy. Typically called by device energy models (eg. a radio) for consuming energy.<br />
** Note that this interface does '''not''' enforce linear behavior. A non-linear function (battery models) can be implemented using the same interface.<br />
<br />
* '''IncreaseRemainingEnergy:'''<br />
** Increases remaining energy. Typically called for recharging energy (eg. a solar panel).<br />
** Note that this interface does '''not''' enforce linear behavior. Non-liner increase functions can be implemented using the same interface.<br />
<br />
* '''AppendDeviceEnergyModel:'''<br />
** Called when installing device energy models. Energy source object keeps track of every device energy models installed onto the node.<br />
<br />
* '''FindDeviceEnergyModels:'''<br />
** Returns a list of device energy models of specified type. Useful when one wants to query certain types of devices for it energy consumption.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''NotifyEnergyDrained''':<br />
** This function Notifies all DeviceEnergyModels installed on the node for the energy depletion event.<br />
** It should be called when energy is drained (remaining energy = 0) in the energy source.<br />
<br />
* '''BreakDeviceEnergyModelRefCycle''':<br />
** This function breaks the reference cycle between EnergySource and the list of DeviceEnergyModels.<br />
** It should be called in DoDispose by all derived class of EnergySource.<br />
<br />
=== Examples ===<br />
<br />
Please see the BasicEnergySource and BasicRadioEnergySource class implementation for how the interfaces are used.<br />
<br />
<br />
== Device Energy Model == <br />
<br />
=== Public APIs ===<br />
<br />
The device energy model base class provides the following interfaces:<br />
<br />
* '''HandleEnergyDepletion''':<br />
** Automatically called by the energy source object when energy is depleted. It's implementation is specific for each device.<br />
<br />
* '''SetEnergySource''':<br />
** Called when installing device energy models. A device energy model can not operate without an energy source.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''DecreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for decreasing (consuming) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
* '''IncreaseRemainingEnergy''':<br />
** Provides a handle to the energy source for increasing (charging) remaining energy.<br />
** Note that this interface is protected and is only accessible from within the device energy model.<br />
<br />
=== Examples ===<br />
<br />
Please see the RadioEnergySource and BasicRadioEnergySource class implementation for how the interfaces are used.</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4745Wireless jamming model2010-08-07T02:53:23Z<p>Uwnsl: /* Public APIs */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''StopJammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_wireless_module_utility_flow.PNG|thumb|Wireless Module Utility work flow.]]<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
// install jammer<br />
jammerHelper.Install (c.Get (4)); // installing on a specific node<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer object */<br />
Ptr<Jammer> jammerPtr = c.Get (4)->GetObject<Jammer> ();<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Sample-script.patch&diff=4527File:Sample-script.patch2010-06-19T21:55:26Z<p>Uwnsl: uploaded a new version of "File:Sample-script.patch"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_phy_layer_driver_flow.PNG&diff=4504File:Ns-3 phy layer driver flow.PNG2010-06-11T23:46:04Z<p>Uwnsl: uploaded a new version of "File:Ns-3 phy layer driver flow.PNG"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_wireless_module_utility_flow.PNG&diff=4503File:Ns-3 wireless module utility flow.PNG2010-06-11T23:43:02Z<p>Uwnsl: uploaded a new version of "File:Ns-3 wireless module utility flow.PNG"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_phy_layer_driver_flow.PNG&diff=4494File:Ns-3 phy layer driver flow.PNG2010-06-08T19:33:59Z<p>Uwnsl: uploaded a new version of "File:Ns-3 phy layer driver flow.PNG"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_mitigate_by_channel_hop_flow.PNG&diff=4493File:Ns-3 mitigate by channel hop flow.PNG2010-06-08T19:31:39Z<p>Uwnsl: uploaded a new version of "File:Ns-3 mitigate by channel hop flow.PNG"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_phy_layer_driver_flow.PNG&diff=4475File:Ns-3 phy layer driver flow.PNG2010-06-03T21:38:31Z<p>Uwnsl: uploaded a new version of "File:Ns-3 phy layer driver flow.PNG"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4474Wireless jamming model2010-06-03T20:53:49Z<p>Uwnsl: /* Overview */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''Stop Jammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_wireless_module_utility_flow.PNG|thumb|Wireless Module Utility work flow.]]<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
// install jammer<br />
jammerHelper.Install (c.Get (4)); // installing on a specific node<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer object */<br />
Ptr<Jammer> jammerPtr = c.Get (4)->GetObject<Jammer> ();<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_wireless_module_utility_flow.PNG&diff=4473File:Ns-3 wireless module utility flow.PNG2010-06-03T20:53:20Z<p>Uwnsl: </p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_jamming_model.PNG&diff=4470File:Ns-3 jamming model.PNG2010-06-03T01:05:18Z<p>Uwnsl: uploaded a new version of "File:Ns-3 jamming model.PNG"</p>
<hr />
<div>ns-3 Jamming model hierarchy</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4469Wireless jamming model2010-06-03T00:48:40Z<p>Uwnsl: /* Overview */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''Stop Jammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
// install jammer<br />
jammerHelper.Install (c.Get (4)); // installing on a specific node<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer object */<br />
Ptr<Jammer> jammerPtr = c.Get (4)->GetObject<Jammer> ();<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4468Wireless jamming model2010-06-03T00:48:20Z<p>Uwnsl: /* PHY Layer Driver Overview */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''Stop Jammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
[[File:Ns-3_phy_layer_driver_flow.PNG|thumb|PHY Layer (NslWifiPhy) driver work flow.]]<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
// install jammer<br />
jammerHelper.Install (c.Get (4)); // installing on a specific node<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer object */<br />
Ptr<Jammer> jammerPtr = c.Get (4)->GetObject<Jammer> ();<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_phy_layer_driver_flow.PNG&diff=4467File:Ns-3 phy layer driver flow.PNG2010-06-03T00:47:06Z<p>Uwnsl: </p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_reactive_jammer_flow.PNG&diff=4466File:Ns-3 reactive jammer flow.PNG2010-06-02T23:34:15Z<p>Uwnsl: uploaded a new version of "File:Ns-3 reactive jammer flow.PNG"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4465Wireless jamming model2010-06-02T23:31:10Z<p>Uwnsl: /* Jamming Mitigation Overview */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''Stop Jammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
[[File:Ns-3_mitigate_by_channel_hop_flow.PNG|thumb|Mitigate by channel hop work flow.]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
// install jammer<br />
jammerHelper.Install (c.Get (4)); // installing on a specific node<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer object */<br />
Ptr<Jammer> jammerPtr = c.Get (4)->GetObject<Jammer> ();<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_mitigate_by_channel_hop_flow.PNG&diff=4464File:Ns-3 mitigate by channel hop flow.PNG2010-06-02T23:29:54Z<p>Uwnsl: </p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=File:Ns-3_reactive_jammer_flow.PNG&diff=4463File:Ns-3 reactive jammer flow.PNG2010-06-02T23:08:58Z<p>Uwnsl: uploaded a new version of "File:Ns-3 reactive jammer flow.PNG"</p>
<hr />
<div></div>Uwnslhttps://www.nsnam.org/mediawiki/index.php?title=Wireless_jamming_model&diff=4462Wireless jamming model2010-06-02T23:03:07Z<p>Uwnsl: /* Overview */</p>
<hr />
<div>= General =<br />
<br />
[http://www.ee.washington.edu/research/nsl/faculty/radha/ Network Security Lab], University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.<br />
<br />
= Project Background =<br />
<br />
Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.<br />
<br />
= Project Goals =<br />
<br />
* To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy. <br />
* To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.<br />
<br />
This model focuses on modeling the '''intelligence layer''' (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.<br />
<br />
= Schedule =<br />
<br />
*5/1/2010 - : Public review. Code available at: http://codereview.appspot.com/1055041/show<br />
*4/19/2010 - 4/30/2010: Private review.<br />
<br />
= Jamming Model Hierarchy =<br />
<br />
[[File:Ns-3_jamming_model.PNG|thumb|Jamming model hierarchy]]<br />
<br />
The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:<br />
<br />
*'''Jamming intelligence (jammer)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Jamming detection/mitigation intelligence (mitigation)'''.<br />
**This base class provides interfaces to wireless module utility.<br />
**Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.<br />
**This class depends on the wireless module utility class.<br />
<br />
*'''Wireless module utility (utility)'''.<br />
**This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.<br />
**This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.<br />
<br />
*'''PHY layer driver (driver)'''.<br />
**Modification to PHY layer classes are required to provide interface to the utility.<br />
**The modifications are specific to the PHY layer class one wants to study.<br />
**Driver also notifies the [http://www.nsnam.org/wiki/index.php/NS-3_energy_model energy model], if installed.<br />
<br />
== Jamming Intelligence (Jammer) ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jammers.PNG|thumb|Jammer class structure]]<br />
<br />
The following types of jammers are provided by the jamming model:<br />
*'''Eavesdropper jammer''':<br />
**Listens and records wireless traffic in channel(s).<br />
*'''Constant jammer''':<br />
**Sends jamming signal of certain duration at a constant interval.<br />
*'''Random jammer''':<br />
**Sends jamming signal of certain duration at a randomly chosen interval.<br />
*'''Reactive jammer''':<br />
**Sends jamming signal of certain duration only when communication is present in the channel.<br />
<br />
Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.<br />
<br />
[[File:Ns-3_reactive_jammer_flow.PNG|thumb|Reactive jammer work flow]]<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartJammer''':<br />
** Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.<br />
<br />
* '''Stop Jammer''':<br />
** Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.<br />
<br />
* '''StartRxHandler''':<br />
** Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.<br />
** A jammer node can decide whether it wants to receive the incoming packet.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jammer intelligence.<br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.<br />
** Jammer class cannot operate without support of WirelessUtilityModule.<br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammerHelper during installation.<br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammerHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsJammerOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jammers.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Jamming Detection/Mitigation ==<br />
<br />
=== Overview ===<br />
<br />
[[File:Ns-3_jamming_mitigation.PNG|thumb|Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.]]<br />
<br />
The following jamming detection strategies are provided by the jamming model:<br />
*Detect jamming by RSS.<br />
*Detect jamming by PDR.<br />
*Detect jamming by RSS & PDR.<br />
<br />
The following jamming mitigation strategies are provided by the jamming model:<br />
*Mitigate by channel hop.<br />
**When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.<br />
<br />
Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartMitigation''':<br />
** Starts jamming detection/mitigation. <br />
** This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.<br />
<br />
* '''StopMitigation''':<br />
** Stops jamming detection/mitigation.<br />
** This function is scheduled to stop jamming detection/mitigation.<br />
<br />
* '''HandleIncomingPacket (EndRxhandler)''':<br />
** Callback function invoked at the end of Rx by WirelessModuleUtility.<br />
** This callback is used to pass the received packet to the jamming detection/mitigation intelligence. <br />
<br />
* '''EndTxHandler''':<br />
** Callback function invoked at the end of Tx by WirelessModuleUtility.<br />
<br />
* '''SetUtilityModule''':<br />
** Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.<br />
** Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule. <br />
<br />
* '''SetEnergySource''':<br />
** Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation. <br />
<br />
* '''SetNodeId''':<br />
** Records current node ID, called by JammingMitigationHelper during installation.<br />
<br />
=== Protected APIs ===<br />
<br />
* '''Pointer to WirelessModuleUtility''':<br />
** Used to expose various public APIs provided WirelessModuleUtility.<br />
<br />
* '''IsMitigationOn'''<br />
<br />
* '''GetEnergyFraction''':<br />
** Returns current node's energy fraction [0,1].<br />
** Used for energy aware jamming mitigation strategies.<br />
<br />
* '''GetNodeId''':<br />
** Returns current node ID, used mainly for debug traces.<br />
<br />
== Wireless Module Utility ==<br />
<br />
=== Overview ===<br />
<br />
This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.<br />
<br />
Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.<br />
<br />
=== Public APIs ===<br />
<br />
* '''StartRxHandler''':<br />
** Handles start of Rx. Returns true if the current packet is to be received.<br />
** Called by PHY layer driver at the beginning of Rx.<br />
** This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.<br />
** This function also updates network information such as RSS.<br />
<br />
* '''EndRxHandler''':<br />
** Handles end of Rx.<br />
** Called by PHY layer driver at the end of Rx.<br />
** This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.<br />
** This function also updates network information such as RSS, PDR and throughput.<br />
<br />
* '''StartTxHandler''':<br />
** Handles start of Tx.<br />
** Called by PHY layer driver at the beginning of Tx.<br />
** This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.<br />
** This function also updates network information such as throughput.<br />
<br />
* '''EndTxHandler''':<br />
** Handles end of Tx.<br />
** Called by PHY layer driver at the end of Tx.<br />
** This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.<br />
<br />
* '''GetTotalBytesRx''':<br />
** Returns total number of bytes received.<br />
<br />
* '''GetTotalBytesTx''':<br />
** Returns total number of bytes sent.<br />
<br />
* '''GetRxThroughput''':<br />
** Returns Rx throughput.<br />
<br />
* '''GetTxThroughput''':<br />
** Returns Tx throughput.<br />
<br />
* '''GetPdr''':<br />
** Returns Packet Delivery Ratio (PDR).<br />
** PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.<br />
** PDR is calculated '''at the receiver side''' as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.<br />
** A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.<br />
** The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.<br />
<br />
* '''GetRss''':<br />
** Returns Received Signal Strength (RSS) at current node.<br />
** PHY layer driver support is required for RSS recording.<br />
** RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).<br />
** The RSS update interval is defined as an attribute of Wireless Module Utility.<br />
<br />
* '''SendJammingSignal''':<br />
** Sends jamming signal of certain power and duration (by invoking PHY layer callback).<br />
** Called by jammer classes to transmit jamming signal.<br />
<br />
* '''SwitchChannel''':<br />
** Switch current wireless channel to specified channel (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects as a mitigation strategy.<br />
<br />
* '''SendMitigationMessage''':<br />
** Send special jamming mitigation message (by invoking PHY layer callback).<br />
** Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.<br />
<br />
== PHY Layer Driver ==<br />
<br />
=== Overview ===<br />
<br />
Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.<br />
<br />
=== Driver Functions ===<br />
<br />
PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:<br />
<br />
* '''InitDriver''':<br />
** Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.<br />
<br />
* '''DriverStartTx''':<br />
** This function calls StartTxHandler in WirelessModuleUtility.<br />
** It is usually inserted into SendPacket function of the PHY class.<br />
<br />
* '''DriverEndTx''':<br />
** This function calls EndTxHandler in WirelessModuleUtility.<br />
** It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is '''scheduled''' to be invoked at the end of Tx.<br />
<br />
* '''DriverStartRx''':<br />
** This function calls StartRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into StartReceivePacket function of the PHY class.<br />
<br />
* '''DriverEndRx''':<br />
** This function calls EndRxHandler in WirelessModuleUtility.<br />
** It is usually inserted into EndRx function of the PHY class.<br />
<br />
* '''UtilitySendPacket''':<br />
** This is a wrapper function for SendPacket of the PHY class.<br />
** It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.<br />
<br />
* '''UpdatePhyLayerInfo''':<br />
** This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.<br />
<br />
* '''MeasureRss''':<br />
** Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.<br />
<br />
= Usage =<br />
<br />
A complete sample simulation script using all components for the Wireless Jamming Model is available here: [[File:Sample-script.patch]]<br />
<br />
== Jammer ==<br />
<br />
The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jammer */<br />
JammerHelper jammerHelper;<br />
// configure jammer type<br />
jammerHelper.SetJammerType ("ns3::ReactiveJammer");<br />
// set jammer parameters<br />
jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));<br />
// install jammer<br />
jammerHelper.Install (c.Get (4)); // installing on a specific node<br />
<br />
Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.<br />
<br />
Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.<br />
<br />
/* obtain pointer to jammer object */<br />
Ptr<Jammer> jammerPtr = c.Get (4)->GetObject<Jammer> ();<br />
/* schedule jammer to start at 7.0 seconds */<br />
Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);<br />
<br />
== Jamming Mitigation ==<br />
<br />
The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install jamming mitigation objects */<br />
JammingMitigationHelper mitigationHelper;<br />
// configure mitigation type<br />
mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");<br />
// configure mitigation parameters<br />
mitigationHelper.Set ("MitigateByChannelHopDetectionThreshold", DoubleValue (0.5));<br />
// install mitigation on nodes<br />
mitigationHelper.Install (c);<br />
<br />
== Wireless Module Utility ==<br />
<br />
The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.<br />
<br />
/* create some nodes */ <br />
NodeContainer c;<br />
c.Create(5);<br />
<br />
/* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */<br />
<br />
/* install wireless module utility objects */<br />
WirelessModuleUtilityHelper utilityHelper;<br />
// set attributes<br />
utilityHelper.Set ("ThroughputUpdateInterval", TimeValue (Seconds (1.0)));<br />
// install on all nodes<br />
utilityHelper.Install (c);</div>Uwnsl