Circuit Builder

Since 2.12
The Circuit Builder is a view of a Control Panel Editor panel. It is an alternative to using the Occupancy Block Tables to create OBlocks, Portals and OPaths. Circuit Builder is a graphical way to create and configure these objects by "point and click" mouse operations. Here "track circuit" is just another name for "OBlock". The prototype name for track having a device that can detect occupancy is Track Circuit. In JMRI we have used the term "Block" and "OBlock" to refer to what in the prototype world is a track circuit. The term Block in the prototype world is a length of track defined by limits, whose use is governed by block signals, cab signals or block limit markers and train orders. That is, a prototype block incorporates a signaling system providing a way to manage safe usage of its trackage. So to model a prototype block, several track circuits may be needed. The term track circuit here in JMRI is just an attempt to get a little closer to prototype usage, but it is just another name for OBlock and the stuff (Portals and OPaths) that gets it to act a little more like a prototype "Block". Creating track circuits, that is, making and configuring OBlocks, Portals and OPaths enables the creation and running of Warrants.

Since 4.17.3
Circuit Builder also configures Signal Masts or Signal Head at Portals to display aspects and appearances that indicate track conditions on your layout. These signals then can modify warrants during their runtime to respond to track conditions.

Getting Started

Make a track diagram of your layout using track icons - of any kind, but eventually they will need to be some kind of Indicator Track. The Item Palette can help you select the kind you want. Then open CircuitBuilder from the Warrant menu. The CircuitBuilder menu will appear. Now use CircuitBuilder menu to make two track circuits (OBlocks).
Add/Edit OBlocks
After making two OBlocks you can make and configure the following items:
Add/Edit Portals
Add/Edit Paths
Edit Portal direction Arrows
Add/Edit Signals
When you are done editing, select the items under the Error Checks submenu for errors and omissions.

Basic Operational Model of Circuit Builder

Circuit Builder works by using icons on a block by block basis. OBlocks, Portals and OPaths are created and linked by "point and click" on the icons of your layout diagram. The element types (OBlock, Portal, OPath, Signal) are created and edited using various editing modes of the tool. In short, it works as follows:

First create an OBlock by selecting track icons. Then create Portals by dragging an icon that overlaps two OBlocks. Then create OPaths by selecting the portal icons and track icons that indicate the path. Finally perhaps add a signal to protect an OBlock by selecting the portal of the approach. The result of this editing transforms the track in your layout panels to indicator trackage displaying the states of the blocks and their paths by color without altering the original look of the panel. These operations are done from the CircuitBuilder menu items and are detailed below.

Panel files previously made with Panel Editor can be used with Circuit Builder as long as they can be loaded into this version of JMRI. Circuit Builder upgrades plain track icons to Indicator Track icons. See The Item Palette for more information about Indicator track icons.

CircuitBuilder is aware of all the objects defined in the Occupancy Block tables. If your layout track diagram is split up among several panels, CircuitBuilder will edit with the icons on each panel separately. It may post messages about missing icons but if the objects are not meant to be represented on that panel, ignore them.

Mouse Operations When Using CircuitBuilder

When in an editing mode of Circuit Builder, the mouse click conventions differ somewhat from those of the panel editors. When a Circuit Builder menu item is selected an editing window is opened and the panel is in a Circuit Builder editing mode. Note the following when in a Circuit Builder editing mode:

Portal Icons

When not in one of the CircuitBuilder editing modes, portal icons are usually invisible. The only situation in normal panel operation where they may be visible is when a warrant is allocated. In this case direction arrows can be shown indicating the direction of travel of the warranted train. Portal icons are necessary for CircuitBuilder to be able to define Portals and OPaths. In such editing modes the icon is usually a red circle that may be dragged or selected. Note: It is important for defining paths that every track circuit depicted on the panel have all its portals represented by a portal icon.

The Circuit Builder Menu

The menu has the following menu items: (except for the items "Add Detector Circuit" and "Error Checks" menu items). The menu item will first ask you to select an OBlock from a pick list. Notice that except for the first and last menu items, first you choose the OBlock, then create or edit the element. For convenience, the Warrant menu item Open CircuitBuilder opens a window with the various editing modes available from radio buttons.

