org.lsst.ccs.drivers.lighthouse

Class ASCIIModbus

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 Serial 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 by encodeFrame(). 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

Constructor Summary

Constructors

Constructor and Description
ASCIIModbus(org.lsst.ccs.drivers.serial.SerialPort port, java.time.Duration timeout, boolean debug) Saves a reference to the open serial port used for the device and saves the given parameters.

Method Summary

Modifier and Type	Method and Description
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.
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	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

Constructor Detail

ASCIIModbus

public ASCIIModbus(org.lsst.ccs.drivers.serial.SerialPort port,
                   java.time.Duration timeout,
                   boolean debug)

Saves a reference to the open serial port used for the device and saves the given parameters.

Parameters:

port - The open SerialPort.

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

debug - Only if true, all frames sent and received will be printed on stdout.

Method Detail

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.

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.