jmri-client

WebSocket client for JMRI with real-time updates and full throttle control.

Features

• ✅ WebSocket-based - Real-time bidirectional communication
• ✅ Event-driven - Subscribe to power changes, throttle updates, and more
• ✅ Full Throttle Control - Speed (0.0-1.0), direction, and functions (F0-F28)
• ✅ Browser & Node.js - Works in browsers and Node.js with auto-detection
• ✅ Mock Mode - Test and demo without JMRI hardware
• ✅ Auto-reconnection - Exponential backoff with jitter
• ✅ 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

npm install jmri-client

Requirements: Node.js 22+ · JMRI 5.0 or later

getSystemConnections() and per-connection power/throttle prefix support require JMRI 5.15.7+. All other features work with any JMRI 5.x release.

Quick Start

import { JmriClient, PowerState } from 'jmri-client';

// Create client
const client = new JmriClient({
  host: 'jmri.local',
  port: 12080
});

// Listen for events
client.on('connected', () => console.log('Connected!'));
client.on('power:changed', (state) => {
  const stateStr = state === PowerState.ON ? 'ON' :
                   state === PowerState.OFF ? 'OFF' : 'UNKNOWN';
  console.log('Power:', stateStr);
});

// Control power
await client.powerOn();

// Acquire and control a throttle
const throttleId = await client.acquireThrottle({ address: 3 });
await client.setThrottleSpeed(throttleId, 0.5);  // 50% speed
await client.setThrottleDirection(throttleId, true);  // Forward
await client.setThrottleFunction(throttleId, 'F0', true);  // Headlight on

// Clean up
await client.releaseThrottle(throttleId);
await client.disconnect();

Documentation

• API Reference - Complete API documentation
• Browser Usage - Using jmri-client in web browsers
• Examples - Common usage patterns
• Mock Mode - Testing without hardware
• Migration Guide - Upgrading from v2.x
• Troubleshooting - Common issues and solutions

Key Concepts

Event-Driven Architecture

Subscribe to real-time updates from JMRI:

client.on('connected', () => { });
client.on('disconnected', (reason) => { });
client.on('power:changed', (state) => { });
client.on('throttle:updated', (id, data) => { });

Throttle Control

Full control of DCC locomotives:

const throttle = await client.acquireThrottle({ address: 3 });
await client.setThrottleSpeed(throttle, 0.5);
await client.setThrottleDirection(throttle, true);
await client.setThrottleFunction(throttle, 'F0', true);
await client.releaseThrottle(throttle);

Auto-Reconnection

Automatically reconnects with exponential backoff:

client.on('reconnecting', (attempt, delay) => {
  console.log(`Reconnecting attempt ${attempt} in ${delay}ms`);
});

Multi-Connection Support

When JMRI has multiple hardware connections configured, use getSystemConnections() to discover their prefixes and pass them to power and throttle commands:

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):

import { JmriClient } from 'jmri-client';
import type { PartialClientOptions } from 'jmri-client';

class MyExtendedClient extends JmriClient {
  constructor(options?: PartialClientOptions) {
    super(options);

    // this.wsClient is available — use it to send/receive JMRI JSON messages
    this.wsClient.on('update', (message: any) => {
      if (message.type === 'sensor') {
        this.emit('sensor:changed', message.data.name, message.data.state);
      }
    });
  }

  async listSensors() {
    const response = await this.wsClient.request({ type: 'sensor', method: 'list' });
    return Array.isArray(response?.data)
      ? response.data.map((r: any) => r.data ?? r)
      : [];
  }
}

WebSocketClient is also exported for direct use if you need it. See its send(), request(), and on('update', ...) API for low-level messaging.

Testing

Unit Tests (no hardware required):

npm test

Mock Mode Demo (no hardware required):

npm run demo:mock

Functional Test (requires JMRI hardware):

npm run functional

⚠️ Safety: Includes automatic power-off on exit, errors, and Ctrl+C.

See Mock Mode Guide and Testing Guide for complete instructions.

Contributing

Issues and pull requests welcome! Please see the GitHub repository.

License

MIT

Links

• GitHub Repository
• NPM Package
• JMRI Project
• JMRI JSON Protocol