@matter/thread-br-client 0.0.1

package/src/tlv/diag/NetworkData.ts

@@ -0,0 +1,241 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ThreadDiagError } from "../../diagnostic/errors.js";
+
+/**
+ * Decoded Thread Network Data (Network Diagnostic TLV type 7).
+ *
+ * Network Data is itself a nested TLV structure. Layout per Thread spec §5.13
+ * and OpenThread `src/core/thread/network_data_tlvs.hpp`:
+ *
+ *   Each TLV: [type:1][length:1][value:length]
+ *     - The type byte packs the stable flag in bit 0: typeByte = (type << 1) | stable.
+ *     - Network Data TLVs do NOT use the MeshCoP 0xFF extended-length escape, so
+ *       this stream needs its own walker rather than `BasicTlv.walk`.
+ *
+ *   Top-level TLV types: Has-Route(0), Prefix(1), Border-Router(2), 6LoWPAN-ID(3),
+ *   Commissioning(4), Service(5), Server(6).
+ *
+ *   Prefix TLV value (`PrefixTlv`):
+ *     [0]      uint8     Domain ID
+ *     [1]      uint8     Prefix Length (bits)
+ *     [2..]    bytes     Prefix, ceil(prefixLength/8) bytes
+ *     [..]     TLVs      Sub-TLVs (Has-Route, Border-Router, 6LoWPAN-ID)
+ *
+ *   Has-Route TLV value: array of 3-byte entries (`HasRouteEntry`):
+ *     [0..1]   uint16-be RLOC16
+ *     [2]      uint8     flags (preference in bits 7..6)
+ *
+ *   Border-Router TLV value: array of 4-byte entries (`BorderRouterEntry`):
+ *     [0..1]   uint16-be RLOC16
+ *     [2..3]   uint16-be flags (P/S/D/C/R/O/N/DP and preference)
+ *
+ *   6LoWPAN-ID (Context) TLV value (`ContextTlv`):
+ *     [0]      uint8     compress flag (bit 4) | Context ID (bits 3..0)
+ *     [1]      uint8     Context Length (bits)
+ *
+ *   Service TLV value (`ServiceTlv`):
+ *     [0]      uint8     T flag (bit 7) | reserved | Service ID (bits 3..0)
+ *     if T == 0: [1..4] uint32-be Enterprise Number; else Enterprise Number is the
+ *                Thread reserved value (0xFFFFFFFF semantically; encoded by T flag).
+ *     [n]      uint8     Service Data Length
+ *     [..]     bytes     Service Data
+ *     [..]     TLVs      Server sub-TLVs
+ *
+ *   Server TLV value (`ServerTlv`):
+ *     [0..1]   uint16-be RLOC16
+ *     [2..]    bytes     Server Data
+ *
+ * Anything not understood is preserved as a raw `{ type, stable, value }` entry,
+ * and `raw` always holds the full original bytes so no data is lost.
+ */
+
+export interface NetworkDataEntry {
+    type: number;
+    stable: boolean;
+    value: Uint8Array;
+}
+
+export interface HasRouteEntry {
+    rloc16: number;
+    preference: number;
+}
+
+export interface BorderRouterEntry {
+    rloc16: number;
+    flags: number;
+}
+
+export interface NetworkDataPrefix {
+    domainId: number;
+    prefixLength: number;
+    prefix: Uint8Array;
+    hasRoutes: HasRouteEntry[];
+    borderRouters: BorderRouterEntry[];
+}
+
+export interface NetworkDataServer {
+    rloc16: number;
+    serverData: Uint8Array;
+}
+
+export interface NetworkDataService {
+    serviceId: number;
+    threadEnterprise: boolean;
+    enterpriseNumber?: number;
+    serviceData: Uint8Array;
+    servers: NetworkDataServer[];
+}
+
+export interface ThreadNetworkData {
+    entries: NetworkDataEntry[];
+    prefixes: NetworkDataPrefix[];
+    services: NetworkDataService[];
+    raw: Uint8Array;
+}
+
+const enum NetworkDataTlvType {
+    HasRoute = 0,
+    Prefix = 1,
+    BorderRouter = 2,
+    Context = 3,
+    Commissioning = 4,
+    Service = 5,
+    Server = 6,
+}
+
+const HAS_ROUTE_ENTRY_BYTES = 3;
+const BORDER_ROUTER_ENTRY_BYTES = 4;
+const HAS_ROUTE_PREFERENCE_SHIFT = 6;
+const SERVICE_THREAD_FLAG = 0x80;
+const SERVICE_ID_MASK = 0x0f;
+
+function walkTlvs(blob: Uint8Array): NetworkDataEntry[] {
+    const out = new Array<NetworkDataEntry>();
+    let offset = 0;
+    while (offset < blob.length) {
+        if (offset + 2 > blob.length) {
+            throw new ThreadDiagError(`Truncated Network Data TLV header at offset ${offset}`);
+        }
+        const typeByte = blob[offset];
+        const length = blob[offset + 1];
+        const valueStart = offset + 2;
+        const valueEnd = valueStart + length;
+        if (valueEnd > blob.length) {
+            throw new ThreadDiagError(
+                `Truncated Network Data TLV value at offset ${offset} (type=${typeByte >> 1}, length=${length})`,
+            );
+        }
+        out.push({ type: typeByte >> 1, stable: (typeByte & 0x1) !== 0, value: blob.slice(valueStart, valueEnd) });
+        offset = valueEnd;
+    }
+    return out;
+}
+
+function parseHasRoutes(value: Uint8Array): HasRouteEntry[] {
+    const out = new Array<HasRouteEntry>();
+    for (let i = 0; i + HAS_ROUTE_ENTRY_BYTES <= value.length; i += HAS_ROUTE_ENTRY_BYTES) {
+        out.push({
+            rloc16: (value[i] << 8) | value[i + 1],
+            preference: value[i + 2] >> HAS_ROUTE_PREFERENCE_SHIFT,
+        });
+    }
+    return out;
+}
+
+function parseBorderRouters(value: Uint8Array): BorderRouterEntry[] {
+    const out = new Array<BorderRouterEntry>();
+    for (let i = 0; i + BORDER_ROUTER_ENTRY_BYTES <= value.length; i += BORDER_ROUTER_ENTRY_BYTES) {
+        out.push({
+            rloc16: (value[i] << 8) | value[i + 1],
+            flags: (value[i + 2] << 8) | value[i + 3],
+        });
+    }
+    return out;
+}
+
+function parsePrefix(value: Uint8Array): NetworkDataPrefix {
+    const domainId = value[0];
+    const prefixLength = value[1];
+    const prefixBytes = Math.ceil(prefixLength / 8);
+    const prefix = value.slice(2, 2 + prefixBytes);
+
+    const hasRoutes = new Array<HasRouteEntry>();
+    const borderRouters = new Array<BorderRouterEntry>();
+    for (const sub of walkTlvs(value.subarray(2 + prefixBytes))) {
+        if (sub.type === NetworkDataTlvType.HasRoute) {
+            hasRoutes.push(...parseHasRoutes(sub.value));
+        } else if (sub.type === NetworkDataTlvType.BorderRouter) {
+            borderRouters.push(...parseBorderRouters(sub.value));
+        }
+    }
+    return { domainId, prefixLength, prefix, hasRoutes, borderRouters };
+}
+
+function parseService(value: Uint8Array): NetworkDataService {
+    const flags = value[0];
+    const threadEnterprise = (flags & SERVICE_THREAD_FLAG) !== 0;
+    const serviceId = flags & SERVICE_ID_MASK;
+
+    let offset = 1;
+    let enterpriseNumber: number | undefined;
+    if (!threadEnterprise) {
+        if (value.length < 5) {
+            throw new ThreadDiagError(`Truncated Service TLV: ${value.length} bytes, need 5 for enterprise number`);
+        }
+        enterpriseNumber = ((value[1] << 24) | (value[2] << 16) | (value[3] << 8) | value[4]) >>> 0;
+        offset = 5;
+    }
+    if (offset >= value.length) {
+        throw new ThreadDiagError(`Truncated Service TLV: missing service data length at offset ${offset}`);
+    }
+    const serviceDataLength = value[offset];
+    offset += 1;
+    const serviceData = value.slice(offset, offset + serviceDataLength);
+    offset += serviceDataLength;
+
+    const servers = new Array<NetworkDataServer>();
+    for (const sub of walkTlvs(value.subarray(offset))) {
+        if (sub.type === NetworkDataTlvType.Server) {
+            if (sub.value.length < 2) continue;
+            servers.push({ rloc16: (sub.value[0] << 8) | sub.value[1], serverData: sub.value.slice(2) });
+        }
+    }
+    return { serviceId, threadEnterprise, enterpriseNumber, serviceData, servers };
+}
+
+export namespace NetworkData {
+    export function decode(value: Uint8Array): ThreadNetworkData {
+        const raw = value.slice();
+
+        let entries: NetworkDataEntry[];
+        try {
+            entries = walkTlvs(value);
+        } catch {
+            // A truncated top-level stream must not abort the whole node's diagnostic
+            // decode; `raw` preserves the bytes for any consumer that wants them.
+            return { entries: [], prefixes: [], services: [], raw };
+        }
+
+        const prefixes = new Array<NetworkDataPrefix>();
+        const services = new Array<NetworkDataService>();
+        for (const entry of entries) {
+            // Structured sub-TLV parsing is best-effort: a malformed inner Prefix/Service
+            // must not discard the top-level entry list or the always-present `raw`.
+            try {
+                if (entry.type === NetworkDataTlvType.Prefix) {
+                    prefixes.push(parsePrefix(entry.value));
+                } else if (entry.type === NetworkDataTlvType.Service) {
+                    services.push(parseService(entry.value));
+                }
+            } catch {
+                // Leave this entry as a raw `entries[]` item; `raw` preserves its bytes.
+            }
+        }
+        return { entries, prefixes, services, raw };
+    }
+}

