Introduce IEndpoint abstraction (#180)

Author: dfederm

.github/copilot-instructions.md

@@ -73,8 +73,10 @@ Implements the Z-Wave Serial API frame-level protocol (as defined by the Z-Wave
 ### Command Classes Layer (`src/ZWave.CommandClasses/`)
 
 Implements Z-Wave Command Classes (Z-Wave Application Specification). This project references `ZWave.Protocol` but **not** `ZWave.Serial`, enabling mock driver implementations without a serial dependency.
-- **`CommandClass`** / **`CommandClass<TCommand>`** — Abstract base classes. Each CC (e.g. `BinarySwitchCommandClass`) inherits from `CommandClass<TEnum>` where `TEnum` is a byte-backed enum of commands. Takes `IDriver` and `INode` interfaces (not concrete types).
-- **`IDriver`** / **`INode`** — Interfaces defined here that abstract the driver layer. `Driver` and `Node` implement these in the ZWave project.
+- **`IEndpoint`** — Interface representing a functional sub-unit of a node. Properties: `NodeId`, `EndpointIndex`, `CommandClasses`, `GetCommandClass()`. Endpoint 0 is the "Root Device" (the node itself); endpoints 1–127 are sub-devices discovered via Multi Channel CC.
+- **`INode`** — Extends `IEndpoint` with node-level properties (`FrequentListeningMode`). A node IS endpoint 0.
+- **`IDriver`** — Interface abstracting the driver layer. `SendCommandAsync` accepts `nodeId` and `endpointIndex` parameters.
+- **`CommandClass`** / **`CommandClass<TCommand>`** — Abstract base classes. Each CC (e.g. `BinarySwitchCommandClass`) inherits from `CommandClass<TEnum>` where `TEnum` is a byte-backed enum of commands. Takes `IDriver` and `IEndpoint` interfaces (not concrete types). The `Endpoint` property provides access to the endpoint this CC belongs to.
 - **`[CommandClass(CommandClassId.X)]` attribute** — Applied to each CC class. The source generator `CommandClassFactoryGenerator` scans for this attribute and generates `CommandClassFactory` with a mapping from `CommandClassId` → constructor.
 - **`ICommand` interface** (`CommandClasses/ICommand.cs`) — Different from the Serial API `ICommand`. Used for CC-level commands with `CommandClassId` and `CommandId`.
 - **`CommandClassFrame`** — Wraps CC payload bytes (CC ID + Command ID + parameters).
@@ -83,7 +85,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 IDs are `ushort` throughout the codebase to support both classic (1–232) and Long Range (256+) nodes.
+- **`Node`** — Represents a Z-Wave network node. Implements `INode` (and thus `IEndpoint` with `EndpointIndex = 0`). 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/`)
 
@@ -116,7 +118,7 @@ Uses `Microsoft.Extensions.Logging` with source-generated `[LoggerMessage]` attr
 
 **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.
+**New Command Class**: Create a class in `src/ZWave.CommandClasses/` inheriting `CommandClass<TEnum>`. Apply `[CommandClass(CommandClassId.X)]`. Constructor takes `(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)`. Define private inner structs for each command (Set/Get/Report) implementing `ICommand`. The source generator auto-registers it. Use `Endpoint` property to access the endpoint (e.g. `Endpoint.NodeId`, `Endpoint.CommandClasses`).
 
 ## Protocol References
 

.github/skills/zwave-implement-cc/SKILL.md

@@ -226,9 +226,9 @@ public sealed class {Name}CommandClass : CommandClass<{Name}Command>
     internal {Name}CommandClass(
         CommandClassInfo info,
         IDriver driver,
-        INode node,
+        IEndpoint endpoint,
         ILogger logger)
-        : base(info, driver, node, logger)
+        : base(info, driver, endpoint, logger)
     {
     }
 
@@ -271,7 +271,7 @@ public sealed class {Name}CommandClass : CommandClass<{Name}Command>
 #### Key Points for the CC Class
 
 - **`[CommandClass(CommandClassId.{Name})]` attribute**: This is required. A Roslyn source generator scans for this attribute and auto-generates the `CommandClassFactory` mapping. No other registration is needed.
-- **Constructor**: Always `internal`, takes `(CommandClassInfo info, IDriver driver, INode node, ILogger logger)`, calls `base(info, driver, node, logger)`.
+- **Constructor**: Always `internal`, takes `(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)`, calls `base(info, driver, endpoint, logger)`. The `Endpoint` property provides access to the endpoint this CC belongs to (e.g. `Endpoint.NodeId`, `Endpoint.CommandClasses`, `Endpoint.GetCommandClass()`).
 - **`IsCommandSupported`**: Return `true` for always-available commands, `false` for report-only/unsupported commands, and use `Version.HasValue ? Version >= N : null` for version-gated commands. Use `null` when it's unknown whether the command is supported.
 - **`Dependencies`**: Only override if this CC does NOT depend on the Version CC. The default is `{ CommandClassId.Version }`. The Version CC itself overrides this to `Array.Empty<CommandClassId>()`.
 

src/ZWave.BuildTools/CommandClassFactoryGenerator.cs

@@ -103,13 +103,13 @@ namespace ZWave.CommandClasses;
 
 internal static class CommandClassFactory
 {
-    private static readonly Dictionary<CommandClassId, Func<CommandClassInfo, IDriver, INode, ILogger, CommandClass>> Constructors = new Dictionary<CommandClassId, Func<CommandClassInfo, IDriver, INode, ILogger, CommandClass>>
+    private static readonly Dictionary<CommandClassId, Func<CommandClassInfo, IDriver, IEndpoint, ILogger, CommandClass>> Constructors = new Dictionary<CommandClassId, Func<CommandClassInfo, IDriver, IEndpoint, ILogger, CommandClass>>
     {
 ");
 
         foreach (KeyValuePair<string, string> pair in idToType)
         {
-            sb.AppendLine($"        {{ {pair.Key}, (info, driver, node, logger) => new {pair.Value}(info, driver, node, logger) }},");
+            sb.AppendLine($"        {{ {pair.Key}, (info, driver, endpoint, logger) => new {pair.Value}(info, driver, endpoint, logger) }},");
         }
 
         sb.Append(@"    };
@@ -125,10 +125,10 @@ internal static class CommandClassFactory
 
         sb.Append(@"    };
 
-    public static CommandClass Create(CommandClassInfo info, IDriver driver, INode node, ILogger logger)
-        => Constructors.TryGetValue(info.CommandClass, out Func<CommandClassInfo, IDriver, INode, ILogger, CommandClass>? constructor)
-            ? constructor(info, driver, node, logger)
-            : new NotImplementedCommandClass(info, driver, node, logger);
+    public static CommandClass Create(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)
+        => Constructors.TryGetValue(info.CommandClass, out Func<CommandClassInfo, IDriver, IEndpoint, ILogger, CommandClass>? constructor)
+            ? constructor(info, driver, endpoint, logger)
+            : new NotImplementedCommandClass(info, driver, endpoint, logger);
 
     public static CommandClassId GetCommandClassId<TCommandClass>()
         where TCommandClass : CommandClass

src/ZWave.CommandClasses/BasicCommandClass.cs

@@ -45,9 +45,9 @@ public sealed class BasicCommandClass : CommandClass<BasicCommand>
     internal BasicCommandClass(
         CommandClassInfo info,
         IDriver driver,
-        INode node,
+        IEndpoint endpoint,
         ILogger logger)
-        : base(info, driver, node, logger)
+        : base(info, driver, endpoint, logger)
     {
     }
 

src/ZWave.CommandClasses/BatteryCommandClass.cs

@@ -164,8 +164,8 @@ public readonly record struct BatteryHealth(
 [CommandClass(CommandClassId.Battery)]
 public sealed class BatteryCommandClass : CommandClass<BatteryCommand>
 {
-    public BatteryCommandClass(CommandClassInfo info, IDriver driver, INode node, ILogger logger)
-        : base(info, driver, node, logger)
+    public BatteryCommandClass(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)
+        : base(info, driver, endpoint, logger)
     {
     }
 

src/ZWave.CommandClasses/BinarySensorCommandClass.cs

@@ -106,8 +106,8 @@ public sealed class BinarySensorCommandClass : CommandClass<BinarySensorCommand>
 {
     private Dictionary<BinarySensorType, bool?>? _sensorValues;
 
-    public BinarySensorCommandClass(CommandClassInfo info, IDriver driver, INode node, ILogger logger)
-        : base(info, driver, node, logger)
+    public BinarySensorCommandClass(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)
+        : base(info, driver, endpoint, logger)
     {
     }
 

src/ZWave.CommandClasses/BinarySwitchCommandClass.cs

@@ -42,8 +42,8 @@ public readonly record struct BinarySwitchReport(
 [CommandClass(CommandClassId.BinarySwitch)]
 public sealed class BinarySwitchCommandClass : CommandClass<BinarySwitchCommand>
 {
-    internal BinarySwitchCommandClass(CommandClassInfo info, IDriver driver, INode node, ILogger logger)
-        : base(info, driver, node, logger)
+    internal BinarySwitchCommandClass(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)
+        : base(info, driver, endpoint, logger)
     {
     }
 

src/ZWave.CommandClasses/ColorSwitchCommandClass.cs

@@ -98,8 +98,8 @@ public sealed class ColorSwitchCommandClass : CommandClass<ColorSwitchCommand>
 {
     private Dictionary<ColorSwitchColorComponent, ColorSwitchColorComponentState?>? _colorComponents;
 
-    public ColorSwitchCommandClass(CommandClassInfo info, IDriver driver, INode node, ILogger logger)
-        : base(info, driver, node, logger)
+    public ColorSwitchCommandClass(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)
+        : base(info, driver, endpoint, logger)
     {
     }
 

src/ZWave.CommandClasses/CommandClass.cs

@@ -9,8 +9,8 @@ namespace ZWave.CommandClasses;
 public abstract class CommandClass<TCommand> : CommandClass
     where TCommand : struct, Enum
 {
-    internal CommandClass(CommandClassInfo info, IDriver driver, INode node, ILogger logger)
-        : base(info, driver, node, logger)
+    internal CommandClass(CommandClassInfo info, IDriver driver, IEndpoint endpoint, ILogger logger)
+        : base(info, driver, endpoint, logger)
     {
         if (Unsafe.SizeOf<TCommand>() != Unsafe.SizeOf<byte>())
         {
@@ -52,12 +52,12 @@ private record struct AwaitedReport(
     internal CommandClass(
         CommandClassInfo info,
         IDriver driver,
-        INode node,
+        IEndpoint endpoint,
         ILogger logger)
     {
         Info = info;
         Driver = driver;
-        Node = node;
+        Endpoint = endpoint;
         Logger = logger;
     }
 
@@ -72,9 +72,9 @@ internal CommandClass(
     protected IDriver Driver { get; }
 
     /// <summary>
-    /// Gets the node this command class belongs to.
+    /// Gets the endpoint this command class belongs to.
     /// </summary>
-    public INode Node { get; }
+    public IEndpoint Endpoint { get; }
 
     /// <summary>
     /// Gets the logger for this command class.
@@ -172,7 +172,7 @@ internal async Task SendCommandAsync<TRequest>(
             throw new ZWaveException(ZWaveErrorCode.CommandNotSupported, "This command is not supported by this node");
         }
 
-        await Driver.SendCommandAsync(command, Node.Id, cancellationToken).ConfigureAwait(false);
+        await Driver.SendCommandAsync(command, Endpoint.NodeId, Endpoint.EndpointIndex, cancellationToken).ConfigureAwait(false);
     }
 
     internal Task<CommandClassFrame> AwaitNextReportAsync<TReport>(CancellationToken cancellationToken)

src/ZWave.CommandClasses/IDriver.cs

@@ -6,11 +6,12 @@
 public interface IDriver
 {
     /// <summary>
-    /// Sends a command class command to a specific node.
+    /// Sends a command class command to a specific node and endpoint.
     /// </summary>
     Task SendCommandAsync<TCommand>(
         TCommand command,
         ushort nodeId,
+        byte endpointIndex,
         CancellationToken cancellationToken)
         where TCommand : struct, ICommand;