org.lsst.ccs.drivers.lighthouse

Class LighthouseClient

java.lang.Object

org.lsst.ccs.drivers.lighthouse.LighthouseClient

public class LighthouseClient
extends Object

Exports high-level operations on a Lighthouse particle counter. Only operations and data are visible, not registers or communication protocols. Implements a command set common to the 2016, 3016 and 5016 family of hand-held and wall-mounted units.

Only a single thread should manipulate an instance of this class. Only a single stream of data records should be in use at any time since advancing to the next record involves updating the record index register on the instrument before reading the record data registers. This lazy retrieval allows you to skip needless I/O if you decide you don't want all the stored records.

Author:

tether

Constructor Summary

Constructors

Constructor and Description
LighthouseClient(Hardware hw) Stores a reference to a Hardware object used to communicate with the instrument and reads the device model and the register map version.

Method Summary

Modifier and Type	Method and Description
boolean	alarmIsEnabled(DataChannel chan) Gets the alarm enable status for a particle channel.
void	clearAllRecords() Delete all records currently stored in the instrument.
void	close() Closes the underlying connection to the device.
static LighthouseClient	ftdiOpen(String ident, Duration timeout, boolean debug) Opens the device on a raw FTDI serial port.
long	getAlarmThreshold(DataChannel chan) Gets the current alarm threshold for a particle channel.
Instant	getClock() Gets the device's time-of-day clock.
String	getLocationName() Gets the label for the current location set for the instrument.
String	getModel() Gets the model of Lighthouse counter hardware (read by constructor).
List<DataRecord>	getRecentRecords(Instant threshold) Gets the data records more recent than a given time.
List<DataRecord>	getRecordsByIndex(int start, int limit) Gets the data records specified by start and limit.
int	getRegisterMapVersion() Gets the version of the Modbus register map used by the hardware (read by constructor).
static LighthouseClient	netOpen(String hostname, int portNo, Duration timeout, boolean debug) Opens a device owned by a TCP server.
static LighthouseClient	serialOpen(String portName, Duration timeout, boolean debug) Opens the device on a generic serial port.
void	setAlarmEnable(DataChannel chan, boolean on) Enables or disables the alarm for a particle channel.
void	setAlarmThreshold(DataChannel chan, long threshold) Sets the particle count alarm threshold for a particle channel but doesn't change the alarm enable status.
void	setClock(Duration tolerance) Sets the device's time-of-day clock to the current system time.
void	setLocationIndex(int index) Sets the register that contains the index number of the instrument's location.
void	startRecording() Starts automatic data collection.
void	stopRecording() Stops data collection.

Methods inherited from class java.lang.Object

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

Constructor Detail

LighthouseClient

public LighthouseClient(Hardware hw)
                 throws org.lsst.ccs.drivers.commons.DriverException

Stores a reference to a Hardware object used to communicate with the instrument and reads the device model and the register map version.

Parameters:

hw - The communications object.

Throws:

org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.

Method Detail

serialOpen

public static LighthouseClient serialOpen(String portName,
                                          Duration timeout,
                                          boolean debug)
                                   throws org.lsst.ccs.drivers.commons.DriverException

Opens the device on a generic serial port. Creates suitable implementations of the interfaces Transport and Hardware.

Parameters:

portName - The serial port name, for example /dev/ttyUSB0.

timeout - How long to wait for a response after sending a command.

debug - If true enables debug-level logging of device command traffic.

Returns:

The new Lighthouse client object.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for all errors.

ftdiOpen

public static LighthouseClient ftdiOpen(String ident,
                                        Duration timeout,
                                        boolean debug)
                                 throws org.lsst.ccs.drivers.commons.DriverException

Opens the device on a raw FTDI serial port. Creates suitable implementations of the interfaces Transport and Hardware. It's possible to connect to a device on another host if that host is running an FTDI server.

Parameters:

ident - The FTDI chip's serial number, possibly preceded by a host name/IP and a colon.

timeout - How long to wait for a response after sending a command.

debug - If true enables debug-level logging of device command traffic.

Returns:

The new Lighthouse client object.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for all errors.

netOpen

public static LighthouseClient netOpen(String hostname,
                                       int portNo,
                                       Duration timeout,
                                       boolean debug)
                                throws org.lsst.ccs.drivers.commons.DriverException

Opens a device owned by a TCP server. Creates suitable implementations of the interfaces Transport and Hardware.

Parameters:

hostname - The server's hostname or IP address.

portNo - The server's port number.

timeout - How long to wait for a response after sending a command.

debug - If true enables debug-level logging of device command traffic.

Returns:

The new Lighthouse client object.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for all errors.

close

public void close()
           throws org.lsst.ccs.drivers.commons.DriverException

