Class NWKHandler

NWK Handler - Zigbee Network Layer Operations

Handles all Zigbee NWK (Network) layer operations including:

NWK command transmission and processing
Route discovery and management
Source routing
Link status
Leave and rejoin operations
Network commissioning

Constructors

constructor

new NWKHandler(
    context: StackContext,
    macHandler: MACHandler,
    callbacks: NWKHandlerCallbacks,
): NWKHandler
Parameters
- context: StackContext
- macHandler: MACHandler
- callbacks: NWKHandlerCallbacks
Returns NWKHandler
- Defined in src/zigbee-stack/nwk-handler.ts:107

Methods

createSourceRouteEntry

createSourceRouteEntry(
relayAddresses: number[],
pathCost: number,
): SourceRouteTableEntry
05-3474-23 #3.6.3.3 (Source routing tables)

Create a new source route table entry

SPEC COMPLIANCE NOTES:
- ✅ Initializes relay list, path cost, and age information for source route maintenance
- ✅ Resets failure counters and last-used metadata per new measurement
- ⚠️ Implementation stores multiple route entries per destination (spec defines single entry with status) - Provides richer path selection but diverges from formal table layout DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- relayAddresses: number[]
- pathCost: number
Returns SourceRouteTableEntry
- Defined in src/zigbee-stack/nwk-handler.ts:524

findBestSourceRoute

findBestSourceRoute(
    destination16: number | undefined,
    destination64: bigint | undefined,
    ignoreStale?: boolean,
): [relayIndex: number, relayAddresses: number[], pathCost: number]
Finds the best source route to the destination. Implements route aging, failure tracking, and intelligent route selection. Entries with expired routes or too many failures will be purged. Bails early if destination16 is broadcast. Throws if both 16/64 are undefined or if destination is unknown (not in device table). Throws if no route and device is not neighbor.

