Design Documentation¶

Overview¶

The ns-3 mesh module extends the ns-3 wifi module to provide mesh networking capabilities according to the IEEE 802.11s standard [ieee80211s].

The basic purpose of IEEE 802.11s is to define a mode of operation for Wi-Fi that permits frames to be forwarded over multiple radio hops transparent to higher layer protocols such as IP. To accomplish this, mesh-capable stations form a Mesh Basic Service Set (MBSS) by running a pair-wise peering protocol to establish forwarding associations, and by running a routing protocol to find paths through the network. A special gateway device called a mesh gate allows a MBSS to interconnect with a Distribution System (DS).

The basic enhancements defined by IEEE 802.11s include:

discovery services
peering management
security
beaconing and synchronization
the Mesh Coordination Function (MCF)
power management
channel switching
extended frame formats
path selection and forwarding
interworking (proxy mesh gateways)
intra-mesh congestion control, and
emergency service support.

The ns-3 models implement only a subset of the above service extensions, focusing mainly on those items related to peering and routing/forwarding of data frames through the mesh.

The Mesh NetDevice based on 802.11s D3.0 draft standard was added in ns-3.6 and includes the Mesh Peering Management Protocol and HWMP (routing) protocol implementations. An overview presentation by Kirill Andreev was published at the Workshop on ns-3 in 2009 [And09]. An overview paper is available at [And10].

As of ns-3.23 release, the model has been updated to the 802.11s-2012 standard [ieee80211s] with regard to packet formats, based on the contribution in [Hep15].

These changes include:

Category codes and the categories compliant to IEEE-802.11-2012 Table 8-38—Category values.
Information Elements (An adjustment of the element ID values was needed according to Table 8-54 of IEEE-802.11-2012).
Mesh Peering Management element format changed according to IEEE-802.11-2012 Figure 8-370.
Mesh Configuration element format changed according to IEEE-802.11-2012 Figure 8-363.
PERR element format changed according to IEEE-802.11-2012 Figure 8-394.

With these changes the messages of the Peering Management Protocol and Hybrid Wireless Mesh Protocol will be transmitted compliant to IEEE802.11-2012 and the resulting pcap trace files can be analyzed by Wireshark.

The multi-interface mesh points are supported as an extension of IEEE draft version 3.0. Note that corresponding ns-3 mesh device helper creates a single interface station by default.

Overview of IEEE 802.11s¶

The implementation of the 802.11s extension consists of two main parts: the Peer Management Protocol (PMP) and Hybrid Wireless Mesh Protocol (HWMP).

The tasks of the peer management protocol are the following:

opening links, detecting beacons, and starting peer link finite state machine, and
closing peer links due to transmission failures or beacon loss.

If a peer link between the sender and receiver does not exist, a frame will be dropped. So, the plug-in to the peer management protocol (PMP) is the first in the list of ns3::MeshWifiInterfaceMacPlugins to be used.

Peer management protocol¶

The peer management protocol consists of three main parts:

the protocol itself, ns3::dot11s::PeerManagementProtocol, which keeps all active peer links on interfaces, handles all changes of their states and notifies the routing protocol about link failures.
the MAC plug-in, ns3::dot11s::PeerManagementProtocolMac, which drops frames if there is no peer link, and peeks all needed information from management frames and information elements from beacons.
the peer link, ns3::dot11s::PeerLink, which keeps finite state machine of each peer link, keeps beacon loss counter and counter of successive transmission failures.

The procedure of closing a peer link is not described in detail in the standard, so in the model the link may be closed by:

beacon loss (see an appropriate attribute of ns3::dot11s::PeerLink class)
transmission failure – when a predefined number of successive packets have failed to transmit, the link will be closed.

The peer management protocol is also responsible for beacon collision avoidance, because it keeps beacon timing elements from all neighbours. Note that the PeerManagementProtocol is not attached to the MeshPointDevice as a routing protocol, but the structure is similar: the upper tier of the protocol is ns3::dot11s::PeerManagementProtocol and its plug-in is ns3::dot11s::PeerManagementProtocolMac.

Hybrid Wireless Mesh Protocol¶

HWMP is implemented in both modes, reactive and proactive, although path maintenance is not implemented (so active routes may time out and need to be rebuilt, causing packet loss). Also the model implements an ability to transmit broadcast data and management frames as unicasts (see appropriate attributes). This feature is disabled at a station when the number of neighbors of the station is more than a threshold value.

