lr-wpan: Reposition scope and limitations doc section and update doc

src/lr-wpan/doc/lr-wpan.rst

@@ -2,15 +2,18 @@
 .. highlight:: cpp
 .. highlight:: bash
 
-PageBreak
-
-Low-Rate Wireless Personal Area Network (LR-WPAN)
-=================================================
+IEEE 802.15.4: Low-Rate Wireless Personal Area Network (LR-WPAN)
+================================================================
 
 This chapter describes the implementation of |ns3| models for the
 low-rate, wireless personal area network (LR-WPAN) as specified by
-IEEE standard 802.15.4 (2003,2006,2011). Both beacon and non-beacon modes are
-supported. Bootstrap (scan and association) is also supported.
+IEEE standard 802.15.4 (2003,2006,2011). The current emphasis is on direct transmissions running on both,
+slotted and unslotted mode (CSMA/CA) of IEEE 802.15.4 operation for use in Zigbee and 6loWPAN networks.
+
+Both beacon and non-beacon modes are supported as well as the bootstrap mechanism (scan and association).
+
+In general, this document describes what is modeled and how it is modeled; the following section [Scope and
+Limitations]() provides more details about what is not covered or what is missing in the model.
 
 The model is implemented into the ``src/lrwpan/`` folder.
 
@@ -109,9 +112,28 @@ For more information on primitives, See IEEE 802.15.4-2011, Table 8.
 
 Although it is expected that other technology profiles (such as
 6LoWPAN and ZigBee) will write their own NetDevice classes, a basic
-LrWpanNetDevice is provided, which encapsulates the common operations
+``LrWpanNetDevice`` is provided, which encapsulates the common operations
 of creating a generic LrWpan device and hooking things together.
 
+
+Scope and Limitations
+---------------------
+
+- Indirect data transmissions are not supported but planned for a future update.
+- Devices are capable of associating with a single PAN coordinator.
+- Interference is modeled as AWGN but this is currently not thoroughly tested.
+- The standard describes the support of multiple PHY band-modulations but currently, only 250kbps O-QPSK (channel page 0) is supported.
+- Active and passive MAC scans are able to obtain a LQI value from a beacon frame, however, the scan primitives assumes LQI is correctly implemented and does not check the validity of its value.
+- Configuration of the ED thresholds are currently not supported.
+- Coordinator realignment command is only supported in orphan scans.
+- Disassociation primitives are not supported.
+- Security is not supported.
+- Guaranteed Time Slots (GTS) are not supported.
+- Not all attributes are supported by the MLME-SET and MLME-GET primitives.
+- Indirect transmissions are only supported during the association process.
+- RSSI is not supported as this is part of the 2015 revision and the current implementation only supports until the 2011 revision.
+- PHY and MAC are currently not supported by the attribute system. To change the behavior of the PHY and MAC the standard SET primitives (e.g. MLME-SET.request) must be used.
+
 The PHY layer
 -------------
 
@@ -226,7 +248,7 @@ Bootstrap (a.k.a. network initialization) is possible with a combination of scan
 Bootstrap as whole depends on procedures that also take place on higher layers of devices and coordinators. These procedures are briefly described in the standard but out of its scope (See IEE 802.15.4-2011 Section 5.1.3.1.). However, these procedures are necessary for a "complete bootstrap" process. In the examples in |ns3|, these high layer procedures are only briefly implemented to demonstrate a complete example that shows the use of scan and association. A full high layer (e.g. such as those found in Zigbee and Thread protocol stacks) should complete these procedures more robustly.
 Examples such as  ``lr-wpan-bootstrap.cc`` demonstrate the whole bootstrap process (including scanning and association) while doing some place holder of procedures that take place in higher layers which are not part of standard focus.
 
-A key element to remember is that bootstrap have 2 key objectives:
+A key element to remember is that bootstrap have 2 objectives:
 
 1- Enable devices to join a new formed network (associate).
 2- Assign short addresses and PAN ID.
