Note:

This Install Guide is suitable for JMRI versions 2.5.2 and later - for versions 2.5.1 and earlier (2008 and before), refer to the old Install Guide.

There is a separate page for debugging the "The JAVA SE Platform binary has stopped working" error message.

JMRI Install Guide: Windows

Installation

  1. Determine if your hardware supports Java and JMRI

    We have had a report that a 180MHz Pentium II is too slow to use, and another that a 330MHz Pentium II is fine, so somewhere around there is the minimum machine configuration, but it's important to have enough memory. We recommend you have at least 128MB of memory for Windows 98, and 256MB of memory for Windows 2000 or later. Having 256MB or 512MB respectively would give better performance. For the more complicated programmer screens, a display with a resolution of 800x600 or larger is strongly recommended. Note that used PC hardware is available for very little money; it might be cheaper to buy a used computer than to update your existing one.

  2. Get JMRI

    Download a version of JMRI, either the latest production version, or a "test version". Since the version numbers change with every release, this link takes you to the general JMRI download page, where you can select whichever version you like.

    JMRI also supports an offline installation - to setup, refer to the offline installation notes below.

    The JMRI project is continuously adding features, bug fixes, examples and tutorials to the release, and so new "test" versions appear every couple of weeks. You may find one of these has features that you really want. These are announced in the "jmriusers" Yahoo discussion group at http://groups.yahoo.com/group/jmriusers/.

  3. Run the JMRI installer
    1. Installer start-up

      installer welcome page

    2. Check for a previous version

      It will then check to see if a previous version of JMRI exists, backup any preference, roster and other settings and, if necessary, uninstall the old version.
      installer backup and remove page
      or
      installer backup page

      Uninstall of version 2.5.1 or earlier:

      Initial confirmation
      installer uninstall old version confirmation

      Uninstaller progress
      installer uninstall old version progress

      Uninstaller complete
      installer uninstall old version complete

      In some circumstances, the removal of version 2.5.1 or earlier is not successful:

      Uninstaller failed
      installer uninstall old version failed

      In such cases, it is necessary to download and run the following file and then re-run the installer:
      RemoveOldJMRIUninstallEntry.exe

    3. Choose installation type

      If supported by your Windows version and depending on the permissions of your user, the installer may ask you to choose to install JMRI just for yourself or for all users of the computer.
      installer user choice

    4. Choose components

      The installer will now present a list of the components to be installed.
      installer component choice
      This will install JMRI to the default location, place shortcuts for DecoderPro and PanelPro on the desktop and create a JMRI Start Menu folder containing shortcuts for typically used JMRI programs.

      If you wish to change where JMRI is installed, change the install type to 'Custom (select to choose program folder)'.
      installer type choice

    5. Check for Java

      It will check for a suitable version of Java on your computer and, if required, will connect to the internet to download the most current version for your computer. (For an offline installation, refer to the offline installation notes below).
      installer ask Java download

      Downloading java
      installer start Java download

    6. Install files

      Once existence of a suitable Java Runtime Environment has been confirmed, it will then install the needed libraries, plus add a "JMRI" program group to your Start menu and put shortcuts to the DecoderPro and PanelPro programs on your desktop.
      installer files install

    7. Installation is complete.

      installer finish

  4. Start the programs from the JMRI group under Programs in your Start menu.
    JMRI Start menu
    (This shows the Start menu following a 'Typical' install - a 'Full' install will place additional icons in this menu)
  5. Configure the program to connect to your layout

    The JMRI hardware page lists the various types of layout equipment that JMRI can connect to, and gives links to instruction pages. Go there next to complete your setup.

Notes:

Offline installation

The Windows JMRI installer for version 2.5.2 or later supports an offline installation of Java and JMRI. Typically, this would be used when the computer on which you wish to run JMRI does not have internet access.

(The following instructions assume that you are setting up a blank removable flash drive - creation of a CD will be similar but may depend on the capabilities of your CD authoring software)

  1. Copy the previously downloaded JMRI installer onto the root of the flash drive.
  2. Create directories in the root of the flash drive called:
    • JRE
    • JRE_98ME

      The following image shows the resulting structure:
      Offline installer folder structure

  3. In the JRE directory, place a copy of the Java offline installer for Windows 2000 or later. If required, the latest version can be downloaded from Sun Microsystems here. A typical name for this file is 'jre-6u11-windows-i586-p-s.exe'.
  4. In the JRE_98ME directory, place a copy of the Java offline installer for Windows 98 and ME. If required, this can be downloaded from Sun Microsystems here. The filename should be 'jre-1_5_0_17-windows-i586-p-s.exe'.

Setup of the JMRI offline installation media is now complete.

Note: If you do not wish to support offline installation on Windows 98 and Windows ME, skip the creation of the directory 'JRE_98ME'.

Large Windows

control panel

Depending on what it wants to display, JMRI can open up very large windows. Generally, JMRI uses the size of the screen and information about fixed things like the start bar to decide the maximum size for an opening window so that e.g. the corners can't be reached to resize the window.

Depending your Windows display operation, large JMRI windows will either resize to stay on the large part of the screen, clear of start bars and menu bars, or will be displayed at the full size of the screen, appearing under the start bar and menu bars.

This is controlled by the Taskbar and Start Menu Properties control panel. JMRI windows can open to the full screen size if the 'Keep the taskbar on top of other windows' option is de-selected.

Also, they can open to the full screen size if the 'Auto hide the taskbar' option is selected

Windows Themes and Skins

If you're using a "skinning" utility which changes the appearance of programs running on your computer, you should tell it to ignore the "java.exe" program. That's how JMRI and DecoderPro will appear to it, and they weren't written with such "skins" in mind.

Serial port configuration

DecoderPro may encounter problems if the serial port used to connect to the layout shares an interrupt with another serial port. Typically COM1 and COM3 share an interrupt, as do COM2 and COM4. In particular, some systems are unable to communicate (and may experience a lockup) when the layout's serial port shares an interrupt with a port used for a serial mouse. Please make sure that the serial port connected to your layout does not share an interrupt with another serial port.

With Windows XP, your serial port parameters might not be properly set for hardware flow control. To fix this, right-click on My Computer and select Properties. Go to the Hardware tab and click on Device Manager. Open up the section that says Ports (COM & LPT). Right-click on the serial port you have the LocoBuffer hooked to and select Properties. Go to the Port Settings tab and set the options to 19200, 8, None, 1, Hardware. Click OK. Close everything. Restart JMRI and verify your connection settings.

Debugging

Sometimes things go wrong. The information in this section can help.

The Log Screen

JMRI logs information about errors to a "messages.log" file in the "systemfiles" sub-directory of the JMRI preferences directory, and to a console window. This window is generally white text on a black background, and is labelled either "Java" or "DOS". If something is going wrong, look there for more information.

  1. To view the "systemfiles" sub-directory, follow the "Preferences" link in "JMRI > Tools and Demos" from the Start menu.
    Preferences link in JMRI > Tools and Demos start menu
  2. Once the preferences folder is opened, navigate to the "systemfiles" folder.
    systemfiles folder within JMRI preferences
  3. Finally, within the "systemfiles" folder, is "messages.log".
    messages.log file within systemfiles folder

If asked for a copy of the error messages, you can usually get them from the messages.log file. If not, to make a copy of the log window:

For JMRI 2.11.1 or later

  1. From the main JMRI window, choose "Help > System Console ...".
    JMRI system console
  2. Click the button "Copy to clipboard".
  3. In your e-mail client, the Yahoo! "Post Message" pane, Notepad, Wordpad, favorite word processor, etc, position your cursor and left-click on Edit and then Paste, or press the "Ctrl" and "V" keys.

