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 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.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jmri.NamedBean
NamedBean.BadNameException, NamedBean.BadSystemNameException, NamedBean.BadUserNameException, NamedBean.DisplayOptions, NamedBean.DuplicateSystemNameException
-
-
Field Summary
Fields Modifier and Type Field Description static int
FAST_CLOCK_CONTROL
static int
INTERMEDIATE
State value indicating output intensity is less than maxIntensity and more than minIntensity, and no transition is in progressstatic int
NO_CONTROL
static int
SENSOR_CONTROL
static int
TIMED_ON_CONTROL
static int
TRANSITIONING
State value mask representing status where output is changing due to a request to transition.static int
TRANSITIONINGHIGHER
State value indicating output intensity is currently changing toward higher intensity.static int
TRANSITIONINGLOWER
State value indicating output intensity is currently changing toward lower intensity.static int
TRANSITIONINGTOFULLOFF
State value indicating output intensity is currently changing toward lower intensity, and will continue until full OFF is reachedstatic int
TRANSITIONINGTOFULLON
State value indicating output intensity is currently changing toward higher intensity, and will continue until full ON is reachedstatic int
TURNOUT_STATUS_CONTROL
static int
TWO_SENSOR_CONTROL
-
Fields inherited from interface jmri.NamedBean
DISPLAY_NAME_FORMAT, INCONSISTENT, PROPERTY_STATE, QUOTED_NAME_FORMAT, UNKNOWN
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
activateLight()
Activates a Light.void
addLightControl(LightControl c)
Add a LightControl to this Light.void
clearLightControls()
Clears (removes) all LightControl objects for this lightvoid
deactivateLight()
Deactivates a Light.default int
getCommandedState()
Query the commanded state.boolean
getEnabled()
Get the Enabled property, which determines whether the control logic built in the light object is operating or not.default int
getKnownState()
Query the known state.java.util.List<LightControl>
getLightControlList()
int
getState()
Get the current state of the Light's output.default boolean
isConsistentState()
Show whether state is stable.default void
requestUpdateFromLayout()
Request an update from the layout soft/hardware.default void
setCommandedState(int s)
Change the commanded state, which results in the relevant command(s) being sent to the hardware.void
setEnabled(boolean state)
Set the Enabled property, which determines whether the control logic built in the light object is operating or not.void
setState(int newState)
Set the demanded output state.-
Methods inherited from interface jmri.NamedBean
addPropertyChangeListener, addPropertyChangeListener, compareSystemNameSuffix, compareTo, describeState, dispose, getBeanType, getComment, getDisplayName, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListenersByReference, getPropertyKeys, getSystemName, getUsageReport, getUserName, removeProperty, setComment, setProperty, setUserName, toString, updateListenerRef, vetoableChange
-
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
-
-
-
Field Detail
-
INTERMEDIATE
static final int INTERMEDIATE
State value indicating output intensity is less than maxIntensity and more than minIntensity, and no transition is in progress- See Also:
- Constant Field Values
-
TRANSITIONINGTOFULLON
static final int TRANSITIONINGTOFULLON
State value indicating output intensity is currently changing toward higher intensity, and will continue until full ON is reached- See Also:
- Constant Field Values
-
TRANSITIONINGHIGHER
static final int TRANSITIONINGHIGHER
State value indicating output intensity is currently changing toward higher intensity. The current transition will stop before full ON is reached.- See Also:
- Constant Field Values
-
TRANSITIONINGLOWER
static final int TRANSITIONINGLOWER
State value indicating output intensity is currently changing toward lower intensity. The current transition will stop before full OFF is reached.- See Also:
- Constant Field Values
-
TRANSITIONINGTOFULLOFF
static final int TRANSITIONINGTOFULLOFF
State value indicating output intensity is currently changing toward lower intensity, and will continue until full OFF is reached- See Also:
- Constant Field Values
-
TRANSITIONING
static final int TRANSITIONING
State value mask representing status where output is changing due to a request to transition.- See Also:
- Constant Field Values
-
NO_CONTROL
static final int NO_CONTROL
- See Also:
- Constant Field Values
-
SENSOR_CONTROL
static final int SENSOR_CONTROL
- See Also:
- Constant Field Values
-
FAST_CLOCK_CONTROL
static final int FAST_CLOCK_CONTROL
- See Also:
- Constant Field Values
-
TURNOUT_STATUS_CONTROL
static final int TURNOUT_STATUS_CONTROL
- See Also:
- Constant Field Values
-
TIMED_ON_CONTROL
static final int TIMED_ON_CONTROL
- See Also:
- Constant Field Values
-
TWO_SENSOR_CONTROL
static final int TWO_SENSOR_CONTROL
- See Also:
- Constant Field Values
-
-
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 interfaceDigitalIO
- 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 interfaceDigitalIO
- 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 interfaceDigitalIO
- 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 interfaceDigitalIO
- 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 interfaceDigitalIO
-
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.
-
getState
int getState()
Get the current state of the Light's output.
-
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 java.util.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.
-
-