package/src/tlv/diag/Primitives.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { ThreadDiagError } from "../../diagnostic/errors.js";
+
+/**
+ * Small fixed-size primitive Network Diagnostic TLVs.
+ *
+ * | TLV | Type | Layout |
+ * |-----|------|--------|
+ * | ExtMacAddress    | 0  | 8-byte EUI-64, network byte order |
+ * | Address16        | 1  | uint16 BE — RLOC16 |
+ * | BatteryLevel     | 14 | uint8 (0..100 percent) |
+ * | SupplyVoltage    | 15 | uint16 BE millivolts |
+ * | ChannelPages     | 17 | variable-length byte array of supported channel pages |
+ * | MaxChildTimeout  | 19 | uint32 BE seconds |
+ * | Eui64            | 23 | 8-byte EUI-64 (factory-assigned, distinct from ExtMacAddress) |
+ *
+ * Layouts mirror OpenThread `network_diagnostic_tlvs.hpp` typedefs and the
+ * `Client::GetNextDiagTlv` parser.
+ */
+
+function eui64Decode(value: Uint8Array, name: string): Uint8Array {
+    if (value.length !== 8) {
+        throw new ThreadDiagError(`${name} TLV must be 8 bytes, got ${value.length}`);
+    }
+    return value.slice();
+}
+
+function eui64Encode(addr: Uint8Array, name: string): Uint8Array {
+    if (addr.length !== 8) {
+        throw new InternalError(`${name} must be 8 bytes, got ${addr.length}`);
+    }
+    return addr.slice();
+}
+
+export namespace ExtMacAddress {
+    export function decode(value: Uint8Array): Uint8Array {
+        return eui64Decode(value, "ExtMacAddress");
+    }
+
+    export function encode(addr: Uint8Array): Uint8Array {
+        return eui64Encode(addr, "ExtMacAddress");
+    }
+}
+
+export namespace Eui64 {
+    export function decode(value: Uint8Array): Uint8Array {
+        return eui64Decode(value, "Eui64");
+    }
+
+    export function encode(addr: Uint8Array): Uint8Array {
+        return eui64Encode(addr, "Eui64");
+    }
+}
+
+export namespace Address16 {
+    export function decode(value: Uint8Array): number {
+        if (value.length !== 2) {
+            throw new ThreadDiagError(`Address16 TLV must be 2 bytes, got ${value.length}`);
+        }
+        return (value[0] << 8) | value[1];
+    }
+
+    export function encode(rloc16: number): Uint8Array {
+        if (!Number.isInteger(rloc16) || rloc16 < 0 || rloc16 > 0xffff) {
+            throw new InternalError(`Address16 out of range: ${rloc16}`);
+        }
+        return new Uint8Array([(rloc16 >> 8) & 0xff, rloc16 & 0xff]);
+    }
+}
+
+export namespace BatteryLevel {
+    export function decode(value: Uint8Array): number {
+        if (value.length !== 1) {
+            throw new ThreadDiagError(`BatteryLevel TLV must be 1 byte, got ${value.length}`);
+        }
+        return value[0];
+    }
+
+    export function encode(percent: number): Uint8Array {
+        if (!Number.isInteger(percent) || percent < 0 || percent > 0xff) {
+            throw new InternalError(`BatteryLevel out of range: ${percent}`);
+        }
+        return new Uint8Array([percent]);
+    }
+}
+
+export namespace SupplyVoltage {
+    export function decode(value: Uint8Array): number {
+        if (value.length !== 2) {
+            throw new ThreadDiagError(`SupplyVoltage TLV must be 2 bytes, got ${value.length}`);
+        }
+        return (value[0] << 8) | value[1];
+    }
+
+    export function encode(millivolts: number): Uint8Array {
+        if (!Number.isInteger(millivolts) || millivolts < 0 || millivolts > 0xffff) {
+            throw new InternalError(`SupplyVoltage out of range: ${millivolts}`);
+        }
+        return new Uint8Array([(millivolts >> 8) & 0xff, millivolts & 0xff]);
+    }
+}
+
+export namespace MaxChildTimeout {
+    export function decode(value: Uint8Array): number {
+        if (value.length !== 4) {
+            throw new ThreadDiagError(`MaxChildTimeout TLV must be 4 bytes, got ${value.length}`);
+        }
+        return ((value[0] << 24) | (value[1] << 16) | (value[2] << 8) | value[3]) >>> 0;
+    }
+
+    export function encode(seconds: number): Uint8Array {
+        if (!Number.isInteger(seconds) || seconds < 0 || seconds > 0xffffffff) {
+            throw new InternalError(`MaxChildTimeout out of range: ${seconds}`);
+        }
+        return new Uint8Array([
+            (seconds >>> 24) & 0xff,
+            (seconds >>> 16) & 0xff,
+            (seconds >>> 8) & 0xff,
+            seconds & 0xff,
+        ]);
+    }
+}
+
+export namespace ChannelPages {
+    export function decode(value: Uint8Array): number[] {
+        return Array.from(value);
+    }
+
+    export function encode(pages: ReadonlyArray<number>): Uint8Array {
+        const out = new Uint8Array(pages.length);
+        for (let i = 0; i < pages.length; i++) {
+            const p = pages[i];
+            if (!Number.isInteger(p) || p < 0 || p > 0xff) {
+                throw new InternalError(`ChannelPages entry out of range: ${p}`);
+            }
+            out[i] = p;
+        }
+        return out;
+    }
+}

package/src/tlv/diag/Route64.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { ThreadDiagError } from "../../diagnostic/errors.js";
+
+/**
+ * Decoded Route64 TLV (Network Diagnostic TLV type 5).
+ *
+ * Layout per OpenThread `src/core/thread/mle_tlvs.hpp` `RouteTlv` and
+ * `mle_types.hpp` `RouterIdMask`:
+ *
+ *   [0]     uint8     ID Sequence
+ *   [1..8]  bytes[8]  Router ID Mask, big-endian bit order: router 0 is the
+ *                     MSB of byte 0 (mask = 0x80 >> (id % 8)).
+ *   [9..]   uint8[N]  N route-data bytes, one per allocated router (in
+ *                     ascending router-id order).
+ *
+ * Each route-data byte:
+ *   bits 7..6 = link quality out (0..3)
+ *   bits 5..4 = link quality in  (0..3)
+ *   bits 3..0 = route cost       (0..15)
+ *
+ * Note: this is the short (1-byte-per-entry) form. OpenThread's
+ * `MLE_LONG_ROUTES` build-time option uses 1.5 bytes per entry — we have
+ * never observed it in real Thread 1.x deployments and it is not required
+ * for our default set.
+ */
+export interface Route64Entry {
+    routerId: number;
+    linkQualityIn: number;
+    linkQualityOut: number;
+    routeCost: number;
+}
+
+export interface Route64 {
+    idSequence: number;
+    entries: Route64Entry[];
+}
+
+const MASK_BYTES = 8;
+const HEADER_BYTES = 1 + MASK_BYTES;
+const MAX_ROUTER_ID = 62; // OpenThread `kMaxRouterId`.
+
+const LINK_QUALITY_OUT_MASK = 0xc0;
+const LINK_QUALITY_OUT_SHIFT = 6;
+const LINK_QUALITY_IN_MASK = 0x30;
+const LINK_QUALITY_IN_SHIFT = 4;
+const ROUTE_COST_MASK = 0x0f;
+
+function isRouterIdSet(mask: Uint8Array, routerId: number): boolean {
+    return (mask[routerId >> 3] & (0x80 >> (routerId & 0x7))) !== 0;
+}
+
+function setRouterIdBit(mask: Uint8Array, routerId: number): void {
+    mask[routerId >> 3] |= 0x80 >> (routerId & 0x7);
+}
+
+export namespace Route64 {
+    export function decode(value: Uint8Array): Route64 {
+        if (value.length < HEADER_BYTES) {
+            throw new ThreadDiagError(`Route64 TLV too short: ${value.length} bytes (need >=${HEADER_BYTES})`);
+        }
+        const idSequence = value[0];
+        const mask = value.subarray(1, HEADER_BYTES);
+
+        const allocatedIds = new Array<number>();
+        for (let id = 0; id <= MAX_ROUTER_ID; id++) {
+            if (isRouterIdSet(mask, id)) allocatedIds.push(id);
+        }
+
+        if (value.length !== HEADER_BYTES + allocatedIds.length) {
+            throw new ThreadDiagError(
+                `Route64 TLV size mismatch: ${value.length} bytes for ${allocatedIds.length} allocated routers`,
+            );
+        }
+
+        const entries = new Array<Route64Entry>();
+        for (let i = 0; i < allocatedIds.length; i++) {
+            const data = value[HEADER_BYTES + i];
+            entries.push({
+                routerId: allocatedIds[i],
+                linkQualityOut: (data & LINK_QUALITY_OUT_MASK) >> LINK_QUALITY_OUT_SHIFT,
+                linkQualityIn: (data & LINK_QUALITY_IN_MASK) >> LINK_QUALITY_IN_SHIFT,
+                routeCost: data & ROUTE_COST_MASK,
+            });
+        }
+        return { idSequence, entries };
+    }
+
+    export function encode(route: Route64): Uint8Array {
+        const sortedEntries = [...route.entries].sort((a, b) => a.routerId - b.routerId);
+
+        const out = new Uint8Array(HEADER_BYTES + sortedEntries.length);
+        out[0] = route.idSequence & 0xff;
+        const mask = out.subarray(1, HEADER_BYTES);
+
+        for (let i = 0; i < sortedEntries.length; i++) {
+            const e = sortedEntries[i];
+            if (!Number.isInteger(e.routerId) || e.routerId < 0 || e.routerId > MAX_ROUTER_ID) {
+                throw new InternalError(`Route64 router ID out of range: ${e.routerId}`);
+            }
+            if (i > 0 && sortedEntries[i - 1].routerId === e.routerId) {
+                throw new InternalError(`Route64 duplicate router ID: ${e.routerId}`);
+            }
+            setRouterIdBit(mask, e.routerId);
+
+            const lqOut = e.linkQualityOut & 0x3;
+            const lqIn = e.linkQualityIn & 0x3;
+            const cost = e.routeCost & 0xf;
+            out[HEADER_BYTES + i] = (lqOut << LINK_QUALITY_OUT_SHIFT) | (lqIn << LINK_QUALITY_IN_SHIFT) | cost;
+        }
+        return out;
+    }
+}

