org.mbari.siam.devices.slisus
Class SatlanticISUS

java.lang.Object
  extended by java.rmi.server.RemoteObject
      extended by java.rmi.server.RemoteServer
          extended by java.rmi.server.UnicastRemoteObject
              extended by org.mbari.siam.core.DeviceService
                  extended by org.mbari.siam.core.InstrumentService
                      extended by 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


Copyright © 2003 MBARI.

The Monterey Bay Aquarium Research Institute (MBARI) provides this documentation and code "as is", with no warranty, express or implied, of its quality or consistency. It is provided without support and without obligation on the part of MBARI to assist in its use, correction, modification, or enhancement.