org.mbari.puck
Class Puck

java.lang.Object
  extended by 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


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.