<BACK Script Concepts and Organization
It is not the intention to teach Python/Jython programming here. There are several good references available on the web. Just search "Python" for details of the language.
One of the simplest and most useful guides for the beginner is https://www.tutorialspoint.com/python/index.htm
Likewise, refer to the JMRI web site for sample scripts, special features that make the JMRI version of Jython unique, and basic programming concepts.
Note that on RHJ Rail, individual scripts can be run from the main Panel Pro Windows console. Scrpts can also be run by executing them from other scripts. This feature forms the bsis for master scripts as described below.
Regarding RHJ Rail, it might be of interest to some to have a general idea of how things are organized. Two approaches present themselves: top down or bottom up. That is, start with the larger concepts and fill in a few of the details or start with the detailed building blocks of the system and show how they are combined to create larger structures.
We will do the top down approach.
Master Scripts - Sequential and Overlapped
The top-most concept in the AOCC is the master script. In its simplest terms, a master script accepts a "list" (a specific concept in Python) of scripts and actions and processes this list in one of two ways:
Sequential
A sequential script list is the simplest method and runs each list element to completion, one element at a time. This functionality has been in use for several years.
Overlapped
Overlapped scripts run the first list element and then, after certain conditions are met, start the next element regardless of whether the first element has completed or not. This is is a bit more complicated but has distinct advantages - many things can happen at once! The extensive use of this method is relatively recent but it has been experimented with in various forms for some time.
Scripts and Conditions
The master script can process over 150 different list elements, each element being a script or a condition. The list elements can be in any order and may be repeated as necessary.
In this context, a script causes an action on the layout: run a given train from one location to another; play a sound; activate or deactivate a special effect; and so on.
Likewise, a condition requires that a certain action be completed: wait for a given sensor to become active; wait for a given number of seconds to pass; wait for a given script to finish; and so on.
Example:
An overlapped master script can be constructed to do the following:
- Run Train A from location 1 to location 6,
- Wait for sensor X to become active (say Train A has reached location 3),
- Run Train B from location 10 to location 16 (while Train A is still running),
- Wait for sensor Y to become active (say Train B has reached location 12),
- Initiate some other action (while Train B is still running and possibly while Train A is still running as well), like changing a signal aspect, initiating a special effect, running another script, or whatever.
Limitations
The number of elements in a master script list has no theoretical limit but experience has shown that it is better to keep the total time an entire master script list requires to something practical, say 5, 10, or maybe 15 minutes of real time.
Script Development
This is too detailed to describe here but a couple of points are worth mentioning.
JMRI/Jython is difficult to learn. The documentation is not well organized and, as a beginner, you may not know exactly what to look for anyway.
A good approach is the classic "take something that works and modify it to do your thing". There are a number of example scripts on the JMRI web site and this is a good place to start.
One concept to watch out for is initialization. Such things as sensors, turnouts, and their associated tables in JMRI Panel Pro or Decoder Pro should be set up and tested before anything very complicated is undertaken.
After you have working scripts for most of the types of things you want to do, its not terribly difficult to make another one.
Python is a powerful programming language and you can do a lot in Jython/Python beyond just starting an engine and sounding its horn. There are many functions (mathematical, logical, time, and so on) that can help calculate, format, process and handle many different things.
A good tip to note is that when you find you need to do something that is not readily apparent from the JMRI examples, do a Python search for what you need. Things like tables, arrays, array processing, output formatting, and so on come to mind.
Remember, Python is not aware of your model railroad environment but does have many powerful programming elements including everything from file processing, mathematical, statistical functions, and many, many other useful methods.
Testing
One concept specific to RHJ Rail that has been developed over time is the concept of RUN or SIMULATION mode.
In RUN mode, everything works as you might expect in real time.
In SIMULATION mode, time flies. To do this in a script, time is defined in milliseconds and for RUN mode, one second=1000 milliseconds, just like in real life. In SIMULATION mode, one second=100 milliseconds and layout power is automatically turned off, all sensors are active (so the script doesn't wait indefinitely for a sensor to become active) and so on.
Thus for debugging scripts, SIMULATION mode is at least 10 times faster than RUN mode, plus the script doesn't have to wait for the time it takes for a train to travel to the next sensor, so you can do testing and find script or logic errors in a much shorter time. Also, the wear and tear on equipment is reduced.
There is nothing worse than being 15 minutes into a session and then having a script error occur. It can take a very long time to get equipment back into its original starting locations in order to try again, not to mention tracking down and fixing the script error that caused things to go wrong in the first place!
Further information can be provided on request to those interested in these concepts.
continued on Technical - Page 8
More details on any of the above can, of course, be obtained by contacting RHJ Rail.
RHJ Rail is owned and operated by Richard H. Johnson
© Copyright 2024 Richard H. Johnson