jmri
Interface Light

All Superinterfaces:

NamedBean

All Known Implementing Classes:

AbstractLight, AbstractVariableLight, AcelaLight, LnLight, SerialLight, SerialLight, SerialLight, SerialLight, SerialLight, SerialLight, SpecificLight, SpecificLight, XNetLight

public interface Light
extends NamedBean

Represent a single visible Light on the physical layout.

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.

Author:

Dave Duchamp Copyright (C) 2004, Ken Cameron Copyright (C) 2008, Bob Jacobsen Copyright (C) 2008

Field Summary

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 progress
static int	NO_CONTROL
static int	OFF State value indicating output intensity is at or below minIntensity
static int	ON State value indicating output intensity is at or above maxIntensity
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 reached
static int	TRANSITIONINGTOFULLON State value indicating output intensity is currently changing toward higher intensity, and will continue until full ON is reached
static int	TURNOUT_STATUS_CONTROL

Fields inherited from interface jmri.NamedBean

INCONSISTENT, UNKNOWN

Method Summary

void	activateLight() Activates a light by control type.
void	deactivateLight() Deactivates a light by control type.
String	getControlSensorName() Control type information, valid by control type
int	getControlSensorSense()
String	getControlTimedOnSensorName()
String	getControlTurnoutName()
int	getControlTurnoutState()
int	getControlType() Control type is an instance variable.
double	getCurrentIntensity() Get the current intensity value.
boolean	getEnabled() Get the Enabled property, which determines whether the control logic built in the light object is operating or not.
int	getFastClockOffHour()
int	getFastClockOffMin()
int	getFastClockOnHour()
int	getFastClockOnMin()
double	getMaxIntensity() Get the current value of the maxIntensity property.
double	getMinIntensity() Get the current value of the minIntensity property.
int	getState() Get the current state of the Light's output.
double	getTargetIntensity() Get the target intensity value for the current transition, if any.
int	getTimedOnDuration()
double	getTransitionTime() Get the number of fastclock minutes taken by a transition from full ON to full OFF or vice versa.
boolean	isIntensityVariable() Check if this object can handle variable intensity.
boolean	isTransitionAvailable() Can the Light change it's intensity setting slowly?
boolean	isTransitioning() Convenience method for checking if the intensity of the light is currently changing due to a transition.
void	setControlSensor(String sensorSystemName)
void	setControlSensorSense(int sense)
void	setControlTimedOnSensor(String sensorSystemName)
void	setControlTurnout(String turnoutSystemName)
void	setControlTurnoutState(int ts)
void	setControlType(int controlType)
void	setEnabled(boolean state) Set the Enabled property, which determines whether the control logic built in the light object is operating or not.
void	setFastClockControlSchedule(int onHour, int onMin, int offHour, int offMin)
void	setMaxIntensity(double intensity) Set the value of the maxIntensity property.
void	setMinIntensity(double intensity) Set the value of the minIntensity property.
void	setState(int newState) Set the demanded output state.
void	setTargetIntensity(double intensity) Set the intended new intensity value for the Light.
void	setTimedOnDuration(int duration)
void	setTransitionTime(double minutes) Set the fast-clock duration for a transition from full ON to full OFF or vice-versa.

Methods inherited from interface jmri.NamedBean

addPropertyChangeListener, dispose, getComment, getNumPropertyChangeListeners, getSystemName, getUserName, removePropertyChangeListener, setComment, setUserName

Field Detail

ON

static final int ON

State value indicating output intensity is at or above maxIntensity

See Also:

Constant Field Values

OFF

static final int OFF

State value indicating output intensity is at or below minIntensity

See Also:

Constant Field Values

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

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

NO_CONTROL

static final int NO_CONTROL

See Also:

Constant Field Values

Method Detail

setState

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

Throws:

IllegalArgumentException - if invalid newState provided

getState

int getState()

Get the current state of the Light's output.

Specified by:

getState in interface NamedBean

getControlType

int getControlType()

Control type is an instance variable. Its value is one of the types noted above.

setControlType

void setControlType(int controlType)

isIntensityVariable

boolean isIntensityVariable()

Check if this object can handle variable intensity.

Unbound property.

Returns:

false if only ON/OFF is available.

setTargetIntensity

void setTargetIntensity(double intensity)

Set the intended new intensity value for the Light. If transitions are in use, they will be applied.

Bound property between 0 and 1.

A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

Attempting to set a value below the MinIntensity property value will result in MinIntensity being set. Similarly, setting a value above MaxIntensity will result in MaxINtensity being set.