package/src/tlv/diag/RouterNeighbor.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One decoded Router Neighbor entry from Network Diagnostic TLV type 31.
+ *
+ * Per-entry layout from OpenThread `src/core/thread/net_diag_tlvs.hpp`
+ * `RouterNeighborTlvValue` (packed struct, ENTRY_BYTES = 24 bytes total):
+ *
+ *   [0]      uint8     mFlags         — bit 7 = kFlagsTrackErrRate
+ *   [1..2]   uint16 BE mRloc16
+ *   [3..10]  uint8[8]  mExtAddress
+ *   [11..12] uint16 BE mVersion
+ *   [13..16] uint32 BE mConnectionTime (seconds since link establishment)
+ *   [17]     uint8     mLinkMargin    (dB)
+ *   [18]     int8      mAverageRssi   (dBm; 127 = not available / unknown)
+ *   [19]     int8      mLastRssi      (dBm; 127 = not available / unknown)
+ *   [20..21] uint16 BE mFrameErrorRate   (0x0000=0%, 0xffff=100%; valid only when supportsErrorRate=true)
+ *   [22..23] uint16 BE mMessageErrorRate (0x0000=0%, 0xffff=100%; valid only when supportsErrorRate=true)
+ */
+export interface RouterNeighborEntry {
+    rloc16: number;
+    /** 8-byte IEEE EUI-64 extended address. */
+    extAddress: Uint8Array;
+    version: number;
+    /** Seconds elapsed since link establishment. */
+    connectionTime: number;
+    /** Link margin in dB. */
+    linkMargin: number;
+    /** Whether this node tracks frame/message error rates (mFlags bit 7). */
+    supportsErrorRate: boolean;
+    /** Average RSSI in dBm. 127 when not available or unknown. */
+    averageRssi: number;
+    /** RSSI of the last received frame in dBm. 127 when not available or unknown. */
+    lastRssi: number;
+    /** Frame error rate as a raw uint16 (0x0000=0%, 0xffff=100%). Valid when supportsErrorRate=true. */
+    frameErrorRate: number;
+    /** IPv6-message error rate as a raw uint16 (0x0000=0%, 0xffff=100%). Valid when supportsErrorRate=true. */
+    messageErrorRate: number;
+}
+
+// Per OpenThread `net_diag_tlvs.hpp` `RouterNeighborTlvValue` (24-byte packed struct).
+const ENTRY_BYTES = 24;
+const FLAGS_TRACK_ERR_RATE = 0x80; // kFlagsTrackErrRate = 1 << 7
+
+export namespace RouterNeighbor {
+    export function decode(value: Uint8Array): RouterNeighborEntry[] {
+        const entryCount = Math.floor(value.length / ENTRY_BYTES);
+        const entries = new Array<RouterNeighborEntry>();
+
+        for (let i = 0; i < entryCount; i++) {
+            const off = i * ENTRY_BYTES;
+            const flags = value[off];
+            const rloc16 = (value[off + 1] << 8) | value[off + 2];
+            const extAddress = value.slice(off + 3, off + 11);
+            const version = (value[off + 11] << 8) | value[off + 12];
+            const connectionTime =
+                ((value[off + 13] << 24) | (value[off + 14] << 16) | (value[off + 15] << 8) | value[off + 16]) >>> 0;
+            const linkMargin = value[off + 17];
+            // int8 signed decode: values >= 128 are negative (two's complement).
+            const averageRssi = value[off + 18] > 127 ? value[off + 18] - 256 : value[off + 18];
+            const lastRssi = value[off + 19] > 127 ? value[off + 19] - 256 : value[off + 19];
+            const frameErrorRate = (value[off + 20] << 8) | value[off + 21];
+            const messageErrorRate = (value[off + 22] << 8) | value[off + 23];
+
+            entries.push({
+                rloc16,
+                extAddress,
+                version,
+                connectionTime,
+                linkMargin,
+                supportsErrorRate: (flags & FLAGS_TRACK_ERR_RATE) !== 0,
+                averageRssi,
+                lastRssi,
+                frameErrorRate,
+                messageErrorRate,
+            });
+        }
+
+        return entries;
+    }
+}

