org.lsst.ccs.monitor

Class Device

java.lang.Object

org.lsst.ccs.monitor.Device

All Implemented Interfaces:

HardwareController, HasLifecycle

Direct Known Subclasses:

CalcDevice

public abstract class Device
extends Object
implements HardwareController, HasLifecycle

Handles hardware devices

Author:

Owen Saxton

Field Summary

Fields

Modifier and Type	Field and Description
protected String	alertOfflineId
protected AlertService	alertService
protected ConfigurationService	configService
protected String	fullName
protected boolean	inited boolean inited: not used in parent Device code, but suggested to be set true in extensions of Device after a first initialize() is complete, successful or not.
protected int	lineMask
protected int	lineState
protected int	lineWarm
protected Logger	log
protected Monitor	mon
protected String	name
protected String	path
protected Subsystem	s

Constructor Summary

Constructors

Constructor and Description
Device()

Method Summary

Modifier and Type	Method and Description
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.
protected void	checkTimeout(Exception e, Class<?> eClass) Deprecated.
protected abstract void	close() Closes the connection (typically by invoking a driver close())
protected void	configure(Monitor mon) Deprecated.
void	disable() Deprecated.
protected void	dropChannel(int id) Drops a channel from the device's list of monitored channels.
void	enable() Deprecated.
List<MonitorUpdateTask>	getDeviceMonitorUpdateTasks() Get the list of MonitorUpdateTasks for this Device.
String	getFullName() Gets the full name.
protected String	getGroupForChannel(Channel ch) Get the group a given channel belongs to.
List<MonitorUpdateTask>	getMonitorUpdateTasksForChannels(Channel... channels) Get the list of MonitorUpdateTasks for the provided Channels belonging to this device.
String	getName() Get the name of this device as defined in the groovy file.
protected void	getOutputLines() Gets the states of all output lines and saves them.
String	getPath() Get the path of this device.
void	init() Called from the enclosing Subsystem at initialization 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-code initialization.
protected abstract void	initialize() Performs hardware initialization Guidance: If all hardware interactions (connection and initialization, via driver) succeed, then setOnline(true).
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) Deprecated.
protected double	readChannel(Channel ch)
protected double	readChannel(int hwChan, int type) Reads a monitor channel.
protected void	readChannelGroup() Reads the monitor channel group.
protected void	readChannelGroup(String group) Reads the monitor channel group.
protected double	readChannelNow(int hwChan, int type) Reads a monitor channel immediately.
void	setDisabled(Boolean value) Set device-disabled state
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.HardwareController

checkStopped

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

build, postBuild, postInit, postShutdown, postStart, shutdown, start

Field Detail

inited

protected boolean inited

boolean inited: not used in parent Device code, but suggested to be set true in extensions of Device after a first initialize() is complete, successful or not. It can then be tested, e.g., to block repeated log messages in bringing a device online, or in ConfigurationParameterChanger or BulkChangeHandler methods (to distiguish their invocattions at build() or init() phase from subsequent invocations), etc.

log

protected final Logger log

lineMask

protected int lineMask

lineWarm

protected int lineWarm

lineState

protected int lineState

mon

@LookupField(strategy=TREE)
protected Monitor mon

s

@LookupField(strategy=TOP)
protected Subsystem s

configService

@LookupField(strategy=TREE)
protected ConfigurationService configService

alertService

@LookupField(strategy=TREE)
protected AlertService alertService

name

@LookupName
protected String name

path

@LookupPath
protected String path

fullName

@LookupPath
protected String fullName

alertOfflineId

protected String alertOfflineId

Constructor Detail

Device

public Device()

Method Detail

init

public void init()

Description copied from interface: HasLifecycle

Called from the enclosing Subsystem at initialization 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-code initialization. No hardware initialization should be performed at this point.

getName

public String getName()

Get the name of this device as defined in the groovy file.

Returns:

The Device name;

getPath

public String getPath()

Get the path of this device.

Returns:

The Device path;

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

@Deprecated
public void disable()

Deprecated.

Disables the device (for backward compatibility)

enable

@Deprecated
public void enable()

Deprecated.

Enables the device (for backward compatibility)

configure

@Deprecated
protected void configure(Monitor mon)

Deprecated.

Performs common configuration. Can be overridden if necessary, but must be called by overriding code. Functionality now seems redundant with initDevice().

Parameters:

mon - The associated monitor

setDisabled

@ConfigurationParameterChanger(propertyName="disabled")
public void setDisabled(Boolean value)

Set device-disabled state

Parameters:

Boolean - value True for device disabled, false for enabled

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 Guidance: If all hardware interactions (connection and initialization, via driver) succeed, then setOnline(true). If not, invoke close() and (if relevant) restore Device to a situation which allows a later retry of initialize(). Note: the initialization attempt should include initSensors(), which, if Device code implements initChannel(), might also entail hardware communication.

close

protected abstract void close()

Closes the connection (typically by invoking a driver close())

initSensors

protected final 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.

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

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. Results should be saved and then returned (one at a time) by readChannel method. Reading should be conditioned on isOnline(). If a read failure (or several successive read failures) is considered significant, "setOnline(false)" should be issued.

readChannelGroup

protected void readChannelGroup(String group)

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. Similar to readChannelGroup(), used if there are several named groups to be read on separate threads.

Parameters:

String - group name

getGroupForChannel

protected String getGroupForChannel(Channel ch)

Get the group a given channel belongs to.

Parameters:

ch - The Channel object

Returns:

A String representing the group this channel belongs to. A null is returned if the Channel belongs to no group.

readChannel

protected double readChannel(int hwChan,
                             int type)

Reads a monitor channel. This method is to be overridden for devices with monitor channels. Suggested: start method with super.readChannel(int hwChan, int type) The read should be conditioned on isOnline(). If a read failure or repeated failure is considered significant, "setOnline(false)" should be issued.

Parameters:

hwChan - The hardware channel number.

type - The encoded channel type returned by checkChannel.

Returns:

The value read from the channel or NaN

readChannel

protected double readChannel(Channel ch)

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

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

Deprecated.

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

@Deprecated
protected boolean isTimeout(Exception e)

Deprecated.

Tests whether exception is a timeout.

Parameters:

e - The exception to be tested.

Returns:

Whether or not the exception is a timeout.

checkLine

protected final 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 final 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 final 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 and stays in PhaseState.INITIALIZING. The startup process will be resumed with a call to org.lsst.ccs.Subsystem#completeInitialization() that will invoke HardwareController#checkStarted()

If this method is considered having succeeded, the state goes to OperationalState.ENGINEERING_OK and PhaseState.OPERATIONAL

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.

getDeviceMonitorUpdateTasks

public List<MonitorUpdateTask> getDeviceMonitorUpdateTasks()

Get the list of MonitorUpdateTasks for this Device.

Returns:

getMonitorUpdateTasksForChannels

public List<MonitorUpdateTask> getMonitorUpdateTasksForChannels(Channel... channels)

Get the list of MonitorUpdateTasks for the provided Channels belonging to this device.

Parameters:

channels - The channels for that must be part of the returned tasks.

Returns: