org.lsst.ccs.drivers.ads

Class ADSDriver

java.lang.Object

org.lsst.ccs.drivers.ads.ADSDriver

public class ADSDriver
extends Object

Uses the ADS wrapper classes to provide a more limited but easier to use interface to a remote PLC server via ADS. Designed with the Beckhoff shutter controller in mind.

The exceptions defined in this class all inherit from the standard CCS exception DriverException and so bear messages with more details about errors.

Author:

tether

See Also:

This Confluence page.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ADSDriver.BadVarHandleException Thrown when the driver is given a VariableHandle that's been released or which has been rejected as invalid by the remote ADS server.
static class	ADSDriver.InitializationException Thrown when the Beckhoff ADS library can't be initialized properly.
static class	ADSDriver.LookupException Thrown when a variable name isn't in the remote PLC symbol table.
static class	ADSDriver.LostContactException Thrown when the driver tries to do something and discovers that it has lost contact with the remote ADS server.
static class	ADSDriver.NotificationException Thrown when an attempt to establish notification fails.
static class	ADSDriver.NotOpenException Thrown during an attempt to use the driver when it isn't open.
static class	ADSDriver.OpenException Thrown when an attempt to open the driver fails.
static class	ADSDriver.ReadWriteException Thrown when a problem arises while trying to read from or write to a PLC variable.

Constructor Summary

Constructors

Constructor and Description
ADSDriver(String localAMSNetId) Sets the local AMS address and obtains an ADS port.

Method Summary

Modifier and Type	Method and Description
void	cancelNotifications(VariableHandle varHandle) Cancels notifications for a given PLC variable.
void	close() Closes any existing connection, releasing all VariableHandles and canceling all notifications in effect.
BlockingQueue<Notification>	getNotificationQueue() Gets the queue used for all notification messages.
VariableHandle	getVariableHandle(String varName) Creates a description of a PLC variable in the MAIN POU.
void	open(String remoteAMSNetId, String remoteIPv4) Establishes a connection to the PLC task of the remote ADS server.
ByteBuffer	readVariable(VariableHandle varHandle) Reads the value of a given PLC variable.
void	releaseVariableHandle(VariableHandle varHandle) Takes a valid VariableHandle instance and makes it invalid.
int	requestNotifications(VariableHandle varHandle, Duration maxDelay, Duration checkInterval, boolean onlyIfChanged) Sets up notifications for the value of a PLC variable.
void	writeVariable(VariableHandle varHandle, ByteBuffer wbuf) Writes the value of a given PLC value.

Methods inherited from class java.lang.Object

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

Constructor Detail

ADSDriver

public ADSDriver(String localAMSNetId)
          throws org.lsst.ccs.drivers.commons.DriverException

Sets the local AMS address and obtains an ADS port.

Parameters:

localAMSNetId - The local AMS address as a dotted string, for example "1.2.3.4.1.1".

Throws:

ADSDriver.InitializationException - if an ADS port can't be obtained.

org.lsst.ccs.drivers.commons.DriverException - if the AMS Net Id is ill-formed.

Method Detail

open

public void open(String remoteAMSNetId,
                 String remoteIPv4)
          throws org.lsst.ccs.drivers.commons.DriverException

Establishes a connection to the PLC task of the remote ADS server. Closes any existing connection.

Parameters:

remoteAMSNetId - The remote AMS address as a dotted string, for example "5.6.7.8.1.1".

remoteIPv4 - A string containing the host name or the dotted IPv4 address of the remote server.

Throws:

ADSDriver.OpenException - if the remote server can't be reached.

org.lsst.ccs.drivers.commons.DriverException - if the AMS netId is ill-formed.

close

public void close()

Closes any existing connection, releasing all VariableHandles and canceling all notifications in effect.

getVariableHandle

public VariableHandle getVariableHandle(String varName)
                                 throws org.lsst.ccs.drivers.commons.DriverException

Creates a description of a PLC variable in the MAIN POU.

Parameters:

varName - The name of the variable, for example "foo", "foo[5]", "foo.bar", etc.

Returns:

An instance of VariableHandle.

Throws:

ADSDriver.NotOpenException - if the driver hasn't been opened.

ADSDriver.LostContactException - if the remote server can't be reached any more.

ADSDriver.LookupException - if the variable's name can't be found in the PLC symbol table.

org.lsst.ccs.drivers.commons.DriverException - for any other error.

See Also:

releaseVariableHandle(org.lsst.ccs.drivers.ads.VariableHandle)

releaseVariableHandle

public void releaseVariableHandle(VariableHandle varHandle)
                           throws org.lsst.ccs.drivers.commons.DriverException

Takes a valid VariableHandle instance and makes it invalid.

Parameters:

varHandle - The VariableHandle to make invalid.

Throws:

ADSDriver.NotOpenException - if the driver isn't open.

ADSDriver.LostContactException - if the driver can no longer get through to the remote server.

ADSDriver.BadVarHandleException - if the handle has already been released or if the remote server rejects the attempt to release.

org.lsst.ccs.drivers.commons.DriverException - for any other error.

See Also:

getVariableHandle(java.lang.String)

requestNotifications

public int requestNotifications(VariableHandle varHandle,
                                Duration maxDelay,
                                Duration checkInterval,
                                boolean onlyIfChanged)
                         throws org.lsst.ccs.drivers.commons.DriverException

Sets up notifications for the value of a PLC variable. Notifications are represented as instances of Notification placed in the notification queue.

Parameters:

varHandle - A valid VariableHandle.

maxDelay - How long the notification messages are allowed to remain queued in the remote server before they are sent.

checkInterval - How often the remote server should decide whether or not to send a new message.

onlyIfChanged - If this is true then the remote server will suppress a new message if the value of the variable hasn't changed since the sending of the previous message. Otherwise it will send the message every time the check interval elapses.

Returns:

The 32-bit handle assigned to the notification by the remote server.

Throws:

ADSDriver.NotOpenException - if the driver isn't open.

ADSDriver.LostContactException - if the driver can no longer get through to the remote server.

ADSDriver.BadVarHandleException - if the handle has already been released or was rejected by the remote server.

ADSDriver.NotificationException - if the request fails for some other reason.

org.lsst.ccs.drivers.commons.DriverException - for any other error.

See Also:

Notification, getNotificationQueue(), getVariableHandle(java.lang.String)

cancelNotifications

public void cancelNotifications(VariableHandle varHandle)
                         throws org.lsst.ccs.drivers.commons.DriverException

Cancels notifications for a given PLC variable.

Parameters:

varHandle - A valid instance of VariableHandle.

Throws:

ADSDriver.NotOpenException - if the driver isn't open.

ADSDriver.BadVarHandleException - if the variable handle isn't valid.

ADSDriver.LostContactException - if communications with the server have been lost.

ADSDriver.NotificationException - if the canceling failed on the remote server.

org.lsst.ccs.drivers.commons.DriverException - for any other error.

See Also:

requestNotifications(org.lsst.ccs.drivers.ads.VariableHandle, java.time.Duration, java.time.Duration, boolean)

readVariable

public ByteBuffer readVariable(VariableHandle varHandle)
                        throws org.lsst.ccs.drivers.commons.DriverException

Reads the value of a given PLC variable.

Parameters:

varHandle - A valid VariableHandle instance.

Returns:

A read-write byte buffer with the correct byte order, with position = 0 and limit and capacity both equal to the variable size.

Throws:

ADSDriver.NotOpenException - if the driver isn't open.

ADSDriver.BadVarHandleException - if the variable handle isn't valid.

ADSDriver.LostContactException - if communications with the server have been lost.

ADSDriver.ReadWriteException - if the reading failed on the remote server.

org.lsst.ccs.drivers.commons.DriverException - for any other error.

writeVariable

public void writeVariable(VariableHandle varHandle,
                          ByteBuffer wbuf)
                   throws org.lsst.ccs.drivers.commons.DriverException

Writes the value of a given PLC value.

Parameters:

varHandle - A valid instance of VariableHandle.

wbuf - A byte buffer whose capacity is exactly the same as the variable size. All the bytes will be written. I recommend that you obtain a buffer of the right size and byte order using VariableHandle.createBuffer() or readVariable(org.lsst.ccs.drivers.ads.VariableHandle).

Throws:

ADSDriver.NotOpenException - if the driver isn't open.

ADSDriver.BadVarHandleException - if the variable handle isn't valid.

ADSDriver.LostContactException - if communications with the server have been lost.

ADSDriver.ReadWriteException - If the writing failed on the remote server.

org.lsst.ccs.drivers.commons.DriverException - for any other error.

getNotificationQueue

public BlockingQueue<Notification> getNotificationQueue()

Gets the queue used for all notification messages.

Returns:

A reference to the blocking queue.