ns-3: Wireless Interference (Jamming) Framework

Network Security Lab, University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to to enable researchers to use ns3 to study jamming and its mitigation methods.

Project description is available at: http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model

The ns-3 Wireless Interference (Jamming) Framework utilizes the ns-3 Energy Framework (officially included in ns-3.9 and onwards).

There are 4 major components for this model:
1. Jammer: Adversary devices sending jamming signal (interference) in the hope to disrupt target wireless network. Different jammer classes represent different jamming strategies (random, constant, eavesdropper, reactive)
2. Jamming Mitigation: Strategies for honest (regular) network nodes to mitigate jamming.
3. Wireless Module Utility: Utility class for interfacing Jammer and Jamming Mitigation classes to PHY layer. This class abstracts the PHY layer so that the same Jammer or Jamming Mitigation class can operate on different wireless PHY without any modification.
4. PHY layer driver (NslWifiPhy): A modification from YansWifiPhy. To show how to integrate the above classes with a wireless PHY implementation.

The jamming model is in active development, comments and suggestions are appreciated.

This patch is based on the latest ns-3-dev tree. To use the jamming framework, apply only the latest patch to ns-3-dev.

[Mathieu Lacage, 2010-05-25 07:54:46]

hi,

I looked briefly over the codebase. There are a couple of small comments below
which probably reflect the lack of time I spent looking at the code. If you
really want to get (better) reviews, I think that you need to spend some time to
describe more fully how all the modules you are adding fit together with some
diagrams or some explanatory text.

My other major comment is about the YansWifiPhy class changes. There have been
others before you who tried to add new phy layers to the wifi module. The
expected way to do this is to subclass WifiPhy, not YansWifiPhy. Others have
rightfully commented that doing this is a lot of work and requires duplicating 
a lot of the YansWifiPhy functionality. I think that no one will disagree with
this but the proper way to add a new phy model without duplicating all the
YansWifiPhy code is not to make all its methods virtual. Instead, I think that
you need to think carefully about which functionality is truly common/shared and
find a way to move that to some shared code (maybe in the WifiPhy base class)
and, then, you can have your own phy model which does not modify the existing
phy models. 

Of course, all this work should be synchronized with the work others are doing
on the phy model, that is, nicola's own spectrum phy and timo's own phy work:
http://code.nsnam.org/timob/ns-3-wifiex/

http://codereview.appspot.com/1055041/diff/48002/56007
File src/common/propagation-loss-model.cc (right):

http://codereview.appspot.com/1055041/diff/48002/56007#newcode87
src/common/propagation-loss-model.cc:87: // TODO figure out what happens when
m_next exists.
yes, you really need to figure this out

http://codereview.appspot.com/1055041/diff/48002/56008
File src/common/propagation-loss-model.h (right):

http://codereview.appspot.com/1055041/diff/48002/56008#newcode69
src/common/propagation-loss-model.h:69: * \param RxGainDbm RX gain at receiver,
in dBm
probably should merge txpowerdbm with txgaindbm and rxpowerdbm with rxgaindbm.

http://codereview.appspot.com/1055041/diff/48002/56008#newcode73
src/common/propagation-loss-model.h:73: * This function is the inverse of
CalcRxPower. Note that not all propagation
I am not sure about what this can be used for and how it could apply to various
propagation models but maybe what you really need is a lower or upper bound on
the distance between the tx and rx sides so, CalcDistance could be renamed
CalcMaxDistance (...) or CalcMinDistance (...)

[(Tony) He Wu, 2010-05-25 22:57:13]

Hi Mathieu,

Thank you very much for your comments. We are working on including more
information on the project wiki page:
http://www.nsnam.org/wiki/index.php/NS-3_wireless_jamming_model to help with the
review process.

