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, though 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 are also implemented on many other hardware types, including Powerline X10 and DMX512 systems.

Some Lights can have a variable intensity ( brightness ). This is commonly used with the FastClock to produce gradual transition between day and night scenes.

Lights should be used if you need a simple mechanism to control scenery lighting, panel lights or for other general on / off tasks.

Lights contain a number of "Light Control" automation options, an easy way of setting up basic logic and interfacing with Sensors, Turnouts or a Fast Clock.

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. Turnouts should be used to reference the digital output bits used with JMRI Signal Heads.

How to setup Lights

The Light Table

Lights are managed in the Light Table.

Below the Light Table there's an Add... button, for each Light row there's Edit and Delete buttons.

Switching a Light On or Off

Manual: Light Table
Lights can be turned On or Off by clicking the button in the State column of the Light Table.
Manual: Light Control Tool
Lights can be set On, Off, or to a particular intensity in the Light Control Tool.
Automated: Light controlled by Turnout
A Light can follow the state of a Turnout, changing state in reaction to Thrown or Closed.
Automated: Light controlled by Sensor
A Light can follow the state of a Sensor, changing state in reaction to Active or Inactive.
Automated: Light controlled by TWO Sensors
A Light can follow the state of 2 Sensors, changing state when BOTH Sensors are Active or Inactive.
Automated: Light controlled by FastClock
A Light may be configured to follow the JMRI Fast Clock, eg. On 21:00 until 07:00, otherwise Off.
Automated: Light controlled by Timer
Following a Sensor active trigger, Light will turn On for a specified time period, then Off.
Automated: Light controlled by Logix
Conditional actions can be used to set the Light status.
Logix can also set actions for setting Light intensity and transition ( fade ) time duration.
Automated: Jython Scripting
Lights can be easily manipulated with custom Jython scripting for maximum control.
Automated: Incoming Hardware Notification
Some hardware types can broadcast light change notifications, which will then update the Light in JMRI.
Check the hardware support pages for specific support for a system.

You can use multiple Light Controls on a single Light, or if you need something more custom to control your Light, consider using a Logix.

Adding a new Light

Light are added and edited via the Light Table

To add a new Light, click the Tools -> Tables -> Lights menu to bring up the Light Table, and click the Add... button at the bottom left of the table to bring up the Add/Edit Light window.

In this window you can

Editing an existing Light

To edit an existing Light, Click on a Light's Edit button in the Light Table to bring up the Add/Edit Light window.

Saving and Loading Lights

Lights are kept in your layout configuration xml file, along with Turnouts, Sensors, control panel setup etc.

To save this information, allowing you to reload it next time you run JMRI, use Store Configuration... in the File menu at the top of the Light Table (or other tables from the Tools menu), or select Store Panel... in the Panel menu.

When a Light with no Light Control is loaded into the Light Table, it will default to an Off state.

The Light Control is enabled on loading, so will automatically monitor any changes in state of its control Sensor, Turnout, or Fast Clock.

The Light Control enabled / disabled state for each Light is not saved in the configuration file. When Lights are loaded from a configuration file, they are all enabled.

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 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.

Further Light Support

JMRI Light Table

JMRI Add / Edit Light ( including automated Light Controls )

JMRI Light Control Tool ( for manual Light operation )