search JMRI:

Common Tools

JMRI provides powerful tools for working with your layout.

• Turnouts
• Lights
• Sensors
• Throttles
• Consisting
• Signaling
• Blocks
• Reporters
• Memory Variables
• Routes
• LRoutes
• Sections
• Transits
• Logix
• Fast Clocks
• Speedometer
• Audio
• ID Tags
• LogixNG
• Timetable

System-specific Tools

• Acela (CTI)
• C/MRI
• CAN
• MERG CBUS
• DCC++
• EasyDCC
• ESU ECoS
• Grapevine
• LocoNet (Digitrax)
• Märklin
• NCE
• OpenLCB
• RPS
• SPROG
• XBee
• XPressNet (Lenz)

Layout Automation

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

• Signaling
• Entry Exit (NX)
• Warrants
• Dispatcher
• Routes
• Fast Clocks
• Scripting

since 4.13.4

Timetable

A timetable describes the timing of trains running on a railroad. This information is used by train crews and dispatchers to prevent collisions. This also applies to model railroads, especially those using timetable and train order dispatching.

This tool provides the ability to collect the required data and generate a timetable graph that can be used to optimize train timing, such scheduling meets.

• Timetable Data Management
• Detail descriptions
  • Layout
  • Train Type
  • Segment
  • Station
  • Schedule
  • Train
  • Stop
• Timetable Graph
• CSV Import
• CSV Export
• Data Structure
• Technical

Manage Timetable Data

The data for a Timetable is represented in a tree structure.

The window is divided into 3 sections.

• The left side of the main section contains the tree structure for all of the layouts and the related data. The tree can expand and collapse to control the amount of detail being displayed.
• The right side of the main section contains the detail information, if any, about the currently selected tree row.
• The right side of bottom section contains the Save and Done buttons. The left side contains the Action buttons. These buttons vary depending on the selected tree row.

Action Buttons

The Edit Process

When the Timetable tool is selected from the PanelPro Tools menu, the timetable data is loaded from the TimeTableData.xml file. The file is located in the timetable directory in the user files location. If the file does not exist, a Sample timetable is copied from the JMRI install location.

When a new node is added, it is created with default values, and the new node is automatically selected. The default name should be changed and the other default values should be reviewed.

When a tree node is selected, the detail section shows the current detail information. The field labels include tooltips. When a field is clicked on or changed, the Cancel and Update buttons become active and the Action buttons become inactive. When edit mode is enabled, selecting a different tree node is disabled until Cancel or Update is selected. A dialog will be displayed as a reminder.

If the Save button is active, there are changes that have not been saved. Select the button to save the changes. Four backup files are retained in the timetable directory.

Select the Done button to close the Timetable window. If there are pending changes to be saved, a dialog will be displayed.

Timetable Menu

Detail descriptions

Layout

The Layout item contains global information.

• Layout name — The layout name.
• Scale — The layout scale. The default is HO
• Fast clock speed — The speed of the fast clock, e.g. 4:1, is entered as 4.
• Throttles — The number of the throttles for the throttle section of the graph. Optional.
• Metric — Indicate if distances are metric based.

The scale is combined with the fast clock speed and the metric indication to calculate the scale mile or scale kilometer. The resulting "smile/skm" is displayed at the bottom.

Train Type

The train type contains a color that will be used for the train graph.

• Type name — The train type name, such as Passenger, Thru Freight, etc.
• Color — The color is selected using a split selector. Click on the color swatch to get the full color chooser or the arrow to get a list of current and standard colors.

The colors help differentiate types or classes of trains.

Segment

Each layout requires at least one segment. Large layouts may have sub-divisions with each sub-division using its own segment.

When a segment is selected, the Graph acton button is added. Select this button to display the train graph. If more than one schedule is defined, a dialog will request the schedule name.

Station