For our PHY class, it shares most functions with the original YansWifiPhy. Only
the send and receive functions are modified. We agree that inheriting from
YansWifiPhy is not the best approach. Originally we are trying to avoid creating
a new channel model, which will be identical to YansWifiChannel. Seeing this is
done for Ns2ExtWifiPhy and Ns2ExtWifiChannel in ns-3-wifiex, we think the same
can be done with our PHY class. We will include a new channel class with our PHY
class in the next patch and leave YansWifiPhy unmodified.

http://codereview.appspot.com/1055041/diff/48002/56007
File src/common/propagation-loss-model.cc (right):

http://codereview.appspot.com/1055041/diff/48002/56007#newcode87
src/common/propagation-loss-model.cc:87: // TODO figure out what happens when
m_next exists.
On 2010/05/25 07:54:47, Mathieu Lacage wrote:
> yes, you really need to figure this out

CalcDistance function can only compute distance for a single non-probabilistic
propagation model. When m_next is present, meaning more then 1 models are
chained together, CalcDistance function will not be applicable.

I will remove the TODO comment.

http://codereview.appspot.com/1055041/diff/48002/56008
File src/common/propagation-loss-model.h (right):

http://codereview.appspot.com/1055041/diff/48002/56008#newcode69
src/common/propagation-loss-model.h:69: * \param RxGainDbm RX gain at receiver,
in dBm
On 2010/05/25 07:54:47, Mathieu Lacage wrote:
> probably should merge txpowerdbm with txgaindbm and rxpowerdbm with rxgaindbm.

Will include in next patch.

http://codereview.appspot.com/1055041/diff/48002/56008#newcode73
src/common/propagation-loss-model.h:73: * This function is the inverse of
CalcRxPower. Note that not all propagation
On 2010/05/25 07:54:47, Mathieu Lacage wrote:
> I am not sure about what this can be used for and how it could apply to
various
> propagation models but maybe what you really need is a lower or upper bound on
> the distance between the tx and rx sides so, CalcDistance could be renamed
> CalcMaxDistance (...) or CalcMinDistance (...)

The motivation behind the CalcDistance function is to provide simple distance
estimation capability, which is essential in localization applications. This
function is the inverse of CalcRxPower. However we can only provide CalcDistance
function for non-probabilistic propagation loss models (Friis, LogDistance,
ThreeLogDistance). Since direct conversions from RX power to distance for
probabilistic propagation loss models are not possible (no 1-to-1 mapping from
RX power to distance exists).

[Mathieu Lacage, 2010-05-26 07:04:35]

On Wed, May 26, 2010 at 12:57 AM,  <mdzzzz@gmail.com> wrote:

> The motivation behind the CalcDistance function is to provide simple
> distance estimation capability, which is essential in localization
> applications. This function is the inverse of CalcRxPower. However we
> can only provide CalcDistance function for non-probabilistic propagation
> loss models (Friis, LogDistance, ThreeLogDistance). Since direct
> conversions from RX power to distance for probabilistic propagation loss
> models are not possible (no 1-to-1 mapping from RX power to distance
> exists).

The question though is: "how do you use it ? " Where from ? Do you
have example code using it ?

Mathieu
-- 
Mathieu Lacage <mathieu.lacage@gmail.com>

[(Tony) He Wu, 2010-05-26 21:03:39]

On 2010/05/26 07:04:35, Mathieu Lacage wrote:
> The question though is: "how do you use it ? " Where from ? Do you
> have example code using it ?
>
> Mathieu
> --
> Mathieu Lacage <mailto:mathieu.lacage@gmail.com>
>

Hi Mathieu,

I have removed the CalcRxPower function (all changes to existing
PropagationLossModel classes) from the patch.

This function is used by WirelessModuleUtility::RssiToDistance. Which we
envisioned for future implementation of certain jamming detection methods. But
currently we only have unit test code and those code doesn't reflect the
function's intended usage.

Thanks,
Tony

[Nicola Baldo, 2010-06-22 01:15:16]

I reviewed the code mainly from the point of view of the impact of the
modifications on the existing wifi codebase. Please find the relative comments
below. As for NslWifiPhy, it is better now that it inherits directly from
WifiPhy, but now there is a huge amount of code duplication. I agree with the
comments previously made by Mathieu, i.e., that to properly address this issue
you should identify which functionality is shared between NslWifiPhy and
YansWifiPhy, and move the corresponding code up in the class hierarchy.

http://codereview.appspot.com/1055041/diff/115001/116029
File src/devices/wifi/interference-helper.cc (right):

http://codereview.appspot.com/1055041/diff/115001/116029#newcode585
src/devices/wifi/interference-helper.cc:585:
InterferenceHelper::CalculateNoiseFloor (WifiMode mode) const
I guess this code comes from InterferenceHelper::CalculateSnr(), right? If so,
you should call CalculateNoiseFloor () from CalculateSnr(), and remove the
duplicate code.

http://codereview.appspot.com/1055041/diff/115001/116030
File src/devices/wifi/interference-helper.h (right):

http://codereview.appspot.com/1055041/diff/115001/116030#newcode70
src/devices/wifi/interference-helper.h:70: double packetRss;
You should explain why you need to calculate packetRss, i.e., what is the use
case that you see for it.

http://codereview.appspot.com/1055041/diff/115001/116030#newcode112
src/devices/wifi/interference-helper.h:112: double CurrentNodeRss (WifiMode
mode);
What do you use this for? Energy Detection?

http://codereview.appspot.com/1055041/diff/115001/116033
File src/devices/wifi/nsl-wifi-phy.cc (right):

http://codereview.appspot.com/1055041/diff/115001/116033#newcode3
src/devices/wifi/nsl-wifi-phy.cc:3: * Copyright (c) 2010 Network Security Lab,
University of Washington, Seattle.
Most of this file is copied from yans-wifi-phy.cc. The GPL allows you to copy
code, of course, but I don't think it allows you to change the copyright owner.
I guess you can add your own copyright line, but you should not delete the
existing one. The same applies for other files as well.

http://codereview.appspot.com/1055041/diff/115001/116033#newcode18
src/devices/wifi/nsl-wifi-phy.cc:18: * Authors: Sidharth Nabar <snabar@uw.edu>,
He Wu <mdzz@u.washington.edu>
Similarly, you should add yourself to the authors, but you should not delete
pre-existing author names.

http://codereview.appspot.com/1055041/diff/115001/116035
File src/devices/wifi/wifi-preamble.h (right):

http://codereview.appspot.com/1055041/diff/115001/116035#newcode29
src/devices/wifi/wifi-preamble.h:29: WIFI_PREAMBLE_INVALID	// PHY layer preamble
for jammer "packets"
I understand that this is an easy way to distinguish between wifi and non-wifi
packets, however I think you should find another way to do it, e.g., adding a
new parameter to NslWifiChannel::Send()

[(Tony) He Wu, 2010-07-03 00:12:02]

We designed NslWifiPhy as an extension of YansWifiPhy, hoping to reuse as much
of YansWifiPhy (and YansWifiChannel) as possible. We intend to show it is easy
to modify an existing PHY class to enable usage of jamming and energy models.

In NslWifiPhy, the modification from YansWifiPhy are in StartReceivePacket,
EndReceive and SendPacket. These modifications are to add taps (function calls)
to "driver" functions. The "driver" functions are functions we introduced in
NslWifiPhy to support jamming and energy model.

The functions we see can be moved up in the hierarchy will only be conversion
functions like DbmToW, WToDbm, DbToRatio. The other functions of YansWifiPhy
either manipulate the class's private members or are private. We don't think
they can be moved.

We agree that duplicating most of YansWifiPhy is not a good approach. But we are
not sure how we can reuse most of YansWifiPhy's code without duplication or
inherit from YansWifiPhy.

http://codereview.appspot.com/1055041/diff/115001/116029
File src/devices/wifi/interference-helper.cc (right):

