zigbee: Update documentation (Mesh routing)

src/zigbee/doc/zigbee.rst

@@ -16,7 +16,7 @@ This module is presented here with no guarantees of any kind and it has no assoc
 CSA or Zigbee (TM) products.
 
 
-The source code for the new module lives in the directory ``src\zigbee``.
+The source code for the new module lives in the directory ``src/zigbee``.
 
 .. _fig-ZigbeeStackArch:
 
@@ -24,7 +24,8 @@ The source code for the new module lives in the directory ``src\zigbee``.
 
     Zigbee Stack Architecture in ns-3
 
-The Zigbee stack implementation is meant to be use on top of an existing |ns3| ``LrWpanNetDevice`` (IEEE 802.15.4-2011 PHY & MAC stack).
+The Zigbee stack implementation is meant to be use on top of a |ns3| NetDevice with a valid lr-wpan MAC layer implementation.
+This is in essence, a Netdevice that contains a ``LrWpanMacBase`` object which enforces a IEEE 802.15.4-2011 compliant MAC.
 The current scope of the project includes **only the NWK layer in the Zigbee stack**. However, the project can be later extended
 to support higher layers like the Application Sublayer (APS) and the Zigbee Cluster Library (ZCL).
 
@@ -37,10 +38,10 @@ Scope and Limitations
 - Source routing and Tree routing are not implemented.
 - Zigbee Stack profile 0x01 (used for tree routing and distributed address assignment) is not supported.
 - A few NIB attributes setting and NWK constants are not supported by the |ns3| attribute system.
-- Traces are not yet implemented.
+- Traces are not implemented yet.
 - Data broadcast do not support retries or passive acknowledgment.
 - Data broadcast to low power routers is not supported as the underlying lr-wpan netdevice has no concept of energy consumption.
-- The following Zigbee layers are not yet supported yet:
+- The following Zigbee layers are not supported yet:
    - Zigbee Application Support Sub-Layer (APS)
    - Zigbee Cluster Library (ZCL)
    - Zigbee Device Object (ZDO)
@@ -98,12 +99,6 @@ From these routing protocols, the current |ns3| implementation only supports the
 
 **Many-To-One Routing**
 
-.. _fig-manyToOne:
-
-.. figure:: figures/manyToOne.*
-
-    Many-To-One routing
-
 In Zigbee networks, it's common for multiple nodes to need to communicate with a single node, often referred to as a concentrator.
 If all nodes perform a Mesh route discovery for this single point in the network, it can lead to an overwhelming number of route request messages, which may degrade network performance.
 Under these circumstances, Many-to-One routing is typically more efficient than Mesh routing.
@@ -115,8 +110,14 @@ The general procedure for Many-to-One routing is as follows:
 2. Devices receiving this broadcast store a reverse route into their routing table pointing to the path towards the concentrator.
 3. If we are receiving the RREQ for the first time or the accumulated pathcost is better to the route stored in the routing table, the RREQ is re-broadcasted.
 
+.. _fig-manyToOne:
+
+.. figure:: figures/manyToOne.*
+
+    Zigbee Many-To-One routing
+
 There can be multiple concentrator nodes in the network and it is possible to run Many-To-One routing along Mesh routing.
-In |ns3|, Many-To-One routing is achieved by using the ``NLME-ROUTE-DISCOVERY.request`` primitive:::
+In |ns3|, Many-To-One routing is achieved by using the ``NLME-ROUTE-DISCOVERY.request`` primitive::
 
    // zstack is an instance of a ZigbeeStack object installed in node that will
    // become the concentrator node.
@@ -128,10 +129,75 @@ In |ns3|, Many-To-One routing is achieved by using the ``NLME-ROUTE-DISCOVERY.re
    zstack->GetNwk()->NlmeRouteDiscoveryRequest(routeDiscParams);
 
 Important: The process described above assumes that devices have already joined the network.
-A route discovery request before a device is part of the network (join process) will result in failure.
+A route discovery request issued before a device is part of the network (join process) will result in failure.
 
 **Mesh Routing**
 
