Author: Bob Jacobsen
Keywords: light lights hardware variable timed intensity automated layout control controls effect lighting model railroad JMRI CMRI panelpro tools dmx512

# JMRI: Lights Documentation

Lights are digital output bits that function as on/off switches. Some hardware also provides for variable intensity Lights.

What are Lights and how are they used?
What is the Light Table?
  - Using the Light Table
How are Lights added and edited?
  - Add/Edit Lights
How are Lights saved and loaded in JMRI?
How do I control a Light?
  - Editing automated Light controls
  - Manual Light Control Tool
What are variable intensity lights?
  - Adding/editing variable intensity Lights
Links to all JMRI Lights Help

## What are Lights and How Are They Used?

Lights were created to provide an easy way to control fascia panel lights and scenery lighting. They can be used for any purpose that requires an on/off switch, for example, to activate an electromagnetic decoupler for a pre-determined time in response to a fascia panel button, or to play a layout sound via a stationary decoder, or to start or stop an animation triggered by a sensor. In general, Lights provide simple mechanism to control any on/off task on the railroad.

Originally developed for use with C/MRI, Lights are also implemented on many other hardware types, including Powerline X10 and Anyma DMX512 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.

Lights can be turned on or off by clicking the status column in the Lights Table. They can also be automatically controlled:

- by a single Sensor
- by two Sensors
- by a Turnout
- by the JMRI Fast Clock
- or switched on for a specified time by a Sensor.

One or more of these controls may be specified when the Light is created or edited (in the Light Table} as an easy way of setting up basic logic and interfacing with Sensors, Turnouts or a Fast Clock. When a Light is created, or when it is read from a configuration file, the Light is 'activated'; it is set up to monitor automatically any changes in state of these controls. When the controlling Sensor, Turnout, or Fast Clock changes, the Light is switched on or off. Lights can also be controlled by Logix if more complicated control logic is needed.

Depending on the hardware interfacing with your Lights, they can be specified as variable intensity (brightness) rather than just on/off. This is commonly used with the Fast Clock to produce gradual transition between day and night scenes.

## The Light Table

Lights are managed in the Light Table. There is one row in the Light Table for each Light. Each row contains the following columns:

- System Name
- User Name (optional)
- State (On/Off)
- Comment (optional, double click to edit)
- Enabled (Automated Light Control excluding Logix)
- Intensity (availble in certain hardware only)

There is also an Add... button on the bottom left of the window and Delete and Edit buttons on each row.

## Adding and Editing a Light

### Adding a new Light

Light are added to the Light Table (Tools -> Tables -> Lights) via a window accessed by clicking the Add... button at the bottom left of the Light Table window.

In this window you can

- Set the System Name
- Enter a User Name
- Set Light Controls, eg. following a Turnout, Sensor or Fast Clock.

### Editing an existing Light

To edit an existing Light, click on the Edit button in the Light Table row for that Light. This will open the Add/Edit Light window.

## Saving and Loading Lights

Like other JMRI objects such as turnouts and sensors, the Lights in your Light Table are kept in your layout configuration xml file. To save this information, allowing you to reload it next time you run JMRI, see Loading and Storing Your Work.

The Light Control is enabled on loading, so will automatically monitor any changes in state of its control sensor, turnout, or fast clock. When a Light with no Light Control is loaded into the Light Table, it will default to an Off state.

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

## Controlling Lights - Setting On/Off/Intensity

There are several ways to turn a light on or off, both manual and automated. Lights can be turned on or off manually by clicking the button in the State column of the Light Table. A Light can also be controlled by one or more of the following:

- the state of a track switch (Turnout), On when the Turnout is Closed, and Off when it is Thrown, or vice versa
- the state of a block occupancy sensor, on when the sensor is active, and off when it is inactive, or vice versa
- a fascia panel button if a Sensor for that button is defined as the control Sensor.
- the JMRI Fast Clock, On for a specified time period, then Off
- two Sensors, On when either of the two Sensors is Active (or Inactive); two sensor control is useful in controlling layout sounds or crossing gates
- a Logix, as the action of one of its conditionals; Logix should be considered if you need more complex logic to control your Lights

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.

A variable Light may also be adjusted by entering a value of 0.00 to 1.00 in the intensity column for the Light. A Light that does not support variable intensities will consider any non zero value as meaning On. If a Light has transition effects enabled and configured, the Light will respond according to those options. See below for more information on variable Lights.

#### Summay of Light On/Off Control Methods

The various ways to control Lights are listed here. They may be used in combinations for a:

Manual:
  - Light Table: Lights can be turned On or Off by clicking the button in the State column of the Light Table.
  - 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.
  - Light controlled by Sensor: A Light can follow the state of a Sensor, changing state in reaction to Active or Inactive.
  - Light controlled by TWO Sensors: A Light can follow the state of 2 Sensors, changing state when BOTH Sensors are Active or Inactive.
  - Light controlled by FastClock: A Light may be configured to follow the JMRI Fast Clock, eg. On 21:00 until 07:00, otherwise Off.
  - Light controlled by Timer: Following a Sensor active trigger, Light will turn On for a specified time period, then Off.
  - 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.
  - Jython Scripting: Lights can be easily manipulated with custom Jython scripting for maximum control.
  - 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.

## Variable Lights

A variable intensity 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.

The status button for a variable Light in the Light Table will also be a status indication of the variable Light. When it is not On or Off it will show if the last change in intensity was moving higher or lower. The intensity displayed will be the current intensity, not the target intensity, when transition effects are enabled.

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.

## Other Light Reading

Light Table Help

Add/editing Lights<

Editing automated Light Controls

Adding/editing variable intensity Lights

Manual Light Control Tool