Circuit Builder

since 2.12

The Circuit Builder is a view of a Control Panel Editor panel used to create track circuits that are implemented in JMRI by OBlocks, Portals and OPaths. The prototype name for track having a device that can detect occupancy is Track Circuit. In JMRI we have misused 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 JMRI track circuit is just an attempt to get a little closer to prototype usage. For now, the Circuit Builder tool is concerned with the creation of track circuits, that is, OBlocks and their elements.

Circuit Builder is an alternative to using the Occupancy Block Tables. OBlocks, Portals and OPaths are created and linked by "point and click" on the icons of your layout diagram or panel. The three element types (OBlock, Portal, OPath) are created and edited using three editing modes of the tool. The result of this editing transforms the track in your layout panels to indicator trackage that displays the states of the blocks and paths by color without altering the original look of the panel.

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 will upgrade the track icons to Indicator Track icons. See The Item Palette for more information about Indicator track icons.

Mouse Operations

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

Dragging is not supported except for portal icons when creating or editing Portals
Several Control Panel Menus are disabled.
Only track and portal icons can be selected.

The Menus

The File Menu

The only menu item, Change View to Control Panel Editor, returns the Circuit Builder view to the Control Panel Editor view.

Menus in Common With Control Panel Editor

The Edit, Options, Zoom and Add Item menus are identical to those in Control Panel Editor. When in an editing mode (i.e. in any of menu items under the Add/Edit Circuits menu) these menus are disabled.

The Circuit Builder Menu

Creates and Edit OBlocks, Portals and OPaths and their display icons. The menu has the following menu items:

Add Detector Circuit - Create an OBlock track circuit and assign the icons that display it. You will be prompted for the system and user names to create a new OBlock. Then you will be in circuit editing mode.
Edit Circuit OBlock - Edit an existing circuit (OBlock). You will be asked to select an OBlock from a picklist. Then you will be in circuit editing mode.
Edit Circuit Portals - Create or edit Portals connecting two track circuits. You will be asked to select an OBlock from a picklist. Then you will be in portal editing mode.
Edit Circuit Paths - Create or edit the paths (OPath) through a track circuit. You will be asked to select an OBlock from a picklist. Then you will be in path editing mode.
Edit Portal Direction Icons - since 3.8 Choose arrows to indicate the direction of a Warrant route through a block. You will be asked to select an OBlock from a picklist. Then you will be in Portal icon editing mode.

The Error Check Menu Item

Verify OBlocks, Portals and OPaths are complete and without errors. The menu has the following menu items:

Circuits without icons - Has a submenu for each track circuit OBlock that does not have an icon. A track circuit needs at least one Indicator Track icon to display its state.
Circuits whose icons need conversion - Has a submenu for each track circuit OBlock whose track icons are not Indicator Track icons.
Note: If track icons are not converted to Indicator Track icons the information needed to display circuit states cannot be saved.
Highlight track icons needing conversion - Highlights all track icons that are not Indicator Track icons. If all track icons are Indicator Track icons, this menu item it labeled All track icons are Indicator icons
Highlight Indicator Track icons without circuits - Highlight all track icons that are not associated with a track circuit. If every track icon is associated with a circuit this menu item is labeled All track icons belong to Circuits
Circuits with Portal Icons misplaced - Has a submenu for each track circuit OBlock that has a warning about Portal icon positioning. The choices are:
- A portal icon is positioned incorrectly. i.e. not placed spanning the two blocks of the Portal.
- A portal icon spans an adjacent circuit with no Indicator icons.
Note: When a circuit's icons are not converted to Indicator icons, after saving and reloading portal icons will not be able to detect whether it spans that circuit.
Check Portal and Path errors - Examines the Portal and OPath definitions looking for errors or incomplete information. A dialog box is displayed listing any errors found.

How to Make OBlocks, Portals and OPaths

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

OBlocks - Circuit Editing mode

Creating OBlocks

From the Add/Edit Circuits menu select the Add Detector 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 Add Detector Circuit window.
The Add Detector Circuit window is identical to the Edit Circuit window. See Circuit Editing Mode below for information about this window.

Editing OBlocks

From the Add/Edit Circuits menu select the Edit Circuit Block menu item. This opens a picklist for you to select a circuit OBlock to edit. Selecting a row and pressing the [Open Circuit] button opens the Edit Circuit window.

