From 6c87dff0ea54188b5c67400acac8f31ca44e8d29 Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Tue, 25 Jun 2019 16:15:31 -0700
Subject: [PATCH] wifi:  Clarify behavioral change due to preamble detection
 model

---
 CHANGES.html                            | 3 ++-
 src/wifi/doc/source/wifi-design.rst     | 8 ++++++++
 src/wifi/doc/source/wifi-references.rst | 1 +
 3 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/CHANGES.html b/CHANGES.html
index e83b1a5e4..2823f87c5 100644
--- a/CHANGES.html
+++ b/CHANGES.html
@@ -106,7 +106,8 @@ us a note on ns-developers mailing list.</p>
 <h2>Changed behavior:</h2>
 <ul>
   <li>The wifi ADDBA handshake process is now protected with the use of two timeouts who makes sure we do not end up in a blocked situation. If the handshake process is not established, packets that are in the queue are sent as normal MPDUs. Once handshake is successfully established, A-MPDUs can be transmitted.</li>
-  <li> The default value of the <b>Margin</b> attribute in SimpleFrameCaptureModel was changed from 10 to 5.</li>
+  <li> In the wifi module, the default value of the <b>Margin</b> attribute in SimpleFrameCaptureModel was changed from 10 to 5.</li>
+  <li> A ThresholdPreambleDetectionModel is added by default to the WifiPhy.  Using default values, this model will discard frames that fall below either -82 dBm RSSI or below 4 dB SNR.  Users may notice that weak wifi signals that were successfully received based on the error model alone (in previous ns-3 releases) are no longer received.  Previous behavior can be obtained by lowering both threshold values or by removing the preamble detection model (via WifiPhyHelper::DisablePreambleDetectionModel()).</li>
   <li>LTE/EPC model has been enhanced with the new features. These new features allow the simulation user to test more realistic simulations related to the core network. These features are:</li>
     <ul>
       <li>SGW, PGW and MME are full nodes.</li>
diff --git a/src/wifi/doc/source/wifi-design.rst b/src/wifi/doc/source/wifi-design.rst
index 576ac42f8..014723752 100644
--- a/src/wifi/doc/source/wifi-design.rst
+++ b/src/wifi/doc/source/wifi-design.rst
@@ -322,6 +322,14 @@ and the PHY is put into the RX state.  Currently, there is only a
 simple threshold-based preamble detection model in ns-3,
 called ``ThresholdPreambleDetectionModel``.  If there is no preamble detection
 model, the preamble is assumed to have been detected.  
+It is important to note that, starting with the ns-3.30 release, the default
+in the WifiPhyHelper is to add the ``ThresholdPreambleDetectionModel`` with
+a threshold RSSI of -82 dBm, and a threshold SNR of 4 dB.  Both the RSSI
+and SNR must be above these respective values for the preamble to be
+successfully detected.  The default sensitivity has been reduced in ns-3.30
+compared with that of previous releases, so some packet receptions that were 
+previously successful will now fail on this check.  More details on the
+modeling behind this change are provided in [lanante2019]_.
 
 In a real system, the ``EndReceive ()`` time would
 not be determined until later when the PHY headers are successfully decoded,
diff --git a/src/wifi/doc/source/wifi-references.rst b/src/wifi/doc/source/wifi-references.rst
index c7b850808..d26357906 100644
--- a/src/wifi/doc/source/wifi-references.rst
+++ b/src/wifi/doc/source/wifi-references.rst
@@ -45,3 +45,4 @@ References
 
 .. [baldo2010] \ N. Baldo et al., "Validation of the ns-3 IEEE 802.11 model using the EXTREME testbed", Proceedings of SIMUTools Conference, March 2010.
 
+.. [lanante2019] \ L. Lanante Jr. et al., "Improved Abstraction for Clear Channel Assessment in ns-3 802.11 WLAN Model", Proceedings of the 2019 Workshop on ns-3, June 2019.