+Mesh routing in Zigbee is often attributed to the mechanisms used by the AODV routing protocol (`RFC 3561 <https://datatracker.ietf.org/doc/html/rfc3561>`_).
+Although Zigbee mesh routing and the AODV protocol share some similarities, there are significant differences between them that directly influence performance.
+
+Firstly, AODV was designed for IP-based networks, whereas Zigbee operates without the concept of IP addresses, thus eliminating their associated overhead.
+Additionally, unlike AODV, Zigbee employs several distinct tables (such as the RREQ table, routing table, neighbor table, and discovery table) to manage route discovery and storage.
+The use of these tables allows Zigbee to implement various storage and update policies based on the type of information they hold.
+For instance, entries for neighboring nodes are typically updated frequently and have a short lifespan.
+In contrast, entries in routing tables are usually long-lived or do not expire but may be replaced by new entries when space is limited.
+The RREQ and discovery tables, on the other hand, are used exclusively during the route discovery process to optimize this process and facilitate the early detection of errors and loops.
+
+In addition to these differences, Zigbee incorporates detailed policies, such as packet retransmissions, which come with defined default values to enhance consistency across various Zigbee implementations.
+For more information on the implementation details and policies that govern Zigbee, please refer to the Zigbee specification.
+
+The primary goal of mesh routing is to establish the shortest path to a specific destination within the network.
+While hop count is the most commonly used metric for calculating path cost, Zigbee can also utilize the link quality indicator (LQI) to determine the shortest route to the destination (the default option).
+The general procedure for mesh routing is as follows:
+
+1. The source node broadcasts a route request (RREQ) to its neighboring nodes, specifying the desired destination.
+2. Upon receiving the RREQ, the device calculates the link cost and adds it to the path cost already present in the RREQ.
+3. The device then searches for a valid route to the destination, first in its neighbor table, followed by its discovery table and routing table.
+4. If the destination is found, the device issues a route reply (RREP). If not, the RREQ is re-broadcasted only if it is the first time that a RREQ for that destination is sent from this location, or if a better path cost has been obtained.
+5. When the RREQ reaches the destination or a neighboring node that knows the destination, an RREP is sent back to the source, using the information contained in the discovery table.
+6. If there is no existing entry in the routing table, a new entry is created with the details of the most optimal path.
+
+.. _fig-mesh:
+
+.. figure:: figures/mesh.*
+
+    Zigbee Mesh routing
+
+Routing table entries are created only when an RREP is received, and only for the destination specified in the route discovery request.
+A separate route discovery request must be issued for each destination that needs to be recorded in the source device.
+
+In |ns3|, Mesh routing is achieved by using the ``NLME-ROUTE-DISCOVERY.request`` primitive::
+
+   // zstack is an instance of a ZigbeeStack object installed in node that is the
+   // source of the route discovery request.
+   // Only a destination address parameter is necessary to be specified.
+   // Parameters destination address mode = UCST_BCST and radius = 0 are the default values and
+   // do not need be explicitly written.
+   // Note: As specified by Zigbee, when a radius is set to 0, the radius used is equal to
+   // nwkMaxDepth(5) * 2.
+   NlmeRouteDiscoveryRequestParams routeDiscParams;
+   routeDiscParams.m_dstAddr = Mac16Address("BE:EF");
+   routeDiscParams.m_dstAddrMode = UCST_BCST;
+   routeDiscParams.m_radius = 0;
+   zstack->GetNwk()->NlmeRouteDiscoveryRequest(routeDiscParams);
+
+Alternatively, a Mesh route discovery can be performed along a data transmission request by using the
+``NLDE-DATA.request`` primitive with the ``ENABLE_ROUTE_DISCOVERY`` option::
+
+    // zstack is an instance of a ZigbeeStack object installed in node that is the
+    // source of the data transmission request.
+    // The data transmission can be sent with either the ENABLE_ROUTE_DISCOVERY option (default) or the
+    // SUPPRESS_ROUTE_DISCOVERY option.
+    NldeDataRequestParams dataReqParams;
+    Ptr<Packet> p = Create<Packet>(5);
+    dataReqParams.m_dstAddrMode = UCST_BCST;
+    dataReqParams.m_dstAddr = Mac16Address("BE:EF");
+    dataReqParams.m_discoverRoute = ENABLE_ROUTE_DISCOVERY;
+    zstack->GetNwk()->NldeDataRequest(dataReqParams, p);
+
+Important: The process described above assumes that devices have already joined the network.
+A route discovery request issued before a device is part of the network (join process) will result in failure.
+
 Usage
 -----