JMRI Setup: Migrating System Prefixes
JMRI system names are supposed to have a
specific format that starts with a "system prefix"
consisting of a single letter, optionally followed by digits. Unfortunately, for a while JMRI
wasn't enforcing that properly, and in a few cases JMRI set itself up with prefixes that
contained multiple letters. This can cause significant long term problems, so we're getting
people to migrate their configurations and panel files to the proper format.
Does this affect me?
You can check if this is an issue for your setup any of a couple ways:
- Open the Preferences, and look at each of the "Connection" panes. If the Connection
Prefix has a letter or a single letter plus digits, this doesn't affect you. If it has more
than a single letter, you should do this migration. (With JMRI 4.13.4 or later, the background will be colored
red and the tooltip will say "This is a legacy prefix that should be migrated, ask on
JMRIusers" if the prefix needs to be migrated)
- Check the system log after running and quitting the program to see if there's a warning
message about "The following system names need to be migrated..." If it's there, you should
do this migration.
How to fix the issue
To fix this issue, you update your configuration and panel files to use new prefixes.
If you encounter any problems, please ask for help on the JMRI users group. There are people there who will happily
do the necessary file modifications, provided they happen to have the spare time available.
If your computer is connected to the Internet, you can upload your configuration as described
on this page. This will make
it easy for the people on jmriusers see exactly what's needed.
- First, you should be using JMRI 4.12 or
later. If you're using an earlier version, please update to at least JMRI 4.12 and fix any problems.
- Next, determine the new prefix for your connection:
- DCCPP for DCC++ (including DCC-EX EX-CommandStations) should be changed to D
- DP for DCC4PC should be changed to D
- DX for Anyma DX should be changed to D
- MC for Marklin CS2 should be changed to M
- MR for MRC should be changed to M
- PI for Raspberry Pi should be changed to P
- TM for TMCC should be changed to T
However, if you already have a connection with that letter, you'll need to pick another
one. The letter is arbitrary, so just pick one that makes sense to you. If you insist to
use a letter already in use, you should add a number to it, for instance defining the new
prefix like "D1", in which case a valid turnout system name would be "D1T123".
- Take a backup of all your files. Maybe more than one. And make sure that they're usable
in case you need to restore from them!
- Take all your panel files, and edit them to change the prefix of all the references. To
help with this, the last time you run JMRI, it put a list of reference names in the log
near the end, and a similar "legacy_bean_names.csv" file was written to your user files
directory. You can search for each of those reference names in turn and change it to the
new prefix.
- Start JMRI (without loading the panel files yet), open the Preferences to the
Connection pane, change your connection prefix to your new choice (the field will turn
orange if the prefix is accepted), Save and Restart.
What happens if I don't make this change?
If you don't make this change, your existing JMRI installation will keep working fine.
If/when you update to newer versions of JMRI:
- When you update to JMRI 4.15.3 or later, you'll start getting prompts about fixing this
every time you start JMRI.
- If you update to JMRI 4.17.1 or later (summer 2019) without fixing this, you won't be
able to use your existing configuration or panel files.
We're sorry for this inconvenience, but we really do have to fix this. Giving people over 18
months lead time seems sufficient.
