JMRI Integration Guide

JMRI (Java Model Railroad Interface) is widely used for DCC decoder programming, rosters, panels, sensors, and layout control. RailScanPro can work with JMRI data in several places, including roster import/export and RailCommand layout import.

What JMRI Can Provide

For live train running, prefer the RailCommand desktop app and local runtime workflow. JMRI may still be part of your hardware environment, but RailCommand's operator docs should be followed for live RailCommand sessions.

Prerequisites

• JMRI 5.0 or later running on a computer on your local network
• A saved JMRI roster or exported layout/panel file, depending on the workflow
• RailScanPro access to the target organization and layout
• A RailCommand layout when importing layout-specific data

Roster Import

Use roster import when you want RailScanPro to know about locomotives already defined in JMRI.

1. In RailScanPro, open /app/settings/integrations/jmri.
2. Choose the roster import flow.
3. Upload or select the JMRI roster data.
4. Review matched locomotives.
5. Approve new draft records or update existing inventory records.

RailScanPro is the home for photos, collection details, reporting, and operational assignments. JMRI can remain the home for DecoderPro-specific decoder setup if that is how your railroad is managed.

Roster Export

Use roster export when you want RailScanPro data available for JMRI workflows.

Open /app/settings/integrations/jmri/export and follow the export prompts.

Switching from JMRI: New Layout from JMRI

Use this when you want your JMRI railroad to become a new RailCommand layout, roster included.

1. Open RailCommand Layouts (/app/railcommand/layouts) and click Import from JMRI, or go straight to /app/railcommand/layouts/import/jmri.
2. Choose your JMRI panel file: the XML file JMRI writes with File, Store, Store Configuration and Panels.
3. Optionally choose your JMRI roster file: roster.xml from the JMRI roster folder.
4. Pick the scale (a JMRI panel file does not record one), confirm you own the files, and click Analyze files.
5. Review the tabs. Turnouts carry their DCC accessory addresses and JMRI system names. Sensors carry their addresses: an NCE AIU sensor keeps its AIU and input, and a LocoNet sensor its board and input. Every JMRI block is listed with its occupancy sensor. The Roster tab lists the locomotives with DCC address, road name and number, and decoder.
6. Read the Warnings tab. Everything the import does not bring across is listed there with the reason: JMRI internal sensors that are not drawn as a panel control (Logix state), lights drawn on no panel, routes, Logix, sections and transits.
7. Answer How will you run this layout? above the Create button. Run trains (like TrainController): open RailCommand and drive is selected for you: you open RailCommand on the layout and drive, the way TrainController worked. Choose Operating sessions (clubs and museums: crew, dispatcher, car forwarding) if you run formal sessions with a crew. You can switch to operating sessions at any time from the layout's page.
8. Click Create layout. The layout is created and the roster is added to your inventory and assigned to the new layout.

What the new layout looks like:

• Each JMRI panel becomes a RailCommand panel with its turnouts, hardware sensors and text labels where the JMRI icons were.
• A Panel Editor panel drawn with JMRI's own track icons (the USS track and USS panels track segment sets, the Control Panel Editor track sets and the small schematics) gets its track rebuilt on the grid, and each turnout sits on the track its icon draws. A crossover drawn with one JMRI turnout becomes a turnout at each end with the same address, so one command throws both. A turnout picture with no JMRI turnout behind it becomes a hand-thrown turnout with no address.
• Track that no JMRI block covers gets a dark block named from its first cell (for example B 7:12), listed on the Blocks tab with an Include box to confirm, rename or give detection. A dead end (a spur ending at a bumper) starts checked; track between turnouts or other features, a loop, or a piece joined to no turnout is only suggested and starts unchecked. A short stretch between two turnouts (under 3 cells) belongs to their interlocking and gets no block.
• The Warnings tab lists, for each rebuilt panel, how many track icons were read and turnouts placed, track icons that join no other track, places where two tracks were drawn closer together than one grid cell, JMRI track icons the grid cannot draw (wyes, slips, three-way turnouts, 90 degree crossings, icons turned by other than 45 degree steps), and custom images that are not part of JMRI's icon sets.
• A panel drawn only with custom images keeps its turnouts and sensors where the icons were, with no track; draw that track in the layout editor.
• A Blocks panel draws every JMRI block from a Panel Editor file as its own short track with its occupancy sensor on it, because a panel picture does not say which block it shows.
• The dispatcher's controls come across as RailCommand panel controls where their icons sat, listed on the Controls tab: a CTC lever or switch plate becomes an on/off switch, a push button (a momentary icon) a push button, and a lamp (a light icon, or a sensor drawn as a lamp) an indicator lamp in its lit colour, flashing if JMRI draws it blinking. Each is named after the JMRI sensor or light behind it, and its notes say what it drove in JMRI: the sensor a lever sets, the JMRI routes that sensor fires (for example on: fires JMRI route 'CP 5 Reverse'), and the light or sensor a lamp follows.
• JMRI routes are not imported as routes, because RailCommand derives its routes from the track diagram. The Warnings tab lists each JMRI route with the turnout positions it sets and the sensors that fire it, so you can check the routes RailCommand derives against the ones your club ran.
• RailCommand does not run JMRI Logix or JMRI routes. The Warnings tab lists, for each control and lamp, the Logix that set or read it, so you can recreate that behaviour as RailCommand rules. JMRI lights drawn with signal pictures are listed too: they import as lamps, so add a real signal on the track where one stands for a signal.
• Turnouts and sensors that no JMRI panel shows go on a panel named Not on a JMRI panel.
• A panel drawn in JMRI's Layout Editor gets its track converted, because the Layout Editor records how every piece joins: the track is joined exactly as in JMRI and only the drawing is fitted to the grid. Each turnout sits on its points with its address, turned the way JMRI draws its legs. A crossover becomes a turnout at each end joined by a diagonal (a double crossover becomes two crossovers back to back, which gives the same routes), each with the JMRI turnout's address; a crossover driven by two JMRI turnouts gives the far track's turnouts the second address. A level crossing becomes a diamond. A slip becomes a diamond too, because an import cannot place a slip: its JMRI turnouts go beside it with their addresses, and the Warnings tab asks you to replace the crossing with a slip in the layout editor. A wye becomes a turnout whose B leg runs straight on. A turntable becomes a turntable with a track on each ray direction. An edge connector becomes an off-page connector paired with its partner on the other panel, and an end bumper ends the track.
• Each JMRI block on a Layout Editor panel goes on the track its segments name, with its occupancy sensor (JMRI keeps the sensor on the Layout Editor block). A JMRI block that runs through a turnout becomes one block on each side of it, numbered (Main, Main (2)), all reading the same sensor, because a RailCommand block never contains a turnout. Only a JMRI block that covers turnouts, crossings or turntables alone stays on the Blocks panel, listed on the Warnings tab.
• The Warnings tab lists, for each converted Layout Editor panel, how many track segments were read and turnouts, blocks and crossings placed, every piece drawn differently from JMRI and why, track that ends because the file stops describing it, and each place to check (for example two tracks JMRI draws crossing without a crossing, such as a bridge). A drawing whose tracks JMRI draws closer together than the usual grid cell is drawn on a finer grid, and the Warnings tab says so. A Layout Editor drawing that cannot be converted keeps its turnouts and sensors where JMRI draws them, with the reason listed.
• A signal drawn on a Panel Editor panel is placed on the rebuilt track cell nearest its icon and governs trains running the way the icon points (a left-hand JMRI signal picture points west, a right-hand one east, turned with the icon), so its face points the other way, toward those trains: a signal whose icon points east faces west. The Warnings tab lists each placed signal, the trains it governs and the way its face points; check them on the Signals tab. A signal whose picture shows no direction asks there which way its face points before the layout is created.
• A signal JMRI anchors on Layout Editor track stands on the converted track: a track point's eastbound signal governs trains running east (south on track drawn upright), so its face points west toward them, and its westbound signal the other way, and a signal on a turnout, crossing or slip leg stands on that leg and faces the trains approaching the turnout along it. The Warnings tab lists each one and the way its face points. A JMRI signal uses RailCommand signalling: RailCommand works its aspects out from the block end or switch it belongs to.
• A signal whose icon has no track within a cell of it, or that is anchored on a Layout Editor panel whose drawing could not be converted, gets that position but is left out, because it protects no track the import drew. Include it once it is on its track.
• A signal no panel draws is listed on the Signals tab without a position. Give it a position (row/column, as TrainController shows it, for example 23/02) to import it, or add it later in the layout editor.

If the panel file was saved while its NCE or LocoNet connection was not loaded, JMRI lists the turnouts and sensors as internal. The import reads the hardware name each panel icon still carries (for example NT41) and says so on the Warnings tab.

Re-import from JMRI into an Existing Layout

A club that keeps editing its JMRI panels can bring each new version across into the same layout.

1. Open the layout (/app/railcommand/layouts/{LayoutId}) and its Import tab.
2. On the JMRI re-import card, click Re-import from JMRI.
3. Choose the updated JMRI panel file and, optionally, the roster file, confirm you own them, and click Analyze files. The layout keeps its name and its scale, and the roster uses that scale.
4. Review the same tabs as a new import, then click Re-import. A re-import does not ask how the layout runs: it keeps its Run trains or Operating sessions choice.

A re-import replaces the layout's track, turnouts, sensors, blocks, signals and panel controls with what the JMRI files hold now. Changes made in RailCommand since the last import that the file does not hold are lost; the previous content is kept (soft-deleted) and support can restore it. The roster is matched to your inventory by JMRI roster id, so locomotives already imported are matched rather than added again, and every roster locomotive is assigned to the layout.

Live Dispatching Context

RailCommand CTC and desktop operator surfaces depend on current layout, hardware, runtime, and session state. If your railroad uses JMRI for detectors, turnouts, or command-station access, confirm the RailCommand hardware and runtime setup before assuming live state will appear.

Useful RailCommand pages:

• Connection manager: /app/railcommand/connection
• Hardware settings: /app/railcommand/layouts/{LayoutId}/hardware
• CTC panel: /app/railcommand/layouts/{LayoutId}/ctc-panel
• Desktop app: /downloads

Troubleshooting

Roster import does not find locomotives - Confirm the JMRI roster was saved/exported and that the file is the one you intended to import.

Imported locomotives do not match existing inventory - Check road name, road number, DCC address, manufacturer, and model number. You may need to approve draft records manually.

Layout import looks incomplete - JMRI panel data may not contain all RailCommand operating details. Add industries, staging, car routing, and session details after import.

Live hardware state is missing - Check RailCommand hardware setup, local runtime status, the command station, and whether JMRI is actually part of the configured live path.

Next Steps

• RailCommand Layout and Panel Editors — define the layout that JMRI data can support
• Operations Intro — understand the full operations system
• Car Cards & Waybills — add car routing on top of JMRI hardware control