Concept
Importing a TrainController project is how most operators create their first RailCommand layout. You upload a .yrrg or .yrl file (up to 50 MB) and RailScanPro builds a brand-new layout from it: the track plan, switchboards, accessories, and — optionally — your roster and trains.
The mental model is derived-not-stored. Your file is parsed into a staged preview; nothing is saved until you press Create. The graph, signal topology, and block wiring are not copied verbatim — they are derived when the layout is created. In between, you review the decoded objects in per-type Transform Tables and resolve anything the decoder flagged instead of guessing. Import is web-only — it always happens in the browser.
On the Blocks table, a block that decodes with no occupancy source at all — no wired contact and no flagman (computed) member — shows a dark territory? suggestion (#1618). Checking it marks the block dark at commit: no detection by design, occupancy not tracked, the dark-neutral display. The importer only ever suggests; it never assumes a block is dark.
The importer also reads the connection labels TrainController draws beside a panel's contacts — the text on an AIU-pin panel, for example. These are not a reviewable Transform Table row: they materialize directly as text cells on the matching switchboard panel when the layout is created, so you see them on the schematic rather than in the review. A label whose decoded position falls outside its panel's grid, or onto a cell something else already occupies, is named in the create-time warnings and left unplaced rather than guessed onto a cell — its text was read correctly, its position was not. Because this decoding happens while the file is parsed, a layout imported before it shipped does not gain the labels by re-deriving: the file has to be imported again.
Label decoding is calibrated on files from current TrainController versions. A file saved by an older one — the import names it as declaring the legacy v9 field marker rather than the modern marker — is read on the marker the file itself declares, but that vintage frames the label records differently, so some or all of its labels may still not decode. The import warns about this on the Warnings tab and reports how many it did decode. On such a file a low or zero label count means undecoded, never that the layout has no labels.
How To
Prerequisites: a TrainController .yrrg/.yrl export (max 50 MB); you own the file or are authorized to import it; you are signed in as the organization that will own the layout.
- From RailCommand Layouts (
/app/railcommand/layouts) click Import from TrainController, or go straight to/app/railcommand/layouts/import/traincontroller. - Drag your file onto the drop zone or use Browse Files. Tick "I own this layout file or am authorized to import it..." (required), then click Analyze File. The file uploads and is parsed server-side; nothing is written yet.
- Review the Transform Tables. One tab per object type — Turnouts, Toggles, Signals, Sensors, Blocks, Routes, Connectors, Controls, plus Roster/Trains when the file carries rolling stock, and Warnings. Each tab badge shows its count. The header's "Also in this file" panel lists decoded facilities (Single Track Lines and Gradients — imported with the layout; their gradient percentages and endpoints follow in a later release once those fields are decoded) alongside roster/consist/geometry counts.
- On each tab, use the include checkbox to keep or drop a row, edit fields inline (name, panel, DCC, aspects, speeds), fix a placement with the COL:ROW field, or use Add row to insert one. Panel and per-column filters narrow large tables; the footer flags any included row missing a position.
- Resolve the flagged uncertainty. On Signals, any head whose facing the decoder could not determine shows a Needs direction flag — pick N/E/S/W (a suggestion is offered) or exclude the row. On Trains, expand a flagged train and set the member's Dir to forward or reversed. On Controls, each imported turntable shows a Needs review flag for its ring size — set the track count (even 2–80 or odd 1–49) or exclude the row; the decoded fields are treated as unproven candidates, not defaults. The importer flags rather than guesses; every included flag must be cleared before you continue.
- Click Create layout (it shows the object count). The graph, signal topology, and block wiring derive at this step, and the summary reports what materialized. Each resolved turntable's ring materializes onto its placed cell as the turntable's behavioral config, flagged Needs configuration so you can finish it in the editor.
Troubleshooting
"Invalid file type" or "File size exceeds 50 MB" — Only .yrrg/.yrl files up to 50 MB are accepted. Re-export a fresh project from TrainController.
Create layout is disabled with a lock reason — An included signal still needs a facing, or a train member, turntable, or row still needs attention. Follow the amber "Signals tab" / "Trains tab" / "Controls tab" link, pick a value or exclude the row, then create. The server re-checks these gates on create, so clearing them in the review UI is not optional.
Two of my signals share one mast, but they imported as two separate signals — That is correct and deliberate. TrainController has no multi-head mast: every signal in a TrainController file is a single head, and a two-head mast is drawn there as two separate signal objects in neighbouring cells. There is nothing in the file that says "these two are one mast", so import never guesses at it and never asks you about it — every imported signal arrives on its own. Building the mast is an editing step: select the heads in the layout editor and group them (and ungroup to split one again). A mast in RailCommand is one cell carrying several heads, which is a stronger model than the drawing trick it replaces.
I used to be asked a "Multi-head?" question during import — It is gone. That question assumed TrainController could express a shared mast; it cannot, so the question could never be answered from the file and has been removed rather than given a default. Nothing about your import is being silently decided instead: signals import solo, which is what the file actually says.
A turntable is locked "Needs review" — Its ring size was decoded as an unproven candidate, not confirmed. Set the track count (even 2–80 or odd 1–49) on the Controls tab, or exclude the turntable, to unlock create.
A refresh sent me back to Upload — The staged review lives only in your session, so refreshing or leaving discards it. Re-upload to restart — nothing was written to your account.
An included row didn't appear after Create — A row flagged "N need a position" does not materialize until it has a COL:ROW placement.
A sensor is locked with "Imported with block" — Expected: block-embedded contacts import their occupancy with the block, not as standalone sensors.
A contact drawn as its own cell now imports its full addressing — since 2026-08-27 a feedback contact TrainController drew as a separate cell carries its board, its input and its flat LocoNet value onto that cell, so its address shows everywhere the block's other sensors do. Layouts imported before that date pick the addressing up at their next connected sign-in; there is nothing to re-import and nothing to migrate.
Cross-checking a sensor against a BDL168 sheet or JMRI — the Sensors tab's read-only LocoNet column shows the flat address as imported (LS1731), the same number JMRI displays and BDL168 planning sheets print. Address and Input are the same sensor in board/channel form: LS1731 is board 109, input 3. The column shows — for a Plain-Number contact, which has no flat LocoNet address.
My AIU pin panel imported, but none of the pin names came with it — the pin addresses have always imported; what was missing was the labels TrainController draws next to them, and those now decode. If your layout was imported before that shipped, re-import the file — a re-derive cannot add them, because the labels are read while the file is parsed. If a fresh import still brings no labels, check the Warnings tab for the legacy-field-marker warning below: on an older file the labels may not decode yet, and that is a gap in our decoder, not an empty panel.
The import warned about a "legacy v9 field marker" — the file was saved by an older TrainController than the label decode is calibrated on. The decoders read the marker from the file itself, so the file is scanned on its own marker; what is not yet calibrated for that vintage is the record layout the switchboard text and connection labels sit in, so they may come back partly or entirely undecoded. The warning states how many labels decoded. Nothing here is the operator's mistake: report the count as what we read, treat it as undecoded rather than absent, and escalate the file.
A decoded label is missing from the panel after create — check the warnings reported with the create result. Two cases are named there: the label's decoded cell fell outside that panel's grid (the cell offset is not yet decoded for the Symbol/Image label variants, so the text is right but the position is not), or it collided with a cell already on that square. In both cases nothing is guessed onto the canvas; place the label yourself in the layout editor. A label that never appears in either warning may not have decoded at all — that shows up earlier, as a parse warning on the Warnings tab, not with the create result.
A turntable in my file isn't on the Controls tab — If the decoder could not recognize a turntable-shaped object it surfaces it on the Warnings tab rather than dropping it silently. Recognized turntables import per-instance, so a multi-turntable file yields one reviewable row each.
Rolling stock is missing — Confirm "Import rolling stock & trains with this layout" is on, or import it later from Asset Management at /app/asset-management/import.
Safety Notes
Import is a web-only authoring action. The ownership attestation is required for legal reasons, and the whole flow runs in the browser — it never actuates hardware. Creating a layout writes a definition; it does not energize track, throw a turnout, or drive a command station. The DCC addresses, aspect counts, and switch times you enter are stored configuration only.
Running the layout happens later on the RailCommand desktop, which presents state and forwards operator intent; the local/UE5 runtime owns all safety-critical execution — interlocking, movement authority, and emergency stop. Correct addresses and facings at import make that runtime correct, but neither the web nor the desktop UI actuates hardware itself.