org.lsst.ccs.monitor

Class Device

java.lang.Object

org.lsst.ccs.monitor.Device

All Implemented Interfaces:

HardwareController, HasLifecycle, UsesSubsystem

Direct Known Subclasses:

CalcDevice, Device

public abstract class Device
extends Object
implements HardwareController, HasLifecycle, UsesSubsystem

Handles hardware devices

Author:

Owen Saxton

Field Summary

Fields

Modifier and Type	Field and Description
protected BitSet	chanMask
protected Map<String,Control>	ctlChans
protected boolean	disabled
protected String	fullName Data fields.
protected boolean	inited
protected int	lineMask
protected int	lineState
protected int	lineWarm
protected Logger	log
protected Monitor	mon
protected String	name
protected boolean	online
protected Subsystem	s

Constructor Summary

Constructors

Constructor and Description
Device()

Method Summary

Modifier and Type	Method and Description
protected void	addChannel(int id) Adds a channel to the device's list of monitored channels.
protected void	addLine(int line) Adds an output line to the known list.
protected int[]	checkChannel(String name, int hwChan, String type, String subtype) Checks a monitor channel's parameters for validity.
TreeWalkerDiag	checkHardware() Override to initiate interaction with the hardware.
protected void	checkHwLine(String name, int line) Checks the validity of an output line.
protected void	checkLine(String name, int line) Checks the validity of an output line.
void	checkOnline() Checks the online state.
void	checkStarted() Override to check that all hardware is correctly initiated.
void	checkStopped() Override with specific code to stop the hardware.
protected void	checkTimeout(Exception e, Class<?> eClass) Checks whether exception is a timeout.
protected abstract void	close() Closes the connection.
protected void	configure(Monitor mon) Performs common configuration.
void	disable() Disables the device.
protected void	dropChannel(int id) Drops a channel from the device's list of monitored channels.
void	enable() Enables the device.
String	getFullName() Gets the full name.
protected void	getOutputLines() Gets the states of all output lines and saves them.
void	init() Called from the enclosing Subsystem at construction phase.
protected void	initChannel(int hwChan, int type, int subtype) Initializes a monitor channel.
protected void	initChannel(String name, int id, int hwChan, int type, int subtype) Initializes a monitor channel.
protected void	initDevice() Performs internal device initialization.
protected abstract void	initialize() Performs hardware initialization.
protected void	initSensors() Initializes all attached sensors.
protected boolean	isHwLineSet(int line) Gets an output line set state.
protected boolean	isLineSet(int line) Gets an output line set state.
boolean	isOnline() Gets the online state.
protected boolean	isTimeout(Exception e) Tests whether exception is a timeout.
protected double	readChannel(int hwChan, int type) Reads a monitor channel.
protected void	readChannelGroup() Reads the monitor channel group.
protected double	readChannelNow(int hwChan, int type) Reads a monitor channel immediately.
protected void	readSensors() Reads all attached sensors (monitor channels).
protected void	setHwLine(int line, boolean on) Sets an output line on or off.
protected void	setLine(int line, boolean on) Sets an output line on or off.
protected void	setLineWarm(int line, boolean on) Sets the warm-start state of an output line.
protected void	setOnline(boolean online) Sets the online state.
protected void	setOutputLines() Sets all output lines from the saved state.
protected boolean	testOnline() Tests the online state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.lsst.ccs.framework.HasLifecycle

postInit, postShutdown, postStart, shutdownNow, start

Methods inherited from interface org.lsst.ccs.UsesSubsystem

getComponentConfigurationEnvironment, getComponentLookup, getName, getSubsystem

Field Detail

fullName

protected String fullName

Data fields.

chanMask

protected BitSet chanMask

disabled

protected boolean disabled

inited

protected boolean inited

online

protected boolean online

mon

@LookupField(strategy=TREE)
protected Monitor mon

log

protected Logger log

ctlChans

@LookupField(strategy=CHILDREN)
protected final Map<String,Control> ctlChans

lineMask

protected int lineMask

lineWarm

protected int lineWarm

lineState

protected int lineState

s

@LookupField(strategy=TOP)
protected Subsystem s

name

@LookupName
protected String name

Constructor Detail

Device

public Device()

