Widen Node ID fields to allow for 16-bit Node Ids (#179)

Author: dfederm

.github/copilot-instructions.md

@@ -68,6 +68,7 @@ Implements the Z-Wave Serial API frame-level protocol (as defined by the Z-Wave
 - **`ZWaveSerialPortCoordinator`** — Manages the serial port, frame send/receive channels, ACK handshake, and retransmission.
 - **`Commands/`** — Each Serial API command (e.g. `SendData`, `GetInitData`, `SoftReset`) is a struct implementing `ICommand<T>` (defined in `Serial/Commands/ICommand.cs`). Commands that expect a callback implement `IRequestWithCallback<T>`.
 - **`CommandId` enum** — All Serial API function IDs.
+- **`CommandDataParsingHelpers`** — Internal shared utilities: `ParseCommandClasses` (CC byte list → `CommandClassInfo` records) and `ParseNodeBitmask` (bitmask → `HashSet<ushort>` node IDs).
 
 ### Command Classes Layer (`src/ZWave.CommandClasses/`)
 
@@ -82,7 +83,7 @@ Implements Z-Wave Command Classes (Z-Wave Application Specification). This proje
 
 - **`Driver`** — Entry point. Implements `IDriver`. Opens serial port, manages frame send/receive, processes unsolicited requests, coordinates request-response and callback flows.
 - **`Controller`** — Represents the Z-Wave USB controller. Runs identification sequence on startup.
-- **`Node`** — Represents a Z-Wave network node. Implements `INode`. Handles interviews and command class discovery.
+- **`Node`** — Represents a Z-Wave network node. Implements `INode`. Handles interviews and command class discovery. Node IDs are `ushort` throughout the codebase to support both classic (1–232) and Long Range (256+) nodes.
 
 ### Source Generators (`src/ZWave.BuildTools/`)
 
@@ -108,11 +109,12 @@ Uses `Microsoft.Extensions.Logging` with source-generated `[LoggerMessage]` attr
 - Tests use **MSTest** with the `MSTest.Sdk` project SDK and the **Microsoft.Testing.Platform** runner.
 - Tests run in parallel at method level.
 - Serial API command tests inherit from `CommandTestBase` and use `TestSendableCommand` / `TestReceivableCommand` helper methods that verify frame structure round-tripping.
+- `CommandDataParsingHelpersTests` covers the shared parsing helpers (`ParseCommandClasses`, `ParseNodeBitmask`).
 - Test files mirror the source structure: `src/ZWave.Serial.Tests/Commands/` contains tests for each serial command.
 
 ## Adding New Functionality
 
-**New Serial API Command**: Create a struct in `src/ZWave.Serial/Commands/` implementing `ICommand<T>` (and `IRequestWithCallback<T>` if it uses callbacks). Add the command ID to `CommandId` enum. Add tests in `src/ZWave.Serial.Tests/Commands/`.
+**New Serial API Command**: Create a struct in `src/ZWave.Serial/Commands/` implementing `ICommand<T>` (and `IRequestWithCallback<T>` if it uses callbacks). Add the command ID to `CommandId` enum. Add tests in `src/ZWave.Serial.Tests/Commands/`. Node ID parameters are `ushort`; cast to `(byte)nodeId` when writing to the buffer. Use `CommandDataParsingHelpers` for shared parsing (node bitmasks, command class lists).
 
 **New Command Class**: Create a class in `src/ZWave.CommandClasses/` inheriting `CommandClass<TEnum>`. Apply `[CommandClass(CommandClassId.X)]`. Define private inner structs for each command (Set/Get/Report) implementing `ICommand`. The source generator auto-registers it.
 

docs/architecture.md

@@ -99,6 +99,10 @@ Each Z-Wave Serial API function is represented as a struct. These map to the fun
 
 **`CommandId` enum** - All Serial API function IDs (e.g. `SendData = 0x13`, `GetInitData = 0x02`).
 
+**`CommandDataParsingHelpers`** (`Commands/CommandDataParsingHelpers.cs`) - Internal shared utilities for parsing common serial API response patterns:
+- `ParseCommandClasses` — Parses a CC byte list with the support/control mark into `CommandClassInfo` records.
+- `ParseNodeBitmask` — Parses a node ID bitmask (each bit = one node) into a `HashSet<ushort>`. Takes a `baseNodeId` parameter (1 for classic nodes, 256+ for LR nodes).
+
 **Communication patterns:**
 - **Fire-and-forget:** Host sends a REQ with no response expected (e.g. `SoftReset`, `SendDataAbort`, `WatchdogKick`)
 - **Request → Response:** Host sends a REQ, chip replies with a RES (e.g. `MemoryGetId`, `GetLibraryVersion`, `GetRoutingInfo`, `IsFailedNode`)
@@ -107,6 +111,8 @@ Each Z-Wave Serial API function is represented as a struct. These map to the fun
 - **Set only:** Host sends a REQ to configure the chip with no response (e.g. `ApplicationNodeInformation`, `SetPromiscuousMode`)
 - **Unsolicited request:** Chip sends a REQ without the host asking (e.g. `ApplicationCommandHandler`, `ApplicationUpdate`, `ApplicationCommandHandlerBridge`, `SerialApiStarted`)
 
+**Node ID encoding:** All node ID parameters in the C# API are `ushort` to support both classic (1–232) and Long Range (256+) nodes. On the wire, node IDs are currently serialized as a single byte (8-bit mode, the default). The `Create()` methods cast `(byte)nodeId` when writing to the buffer.
+
 ### Command Classes (`src/ZWave.CommandClasses/`)
 
 Implements Z-Wave Command Classes per the Z-Wave Application Specification. These are the application-level messages exchanged between Z-Wave nodes. This project references `ZWave.Protocol` but **not** `ZWave.Serial`, enabling mock driver implementations without a serial dependency.
@@ -144,6 +150,7 @@ Implements Z-Wave Command Classes per the Z-Wave Application Specification. Thes
 - `IdentifyAsync()` queries the chip: home/node ID, serial API capabilities, library version, controller capabilities, supported setup subcommands, SUC node ID, and init data (node list)
 - Promotes itself to SUC/SIS if none exists on the network
 - Creates `Node` instances for every node in the network
+- Stores nodes in a `Dictionary<ushort, Node>` keyed by node ID
 
 **`Node`** (`Node.cs`) - Represents a Z-Wave network node. Implements `INode`.
 - `InterviewAsync()` queries protocol info, requests node info, discovers command classes, then interviews each CC in topological dependency order

src/ZWave.CommandClasses/IDriver.cs

@@ -10,12 +10,12 @@ public interface IDriver
     /// </summary>
     Task SendCommandAsync<TCommand>(
         TCommand command,
-        byte nodeId,
+        ushort nodeId,
         CancellationToken cancellationToken)
         where TCommand : struct, ICommand;
 
     /// <summary>
     /// Gets a node by its ID, or null if the node is not found.
     /// </summary>
-    INode? GetNode(byte nodeId);
+    INode? GetNode(ushort nodeId);
 }

src/ZWave.CommandClasses/INode.cs

@@ -8,7 +8,7 @@ public interface INode
     /// <summary>
     /// Gets the node ID.
     /// </summary>
-    byte Id { get; }
+    ushort Id { get; }
 
     /// <summary>
     /// Gets the frequent listening mode of the node.

src/ZWave.CommandClasses/PowerlevelCommandClass.cs

@@ -104,7 +104,7 @@ public readonly record struct PowerlevelTestResult(
     /// <summary>
     /// The node ID of the node which is or has been under test.
     /// </summary>
-    byte NodeId,
+    ushort NodeId,
 
     /// <summary>
     /// The result of the test
@@ -178,7 +178,7 @@ public async Task<PowerlevelReport> GetAsync(CancellationToken cancellationToken
     /// power level specified.
     /// </summary>
     public async Task<PowerlevelTestResult> TestNodeAsync(
-        byte testNodeId,
+        ushort testNodeId,
         Powerlevel powerlevel,
         ushort testFrameCount,
         CancellationToken cancellationToken)
@@ -334,12 +334,12 @@ public PowerlevelTestNodeSetCommand(CommandClassFrame frame)
         public CommandClassFrame Frame { get; }
 
         public static PowerlevelSetCommand Create(
-            byte testNodeId,
+            ushort testNodeId,
             Powerlevel powerlevel,
             ushort testFrameCount)
         {
             Span<byte> commandParameters = stackalloc byte[4];
-            commandParameters[0] = testNodeId;
+            commandParameters[0] = (byte)testNodeId;
             commandParameters[1] = (byte)powerlevel;
             testFrameCount.WriteBytesBE(commandParameters[2..4]);
 
@@ -389,7 +389,7 @@ public PowerlevelTestNodeReportCommand(CommandClassFrame frame)
                 throw new ZWaveException(ZWaveErrorCode.InvalidPayload, "Powerlevel Test Node Report frame is too short");
             }
 
-            byte nodeId = frame.CommandParameters.Span[0];
+            ushort nodeId = frame.CommandParameters.Span[0];
             if (nodeId == 0)
             {
                 return null;

src/ZWave.CommandClasses/WakeUpCommandClass.cs

@@ -125,7 +125,7 @@ public async Task<WakeUpInterval> GetIntervalAsync(CancellationToken cancellatio
     /// <summary>
     /// Configure the Wake Up interval and destination of a node.
     /// </summary>
-    public async Task SetIntervalAsync(uint wakeupIntervalInSeconds, byte wakeupDestinationNodeId, CancellationToken cancellationToken)
+    public async Task SetIntervalAsync(uint wakeupIntervalInSeconds, ushort wakeupDestinationNodeId, CancellationToken cancellationToken)
     {
         var command = WakeUpIntervalSetCommand.Create(wakeupIntervalInSeconds, wakeupDestinationNodeId);
         await SendCommandAsync(command, cancellationToken).ConfigureAwait(false);
@@ -196,7 +196,7 @@ public WakeUpIntervalSetCommand(CommandClassFrame frame)
 
         public CommandClassFrame Frame { get; }
 
-        public static WakeUpIntervalSetCommand Create(uint wakeupIntervalInSeconds, byte wakeupDestinationNodeId)
+        public static WakeUpIntervalSetCommand Create(uint wakeupIntervalInSeconds, ushort wakeupDestinationNodeId)
         {
             Span<byte> commandParameters = stackalloc byte[4];
 
@@ -212,7 +212,7 @@ public static WakeUpIntervalSetCommand Create(uint wakeupIntervalInSeconds, byte
             wakeupIntervalInSeconds.WriteBytesBE(secondsBytes);
             secondsBytes[1..].CopyTo(commandParameters);
 
-            commandParameters[3] = wakeupDestinationNodeId;
+            commandParameters[3] = (byte)wakeupDestinationNodeId;
 
             CommandClassFrame frame = CommandClassFrame.Create(CommandClassId, CommandId, commandParameters);
             return new WakeUpIntervalSetCommand(frame);

src/ZWave.Serial.Tests/Commands/AddNodeToNetworkTests.cs

@@ -9,7 +9,7 @@ public class AddNodeToNetworkTests : CommandTestBase
     private record AddNodeToNetworkCallbackData(
         byte SessionId,
         AddNodeStatus Status,
-        byte AssignedNodeId,
+        ushort AssignedNodeId,
         byte BasicDeviceClass,
         byte GenericDeviceClass,
         byte SpecificDeviceClass,

src/ZWave.Serial.Tests/Commands/ApplicationCommandHandlerBridgeTests.cs

@@ -8,8 +8,8 @@ public class ApplicationCommandHandlerBridgeTests : CommandTestBase
 {
     private record ApplicationCommandHandlerBridgeData(
         ReceivedStatus ReceivedStatus,
-        byte DestinationNodeId,
-        byte SourceNodeId,
+        ushort DestinationNodeId,
+        ushort SourceNodeId,
         ReadOnlyMemory<byte> Payload,
         RssiMeasurement ReceivedRssi);
 

src/ZWave.Serial.Tests/Commands/ApplicationCommandHandlerTests.cs

@@ -8,7 +8,7 @@ public class ApplicationCommandHandlerTests : CommandTestBase
 {
     private record ApplicationCommandHandlerData(
         ReceivedStatus ReceivedStatus,
-        byte NodeId,
+        ushort NodeId,
         ReadOnlyMemory<byte> Payload,
         RssiMeasurement ReceivedRssi);
 

src/ZWave.Serial.Tests/Commands/ApplicationUpdateTests.cs

@@ -7,14 +7,14 @@ namespace ZWave.Serial.Tests.Commands;
 public class ApplicationUpdateTests : CommandTestBase
 {
     private record ApplicationUpdateGenericData(
-        byte NodeId,
+        ushort NodeId,
         byte BasicDeviceClass,
         byte GenericDeviceClass,
         byte SpecificDeviceClass,
         IReadOnlyList<CommandClassInfo> CommandClasses);
 
     private record ApplicationUpdateSmartStartPrimeData(
-        byte NodeId,
+        ushort NodeId,
         ReceivedStatus ReceivedStatus,
         uint HomeId,
         byte BasicDeviceClass,
@@ -23,7 +23,7 @@ private record ApplicationUpdateSmartStartPrimeData(
         IReadOnlyList<CommandClassInfo> CommandClasses);
 
     private record ApplicationUpdateSmartStartIncludedNodeInfoData(
-        byte NodeId,
+        ushort NodeId,
         ReceivedStatus ReceivedStatus,
         uint HomeId);