jmri-client 4.1.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/dist/browser/jmri-client.js

@@ -1481,10 +1481,12 @@ var PowerManager = class extends import_index.default {
   }
   /**
    * Get current track power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
    */
-  async getPower() {
+  async getPower(prefix) {
     const message = {
-      type: "power"
+      type: "power",
+      ...prefix !== void 0 && { data: { state: 0 /* UNKNOWN */, prefix } }
     };
     const response = await this.client.request(message);
     if (response.data?.state !== void 0) {
@@ -1494,12 +1496,14 @@ var PowerManager = class extends import_index.default {
   }
   /**
    * Set track power state
+   * @param state - The desired power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
    */
-  async setPower(state) {
+  async setPower(state, prefix) {
     const message = {
       type: "power",
       method: "post",
-      data: { state }
+      data: { state, ...prefix !== void 0 && { prefix } }
     };
     await this.client.request(message);
     const oldState = this.currentState;
@@ -1510,15 +1514,17 @@ var PowerManager = class extends import_index.default {
   }
   /**
    * Turn track power on
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
    */
-  async powerOn() {
-    await this.setPower(2 /* ON */);
+  async powerOn(prefix) {
+    await this.setPower(2 /* ON */, prefix);
   }
   /**
    * Turn track power off
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
    */
-  async powerOff() {
-    await this.setPower(4 /* OFF */);
+  async powerOff(prefix) {
+    await this.setPower(4 /* OFF */, prefix);
   }
   /**
    * Get cached power state (no network request)
@@ -1672,7 +1678,8 @@ var ThrottleManager = class extends import_index.default {
       type: "throttle",
       data: {
         name: throttleName,
-        address: options.address
+        address: options.address,
+        ...options.prefix !== void 0 && { prefix: options.prefix }
       }
     };
     const response = await this.client.request(message);
@@ -2051,6 +2058,29 @@ var LightManager = class extends import_index.default {
   }
 };
 
+// src/managers/system-connections-manager.ts
+var SystemConnectionsManager = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List all available JMRI system connections and their prefixes.
+   * Use the returned prefix values with power and throttle commands to
+   * target a specific hardware connection when multiple are configured.
+   */
+  async getSystemConnections() {
+    const message = {
+      type: "systemConnections",
+      method: "list"
+    };
+    const response = await this.client.request(message);
+    if (!response.data) {
+      return [];
+    }
+    return Array.isArray(response.data) ? response.data : [response.data];
+  }
+};
+
 // src/types/client-options.ts
 var DEFAULT_CLIENT_OPTIONS = {
   host: "localhost",
@@ -2128,6 +2158,7 @@ var JmriClient = class extends import_index.default {
     this.throttleManager = new ThrottleManager(this.wsClient);
     this.turnoutManager = new TurnoutManager(this.wsClient);
     this.lightManager = new LightManager(this.wsClient);
+    this.systemConnectionsManager = new SystemConnectionsManager(this.wsClient);
     this.wsClient.on("connected", () => this.emit("connected"));
     this.wsClient.on("disconnected", (reason) => this.emit("disconnected", reason));
     this.wsClient.on(
@@ -2212,27 +2243,50 @@ var JmriClient = class extends import_index.default {
   // ============================================================================
   /**
    * Get current track power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
    */
-  async getPower() {
-    return this.powerManager.getPower();
+  async getPower(prefix) {
+    return this.powerManager.getPower(prefix);
   }
   /**
    * Set track power state
+   * @param state - The desired power state
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
    */
-  async setPower(state) {
-    return this.powerManager.setPower(state);
+  async setPower(state, prefix) {
+    return this.powerManager.setPower(state, prefix);
   }
   /**
    * Turn track power on
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
    */
-  async powerOn() {
-    return this.powerManager.powerOn();
+  async powerOn(prefix) {
+    return this.powerManager.powerOn(prefix);
   }
   /**
    * Turn track power off
+   * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
+   */
+  async powerOff(prefix) {
+    return this.powerManager.powerOff(prefix);
+  }
+  // ============================================================================
+  // System Connections
+  // ============================================================================
+  /**
+   * List all available JMRI system connections and their prefixes.
+   * Use the returned prefix values with power and throttle commands to
+   * target a specific hardware connection when multiple are configured.
+   *
+   * @example
+   * ```typescript
+   * const connections = await client.getSystemConnections();
+   * // [{ name: 'LocoNet', prefix: 'L' }, { name: 'DCC++', prefix: 'D' }]
+   * await client.powerOn('L'); // power on via LocoNet only
+   * ```
    */
-  async powerOff() {
-    return this.powerManager.powerOff();
+  async getSystemConnections() {
+    return this.systemConnectionsManager.getSystemConnections();
   }
   // ============================================================================
   // Roster Management

package/dist/cjs/client.js

@@ -11,6 +11,7 @@ const roster_manager_js_1 = require("./managers/roster-manager.js");
 const throttle_manager_js_1 = require("./managers/throttle-manager.js");
 const turnout_manager_js_1 = require("./managers/turnout-manager.js");
 const light_manager_js_1 = require("./managers/light-manager.js");
+const system_connections_manager_js_1 = require("./managers/system-connections-manager.js");
 const client_options_js_1 = require("./types/client-options.js");
 /**
  * JMRI WebSocket Client
@@ -45,6 +46,7 @@ class JmriClient extends eventemitter3_1.EventEmitter {
         this.throttleManager = new throttle_manager_js_1.ThrottleManager(this.wsClient);
         this.turnoutManager = new turnout_manager_js_1.TurnoutManager(this.wsClient);
         this.lightManager = new light_manager_js_1.LightManager(this.wsClient);
+        this.systemConnectionsManager = new system_connections_manager_js_1.SystemConnectionsManager(this.wsClient);
         // Forward events from WebSocket client
         this.wsClient.on('connected', () => this.emit('connected'));
         this.wsClient.on('disconnected', (reason) => this.emit('disconnected', reason));
@@ -104,27 +106,50 @@ class JmriClient extends eventemitter3_1.EventEmitter {
     // ============================================================================
     /**
      * Get current track power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async getPower() {
-        return this.powerManager.getPower();
+    async getPower(prefix) {
+        return this.powerManager.getPower(prefix);
     }
     /**
      * Set track power state
+     * @param state - The desired power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async setPower(state) {
-        return this.powerManager.setPower(state);
+    async setPower(state, prefix) {
+        return this.powerManager.setPower(state, prefix);
     }
     /**
      * Turn track power on
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOn() {
-        return this.powerManager.powerOn();
+    async powerOn(prefix) {
+        return this.powerManager.powerOn(prefix);
     }
     /**
      * Turn track power off
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOff() {
-        return this.powerManager.powerOff();
+    async powerOff(prefix) {
+        return this.powerManager.powerOff(prefix);
+    }
+    // ============================================================================
+    // System Connections
+    // ============================================================================
+    /**
+     * List all available JMRI system connections and their prefixes.
+     * Use the returned prefix values with power and throttle commands to
+     * target a specific hardware connection when multiple are configured.
+     *
+     * @example
+     * ```typescript
+     * const connections = await client.getSystemConnections();
+     * // [{ name: 'LocoNet', prefix: 'L' }, { name: 'DCC++', prefix: 'D' }]
+     * await client.powerOn('L'); // power on via LocoNet only
+     * ```
+     */
+    async getSystemConnections() {
+        return this.systemConnectionsManager.getSystemConnections();
     }
     // ============================================================================
     // Roster Management

package/dist/cjs/managers/index.js

@@ -22,3 +22,4 @@ __exportStar(require("./roster-manager.js"), exports);
 __exportStar(require("./throttle-manager.js"), exports);
 __exportStar(require("./turnout-manager.js"), exports);
 __exportStar(require("./light-manager.js"), exports);
+__exportStar(require("./system-connections-manager.js"), exports);

package/dist/cjs/managers/power-manager.js

@@ -23,10 +23,12 @@ class PowerManager extends eventemitter3_1.EventEmitter {
     }
     /**
      * Get current track power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async getPower() {
+    async getPower(prefix) {
         const message = {
-            type: 'power'
+            type: 'power',
+            ...(prefix !== undefined && { data: { state: jmri_messages_js_1.PowerState.UNKNOWN, prefix } })
         };
         const response = await this.client.request(message);
         if (response.data?.state !== undefined) {
@@ -36,12 +38,14 @@ class PowerManager extends eventemitter3_1.EventEmitter {
     }
     /**
      * Set track power state
+     * @param state - The desired power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async setPower(state) {
+    async setPower(state, prefix) {
         const message = {
             type: 'power',
             method: 'post',
-            data: { state }
+            data: { state, ...(prefix !== undefined && { prefix }) }
         };
         await this.client.request(message);
         const oldState = this.currentState;
@@ -52,15 +56,17 @@ class PowerManager extends eventemitter3_1.EventEmitter {
     }
     /**
      * Turn track power on
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOn() {
-        await this.setPower(jmri_messages_js_1.PowerState.ON);
+    async powerOn(prefix) {
+        await this.setPower(jmri_messages_js_1.PowerState.ON, prefix);
     }
     /**
      * Turn track power off
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOff() {
-        await this.setPower(jmri_messages_js_1.PowerState.OFF);
+    async powerOff(prefix) {
+        await this.setPower(jmri_messages_js_1.PowerState.OFF, prefix);
     }
     /**
      * Get cached power state (no network request)

package/dist/cjs/managers/system-connections-manager.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * System connections manager — discovers available JMRI hardware connection prefixes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemConnectionsManager = void 0;
+class SystemConnectionsManager {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all available JMRI system connections and their prefixes.
+     * Use the returned prefix values with power and throttle commands to
+     * target a specific hardware connection when multiple are configured.
+     */
+    async getSystemConnections() {
+        const message = {
+            type: 'systemConnections',
+            method: 'list'
+        };
+        const response = await this.client.request(message);
+        if (!response.data) {
+            return [];
+        }
+        return Array.isArray(response.data) ? response.data : [response.data];
+    }
+}
+exports.SystemConnectionsManager = SystemConnectionsManager;

package/dist/cjs/managers/throttle-manager.js

@@ -37,7 +37,8 @@ class ThrottleManager extends eventemitter3_1.EventEmitter {
             type: 'throttle',
             data: {
                 name: throttleName,
-                address: options.address
+                address: options.address,
+                ...(options.prefix !== undefined && { prefix: options.prefix })
             }
         };
         const response = await this.client.request(message);

package/dist/esm/client.js

@@ -8,6 +8,7 @@ import { RosterManager } from './managers/roster-manager.js';
 import { ThrottleManager } from './managers/throttle-manager.js';
 import { TurnoutManager } from './managers/turnout-manager.js';
 import { LightManager } from './managers/light-manager.js';
+import { SystemConnectionsManager } from './managers/system-connections-manager.js';
 import { mergeOptions } from './types/client-options.js';
 /**
  * JMRI WebSocket Client
@@ -42,6 +43,7 @@ export class JmriClient extends EventEmitter {
         this.throttleManager = new ThrottleManager(this.wsClient);
         this.turnoutManager = new TurnoutManager(this.wsClient);
         this.lightManager = new LightManager(this.wsClient);
+        this.systemConnectionsManager = new SystemConnectionsManager(this.wsClient);
         // Forward events from WebSocket client
         this.wsClient.on('connected', () => this.emit('connected'));
         this.wsClient.on('disconnected', (reason) => this.emit('disconnected', reason));
@@ -101,27 +103,50 @@ export class JmriClient extends EventEmitter {
     // ============================================================================
     /**
      * Get current track power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async getPower() {
-        return this.powerManager.getPower();
+    async getPower(prefix) {
+        return this.powerManager.getPower(prefix);
     }
     /**
      * Set track power state
+     * @param state - The desired power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async setPower(state) {
-        return this.powerManager.setPower(state);
+    async setPower(state, prefix) {
+        return this.powerManager.setPower(state, prefix);
     }
     /**
      * Turn track power on
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOn() {
-        return this.powerManager.powerOn();
+    async powerOn(prefix) {
+        return this.powerManager.powerOn(prefix);
     }
     /**
      * Turn track power off
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOff() {
-        return this.powerManager.powerOff();
+    async powerOff(prefix) {
+        return this.powerManager.powerOff(prefix);
+    }
+    // ============================================================================
+    // System Connections
+    // ============================================================================
+    /**
+     * List all available JMRI system connections and their prefixes.
+     * Use the returned prefix values with power and throttle commands to
+     * target a specific hardware connection when multiple are configured.
+     *
+     * @example
+     * ```typescript
+     * const connections = await client.getSystemConnections();
+     * // [{ name: 'LocoNet', prefix: 'L' }, { name: 'DCC++', prefix: 'D' }]
+     * await client.powerOn('L'); // power on via LocoNet only
+     * ```
+     */
+    async getSystemConnections() {
+        return this.systemConnectionsManager.getSystemConnections();
     }
     // ============================================================================
     // Roster Management

package/dist/esm/managers/index.js

@@ -6,3 +6,4 @@ export * from './roster-manager.js';
 export * from './throttle-manager.js';
 export * from './turnout-manager.js';
 export * from './light-manager.js';
+export * from './system-connections-manager.js';

package/dist/esm/managers/power-manager.js

@@ -20,10 +20,12 @@ export class PowerManager extends EventEmitter {
     }
     /**
      * Get current track power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async getPower() {
+    async getPower(prefix) {
         const message = {
-            type: 'power'
+            type: 'power',
+            ...(prefix !== undefined && { data: { state: PowerState.UNKNOWN, prefix } })
         };
         const response = await this.client.request(message);
         if (response.data?.state !== undefined) {
@@ -33,12 +35,14 @@ export class PowerManager extends EventEmitter {
     }
     /**
      * Set track power state
+     * @param state - The desired power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async setPower(state) {
+    async setPower(state, prefix) {
         const message = {
             type: 'power',
             method: 'post',
-            data: { state }
+            data: { state, ...(prefix !== undefined && { prefix }) }
         };
         await this.client.request(message);
         const oldState = this.currentState;
@@ -49,15 +53,17 @@ export class PowerManager extends EventEmitter {
     }
     /**
      * Turn track power on
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOn() {
-        await this.setPower(PowerState.ON);
+    async powerOn(prefix) {
+        await this.setPower(PowerState.ON, prefix);
     }
     /**
      * Turn track power off
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    async powerOff() {
-        await this.setPower(PowerState.OFF);
+    async powerOff(prefix) {
+        await this.setPower(PowerState.OFF, prefix);
     }
     /**
      * Get cached power state (no network request)

package/dist/esm/managers/system-connections-manager.js

@@ -0,0 +1,24 @@
+/**
+ * System connections manager — discovers available JMRI hardware connection prefixes
+ */
+export class SystemConnectionsManager {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all available JMRI system connections and their prefixes.
+     * Use the returned prefix values with power and throttle commands to
+     * target a specific hardware connection when multiple are configured.
+     */
+    async getSystemConnections() {
+        const message = {
+            type: 'systemConnections',
+            method: 'list'
+        };
+        const response = await this.client.request(message);
+        if (!response.data) {
+            return [];
+        }
+        return Array.isArray(response.data) ? response.data : [response.data];
+    }
+}

package/dist/esm/managers/throttle-manager.js

@@ -34,7 +34,8 @@ export class ThrottleManager extends EventEmitter {
             type: 'throttle',
             data: {
                 name: throttleName,
-                address: options.address
+                address: options.address,
+                ...(options.prefix !== undefined && { prefix: options.prefix })
             }
         };
         const response = await this.client.request(message);

package/dist/types/client.d.ts

@@ -4,7 +4,7 @@
 import { EventEmitter } from 'eventemitter3';
 import { WebSocketClient } from './core/websocket-client.js';
 import { PartialClientOptions } from './types/client-options.js';
-import { PowerState, RosterEntryWrapper, TurnoutState, TurnoutData, LightState, LightData } from './types/jmri-messages.js';
+import { PowerState, RosterEntryWrapper, TurnoutState, TurnoutData, LightState, LightData, SystemConnectionData } from './types/jmri-messages.js';
 import { ConnectionState } from './types/events.js';
 import { ThrottleAcquireOptions, ThrottleFunctionKey, ThrottleState } from './types/throttle.js';
 /**
@@ -19,6 +19,7 @@ export declare class JmriClient extends EventEmitter {
     private throttleManager;
     private turnoutManager;
     private lightManager;
+    private systemConnectionsManager;
     /**
      * Create a new JMRI client
      *
@@ -55,20 +56,38 @@ export declare class JmriClient extends EventEmitter {
     isConnected(): boolean;
     /**
      * Get current track power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    getPower(): Promise<PowerState>;
+    getPower(prefix?: string): Promise<PowerState>;
     /**
      * Set track power state
+     * @param state - The desired power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    setPower(state: PowerState): Promise<void>;
+    setPower(state: PowerState, prefix?: string): Promise<void>;
     /**
      * Turn track power on
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    powerOn(): Promise<void>;
+    powerOn(prefix?: string): Promise<void>;
     /**
      * Turn track power off
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    powerOff(): Promise<void>;
+    powerOff(prefix?: string): Promise<void>;
+    /**
+     * List all available JMRI system connections and their prefixes.
+     * Use the returned prefix values with power and throttle commands to
+     * target a specific hardware connection when multiple are configured.
+     *
+     * @example
+     * ```typescript
+     * const connections = await client.getSystemConnections();
+     * // [{ name: 'LocoNet', prefix: 'L' }, { name: 'DCC++', prefix: 'D' }]
+     * await client.powerOn('L'); // power on via LocoNet only
+     * ```
+     */
+    getSystemConnections(): Promise<SystemConnectionData[]>;
     /**
      * Get all roster entries
      */

package/dist/types/managers/index.d.ts

@@ -6,3 +6,4 @@ export * from './roster-manager.js';
 export * from './throttle-manager.js';
 export * from './turnout-manager.js';
 export * from './light-manager.js';
+export * from './system-connections-manager.js';

package/dist/types/managers/power-manager.d.ts

@@ -13,20 +13,25 @@ export declare class PowerManager extends EventEmitter {
     constructor(client: WebSocketClient);
     /**
      * Get current track power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    getPower(): Promise<PowerState>;
+    getPower(prefix?: string): Promise<PowerState>;
     /**
      * Set track power state
+     * @param state - The desired power state
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    setPower(state: PowerState): Promise<void>;
+    setPower(state: PowerState, prefix?: string): Promise<void>;
     /**
      * Turn track power on
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    powerOn(): Promise<void>;
+    powerOn(prefix?: string): Promise<void>;
     /**
      * Turn track power off
+     * @param prefix - Optional JMRI connection prefix to target a specific hardware connection
      */
-    powerOff(): Promise<void>;
+    powerOff(prefix?: string): Promise<void>;
     /**
      * Get cached power state (no network request)
      */

package/dist/types/managers/system-connections-manager.d.ts

@@ -0,0 +1,15 @@
+/**
+ * System connections manager — discovers available JMRI hardware connection prefixes
+ */
+import { WebSocketClient } from '../core/websocket-client.js';
+import { SystemConnectionData } from '../types/jmri-messages.js';
+export declare class SystemConnectionsManager {
+    private client;
+    constructor(client: WebSocketClient);
+    /**
+     * List all available JMRI system connections and their prefixes.
+     * Use the returned prefix values with power and throttle commands to
+     * target a specific hardware connection when multiple are configured.
+     */
+    getSystemConnections(): Promise<SystemConnectionData[]>;
+}

package/dist/types/types/jmri-messages.d.ts

@@ -33,6 +33,7 @@ export declare function powerStateToString(state: PowerState): string;
  */
 export interface PowerData {
     state: PowerState;
+    prefix?: string;
 }
 /**
  * Power message
@@ -41,6 +42,21 @@ export interface PowerMessage extends JmriMessage {
     type: 'power';
     data?: PowerData;
 }
+/**
+ * System connection data (from JMRI systemConnections list)
+ */
+export interface SystemConnectionData {
+    name: string;
+    prefix: string;
+    userName?: string;
+}
+/**
+ * System connections message
+ */
+export interface SystemConnectionsMessage extends JmriMessage {
+    type: 'systemConnections';
+    data?: SystemConnectionData | SystemConnectionData[];
+}
 /**
  * Throttle data structure
  */
@@ -51,6 +67,7 @@ export interface ThrottleData {
     forward?: boolean;
     release?: null;
     status?: string;
+    prefix?: string;
     F0?: boolean;
     F1?: boolean;
     F2?: boolean;
@@ -263,4 +280,4 @@ export interface ErrorMessage extends JmriMessage {
 /**
  * Union type of all possible JMRI messages
  */
-export type AnyJmriMessage = PowerMessage | ThrottleMessage | RosterMessage | TurnoutMessage | LightMessage | PingMessage | PongMessage | HelloMessage | GoodbyeMessage | ErrorMessage;
+export type AnyJmriMessage = PowerMessage | ThrottleMessage | RosterMessage | TurnoutMessage | LightMessage | SystemConnectionsMessage | PingMessage | PongMessage | HelloMessage | GoodbyeMessage | ErrorMessage;

package/dist/types/types/throttle.d.ts

@@ -13,6 +13,12 @@ export interface ThrottleAcquireOptions {
      * Whether this is a long address (default: true for addresses > 127)
      */
     isLongAddress?: boolean;
+    /**
+     * JMRI connection prefix to target a specific hardware connection.
+     * When omitted, routes to the default connection manager.
+     * Use getSystemConnections() to discover available prefixes.
+     */
+    prefix?: string;
 }
 /**
  * Throttle function key (F0-F28)

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.1.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",