Method Detail

init

public void init()

Description copied from interface: HasLifecycle

Called from the enclosing Subsystem at construction phase. This method is called before the children components of this object have their init method called. At the time it is called, connection to the messaging layer is not yet done, so there should be no attempt to send messages in the body of this method. Configuration for message listening can nevertheless be done here, such as adding MessageListener objects.

It is unnecessary to call super.init()

Specified by:

init in interface HasLifecycle

initDevice

protected void initDevice()

Performs internal device initialization. No hardware initialization should be performed at this point.

getFullName

public String getFullName()

Gets the full name.

Returns:

The full name of the device

isOnline

public boolean isOnline()

Gets the online state.

Returns:

Whether or not the device is online

disable

public void disable()

Disables the device.

enable

public void enable()

Enables the device.

configure

protected void configure(Monitor mon)

Performs common configuration. Can be overridden if necessary, but must be called by overriding code.

Parameters:

mon - The associated monitor

checkChannel

protected int[] checkChannel(String name,
                             int hwChan,
                             String type,
                             String subtype)
                      throws Exception

Checks a monitor channel's parameters for validity. This method is to be overridden for devices with monitor channels that have descriptive information to be checked and encoded.

Parameters:

name - The name of the channel.

hwChan - The hardware channel number.

type - The channel type string.

subtype - The channel subtype string.

Returns:

A two-element array containing the encoded type [0] and subtype [1].

Throws:

Exception - if any errors found in the parameters

initialize

protected abstract void initialize()

Performs hardware initialization.

close

protected abstract void close()

Closes the connection.

initSensors

protected void initSensors()

Initializes all attached sensors.

initChannel

protected void initChannel(int hwChan,
                           int type,
                           int subtype)

Initializes a monitor channel. This method is to be overridden for devices with monitor channels that need to be configured in the hardware.

Parameters:

hwChan - The hardware channel number.

type - The encoded channel type returned by checkChannel.

subtype - The channel subtype returned by checkChannel.

initChannel

protected void initChannel(String name,
                           int id,
                           int hwChan,
                           int type,
                           int subtype)

Initializes a monitor channel. This method is to be overridden for devices with monitor channels that need to be configured in the hardware.

Parameters:

name - The channel name

id - The channel ID

hwChan - The hardware channel number.

type - The encoded channel type returned by checkChannel.

subtype - The channel subtype returned by checkChannel.

addChannel

protected void addChannel(int id)

Adds a channel to the device's list of monitored channels.

Parameters:

id - The id of the channel.

dropChannel

protected void dropChannel(int id)

Drops a channel from the device's list of monitored channels. The monitor's list must be updated as well, and the channel itself made invalid.

Parameters:

id - The id of the channel.

checkOnline

public void checkOnline()

Checks the online state. If offline, an attempt is made to re-initialize the device.

testOnline

protected boolean testOnline()

Tests the online state. If offline, an error message is logged.

Returns:

Whether or not the device is online.

setOnline

protected void setOnline(boolean online)

Sets the online state. If the device is set offline, an error message is logged.

Parameters:

online - The online state to set: true or false

readSensors

protected void readSensors()

Reads all attached sensors (monitor channels).

readChannelGroup

protected void readChannelGroup()

Reads the monitor channel group. This method is to be overridden for devices that reads some (or all) of its monitor channels at one time.

readChannel

protected double readChannel(int hwChan,
                             int type)

Reads a monitor channel. This method is to be overridden for devices with monitor channels.

Parameters:

hwChan - The hardware channel number.

type - The encoded channel type returned by checkChannel.

Returns:

The value read from the channel

readChannelNow

protected double readChannelNow(int hwChan,
                                int type)

Reads a monitor channel immediately. This method is to be overridden for devices with monitor channels. It is used when the instantaneous value of the channel is needed rather than the one obtained during a previous readChannelGroup call.

Parameters:

hwChan - The hardware channel number.

type - The encoded channel type returned by checkChannel.

Returns:

The value read from the channel

checkTimeout

protected void checkTimeout(Exception e,
                            Class<?> eClass)
                     throws Exception

Checks whether exception is a timeout. If it is a timeout, the device is set offline. In all cases an exception of the supplied class is thrown, containing the message of the original exception.

