From afeec2978c8327991345c05d3a98afbb510977b8 Mon Sep 17 00:00:00 2001
From: Alberto Gallegos Ramonet <alramonet@is.tokushima-u.ac.jp>
Date: Thu, 12 Dec 2024 14:24:04 +0900
Subject: [PATCH] zigbee: Update Zigbee documentation direct join

---
 doc/models/Makefile             |   6 ++--
 src/zigbee/doc/figures/mesh.dia | Bin 3885 -> 3883 bytes
 src/zigbee/doc/zigbee.rst       |  56 ++++++++++++++++++++++++++++----
 3 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/doc/models/Makefile b/doc/models/Makefile
index 77e6ff463..70902beda 100644
--- a/doc/models/Makefile
+++ b/doc/models/Makefile
@@ -561,9 +561,9 @@ $(FIGURES)/nist-frame-success-rate-ax.pdf_width = 12cm
 $(FIGURES)/assoc-manager.pdf_width = 12cm
 $(FIGURES)/emlsr-dl-txop.pdf_width = 12cm
 $(FIGURES)/emlsr-ul-txop.pdf_width = 12cm
-$(FIGURES)/zigbeeStackArch.pdf_width = 8cm
-$(FIGURES)/manyToOne.pdf_width = 8cm
-$(FIGURES)/mesh.pdf_width = 8cm
+$(FIGURES)/zigbeeStackArch.pdf_width = 6cm
+$(FIGURES)/manyToOne.pdf_width = 6cm
+$(FIGURES)/mesh.pdf_width = 6cm
 
 IMAGES_PNG = ${IMAGES_EPS:.eps=.png}
 IMAGES_PDF = ${IMAGES_EPS:.eps=.pdf}
diff --git a/src/zigbee/doc/figures/mesh.dia b/src/zigbee/doc/figures/mesh.dia
index 59368f0f2463ac2e4f510fa263203c97ff5f75b6..94f9617e80f6989f5da7ba6798063cc4135e5018 100644
GIT binary patch
delta 1953
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

delta 1955
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

diff --git a/src/zigbee/doc/zigbee.rst b/src/zigbee/doc/zigbee.rst
index 507895a28..75d51cfd2 100644
--- a/src/zigbee/doc/zigbee.rst
+++ b/src/zigbee/doc/zigbee.rst
@@ -78,22 +78,66 @@ The following is a brief explanation of how users can interact with the NWK and
 Network joining
 ~~~~~~~~~~~~~~~
 
-In a Zigbee network, devices must be organized and related to one another based on their specific roles.
+In a Zigbee network, before devices attempt to exchange data with one another, they must first be organized and related to one another based on their specific roles.
 There are three primary roles in a Zigbee network:
 
-- **Coordinator:** This is the initiating device in the network, and there can only be one coordinator at a time.
-- **Router:** This device is capable of relaying data and commands on behalf of other devices.
-- **End Device:** These are devices with limited capabilities (for example, they cannot route messages) that serve as endpoints within the network.
+- **Coordinator (ZC):** This is the initiating device in the network, and there can only be one coordinator at a time.
+- **Router (ZR):** This device is capable of relaying data and commands on behalf of other devices.
+- **End Device (ZE):** These are devices with limited capabilities (for example, they cannot route messages) that serve as endpoints within the network.
 
 Devices can join a Zigbee network as either routers or end devices.
 They can do this through one of two methods: by using the MAC association process or by joining the network directly.
 
-**Direct Join (a.k.a. Orphaning process)**
-
 
 **Mac Association Join**
 
 
+
+**Direct Join (a.k.a. Orphaning process)**
+
+Direct Join is employed when the number of nodes in the network and their relationships are known in advance.
+As the name suggests, this method involves registering devices directly with a coordinator or router.
+Subsequently, these devices confirm their registration with the coordinator to receive a network address.
+
+This process is simpler than the association method of joining a network, but it is less flexible since it requires manual intervention.
+Below is a summary of the direct join process:
+
+1. If a coordinator device or router is already operational, devices that can communicate with this coordinator must be manually registered using the primitive `NLME-DIRECT-JOIN.request`.
+2. After this registration, the devices registered in step 1 will send a `NLME-JOIN.request` with the rejoin network parameter set to `DIRECT_OR_REJOIN`. This action triggers a MAC orphaning request message, which is used to confirm the device's existence with the coordinator.
+3. The coordinator or router will respond to the orphaning message by providing an assigned short address.
+4. The device accepts this short address and successfully joins the network.
+
+Note: The process described above outlines the steps for joining the network using a direct join method.
+However, devices that are required to act as routers must also issue an additional `NLME-START-ROUTER.request` primitive after joining the network in order to begin functioning as routers.
+
+In |ns3|, a direct join primitive is used as follows::
+
+    CapabilityInformation capaInfo;
+    capaInfo.SetDeviceType(zigbee::MacDeviceType::ROUTER); // The joining device capability is defined here
+    capaInfo.SetAllocateAddrOn(true); // If false, an extended address mode will be used instead
+    // zstack is an instance of a ZigbeeStack object installed in node that is the
+    // coordinator or router where the joining device is being registered
+    NlmeDirectJoinRequestParams directParams;
+    directParams.m_capabilityInfo = capaInfo.GetCapability();
+    directParams.m_deviceAddr = Mac64Address("00:00:00:00:00:00:00:01"); // The device IEEE address (Ext address)
+    zstack->GetNwk()->NlmeDirectJoinRequest(directParams);
+
+The device joining the network must issue a primitive similar to this one::
+
+    // zstack is an instance of a ZigbeeStack object installed in the node joining the network
+    // The orphaning message will be sent to every channel and interface specified.
+    // The rejoin network parameter must be DIRECT_OR_REJOIN
+    NlmeJoinRequestParams joinParams;
+    joinParams.m_rejoinNetwork = zigbee::JoiningMethod::DIRECT_OR_REJOIN;
+    joinParams.m_scanChannelList.channelPageCount = 1;
+    joinParams.m_scanChannelList.channelsField[0] = zigbee::ALL_CHANNELS;
+    joinParams.m_capabilityInfo = capaInfo.GetCapability();
+    joinParams.m_extendedPanId = Mac64Address("00:00:00:00:00:00:CA:FE").ConvertToInt();
+    zstack->GetNwk()->NlmeJoinRequest(joinParams);
+
+
+See zigbee/examples for detailed examples using network joining.
+
 Routing
 ~~~~~~~