Circuit Editing Mode

The Edit Circuit window is identical to the Add Detector Circuit window. Its purpose is to identify all the track icons that are used to display the track circuit. It also configures the OBlock sensors for occupancy detection and error indication. Oblock names can be changed and the track circuit deleted. Finally, the circuit track icons can be upgraded to 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 (i.e. OBlock). The icons for a track circuit should be contiguous. The icons that display the circuit are highlighted in blue. Selecting other icon types has no effect. Also, panel items cannot be dragged and repositioned.

Circuit Editing mode Dialog Box

When adding or editing a circuit, the dialog window has text fields to name the sensor that will detect occupancy and a sensor that can detect power problems. Each of these sensors are optional and can be entered later. If no occupancy detection sensor is named, the circuit will be a Dark Block. There is an [Open Picklist] button to display sensor names that can be dragged and dropped onto the sensor name text fields.
The dialog window has a field to show the current state of the circuit.
The Dialog window also has convenience fields that count the track icons that are selected for the circuit.
The Dialog window has a text field to change the name of the circuit (OBlock User Name) and a [Change Name] button to accomplish a name change.
The Convert Icons button will convert the icons in the circuit to Track Indicator icons if they are not already icons of this type. This can be done later. Converted icons may need to be repositioned. This can be done after leaving Circuit Editing mode (pressing the [Done] button).
The Done button completes the creation and editing of the track circuit.
The Delete Circuit button deletes all components of the track circuit. That is, the OBlock, all the OPaths in it and the Portals into and out of the block.

You may leave Dark blocks (no occupancy detection) with track icons unconverted. There is a trade-off here on the appearance.

Portals

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

Portal Editing mode

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

Portal icons are needed to graphically define Paths (See the next section). They serve no other purpose. After you have defined all the track circuits and the Portals and Paths needed to calulate routes; and have created and run warrants; and have tested everything sufficiently, these icons can be removed. On the other hand, there is no harm in letting them persist. They are only visible in the Circuit Builder view.

The Edit Portal window has a list of the portals already defined for the track circuit (OBlock) and a text field to name new portals to be created. The window also has a icon to represent portals as a red circle in the main window.
The text field can be used to change the name of a portal with the [Change Name] button to accomplish the name change.
Portals are created by naming them in the text field and dragging the red circle icon to its position between the two track circuits it connects. After dragging the icon into position the portal is listed in the Portal List.
Portals that were created in the Occupancy Tables do not have red circle icons. For any portal in the Portal List that does not have an icon, select it from the list and drag a red circle icon to its position between the blocks it connects. Portal icons are needed to create and display paths.
Please be sure all portals are represented by icons before making paths.
To change the name of a portal, first select it from the list, then change the name in the Portal Name text field and lastly, press the Change Name button.
To delete a portal, select it from the list and press the Delete Portal button.
The Done button completes the creation and/or editing of Portals.

Paths

From the Add/Edit Circuits menu select the Edit Circuit Paths menu item. This opens a picklist for you to select a circuit OBlock to edit. Selecting a row and pressing the [Open> Circuit] button opens the Add/Edit Path window. The track circuit will be highlighted in blue and if any Portals have been defined, they will be shown with a red circle.

Path Editing mode

The purpose of this window is to create and edit the paths in the track circuit. In this mode, no panel items can be moved or selected.

The Edit Paths window has a list of the paths already defined for the track circuit and a text field to name paths to be created.
The text field can be used to change the name of a path with the [Change Name] button to accomplish the name change.
Paths are created by selecting the icons that display the path. The selected icons are displayed green. A second mouse click deselects the icon.
When selecting a turnout icon for the path, it needs to have its points set correctly. To keep the icon selected green when you throw the switch, hold the Shift Key down when clicking with the mouse. This keeps the selection green while throwing the switch.
It is important the portals for the entrance and/or exit of the path be selected also. When a portal icon (red circle) is selected it turns into a green square. A path will have one portal selected, if it is a stub siding and must have two portals selected (entrance to and exit from the block) if it is a through path.
To change the name of a path, first select it from the list, then change the name in the Path Name text field and lastly, press the Change Name button.
To delete a path, select it from the list and press the Delete Path button.

Further Reference

For a step-by-step instruction on Warrants and Circuit Builder, check out the clinic presentation by Dick Bronson on JMRI 2014 Control Panel Editor plus Warrants.