Closes the underlying connection to the device.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for I/O errors.

getModel

public String getModel()

Gets the model of Lighthouse counter hardware (read by constructor).

Returns:

The model designation string.

getRegisterMapVersion

public int getRegisterMapVersion()

Gets the version of the Modbus register map used by the hardware (read by constructor).

Returns:

An integer with decimal digits xxyy, where xx is the major version and yy the minor version.

stopRecording

public void stopRecording()
                   throws org.lsst.ccs.drivers.commons.DriverException

Stops data collection. Aborts any new record being created. Has no effect if data collection has already been stopped.

Throws:

org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.

startRecording

public void startRecording()
                    throws org.lsst.ccs.drivers.commons.DriverException

Starts automatic data collection. Has no effect if data collection is already started.

Throws:

org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.

getRecordsByIndex

public List<DataRecord> getRecordsByIndex(int start,
                                          int limit)
                                   throws org.lsst.ccs.drivers.commons.DriverException

Gets the data records specified by start and limit.

Parameters:

start - Specifies the index of the earliest record to fetch. A non-negative value means index 0 + start while a negative value means index N + start, where N is the total number of records available.

limit - The number of records to fetch, with zero meaning all after the starting point.

Returns:

The unmodifiable record list in ASCENDING order by record index (and timestamp).

Throws:

org.lsst.ccs.drivers.commons.DriverException - if communication problems arise or if data collection hasn't been stopped.

getRecentRecords

public List<DataRecord> getRecentRecords(Instant threshold)
                                  throws org.lsst.ccs.drivers.commons.DriverException

Gets the data records more recent than a given time.

Parameters:

threshold - All records returned will be more recent than this.

Returns:

The unmodifiable record list, most recent record first.

Throws:

org.lsst.ccs.drivers.commons.DriverException - if communication problems arise or if data collection hasn't been stopped.

clearAllRecords

public void clearAllRecords()
                     throws org.lsst.ccs.drivers.commons.DriverException

Delete all records currently stored in the instrument.

Throws:

org.lsst.ccs.drivers.commons.DriverException - if communication problems arise or if data collection hasn't been stopped.

setAlarmThreshold

public void setAlarmThreshold(DataChannel chan,
                              long threshold)
                       throws org.lsst.ccs.drivers.commons.DriverException

Sets the particle count alarm threshold for a particle channel but doesn't change the alarm enable status.

Parameters:

chan - The channel to be affected.

threshold - The limiting particle count.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for I/O errors.

IllegalArgumentException - if the channel is analog or if the threshold is not in the interval [0, 2^32-1].

getAlarmThreshold

public long getAlarmThreshold(DataChannel chan)
                       throws org.lsst.ccs.drivers.commons.DriverException

Gets the current alarm threshold for a particle channel.

Parameters:

chan - The channel to query.

Returns:

The current alarm threshold.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for I/O errors.

IllegalArgumentException - if the channel is analog.

setAlarmEnable

public void setAlarmEnable(DataChannel chan,
                           boolean on)
                    throws org.lsst.ccs.drivers.commons.DriverException

Enables or disables the alarm for a particle channel.

Parameters:

chan - The channel to affect.

on - true to enable alarms, false to disable.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for I/O errors.

IllegalArgumentException - if the channel is analog.

alarmIsEnabled

public boolean alarmIsEnabled(DataChannel chan)
                       throws org.lsst.ccs.drivers.commons.DriverException

Gets the alarm enable status for a particle channel.

Parameters:

chan - The channel to query.

Returns:

true if enabled, false if disabled.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for I/O errors.

IllegalArgumentException - if the channel is analog.

setClock

public void setClock(Duration tolerance)
              throws org.lsst.ccs.drivers.commons.DriverException

Sets the device's time-of-day clock to the current system time.

Parameters:

tolerance - When read back the device clock must be no further than this from the current system time just after the read.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for I/O errors or if the clock value read back is bad.

getClock

public Instant getClock()
                 throws org.lsst.ccs.drivers.commons.DriverException

Gets the device's time-of-day clock.

Returns:

The clock reading.

Throws:

org.lsst.ccs.drivers.commons.DriverException - for I/O errors.

setLocationIndex

public void setLocationIndex(int index)
                      throws org.lsst.ccs.drivers.commons.DriverException

Sets the register that contains the index number of the instrument's location.

Parameters:

index - The index (1 = lowest index).

Throws:

org.lsst.ccs.drivers.commons.DriverException - if the operation failed.

IllegalArgumentException - if the index is invalid.

getLocationName

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

Gets the label for the current location set for the instrument.

Returns:

The location label string.

Throws:

org.lsst.ccs.drivers.commons.DriverException - if the operation fails.