Parameters:

e - The exception to be checked.

eClass - The class of the exception to be thrown.

Throws:

Exception

isTimeout

protected boolean isTimeout(Exception e)

Tests whether exception is a timeout.

Parameters:

e - The exception to be tested.

Returns:

Whether or not the exception is a timeout.

checkLine

protected void checkLine(String name,
                         int line)
                  throws Exception

Checks the validity of an output line.

Parameters:

name - The name of the output line.

line - The hardware line number of the output line.

Throws:

Exception - if the line number is invalid.

checkHwLine

protected void checkHwLine(String name,
                           int line)
                    throws Exception

Checks the validity of an output line. This method is to be overridden for devices with output lines.

Parameters:

name - The name of the output line.

line - The hardware line number of the output line.

Throws:

Exception - if the line number is invalid.

setLineWarm

protected void setLineWarm(int line,
                           boolean on)

Sets the warm-start state of an output line.

Parameters:

line - The output line number.

on - The warm-start on state to set: true or false

setLine

protected void setLine(int line,
                       boolean on)

Sets an output line on or off.

Parameters:

line - The output line number.

on - The on state to set: true or false

setHwLine

protected void setHwLine(int line,
                         boolean on)

Sets an output line on or off. This method is to be overridden for devices with output lines.

Parameters:

line - The output line number.

on - The on state to set: true or false

isLineSet

protected boolean isLineSet(int line)

Gets an output line set state.

Parameters:

line - The output line number.

Returns:

Whether or not the line is set.

isHwLineSet

protected boolean isHwLineSet(int line)

Gets an output line set state. This method is to be overridden for devices with output lines.

Parameters:

line - The output line number.

Returns:

Whether or not the line is set.

setOutputLines

protected void setOutputLines()

Sets all output lines from the saved state.

getOutputLines

protected void getOutputLines()

Gets the states of all output lines and saves them.

addLine

protected void addLine(int line)

Adds an output line to the known list.

Parameters:

line - The output line number.

checkHardware

public TreeWalkerDiag checkHardware()
                             throws HardwareException

Description copied from interface: HardwareController

Override to initiate interaction with the hardware. First interaction with low level hardware should take place in the body of this method. At the time it is called, the enclosing subsystem has connected to the messaging layer and is in PhaseState.INITIALIZING state.

If accessing the hardware is considered as having failed, this method should throw an HardwareException. This will interrupt the startup process and make the subsystem go to OperationalState.ENGINEERING_FAULT. The startup process will be resumed with a call to Subsystem.completeInitialization() that will invoke HardwareController.checkStarted()

If this method is considered having succeeded, the state remains to OperationalState.ENGINEERING_OK

Specified by:

checkHardware in interface HardwareController

Returns:

a TreeWalkerDiag indicating if this component has already performed hardware checking for its own components (HANDLING_CHILDREN) or if the framework should do it (GO)

Throws:

HardwareException - if any failure interacting with the hardware occurs. The exception is caught by the framework.

checkStarted

public void checkStarted()
                  throws HardwareException

Description copied from interface: HardwareController

Override to check that all hardware is correctly initiated. Note that this method is only invoked by the framework when the previous step failed. It is triggered by a call to Subsystem.completeInitialization()

If a failure in the way the hardware has been started is noticed, the implementation should throw an HardwareException. This will interrupt the startup process and make the subsystem remain in OperationalState.ENGINEERING_FAULT. The startup process will be resumed with a subsequent call to Subsystem.completeInitialization()

Specified by:

checkStarted in interface HardwareController

Throws:

HardwareException - if a failure is noticed in the way hardware is started.

checkStopped

public void checkStopped()
                  throws HardwareException

Description copied from interface: HardwareController

Override with specific code to stop the hardware. It is invoked upon calls to Agent.shutdown() or Subsystem.stop(long). At the time it is called, the enclosing subsystem is in PhaseState.CLOSING phase

If a failure in stopping hardware is noticed, the implementation should throw an HardwareException. This will interrupt the shutdown process

If no HardwareException is thrown, the shutdown process will resume.

Specified by:

checkStopped in interface HardwareController

Throws:

HardwareException - if a failure occurs while stopping the hardware.