package/src/tlv/diag/Timeout.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "@matter/general";
+import { ThreadDiagError } from "../../diagnostic/errors.js";
+
+/**
+ * Decoded Timeout TLV (Network Diagnostic TLV type 3).
+ *
+ * Big-endian uint32 — maximum polling time period (seconds) for SEDs.
+ * Source: OpenThread `network_diagnostic_tlvs.hpp` `TimeoutTlv` and
+ * `network_diagnostic.cpp` parser.
+ */
+export namespace Timeout {
+    export function decode(value: Uint8Array): number {
+        if (value.length !== 4) {
+            throw new ThreadDiagError(`Timeout TLV must be 4 bytes, got ${value.length}`);
+        }
+        return ((value[0] << 24) | (value[1] << 16) | (value[2] << 8) | value[3]) >>> 0;
+    }
+
+    export function encode(seconds: number): Uint8Array {
+        if (!Number.isInteger(seconds) || seconds < 0 || seconds > 0xffffffff) {
+            throw new InternalError(`Timeout TLV out of range: ${seconds}`);
+        }
+        return new Uint8Array([
+            (seconds >>> 24) & 0xff,
+            (seconds >>> 16) & 0xff,
+            (seconds >>> 8) & 0xff,
+            seconds & 0xff,
+        ]);
+    }
+}