ASCIIModbus (LSST CCS - LighthouseDriver 1.0.4 API)

java.lang.Object
- org.lsst.ccs.drivers.lighthouse.ASCIIModbus

All Implemented Interfaces:

Hardware
```
public class ASCIIModbus
extends Object
implements Hardware
```
Very simple ASCII Modbus communications, just good enough for the Lighthouse particle counter.
Built atop the CCS ASCII device driver.
The internal form of a Modbus command or response used by this class is an array of int where each int contains a byte value 0-255. The last byte is reserved for the Linear Redundancy Check to be calculated prior to encoding as a frame. Big-endian byte order is used for multi-byte quantities such as register addresses. The non-LRC bytes for a register reading command are:
- Modbus slave number (1 to 247)
- Function code (0 to 127)
- Register address (high)
- Register address (low)
- Number of registers (high)
- Number of registers (low)
The register writing command format is similar except that the number of registers to read is replaced by the value to write to the register. Note that all Modbus registers are 16 bits wide.
The internal form of a normal response to a read-registers command echos the slave number and function code of the command, then follows with:
- Count N of data bytes to follow. Yes, BYTES not registers, and only one byte for the count itself.
- Data byte 0 (first register high)
- Data byte 1 (first register low)
- ...
- Data byte N - 2 (last register high)
- Data byte N - 1 (last register low).
I don't know what would happen if you tried to read more than 128 registers using a single command. You might get an exception or multiple responses.
The normal response to a write-register command is to echo the command without change.
An exception (abnormal) response looks like this:
- Slave number
- Original function code + 128
- Error code.
The transmitted (framed) representation of the internal binary command or response conforms to the older 7-bit ASCII variant of the Modbus protocol. The frame starts with a colon, is followed by two hex characters for each data byte and ends with CRLF. "Data byte" includes the LRC byte which is calculated before framing and set as the last data byte. The LRC is simply the lowest-order eight bits of the twos-complement of the sum of the non-LRC data bytes (before framing).
The Lighthouse counter implements just two classes of Modbus registers: holding (16-bit read/write) and input (16-bit read-only). The register addresses used in commands are not those that appear in the documentation. There, input register addresses start at 30001 and holding register addresses start at 40001. Each command deals with only a single class of register and so the address in the command is the documented address minus the starting address of the class.
This software treats all Modbus registers as 16-bit unsigned values. In order to use streams and avoid problems with sign extension, ints are used for eight-bit and 16-bit quantities while longs are used for 32-bit quantities. A register value is represented as first the high-order byte, then the low. A 32-bit unsigned int is represented using a pair of consecutive registers with the high 16 bits in the lower-addressed register. An IEEE single-precision floating-point value also uses two consecutive registers but in this case the high portion containing the exponent is in the second register. A string is represented as a series of eight-bit bytes occupying a series of consecutive registers, read from lowest to highest address. The first character in each register is in the high-order byte. The number of registers depends on the maximum length of the string. Strings shorter than the maximum are padded on the right with NULs, but no NUL appears for a string that uses all the bytes in the assigned registers.
Author:

tether

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`ALARM_FLAGS_OFFSET` The offset from `RECORD_ADDRESS` of the first input register containing channel alarm flags.
`static int`	`ANALOG_CHANNEL_OFFSET` The offset from `RECORD_ADDRESS` of the first input register with analog channel data.
`static int`	`DEVICE_STATUS_OFFSET` offset from `RECORD_ADDRESS` of the device-status-high register.
`static int`	`LOCATION_NUMBER_OFFSET` The offset from `RECORD_ADDRESS` of the location-number-high register.
`static int`	`PARTICLE_CHANNEL_OFFSET` The offset from `RECORD_ADDRESS` of the first input register with particle channel data.
`static int`	`RECORD_ADDRESS` The address (less 3001) of the first input register in the record header.
`static int`	`RECORD_HEADER_SIZE` The number of registers in the record header.
`static int`	`SAMPLE_TIME_OFFSET` The offset from `RECORD_ADDRESS` of the sample-time-high register.
`static int`	`TIMESTAMP_OFFSET` The offset from `RECORD_ADDRESS` of the timestamp-high register.

Constructor Summary

