Skip to main content

JMRI is...

Scripting

Information on writing scripts to control JMRI in more detail:

Python and Jython (General Info)

JMRI scripts are in Jython, a version of Python, a popular general-purpose computer language

Tools

JMRI provides powerful tools for working with your layout.

Layout Automation

JMRI can be used to automate parts of your layout, from simply controlling a crossing gate to running trains in the background.

JMRI: The Python/Jython language

Python is a widely used scripting language that's available on many types of computers. A Java-based variant, called Jython, has been integrated with JMRI to make it easy to control a model railroad from the command line of a computer. For our purposes, the two languages are completely the same.

If like me you prefer to read off paper, there are lots of books available on Python. Perhaps one of the best for beginners is "Learning Python" published by O'Reilly. It contains more than you really need to know, though.

The jython.org site has some introductory information, though their tutorial spends too much time on the engineering details at the beginning. You might want to skip to the part about the language itself.

Non-programmers might want to start with some of the resources for them listed on the python website.

If you are interested in the underlying technicalities of the language, IBM Developerworks has two good articles here and here. They also have a nice tutorial here, although they require you to register with your email address to access it.

Looking at the examples in the "jython" directory in the JMRI distribution will also be of value. See the examples page for links to these sample scripts.

How do Jython and Python differ?

For the purposes of writing JMRI scripts, they don't differ very much. Most of the differences involve what happens in somewhat contrived error cases. There are also some restrictions on what you can do with the computer's configuration information, etc, in Jython, but these are not things a JMRI script is likely to need.

Some additional information on the differences is available here.

IMPORTANT INFORMATION ABOUT PROGRAM FORMATTING: INDENTATION MATTERS

The single oddest thing about Python is that the indentation matters. Instead of using { and } characters to indicate the beginning and end of a block or function, that's done with indentation in Python. Of course, in a C-like language people usually indent blocks anyway, but it takes a little getting used to that you have to do it in Python. You should indent with four spaces for each level in your code. (Four is a convention, but it really helps readability; using tabs can cause lots of confusion and is not recommended. Mixing spaces and tabs is likely to cause lots of confusion; please don't do that)

For example, this is a syntax error:

   a = 15
      print a
   b = 21
because those statements, though logically grouped at the same level in the program, aren't indented the same. This sounds like a pain at first, but you rapidly get used to it. Then it makes things like the following pretty easy to read, without having to worry about where the { and } go: 
        if ( now == -1 ) :
                done = 1
        else :
                done = 0
        print done
If you do get a message about "Syntax error", look at the indicated line number to see if your indentation isn't lined up.

Is JMRI's support for Python complete?

JMRI scripting uses Jython, a Java-implemented form of the Python language. The basic language is pretty complete, but not all of the Python libraries are available. Some "import" statements that you might read in a book might not work because of missing libraries.

Support is improving all the time, though, and you might want to try a more modern version of Jython than the one that JMRI distributes. To do that, install Jython on you computer, then add a python.properties file in your user files directory or preferences directory that sets the python configuration variables, e.g. on Windows:

python.path = C:\\jython2.7.0\\Lib\\site\-packages
python.startup =

Note that the double-back-slashes are necessary. They'll appear as single-back-slashes in the final value, which you can check with the "Context" item from the main JMRI Help menu. On Mac use something like:

python.path = /Users/username/jython2.7.0/Lib/site-packages
python.startup =
or where-ever you've installed the new Jython. Linux is similar.