org.mbari.siam.devices.slisus
Class SatlanticISUS

java.lang.Object
  java.rmi.server.RemoteObject
      java.rmi.server.RemoteServer
          java.rmi.server.UnicastRemoteObject
              org.mbari.siam.core.DeviceService
                  org.mbari.siam.core.InstrumentService
                      org.mbari.siam.devices.slisus.SatlanticISUS

All Implemented Interfaces:

java.io.Serializable, java.rmi.Remote, ScheduleOwner, Device, DeviceServiceIF, Instrument

public class SatlanticISUS
extends InstrumentService
implements Instrument

The MBARI-ISUS class represents the InstrumentServices driver for controlling the Satlantic MBARI_ISUS. The primary responsibilities of this class is to:-

 
 Capture sample data from the instrument.
 
 

See Also:

Device, Instrument, PowerPort, InstrumentService, Serialized Form

Field Summary

Fields inherited from class org.mbari.siam.core.InstrumentService

_defaultSampleScheduleName, _instrumentAttributes, _lastPacket, _lastSensorDataPacket, _log4j, _messagePacket, _packetLog, _recordType, _schedules, _sensorDataPacket, RECORDTYPE_DEFAULT, RECORDTYPE_METADATA, RECORDTYPE_UNDEFINED

Fields inherited from class org.mbari.siam.core.DeviceService

_fromDevice, _instrumentPort, _nodeProperties, _parentNode, _regEntry, _sandBox, _serviceCachePath, _serviceName, _servicePropertiesPath, _serviceXMLPath, _toDevice, CACHED_PROPERTIES_FILENAME, PROPERTIES_FILENAME, XML_FILENAME

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface org.mbari.siam.distributed.Device

ERROR, INITIAL, INSTRUMENT_STATE, MDATA_ALL, OK, SAFE, SAMPLING, SERVICE_ATTRIBUTES, SERVICE_CACHE, SERVICE_PROPERTIES, SERVICE_XML, SHUTDOWN, SLEEPING, SUSPEND, UNKNOWN

Constructor Summary

SatlanticISUS()

Method Summary

protected ScheduleSpecifier	createDefaultSampleSchedule() Return specifier for default sampling schedule.
protected byte[]	getInstrumentMetadata() Not implemented
SerialPortParameters	getSerialPortParameters() Return parameters to use on serial port.
protected PowerPolicy	initCommunicationPowerPolicy() Return initial value of communication power policy.
protected int	initCurrentLimit() Specify current limit in increments of 120 mA upto 11880 mA.
protected void	initializeInstrument() This method tries to initialize the ISUS.
protected PowerPolicy	initInstrumentPowerPolicy() Return initial value of instrument power policy.
protected int	initInstrumentStartDelay() Specify startup delay (millisec)
protected int	initMaxSampleBytes() Specify maximum bytes in raw sample.
protected byte[]	initPromptString() Specify prompt string.
protected byte[]	initSampleTerminator() Specify sample terminator.
protected void	prepareToSample() Called by the framework before sampling.
protected int	readIsusRecords(java.io.InputStream instream, byte[] sample, long totalTimeoutMSec, long lineTimeoutMSec) Called by the readSample to fetch the sample data returned from the instrument and copy to sample buffer.
protected int	readSample(byte[] sample) Called by the framework to fetch the sample data returned from the instrument and copy to sample buffer.
protected void	requestSample() requestSample does not actually poll the instrument in this case, since it is assumed to be in a scheduled output mode, periodically coming out of sleep, taking a measurement, and sending the data out the serial port.
void	setClock(long t) Not implemented.
int	test() For some reason, this method is required by the framework

Methods inherited from class org.mbari.siam.core.InstrumentService

acquire, acquireSample, addDefaultPacketFilters, addSchedule, addSchedule, annotate, cacheProperties, checkInputProperties, cleanupServiceState, clearDefaultPacketFilters, clearPropertiesCache, createTask, disableSamplingDiagnostics, disableSummary, doScheduledTask, enableSamplingDiagnostics, enableSummary, getAllSchedules, getChildren, getCommunicationPowerPolicy, getCurrentLimit, getDefaultPacketFilters, getDefaultSampleSchedule, getDefaultSampleScheduleName, getDevicePacketParser, getFileBytes, getInstrumentBlock, getInstrumentPowerPolicy, getInstrumentStartDelay, getInstrumentStateMetadata, getLastSample, getLocation, getMaxSampleBytes, getMaxSampleTries, getMetadata, getMetadata, getMetadataPayload, getPackets, getPackets, getParent, getParser, getPortDiagnostics, getPortDiagnosticsSummary, getPromptString, getProperties, getProperty, getSampleBuf, getSampleSchedule, getSampleTerminator, getSampleTimeout, getSchedule, getScheduleKey, getSchedules, getServiceCacheBytes, getServicePropertiesBytes, getServiceXMLBytes, initialize, initializeDriverDefaults, initServiceState, interruptSampling, logPacket, managePowerSleep, managePowerWake, parseDataPacket, postSample, powerOff, powerOffCallback, powerOn, powerOnCallback, prepareToRun, printData, processSample, removeAllSchedules, removeSchedule, resetPortDiagnostics, resumeSchedule, running, setAttributes, setClock, setCommunicationPowerPolicy, setCurrentLimit, setDefaultSampleScheduleName, setInstrumentBlock, setInstrumentPowerPolicy, setInstrumentStartDelay, setMaxSampleBytes, setMaxSampleTries, setPromptString, setProperty, setRecordType, setSampleTerminator, setSampleTimeout, shutdown, shutdownInstrument, sleepingUntil, summaryEnabled, suspend, suspendSchedule, sync, syncSchedule, validateSample

