feat: Phase 4 - Device Discovery Framework (Issue #49)

[tylerkron]

User description

Summary

Implements Phase 4 of the migration plan: Device Discovery Framework as specified in Issue #49.

This PR adds comprehensive device discovery functionality to daqifi-core, enabling discovery of DAQiFi devices via WiFi/UDP, Serial/USB, and HID (bootloader mode).

New Features

🔍 Device Discovery Interfaces

• IDeviceFinder - Interface for device discovery mechanisms with async/await and cancellation support
• IDeviceInfo - Interface for discovered device metadata
• DeviceInfo - Concrete implementation with support for WiFi, Serial, and HID devices
• DeviceDiscoveredEventArgs - Event args for real-time discovery notifications
• Enumerations:
  • DeviceType (Unknown, Daqifi, Nyquist)
  • ConnectionType (Unknown, WiFi, Serial, Hid)

📡 WiFi Device Discovery (WiFiDeviceFinder)

• UDP broadcast discovery on configurable port (default 30303 matching desktop implementation)
• Parses protobuf responses from devices extracting:
  • IP address, MAC address, TCP port
  • Hostname, serial number, firmware version
  • Device type (from part number), power status
• Network interface enumeration for proper subnet-directed broadcasts
• Duplicate device detection (by MAC address or serial number)
• Async discovery with timeout and cancellation token support
• Event-based notifications (DeviceDiscovered, DiscoveryCompleted)

🔌 Serial Device Discovery (SerialDeviceFinder)

• Enumerates available serial/USB ports using existing SerialStreamTransport
• Configurable baud rate (default 115200)
• Async discovery with cancellation support
• Note: Full device info retrieval via SCPI commands deferred to Phase 6 (Protocol Implementation)

🛠️ HID Device Discovery (HidDeviceFinder)

• Framework for bootloader mode device discovery (VendorId: 0x4D8, ProductId: 0x03C)
• Basic structure in place following IDeviceFinder interface
• Note: Full HID enumeration deferred until HID library dependency is added to core

Testing

Added 23 new unit tests covering all discovery functionality:

Test Coverage

• ✅ WiFiDeviceFinderTests - 7 tests covering async discovery, cancellation, events, disposal
• ✅ SerialDeviceFinderTests - 7 tests for serial enumeration and lifecycle
• ✅ HidDeviceFinderTests - 5 tests for HID discovery framework
• ✅ DeviceInfoTests - 4 tests for device info formatting and defaults

Test Results

Passed!  - Failed: 0, Passed: 23, Skipped: 0, Total: 23

• All tests passing on .NET 8.0 and .NET 9.0
• Proper async/await patterns with cancellation token support
• No test flakiness or port binding conflicts

Implementation Details

Leverages Existing Infrastructure

• Uses existing UdpTransport from Phase 3 for WiFi discovery
• Uses existing SerialStreamTransport.GetAvailablePortNames() for serial enumeration
• Uses existing protobuf message types (DaqifiOutMessage) for device discovery responses
• Follows code patterns established in Phase 3 (Connection Management)

Cross-Platform Compatible

• No Windows-specific dependencies
• Works on Linux, macOS, and Windows
• Uses standard .NET networking APIs

Code Quality

• Comprehensive XML documentation on all public APIs
• Follows existing coding standards and conventions
• Proper disposal patterns with IDisposable
• Event-driven architecture for real-time discovery feedback

Desktop Migration Impact

Once this is deployed to NuGet as Core 0.6.0, daqifi-desktop can migrate:

Before (Desktop):

var wifiFinder = new Desktop.DaqifiDeviceFinder(30303);
var serialFinder = new Desktop.SerialDeviceFinder();
var hidFinder = new Desktop.HidDeviceFinder();

After (Core):

using Daqifi.Core.Device.Discovery;

var wifiFinder = new WiFiDeviceFinder(); // Default port 30303
var serialFinder = new SerialDeviceFinder(); // Default 115200 baud
var hidFinder = new HidDeviceFinder();

// All implement IDeviceFinder with consistent async API
foreach (var finder in new IDeviceFinder[] { wifiFinder, serialFinder, hidFinder })
{
    finder.DeviceDiscovered += (s, e) => Console.WriteLine($"Found: {e.DeviceInfo}");
    var devices = await finder.DiscoverAsync(TimeSpan.FromSeconds(5));
}

Desktop Code Reduction

• DaqifiDeviceFinder → replaced with WiFiDeviceFinder (remove ~255 lines)
• SerialDeviceFinder → replaced with core implementation (remove ~154 lines)
• HidDeviceFinder → replaced with core implementation (remove ~83 lines)
• Total: ~492 lines removed from desktop

Migration Plan Progress

• ✅ Phase 1: Foundation (Core 0.3.0)
• ✅ Phase 2: Message System (Core 0.4.0)
• ✅ Phase 3: Connection Management (Core 0.5.0)
• ✅ Phase 4: Device Discovery (Core 0.6.0) ← This PR
• ⏳ Phase 5: Channel Management
• ⏳ Phase 6: Protocol Implementation
• ⏳ Phase 7: Advanced Features
• 🚫 Phase 8: Desktop Integration (deferred until Phases 3-7 complete)

Breaking Changes

None - This is purely additive functionality.

Dependencies

• Depends on: Phase 3 (Connection Management) - UDP transport ✅
• Blocks: Phase 5 (Channel Management) and Phase 6 (Protocol Implementation)

Related Issues

• Closes Phase 4: Device Discovery Framework #49 (Phase 4: Device Discovery Framework)
• Part of migration plan in DAQIFI_CORE_MIGRATION_PLAN.md

Checklist

• Code builds successfully
• All tests passing (23/23 pass)
• No breaking changes to existing APIs
• XML documentation on all public APIs
• Cross-platform compatible (no Windows-specific code)
• Follows existing code patterns and conventions
• Migration plan updated with completion status

🤖 Generated with Claude Code

---

PR Type

Enhancement, Tests

---

Description

• Implements Phase 4 device discovery framework with WiFi, Serial, and HID support

• Adds IDeviceFinder interface and concrete implementations for three connection types

• Includes DeviceInfo class and enumerations for device/connection types

• Provides 23 comprehensive unit tests covering all discovery mechanisms

---

Diagram Walkthrough

flowchart LR
  IDeviceFinder["IDeviceFinder<br/>Interface"]
  WiFi["WiFiDeviceFinder<br/>UDP Broadcast"]
  Serial["SerialDeviceFinder<br/>Port Enumeration"]
  HID["HidDeviceFinder<br/>Bootloader Mode"]
  DeviceInfo["DeviceInfo<br/>Metadata"]
  Events["DeviceDiscoveredEventArgs<br/>Event Notifications"]
  
  IDeviceFinder -- "implemented by" --> WiFi
  IDeviceFinder -- "implemented by" --> Serial
  IDeviceFinder -- "implemented by" --> HID
  WiFi -- "returns" --> DeviceInfo
  Serial -- "returns" --> DeviceInfo
  HID -- "returns" --> DeviceInfo
  WiFi -- "raises" --> Events
  Serial -- "raises" --> Events
  HID -- "raises" --> Events

Loading

File Walkthrough

	Relevant files
Enhancement	7 files IDeviceFinder.cs Device discovery interface with async support                        +36/-0    IDeviceInfo.cs Device metadata interface and type enumerations                    +113/-0  DeviceInfo.cs Concrete device information implementation                              +81/-0    DeviceDiscoveredEventArgs.cs Event arguments for device discovery notifications              +23/-0    WiFiDeviceFinder.cs UDP broadcast WiFi device discovery implementation              +359/-0  SerialDeviceFinder.cs Serial port enumeration device discovery                                  +189/-0  HidDeviceFinder.cs HID bootloader mode discovery framework                                    +125/-0
Tests	4 files WiFiDeviceFinderTests.cs WiFi discovery async and event tests                                          +102/-0  SerialDeviceFinderTests.cs Serial discovery lifecycle and baud rate tests                      +97/-0    HidDeviceFinderTests.cs HID discovery framework and disposal tests                              +80/-0    DeviceInfoTests.cs Device info formatting and default value tests                      +86/-0

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided - [ ] Create ticket/issue <!-- /create_ticket --create_ticket=true --> </details></td></tr>
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Prevent concurrent discovery operations To prevent resource conflicts from simultaneous discovery operations, add a SemaphoreSlim to each finder class. This will ensure that only one DiscoverAsync call can execute at a time per instance, improving the robustness of the classes. Examples: src/Daqifi.Core/Device/Discovery/WiFiDeviceFinder.cs [81-177] public async Task<IEnumerable<IDeviceInfo>> DiscoverAsync(CancellationToken cancellationToken = default) { return await DiscoverAsync(TimeSpan.FromSeconds(DefaultTimeoutSeconds), cancellationToken); } /// <summary> /// Discovers devices asynchronously with a timeout. /// </summary> /// <param name="timeout">The timeout for discovery.</param> /// <returns>A task containing the collection of discovered devices.</returns> ... (clipped 87 lines) src/Daqifi.Core/Device/Discovery/SerialDeviceFinder.cs [70-104] public async Task<IEnumerable<IDeviceInfo>> DiscoverAsync(CancellationToken cancellationToken = default) { ThrowIfDisposed(); var discoveredDevices = new List<IDeviceInfo>(); var availablePorts = SerialStreamTransport.GetAvailablePortNames(); foreach (var portName in availablePorts) { if (cancellationToken.IsCancellationRequested) ... (clipped 25 lines) Solution Walkthrough: Before: // In WiFiDeviceFinder.cs public class WiFiDeviceFinder : IDeviceFinder, IDisposable { // ... private async Task<IEnumerable<IDeviceInfo>> DiscoverAsync(TimeSpan timeout, CancellationToken cancellationToken) { ThrowIfDisposed(); using var udpTransport = new UdpTransport(_discoveryPort); await udpTransport.OpenAsync(); // ... send broadcast and receive responses await udpTransport.CloseAsync(); OnDiscoveryCompleted(); return discoveredDevices; } } After: // In WiFiDeviceFinder.cs public class WiFiDeviceFinder : IDeviceFinder, IDisposable { private readonly SemaphoreSlim _discoverySemaphore = new SemaphoreSlim(1, 1); // ... private async Task<IEnumerable<IDeviceInfo>> DiscoverAsync(TimeSpan timeout, CancellationToken cancellationToken) { await _discoverySemaphore.WaitAsync(cancellationToken); try { ThrowIfDisposed(); // ... (rest of the discovery logic) } finally { _discoverySemaphore.Release(); } } } Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies a significant concurrency issue in the finder classes that could lead to runtime exceptions from resource conflicts, and proposes a standard, effective solution.	Medium
Possible issue	✅ Fix incorrect timeout in async method Suggestion Impact: The commit updated DiscoverAsync(CancellationToken) to call the overload with Timeout.InfiniteTimeSpan instead of a 5-second timeout, aligning behavior with the suggestion. code diff: public async Task<IEnumerable<IDeviceInfo>> DiscoverAsync(CancellationToken cancellationToken = default) { - return await DiscoverAsync(TimeSpan.FromSeconds(DefaultTimeoutSeconds), cancellationToken); + return await DiscoverAsync(Timeout.InfiniteTimeSpan, cancellationToken); } In DiscoverAsync(CancellationToken), remove the fixed 5-second timeout by calling the overload with Timeout.InfiniteTimeSpan to let the cancellationToken be the sole cancellation trigger. src/Daqifi.Core/Device/Discovery/WiFiDeviceFinder.cs [81-84] public async Task<IEnumerable<IDeviceInfo>> DiscoverAsync(CancellationToken cancellationToken = default) { - return await DiscoverAsync(TimeSpan.FromSeconds(DefaultTimeoutSeconds), cancellationToken); + return await DiscoverAsync(Timeout.InfiniteTimeSpan, cancellationToken); } [Suggestion processed] Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the method imposes an unexpected 5-second timeout, which violates the expected behavior of a method overload that only takes a CancellationToken.	Low
Update