@@ -236,7 +258,7 @@ Devices that have the short address ``FF:FE`` and have a valid PAN ID can commun
 extended address mode. In this mode, devices will use its 64 bit address (A.K.A. extended address) to communicate in the network.
 
 A fixed association is possible in |ns3| without the use of the bootstrap process. For this purpose, the ``LrWpanHelper::CreateAssociatedPan``
-is used.
+is used. See the Helpers subsection for more details.
 
 MAC transmission Queues
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -327,13 +349,22 @@ The default delay model used is ``ConstantSpeedPropagationDelayMode``. Alternati
     lrWpanHelper.CreateAssociatedPan(lrwpanDevices, 0xCAFE);
     NetDeviceContainer lrwpanDevices = lrWpanHelper.Install(nodes);
 
-In the example shown above, the function ``CreateAssociatedPan`` forms a star topology PAN with devices sharing the same PAN ID (0xCAFE).
-Devices are assigned both 64 bit addresses (extended addresses) and 16 bit addresses (short addresses). The first node is assigned the
-role of PAN coordinator. Number of nodes are limited by the number of possible assignable short addresses ([00:01]-[FF:FD]).
+In the example shown above, the function ``CreateAssociatedPan`` forms a star topology PAN with devices sharing the same PAN ID (In the example 0xCAFE).
+Devices are assigned both 64 bit addresses (extended addresses) and 16 bit addresses (short addresses) and can use either to communicate
+when the configuration is completed. The first node in the ``NodeContainer`` is assigned the role of PAN coordinator.
+The number of nodes provided to the helper are limited by the number of possible assignable short addresses ([00:01]-[FF:FD]).
 
-For more complex topologies or a more robust address assignation scheme, the bootstrap process is recommended.
+It is also possible to manually assign the PAN ID, the extended address and the short address without the use of a helper. To know how to do this,
+refer to the ``lr-wpan-data.cc`` example.
 
-The helper can be used to generate pcap or ascii traces.
+For more complex topologies an auto-configured address assignation scheme is recommended,
+the bootstrap process (scan and association) described by the standard can help with this.
+
+**Important:** Devices that does not have short addresses assigned (Any address other than ``FF:FF``) on PAN IDs cannot communicate in lr-wpan network. Make sure both
+are present in your simulated devices using any of the schemes described.
+
+
+Finally, the ``LrWpanHelper`` can be used to generate pcap or ascii traces.
 These pcap files can be later on visualized in Wireshark.
 
 ::
@@ -344,8 +375,59 @@ These pcap files can be later on visualized in Wireshark.
     Ptr<OutputStreamWrapper> stream = ascii.CreateFileStream("lr-wpan-data.tr");
     lrWpanHelper.EnableAsciiAll(stream);
 