Setting the intensity to the value of the MinIntensity property will result in the Light going to the OFF state at the end of the transition. Similarly, setting the intensity to the MaxIntensity value will result in the Light going to the ON state at the end of the transition.

All others result in the INTERMEDIATE state.

Light implementations with isIntensityVariable false may not have their TargetIntensity set to values between MinIntensity and MaxIntensity, which would result in the INTERMEDIATE state, as that is invalid for them.

If a non-zero value is set in the transitionTime property, the state will be one of TRANSITIONTOFULLON, TRANSITIONHIGHER, TRANSITIONLOWER or TRANSITIONTOFULLOFF until the transition is complete.

Throws:

IllegalArgumentException - when intensity is less than 0.0 or more than 1.0

IllegalArgumentException - if isIntensityVariable is false and the new value is between MaxIntensity and MinIntensity

getCurrentIntensity

double getCurrentIntensity()

Get the current intensity value. If the Light is currently transitioning, this may be either an intermediate or final value.

A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

getTargetIntensity

double getTargetIntensity()

Get the target intensity value for the current transition, if any. If the Light is not currently transitioning, this is the current intensity value.

A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

Bound property

setMaxIntensity

void setMaxIntensity(double intensity)

Set the value of the maxIntensity property.

Bound property between 0 and 1.

A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

Throws:

IllegalArgumentException - when intensity is less than 0.0 or more than 1.0

IllegalArgumentException - when intensity is not greater than the current value of the minIntensity property

getMaxIntensity

double getMaxIntensity()

Get the current value of the maxIntensity property.

A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

setMinIntensity

void setMinIntensity(double intensity)

Set the value of the minIntensity property.

Bound property between 0 and 1.

A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

Throws:

IllegalArgumentException - when intensity is less than 0.0 or more than 1.0

IllegalArgumentException - when intensity is not less than the current value of the maxIntensity property

getMinIntensity

double getMinIntensity()

Get the current value of the minIntensity property.

A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

isTransitionAvailable

boolean isTransitionAvailable()

Can the Light change it's intensity setting slowly?

If true, this Light supports a non-zero value of the transitionTime property, which controls how long the Light will take to change from one intensity level to another.

Unbound property

setTransitionTime

void setTransitionTime(double minutes)

Set the fast-clock duration for a transition from full ON to full OFF or vice-versa.

Note there is no guarantee of how this scales when other changes in intensity take place. In particular, some Light implementations will change at a constant fraction per fastclock minute and some will take a fixed duration regardless of the size of the intensity change.

Bound property

Throws:

IllegalArgumentException - if isTransitionAvailable() is false and minutes is not 0.0

IllegalArgumentException - if minutes is negative

getTransitionTime

double getTransitionTime()

Get the number of fastclock minutes taken by a transition from full ON to full OFF or vice versa.

Returns:

0.0 if the output intensity transition is instantaneous

isTransitioning

boolean isTransitioning()

Convenience method for checking if the intensity of the light is currently changing due to a transition.

Bound property so that listeners can conveniently learn when the transition is over.

getControlSensorName

String getControlSensorName()

Control type information, valid by control type

getControlSensorSense

int getControlSensorSense()

getFastClockOnHour

int getFastClockOnHour()

getFastClockOnMin

int getFastClockOnMin()

getFastClockOffHour

int getFastClockOffHour()

getFastClockOffMin

int getFastClockOffMin()

getControlTurnoutName

String getControlTurnoutName()

getControlTurnoutState

int getControlTurnoutState()

getControlTimedOnSensorName

String getControlTimedOnSensorName()

getTimedOnDuration

int getTimedOnDuration()

setControlSensor

void setControlSensor(String sensorSystemName)

setControlSensorSense

void setControlSensorSense(int sense)

setFastClockControlSchedule

void setFastClockControlSchedule(int onHour,
                                 int onMin,
                                 int offHour,
                                 int offMin)

setControlTurnout

void setControlTurnout(String turnoutSystemName)

setControlTurnoutState

void setControlTurnoutState(int ts)

setControlTimedOnSensor

void setControlTimedOnSensor(String sensorSystemName)

setTimedOnDuration

void setTimedOnDuration(int duration)

setEnabled

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.

getEnabled

boolean getEnabled()

Get the Enabled property, which determines whether the control logic built in the light object is operating or not.

activateLight

void activateLight()

Activates a light by control type. This method tests the control type, and set up a control mechanism, appropriate for the control type.

deactivateLight

void deactivateLight()

Deactivates a light by control type. This method tests the control type, and deactivates the control mechanism, appropriate for the control type.