Adding/Editing Lights

Adding a new Light

To add a new Light, follow this procedure:

Click Lights in the Tables submenu of the Tools menu to bring up the Light Table, and click the Add... button at the bottom of the Light Table to bring up the "Add" version of the Add/Edit Light window.
Select a System: if your layout is connected to more than one system or if creating an internal Light. Next enter the Hardware Address: of your new Light (usually a number). This is the address JMRI will send to your system when switching the Light. From this information, the program will make a System Name in the JMRI convention, appropriate for a Light in the selected System using the entered address. Examples of valid System Names are: CL1004, and 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 of the Light. Entry of a user name is optional.
If you wish to enter a control for your new Light, click the Add Control button, and enter your choices into the Add/Edit Light Control window which appears. You may enter as many Light Controls as desired. More information on Light Controls is below.
Each Light Control is displayed in the Light Control table. The Control Type is shown on the left, followed by a Description of the Control mechanism. These are followed by Edit and a Delete buttons. Click Edit to bring back the Add/Edit Light Control window allowing changes to the control specification. Click Delete to remove a Light Control.
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 window. 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.

-OR-

Click the Cancel button to dismiss the window without creating any more Lights.

Adding several new Lights at Once

If the selected System: supports adding multiple Lights at once, the Add/Edit Light window will display two additional items, as shown below:

Adding several new Lights at once is optional. If you only want to add one new Light, ignore the Add a sequential range check box and the Number to Add: entry. If you want to add several new Lights with sequential hardware addresses, click the Add a sequential range check box. When this box is checked, the Number to Add: entry is active. Enter the number of sequential entries you want to add. Enter other items for the first Light, following the procedure above, and click the Create button. If any of the requested addresses are not available (previously assigned to a Light or a Turnout), a message will appear in the notes area, and no new Lights will be created. If everything checks out, the requested Lights will be created, and a message will appear in the notes area

Adding multiple Lights at once is intended to support stationary decoders which require several addresses in sequence. As a result, restrictions apply when creating several Lights at once. Note the following:

The addresses must be numerical--only numbers are allowed in the hardware address.
The addresses of the created Lights must be consecutive.
All requested addresses must be available, i.e., not currently assigned to a Light or Turnout.
If a user name is entered, each of the created Lights will have that user name with "+1", "+2", etc. appended.
Entered Light Control items and Variable Intensity items will be assigned to the first Light created, and not to subsequent Lights. These items may be added by Editing (see below).

Editing an existing Light

To edit an existing Light, follow this procedure:

To Edit of an existing Light click on a Light's Edit button in the Light Table to bring up the "Edit" version of the Add/Edit Light window.
The System Name: of the Light is displayed at the top of the window and cannot be changed. The User Name: may be changed either here or in the Light Table. The Light Control and notes areas are the same as above.
After making changes to the Light information, click Update to change the selected Light. 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. If all is fine, the Light is changed and the Add/Edit Light window is dismissed.

-OR-

Click Cancel to exit edit mode without changing the selected Light. If the Add/Edit Light window 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 Add/Edit Light Control window is used to specify a Light control. The operation of a Light can be controlled in the following ways:

By Sensor - The Light will be turned ON when the 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 position 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.
By Two Sensors - The Light will be turned ON when the either of the two sensors changes to active or inactive, depending upon the choice made in the Sense for ON popup menu, and it will be turned OFF, when both of the two sensors are in the reverse state. Specify each sensor by entering its name (system name or user name) in the Sensor Name field. The order of entry does not matter. This option has multiple uses, such as controlling crossing gates with point sensors that detect when a train passes. By placing two point sensors, one at each end of a bridge, a layout sound for a bridge rumble may be played while the train is traversing the bridge.

Light Control Cautions

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. The sensor or turnout must be in the Sensor Table or the Turnout Table.
If you enter a user name to specify a sensor or a turnout, be very careful about changing the user name of your sensor or turnout. A simple change of user name could break your Light control definitions.
If you enter multiple Light controls for the same Light, it is possible that the Light controls might conflict or overlap with each other, producing strange results. The user is responsible for ensuring that Light controls do not conflict.

Working with Variable Intensity Lights

If the selected System: supports Lights with variable intensity, the Add/Edit Light window will display the Variable Intensity area shown below when adding a Light:

Systems, like PowerLine, that support variable intensity lights also support lights with fixed intensity. If you are adding a Light with fixed intensity, i.e. an ON/OFF light, ignore the items in the Variable Intensity area. When editing a simple ON/OFF light, the items in the Variable Intensity area are not relevant, and are not displayed.

The intensity of a Light is represented internally by the range from 0.0 to 1.0, with 1.0 being brightest. Intensity limits are entered as percentages, from 0 through 100, in the Minimum Intensity and Maximum Intensity fields. Because the actual light hardware has only finite resolution, the intensity value is mapped to the nearest supported setting.

Each Light has a Target Intensity property which can be set directly. Attempting to set the Target Intensity outside the Minimum Intensity to Maximum Intensity range will result in the Target Intensity being set to the relevant limit.