Methods inherited from class org.mbari.siam.core.DeviceService

addDataListener, advertiseService, createRegistryEntry, getAttributes, getCommPortName, getFrameworkVersion, getId, getInstrumentPort, getName, getRemoteSerialPort, getRemoteSerialPort, getSamplingCount, getSamplingErrorCount, getSamplingRetryCount, getStatus, host, incRetryCount, initializePropertyDefaults, registryEntry, registryName, removeDataListener, resume, setInstrumentPort, setNodeProperties, setParent, setSerialPort, setStatusError, setStatusInitial, setStatusOk, setStatusSafe, setStatusSampling, setStatusShutdown, setStatusSuspend

Methods inherited from class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.mbari.siam.distributed.Instrument

acquireSample, addDefaultPacketFilters, annotate, cacheProperties, clearDefaultPacketFilters, clearPropertiesCache, disableSummary, enableSummary, getDefaultPacketFilters, getLastSample, getPackets, getPackets, getParser, getPortDiagnostics, getPortDiagnosticsSummary, getProperties, getProperty, getSampleSchedule, getSchedules, resetPortDiagnostics, setClock, setProperty, summaryEnabled

Methods inherited from interface org.mbari.siam.distributed.Device

getChildren, getCommPortName, getFrameworkVersion, getId, getLocation, getMetadata, getName, getParent, getSamplingCount, getSamplingErrorCount, getSamplingRetryCount, getStatus, host, powerOff, powerOn, prepareToRun, resume, shutdown, suspend

Methods inherited from interface org.mbari.siam.distributed.DeviceServiceIF

getName

Constructor Detail

SatlanticISUS

public SatlanticISUS()
              throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException - .

Method Detail

initInstrumentStartDelay

protected int initInstrumentStartDelay()

Specify startup delay (millisec)

Specified by:

initInstrumentStartDelay in class InstrumentService

initPromptString

protected byte[] initPromptString()

Specify prompt string.

Specified by:

initPromptString in class InstrumentService

initSampleTerminator

protected byte[] initSampleTerminator()

Specify sample terminator.

Specified by:

initSampleTerminator in class InstrumentService

initMaxSampleBytes

protected int initMaxSampleBytes()

Specify maximum bytes in raw sample.

Specified by:

initMaxSampleBytes in class InstrumentService

initCurrentLimit

protected int initCurrentLimit()

Specify current limit in increments of 120 mA upto 11880 mA.

Specified by:

initCurrentLimit in class InstrumentService

initInstrumentPowerPolicy

protected PowerPolicy initInstrumentPowerPolicy()

Return initial value of instrument power policy.

Specified by:

initInstrumentPowerPolicy in class InstrumentService

initCommunicationPowerPolicy

protected PowerPolicy initCommunicationPowerPolicy()

Return initial value of communication power policy.

Specified by:

initCommunicationPowerPolicy in class InstrumentService

createDefaultSampleSchedule

protected ScheduleSpecifier createDefaultSampleSchedule()
                                                 throws ScheduleParseException

Return specifier for default sampling schedule.

Specified by:

createDefaultSampleSchedule in class InstrumentService

Throws:

ScheduleParseException

getSerialPortParameters

public SerialPortParameters getSerialPortParameters()
                                             throws gnu.io.UnsupportedCommOperationException

Return parameters to use on serial port.

Overrides:

getSerialPortParameters in class DeviceService

Throws:

gnu.io.UnsupportedCommOperationException

initializeInstrument

protected void initializeInstrument()
                             throws InitializeException,
                                    java.lang.Exception

This method tries to initialize the ISUS. However the instrument is extraordinarily difficult to program since it can be in a number of states, each one requiring a different scheme to initialize the instrument. This has made this method complex and potentially unreliable as there is no documentation on the various states in which the instrument can find itself. Empirically determining this is not the right way but alas the only way.

Overrides:

