Skip to main content

JMRI is...

Common Tools

JMRI provides powerful tools for working with your layout.

System-specific Tools

Layout Automation

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

JMRI: Lights Documentation

What are Lights?

Lights are digital output bits that function as on/off switches. Lights were created to provide easy control for fascia panel lights and scenery lighting. Lights can also be used for any purpose that requires an on/off switch. A light can be used, for example, to activate an electromagnetic decoupler for a pre-determined time in response to a fascia panel button. Originally developed for use with C/MRI, Lights currently are also implemented on LocoNet (Digitrax), Oaktree and MERG CBUS systems.

Lights share available digital output bits with Turnouts. Either a Light or a Turnout, but not both, can control a specific digital output bit. Since Lights lack the feedback structure of Turnouts, Lights should not be used to control track switches (Turnouts) on the layout; only Turnouts should be used to control track switches. For historical reasons, Signal Head appearances are defined using Turnouts, even though they may actually be physical lights. So Turnouts should be used to reference the digital output bits used with JMRI Signal Heads. Lights should be used if you need a simple mechanism to control scenery lighting or panel lights, or for other on/off tasks where the control mechanisms of Lights fit the need.

Optionally a Light may be controlled in one of four ways: it may be controlled by a Sensor, by a Turnout, by the JMRI Fast Clock, or switched on for a specified Time by a sensor. When a Light is created, or when it is read from a configuration file, the Light is 'activated'; it is set up to automatically monitor any changes in state of its control Sensor, Turnout, or Fast Clock. When the controlling Sensor, Turnout, or Fast Clock changes in a user-specified way, the Light is switched on or off. Lights can also be controlled by Logix, if more complicated control logic is needed.

The Light Table contains an 'Enabled' column. For a Light to be triggered by its control Sensor, its control Turnout or the Fast Clock it must be "enabled", that is, its check box in the 'Enabled' column must be checked. You can uncheck this box to temporarily disable a Light from being triggered, i.e. prevent it switching when its control mechanism fires.

How to setup Lights

The Light Table

Lights are created and edited in the Light Table.
It contains the following columns:

Light Table Controls

Below the Light Table there's an Add... button.

In each line of the table is an Edit and a Delete button.

Switching a Light On or Off

Lights may be turned on or off by clicking the button in the State column of the Light Table. A Light may be set up to follow the state of a track switch (Turnout), On when the Turnout is Closed, and Off when it is Thrown, or vice versa. A Light may be set to follow the state of a Block occupancy Sensor, On when the Sensor is Active, and Off when it is Inactive, or vice versa. A Light may also be set by a fascia panel button if a Sensor for that button is defined as the Control Sensor. A Light may be configured to follow the JMRI Fast Clock, On for a specified time period, then Off. A Light may also be controlled from a Logix, as the action of one of its Conditionals. If you need more powerful logic to control your Light, consider using a Logix.

Note that enabled/disabled applies only to a Light's automated control mechanism. A 'disabled' state will not prevent a Light from being turned On or Off using the button in the Light Table or from being controlled by a Logix.

Saving Lights to disk

Lights are saved in your layout configuration file, along with Turnouts, Sensors, Signal Heads, etc. To store this information on disk, use Store Configuration... in the File menu at the top of the Lights Table (or other tables from the Tools menu), or select Store Panel... in the Panel menu. Note that the enabled/disabled state of each Light is not saved in the configuration file. When Lights are loaded from a configuration file, they are all enabled.

Adding a new Light