A "station" occurs any place a train can stop or an arrival/departure time is desired. The first station in a segment will have a distance of zero. The remaining stations will have the cumulative distance. The distance is measured in feet or meters depending on the layout metric setting. When multiple segments are being used, the first station of a secondary segment will have the SAME station name as the mainline station.

• Station name — The name of the station.
• Distance — The cumulative distance in feet or meters from the beginning of the segment.
• Double track — Set if a double (or more) track line.
• Sidings — The number of siding tracks at this station.
• Staging — The number of staging tracks when the station is a staging yard.

The double track, sidings and staging fields provide documentation that may be useful.

Schedule

The schedule defines time frame for the timetable.

• Schedule name — The name of the schedule, such as #28.
• Effective date — The date the schedule takes effect. This is a free format field and is only used on the graph.
• Start hour — The start hour is limited to 0 thru 23.
• Duration — The duration can be from 1 to 24 hours.

if the duration is less than 24 hours, then trains will be restricted to running within the specified time frame.

Train

The train item provides required information for the timetable and optional descriptive data.

• Train name — This is usually a short name, or symbol, for the train.
• Description — This is a more descriptive name for the train.
• Type — The train type is selected from the train type list defined earlier.
• Default speed — The default speed is used when the next speed for a stop is set to zero.
• Start time — The start time using hh:mm.
• Throttle — The assigned throttle if using the throttles feature.
• Notes — Additional information about the train, such as special handling.

The calculated duration for the train is also displayed.

Stop

A stop occurs whenever a train has to perform some action or the timetable needs to display the time a train passes a location.

• Station — The selected station for this Stop. The station selection drop down displays both the segment name and the station name.
• Duration — The number of minutes that the train will be at the station. When set to zero, the arrival and departure times are the same.
• Next speed — When set to zero, the train's default speed will be used. If not zero, the next speed will be used to calculate the time to the next station.
• Staging track — The assigned staging track.
• Notes — Additional information about the stop for train.

The series of stops define the route for the train. The assigned sequence number and the calculated arrival and departure times are displayed.

After the stops have been added for a train, the order of the stops can be changed by selecting a stop and using the Up or Down action buttons.

The route for a train can include station stops in more than one segment. For example, segment Mainline has stations A, B, C, D and E, and segment Branch has stations C, X, Y, Z. Station C is the junction point. A train running from A to Z would be assigned Mainline stops A, B and C. The Branch stops would be X, Y and Z. The rule for segment changes is that the first station on the next segment is not a Stop. Z to A would be Branch Z, Y, X and C and Mainline would be B and A.

Timetable Graph

The graph provides a graphical view of the data for a Timetable segment and schedule.

Select which Segment you want to graph from the Segments directory.

The window is divided into 4 sections.

• The upper left section displays the layout, segment and schedule information.
• The station names are listed along the left side. They are positioned relative to the distance from the initial station.
• The top section contains the throttle rows and assignments. If the layout throttle count is zero, this section is blank.
• The body of the graph is in the 4th section. There is a horizontal grid line for each station and a vertical grid line for each hour in the timetable. The trains are represented by colored lines based on the assigned train type. The train name (symbol) is printed at the beginning and end points. The minute values are included based on the main timetable menu selection.

If the schedule duration is 24 hours, a train can wrap around the end of the day as long as the wrap occurs during a station stop duration period. If it occurs while the train is "running", the train diagram gets really goofy.

For trains that span segments, only the activity in the active segment is displayed.

CSV Import

The CSV Import menu item can be used to create and extend the data for a timetable by using additional data from other sources. The input file has the following format.

CSV Record Types. The first field is the record type keyword (not I18N). Most fields are optional.

• "Layout", "layout name", "scale", fastClock, throttles, "metric"
  • Defaults: "New Layout", "HO", 4, 0, "No"
  • Occurs: Must be first record, occurs once
