A Discrete-Event Network Simulator


Low-Rate Wireless Personal Area Network (LR-WPAN)

This chapter describes the implementation of ns-3 models for the low-rate, wireless personal area network (LR-WPAN) as specified by IEEE standard 802.15.4 (2006).

Model Description

The source code for the lr-wpan module lives in the directory src/lr-wpan.


The model design closely follows the standard from an architectural standpoint.


Architecture and scope of lr-wpan models

The grey areas in the figure (adapted from Fig 3. of IEEE Std. 802.15.4-2006) show the scope of the model.

The Spectrum NetDevice from Nicola Baldo is the basis for the implementation.

The implementation also plans to borrow from the ns-2 models developed by Zheng and Lee in the future.


The APIs closely follow the standard, adapted for ns-3 naming conventions and idioms. The APIs are organized around the concept of service primitives as shown in the following figure adapted from Figure 14 of IEEE Std. 802.15.4-2006.


Service primitives

The APIs are organized around four conceptual services and service access points (SAP):

  • MAC data service (MCPS)
  • MAC management service (MLME)
  • PHY data service (PD)
  • PHY management service (PLME)

In general, primitives are standardized as follows (e.g. Sec of IEEE 802.15.4-2006)::

MCPS-DATA.request      (

This maps to ns-3 classes and methods such as::

struct McpsDataRequestParameters
  uint8_t m_srcAddrMode;
  uint8_t m_dstAddrMode;

LrWpanMac::McpsDataRequest (McpsDataRequestParameters params)


The MAC at present implements the unslotted CSMA/CA variant, without beaconing. Currently there is no support for coordinators and the relavant APIs.

The implemented MAC is similar to Contiki’s NullMAC, i.e., a MAC without sleep features. The radio is assumed to be always active (receiving or transmitting), of completely shut down. Frame reception is not disabled while performing the CCA.

The main API supported is the data transfer API (McpsDataRequest/Indication/Confirm). CSMA/CA according to Stc 802.15.4-2006, section is supported. Frame reception and rejection according to Std 802.15.4-2006, section is supported, including acknowledgements. Only short addressing completely implemented. Various trace sources are supported, and trace sources can be hooked to sinks.


The physical layer components consist of a Phy model, an error rate model, and a loss model. The error rate model presently models the error rate for IEEE 802.15.4 2.4 GHz AWGN channel for OQPSK; the model description can be found in IEEE Std 802.15.4-2006, section E.4.1.7. The Phy model is based on SpectrumPhy and it follows specification described in section 6 of IEEE Std 802.15.4-2006. It models PHY service specifications, PPDU formats, PHY constants and PIB attributes. It currently only supports the transmit power spectral density mask specified in 2.4 GHz per section The noise power density assumes uniformly distributed thermal noise across the frequency bands. The loss model can fully utilize all existing simple (non-spectrum phy) loss models. The Phy model uses the existing single spectrum channel model. The physical layer is modeled on packet level, that is, no preamble/SFD detection is done. Packet reception will be started with the first bit of the preamble (which is not modeled), if the SNR is more than -5 dB, see IEEE Std 802.15.4-2006, appendix E, Figure E.2. Reception of the packet will finish after the packet was completely transmitted. Other packets arriving during reception will add up to the interference/noise.

Currently the receiver sensitivity is set to a fixed value of -106.58 dBm. This corresponds to a packet error rate of 1% for 20 byte reference packets for this signal power, according to IEEE Std 802.15.4-2006, section 6.1.7. In the future we will provide support for changing the sensitivity to different values.


Packet error rate vs. signal power


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 of creating a generic LrWpan device and hooking things together.

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 the unslotted mode of 802.15.4 operation for use in Zigbee, and the scope is limited to enabling a single mode (CSMA/CA) with basic data transfer capabilities. Association with PAN coordinators is not yet supported, nor the use of extended addressing. Interference is modeled as AWGN but this is currently not thoroughly tested.

The NetDevice Tx queue is not limited, i.e., packets are never dropped due to queue becoming full. They may be dropped due to excessive transmission retries or channel access failure.


  • Wireless Medium Access Control (MAC) and Physical Layer (PHY) Specifications for Low-Rate Wireless Personal Area Networks (WPANs), IEEE Computer Society, IEEE Std 802.15.4-2006, 8 September 2006.
    1. Zheng and Myung J. Lee, “A comprehensive performance study of IEEE 802.15.4,” Sensor Network Operations, IEEE Press, Wiley Interscience, Chapter 4, pp. 218-237, 2006.


Enabling lr-wpan

Add lr-wpan to the list of modules built with ns-3.


The helper is patterned after other device helpers. In particular, tracing (ascii and pcap) is enabled similarly, and enabling of all lr-wpan log components is performed similarly. Use of the helper is exemplified in examples/lr-wpan-data.cc. For ascii tracing, the transmit and receive traces are hooked at the Mac layer.

The default propagation loss model added to the channel, when this helper is used, is the LogDistancePropagationLossModel with default parameters.


The following examples have been written, which can be found in src/lr-wpan/examples/:

  • lr-wpan-data.cc: A simple example showing end-to-end data transfer.
  • lr-wpan-error-distance-plot.cc: An example to plot variations of the packet success ratio as a function of distance.
  • lr-wpan-error-model-plot.cc: An example to test the phy.
  • lr-wpan-packet-print.cc: An example to print out the MAC header fields.
  • lr-wpan-phy-test.cc: An example to test the phy.

In particular, the module enables a very simplified end-to-end data transfer scenario, implemented in lr-wpan-data.cc. The figure shows a sequence of events that are triggered when the MAC receives a DataRequest from the higher layer. It invokes a Clear Channel Assessment (CCA) from the PHY, and if successful, sends the frame down to the PHY where it is transmitted over the channel and results in a DataIndication on the peer node.


Data example for simple LR-WPAN data transfer end-to-end

The example lr-wpan-error-distance-plot.cc plots the packet success ratio (PSR) as a function of distance, using the default LogDistance propagation loss model and the 802.15.4 error model. The channel (default 11), packet size (default 20 bytes) and transmit power (default 0 dBm) can be varied by command line arguments. The program outputs a file named 802.15.4-psr-distance.plt. Loading this file into gnuplot yields a file 802.15.4-psr-distance.eps, which can be converted to pdf or other formats. The default output is shown below.


Default output of the program lr-wpan-error-distance-plot.cc


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.
  • lr-wpan-collision-test.cc: Test correct reception of packets with interference and collisions.
  • lr-wpan-error-model-test.cc: Check that the error model gives predictable values.
  • lr-wpan-packet-test.cc: Test the 802.15.4 MAC header/trailer classes
  • lr-wpan-pd-plme-sap-test.cc: Test the PLME and PD SAP per IEEE 802.15.4
  • lr-wpan-spectrum-value-helper-test.cc: Test that the conversion between power (expressed as a scalar quantity) and spectral power, and back again, falls within a 25% tolerance across the range of possible channels and input powers.


The model has not been validated against real hardware. The error model has been validated against the data in IEEE Std 802.15.4-2006, section E.4.1.7 (Figure E.2). The MAC behavior (CSMA backoff) has been validated by hand against expected behavior. The below plot is an example of the error model validation and can be reproduced by running lr-wpan-error-model-plot.cc:


Default output of the program lr-wpan-error-model-plot.cc