SPEC COMPLIANCE NOTES (05-3474-23 #3.6.3):
- ✅ Returns early for broadcast addresses (no routing needed)
- ✅ Validates destination is known in device table
- ✅ Returns undefined arrays for direct communication (neighbor devices)
- ⚠️ ROUTE AGING: Implements custom aging mechanism - CONFIG_NWK_ROUTE_EXPIRY_TIME: 300000ms (5 minutes) - CONFIG_NWK_ROUTE_STALENESS_TIME: 120000ms (2 minutes) - These values are implementation-specific, not from spec
- ✅ Route failure tracking with blacklisting: - CONFIG_NWK_ROUTE_MAX_FAILURES: 3 consecutive failures - Marks routes as unusable after threshold ✅
- ⚠️ MULTI-CRITERIA ROUTE SELECTION: - Path cost (hop count) ✅ - Staleness penalty (route age) ✅ - Failure penalty (consecutive failures) ✅ - Recency bonus (recently used routes) ✅ - This is more sophisticated than spec requires
- ✅ Checks MAC NO_ACK tracking for relay validation - Filters out routes with unreliable relays ✅
- ✅ Triggers many-to-one route request when no valid routes - Uses setImmediate for non-blocking trigger ✅
- ⚠️ SPEC DEVIATION: Route table per spec should be: - Destination address - Status (active, discovery underway, validation underway, inactive) - Next hop address - Source route subframe (if source routing) Current implementation uses array of SourceRouteTableEntry per destination This allows multiple routes per destination (more flexible)
- ⚠️ ROUTE DISCOVERY: Triggers MTORR when needed - Spec #3.6.3.5: Route discovery should be used - Implementation uses many-to-one routing (concentrator) ✅ - This is appropriate for coordinator as concentrator
IMPORTANT: This is a critical performance path - called for every outgoing frame DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- destination16: number | undefined
- destination64: bigint | undefined
- ignoreStale: boolean = false
Returns [relayIndex: number, relayAddresses: number[], pathCost: number]
- request invalid (e.g. broadcast destination): [undefined, undefined, undefined]
- request valid and source route unavailable (unknown device or neighbor): [undefined, undefined, undefined]
- request valid and source route available and >=1 relay: [last index in relayAddresses, list of relay addresses, cost of the path]
- request valid and source route available and 0 relay: [undefined, undefined, cost of the path]
- Defined in src/zigbee-stack/nwk-handler.ts:293

hasSourceRoute

hasSourceRoute(
    address16: number,
    newEntry: SourceRouteTableEntry,
    existingEntries?: SourceRouteTableEntry[],
): boolean
05-3474-23 #3.6.3.3

Check if a source route already exists in the table

SPEC COMPLIANCE NOTES:
- ✅ Compares relay hop list and cost to detect duplicate paths before insertion
- ✅ Accepts optional pre-fetched entry array to avoid redundant map lookups
- ⚠️ Formally spec route table holds single entry per destination; this helper assumes multi-entry model DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- address16: number
- newEntry: SourceRouteTableEntry
- OptionalexistingEntries: SourceRouteTableEntry[]
Returns boolean
- Defined in src/zigbee-stack/nwk-handler.ts:545

markRouteFailure

markRouteFailure(destination16: number, triggerRepair?: boolean): void
05-3474-23 #3.6.3.3

Mark a route as failed and handle route repair if needed. Consolidates failure tracking and MTORR triggering per Zigbee spec.

SPEC COMPLIANCE NOTES:
- ✅ Increments failure counter and triggers Many-to-One route discovery after threshold
- ✅ Purges routes that rely on failed relay as required for repair
- ✅ Supports explicit repair trigger (e.g., NWK_STATUS link failure) DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- destination16: number
  Network address of the destination
- triggerRepair: boolean = false
  If true, will purge routes using this destination as relay and trigger MTORR
Returns void
- Defined in src/zigbee-stack/nwk-handler.ts:475

markRouteSuccess

markRouteSuccess(destination16: number): void
05-3474-23 #3.6.3.3

Mark a route as successfully used

SPEC COMPLIANCE NOTES:
- ✅ Resets failure counter and updates last-used timestamp after successful forwarding
- ✅ Operates on currently selected best route entry to keep metrics coherent
- ⚠️ Multi-entry route table means only first entry updated; others remain untouched DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- destination16: number
  Network address of the destination
Returns void
- Defined in src/zigbee-stack/nwk-handler.ts:450

nextRouteRequestId

nextRouteRequestId(): number
Get next route request ID. HOT PATH: Optimized counter increment

Returns number
Incremented route request ID (wraps at 255)
- Defined in src/zigbee-stack/nwk-handler.ts:151

nextSeqNum

nextSeqNum(): number
Get next NWK sequence number. HOT PATH: Optimized counter increment

Returns number
Incremented NWK sequence number (wraps at 255)
- Defined in src/zigbee-stack/nwk-handler.ts:139

processCommand

processCommand(
    data: Buffer,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): Promise<void>
05-3474-23 #3.4 (NWK command processing)

SPEC COMPLIANCE NOTES:
- ✅ Dispatches all mandatory NWK commands for coordinator role (ROUTE_REQ/REPLY, NWK_STATUS, LEAVE, LINK_STATUS, etc.)
- ✅ Maintains offset propagation between handlers to consume payload sequentially
- ✅ Logs unsupported command IDs per spec recommendation to ignore silently (kept as warning for diagnostics)
- ⚠️ Commissioning, Link Power Delta, ED Timeout handling partially implemented (documented TODOs) DEVICE SCOPE: Coordinator, routers (N/A), end devices (N/A)
Parameters
- data: Buffer
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns Promise<void>
- Defined in src/zigbee-stack/nwk-handler.ts:716

processCommissioningRequest

processCommissioningRequest(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): Promise<number>
05-3474-23 #3.4.14 Optional

SPEC COMPLIANCE NOTES:
- ✅ Correctly decodes assocType and capabilities
- ⚠️ TODO: TLVs not decoded (may contain critical R23+ commissioning info)
- ✅ Determines initial join vs rejoin from assocType: - 0x00 = Initial Join ✅ - 0x01 = Rejoin ✅
- ✅ Determines neighbor by comparing MAC and NWK source addresses
- ✅ Calls context associate with appropriate parameters
- ✅ Sends COMMISSIONING_RESPONSE with status and address
- ✅ Sends TRANSPORT_KEY_NWK on SUCCESS when required
- ⚠️ MISSING: No validation of commissioning TLVs - TLVs may contain security parameters - Should validate and process these
- ⚠️ SPEC NOTE: Comment about sending Remove Device CMD to deny join - Alternative to normal rejection mechanism - Not implemented here
COMMISSIONING vs NORMAL JOIN:
- Commissioning is R23+ feature for network commissioning
- May have different security requirements than legacy join
- TLV support is critical for full R23 compliance DEVICE SCOPE: Coordinator
Parameters
- data: Buffer
  Command data
- offset: number
  Current offset in data
- macHeader: MACHeader
  MAC header
- nwkHeader: ZigbeeNWKHeader
  NWK header
Returns Promise<number>
New offset after processing
- Defined in src/zigbee-stack/nwk-handler.ts:1946

processCommissioningResponse

processCommissioningResponse(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.15 (Commissioning Response) — Optional in R23

SPEC COMPLIANCE NOTES:
- ✅ Extracts assigned address and status value per Table 3-22
- ✅ Logs success vs failure for commissioning diagnostics
- ⚠️ TODO: Process optional TLVs (required for full Zigbee Direct compliance) DEVICE SCOPE: Routers (N/A), end devices (N/A)
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns number
- Defined in src/zigbee-stack/nwk-handler.ts:2006

processEdTimeoutRequest

processEdTimeoutRequest(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): Promise<number>
05-3474-23 #3.4.11

SPEC COMPLIANCE:
- ✅ Decodes requested timeout index and configuration octet per spec Table 3-54
- ✅ Validates timeout against END_DEVICE_TIMEOUT_TABLE and device presence before accepting
- ✅ Updates StackContext end-device timeout metadata and responds with status codes (SUCCESS/INCORRECT_VALUE/UNSUPPORTED_FEATURE)
- ⚠️ Still lacks parent policy enforcement (e.g., max timeout per device class)
- ❌ NOT IMPLEMENTED: Keep-alive scheduling or timeout expiration handling
- ❌ NOT IMPLEMENTED: TLV processing for R23 extensions DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns Promise<number>
- Defined in src/zigbee-stack/nwk-handler.ts:1755

processEdTimeoutResponse

processEdTimeoutResponse(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.12

SPEC COMPLIANCE:
- ✅ Correctly decodes status (SUCCESS, INCORRECT_VALUE, UNSUPPORTED_FEATURE)
- ✅ Decodes parent info (keepalive support, power negotiation)
- ✅ Logs timeout response information
- ❌ NOT IMPLEMENTED: Action on response (only logs)
- ❌ NOT IMPLEMENTED: TLV support (R23) DEVICE SCOPE: End devices (N/A)
NOTE: Coordinator typically doesn't receive this (sent to end devices)
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns number
- Defined in src/zigbee-stack/nwk-handler.ts:1808

processLeave

processLeave(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): Promise<number>
05-3474-23 #3.4.4 (Leave command)

SPEC COMPLIANCE NOTES:
- ✅ Parses removeChildren/request/rejoin flags from options byte (Table 3-16)
- ✅ Invokes disassociate when device signals final leave (request=false & rejoin=false)
- ⚠️ removeChildren flag purposely ignored (deprecated) DEVICE SCOPE: Coordinator, routers (N/A), end devices (N/A)
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns Promise<number>
- Defined in src/zigbee-stack/nwk-handler.ts:1165

processLinkPwrDelta

processLinkPwrDelta(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.13

SPEC COMPLIANCE:
- ✅ Decodes transmit power delta
- ✅ Logs power delta information
- ✅ Extracts nested TLVs (if present)
- ❌ NOT IMPLEMENTED: Power adjustment action
- ❌ NOT IMPLEMENTED: Feedback mechanism
- ❌ NOT IMPLEMENTED: R23 TLV processing DEVICE SCOPE: Coordinator, routers (N/A)
IMPACT: Receives command but doesn't adjust transmit power
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns number
- Defined in src/zigbee-stack/nwk-handler.ts:1880

processLinkStatus

processLinkStatus(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.8

SPEC COMPLIANCE NOTES:
- ✅ Correctly decodes options byte, link count, and link entries
- ✅ Parses firstFrame and lastFrame flags for multi-frame support
- ✅ Extracts linkCount from CMD_LINK_OPTION_COUNT_MASK
- ✅ Each link entry has: address, incomingCost, outgoingCost
- ✅ Marks device as neighbor if link to coordinator is reported
- ⚠️ SOURCE ROUTE CREATION FROM LINK STATUS: - Creates source route entry for each neighbor ✅ - Uses incomingCost as pathCost (link quality from neighbor's perspective) ✅ - For coordinator link: creates empty relay list (direct route) ✅ - For other links: creates route through that address ✅
- ✅ Updates existing routes if already present (by matching relay list)
- ✅ Resets failureCount on route update (fresh link status = healthy link)
- ⚠️ SPEC QUESTION: Using link status to build source routes - Spec #3.4.8 describes link status for neighbor table maintenance - Using it to build source routes is an implementation optimization - This may not be fully spec-compliant but is pragmatic
- ⚠️ Neighbor table maintenance is purposely not implemented due to "unlimited" table size on host - No neighbor table present, only a flag in device table - This is a significant spec deviation
- ⚠️ COST CALCULATION: Uses incoming cost directly as path cost - This may underestimate total path cost for multi-hop routes - Should consider accumulated path cost through intermediaries DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- data: Buffer
  Command data
- offset: number
  Current offset in data
- macHeader: MACHeader
  MAC header
- nwkHeader: ZigbeeNWKHeader
  NWK header
Returns number
New offset after processing
- Defined in src/zigbee-stack/nwk-handler.ts:1490

processRejoinReq

processRejoinReq(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): Promise<number>
05-3474-23 #3.4.6 Optional

SPEC COMPLIANCE NOTES:
- ✅ Correctly decodes capabilities byte
- ✅ Determines rejoin type based on frameControl.security: - security=false: Trust Center Rejoin (unsecured) - security=true: NWK rejoin (secured with NWK key)
- ⚠️ TRUST CENTER REJOIN HANDLING: - Checks if device is known and authorized ✅ - Denies rejoin if device unknown or unauthorized ✅ - SPEC WARNING in comment about unsecured packets from neighbors "Unsecured Packets at the network layer claiming to be from existing neighbors... must not rewrite legitimate data in nwkNeighborTable" This is a critical security requirement ✅
- ✅ Centralized Trust Center enforces coordinator EUI64; distributed/uninitialized modes not supported here (N/A)
- ✅ Calls context associate with correct parameters: - initialJoin=false (this is a rejoin) ✅ - neighbor determined by comparing MAC and NWK source ✅ - denyOverride based on security analysis ✅
- ✅ Sends REJOIN_RESP with assigned address and status
- ✅ Re-distributes current NWK key when rejoin requires key update
- ✅ Does not require VERIFY_KEY after rejoin per spec note
SECURITY CONCERNS:
- Unsecured rejoin handling is critical for security
- Must validate device authorization before accepting
- Missing apsTrustCenterAddress validation is a security gap DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- data: Buffer
  Command data
- offset: number
  Current offset in data
- macHeader: MACHeader
  MAC header
- nwkHeader: ZigbeeNWKHeader
  NWK header
Returns Promise<number>
New offset after processing
- Defined in src/zigbee-stack/nwk-handler.ts:1321

processRejoinResp

processRejoinResp(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.7

Optional

SPEC COMPLIANCE NOTES:
- ✅ Parses status and new short address per Table 3-19
- ✅ Logs success/failure for Trust Center auditing
- ⚠️ Does not currently update device tables; caller expected to handle
- ⚠️ TLV extensions (R23) not parsed yet DEVICE SCOPE: Routers (N/A), end devices (N/A)
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns number
- Defined in src/zigbee-stack/nwk-handler.ts:1404

processReport

processReport(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.9 (deprecated in R23)

SPEC COMPLIANCE:
- ✅ Correctly decodes options, EPID, updateID, panID
- ✅ Handles PAN ID conflict reports
- ✅ Logs report information
- ❌ NOT IMPLEMENTED: Channel update action
- ❌ NOT IMPLEMENTED: Network update propagation
- ❌ NOT IMPLEMENTED: PAN ID conflict resolution
- ❌ NOT IMPLEMENTED: TLV support (R23) DEVICE SCOPE: Coordinator, routers (N/A)
NOTE: Deprecated in R23, should no longer be sent by R23 devices IMPACT: Coordinator doesn't act on network reports
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns number
- Defined in src/zigbee-stack/nwk-handler.ts:1666

processRouteRecord

processRouteRecord(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.5

SPEC COMPLIANCE NOTES:
- ✅ Correctly decodes relayCount and relay addresses
- ✅ Stores source route in sourceRouteTable
- ✅ Creates source route entry with relays and path cost (relayCount + 1)
- ✅ Handles missing source16 by looking up via source64
- ✅ Checks for duplicate routes before adding (hasSourceRoute)
- ✅ ROUTE_RECORD provides path from source to coordinator - Relay list is in order from source toward coordinator ✅ - Path cost calculation (relayCount + 1) is correct ✅
- ✅ Validates source16 is defined before adding to table
- ✅ Stores relay addresses in correct order for source routing
IMPORTANT: Route records are sent by devices to establish reverse path to concentrator This is correct for coordinator acting as concentrator. DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- data: Buffer
  Command data
- offset: number
  Current offset in data
- macHeader: MACHeader
  MAC header
- nwkHeader: ZigbeeNWKHeader
  NWK header
Returns number
New offset after processing
- Defined in src/zigbee-stack/nwk-handler.ts:1243

processRouteReply

processRouteReply(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.2 (Route Reply)

SPEC COMPLIANCE NOTES:
- ✅ Decodes originator/responder addresses (short and extended) per options mask
- ✅ Reconstructs relay path including MAC next hop when coordinator originates discovery
- ✅ Normalizes zero path cost to hop-derived value to satisfy spec requirement (>0)
- ⚠️ TLVs and status-field failure indicators remain TODO DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns number
- Defined in src/zigbee-stack/nwk-handler.ts:906

processRouteReq

processRouteReq(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): Promise<number>
05-3474-23 #3.4.1 (Route Request)

SPEC COMPLIANCE NOTES:
- ✅ Decodes options, destination, and many-to-one fields per Table 3-12
- ✅ Sends ROUTE_REPLY when coordinator is destination (spec #3.6.3.5.2 requirement for concentrators)
- ✅ Preserves destination64 when provided to maintain IEEE correlation
- ⚠️ Path cost not incremented (acceptable for terminal node)
- ⚠️ Route discovery table not implemented (coordinator does not forward requests) DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- data: Buffer
  Command data
- offset: number
  Current offset in data
- macHeader: MACHeader
  MAC header
- nwkHeader: ZigbeeNWKHeader
  NWK header
Returns Promise<number>
New offset after processing
- Defined in src/zigbee-stack/nwk-handler.ts:814

processStatus

processStatus(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): Promise<number>
05-3474-23 #3.4.3

SPEC COMPLIANCE:
- ✅ Correctly decodes status code
- ✅ Handles destination16 parameter for routing failures
- ✅ Marks route as failed and schedules MTORR recovery
- ✅ Logs network status issues for diagnostics
- ❌ NOT IMPLEMENTED: TLV processing (R23)
- ✅ Issues REJOIN_RESP with address-conflict status to prompt device reassignment DEVICE SCOPE: Coordinator, routers (N/A), end devices (N/A)
IMPACT: Receives status but minimal action beyond route marking
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns Promise<number>
- Defined in src/zigbee-stack/nwk-handler.ts:1065

processUpdate

processUpdate(
    data: Buffer,
    offset: number,
    macHeader: MACHeader,
    nwkHeader: ZigbeeNWKHeader,
): number
05-3474-23 #3.4.10

SPEC COMPLIANCE:
- ✅ Correctly decodes options, EPID, updateID, panID
- ✅ Handles PAN update information
- ✅ Logs update information
- ❌ NOT IMPLEMENTED: Channel update if updateID is newer
- ❌ NOT IMPLEMENTED: Network parameter updates
- ❌ NOT IMPLEMENTED: Update propagation
- ❌ NOT IMPLEMENTED: TLV support (R23) DEVICE SCOPE: Routers (N/A), end devices (N/A)
Parameters
- data: Buffer
- offset: number
- macHeader: MACHeader
- nwkHeader: ZigbeeNWKHeader
Returns number
- Defined in src/zigbee-stack/nwk-handler.ts:1710

sendCommand

sendCommand(
    cmdId: ZigbeeNWKCommandId,
    finalPayload: Buffer,
    nwkSecurity: boolean,
    nwkSource16: number,
    nwkDest16: number,
    nwkDest64: bigint | undefined,
    nwkRadius: number,
): Promise<boolean>
05-3474-23 #3.4 (NWK command frames)

SPEC COMPLIANCE NOTES:
- ✅ Prepends Zigbee NWK header and optional security per caller (spec Table 3-5)
- ✅ Applies source routing when available via findBestSourceRoute (spec #3.6.3.3)
- ✅ Maps NWK destination to MAC destination with broadcast handling
- ⚠️ Relies on caller to ensure command-specific payload validity (e.g., TLVs) DEVICE SCOPE: Coordinator, routers (N/A), end devices (N/A)
Parameters
- cmdId: ZigbeeNWKCommandId
  Command identifier (first byte of payload)
- finalPayload: Buffer
  Fully encoded NWK command payload (including cmdId)
- nwkSecurity: boolean
  Whether to enable NWK security header
- nwkSource16: number
  Source network address for header
- nwkDest16: number
  Destination network address
- nwkDest64: bigint | undefined
  Optional destination IEEE address (for concentrator routing)
- nwkRadius: number
  Initial radius/TTL
Returns Promise<boolean>
True if success sending (or indirect transmission)
- Defined in src/zigbee-stack/nwk-handler.ts:597

sendCommissioningResponse

sendCommissioningResponse(
    requestSource16: number,
    newAddress16: number,
    status: number,
): Promise<boolean>
05-3474-23 #3.4.15 (Commissioning Response) — Optional in R23

SPEC COMPLIANCE NOTES:
- ✅ Sends commissioning response with STATUS + new address fields as defined in Table 3-22
- ✅ Uses NWK security=false (spec permits unsecured when join not completed)
- ✅ Applies default radius (CONFIG_NWK_MAX_HOPS) for reachability
- ⚠️ TLV payload not supported (TODO) DEVICE SCOPE: Coordinator
Parameters
- requestSource16: number
  Destination device
- newAddress16: number
  Assigned address echoed back
- status: number
  Commissioning status
Returns Promise<boolean>
True if success sending (or indirect transmission)
- Defined in src/zigbee-stack/nwk-handler.ts:2046

sendEdTimeoutResponse

sendEdTimeoutResponse(
    requestDest16: number,
    requestedTimeout: number,
    statusOverride?: number,
    parentInfoOverride?: number,
): Promise<boolean>
05-3474-23 #3.4.12

SPEC COMPLIANCE:
- ✅ Populates status field with SUCCESS/INCORRECT_VALUE/UNSUPPORTED_FEATURE based on request validation
- ✅ Sends parent information bitmap indicating keep-alive support (defaults to DATA_POLL + REQUEST + POWER_NEGOTIATION)
- ✅ Applies NWK security and unicasts to requester as required
- ❌ NOT IMPLEMENTED: TLV extensions (R23) DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- requestDest16: number
- requestedTimeout: number
- OptionalstatusOverride: number
- OptionalparentInfoOverride: number
Returns Promise<boolean>
- Defined in src/zigbee-stack/nwk-handler.ts:1839

sendLeave

sendLeave(destination16: number, rejoin: boolean): Promise<boolean>
05-3474-23 #3.4.4 (Leave command)

SPEC COMPLIANCE NOTES:
- ✅ Sets request bit (bit6) and optional rejoin bit based on caller input
- ✅ Forces removeChildren=0 to avoid unintended network disruption (spec allows but not typical for TC)
- ✅ Applies NWK security and unicasts to destination per coordinator requirements DEVICE SCOPE: Coordinator, routers (N/A), end devices (N/A)
Parameters
- destination16: number
  Target network address
- rejoin: boolean
  Whether device should rejoin after leave
Returns Promise<boolean>
True if success sending (or indirect transmission)
- Defined in src/zigbee-stack/nwk-handler.ts:1198

sendLinkStatus

sendLinkStatus(links: ZigbeeNWKLinkStatus[]): Promise<void>
05-3474-23 #3.4.8 (Link Status command)

SPEC COMPLIANCE NOTES:
- ✅ Fragments link list across multiple frames respecting MAX_PAYLOAD (27 entries per frame)
- ✅ Sets FIRST/LAST frame bits per Table 3-20 and repeats last link between frames as required
- ✅ Encodes incoming/outgoing cost nibble per spec definition
- ⚠️ Uses coordinator broadcast radius=1 as optimization (spec allows broader radius) DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- links: ZigbeeNWKLinkStatus[]
  Link status entries sorted ascending by address
Returns Promise<void>
- Defined in src/zigbee-stack/nwk-handler.ts:1589

sendPeriodicManyToOneRouteRequest

sendPeriodicManyToOneRouteRequest(): Promise<void>
05-3474-23 #3.6.3.5.2 (Many-to-One Route Discovery)

SPEC COMPLIANCE NOTES:
- ✅ Issues ROUTE_REQUEST with Many-to-One flag when concentrator timer elapses
- ✅ Enforces minimum spacing (CONFIG_NWK_CONCENTRATOR_MIN_TIME) to prevent flooding per spec guidance
- ✅ Uses WITH_SOURCE_ROUTING mode to advertise concentrator capability DEVICE SCOPE: Coordinator, routers (N/A)
Returns Promise<void>
- Defined in src/zigbee-stack/nwk-handler.ts:232

sendPeriodicZigbeeNWKLinkStatus

sendPeriodicZigbeeNWKLinkStatus(ignoreStale?: boolean): Promise<void>
05-3474-23 #3.4.8 (Link Status command)

SPEC COMPLIANCE NOTES:
- ✅ Sends periodic LINK_STATUS commands at 15s interval with jitter per spec guidance for link cost maintenance
- ✅ Derives incoming/outgoing cost from neighbor LQA and routing metrics (spec Table 3-20)
- ✅ Resets timer using refresh() to maintain continuous reporting while handler active
- ⚠️ Aggregated cost calculation includes implementation-specific LQA penalty (documented)
- ✅ Enforces CONFIG_NWK_ROUTER_AGE_LIMIT by zeroing costs after consecutive misses per spec DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- ignoreStale: boolean = false
Returns Promise<void>
- Defined in src/zigbee-stack/nwk-handler.ts:170

sendRejoinResp

sendRejoinResp(
    requestSource16: number,
    newAddress16: number,
    status: number,
): Promise<boolean>
05-3474-23 #3.4.7 (Rejoin Response)

SPEC COMPLIANCE NOTES:
- ✅ Returns new short address and status per Table 3-19
- ✅ Sends NWK-secured unicast response when NWK security is enabled
- ⚠️ Does not attach optional TLV extensions DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- requestSource16: number
  Requestor network address
- newAddress16: number
  Assigned network address
- status: number
  Rejoin status (MACAssociationStatus or NWK status)
Returns Promise<boolean>
True if success sending (or indirect transmission)
- Defined in src/zigbee-stack/nwk-handler.ts:1440

sendRouteReply

sendRouteReply(
    requestDest1stHop16: number,
    requestRadius: number,
    requestId: number,
    originator16: number,
    responder16: number,
    originator64?: bigint,
    responder64?: bigint,
): Promise<boolean>
05-3474-23 #3.4.2 / #3.6.4.5.2 (Route Reply)

SPEC COMPLIANCE NOTES:
- ✅ Encodes IEEE address presence bits and includes optional fields
- ✅ Sets path cost to 1 hop when coordinator responds directly
- ✅ Unicasts reply via first hop recorded in request MAC header
- ⚠️ TLV payload not encoded (optional R23 extension) DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- requestDest1stHop16: number
  SHALL be set to the network address of the first hop in the path back to the originator of the corresponding route request command frame
- requestRadius: number
- requestId: number
  8-bit sequence number of the route request to which this frame is a reply
- originator16: number
  SHALL contain the 16-bit network address of the originator of the route request command frame to which this frame is a reply
- responder16: number
  SHALL always be the same as the value in the destination address field of the corresponding route request command frame
- Optionaloriginator64: bigint
  SHALL be 8 octets in length and SHALL contain the 64-bit address of the originator of the route request command frame to which this frame is a reply. This field SHALL only be present if the originator IEEE address sub-field of the command options field has a value of 1.
- Optionalresponder64: bigint
  SHALL be 8 octets in length and SHALL contain the 64-bit address of the destination of the route request command frame to which this frame is a reply. This field SHALL only be present if the responder IEEE address sub-field of the command options field has a value of 1.
Returns Promise<boolean>
- Defined in src/zigbee-stack/nwk-handler.ts:1001

sendRouteReq

sendRouteReq(
    manyToOne: ZigbeeNWKManyToOne,
    destination16: number,
    destination64?: bigint,
): Promise<boolean>
05-3474-23 #3.4.1 (Route Request)

SPEC COMPLIANCE NOTES:
- ✅ Encodes options bits for many-to-one and DEST_EXT addressing
- ✅ Uses modulo-256 route request identifier (nextRouteRequestId)
- ✅ Broadcasts discovery (dest=BCAST_DEFAULT) when acting as concentrator
- ⚠️ TLV payload not supported (optional R23 extension) DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- manyToOne: ZigbeeNWKManyToOne
- destination16: number
  intended destination of the route request command frame
- Optionaldestination64: bigint
  SHOULD always be added if it is known
Returns Promise<boolean>
- Defined in src/zigbee-stack/nwk-handler.ts:867

sendStatus

sendStatus(
    requestSource16: number,
    status: ZigbeeNWKStatus,
    destination?: number,
): Promise<boolean>
05-3474-23 #3.4.3

SPEC COMPLIANCE:
- ✅ Sends to appropriate destination (broadcast or unicast)
- ✅ Includes error codes (NO_ROUTE_AVAILABLE, LINK_FAILURE, etc.)
- ✅ No security applied (per spec)
- ✅ Optional destination16 for routing failures/address conflicts DEVICE SCOPE: Coordinator, routers (N/A)
Parameters
- requestSource16: number
- status: ZigbeeNWKStatus
- Optionaldestination: number
  Destination address (only if status is LINK_FAILURE or ADDRESS_CONFLICT)
  
  in case of a routing failure, it SHALL contain the destination address from the data frame that encountered the failure
  
  in case of an address conflict, it SHALL contain the offending network address.
Returns Promise<boolean>
- Defined in src/zigbee-stack/nwk-handler.ts:1132

start

start(): Promise<void>
Returns Promise<void>
- Defined in src/zigbee-stack/nwk-handler.ts:113

stop

stop(): void
Returns void
- Defined in src/zigbee-stack/nwk-handler.ts:125

Class NWKHandler

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns NWKHandler

Methods

createSourceRouteEntry

Parameters

Returns SourceRouteTableEntry

findBestSourceRoute

Parameters

Returns [relayIndex: number, relayAddresses: number[], pathCost: number]

hasSourceRoute

Parameters

Returns boolean

markRouteFailure

Parameters

Returns void

markRouteSuccess

Parameters

Returns void

nextRouteRequestId

Returns number

nextSeqNum

Returns number

processCommand

Parameters

Returns Promise<void>

processCommissioningRequest

Parameters

Returns Promise<number>

processCommissioningResponse

Parameters

Returns number

processEdTimeoutRequest

Parameters

Returns Promise<number>

processEdTimeoutResponse

Parameters

Returns number

processLeave

Parameters

Returns Promise<number>

processLinkPwrDelta

Parameters

Returns number

processLinkStatus

Parameters

Returns number

processRejoinReq

Parameters

Returns Promise<number>

processRejoinResp

Parameters

Returns number

processReport

Parameters

Returns number

processRouteRecord

Parameters

Returns number

processRouteReply

Parameters

Returns number

processRouteReq

Parameters

Returns Promise<number>

processStatus

Parameters

Returns Promise<number>

processUpdate

Parameters

Returns number

sendCommand

Parameters

Returns Promise<boolean>

sendCommissioningResponse