Code documentation

Development tools

Code Structure

Techniques and Standards

How To

Functional Info

Background Info

JMRI Web Site:
Contents/ Index

Donate to JMRI Donate to JMRI.org

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

Implications of User Files Location with 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. 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.

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.