Constructors
Constructor and Description
`ASCIIModbus(Transport transport, java.time.Duration timeout, boolean debug)` Saves a reference to the transport used for the device and saves the given parameters.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`alarmIsEnabled(DataChannel chan)` Gets the alarm enable status for a particle channel.
`boolean`	`channelIsEnabled(DataChannel chan)` Checks whether the given data channel is enabled.
`void`	`close()` Closes the underlying connection to the device.
`long`	`getAlarmThreshold(DataChannel chan)` Gets the current alarm threshold for a particle channel.
`long`	`getClock()` Gets the device's time-of-day clock.
`String`	`getDeviceLocationName()` Gets the label for the current location set for the device.
`ChannelType`	`readChannelType(DataChannel chan)` Reads the data type registers for a data channel of the current record.
`ChannelUnits`	`readChannelUnits(DataChannel chan)` Reads the units registers for a data channel of the current record.
`double`	`readChannelValue(DataChannel chan)` Reads the value registers for a data channel of the current record.
`Set<DeviceFlag>`	`readDeviceFlags()` Reads the device status register.
`int`	`readDeviceMapVersion()` Reads the Modbus map version register.
`String`	`readDeviceModel()` Reads the model designation registers.
`String`	`readLocationString(int location)` Reads the location string corresponding to a location number.
`DataRecord`	`readRecord()` Reads the current data record from the device faster than one could by combining the other methods exported by this interface.
`int`	`readRecordCount()` Reads the record count register.
`java.time.Duration`	`readRecordDuration()` Reads the record sample time register.
`Set<RecordFlag>`	`readRecordFlags()` Reads the device status registers of the current record.
`String`	`readRecordLocation()` Reads the registers for location number and location name.
`java.time.Instant`	`readRecordStartTime()` Reads the record timestamp register.
`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(long epochSecond)` Sets the device's time-of-day clock.
`void`	`setDeviceLocationIndex(int index)` Sets the current-location register for the device.
`void`	`writeDeviceCommand(DeviceCommand cmd)` Writes to the device command register.
`void`	`writeRecordIndex(int index)` Writes to the record index register, making the data registers show the contents of a particular record in its memory.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - RECORD_ADDRESS
```
public static final int RECORD_ADDRESS
```
    The address (less 3001) of the first input register in the record header.
    
    See Also:
    
    Constant Field Values
  - TIMESTAMP_OFFSET
```
public static final int TIMESTAMP_OFFSET
```
    The offset from RECORD_ADDRESS of the timestamp-high register.
    
    See Also:
    
    Constant Field Values
  - SAMPLE_TIME_OFFSET
```
public static final int SAMPLE_TIME_OFFSET
```
    The offset from RECORD_ADDRESS of the sample-time-high register.
    
    See Also:
    
    Constant Field Values
  - LOCATION_NUMBER_OFFSET
```
public static final int LOCATION_NUMBER_OFFSET
```
    The offset from RECORD_ADDRESS of the location-number-high register.
    
    See Also:
    
    Constant Field Values
  - DEVICE_STATUS_OFFSET
```
public static final int DEVICE_STATUS_OFFSET
```
    offset from RECORD_ADDRESS of the device-status-high register.
    
    See Also:
    
    Constant Field Values
  - PARTICLE_CHANNEL_OFFSET
```
public static final int PARTICLE_CHANNEL_OFFSET
```
    The offset from RECORD_ADDRESS of the first input register with particle channel data.
    
    See Also:
    
    Constant Field Values
  - ANALOG_CHANNEL_OFFSET
```
public static final int ANALOG_CHANNEL_OFFSET
```
    The offset from RECORD_ADDRESS of the first input register with analog channel data.
    
    See Also:
    
    Constant Field Values
  - ALARM_FLAGS_OFFSET
```
public static final int ALARM_FLAGS_OFFSET
```
    The offset from RECORD_ADDRESS of the first input register containing channel alarm flags.
    
    See Also:
    
    Constant Field Values
  - RECORD_HEADER_SIZE
```
public static final int RECORD_HEADER_SIZE
```
    The number of registers in the record header. Particle channels abut the record header.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - ASCIIModbus
```
public ASCIIModbus(Transport transport,
                   java.time.Duration timeout,
                   boolean debug)
```
    Saves a reference to the transport used for the device and saves the given parameters.
    
    Parameters:
    
    transport - The open transport link.
    
    timeout - How long to wait for a response to a command.
    
    debug - Only if true, all frames sent and received will be logged with <package logger>.debug().
