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 tools for working with your layout:
Layout Automation
Use JMRI to automate parts of your layout and operations:
Supported Hardware
JMRI supports a wide range of DCC systems, command stations and protocols.
Applications
By the community of JMRI.org:

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

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, also see the support on their Wiki, https://wiki.python.org/jython/.

Non-programmers might want to start with this Beginners Guide listed on the Jython wiki.

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.

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.