JMRI: Profile Directory Tutorial
This page is a tutorial on how JMRI stores and accesses preference and profile
information.
Locations and contents
- Settings Location (portable name = "settings:")
-
This is the only fixed location and is determined by the underlying operating system type
and your logged-in-username. It's a known place the JMRI program can always look and find
essential settings files that tell it where everything else is located.
The following files/folders are always located here:
- nodeIdentity.xml
- This file contains a unique nodeIdentity string that is generated the first time
JMRI uses this Settings Location, doesn't change and serves to distinguish between
other possible Settings Locations (such as under another username, on a different
operating system partition or another computer).
- profiles.xml
- This file lists the name of every Profile Folder known to this instance of JMRI and
its location. It also has a list of all paths you wish to search for profiles and which
path is the default for newly-created profiles. "settings:" is always searched but it
doesn't have to be the default.
- preferences
- This directory contains preferences that are retained on the computer for use in
all JMRI application profiles. If it is not present, no preferences that apply to all
profiles have been written.
- log
- This folder contains the "session.log" and "messages.log" files, plus several
previous versions of these files.
- DecoderProConfig3.properties
- PanelProConfig2.properties
- SoundProConfig2.properties
-
These files are created the first time each of the apps are run and simply contain
three pieces of information:
- The name of the Profile Folder last used by this app.
- Whether you want the app to autostart with the last-used Profile Folder
- How long to display the Profile Selector box if you choose not to
autostart.
- Other files/folders:
-
The following may be present, but do not have to be:
- Various Profile Folders you have created. From V4.13.4 on, newly-created
Profile Folders will have a ".jmri" extension.
- Your User Files - panels etc.
- Your "roster" folder and its (recreatable) roster.xml file.
- Profile Location (portable name = "profile:")
-
This folder is the one chosen by the Profile Selector mechanism for the current JMRI
session.
The "profile" folder at the profile: location contains the "profile.xml" and
"profile.properties" files and one or more node specific folders that start with
"jmri-".
The node specific folders contain local versions of "profile.xml",
"profile.properties" and "user-interface.xml". The "user-interface.xml" file contains
information on window size and positions, column widths, etc.
Other files/folders:
- Other specific preference folders (throttle, etc.)
The following may be present, but do not have to be:
- Your User Files - panels etc.
- Your "roster" folder and its (recreatable) roster.xml file.
- User Files Location (portable name = "preference:")
-
This location contains:
- Your User Files - panels etc.
The following may be present, but does not have to be:
- Your "roster" folder and its (recreatable) roster.xml file.
You are free to change the User Files Location as you like (Preferences->File
Locations).
- Roster Location
-
This location contains:
- A "roster.xml" file, which is a (recreatable) index of the XML files in the
"roster" folder. You should create/recreate "roster.xml" (Actions->Recreate Roster
Index) if it is missing or you are experiencing roster problems.
- Your "roster" folder. This contains:
- An XML file for each loco entry in your roster, with stored CV values,
etc.
- ".bak" files, which are backup versions of entries in your roster.
- A "consist" folder, which stores information on consists you have created using
the Consist tools in JMRI.
- Copies of media files you have added to roster entries, throttles etc.
(Older JMRI versions stored roster images in a "resources" folder in the User Files
Location. If you have been using JMRI for a long time, you may have roster images
in both locations.)
By default the Roster Location is the same as (and follows) the User Files location
unless you explicitly set a different location.
You are free to change the Roster Location as you like
(Preferences->Roster->Roster->Location Set/Reset). The Reset button causes the
Roster Location to again follow the User Files location.
- Scripts Location (portable name = "scripts:")
-
This location defaults to the "jython" sample scripts folder located within your JMRI
Program Location. You should never store user-created files anywhere within your Program
Location, they are likely to be lost in a JMRI upgrade.
If you are creating your own scripts you may wish to change the Scripts Location
(Preferences->File Locations).
- Program Location (portable name = "program:")
- This location is set when JMRI is installed and can only be changed when installing the
software. You should never store user-created files anywhere within your Program Location,
they are likely to be lost in a JMRI upgrade.
User Files Location defaults and implications
Depending when you first installed JMRI on your computer, the default User Files Location
will differ:
- Before the advent of Profiles (JMRI V3.8),the default User Files Location was the same
as the Settings. This arrangement stayed in place with the upgrade.
- After the implementation of Profiles (JMRI V3.8),the default User Files Location for
new installations is the same as the Profile Location.
Implications of User Files Location with Profiles
- If you create a new profile, User Files Location = Profile Location. This means the
profile will have an initially-empty set of User Files.
- If you create a copy of a profile that has User Files Location within the Profile
Location, the new profile will have a new private copy of User Files from the source
profile. The two sets will be unconnected and changes to one will not affect the
other.
- If you create a copy of a profile that has User Files Location anywhere on the computer
outside the Profile Location, the new profile will share User Files with the source
profile. So changes will be seen by both profiles.
Implications of Separating User Files Location and Roster Location
If you separate User Files Location from Roster Location (as documented above), you can
implement differing sharing/separation of the two, e.g a single roster shared between two
different layouts (each with its own profile).
Sharing User Files between Computers
Since User Files can be relocated completely outside of the user's JMRI file system, sharing
of User Files between computers is easy:
Use of simple file sharing or using a local NAS or other file server
This approach seems appealing at first sight. However there are considerable disadvantages
and risks.
- The host computer or server must always be on line when using JMRI on any
computer.
- Use of JMRI on a laptop away from home or Internet access will not be possible.
- JMRI is not designed for simultaneous file access. The risk of file corruption is very
high.
- Recovery from a file corruption may be difficult or impossible unless a very
comprehensive incremental backup strategy is in use and even the there is likely to be some
data loss.
See the link below for further information on issues with simple file sharing:
Use of a cloud-synced sharing solution
Note that in this context we are not talking about a Cloud Server approach where your files
only exist on a remote server. We are talking about a service such as Dropbox, Google Drive,
OneDrive where full local copies exist on each computer and each copy is kept in sync with
the central Cloud copy.
There are considerable advantages with this approach.
- Only one computer needs to be switched on at a time.
- Use of JMRI on a laptop away from home or Internet access is fine. The file changes
will be synced next time you are connected.
- These services generally do not usually use simultaneous file access. The risk of file
corruption is much lower.
- Recovery from unintended file changes is much easier. For example Dropbox keeps every
saved change you have made in the past 30 days (even if you only have one computer) and
allows easy reversion.
We tend to talk about Dropbox because that is the one that seems to be most used by JMRI
developers and users, some of whom have been doing so for many years. For more information
and setup instructions (also applicable to competing services) see the
JMRI page on Dropbox use.
Sharing Profiles between Computers
In the same way that User Files can be relocated completely outside of the user's JMRI file
system and shared between computers, so can entire Profiles. In Preferences->Config
Profiles->Search Paths you can add a search path in a synced/shared location and set that
to be the default for newly-created profiles. It's then simply a matter of manually moving
each Profile Folder from the Settings Location to your new shared folder. When you first use
a shared profile on a different computer JMRI creates a node-specific folder for storing
overrides of settings (see above) that are machine-specific (e.g. COM port names).
I have been using both of shared User Files (a "JMRI" folder in my Dropbox folder) for
many years and a shared Profiles (a "JMRI Config Profiles" folder in my Dropbox folder) for
more than a year now (and tweaked some JMRI code to improve node differentiation) across more
than a dozen machines/virtual machines, running Mac, Windows and Linux.
Portable File Access in JMRI
The success of file and profile sharing in JMRI is very dependent on the use of our Portable
File Access specification in XML files.
Briefly, this consists of pseudo-URL prefixes (portable names mentioned above) that
replace machine-specific directory paths in file specifications with a set of prefixes
relative to known JMRI and machine locations. These are expanded by the local JMRI instance
to create a machine-specific file specification. The component separators are standardised as
"/" and converted locally.
For more information see the FileNames page. For a
full list of prefixes, see the
JavaDocs for the FileUtil class.