For earlier versions of JMRI

  1. In the command prompt window, left-click on the JMRI icon to the left of the words "DecoderPro" (or "PanelPro"). You will get a drop-down menu.
  2. In that menu, put your cursor over "Edit" to get a sub-menu.
  3. Left-click on "Select All" in that sub-menu. All the text in the window will reverse colors with the background, and the menus will disappear.

    Alternately, you can left click on "Mark" in that sub-menu. The menus will disappear. Then, left-click and hold while dragging the cursor over the text to be copied. Only the selected text will reverse colors with the background.

  4. Repeat Steps 1 and 2 above, then left click "Copy" on the sub-menu. The text and window will revert to their original colors. The text is now on XP's clipboard.
  5. In your e-mail client, the Yahoo! "Post Message" pane, Notepad, Wordpad, favorite word processor, etc, position your cursor and left-click on Edit and then Paste, or press the "Ctrl" and "V" keys.

Startup issues

To assist with resolving JMRI start-up issues, it is possible to modify the start menu shortcut used to launch JMRI.

Shortcuts are modified as follows:

  1. From the Start button, navigate to the JMRI menu and right-click the DecoderPro icon (the PanelPro and/or SoundPro icons can be similarly modified)
    start menu properties
  2. Insert the '/debug' option into the shortcut 'Target'
    modify shortcut target

    When launched, the following window will appear showing various useful information:
    launcher debug window

    Copy the contents of this window by 'right-clicking' and then choosing 'Copy Details to Clipboard'

  3. In your e-mail client, the Yahoo! "Post Message" pane, Notepad, Wordpad, favorite word processor, etc, position your cursor and left-click on Edit and then Paste, or press the "Ctrl" and "V" keys.

For further information on the JMRI shortcuts, see the page outlining the start-up procedure on Windows.

Shutdown issues

To assist with resolving JMRI shutdown issues, it is possible to modify the start menu shortcut used to launch JMRI.

Shortcuts are modified as follows:

  1. From the Start button, navigate to the JMRI menu and right-click the DecoderPro icon (the PanelPro and/or SoundPro icons can be similarly modified)
    start menu properties
  2. Insert the '/noisy' option into the shortcut 'Target'
    modify shortcut target

    When launched, the Java System Console window will appear showing various messages from the JMRI program:
    java system console window

  3. When the shutdown of JMRI appears to hang, click in the Java System Console window and then press 'Ctrl-Break' on the keyboard - this will print a Java Thread Dump showing all active threads still running in JMRI:
    java thread dump
  4. Once the Java Thread Dump has been printed, select all the text in the window by clicking the top-left icon and choosing 'Edit > Select all':
    java thread dump
  5. Once selected, copy the text to the clipboard by clicking the top-left icon and choosing 'Edit > Copy':
    java thread dump
  6. In your e-mail client, the Yahoo! "Post Message" pane, Notepad, Wordpad, favorite word processor, etc, position your cursor and left-click on Edit and then Paste, or press the "Ctrl" and "V" keys.

For further information on the JMRI shortcuts, see the page outlining the start-up procedure on Windows.

Reverting to an earlier version

During installation, JMRI can do a number of things automatically that makes it easier to revert to a previous working setup if a major problem is encountered in a test release.

Note: This procedure will not preserve work done since upgrading; it restores everything back to the state at the time of upgrade.

A backup copy of all your user files (Panel files, Roster entries, Preferences etc.) is saved when a new revision of JMRI is installed. This is done by the installer when it asks to save a backup copy which, if selected, is saved in a folder named "JMRI_backup".

When installing a newer version of JMRI than that already installed, backup creation is defaulted to "Yes"; when installing an older version, it is defaulted to "No".

If problems occur with the new version and it is necessary to revert to the last version in use, you should install the older version right over the version currently installed. Then find the folder that holds the folder named "JMRI_backup". This will normally be located in your user-profile folder - a quick way to find this is to follow the "Preferences" link in "JMRI > Tools and Demos" from the Start menu.
Preferences link in JMRI > Tools and Demos start menu
Once opened, navigate up one level to your user-profile folder.

Depending on the version of Windows, this will typically be one of:

Windows 98 - ME
C:\WINDOWS
Windows 2000 - XP
C:\Documents and Settings\[username]
Windows Vista - 7
C:\Users\[username]
Within this folder, look for and delete the folder "JMRI" then rename folder "JMRI_backup" to "JMRI".

Restart JMRI and you should be back to where you were before installing the new version.