jmri-client 4.1.0 → 4.2.0-beta.1

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

@@ -42,6 +42,12 @@ client.on('error', (error: Error) => { });
 // Power events
 client.on('power:changed', (state: PowerState) => { });
 
+// Turnout events
+client.on('turnout:changed', (name: string, state: TurnoutState) => { });
+
+// Light events
+client.on('light:changed', (name: string, state: LightState) => { });
+
 // Throttle events
 client.on('throttle:acquired', (throttleId: string) => { });
 client.on('throttle:updated', (throttleId: string, data: any) => { });
@@ -106,6 +112,38 @@ const entry = await client.getRosterEntryByAddress(3);
 const results = await client.searchRoster('steam');
 ```
 
+## Light Control
+
+```typescript
+// Get current light state
+const state: LightState = await client.getLight('IL1');
+
+// LightState enum values (from JMRI JSON protocol):
+// LightState.UNKNOWN = 0  (state cannot be determined)
+// LightState.ON = 2       (light is on)
+// LightState.OFF = 4      (light is off)
+
+// Set light state
+await client.setLight('IL1', LightState.ON);
+await client.turnOnLight('IL1');   // Convenience method
+await client.turnOffLight('IL1');  // Convenience method
+
+// List all lights
+const lights: LightData[] = await client.listLights();
+for (const light of lights) {
+  console.log(`${light.userName}: ${light.state === LightState.ON ? 'ON' : 'OFF'}`);
+}
+
+// Cached state (no network request)
+const cachedState = client.getLightState('IL1');
+const allCached = client.getCachedLights();
+
+// Listen for light changes
+client.on('light:changed', (name: string, state: LightState) => {
+  console.log(`Light ${name} changed to ${state === LightState.ON ? 'ON' : 'OFF'}`);
+});
+```
+
 ## Throttle Control
 
 ```typescript
@@ -165,12 +203,15 @@ const state = client.getConnectionState();
 ## Utility Functions
 
 ```typescript
-import { powerStateToString, isThrottleFunctionKey, isValidSpeed } from 'jmri-client';
+import { powerStateToString, lightStateToString, isThrottleFunctionKey, isValidSpeed } from 'jmri-client';
 
 // Convert PowerState enum to readable string
 const stateStr = powerStateToString(PowerState.ON);  // 'ON'
 const stateStr2 = powerStateToString(PowerState.UNKNOWN);  // 'UNKNOWN'
 
+// Convert LightState enum to readable string
+const lightStr = lightStateToString(LightState.ON);  // 'ON'
+
 // Validate throttle function key
 isThrottleFunctionKey('F0');  // true
 isThrottleFunctionKey('F99');  // false
@@ -189,7 +230,11 @@ import {
   JmriClient,
   JmriClientOptions,
   PowerState,
+  LightState,
+  LightData,
   RosterEntry,
+  TurnoutState,
+  TurnoutData,
   ThrottleState,
   ThrottleFunctionKey,
   ConnectionState

package/docs/EXAMPLES.md

@@ -113,6 +113,37 @@ client.on('connected', async () => {
 });
 ```
 
+## Light Control
+
+```typescript
+import { JmriClient, LightState } from 'jmri-client';
+
+const client = new JmriClient({ host: 'jmri.local' });
+
+client.on('connected', async () => {
+  // List all lights
+  const lights = await client.listLights();
+  console.log(`Found ${lights.length} lights`);
+
+  for (const light of lights) {
+    console.log(`  ${light.userName ?? light.name}: ${light.state === LightState.ON ? 'ON' : 'OFF'}`);
+  }
+
+  // Turn a light on
+  await client.turnOnLight('IL1');
+  console.log('Light IL1 turned ON');
+
+  // Turn it off again
+  await client.turnOffLight('IL1');
+  console.log('Light IL1 turned OFF');
+});
+
+// Monitor light changes in real-time
+client.on('light:changed', (name, state) => {
+  console.log(`Light ${name} is now ${state === LightState.ON ? 'ON' : 'OFF'}`);
+});
+```
+
 ## Roster Search
 
 ```typescript

package/docs/MOCK_MODE.md

@@ -72,6 +72,18 @@ Three sample locomotives:
 
 Each includes realistic function key mappings (F0-F4).
 
+### Lights
+Three sample lights:
+- **IL1** - Yard Light (OFF)
+- **IL2** - Platform Light (OFF)
+- **IL3** - Signal Lamp (ON)
+
+### Turnouts
+Three sample turnouts:
+- **LT1** - Main Diverge (CLOSED)
+- **LT2** - Yard Lead (CLOSED)
+- **LT3** - Siding Entry (THROWN)
+
 ### Throttle Responses
 Supports all throttle operations:
 - Acquire/release
@@ -152,6 +164,8 @@ const response = await mockManager.getMockResponse({
 The mock system maintains state for realistic behavior:
 
 - **Power state** - Remembers if power is ON or OFF
+- **Light states** - Tracks ON/OFF state per light
+- **Turnout states** - Tracks CLOSED/THROWN state per turnout
 - **Throttles** - Tracks acquired throttles and their states
 - **Speed/Direction** - Maintains current speed and direction per throttle
 - **Functions** - Tracks function key states (F0-F28)
@@ -196,6 +210,8 @@ Mock mode implements the full JMRI client API. All methods work identically:
 - ✅ `connect()` / `disconnect()`
 - ✅ `getPower()` / `powerOn()` / `powerOff()`
 - ✅ `getRoster()`
+- ✅ `getLight()` / `setLight()` / `turnOnLight()` / `turnOffLight()` / `listLights()`
+- ✅ `getTurnout()` / `setTurnout()` / `throwTurnout()` / `closeTurnout()` / `listTurnouts()`
 - ✅ `acquireThrottle()` / `releaseThrottle()`
 - ✅ `setThrottleSpeed()`
 - ✅ `setThrottleDirection()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jmri-client",
-  "version": "4.1.0",
+  "version": "4.2.0-beta.1",
   "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",