feat(cli): add --id option to discover command for slave ID filtering (#321)

Add optional --id parameter to the discover command that allows filtering
device searches to specific slave IDs instead of searching the full 1-247 range.

Core Implementation:
- Add parseIdRange() utility to parse ID specifications like "1,2,3-5"
- Extend GeneratorOptions with optional slaveIds filter
- Update parameter generators to respect slave ID filtering
- Add --id CLI option with support for multiple specifications

User Experience:
- Display filtered IDs in console output (e.g., "Slave IDs: 1, 2, 3 (3 IDs)")
- Merge and deduplicate multiple --id flags
- Maintain priority ordering (defaultAddress first, then 1, 2, then rest)

Performance Benefits:
- Searching only 5 IDs instead of 247 reduces combinations by ~98%
- Example: Quick scan of IDs 1-5 completes in ~1 min vs ~50 min for all IDs
- With driver: IDs 1-5 in ~30 sec vs ~25 min for all IDs

Critical Fixes (Post-Review):
1. Progress tracker bug (e2d1514) - countParameterCombinations now respects slaveIds filter
2. Empty string validation (4ed1517) - Rejects empty --id specifications with clear error
3. Decimal validation (d744871) - Rejects decimal numbers explicitly

Testing:
- 28 unit tests for ID range parser (including edge cases)
- 10 unit tests for parameter generator filtering
- 10 E2E tests for discover command integration
- All 449 tests passing

Related issues: #326, #328, #329, #330, #331

Author: groupsky

packages/cli/docs/discover-command.md

@@ -54,6 +54,22 @@ This will:
   - Lower values scan faster but may cause errors
   - Recommended: 100ms minimum
 
+- `--id <spec>` - Limit search to specific slave IDs (can be specified multiple times)
+  - Format: Single IDs or ranges separated by commas (e.g., `1,2,3-5`)
+  - Multiple `--id` flags are merged and deduplicated
+  - Dramatically reduces scan time when you know which IDs to search
+  - Examples:
+    - `--id 1` - Search only slave ID 1
+    - `--id 1,2,3` - Search IDs 1, 2, and 3
+    - `--id 1-5` - Search IDs 1 through 5
+    - `--id 1,3-5,10` - Search IDs 1, 3, 4, 5, and 10
+    - `--id 1-3 --id 5-7` - Search IDs 1, 2, 3, 5, 6, and 7
+
+- `--max-devices <count>` - Maximum devices to find (default: `1`, use `0` for unlimited)
+  - Stops scanning after finding specified number of devices
+  - Use `0` to find all devices on the bus
+  - Speeds up discovery when you only need to find one device
+
 ### Output Options
 
 - `--format <type>` - Output format (default: `table`)
@@ -188,12 +204,14 @@ Discovery time depends on several factors:
 
 **Examples:**
 
-| Strategy | Driver | Combinations | Timeout | Est. Time  |
-| -------- | ------ | ------------ | ------- | ---------- |
-| Quick    | No     | ~2,964       | 1000ms  | ~50 min    |
-| Quick    | Yes    | ~1,482       | 1000ms  | ~25 min    |
-| Thorough | No     | ~23,712      | 1000ms  | ~6.5 hours |
-| Thorough | Yes    | ~1,482       | 1000ms  | ~25 min    |
+| Strategy | Driver | ID Filter | Combinations | Timeout | Est. Time  |
+| -------- | ------ | --------- | ------------ | ------- | ---------- |
+| Quick    | No     | None      | ~2,964       | 1000ms  | ~50 min    |
+| Quick    | No     | 1-5       | ~60          | 1000ms  | ~1 min     |
+| Quick    | Yes    | None      | ~1,482       | 1000ms  | ~25 min    |
+| Quick    | Yes    | 1-5       | ~30          | 1000ms  | ~30 sec    |
+| Thorough | No     | None      | ~23,712      | 1000ms  | ~6.5 hours |
+| Thorough | Yes    | None      | ~1,482       | 1000ms  | ~25 min    |
 
 **Note:** Actual time is usually much faster because:
 
@@ -202,10 +220,11 @@ Discovery time depends on several factors:
 
 ### Optimization Tips
 
-1. **Use a driver** - Reduces combinations by 50-90%
-2. **Lower timeout** - Use 250-500ms if devices respond quickly
-3. **Start with quick strategy** - Finds 90% of devices
-4. **Know your device** - If you know slave ID, modify the scan manually
+1. **Filter slave IDs** - Use `--id` if you know which IDs to search (reduces combinations by up to 98%)
+2. **Use a driver** - Reduces combinations by 50-90%
+3. **Lower timeout** - Use 250-500ms if devices respond quickly
+4. **Start with quick strategy** - Finds 90% of devices
+5. **Stop after first device** - Default `--max-devices 1` stops after finding one device
 
 ### Progress Monitoring
 
@@ -391,6 +410,26 @@ Discover on Windows COM port:
 ya-modbus discover --port COM3
 ```
 
+### Example 8: Search Specific Slave IDs
+
+Search only specific slave IDs to dramatically reduce scan time:
+
+```bash
+# Search only ID 1
+ya-modbus discover --port /dev/ttyUSB0 --id 1
+
+# Search IDs 1-5
+ya-modbus discover --port /dev/ttyUSB0 --id 1-5
+
+# Search specific IDs: 1, 2, 3, 10, 11, 12
+ya-modbus discover --port /dev/ttyUSB0 --id 1-3,10-12
+
+# Search IDs from multiple specifications (merged and deduplicated)
+ya-modbus discover --port /dev/ttyUSB0 --id 1,2 --id 3-5
+```
+
+**Performance benefit:** Searching only 5 IDs instead of all 247 reduces combinations by ~98%, completing in seconds instead of minutes.
+
 ## Advanced Usage
 
 ### Combining with Other Commands

packages/cli/src/commands/discover.test.ts

@@ -516,4 +516,128 @@ describe('Discover Command', () => {
       expect(stdoutWriteSpy).not.toHaveBeenCalled()
     })
   })
+
+  describe('--id option (slave ID filtering)', () => {
+    test('should show filtered IDs when --id is specified', async () => {
+      jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        id: '1,2,3',
+        format: 'table',
+      })
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('Slave IDs: 1, 2, 3 (3 IDs)')
+    })
+
+    test('should show "all" when --id is not specified', async () => {
+      jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        format: 'table',
+      })
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('Slave IDs: 1-247 (all)')
+    })
+
+    test('should parse ID ranges correctly', async () => {
+      jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        id: '1-5,10',
+        format: 'table',
+      })
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('Slave IDs: 1, 2, 3, 4, 5, 10 (6 IDs)')
+    })
+
+    test('should merge multiple --id specifications', async () => {
+      jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        id: ['1,2', '3-5'],
+        format: 'table',
+      })
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('Slave IDs: 1, 2, 3, 4, 5 (5 IDs)')
+    })
+
+    test('should deduplicate merged ID specifications', async () => {
+      jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        id: ['1-3', '2-4'],
+        format: 'table',
+      })
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('Slave IDs: 1, 2, 3, 4 (4 IDs)')
+    })
+
+    test('should pass filtered IDs to scanner', async () => {
+      const scanSpy = jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        id: '1,5,10',
+        format: 'table',
+      })
+
+      expect(scanSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          slaveIds: [1, 5, 10],
+        }),
+        expect.anything()
+      )
+    })
+
+    test('should not pass slaveIds to scanner when --id not specified', async () => {
+      const scanSpy = jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        format: 'table',
+      })
+
+      // Should not have slaveIds property in generator options
+      const generatorOptions = scanSpy.mock.calls[0][0]
+      expect(generatorOptions).not.toHaveProperty('slaveIds')
+    })
+
+    test('should handle invalid ID specification with error', async () => {
+      await expect(
+        discoverCommand({
+          port: '/dev/ttyUSB0',
+          id: 'invalid',
+          format: 'table',
+        })
+      ).rejects.toThrow(/invalid/i)
+    })
+
+    test('should handle out-of-range IDs with error', async () => {
+      await expect(
+        discoverCommand({
+          port: '/dev/ttyUSB0',
+          id: '0,1,2',
+          format: 'table',
+        })
+      ).rejects.toThrow(/valid Modbus slave address/i)
+    })
+
+    test('should not show filtered IDs in silent mode', async () => {
+      jest.spyOn(scanner, 'scanForDevices').mockResolvedValue(mockDevices)
+
+      await discoverCommand({
+        port: '/dev/ttyUSB0',
+        id: '1,2,3',
+        format: 'table',
+        silent: true,
+      })
+
+      expect(consoleLogSpy).not.toHaveBeenCalledWith(expect.stringContaining('Slave IDs'))
+    })
+  })
 })

packages/cli/src/commands/discover.ts

@@ -4,6 +4,7 @@ import type { DiscoveryStrategy } from '../discovery/parameter-generator.js'
 import { ProgressTracker } from '../discovery/progress.js'
 import { scanForDevices } from '../discovery/scanner.js'
 import { formatDiscoveryJSON, formatDiscoveryTable } from '../formatters/discovery-results.js'
+import { parseIdRange } from '../utils/parse-id-range.js'
 
 /**
  * Discover command options
@@ -18,6 +19,7 @@ export interface DiscoverOptions {
   timeout?: number
   delay?: number
   maxDevices?: number
+  id?: string | string[]
   verbose?: boolean
   silent?: boolean
 
@@ -42,10 +44,29 @@ export async function discoverCommand(options: DiscoverOptions): Promise<void> {
   const verbose = options.verbose ?? false
   const silent = options.silent ?? false
 
+  // Parse and merge ID specifications
+  let slaveIds: number[] | undefined
+  if (options.id) {
+    const idSpecs = Array.isArray(options.id) ? options.id : [options.id]
+    const allIds = new Set<number>()
+
+    for (const spec of idSpecs) {
+      const ids = parseIdRange(spec)
+      ids.forEach((id) => allIds.add(id))
+    }
+
+    slaveIds = Array.from(allIds).sort((a, b) => a - b)
+  }
+
   if (!silent) {
     console.log(`Starting Modbus device discovery on ${options.port}...`)
     console.log(`Strategy: ${strategy}`)
     console.log(`Timeout: ${timeout}ms, Delay: ${delay}ms`)
+    if (slaveIds) {
+      console.log(`Slave IDs: ${slaveIds.join(', ')} (${slaveIds.length} IDs)`)
+    } else {
+      console.log('Slave IDs: 1-247 (all)')
+    }
     if (maxDevices === 0) {
       console.log('Mode: Find all devices')
     } else {
@@ -103,6 +124,10 @@ export async function discoverCommand(options: DiscoverOptions): Promise<void> {
     generatorOptions.supportedConfig = driverMetadata.supportedConfig
   }
 
+  if (slaveIds) {
+    generatorOptions.slaveIds = slaveIds
+  }
+
   const totalCombinations = countParameterCombinations(generatorOptions)
 
   const progress = new ProgressTracker(totalCombinations)

packages/cli/src/discovery/parameter-generator-utils.test.ts

@@ -113,6 +113,45 @@ describe('countParameterCombinations', () => {
       const count = countParameterCombinations(options)
       expect(count).toBe(1)
     })
+
+    test('respects slaveIds filter', () => {
+      const options: GeneratorOptions = {
+        strategy: 'quick',
+        slaveIds: [1, 2, 3],
+      }
+
+      // 2 baud × 3 parity × 1 data × 1 stop × 3 filtered IDs
+      // = 2 × 3 × 1 × 1 × 3 = 18
+      const count = countParameterCombinations(options)
+      expect(count).toBe(18)
+    })
+
+    test('slaveIds filter overrides addressRange', () => {
+      const options: GeneratorOptions = {
+        strategy: 'quick',
+        slaveIds: [1, 5, 10],
+        supportedConfig: {
+          validAddressRange: [1, 247], // This should be ignored
+        },
+      }
+
+      // 2 baud × 3 parity × 2 data × 2 stop × 3 filtered IDs
+      // Falls back to STANDARD_DATA_BITS and STANDARD_STOP_BITS when supportedConfig exists
+      // = 2 × 3 × 2 × 2 × 3 = 72
+      const count = countParameterCombinations(options)
+      expect(count).toBe(72)
+    })
+
+    test('handles empty slaveIds array', () => {
+      const options: GeneratorOptions = {
+        strategy: 'quick',
+        slaveIds: [],
+      }
+
+      // 2 baud × 3 parity × 1 data × 1 stop × 0 IDs = 0
+      const count = countParameterCombinations(options)
+      expect(count).toBe(0)
+    })
   })
 
   describe('default config prioritization', () => {

packages/cli/src/discovery/parameter-generator-utils.ts

@@ -80,16 +80,21 @@ export function getParameterArrays(
  * ```
  */
 export function countParameterCombinations(options: GeneratorOptions): number {
-  const { strategy, supportedConfig } = options
+  const { strategy, supportedConfig, slaveIds } = options
 
   const { baudRates, parities, dataBits, stopBits, addressRange } = getParameterArrays(
     strategy,
     supportedConfig
   )
 
   // Calculate address count
-  const [minId, maxId] = addressRange
-  const addressCount = maxId - minId + 1
+  let addressCount: number
+  if (slaveIds !== undefined) {
+    addressCount = slaveIds.length
+  } else {
+    const [minId, maxId] = addressRange
+    addressCount = maxId - minId + 1
+  }
 
   // Total combinations = addresses × baud rates × parities × data bits × stop bits
   return addressCount * baudRates.length * parities.length * dataBits.length * stopBits.length