Package jmri

Interface Light

All Superinterfaces:
Comparable<NamedBean>, DigitalIO, NamedBean, PropertyChangeProvider
All Known Subinterfaces:
VariableLight
All Known Implementing Classes:
AbstractLight, AbstractVariableLight, AcelaLight, AnymaDMX_UsbLight, BiDiBLight, CbusLight, DCCppLight, IpocsLight, JMRIClientLight, LnLight, MqttLight, NceLight, OlcbLight, SerialLight, SerialLight, SerialLight, SerialLight, SerialLight, SerialLight, SerialX10Light, SpecificDmxLight, SpecificInsteonLight, SpecificInsteonLight, SpecificLight, SpecificLight, SpecificLight, SpecificX10Light, SpecificX10Light, XBeeLight, XNetLight
public interface Light extends DigitalIO
Represent a single visible Light on the physical layout.

Each Light may have one or more control mechanisms. Control mechanism types are defined here. If a Light has any controls, the information is contained in LightControl objects, which are referenced via that Light.

Lights have a state and an intensity.

The intensity of the hardware output is represented by the range from 0.0 to 1.0, with 1.0 being brightest.

The primary states are:

  • ON, corresponding to maximum intensity
  • INTERMEDIATE, some value between maximum and minimum
  • OFF, corresponding to minimum intensity
The underlying hardware may provide just the ON/OFF two levels, or have a semi-continuous intensity setting with some number of steps.

The light has a TargetIntensity property which can be set directly. In addition, it has a CurrentIntensity property which may differ from TargetIntensity while the Light is being moved from one intensity to another.

Intensity is limited by MinIntensity and MaxIntensity parameters. Setting the state to ON sets the TargetIntensity to MinIntensity, and to OFF sets the TargetIntensity to MaxIntensity. Attempting to directly set the TargetIntensity outside the values of MinIntensity and MaxIntensity (inclusive) will result in the TargetIntensity being set to the relevant limit.

Because the actual light hardware has only finite resolution, the intensity value is mapped to the nearest setting. For example, in the special case of a two-state (on/off) Light, setting a TargetIntensity of more than 0.5 will turn the Light on, less than 0.5 will turn the light off.

Specific implementations will describe how the settings map to the particular hardware commands.

The transition rate is absolute; the intensity changes at a constant rate regardless of whether the change is a big one or a small one.

This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  • Field Details

  • Method Details

    • isConsistentState

      default boolean isConsistentState()
      Show whether state is stable. For turnouts, a consistent state is one you can safely run trains over. For lights, it's a state which is either on or off, not in between.
      Specified by:
      isConsistentState in interface DigitalIO
      Returns:
      true if state is valid and the known state is the same as commanded

    • setCommandedState

      @InvokeOnLayoutThread default void setCommandedState(int s)
      Change the commanded state, which results in the relevant command(s) being sent to the hardware. The exception is thrown if there are problems communicating with the layout hardware.
      Specified by:
      setCommandedState in interface DigitalIO
      Parameters:
      s - the desired state

    • getCommandedState

      default int getCommandedState()
      Query the commanded state. This is a bound parameter, so you can also register a listener to be informed of changes.
      Specified by:
      getCommandedState in interface DigitalIO
      Returns:
      the commanded state

    • getKnownState

      default int getKnownState()
      Query the known state. This is a bound parameter, so you can also register a listener to be informed of changes. A result is always returned; if no other feedback method is available, the commanded state will be used.
      Specified by:
      getKnownState in interface DigitalIO
      Returns:
      the known state

    • requestUpdateFromLayout

      @InvokeOnLayoutThread default void requestUpdateFromLayout()
      Request an update from the layout soft/hardware. May not even happen, and if it does it will happen later; listen for the result.
      Specified by:
      requestUpdateFromLayout in interface DigitalIO

    • setState

      @InvokeOnLayoutThread void setState(int newState)
      Set the demanded output state. Valid values are ON and OFF. ON corresponds to the maxIntensity setting, and OFF corresponds to minIntensity.

      Bound parameter.

      Note that the state may have other values, such as INTERMEDIATE or a form of transitioning, but that these may not be directly set.

      Specified by:
      setState in interface NamedBean
      Parameters:
      newState - the new desired state
      Throws:
      IllegalArgumentException - if invalid newState provided

    • getState

      int getState()
      Get the current state of the Light's output.
      Specified by:
      getState in interface NamedBean
      Returns:
      the state

    • clearLightControls

      void clearLightControls()
      Clears (removes) all LightControl objects for this light

    • addLightControl

      void addLightControl(@Nonnull LightControl c)
      Add a LightControl to this Light.

      Duplicates are considered the same, hence not added

      Parameters:
      c - the light control to add.

    • getLightControlList

      @Nonnull List<LightControl> getLightControlList()
      Returns:
      a list of all LightControls

    • setEnabled

      @InvokeOnLayoutThread void setEnabled(boolean state)
      Set the Enabled property, which determines whether the control logic built in the light object is operating or not. Light objects are usually enabled.
      Parameters:
      state - true if control logic is enabled; false otherwise

    • getEnabled

      boolean getEnabled()
      Get the Enabled property, which determines whether the control logic built in the light object is operating or not.
      Returns:
      true if control logic is enabled; false otherwise

    • activateLight

      @InvokeOnLayoutThread void activateLight()
      Activates a Light. This method activates each LightControl, setting up a control mechanism, appropriate to its control type.

    • deactivateLight

      @InvokeOnLayoutThread void deactivateLight()
      Deactivates a Light. This method deactivates each LightControl, shutting down its control mechanism.