Skip to main content

JMRI: Sensors Documentation

What are Sensors?

A Sensor is JMRI's way of representing an input from the layout.

JMRI uses a Sensor to represent the status of a block occupancy detector, or a pushbutton on the fascia, or just about anything else you can attach to an input on your DCC or C/MRI system. Sensors are created and managed in the Sensor Table.

Controlling a Sensor

Generally, you don't control the state of a Sensor object; JMRI, working with the hardware on your layout, does.

But there are some occasions where you might like to locally change the state of a Sensor: To debug some logic that uses the Sensor as an input, etc. It can be very convenient to temporarily change how a Sensor is set without having to run out to the layout and push a button or put a locomotive in a block.

Therefore, JMRI lets you change a Sensor via the Sensor Table (see below), or by clicking on a sensor icon on a panel (See the PanelPro pages for more on Panels).

The change takes effect immediately, unless a debounce timer is configured, but only lasts until the next time you change it in the program, or the next time the input hardware on the layout changes the value.

The Sensor Table

Sensors can be viewed and configured using the Sensor Table. The following columns are displayed by default (additional columns may be displayed by right-clicking in the column header and checking by their names, or checking the boxes at the bottom of the window):
  • System Name
  • User Name (optional)
  • State (either Active, Inactive, Inconsistent or - at first - Unknown
  • Comment (optional, double click to edit)
  • Inverted (checkbox)

The Sensor State column can be displayed either as text or as icons. This can be set as a global preferences via a display setting in the main Preferences menu under Display.

Saving Sensors to disk

Sensors are kept in your layout configuration, along with Turnouts, Lights, Signal Heads, control panel setup etc. To store this information on disk, allowing you to reload it the next time you run JMRI, see Loading and Storing Your Work.

Adding a New Sensor

To create a new Sensor, follow this procedure:

  1. Click Tools ⇒ Tables ⇒ Sensors to display the Sensor Table pane. Next, click the Add... button at the bottom of the pane to bring up the "Add/Edit Sensor" window.
  2. From the System drop down list select the system to which the Sensor is connected. In the Hardware Address field enter the hardware address of the input connection being referenced.
    The format of the Hardware Address can often be made in the format of "board:channel" or "Cab Address:Pin"; you will need to confirm the specifics of each system's Naming Rules.
  3. Optionally, enter a User Name for the Sensor. Any string not used by other Sensors will be accepted, but it is useful to enter a name that describes the intended use or location of the Sensor.
  4. You can add a number of Sensors at once by clicking on the Add a Range checkbox and then entering the Number to Add. JMRI will increment the hardware number for each additional sensor. If a hardware address already exists in the Sensors range that is being added, then JMRI will skip that address. If you have entered a User Name, then a number will be appended for each additional sensor to ensure that the User Name is unique.
  5. Click the OK button at the bottom of the pane. If everything is fine, a message stating "New Sensor added..." will be displayed in the notes area. If there is trouble with anything, an error or warning message will be displayed in the notes area; you should then correct the error and click OK again.
  6. You will then see the current status of the sensor (or sensors) in the main Sensor Table panel.

For additional information about working with the Sensor Table, click here.

Sensor Table Controls

Below the table are check boxes to display additional columns with sensor control information.

The Defaults pulldown menu on the window menu bar allows you to set two system-wide settings:

  • Global Debounce Delay: to set debounce time on a system-wide basis (unless overridden). See also below.
  • Initial Sensor State (for Internal Sensors only): lets you choose what state Internal Sensors (system name beginning with "IS") will display after JMRI startup. [Note that the initial state of other sensors cannot be set directly by JMRI, although you can use a script to set them.

Sensor Debounce Delay

The Sensor Debounce Delay helps prevent false triggers of a Sensor being passed into the system and triggering other events in the system.
Such false triggers could be due to a dirty piece of track or electrical interference.

You can assign a delay in milliseconds before any sensor change is registered with the rest of the system. If after that period the state has not changed compared to the original state, the Sensor state will be passed onto the rest of the system.
However if the Sensor's state is different after the delay has passed, then the system will restart the process, this time after the timer has finished it will check to see if the sensor state is in the same state as it was before it restarted the process. If not the process is re-started again until the state is the same before and after the delay has passed.

Sensor Groups

A Sensor Group is a group of sensors of which at most one can be active at a time. When one member of the group becomes active, all others are set to inactive.

Sensor Groups are configured via the Sensor Group Tool.