initializeInstrument in class InstrumentService

Throws:

InitializeException

java.lang.Exception

prepareToSample

protected void prepareToSample()
                        throws java.lang.Exception

Called by the framework before sampling.

Overrides:

prepareToSample in class InstrumentService

Throws:

java.lang.Exception

requestSample

protected void requestSample()
                      throws TimeoutException,
                             java.lang.Exception

requestSample does not actually poll the instrument in this case, since it is assumed to be in a scheduled output mode, periodically coming out of sleep, taking a measurement, and sending the data out the serial port. Devising a robust sampling strategy for the instrument is difficult, since there are not an explicit delimiters marking the beginning and end of the data, and the timing is variable and not deterministic; there is some text that comes out before the data appears, but nothing to indicate the end of the data output. It would have been better if it were possible to disable all output other than the data, or if there were a delimiter to mark the end of data, and some known bound on the time it could take to produce a sample. A polled mode would also suffice. The sampling strategy is further complicated by the fact that the power-on timing is such that if the instrument is not allowed enough time between power-off and power-on, it can go into an unresponsive state. Also, if the instrument is kept awake through a sampling cycle, it goes into an unresponsive state. Another difficulty presented by the instrument is that its configuration consists of multi-layered menus which present an obstacle to programming, since traversing them is cumbersome in software. Moreover, the menu text contains subtle changes in different firmware versions, creating additional opportunities for failure through broken parsing. Another configuration related issue is that some areas of the menu system cannot be exited without power cycling the instrument, making it awkward to discover the instrument's current state in a robust and efficient way. The sampling strategy in this version has been completely revised, and appears to be more robust: The instrument must be configured in Scheduled mode, and given a power policy of POWER_ALWAYS. At initialization, the instrument is power-cycled, and the sample period is obtained from the instrument, by traversing its menus. Following successful initialization, the instrument service attempts to obtain a sample. The instrument service begins by waiting for text indicating that the UV light source is powered on, which precedes the output of data by some (variable) relatively short time period. If the UV-on text is not found, the service power cycles the instrument and reschedules itself to make another attempt in the next sample interval. If UV-on text is found, the service framework calls readSample, which in turn calls the method readISUSRecords. readISUSRecords then reads lines (using StreamUtils.skipUntil); a pair of timeouts governs the reading of each line and the total time allowed to obtain the data. This is not ideal, since the timeout for the reading of each line must be empirically determined, and is somewhat arbitrary, and as a result is probably longer than necessary. It seems to work fairly robustly, however. When the UV-on message is found, the service is re-synchronized to execute again in one sample period less some gaurd time (specified in _attributes.preemptionSec). The loop acquires lines, which it must parse to eliminate non-data lines and to extract the data, which is coalesced into the sample buffer and returned to the instrument service. When the expected number of light and dark records (set through _attributes.lightRecords, etc.), the data collection ends. Two additional tuning parameters, _attributes.requestAdjustSec and _attributes.readAdjustSec, may be used to adjust the timing in situ, should it change significantly, as it has been known to do, perhaps owing to file access timing within the instrument's flash file system. These default to zero.

Specified by:

requestSample in class InstrumentService

Throws:

TimeoutException - thrown if no data is detected within the specified timeout period

java.lang.Exception - not thrown

readSample

protected int readSample(byte[] sample)
                  throws TimeoutException,
                         java.io.IOException,
                         java.lang.Exception

Called by the framework to fetch the sample data returned from the instrument and copy to sample buffer.

Overrides:

readSample in class InstrumentService

Parameters:

sample -

Returns:

sample size (bytes)

Throws:

TimeoutException - sample time exceeded

java.io.IOException - error in input stream

java.lang.Exception - Packet exceeded packet length indicator (should really be in validateSample(..))

readIsusRecords

protected int readIsusRecords(java.io.InputStream instream,
                              byte[] sample,
                              long totalTimeoutMSec,
                              long lineTimeoutMSec)
                       throws TimeoutException,
                              java.io.IOException,
                              java.lang.Exception

Called by the readSample to fetch the sample data returned from the instrument and copy to sample buffer.

Parameters:

instream -

sample -

totalTimeoutMSec - total time allowed to find data

lineTimeoutMSec - time allowed to obtain a single line

Returns:

sample size (bytes)

Throws:

TimeoutException - sample time exceeded

java.io.IOException - error in input stream

java.lang.Exception

getInstrumentMetadata

protected byte[] getInstrumentMetadata()

Not implemented

Returns:

Instrument metadata (byte array)

setClock

public void setClock(long t)

Not implemented. Samples are locally timestamped

Specified by:

setClock in interface Instrument

Specified by:

setClock in class InstrumentService

Parameters:

t -

test

public int test()

For some reason, this method is required by the framework

Specified by:

test in interface Device