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.
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 (see below), 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 Debounce Delay facility is there to help 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.
The facility allows you to assign a delay in
milliseconds before the 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 the 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.
How to set up Sensors
The Sensor TableSensors can be viewed and configured using the Sensor Table. It contains the following columns:
- System Name
- User Name (optional)
- State (either Active, Inactive, Inconsistent or - at first - Unknown
- Comment (optional, double click to edit)
- Inverted (checkbox)
Sensor Table Controls
Below the table is the Add... button
and a check box to Show Sensor Debounce Information
The Defaults menu allows you to set 2 system wide settings:
- Global Debounce Delay
- Initial Sensor State
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 to reload it next time you run JMRI, use Store Configuration... in the File menu at the top of the Sensors Table (or other tables from the Tools menu), or select Store Panel... in the Panel menu.
Adding a new Sensor
To create a new Sensor, follow this procedure:
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.
Enter a User Name for the Sensor. Any string of characters that is different from the User Name of other Sensors will be accepted, but it's wise to use a string that describes the intended use of the Sensor. You can leave this field blank if you'd like.
If you wish to add a number of Sensors at once, click on the Add a Range checkbox and then in the Number to Add field enter the number of Sensors that you wish to add. If you have entered a User Name, then this will be appended with a number to ensure that each User Name is unique. If a hardware address already exists in the Sensors range that is being added, then JMRI will skip that address and carry on.
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.
Back in the main Sensor Table, you can then see the current status of the Sensor.