http://codereview.appspot.com/1055041/diff/115001/116029#newcode585
src/devices/wifi/interference-helper.cc:585:
InterferenceHelper::CalculateNoiseFloor (WifiMode mode) const
On 2010/06/22 01:15:16, Nicola Baldo wrote:
> I guess this code comes from InterferenceHelper::CalculateSnr(), right? If so,
> you should call CalculateNoiseFloor () from CalculateSnr(), and remove the
> duplicate code.

Done.

http://codereview.appspot.com/1055041/diff/115001/116030
File src/devices/wifi/interference-helper.h (right):

http://codereview.appspot.com/1055041/diff/115001/116030#newcode70
src/devices/wifi/interference-helper.h:70: double packetRss;
On 2010/06/22 01:15:16, Nicola Baldo wrote:
> You should explain why you need to calculate packetRss, i.e., what is the use
> case that you see for it.

Packet (average) RSS is an important value for jamming detection. In the case of
a reactive jammer. RSS of a packet may not be affected initially, but the
average RSS of the entire packet will increase because of the jammer's
interference to the rest of the packet.

We believe there are existing ways for reporting packet (average) RSS. But they
are only for successfully received packets. In our case packet (average) RSS is
needed for dropped packets as well (to detect jamming). Therefore packetRss is
needed here.

http://codereview.appspot.com/1055041/diff/115001/116030#newcode112
src/devices/wifi/interference-helper.h:112: double CurrentNodeRss (WifiMode
mode);
On 2010/06/22 01:15:16, Nicola Baldo wrote:
> What do you use this for? Energy Detection?

Yes this function can be used for energy detection. Our original intention is to
use this function for tracking (tracing) current node's RSS during the
simulation. It helps to plot the RSS over time, which will show the presence of
a jammer. 

It can also be used for jamming detection. A node can start suspecting itself
being jammed when RSS around the node is above certain threshold.

Perhaps is should be renamed as CurrentNodeRadioEnergyLevel?

http://codereview.appspot.com/1055041/diff/115001/116033
File src/devices/wifi/nsl-wifi-phy.cc (right):

http://codereview.appspot.com/1055041/diff/115001/116033#newcode3
src/devices/wifi/nsl-wifi-phy.cc:3: * Copyright (c) 2010 Network Security Lab,
University of Washington, Seattle.
On 2010/06/22 01:15:16, Nicola Baldo wrote:
> Most of this file is copied from yans-wifi-phy.cc. The GPL allows you to copy
> code, of course, but I don't think it allows you to change the copyright
owner.
> I guess you can add your own copyright line, but you should not delete the
> existing one. The same applies for other files as well.

Done.

http://codereview.appspot.com/1055041/diff/115001/116033#newcode18
src/devices/wifi/nsl-wifi-phy.cc:18: * Authors: Sidharth Nabar <snabar@uw.edu>,
He Wu <mdzz@u.washington.edu>
On 2010/06/22 01:15:16, Nicola Baldo wrote:
> Similarly, you should add yourself to the authors, but you should not delete
> pre-existing author names.

Done.

http://codereview.appspot.com/1055041/diff/115001/116035
File src/devices/wifi/wifi-preamble.h (right):

http://codereview.appspot.com/1055041/diff/115001/116035#newcode29
src/devices/wifi/wifi-preamble.h:29: WIFI_PREAMBLE_INVALID	// PHY layer preamble
for jammer "packets"
On 2010/06/22 01:15:16, Nicola Baldo wrote:
> I understand that this is an easy way to distinguish between wifi and non-wifi
> packets, however I think you should find another way to do it, e.g., adding a
> new parameter to NslWifiChannel::Send()
> 

Thanks a lot for the suggestion. This invalid preamble was added before
introducing NslWifiChannel. We think this issue depends on how we decide to
handle code duplication between YansWifiPhy and NslWifiPhy.

We can make the change of adding a new parameter to NslWifiChannel::Send() now.
But we may have to put the invalid preamble back if our discussion leads to
reusing YansWifiChannel eventually.