How to Make OBlocks, Portals and OPaths

Creation and editing of these objects is done is with the editing modes of Circuit Builder.

Creating OBlocks

From the Circuit Builder menu select the Add OBlock Circuit menu item. This opens a dialog for you to create a circuit OBlock by supplying its system and user name. Creating the OBlock opens the Edit Circuit OBlock window.
Note: Each OBlock must have at least one Indicator Track icon to represent it. Otherwise CircuitBuilder cannot define Portals and Paths

Editing OBlocks

From the Circuit Builder menu select the Edit Circuit OBlock menu item. This opens a picklist for you to select a circuit OBlock to edit. Selecting a row and pressing the Show OBlock button opens the Edit Circuit window. If any track icons have been defined to indicate the OBlock, they will be highlighted in blue.

Circuit Editing Mode

The Edit Circuit window used is to identify all the track icons will display the track circuit. It also configures the OBlock sensors for occupancy detection and error indication. OBlock user names can be changed or have a track circuit OBlock. The length of block can be entered as either inches or centimeters. deleted. Finally, the circuit track icons can be upgraded to be Indicator Track icons.

In this mode, mouse clicks on a track icon in the basic window frame toggles selection of the track. Select the icons you want to use to display the track circuit. The icons for a track circuit typically are, but need not be contiguous. The icons that display the circuit are highlighted in blue. Icon types other than track icons cannot be selected. No icons can be dragged.

When exiting the Edit Circuit window the OBlock is checked for any possible deficiencies. If any are detected you will be prompted and given the option to return to the window or continue to close it.

Portals - Add/Edit Circuit Portals

From the Circuit Builder menu select the Add/Edit Circuit Portals menu item. This opens a picklist for you to select a circuit OBlock to edit. Selecting a row and pressing the Show OBlock button opens the Add/Edit Portal window. The track circuit will be highlighted in blue. if any Portals have been defined, they will be shown as a red circle and also highlighted in blue.

Portal Editing mode

Use this window create and edit portals. A portal is represented by a red circle icon. The blocks it connects are determined by positioning a portal icon so it spans the two blocks it connects. That is, the icon should overlap a track icon representing each of the two blocks. In this mode, only portal icons can be repositioned. No other panel items can be moved or selected.

To create a new portal type in a name for it in the Portal Name text field. Then drag the red circle portal icon to the panel. Place it so that it intersects with a track icon representing the OBlock you selected to open the window. The OBlock circuit you selected is the "home" block. Position the portal icon so it also intersects with a track icon representing an adjacent block. Overlapping both blocks defines the portal.

To create an icon for a portal previously defined, perhaps from the Occupancy Block tables, select the portal from the "Portals into and out of circuit ..." list. Then, as above drag and position the red circle icon.

Notice that when you select a portal from the portal list, its icon highlight changes from blue to pink. Conversely, selecting an portal icon on the panel with a mouse click will select the portal it represents in the portal list. When repositioning a portal icon it may be necessary to "unlock" its position.

There may be diagrams where a portal icon cannot span icons from each block that the portal connects. An example of this might be when the panel diagram depicts a loop as a line of blocks across the panel from left to right. Here a leftmost block icon cannot be spanned by one from the rightmost block. This can be handled in one of two ways. A non-contiguous track icon could be placed from one edge onto the opposite edge of the diagram and a have the portal icon overlap both blocks there.
(since 4.17.3) Or two portal icons can be used for the same portal. Each icon placed on the respective blocks at the opposite sides of the diagram.

When exiting the Add/Edit Portal window the Portal is checked for any possible deficiencies. If any are detected you will be prompted and given the option to return to the window or continue to close it.

Paths - Add/Edit Circuit Paths

From the Circuit Builder menu select the Add/Edit Circuit Paths menu item. This opens a picklist for you to select a circuit OBlock to edit. Selecting a row and pressing the Show OBlock button opens the Add/Edit Path window. The track circuit will be highlighted in blue and the portal icons shown with a red circle and highlighted in blue.

