Package jmri

Interface Light

  • All Superinterfaces:
    java.lang.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.

    • Method Detail

      • 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

      • 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:
        java.lang.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.

      • 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.