[nexus] add test 5.2.4 Router Upgrade Threshold - REED (#12395)

Adds a new Nexus test case for 'Router Upgrade Threshold - REED' (5.2.4)
as specified in the test specification.

Summary of changes:
- Implemented Nexus test 5.2.4:
    - test_5_2_4.cpp: Sets up a topology with 16 routers (including Leader)
      and verifies that a REED DUT does not upgrade to a router until a
      minimal end device (MED) attempts to attach to it.
    - verify_5_2_4.py: PCAP verification script for test 5.2.4, ensuring
      correct MLE advertisements, Parent/Child ID exchange, Address Solicit
      Request formatting, and ICMPv6 Echo connectivity.
- Updated build and execution scripts:
    - Modified CMakeLists.txt to build the new 5_2_4 test executable.
    - Updated run_nexus_tests.sh to include 5_2_4 in the default test list.

The test verifies that the DUT correctly manages the router upgrade
threshold and transitions to the router role when required to support a
child.
This commit is contained in:
Jonathan Hui
2026-02-09 17:16:19 -08:00
committed by GitHub
parent 462425c0e8
commit 7215d063f4
4 changed files with 544 additions and 0 deletions
+1
View File
@@ -131,6 +131,7 @@ ot_nexus_test(5_1_12 "cert;nexus")
ot_nexus_test(5_1_13 "cert;nexus")
ot_nexus_test(5_2_1 "cert;nexus")
ot_nexus_test(5_2_3 "cert;nexus")
ot_nexus_test(5_2_4 "cert;nexus")
# Misc tests
ot_nexus_test(border_admitter "core;nexus")
+1
View File
@@ -63,6 +63,7 @@ DEFAULT_TESTS=(
"5_1_13"
"5_2_1"
"5_2_3"
"5_2_4"
)
# Use provided arguments or the default test list
+308
View File
@@ -0,0 +1,308 @@
/*
* Copyright (c) 2026, The OpenThread Authors.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the copyright holder nor the
* names of its contributors may be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
#include <stdio.h>
#include "platform/nexus_core.hpp"
#include "platform/nexus_node.hpp"
namespace ot {
namespace Nexus {
/**
* Time to advance for a node to form a network and become leader.
*/
static constexpr uint32_t kFormNetworkTime = 13 * 1000;
/**
* Time to advance for a node to join as a child and upgrade to a router.
* This duration accounts for MLE attach process and ROUTER_SELECTION_JITTER.
*/
static constexpr uint32_t kAttachToRouterTime = 200 * 1000;
/**
* REED_ADVERTISEMENT_INTERVAL in milliseconds.
*/
static constexpr uint32_t kReedAdvertisementInterval = 570 * 1000;
/**
* REED_ADVERTISEMENT_MAX_JITTER in milliseconds.
*/
static constexpr uint32_t kReedAdvertisementMaxJitter = 60 * 1000;
/**
* Time to wait for MLE advertisement.
*/
static constexpr uint32_t kWaitTime = kReedAdvertisementInterval + kReedAdvertisementMaxJitter;
/**
* Time to wait for ICMPv6 Echo Response.
*/
static constexpr uint32_t kEchoResponseTime = 1000;
/**
* Number of routers in the topology besides the leader.
*/
static constexpr uint16_t kNumRouters = 15;
/**
* Hop limit for ICMPv6 Echo Request.
*/
static constexpr uint8_t kEchoHopLimit = 64;
/**
* Echo Request Identifier.
*/
static constexpr uint16_t kEchoIdentifier = 0x1234;
void Test5_2_4(void)
{
/**
* 5.2.4 Router Upgrade Threshold - REED
*
* 5.2.4.1 Topology
* - Each router numbered 1 through 15 have a link to leader
* - Router 15 and REED_1 (DUT) have a link
* - REED_1 (DUT) and MED_1 have a link.
*
* 5.2.4.2 Purpose & Description
* The purpose of this test case is to:
* 1. Verify that the DUT does not attempt to become a router if there are already 16 active routers on the Thread
* network AND it is not bringing children.
* 2. Verify that the DUT transmits MLE Advertisement messages every REED_ADVERTISEMENT_INTERVAL (+
* REED_ADVERTISEMENT_MAX_JITTER) seconds.
* 3. Verify that the DUT upgrades to a router by sending an Address Solicit Request when a child attempts to
* attach to it.
*
* Spec Reference | V1.1 Section | V1.3.0 Section
* --------------------------------------------|----------------|----------------
* Router ID Management / Router ID Assignment | 5.9.9 / 5.9.10 | 5.9.9 / 5.9.10
*/
Core nexus;
Node &leader = nexus.CreateNode();
Node *routers[kNumRouters];
Node &reed1 = nexus.CreateNode();
Node &med1 = nexus.CreateNode();
leader.SetName("Leader");
for (uint16_t i = 0; i < kNumRouters; i++)
{
routers[i] = &nexus.CreateNode();
routers[i]->SetName("Router", i + 1);
}
reed1.SetName("REED", 1);
med1.SetName("MED", 1);
nexus.AdvanceTime(0);
Instance::SetLogLevel(kLogLevelNote);
/** Use AllowList feature to restrict the topology. */
for (uint16_t i = 0; i < kNumRouters; i++)
{
leader.AllowList(*routers[i]);
routers[i]->AllowList(leader);
}
/** Router 15 and REED_1 (DUT) have a link */
routers[kNumRouters - 1]->AllowList(reed1);
reed1.AllowList(*routers[kNumRouters - 1]);
/** REED_1 (DUT) and MED_1 have a link. */
reed1.AllowList(med1);
med1.AllowList(reed1);
Log("Step 1: Ensure topology is formed correctly without the DUT.");
/**
* Step 1: All
* - Description: Ensure topology is formed correctly without the DUT.
* - Pass Criteria: N/A
*/
leader.Form();
nexus.AdvanceTime(kFormNetworkTime);
VerifyOrQuit(leader.Get<Mle::Mle>().IsLeader());
for (uint16_t i = 0; i < kNumRouters; i++)
{
routers[i]->Join(leader);
}
nexus.AdvanceTime(kAttachToRouterTime);
for (uint16_t i = 0; i < kNumRouters; i++)
{
VerifyOrQuit(routers[i]->Get<Mle::Mle>().IsRouter());
}
Log("Step 2: The harness causes the DUT to attach to any node, 2-hops from the Leader.");
/**
* Step 2: REED_1 (DUT)
* - Description: The harness causes the DUT to attach to any node, 2-hops from the Leader.
* - Pass Criteria: The DUT MUST NOT attempt to become an active router by sending an Address Solicit Request.
*/
reed1.Join(*routers[kNumRouters - 1]);
nexus.AdvanceTime(kAttachToRouterTime);
VerifyOrQuit(reed1.Get<Mle::Mle>().IsChild());
Log("Step 3: Automatically sends MLE Advertisements.");
/**
* Step 3: REED_1 (DUT)
* - Description: Automatically sends MLE Advertisements.
* - Pass Criteria:
* - The DUT MUST send properly formatted MLE Advertisements.
* - MLE Advertisements MUST be sent with an IP Hop Limit of 255, to the Link-Local All Nodes multicast
* address (FF02::1).
* - The following TLVs MUST be present in the MLE Advertisements:
* - Leader Data TLV
* - Source Address TLV
* - The following TLV MUST NOT be present in the MLE Advertisement:
* - Route64 TLV
*/
Log("Step 4: Wait for REED_ADVERTISEMENT_INTERVAL+ REED_ADVERTISEMENT_MAX_JITTER seconds.");
/**
* Step 4: Wait
* - Description: Wait for REED_ADVERTISEMENT_INTERVAL+ REED_ADVERTISEMENT_MAX_JITTER seconds (default time = 630
* seconds).
* - Pass Criteria: N/A
*/
nexus.AdvanceTime(kWaitTime);
Log("Step 5: Automatically sends a MLE Advertisement.");
/**
* Step 5: REED_1 (DUT)
* - Description: Automatically sends a MLE Advertisement.
* - Pass Criteria: The DUT MUST send a second MLE Advertisement after REED_ADVERTISEMENT_INTERVAL+JITTER where
* JITTER <= REED_ADVERTISEMENT_MAX_JITTER.
*/
Log("Step 6: Automatically sends multicast MLE Parent Request.");
/**
* Step 6: MED_1
* - Description: Automatically sends multicast MLE Parent Request.
* - Pass Criteria: N/A
*/
med1.Join(reed1, Node::kAsMed);
Log("Step 7: Automatically sends MLE Parent Response.");
/**
* Step 7: REED_1 (DUT)
* - Description: Automatically sends MLE Parent Response.
* - Pass Criteria: The DUT MUST reply with a properly formatted MLE Parent Response.
*/
Log("Step 8: Automatically sends MLE Child ID Request to the DUT.");
/**
* Step 8: MED_1
* - Description: Automatically sends MLE Child ID Request to the DUT.
* - Pass Criteria: N/A
*/
Log("Step 9: Automatically sends an Address Solicit Request to the Leader.");
/**
* Step 9: REED_1 (DUT)
* - Description: Automatically sends an Address Solicit Request to the Leader.
* - Pass Criteria:
* - Verify that the DUTs Address Solicit Request is properly formatted:
* - CoAP Request URI: coap://[<leader address>]:MM/a/as
* - CoAP Payload:
* - MAC Extended Address TLV
* - Status TLV
* - RLOC16 TLV (optional)
*/
nexus.AdvanceTime(kAttachToRouterTime);
VerifyOrQuit(reed1.Get<Mle::Mle>().IsRouter());
Log("Step 10: Optionally, automatically sends a Multicast Link Request after receiving an Address Solicit "
"Response.");
/**
* Step 10: REED_1 (DUT)
* - Description: Optionally, automatically sends a Multicast Link Request after receiving an Address Solicit
* Response from Leader with its new Router ID.
* - Pass Criteria:
* - The DUT MAY send a Multicast Link Request to the Link-Local All-Routers multicast address (FF02::2).
* - The following TLVs MUST be present in the Link Request:
* - Challenge TLV
* - Leader Data TLV
* - Source Address TLV
* - TLV Request TLV: Link Margin
* - Version TLV
*/
Log("Step 11: Automatically sends MLE Child ID Response to MED_1.");
/**
* Step 11: REED_1 (DUT)
* - Description: Automatically sends MLE Child ID Response to MED_1.
* - Pass Criteria: The DUTs MLE Child ID Response MUST be properly formatted with MED_1s new 16-bit address.
*/
VerifyOrQuit(med1.Get<Mle::Mle>().IsChild());
Log("Step 12: Harness verifies connectivity by instructing the device to send an ICMPv6 Echo Request.");
/**
* Step 12: MED_1
* - Description: The harness verifies connectivity by instructing the device to send an ICMPv6 Echo Request to the
* Leader.
* - Pass Criteria: The Leader MUST respond with an ICMPv6 Echo Reply.
*/
{
Message *message = med1.Get<Ip6::Icmp>().NewMessage();
Ip6::MessageInfo messageInfo;
VerifyOrQuit(message != nullptr);
messageInfo.SetPeerAddr(leader.Get<Mle::Mle>().GetMeshLocalEid());
messageInfo.SetHopLimit(kEchoHopLimit);
SuccessOrQuit(med1.Get<Ip6::Icmp>().SendEchoRequest(*message, messageInfo, kEchoIdentifier));
}
nexus.AdvanceTime(kEchoResponseTime);
nexus.SaveTestInfo("test_5_2_4.json");
}
} // namespace Nexus
} // namespace ot
int main(void)
{
ot::Nexus::Test5_2_4();
printf("All tests passed\n");
return 0;
}
+234
View File
@@ -0,0 +1,234 @@
#!/usr/bin/env python3
#
# Copyright (c) 2026, The OpenThread Authors.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# 3. Neither the name of the copyright holder nor the
# names of its contributors may be used to endorse or promote products
# derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
#
import sys
import os
# Add the current directory to sys.path to find verify_utils
CUR_DIR = os.path.dirname(os.path.abspath(__file__))
sys.path.append(CUR_DIR)
import verify_utils
from pktverify import consts
from pktverify.null_field import nullField
def verify(pv):
# 5.2.4 Router Upgrade Threshold - REED
#
# 5.2.4.1 Topology
# - Each router numbered 1 through 15 have a link to leader
# - Router 15 and REED_1 (DUT) have a link
# - REED_1 (DUT) and MED_1 have a link.
#
# 5.2.4.2 Purpose & Description
# The purpose of this test case is to:
# 1. Verify that the DUT does not attempt to become a router if there are already 16 active routers on the
# Thread network AND it is not bringing children.
# 2. Verify that the DUT transmits MLE Advertisement messages every REED_ADVERTISEMENT_INTERVAL (+
# REED_ADVERTISEMENT_MAX_JITTER) seconds.
# 3. Verify that the DUT upgrades to a router by sending an Address Solicit Request when a child attempts
# to attach to it.
#
# Spec Reference | V1.1 Section | V1.3.0 Section
# --------------------------------------------|----------------|----------------
# Router ID Management / Router ID Assignment | 5.9.9 / 5.9.10 | 5.9.9 / 5.9.10
pkts = pv.pkts
pv.summary.show()
LEADER = pv.vars['Leader']
ROUTER_15 = pv.vars['Router 15']
REED_1 = pv.vars['REED 1']
MED_1 = pv.vars['MED 1']
# Step 1: All
# - Description: Ensure topology is formed correctly without the DUT.
# - Pass Criteria: N/A
print("Step 1: Ensure topology is formed correctly without the DUT.")
# Step 2: REED_1 (DUT)
# - Description: The harness causes the DUT to attach to any node, 2-hops from the Leader.
# - Pass Criteria: The DUT MUST NOT attempt to become an active router by sending an Address Solicit Request.
print("Step 2: The DUT MUST NOT attempt to become an active router.")
# We verify it joins as a child and NO Address Solicit Request is sent before Step 9.
pkts.filter_wpan_src64(REED_1).\
filter_wpan_dst64(ROUTER_15).\
filter_mle_cmd(consts.MLE_CHILD_ID_REQUEST).\
must_next()
# Step 3: REED_1 (DUT)
# - Description: Automatically sends MLE Advertisements.
# - Pass Criteria:
# - The DUT MUST send properly formatted MLE Advertisements.
# - MLE Advertisements MUST be sent with an IP Hop Limit of 255, to the Link-Local All Nodes multicast
# address (FF02::1).
# - The following TLVs MUST be present in the MLE Advertisements:
# - Leader Data TLV
# - Source Address TLV
# - The following TLV MUST NOT be present in the MLE Advertisement:
# - Route64 TLV
print("Step 3: The DUT MUST send properly formatted MLE Advertisements.")
_pkt = pkts.filter_wpan_src64(REED_1).\
filter_LLANMA().\
filter_mle_cmd(consts.MLE_ADVERTISEMENT).\
filter(lambda p: {
consts.LEADER_DATA_TLV,
consts.SOURCE_ADDRESS_TLV
} <= set(p.mle.tlv.type) and
p.ipv6.hlim == 255).\
must_next()
_pkt.must_not_verify(lambda p: (consts.ROUTE64_TLV) in p.mle.tlv.type)
# Step 4: Wait
# - Description: Wait for REED_ADVERTISEMENT_INTERVAL+ REED_ADVERTISEMENT_MAX_JITTER seconds (default time = 630
# seconds).
# - Pass Criteria: N/A
print("Step 4: Wait for REED_ADVERTISEMENT_INTERVAL+ REED_ADVERTISEMENT_MAX_JITTER seconds.")
# Step 5: REED_1 (DUT)
# - Description: Automatically sends a MLE Advertisement.
# - Pass Criteria: The DUT MUST send a second MLE Advertisement after REED_ADVERTISEMENT_INTERVAL+JITTER where
# JITTER <= REED_ADVERTISEMENT_MAX_JITTER.
print("Step 5: The DUT MUST send a second MLE Advertisement.")
pkts.filter_wpan_src64(REED_1).\
filter_LLANMA().\
filter_mle_cmd(consts.MLE_ADVERTISEMENT).\
must_next()
# Step 6: MED_1
# - Description: Automatically sends multicast MLE Parent Request.
# - Pass Criteria: N/A
print("Step 6: MED_1 sends multicast MLE Parent Request.")
pkts.filter_wpan_src64(MED_1).\
filter_LLARMA().\
filter_mle_cmd(consts.MLE_PARENT_REQUEST).\
must_next()
# Step 7: REED_1 (DUT)
# - Description: Automatically sends MLE Parent Response.
# - Pass Criteria: The DUT MUST reply with a properly formatted MLE Parent Response.
print("Step 7: The DUT MUST reply with a properly formatted MLE Parent Response.")
pkts.filter_wpan_src64(REED_1).\
filter_wpan_dst64(MED_1).\
filter_mle_cmd(consts.MLE_PARENT_RESPONSE).\
filter(lambda p: {
consts.CHALLENGE_TLV,
consts.CONNECTIVITY_TLV,
consts.LEADER_DATA_TLV,
consts.LINK_LAYER_FRAME_COUNTER_TLV,
consts.LINK_MARGIN_TLV,
consts.RESPONSE_TLV,
consts.SOURCE_ADDRESS_TLV,
consts.VERSION_TLV
} <= set(p.mle.tlv.type)).\
must_next()
# Step 8: MED_1
# - Description: Automatically sends MLE Child ID Request to the DUT.
# - Pass Criteria: N/A
print("Step 8: MED_1 sends MLE Child ID Request to the DUT.")
pkts.filter_wpan_src64(MED_1).\
filter_wpan_dst64(REED_1).\
filter_mle_cmd(consts.MLE_CHILD_ID_REQUEST).\
must_next()
# Step 9: REED_1 (DUT)
# - Description: Automatically sends an Address Solicit Request to the Leader.
# - Pass Criteria:
# - Verify that the DUTs Address Solicit Request is properly formatted:
# - CoAP Request URI: coap://[<leader address>]:MM/a/as
# - CoAP Payload:
# - MAC Extended Address TLV
# - Status TLV
# - RLOC16 TLV (optional)
print("Step 9: The DUT MUST send an Address Solicit Request to the Leader.")
pkts.filter_wpan_src64(REED_1).\
filter_coap_request(consts.ADDR_SOL_URI).\
filter(lambda p: {
consts.NL_MAC_EXTENDED_ADDRESS_TLV,
consts.NL_STATUS_TLV
} <= set(p.coap.tlv.type)).\
must_next()
# Step 10: REED_1 (DUT)
# - Description: Optionally, automatically sends a Multicast Link Request after receiving an Address Solicit
# Response from Leader with its new Router ID.
# - Pass Criteria:
# - The DUT MAY send a Multicast Link Request to the Link-Local All-Routers multicast address (FF02::2).
# - The following TLVs MUST be present in the Link Request:
# - Challenge TLV
# - Leader Data TLV
# - Source Address TLV
# - TLV Request TLV: Link Margin
# - Version TLV
print("Step 10: The DUT MAY send a Multicast Link Request.")
# We use next() since it's optional
pkts.filter_wpan_src64(REED_1).\
filter_LLARMA().\
filter_mle_cmd(consts.MLE_LINK_REQUEST).\
filter(lambda p: {
consts.CHALLENGE_TLV,
consts.LEADER_DATA_TLV,
consts.SOURCE_ADDRESS_TLV,
consts.TLV_REQUEST_TLV,
consts.VERSION_TLV
} <= set(p.mle.tlv.type)).\
next()
# Step 11: REED_1 (DUT)
# - Description: Automatically sends MLE Child ID Response to MED_1.
# - Pass Criteria: The DUTs MLE Child ID Response MUST be properly formatted with MED_1s new 16-bit address.
print("Step 11: The DUT MUST send MLE Child ID Response to MED_1.")
pkts.filter_wpan_src64(REED_1).\
filter_wpan_dst64(MED_1).\
filter_mle_cmd(consts.MLE_CHILD_ID_RESPONSE).\
filter(lambda p: {
consts.ADDRESS16_TLV,
consts.LEADER_DATA_TLV,
consts.NETWORK_DATA_TLV,
consts.SOURCE_ADDRESS_TLV
} <= set(p.mle.tlv.type)).\
must_next()
# Step 12: MED_1
# - Description: The harness verifies connectivity by instructing the device to send an ICMPv6 Echo Request to the
# Leader.
# - Pass Criteria: The Leader MUST respond with an ICMPv6 Echo Reply.
print("Step 12: Harness verifies connectivity by sending an ICMPv6 Echo Request.")
_pkt = pkts.filter_ping_request().\
filter_wpan_src64(MED_1).\
must_next()
pkts.filter_ping_reply(identifier=_pkt.icmpv6.echo.identifier).\
filter_ipv6_dst(_pkt.ipv6.src).\
must_next()
if __name__ == '__main__':
verify_utils.run_main(verify)