[Nicola Baldo, 2010-12-17 00:23:08]

To summarize: I think the preamble change could be acceptable, but the whole
packetRss stuff to me seems too much of a custom hack to be allowed in ns-3-dev.
This because basically it repeats the total power calculation twice, just to
support your jamming detection scheme.

http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
File src/devices/wifi/interference-helper.cc (right):

http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
src/devices/wifi/interference-helper.cc:549:
InterferenceHelper::CalculatePacketRss (Ptr<const InterferenceHelper::Event>
event,
I get the impression that this calculation as a similar computational load to
that of calculating the SNR for all chunks when CalculateSnrPer () is called. So
you are roughly doubling the computational load of the interference model, am I
right?

If so, I think you need to find a more efficient way of doing it. I get the
impression that this is related to bug 1028.

http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
File src/devices/wifi/interference-helper.h (right):

http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
src/devices/wifi/interference-helper.h:71: double packetRss;
I think that "packetRss" is a misnomer, since the RSS is normally calculated
only on the first part of the packet. At least for some old 802.11b chipset I am
familiar with, I think RSSI is the value of the Energy Detector sampled when the
AGC locks. So this variable here should be called "averagePacketRss".
 
By the way, I don't think any commercial device provides this average packet
RSS. What I think devices implement is that if they detect a significant
variation in the received energy, then the AGC unlocks and reception is aborted
(because it is almost sure to fail).

http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/wifi-pream...
File src/devices/wifi/wifi-preamble.h (right):

http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/wifi-pream...
src/devices/wifi/wifi-preamble.h:29: WIFI_PREAMBLE_INVALID	// PHY layer preamble
for jammer "packets"

I know that I suggested not to use it in a previous review, but after bug 1016
it is evident that the preamble serves in general the purpose of identifying
different types of wireless technologies. So I am ok for using it to identifying
generic interferers as well.

As for the naming, rather than "INVALID" I I would consider to call this
"NON_WIFI_PREAMBLE", or maybe "GENERIC_INTERFERER" to highlight the fact that
this is the way it will be processed by YansWifiPhy.
In any case we'll probably have to revise the naming of all preambles to address
bug 1016.

[snabar_u.washington.edu, 2010-12-17 18:22:51]

Hi Nicola,

Thank you very much for your email. I will discuss with Tony about each of
these issues and we will post an updated patch.

I also had another question for you: for the jammer's PHY class, we need
several aspects from yans-wifi-phy and we need it to talk on
Yans-Wifi-Channel (so that its packets can be heard at the other nodes).
However, there are also some differences w.r.t Yans. In this situation, we
have the following options:

1. Create JammerWifiPhy as a child of YansWifiPhy.
2. Modify YansWifiPhy to serve as a jammer as well as honest nodes.
3. Create JammerWifiPhy as a child of WifiPhy and modify YansWifiChannel to
take both, YansWifiPhy and JamemrWifiPhy objects.

Please let us know which one you would recommend. I would be happy to
discuss this with you in further detail if you like.

Thanks,
Sidharth


On Thu, Dec 16, 2010 at 4:23 PM, <nicobaldo@gmail.com> wrote:

> To summarize: I think the preamble change could be acceptable, but the
> whole packetRss stuff to me seems too much of a custom hack to be
> allowed in ns-3-dev. This because basically it repeats the total power
> calculation twice, just to support your jamming detection scheme.
>
>
>
>
>
>
>
http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
> File src/devices/wifi/interference-helper.cc (right):
>
>
>
http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
> src/devices/wifi/interference-helper.cc:549:
> InterferenceHelper::CalculatePacketRss (Ptr<const
> InterferenceHelper::Event> event,
> I get the impression that this calculation as a similar computational
> load to that of calculating the SNR for all chunks when CalculateSnrPer
> () is called. So you are roughly doubling the computational load of the
> interference model, am I right?
>
> If so, I think you need to find a more efficient way of doing it. I get
> the impression that this is related to bug 1028.
>
>
>
http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
> File src/devices/wifi/interference-helper.h (right):
>
>
>
http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/interferen...
> src/devices/wifi/interference-helper.h:71: double packetRss;
> I think that "packetRss" is a misnomer, since the RSS is normally
> calculated only on the first part of the packet. At least for some old
> 802.11b chipset I am familiar with, I think RSSI is the value of the
> Energy Detector sampled when the AGC locks. So this variable here should
> be called "averagePacketRss".
>
> By the way, I don't think any commercial device provides this average
> packet RSS. What I think devices implement is that if they detect a
> significant variation in the received energy, then the AGC unlocks and
> reception is aborted (because it is almost sure to fail).
>
>
>
http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/wifi-pream...
> File src/devices/wifi/wifi-preamble.h (right):
>
>
>
http://codereview.appspot.com/1055041/diff/243001/src/devices/wifi/wifi-pream...
> src/devices/wifi/wifi-preamble.h:29: WIFI_PREAMBLE_INVALID      // PHY
> layer
> preamble for jammer "packets"
>
> I know that I suggested not to use it in a previous review, but after
> bug 1016 it is evident that the preamble serves in general the purpose
> of identifying different types of wireless technologies. So I am ok for
> using it to identifying generic interferers as well.
>
> As for the naming, rather than "INVALID" I I would consider to call this
> "NON_WIFI_PREAMBLE", or maybe "GENERIC_INTERFERER" to highlight the fact
> that this is the way it will be processed by YansWifiPhy.
> In any case we'll probably have to revise the naming of all preambles to
> address bug 1016.
>
> http://codereview.appspot.com/1055041/
>

[Longwei.Su, 2011-10-27 13:26:08]

Hi,
I am trying this jamming module on ns-3.11. After apply all the patches, and
./waf with example and test enable, the console show that jamming model is
built. However, when I check all the available executable simulation, I could
not find example or simulation from jamming model.

Is there any step that I miss?
Any comment will be appreciate.

Thanks
Longwei

[rkeeler78, 2012-06-28 19:18:43]

I noticed in the latest patch, there are a few bugs that don't allow the
examples to compile in the released ns-3.11. 

Specifically:
(1) in jamming-mitigation-example.cc, need to comment the lines including
"ns3/helper-module.h" and "ns3/contrib-module.h". Both no longer exist in 3.11

(2) In jamming/examples/wscript, remove all references to the "simulator"
module. There is no longer a simulator module. As a result, the examples never
build!

[tuan.ant117, 2012-07-17 15:07:47]

with le laatest patch, when I run ./waf:
[1132/1667] cxx: src/jamming/model/nsl-wifi-phy.cc ->
build/src/jamming/model/nsl-wifi-phy.cc.1.o
../src/jamming/model/nsl-wifi-phy.cc: In member function ‘virtual void
ns3::NslWifiPhy::SendPacket(ns3::Ptr<const ns3::Packet>, ns3::WifiMode,
ns3::WifiPreamble, uint8_t)’:
../src/jamming/model/nsl-wifi-phy.cc:559: error: ‘NotifyPromiscSniffTx’ was not
declared in this scope
../src/jamming/model/nsl-wifi-phy.cc: In member function ‘void
ns3::NslWifiPhy::EndReceive(ns3::Ptr<ns3::Packet>,
ns3::Ptr<ns3::InterferenceHelper::Event>)’:
../src/jamming/model/nsl-wifi-phy.cc:827: error: ‘NotifyPromiscSniffRx’ was not
declared in this scope

what can i do for declare the parameter NotifyPromiscSniffTx and
NotifyPromiscSniffRx?

thanks!

[Cla.mar92, 2021-06-23 10:25:00]

Hi xysamrin0, the Patch set 19 is too large to download, could you provide a
link to download the full module?
Thanks,
Claudio