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
It contains the following columns:
- System Name
- User Name (optional)
- Comment (optional, double click to edit)
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:
- 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.
- 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:
LL401, assuming you have the hardware for the addressed digital output bits.
- 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.
- 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.
- 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.
- 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.
- 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:
- Edit of an existing Light may be started in either of two ways:
- 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.
- 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.
- 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 LightsThe operation of a Light can be controlled in the following ways:
By Sensor - The Light will be turned on when the Control Sensor changes to active or inactive, depending upon the choice made in the 'Sense for ON' popup menu, and it will be turned off, when the sensor reverses state. Specify the Sensor by entering its name (System Name or User Name) in the 'Sensor Name' field. This option has a number of uses, including setting a fascia panel light to follow Block occupancy. That is useful, for example, for monitoring train positions in a hidden staging area.
By Fast Clock - The Light will be turned on when the Fast Clock reaches the time entered in 'Time On' and will be turned off when the Fast Clock reaches the time entered in 'Time Off'. The times are entered in "hh:mm" format, where "hh" is hours and "mm" is minutes for a 24-hour clock. One use of this option is to turn on and off scenery lighting, street lights, house lights, etc. to simulate night time on the layout.
By Turnout Status - The Light will be turned on when the turnout changes to closed or thrown, depending upon the choice made in the 'Status for ON' popup menu, and it will be turned off, when the turnout reverses its status. Specify the Turnout by entering its name (System Name or User Name) in the 'Turnout Name' field. This option may be used to set a fascia panel light to follow the status of a Turnout. That is useful, for example, for monitoring the status of hidden turnouts.
By Timed ON - The Light will be turned on when the trigger Sensor changes to Active, and it will be turned off when the specified time has elapsed. Specify the trigger Sensor by entering its name (System Name or User Name) in the 'Trigger Sensor Name' field. Enter the time the Light is to remain on (in milliseconds) in the 'Duration ON' field. This option has a number of uses, it was originally designed to turn on an electromagnetic decoupler in response to a fascia pushbutton, but it can also be used for other types of layout animation, for example, to control the ringing of a crossing bell when a Train enters a Block.
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:
- 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.
- 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.