Forwarding delay¶

Previous versions of this model have had issues with collisions due to the lack of a model for forwarding delay, and lack of clarity about whether backoff should be invoked when forwarding a broadcast frame. These issues become problematic for mesh, because in a topology in which multiple nodes within radio range of the next hop node decide to forward a received frame at the same time, they will repeatedly collide (if no backoff is triggered). Past contributors have argued for the triggering of backoff when forwarding a frame (e.g., [Hep16]), but current wifi module maintainers concluded that the standard does not call for backoff in this case. This was also privately confirmed with a Wi-Fi vendor. Issue 478 in the GitLab.com tracker has more discussion on this point.

In practice, it is assumed that collisions can be avoided due to the fact that each mesh node will take slightly different times to process and forward the frame, and one will go first and trigger a channel busy detection on the other nodes. To accomplish this in ns-3, we must include a model for forwarding delay that includes some randomness.

The class ns3::MeshPointDevice is responsible for forwarding unicast frames, and the class ns3::dot11s::HwmpProtocol is responsible for forwarding management frames when HWMP is used. ns3::MeshPointDevice has an attribute called ForwardingDelay that configures a random variable (units of microseconds) from which a forwarding delay value is drawn for each frame forwarding event. The default configuration of this attribute is a uniform random variable between 300 and 400 microseconds. The mean value was chosen based on the measurement results reported in [Hep16] which measured and derived an average 350 microsecond delay in forwarding frames on real mesh devices. The range of this variable is somewhat arbitrary and determined by some simulation testing to provide a generally low probability of collision; the 100 microsecond range is roughly 11 slot times. The HWMP protocol can also access this random variable to create forwarding delay for the forwarding of management frames. Users may substitute other random variable configurations as desired.

Scope and Limitations¶

Supported features¶

Peering Management Protocol (PMP), including link close heuristics and beacon collision avoidance.
Hybrid Wireless Mesh Protocol (HWMP), including proactive and reactive modes, unicast/broadcast propagation of management traffic, multi-radio extensions.
802.11e compatible airtime link metric.

Verification¶

Comes with the custom Wireshark dissector.
Linux kernel mac80211 layer compatible message formats.

Unsupported features¶

Mesh Coordinated Channel Access (MCCA).
Internetworking: mesh access point and mesh portal.
Security.
Power save.
Path maintenance (sending PREQ proactively before a path expires)
Though multi-radio operation is supported, no channel assignment protocol is proposed for now. (Correct channel switching is not implemented)

Models yet to be created¶

Mesh access point (QoS + non-QoS?)
Mesh portal (QoS + non-QoS?)

Open issues¶

Users should be aware that the mesh module has not been actively maintained for several years and that there may be some performance and standards-alignment issues with the current code. Below is a listing of possible (confirmed and unconfirmed) issues.

A bug was previously reported in the Wi-Fi module that manifests itself as performance degradation in large mesh networks, due to incorrect duplicate frame detection for QoS data frames (https://www.nsnam.org/bugzilla/show_bug.cgi?id=2326).

Mesh does not work for 802.11n/ac/ax stations (https://gitlab.com/nsnam/ns-3-dev/-/issues/176).

Mesh PCAP is not decoded properly by Wireshark (https://www.nsnam.org/bugzilla/show_bug.cgi?id=2880).

Energy module can not be used on mesh devices (https://www.nsnam.org/bugzilla/show_bug.cgi?id=2265).

IE11S_MESH_PEERING_PROTOCOL_VERSION should be removed as per standard. Protocol ID should actually be part of the Mesh Peering Management IE (https://www.nsnam.org/bugzilla/show_bug.cgi?id=2600).

MeshInformationElementVector printing error (https://www.nsnam.org/bugzilla/show_bug.cgi?id=2728).

Mesh is not compatible with IPv6 (https://www.nsnam.org/bugzilla/show_bug.cgi?id=2881).

Mesh is forwarding multicast frames as unicast rather than as group-addressed frames (https://gitlab.com/nsnam/ns-3-dev/-/issues/485).

Mesh group addresses are not being set correctly for multicast frames (https://gitlab.com/nsnam/ns-3-dev/-/issues/476).