jmri-client 4.2.0-beta.1 → 4.2.0-beta.2

package/README.md

@@ -19,6 +19,7 @@ WebSocket client for [JMRI](http://jmri.sourceforge.net/) with real-time updates
 - ✅ **Heartbeat monitoring** - Automatic ping/pong keepalive
 - ✅ **TypeScript** - Full type definitions included
 - ✅ **Dual module support** - ESM and CommonJS
+- ✅ **Multi-connection** - Target specific hardware connections by prefix when multiple are configured
 - ✅ **Extensible** - Subclass `JmriClient` to add support for additional JMRI object types
 
 ## Installation
@@ -106,6 +107,20 @@ client.on('reconnecting', (attempt, delay) => {
 });
 ```
 
+### Multi-Connection Support
+
+When JMRI has multiple hardware connections configured, use `getSystemConnections()` to discover their prefixes and pass them to power and throttle commands:
+
+```typescript
+const connections = await client.getSystemConnections();
+// [{ name: 'LocoNet', prefix: 'L' }, { name: 'DCC++', prefix: 'D' }]
+
+await client.powerOn('L');                             // LocoNet only
+const throttle = await client.acquireThrottle({ address: 3, prefix: 'L' });
+```
+
+When no prefix is supplied the command routes to JMRI's default connection manager, which is the correct behaviour for single-connection layouts.
+
 ### Extending JmriClient
 
 `JmriClient` exposes its `wsClient` as `protected`, so you can subclass it to add support for JMRI object types not yet built in (e.g., sensors, lights, routes, blocks):

package/docs/API.md

@@ -65,6 +65,9 @@ client.on('heartbeat:timeout', () => { });
 // Get current power state
 const state: PowerState = await client.getPower();
 
+// Get power state for a specific hardware connection (see System Connections)
+const state: PowerState = await client.getPower('L');  // LocoNet prefix
+
 // PowerState enum values (from JMRI JSON protocol):
 // PowerState.UNKNOWN = 0  (state cannot be determined)
 // PowerState.ON = 2       (power is on)
@@ -83,10 +86,15 @@ switch (state) {
     break;
 }
 
-// Set power
+// Set power (all connections, or a specific one)
 await client.setPower(PowerState.ON);
-await client.powerOn();   // Convenience method
-await client.powerOff();  // Convenience method
+await client.setPower(PowerState.ON, 'L');  // LocoNet only
+
+// Convenience methods — all accept an optional prefix
+await client.powerOn();         // All connections
+await client.powerOn('L');      // LocoNet only
+await client.powerOff();        // All connections
+await client.powerOff('D');     // DCC++ only
 
 // Listen for power changes (including UNKNOWN states)
 client.on('power:changed', (state: PowerState) => {
@@ -96,6 +104,29 @@ client.on('power:changed', (state: PowerState) => {
 });
 ```
 
+## System Connections
+
+Discover the hardware connections JMRI has configured and their short prefix strings. Use these prefixes to target power and throttle commands at a specific connection when multiple are active.
+
+```typescript
+// List all available system connections
+const connections: SystemConnectionData[] = await client.getSystemConnections();
+// [
+//   { name: 'LocoNet', prefix: 'L', userName: 'LocoNet' },
+//   { name: 'DCC++', prefix: 'D' }
+// ]
+
+// Use a prefix to target a specific connection
+const [loconet] = connections.filter(c => c.name === 'LocoNet');
+await client.powerOn(loconet.prefix);
+
+// Acquire a throttle on a specific connection
+const throttleId = await client.acquireThrottle({
+  address: 3,
+  prefix: loconet.prefix
+});
+```
+
 ## Roster Management
 
 ```typescript
@@ -150,6 +181,9 @@ client.on('light:changed', (name: string, state: LightState) => {
 // Acquire throttle
 const throttleId = await client.acquireThrottle({ address: 3 });
 
+// Acquire throttle on a specific hardware connection
+const throttleId = await client.acquireThrottle({ address: 3, prefix: 'L' });
+
 // Control speed (0.0 to 1.0)
 await client.setThrottleSpeed(throttleId, 0.0);   // Stopped
 await client.setThrottleSpeed(throttleId, 0.5);   // Half speed
@@ -237,6 +271,7 @@ import {
   TurnoutData,
   ThrottleState,
   ThrottleFunctionKey,
-  ConnectionState
+  ConnectionState,
+  SystemConnectionData
 } from 'jmri-client';
 ```

package/docs/EXAMPLES.md

@@ -283,6 +283,48 @@ async function runLayout() {
 runLayout();
 ```
 
+## Multi-Connection / Hardware Prefix
+
+When JMRI is configured with more than one hardware connection (e.g. both LocoNet and DCC++), use `getSystemConnections()` to discover the available prefixes, then pass them to power and throttle commands to target a specific connection.
+
+```typescript
+import { JmriClient } from 'jmri-client';
+
+const client = new JmriClient({ host: 'jmri.local' });
+
+client.on('connected', async () => {
+  // Discover what hardware connections JMRI has configured
+  const connections = await client.getSystemConnections();
+  console.log('Available connections:');
+  for (const conn of connections) {
+    console.log(`  ${conn.name} (prefix: "${conn.prefix}")`);
+  }
+  // Available connections:
+  //   LocoNet (prefix: "L")
+  //   DCC++ (prefix: "D")
+
+  // Power on via LocoNet only
+  await client.powerOn('L');
+
+  // Acquire a throttle on LocoNet
+  const throttle = await client.acquireThrottle({ address: 3, prefix: 'L' });
+  await client.setThrottleDirection(throttle, true);
+  await client.setThrottleSpeed(throttle, 0.3);
+
+  await new Promise(resolve => setTimeout(resolve, 5000));
+
+  await client.setThrottleSpeed(throttle, 0);
+  await client.releaseThrottle(throttle);
+
+  // Power off via LocoNet only
+  await client.powerOff('L');
+
+  await client.disconnect();
+});
+```
+
+Single-connection layouts work exactly as before — just omit the prefix and JMRI routes to the default connection.
+
 ## CommonJS Usage
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jmri-client",
-  "version": "4.2.0-beta.1",
+  "version": "4.2.0-beta.2",
   "description": "WebSocket client for JMRI with real-time updates and throttle control - works in both Node.js and browsers",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",