Keywords: save store jython script, jython naming, jython threads, jython automation, jython siglets, jython AbstractAutomaton

# JMRI: "What...Where" of Jython Scripting with JMRI

Other interesting tidbits about scripting in JMRI with Jython

- Where should I store my JMRI Jython scripts?
- Where can I find more information on the JMRI classes?
- What is the difference between System names and User names?
- What do the words "`import`" and "`class`" mean?
- Why should I based my script on "Siglet" and "AbstractAutomaton" classes?
- What's the difference between the "Siglet" and "AbstractAutomaton" classes?

See the examples page for many sample scripts. Also, the introductory page shows some of the basic commands.

See also JMRI Scripting "How To..."

See also Jython/Python Language for general info about the language.

## Where should I store my JMRI Jython scripts?

You CAN use any location for your own scripts, including locations within a Dropbox (or other file sharing system) folder where they will be available across multiple computers. [Instructions on using Dropbox with various JMRI files can be found at JMRI Setup: Sharing Files with Dropbox.]

However, you should NEVER store your own scripts (or any other user-created files) anywhere within your Program Location as they will be lost in a JMRI upgrade. Unfortunately, JMRI currently defaults the Scripts Location to the Jython sample scripts folder located within your JMRI Program Location. To resolve this, change the Scripts Location in Preferences (Preferences->Locations) so that your location will be displayed automatically.

[Go to top of page]

## Where can I find more information on the JMRI classes?

The class documentation pages include automatically-built summary information on every class.

There are a lot of classes! To help you find things, it might be useful to look at the page on JMRI structure, which is part of the JMRI technical documentation. Note the references on the left-hand side.

Additional information can be found in the JavaDocs for specific types of classes, for example:

https://jmri.org/JavaDoc/doc/index.html?jmri/SensorManager.html
https://jmri.org/JavaDoc/doc/index.html?jmri/TurnoutManager.html
https://jmri.org/JavaDoc/doc/index.html?jmri/LightManager.html
https://jmri.org/JavaDoc/doc/index.html?jmri/BlockManager.html

[Go to top of page]

## What is the difference between System Names and User Names?

Click for more information on Names and Naming.

System names for sensors, turnouts, lights and others, are connection specific. A LocoNet sensor name begins with "LS" while a CMRI sensor begins with "CS" and an internal sensor with "IS". "provide" methods check the prefix of the passed string to determine if it matches a defined connection or internal. If so, and the rest of the name is valid, the sensor is created. If a match does not exist, it assigns the prefix for the first connection in the currently open connection list.

Example: If your connections are LocoNet and CMRI, a provideSensor request without a prefix of LS, CS or IS, will be assigned LS. If the name value is not one to four numeric digits (a LocoNet requirement), you get a bad format error. Memories are only internal, so provideMemory uses "IM" as the default prefix.

Since System names follow a prescribed format, there is a procedure for checking whether a name is valid. Use this code to create a sensor with a valid name:

            try:
               sensors.validateSystemNameFormat(MySensorSystemName)
            except jmri.NamedBean.BadSystemNameException:
               print 'Invalid name: ', MySensorSystemName

User names are set after input and outputs are created. They can be any character string you want. You can use user name or system name in scripts and Logix. The use of user names is recommended for these purposes if there is the possibility that you will be changing your control system in which case system names will be changing as well.

### Obtaining User Names from Objects

If a returned object from a query is a NamedBean Object, ( ie. it appears in a JMRI Table ) the return value ( from Java #toString() ) is the Hardware Address.
If you require the ID Tag UserName, eg. For a Block with username "BlockUserName", you could use :

            mylocostring=blocks.getByUserName("BlockUserName").getValue() #Block value Object could be a String or ID Tag
            if (isinstance(mylocostring,jmri.NamedBean)) : # The object is a NamedBean
                mylocostring = mylocostring .getUserName() # Set to the User Name
            print mylocostring

It can sometimes be handy to get further information on a Reporter value. The toReportString method provides an object specific report, which may or may not actually contain the user name by itself.
For example, a LocoNet TranspondingTag may report strings such as '1234 enter' or '1234 exit', while Railcom objects will add any detector supplied values, such as orientation, to the string.

Eg. For a Block with username "BlockUserName", you could use :

            mylocostring=blocks.getByUserName("BlockUserName").getValue() #Block Object could be a String or ID Tag
            if (isinstance(mylocostring,jmri.Reportable)) : # The object is a Reportable
                mylocostring = mylocostring .toReportString() # Set to the Report String
            print mylocostring

[Go to top of page]

## What do the words "`import`", "`class`" mean?

They're part of the jython language used for the scripting.

"import" allow you to refer to things by shorter names, essentially telling jython "search the imported packages (e.g. jarray and jmri) packages and recognize all the names there". For somebody trying to understand this script, you can just treat them as "ensuring the program can find parts we want".

"class" means "start the definition of a group of things that go together" (all you other experts, please don't jump on me about this; I understand both intrinsic/extrinsic polymorphism, I'm just trying to get the general idea across).

For example, in the SigletExample.py file is a description of a "class" called SigletExample, which contains two routines/functions/members: A subroutine called "defineIO", and one called "setOutput"

This "class" is associated with another called "Siglet" (actually jmri.jmrit.automat.Siglet; that's that long naming thing again), which knows when to invoke routines by those two names to get done what you want.

Essentially, you're defining two parts ("defineIO" & "setOutput") that plug into a pre-existing structure to drive signals. That pre-existing structure is very powerful, and lets you do all sorts of things, but also provides this method to try to keep it simpler.

OK, at this point most people's eyes are fully glazed over. Your best bet when starting with this stuff is to use the "copy and modify" approach to software development. It's good to try to understand the entire content of the file, but don't worry about understanding it well enough to be able to recreate it from scratch. Instead, just modify little bits and play with it.

[Go to top of page]

## Why should I base my scripts on "Siglet" and "AbstractAutomaton" classes?

Scripts are part of the main JMRI program. This creates a bit of a problem: when something goes wrong in a script, it may crash JMRI. When a script goes to sleep, the whole program sleeps. However, if you want to run independent of JMRI, you can via a separate "thread." The Siglet and AbstractAutomaton classes have created to allow you to base your scripts on a class that will run as an independent thread but with the ability to communicate with the rest of JMRI. For more information, see the section on threads.

Effectively, each Automat or Siglet is a separate program running when it needs to. Since they run in separate threads, they can wait for something to happen while the rest of the JMRI program proceeds - a very useful capability indeed.

## What's the difference between the "Siglet" and "AbstractAutomaton" classes?

Some examples use the AbstractAutomaton class as a base, while others use the Siglet class. This is because those are intended for two different purposes.

"Siglet" is meant to be used for driving signals. You provide two pieces of code:

defineIO
  which defines the various sensors, turnouts and signals that the output signal depends on as input when calculating the appearance of the signal.
setOutout
  which recalculates the signal appearance from the defined inputs.

The Siglet base class then handles all of the listening for changes, setting up for parallel execution, etc. Your defineIO routine will be called once at the beginning, and after than any time one or more of the inputs changes, your setOutput routine will be called to recalculate the signal appearance.

Of course, you can use this class to calculate other things than signal appearances. But the key element is that the calculation is redone when the inputs change, and only when the inputs change.

AbstractAutomaton is a more general class that's intended to allow more powerful operations (and Siglet actually uses that more powerful base). You define two functions:

init
  which is called exactly once to do any one-time setup you need
handle
  which is called over and over and over again until it returns FALSE.

Using AbstractAutomoton provides you with a number of tools: you can wait for a particular sensor to go active, do something, then wait for a different sensor to go inactive, etc. This allows you much more freedom to create complicated and powerful sequences than the Siglet class, because Siglets are limited to doing just one thing (they aren't intended to do sequences of operations).

For more info on the routines that AbstractAutomaton provides to help you, see the Javadocs for the class. (Scroll down to the section called "Method Summary")

[Go to top of page]