Adding/Editing Lights

Adding a new Light

To add a new Light, follow this procedure:
  1. 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 pane to bring up the Add Light pane.

  2. Select a System Connection if your layout is connected to more than one system or to create an Internal Light.
    Next enter the Hardware Address of your new Light (often entered as a number, look at the Tooltip for accepted entry patterns per system). 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.
    When you hover your mouse over the Hardware Address entry field, a tooltip will display accepted entry example (depending on availability).
    Some examples of valid System Names are: CL1004, and LL401 (entered as '401' here), 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 of the Light. Entry of a User Name is optional.

  4. If you wish to enter a Control for your new Light, click the Add Control button, and enter your choices into the Add Light Control pane which appears. You may enter as many Light Controls as desired. More information on Light Controls below.

  5. Each Light Control is displayed in the Light Control table on the Add Light and Edit Light pane. The Control Type is shown on the left, followed by a Description of the Control mechanism. These are followed by Edit and Delete buttons. Click Edit to bring up the Edit Light Control pane allowing changes to the control specification as described above. Click a Delete button to remove a Light Control.

  6. Next is the notes area of the Add Light pane. 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 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:

    Correct the error and click Create again.


    Click the Close button to dismiss the pane without creating any more Lights.

Adding several new Lights at Once

If the selected System Connection supports adding multiple Lights at once, the Add Light pane will display two additional items, marked in purple:

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 of items: entry.
If you want to add several new Lights with sequential hardware addresses, check the Add a sequential range check box.
When this box is checked, the Number of items: field is activated. Set the number of Lights you want to add. Enter other properties 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 by the same address), 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 at the bottom of the pane.

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:

Editing an existing Light

To edit an existing Light, follow this procedure:
  1. Click on a Light's Edit button in the Light Table to bring up the Edit Light pane:

  2. The System Name: of the Light is displayed at the top of the pane and cannot be changed once created.
    The User Name may be changed either here or by double clicking on it in the Light Table.
    The Light Control and notes areas are the same as above.

  3. 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 pane is dismissed.


    Click Cancel to exit edit mode without changing the selected Light. If the Edit Light pane 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. Automated operation of a Light can be controlled in one or more of the following ways:

Light Control Cautions

Working with Variable Intensity Lights

If the selected System Connection supports Lights with variable intensity, the Add Light and Edit Light panes will display the Variable Intensity area:

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, just leave the items in the Variable Intensity area as set. When editing a simple ON/OFF light on a system not supporting variable lights, the items in the Variable Intensity area 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 boxes. 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 using a script or other code. 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.

Back to the Light Table help page.