- Method Detail
  - close
```
public void close()
           throws org.lsst.ccs.drivers.commons.DriverException
```
    Closes the underlying connection to the device.
    
    Specified by:
    
    close in interface Hardware
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - readDeviceModel
```
public String readDeviceModel()
                       throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the model designation registers.
    
    Specified by:
    
    readDeviceModel in interface Hardware
    
    Returns:
    
    The register values made into a String.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readDeviceMapVersion
```
public int readDeviceMapVersion()
                         throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the Modbus map version register.
    
    Specified by:
    
    readDeviceMapVersion in interface Hardware
    
    Returns:
    
    The version number times 100. v1.44 would be represented as 144.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readDeviceFlags
```
public Set<DeviceFlag> readDeviceFlags()
                                throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the device status register.
    
    Specified by:
    
    readDeviceFlags in interface Hardware
    
    Returns:
    
    A set with one element per bit set in the register.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - writeDeviceCommand
```
public void writeDeviceCommand(DeviceCommand cmd)
                        throws org.lsst.ccs.drivers.commons.DriverException
```
    Writes to the device command register.
    
    Specified by:
    
    writeDeviceCommand in interface Hardware
    
    Parameters:
    
    cmd - A valid device command.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readRecordCount
```
public int readRecordCount()
                    throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the record count register.
    
    Specified by:
    
    readRecordCount in interface Hardware
    
    Returns:
    
    The number of records currently held in the device's memory.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - writeRecordIndex
```
public void writeRecordIndex(int index)
                      throws org.lsst.ccs.drivers.commons.DriverException
```
    Writes to the record index register, making the data registers show the contents of a particular record in its memory.
    
    Specified by:
    
    writeRecordIndex in interface Hardware
    
    Parameters:
    
    index - The zero-based record index. 0 .. N - 1, or -1 for the latest record.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readRecordStartTime
```
public java.time.Instant readRecordStartTime()
                                      throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the record timestamp register.
    
    Specified by:
    
    readRecordStartTime in interface Hardware
    
    Returns:
    
    The time at which data collection started for the current record.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readRecordDuration
```
public java.time.Duration readRecordDuration()
                                      throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the record sample time register.
    
    Specified by:
    
    readRecordDuration in interface Hardware
    
    Returns:
    
    How long data collection took for the current record.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readRecordLocation
```
public String readRecordLocation()
                          throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the registers for location number and location name.
    
    Specified by:
    
    readRecordLocation in interface Hardware
    
    Returns:
    
    The name of the device location for the current record.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readLocationString
```
public String readLocationString(int location)
                          throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the location string corresponding to a location number.
    
    Parameters:
    
    location - The location number, >= 1.
    
    Returns:
    
    The location string.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - readRecordFlags
```
public Set<RecordFlag> readRecordFlags()
                                throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the device status registers of the current record.
    
    Specified by:
    
    readRecordFlags in interface Hardware
    
    Returns:
    
    The set of RecordFlag corresponding to the status mask. See RecordFlag.flagsFromMask(int).
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise.
  - readChannelType
```
public ChannelType readChannelType(DataChannel chan)
                            throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the data type registers for a data channel of the current record.
    
    Specified by:
    
    readChannelType in interface Hardware
    
    Parameters:
    
    chan - The channel.
    
    Returns:
    
    The channel type.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise or if the channel type label read from the device isn't what's specified by chan.
  - readChannelUnits
```
public ChannelUnits readChannelUnits(DataChannel chan)
                              throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the units registers for a data channel of the current record.
    
    Specified by:
    
    readChannelUnits in interface Hardware
    
    Parameters:
    
    chan - The channel.
    
    Returns:
    
    The units.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise or if the units label read from the device isn't what's specified by chan.
  - readChannelValue
```
public double readChannelValue(DataChannel chan)
                        throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the value registers for a data channel of the current record. Assumes that the registers hold a single-precision IEEE float for an analog channel or an int for others.
    
    Specified by:
    
    readChannelValue in interface Hardware
    
    Parameters:
    
    chan - The channel.
    
    Returns:
    
    The value, converted to double.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - if communication problems arise or if the channel isn't enabled on the device.
  - channelIsEnabled
