org.mbari.puck
Class Puck

java.lang.Object
  org.mbari.puck.Puck

Direct Known Subclasses:

Puck_1_3

public abstract class Puck
extends java.lang.Object

Define operations that can be performed on an MBARI PUCK. These include operations such as read, write, erase, etc. According to PUCK specification, these operations will be recognized and executed if device is in "PUCK mode" (as opposed to "instrument mode"). Thus the setPuckMode() method should be invoked prior to executing the other methods.

The "PUCK offset" points to the location in PUCK memory to be accessed by the next read() or write() operation; these operations automatically advance the offset by the number of bytes read or written. In addition, the offset can be explicitly set with setOffset().

Author:

Tom O'Reilly

Nested Class Summary

static class

Puck.Datasheet Instrument data sheet associated with PUCK device.

Field Summary

protected boolean

_readyToWrite Indicates that PUCK memory is ready to be written to; set to true by erase(), set to false by flush().

Constructor Summary

Puck(gnu.io.SerialPort port)
Create Puck, using specified SerialPort.

Method Summary

void	close() Free resources.
void	erase() Erase PUCK payload and set offset to 0.
boolean	externalDevice() Return true if PUCK device is external to instrument.
void	flush() End a PUCK write session; no other write() calls should be attempted following flush(), until a new write session is intiated with erase().
protected void	flushInput() Discard characters from input until no more are available.
int	getOffset() Return PUCK read/write offset
void	getPuckPrompt(int nTries) Send PUCK "null command" and look for appropriate response.
abstract int	getVersionNumber() Return a version number for the datasheet, per section 4 of the PUCK specification.
boolean	hasPayload() Return true if PUCK has payload space, else return false.
abstract byte[]	nullCommand() Return PUCK "null" command"
abstract byte[]	promptString() Return PUCK prompt string.
int	read(byte[] payload, int offset, int nBytesRequested) Read up to nBytesRequested bytes from current PUCK offset into an array of bytes.
Puck.Datasheet	readDatasheet() Read and return PUCK datasheet.
protected java.lang.String	readResponse(long timeout) Read and return PUCK response after trimming whitespace from beginning and end; throw Exception if response contains "ERR".
void	setBaud(int baud) Set baud rate on both sides of comm link.
int	setFastBaud() Configure PUCK interface for highest valid baud, on both sides of serial link.
void	setInstrumentMode() Put device into Instrument mode.
void	setOffset(int offset) Set PUCK read/write offset.
abstract void	setPuckMode(int nTries) Put device into PUCK mode
int	size() Return total size of PUCK storage, in bytes; includes datasheet.
int	skipDatasheet() Move read/write offset to just past datasheet, to beginning of payload section.
void	write(byte[] payload) Write payload bytes, starting at current PUCK offset.
boolean	writeableDatasheet() Return true if datasheet is writeable; else return false
void	writeDatasheet(Puck.Datasheet datasheet) Write datasheet

Methods inherited from class java.lang.Object

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

Field Detail

_readyToWrite

protected boolean _readyToWrite

Indicates that PUCK memory is ready to be written to; set to true by erase(), set to false by flush().

Constructor Detail

Puck

public Puck(gnu.io.SerialPort port)
     throws java.io.IOException,
            java.lang.Exception

Create Puck, using specified SerialPort.

Throws:

java.io.IOException

java.lang.Exception

Method Detail

flush

public void flush()
           throws java.io.IOException,
                  java.lang.Exception

End a PUCK write session; no other write() calls should be attempted following flush(), until a new write session is intiated with erase().

Throws:

java.io.IOException

java.lang.Exception

readDatasheet

public Puck.Datasheet readDatasheet()
                             throws java.io.IOException,
                                    java.lang.Exception

Read and return PUCK datasheet.

Throws:

java.io.IOException

java.lang.Exception

writeDatasheet

public void writeDatasheet(Puck.Datasheet datasheet)
                    throws java.io.IOException,
                           java.lang.Exception

Write datasheet

Throws:

java.io.IOException

java.lang.Exception

skipDatasheet

public int skipDatasheet()
                  throws java.io.IOException,
                         java.lang.Exception

Move read/write offset to just past datasheet, to beginning of payload section.

Throws:

java.io.IOException

java.lang.Exception

setInstrumentMode

public void setInstrumentMode()
                       throws java.lang.Exception

Put device into Instrument mode.

Throws:

java.lang.Exception

erase

public void erase()
           throws java.lang.Exception

Erase PUCK payload and set offset to 0.

Throws:

java.lang.Exception

setOffset

public void setOffset(int offset)
               throws java.lang.Exception

Set PUCK read/write offset.

Throws:

java.lang.Exception

getOffset

public int getOffset()
              throws java.lang.Exception

Return PUCK read/write offset

Throws:

java.lang.Exception

write

public void write(byte[] payload)
           throws java.io.IOException,
                  java.lang.Exception

Write payload bytes, starting at current PUCK offset. Note that PUCK memory should be erased prior to a "writing session".

Throws:

java.io.IOException

java.lang.Exception

read

public int read(byte[] payload,
                int offset,
                int nBytesRequested)
         throws java.lang.Exception

Read up to nBytesRequested bytes from current PUCK offset into an array of bytes. Attempt to read as many as nBytesRequested, but a smaller number may be read, possibly zero. The PUCK offset is advanced by the number of bytes actually read, which is as an integer. Bytes are stored in payload, starting at index offset.

Throws:

java.lang.Exception

setBaud

public void setBaud(int baud)
             throws java.lang.Exception

Set baud rate on both sides of comm link.

Throws:

java.lang.Exception

setFastBaud

public int setFastBaud()
                throws java.io.IOException

Configure PUCK interface for highest valid baud, on both sides of serial link.

Throws:

java.io.IOException

size

public int size()
         throws java.io.IOException,
                java.lang.Exception

Return total size of PUCK storage, in bytes; includes datasheet.

Throws:

java.io.IOException

java.lang.Exception

getPuckPrompt

public void getPuckPrompt(int nTries)
                   throws java.lang.Exception

Send PUCK "null command" and look for appropriate response.

Throws:

java.lang.Exception

readResponse

protected java.lang.String readResponse(long timeout)
                                 throws java.lang.Exception

Read and return PUCK response after trimming whitespace from beginning and end; throw Exception if response contains "ERR".

Throws:

java.lang.Exception

hasPayload

public boolean hasPayload()
                   throws java.lang.Exception

Return true if PUCK has payload space, else return false.

Throws:

java.lang.Exception

writeableDatasheet

public boolean writeableDatasheet()
                           throws java.lang.Exception

Return true if datasheet is writeable; else return false

Throws:

java.lang.Exception

externalDevice

public boolean externalDevice()
                       throws java.lang.Exception

Return true if PUCK device is external to instrument.

Throws:

java.lang.Exception

close

public void close()
           throws java.io.IOException

Free resources. NOTE: This method should NOT close resources associated with the referenced SerialPort!

Throws:

java.io.IOException

setPuckMode

public abstract void setPuckMode(int nTries)
                          throws java.io.IOException

Put device into PUCK mode

Throws:

java.io.IOException

nullCommand

public abstract byte[] nullCommand()

Return PUCK "null" command"

promptString

public abstract byte[] promptString()

Return PUCK prompt string.

getVersionNumber

public abstract int getVersionNumber()

Return a version number for the datasheet, per section 4 of the PUCK specification.

flushInput

protected void flushInput()
                   throws java.lang.Exception

Discard characters from input until no more are available.

Throws:

java.lang.Exception