Path Editing mode

Use this window is to create and edit the paths in the track circuit. In this mode, no panel items can be moved and only track and portal icons can be selected.

To create a new OPath, first press the Clear Selection button. Then type a name for the path into the Path Name text field. Now select all the track icons that mark the route. Selected route icons change their color to green. When selecting a turnout track icon, the position of the points may not be correct. To change the position of the points, hold the Shift key down while clicking on the turnout icon. At least one portal must be selected to complete the definition of an OPath. A selected a portal icon changes from a red circle to a green square.

Be sure you select all the turnout icons for turnouts that need to be set to define the path. Also be sure that the portal icons needed for entrance and exit are selected. A path must have at least one portal and at most two.

If the value of the Length text field is "0.0" the length of the path will be inherited from the value of what was entered for the length of the OBlock circuit. If the length of the path is significantly different from the OBlock length (i.e. by more than 10%), enter a length for the path. Note: Path lengths are needed for a warrant to calculate where to begin a speed change required by a signal aspect or block occupation ahead of the train.

When exiting the Add/Edit Path window the Path is checked for any possible deficiencies. If any are detected you will be prompted and given the option to return to the window or continue to close it.

Portals - Edit Portal Direction Icons

Since 3.8
From the Circuit Builder menu select the Edit Portal Direction Icons menu item. This opens a picklist for you to select a circuit OBlock to edit. Selecting a row and pressing the Show OBlock button opens the Edit Portal Direction Arrows window. The track circuit will be highlighted in blue and the portal icons shown with a red circle and highlighted in blue.

Portal Direction Arrows Editing

Use this window to modify the portal icon to show the direction of travel for a warrant. Portal icons must exist in order to have direction arrows when a warrant is allocated.

To set the direction, either select a portal icon or select a portal from the "Portals into and out of circuit ..." list. A green arrow will replace the red circle on the highlighted portal icon. To have the arrow display the correct direction the arrow must point into the OBlock circuit. If it does not, select one or the other of the green arrows on the Entry Icon box. The arrows can be moved and rotated to display a more desirable direction. If a n icon is moved, be sure it retains its position overlapping the blocks it joins.

If you do not want an arrow to display at the portal when a warrant is allocated, select the "No Icon" icon.

After all the portal icon arrows are pointing into the block, verify that each adjacent OBock also has its portal direction arrow set into that block.

Signals - Edit Signal Masts

Since 4.17.3
From the Circuit Builder menu select the Add/Edit Signal Masts menu item. This opens a picklist for you to select a circuit OBlock where you want to have protection by signals. Selecting a row and pressing the Show OBlock button opens the Add/Edit Signals window. The track circuit icons will be highlighted in blue and the portal icons shown with a red circle highlighted in blue.

Signal Position Editing

Use this window to configure a Signal Head or Signal Mast to protect the OBlock. There is a "speed name" associated with every signal aspect that limits the speed a train may have through the protected block. The speed names are mapped to speed numbers by a table in Warrant Preferences. Warrants use the speed number to modify the scripted speed before entering the block. The meaning of the speed number is interpreted to be according to your choice of a radio button in Warrant Preferences.

To set a signal to protect the OBlock, choose the portal where the signal will guard entrance into the block. The opposing block of the portal will be the approach OBlock. Choosing the portal can be done by either selecting a highlighted portal icon or selecting a portal from the "Portals into and out of circuit ..." list.

Enter the name of the signal into the Signal Name text field. Alternatively there are Open Picklist buttons to display signal names. Drag a name into the Signal Name text field. Pressing the Configure Signal button will attach the signal at the portal.

Important Note:
It is recommended to use Signal Masts rather than Signal Heads. If you do use a Signal Head be sure it is not part of the definition of a Signal Mast. Signal Head appearances are translated to speed names according to to a table in Warrant Preferences. Then, as above, the speed name is used to regulate train speed.

The signal add/edit window has the following items.

Selecting a signal icon will select the portal if it protects the block there. Otherwise a dialog windows opens to configure or replace protection.

Further Reference