```
public boolean channelIsEnabled(DataChannel chan)
                         throws org.lsst.ccs.drivers.commons.DriverException
```
    Checks whether the given data channel is enabled.
    
    Specified by:
    
    channelIsEnabled in interface Hardware
    
    Parameters:
    
    chan - The channel to check.
    
    Returns:
    
    True if the channel is enabled on the device, else false.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - upon I/O error.
  - readRecord
```
public DataRecord readRecord()
                      throws org.lsst.ccs.drivers.commons.DriverException
```
    Reads the current data record from the device faster than one could by combining the other methods exported by this interface.
    
    Specified by:
    
    readRecord in interface Hardware
    
    Returns:
    
    The data record.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - 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.
    
    Specified by:
    
    setAlarmThreshold in interface Hardware
    
    Parameters:
    
    chan - The channel to be affected.
    
    threshold - The limiting particle count.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - getAlarmThreshold
```
public long getAlarmThreshold(DataChannel chan)
                       throws org.lsst.ccs.drivers.commons.DriverException
```
    Gets the current alarm threshold for a particle channel.
    
    Specified by:
    
    getAlarmThreshold in interface Hardware
    
    Parameters:
    
    chan - The channel to query.
    
    Returns:
    
    The current alarm threshold.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - setAlarmEnable
```
public void setAlarmEnable(DataChannel chan,
                           boolean on)
                    throws org.lsst.ccs.drivers.commons.DriverException
```
    Enables or disables the alarm for a particle channel.
    
    Specified by:
    
    setAlarmEnable in interface Hardware
    
    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.
  - alarmIsEnabled
```
public boolean alarmIsEnabled(DataChannel chan)
                       throws org.lsst.ccs.drivers.commons.DriverException
```
    Gets the alarm enable status for a particle channel.
    
    Specified by:
    
    alarmIsEnabled in interface Hardware
    
    Parameters:
    
    chan - The channel to query.
    
    Returns:
    
    true if enabled, false if disabled.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - setClock
```
public void setClock(long epochSecond)
              throws org.lsst.ccs.drivers.commons.DriverException
```
    Sets the device's time-of-day clock.
    
    Specified by:
    
    setClock in interface Hardware
    
    Parameters:
    
    epochSecond - Elapsed seconds since the Unix epoch.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - getClock
```
public long getClock()
              throws org.lsst.ccs.drivers.commons.DriverException
```
    Gets the device's time-of-day clock.
    
    Specified by:
    
    getClock in interface Hardware
    
    Returns:
    
    The clock reading in seconds since the Unix epoch.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - setDeviceLocationIndex
```
public void setDeviceLocationIndex(int index)
                            throws org.lsst.ccs.drivers.commons.DriverException
```
    Sets the current-location register for the device.
    
    Specified by:
    
    setDeviceLocationIndex in interface Hardware
    
    Parameters:
    
    index - The index (lowest = 1).
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.
  - getDeviceLocationName
```
public String getDeviceLocationName()
                             throws org.lsst.ccs.drivers.commons.DriverException
```
    Gets the label for the current location set for the device.
    
    Specified by:
    
    getDeviceLocationName in interface Hardware
    
    Returns:
    
    The current location label.
    
    Throws:
    
    org.lsst.ccs.drivers.commons.DriverException - for I/O errors.

Class ASCIIModbus

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

RECORD_ADDRESS

TIMESTAMP_OFFSET

SAMPLE_TIME_OFFSET

LOCATION_NUMBER_OFFSET

DEVICE_STATUS_OFFSET

PARTICLE_CHANNEL_OFFSET

ANALOG_CHANNEL_OFFSET

ALARM_FLAGS_OFFSET

RECORD_HEADER_SIZE

Constructor Detail

ASCIIModbus

Method Detail

close

readDeviceModel

readDeviceMapVersion

readDeviceFlags

writeDeviceCommand

readRecordCount

writeRecordIndex

readRecordStartTime

readRecordDuration

readRecordLocation

readLocationString

readRecordFlags

readChannelType

readChannelUnits

readChannelValue

channelIsEnabled

readRecord

setAlarmThreshold

getAlarmThreshold

setAlarmEnable

alarmIsEnabled

setClock

getClock

setDeviceLocationIndex

getDeviceLocationName