• "TrainType", "type name", color number
  • Defaults: "New Type", #000000
  • Occurs: Follows Layout record, occurs 0 to n times. If none, a default train type is created which will be used for all trains.
  • Note 1: #000000 is black.
  • Note 2: If the type name is UseLayoutTypes, the train types for the current layout will be used.
• "Segment", "segment name"
  • Default: "New Segment"
  • Occurs: Follows last TrainType, if any. Occurs 1 to n times.
• "Station", "station name", distance, doubleTrack, sidings, staging
  • Defaults: "New Station", 1.0, No, 0, 0
  • Occurs: Follows parent segment, occurs 1 to n times.
  • Note: If the station name is UseSegmentStations, the stations for the current segment will be used.
• "Schedule", "schedule name", "effective date", startHour, duration
  • Defaults: "New Schedule", "Today", 0, 24
  • Occurs: Follows last station, occurs 1 to n times.
• "Train", "train name", "train description", type, defaultSpeed, starttime, throttle, notes
  • Defaults: "NT", "New Train", 0, 1, 0, 0, ""
  • Occurs: Follows parent schedule, occurs 1 to n times.
  • Note1: The type is the relative number of the train type listed above starting with 1 for the first train type.
  • Note2: The start time is an integer between 0 and 1439, subject to the schedule start time and duration.
• "Stop", station, duration, nextSpeed, stagingTrack, notes
  • Defaults: 0, 0, 0, 0, ""
  • Required: station number.
  • Occurs: Follows parent train in the proper sequence. Occurs 1 to n times.
  • Note 1: The station is the relative number of the station listed above starting with 1 for the first station.
  • Note 2: If more that one segment is used, the station number is cumulative.

Except for Stops, each record can have one of three actions:

1. If no name is supplied, a default object will be created.
2. If the name matches an existing name, the existing object will be used.
3. A new object will be created with the supplied name. The remaining fields, if any, will replace the default values.

Minimal file using defaults except for station names and distances:

  "Layout"
  "Segment"
  "Station", "Station 1", 0.0
  "Station", "Station 2", 25.0
  "Schedule"
  "Train"
  "Stop", 1
  "Stop", 2
        

The import applies the changes to the data in memory. At the end of the import a dialog is displayed with the option to save the changes to the timetable data file.

CSV Export

The CSV Export menu item is used to create a CSV file that can imported into a spreadsheet program. The timetable data will be for the selected layout, segment and schedule. The train names will be sorted by name and grouped by direction of travel. The stations will be in order based on distance.

While turns are supported by the graphing process, they don't work for a timetable since they have both up and down directions. For these cases use two trains, one for going out and a second one for returning. In the sample below, BT and GT are turns that highlight this issue.

CSV Content:

• Line 1 - Layout name, segment name and schedule name.
• Line 2 - Train names sorted by name and grouped by down or up direction.
• Line 3 to end - Station row with the arrival and departure times for each train.

Sample spreadsheet using the CSV export file:

Data Structure

The following diagram shows the data relationships.

Each record (Java class) has a primary key. This is assigned by the timetable data manager. Foreign keys create the data structure.

Technical

The Timetable data is stored in a fixed xml file located at preference:timetable/TimeTableData.xml. The first time the tool is used, the directory is created and a sample data file is copied from program:xml/demoTimeTable/TimeTableData.xml.

Access to the data is handled by the TimeTableDataManager. The data manager is obtained by calling TimeTableDataManager.getDataManager(). This is a static method that returns the current manager or creates a new one. If a new data manager is created, the data is loaded from the data file. The can only be one occurance, and therefore data, at the same time.

The data manager provides data access methods for the TimeTable application as well as any other JMRI components, such as Jython. The data manager and the data classes perform extensive integrity checking. The IllegalArgumentException will the thrown for any errors. The exception includes a keyword describing the problem. Some exceptions have additional supporting data.

A sample Jython program, TimeTable.py, is included in the JMRI distribution. The program shows how to establish the data manager connection and navigate the timetable data structure.

---