To add a new Light, follow this procedure:

  1. Click the Tools -> Tables -> Lights menu to bring up the Light Table, and click the Add... button at the bottom of the pane to bring up the Add/Edit Light pane.
  2. Enter a System Name, according to the JMRI convention. The first letter designates your hardware system ('L' for LocoNet, 'C" for C/MRI, etc.), and the second letter must be 'L' for Light. These are followed by a number that gives the hardware address of the digital output bit being referenced. Examples of valid system addresses are: CL1004 and LL401, assuming you have the hardware for the addressed digital output bits.
  3. Enter a User Name. Any string of characters that is different from the User Name of other Lights will be accepted, but it's wise to use a string that describes the intended use or layout location of the Light.
  4. Select the control type from the options in the popup menu. When you change the control type, different options appear on the two lines below. Control options are discussed in more detail below.
  5. Enter the required information to complete the control definition in the fields that appear. If you need to enter a Sensor name or a Turnout name, you must enter the name (System Name or User Name) of an existing Sensor or Turnout. Caution: if you choose to enter a User Name, be careful about changing the User Name of your Sensor or Turnout afterwards. A simple change of User Name could break your Light control definition.
  6. Next is the notes area of the Add/Edit Light window. This is where instructions and error messages will appear as you create or edit a Light. Always check this area to see if things went as expected.
  7. Click the Create button at the bottom of the pane. If everything is fine, a message stating "New Light 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 Create again.

Editing an existing Light

To edit an existing Light, follow this procedure:

  1. Edit of an existing Light may be started in either of two ways:
    • Click on a Light's Edit button in the Light Table.
    • Enter the System Name of the Light to be edited in the Add/Edit Light pane and click the Edit button at the bottom of the pane. This must be the same as the System Name shown in the Light Table.
    The Create and Edit buttons at the bottom of the Add/Edit Light panel will change to Update and Cancel.
  2. Make whatever changes or additions you need to the information in the dialog. Note that the System Name of the edited Light may not be changed, but the User Name may be changed. Other items are as described above.
  3. After making changes to the Light information, click Update to change the selected Light. If everything is fine, a message stating "Light updated... " will be displayed in the notes area. If there is any trouble, an error or warning message will be displayed in the notes area, and the update is stopped for you to correct the error and click Update again.
  4. Click Cancel to exit edit mode without changing the selected Light. If the Add/Edit Light panel is dismissed (closed) while in edit mode, Cancel is automatically selected, and no changes are made to the selected Light.

Automated Control Options for Lights

The operation of a Light can be controlled in the following ways:

Variable Lights

A variable Light allows for a variable number of intensities between on and off. The typical use would be for layout lighting simulating the changes for the time of day and night. Only some forms of Lights have the ability to be variable. Examples would include Internal and PowerLine devices. A number of configuration options are available for variable Lights below.

A variable Light is adjusted by an intensity setting. The range of the intensity is from 0.00 for full Off to 1.00 which is full On. User entry for the intensity will either use a floating point value from 0 to 1 or a percentage value of 0% to 100%.

Depending on the hardware used, some variable Lights will make an initialization adjustment when switching from simple on/off mode to using intensity settings. On such devices this will not be needed again as long as only intensity setting commands are used. Mixing on/off commands may require the initialization to occur again.

A Variable Light has three types of operators:

On
This operation will turn a Variable Light on. It will over-ride any current intensity and set the intensity to 1. If there are any transition effects enabled, they will be ignored and intensity will go to the maximum amount.
Off
This operation will turn a Variable Light off. It will over-ride any current intensity and set the intensity to 0. If there are any transition effects enabled, they will be ignored and intensity will go to the maximum amount.
Set Intensity
This operation will set a target intensity for the Variable Light. If the interface supports transition effects and they are configured, the Light will make a controlled transition from the current setting to the new setting.

Variable Light Settings

These settings adjust how the 'set intensity' command is used.

Minimum Intensity:
A value 0 to 100 (percent) that sets the lowest amount of light that will be output by a dim command. An explicit Off command will ignore this value.
Maximum Intensity:
A value 0 to 100 (percent) that sets the highest amount of light that will be output by a dim command. An explicit On command will ignore this value.
Transition Time:
Number of Fast Clock minutes to go from 0% to 100% intensity. A value of zero will cause the device to change from one intensity to new intensity as fast as the device is able to do so.