-Examples
-~~~~~~~~
+Attributes
+~~~~~~~~~~
+
+The following is a list of attributes used to configure the behavior of the PHY layer:
+
+* ``PostReceptionErrorModel``: An optional packet error model can be added to the receive packet process after any propagation-based (SNR-based) error models have been applied. Typically this is used to force specific packet drops, for testing purposes.
+
+
+The following is a list of attributes that can be set directly to configure the
+general behavior of the **MAC layer**. Most of this attributes have a counter part with
+the PIB attributes and constants described by the standard.
+
+* ``PanId``: Set the 16-bit identifier of the associated PAN.
+
+Traces
+~~~~~~
+
+
+The following is a list of the trace source that can be used to monitor the behavior of the **PHY layer**:
+
+* ``TrxStateValue``: The state of the finit state machine of the PHY.
+* ``TrxState``: The state of the transceiver.
+* ``PhyTxBegin``: Indicates that a packet has begun transmitting over the channel medium.
+* ``PhyTxEnd``: Indicates that a packet has been completely transmitted over the channel.
+* ``PhyTxDrop``: Indicates that a packet has been dropped by the device during transmission.
+* ``PhyRxBegin``: Indicates that a packet has begun being received from the channel medium by the receiver.
+* ``PhyRxEnd``: Indicates that a packet has been completely received from the channel medium.
+* ``PhyRxDrop``: Indicates that a packet has been dropped by the device during reception.
+
+The following is a list of the trace sources that can be used to monitor the behavior of the **MAC layer**:
+
+* ``MacTxEnqueue``: Trace source indicating a packet has been enqueued in the transaction queue.
+* ``MacTxDequeue``: Trace source indicating a packet has was dequeued from the transaction queue.
+* ``MacIndTxEnqueue``: Trace source indicating a packet has been enqueued in the indirect transaction queue.
+* ``MacIndTxDequeue``: Trace source indicating a packet has was dequeued from the indirect transaction queue.
+* ``MacTx``: Trace source indicating a packet has arrived for transmission by this device.
+* ``MacTxOk``: Trace source indicating a packet has been successfully sent.
+* ``MacTxDrop``: Trace source indicating a packet has been dropped during transmission.
+* ``MacIndTxDrop``: Trace source indicating a packet has been dropped from the indirect transaction queue (The pending transaction list).
+* ``MacPromiscRx``: A packet has been received by this device, has been passed up from the physical layer and is being forwarded up the local protocol stack.
+* ``MacRx``: A packet has been received by this device, has been passed up from the physical layer and is being forwarded up the local protocol stack.
+* ``MacRxDrop``: Trace source indicating a packet was received, but dropped before being forwarded up the stack.
+* ``Sniffer``: Trace source simulating a non-promiscuous packet sniffer attached to the device.
+* ``PromiscSniffer``: Trace source simulating a promiscuous packet sniffer attached to the device.
+* ``MacStateValue``: Shows the current state of LrWpan MAC layer.
+* ``MacIncSuperframeStatus``: When using the beacon mode, shows the period status of the incoming superframe.
+* ``MacOutSuperframeStatus``: When using the beacon mode, shows the period status of the outgoing superframe.
+* ``MacState``: The state of LrWpan Mac.
+* ``MacSentPkt``: Trace source reporting some information about the sent packet.
+* ``IfsEnd``: Reports the end of an Interframe space period (IFS).
+
+Examples and Tests
+------------------
 
 The following examples have been written, which can be found in ``src/lr-wpan/examples/``:
 
@@ -394,9 +476,6 @@ surrounding devices.
 
     Default output of the program ``lr-wpan-error-distance-plot.cc``
 
-Tests
-~~~~~
-
 The following tests have been written, which can be found in ``src/lr-wpan/tests/``:
 
 * ``lr-wpan-ack-test.cc``:  Check that acknowledgments are being used and issued in the correct order.
@@ -432,28 +511,6 @@ of the error model validation and can be reproduced by running
 
     Default output of the program ``lr-wpan-error-model-plot.cc``
 
-
-Scope and Limitations
----------------------
-
-Future versions of this document will contain a PICS proforma similar to
-Appendix D of IEEE 802.15.4-2006. The current emphasis is on direct transmissions
-running on both, slotted and unslotted mode (CSMA/CA) of 802.15.4 operation for use in Zigbee.
-
-- Indirect data transmissions are not supported but planned for a future update.
-- Devices are capable of associating with a single PAN coordinator.
-- Interference is modeled as AWGN but this is currently not thoroughly tested.
-- The standard describes the support of multiple PHY band-modulations but currently, only 250kbps O-QPSK (channel page 0) is supported.
-- Active and passive MAC scans are able to obtain a LQI value from a beacon frame, however, the scan primitives assumes LQI is correctly implemented and does not check the validity of its value.
-- Configuration of the ED thresholds are currently not supported.
-- Coordinator realignment command is only supported in orphan scans.
-- Disassociation primitives are not supported.
-- Security is not supported.
-- Guaranteed Time Slots (GTS) are not supported.
-- Not all attributes are supported by the MLME-SET and MLME-GET primitives.
-- Indirect transmissions are only supported during the association process.
-- RSSI is not supported as this is part of the 2015 revision and the current implementation only supports until the 2011 revision.
-
 References
 ----------