lejos.nxt.comm
Class NXTConnection

java.lang.Object
  lejos.nxt.comm.NXTConnection

All Implemented Interfaces:

Connection, InputConnection, OutputConnection, StreamConnection

Direct Known Subclasses:

BTConnection, RS485Connection, USBConnection

public abstract class NXTConnection
extends Object
implements StreamConnection

Generic lejos nxt connection class. Provide access to standard read/write methods. This code supports both asynchronous (used for Bluetooth and RS-485 connections) and synchronous (used for USB) I/O operations for the actual reading and writing of the low level buffers.

NOTE: The code in this class makes a number of assumptions:

1. The input and output buffers have been sized to match the underlying device and the packet header size. In particular, the synchronous code assumes that the entire output buffer can be written using a single atomic write operation.
2. Although the code can handle any size packet header, the default is assumed to be 2 bytes. If this is not the case (for example USB), then the setIOMode function must be over-ridden.
3. This class allows the use of a "soft" EOF implementation which uses a zero length packet as an EOF marker. This only operates when in PACKET mode and can be overridden. Currently this is used for USB devices. It is not used for Bluetooth/RS-485 connections.
4. Some devices (like USB), have an inherent packet structure. The current PC assumes that when in PACKET mode, an entire packet will fit within a single USB packet. This limits the maximum packet size which can be used over USB connections to 63 bytes. This code does not currently enforce this limit.

Author:

Andy Shaw

Field Summary

static int	LCP Lego Communications Protocol (LCP) I/O mode.
static int	PACKET PACKET I/O mode.
static int	RAW RAW I/O mode.

Constructor Summary

NXTConnection()

Method Summary

int	available() Convenience method that calls available(0)
int	available(int what) Indicate the number of bytes available to be read.
void	close() Close the connection.
String	getAddress() Get the device address set by implementation.
DataInputStream	openDataInputStream() Return the DataInputStream for this connect
DataOutputStream	openDataOutputStream() Return the DataOutputStream for this connection.
InputStream	openInputStream() Return the InputStream for this connection.
OutputStream	openOutputStream() Return the OutputStream for this connection
int	read(byte[] data, int len) Perform a blocking read on the connection
int	read(byte[] data, int outLen, boolean wait) Attempt to read data from the connection.
int	readPacket(byte[] buf, int len) Read a packet from the stream.
int	sendPacket(byte[] buf, int bufLen) Send a data packet.
void	setIOMode(int mode) Set operating mode.
int	write(byte[] data, int len) Perform a blocking write on the connection
int	write(byte[] data, int len, boolean wait) Attempt to write bytes to the connection.

Methods inherited from class java.lang.Object

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

Field Detail

LCP

public static final int LCP

Lego Communications Protocol (LCP) I/O mode. The LCP is defined by The Lego Company to allow limited remote command control of a NXT brick. See the Lego Mindstorms Site. Look for the Bluetooth Developer Kit in Support | Files | Advanced

See Also:

Constant Field Values

PACKET

public static final int PACKET

PACKET I/O mode. This is default and is probably the best mode to use if you are talking to a NXT using the leJOS classes. Headers are included for each packet of data sent and received.

See Also:

Constant Field Values

RAW

public static final int RAW

RAW I/O mode. This mode is just that and omits any headers. It is used normally for connections to non-NXT devices such as cell phones, etc.

See Also:

Constant Field Values

Constructor Detail

NXTConnection

public NXTConnection()

Method Detail

getAddress

public String getAddress()

Get the device address set by implementation.

Returns:

The device address

write

public int write(byte[] data,
                 int len,
                 boolean wait)

Attempt to write bytes to the connection. Optionally wait if it is not possible to write at the moment. Supports both PACKET and RAW write operations. If in PACKET mode, a set of header bytes indicating the size of the packet will be sent ahead of the data.

NOTE: If in PACKET mode, the maximum write will be limited to the underlying maximum packet length. When using PACKET mode with writes larger then the I/O buffer, the wait mode=true must be used to ensure correct operation.

Parameters:

data - The data to be written.

len - The number of bytes to write.

wait - true if the call should block until all of the data has been sent.

Returns:

• > 0: number of bytes written.
• 0: Request would have blocked (and wait was false).
• -1: An error occurred
• -2: Data has been lost (See NOTE above).

read

public int read(byte[] data,
                int outLen,
                boolean wait)

Attempt to read data from the connection. Optionally wait for data to become available. Supports both PACKET and RAW mode operations. When in PACKET mode, the packet length bytes are automatically processed. The read will return just a single packet. If the packet is larger then the requested length, then the rest of the packet will be returned in the following reads.

If wait is true then in PACKET mode, the call will wait until either the entire packet can be read or outLen bytes are available. In stream mode the call will return if at least 1 byte has been read.

Parameters:

data - Location to return the data. If null the data is discarded.

outLen - Max number of bytes to read.

wait - Should the call block waiting for data.

Returns:

• > 0: number of bytes read.
• 0: no bytes available (and wait was false).
• -1: EOF/Connection closed.
• -2: data lost (see notes).
• -3: Some other error

available

public int available(int what)

Indicate the number of bytes available to be read. Supports both PACKET mode and stream connections.

Parameters:

what - 0 (all modes) return the number of bytes that can be read without blocking. 1 (packet mode) return the number of bytes still to be read from the current packet. 2 (packet mode) return the length of the current packet.

Returns:

number of bytes available

available

public int available()

Convenience method that calls available(0)

Returns:

number of bytes available

See Also:

available(int)

setIOMode

public void setIOMode(int mode)

Set operating mode. Controls the packet/stream mode of this channel. For PACKET mode, it defines the header size to be used.

Parameters:

mode - I/O mode to be used for this connection. RAW, LCP, or PACKET

See Also:

RAW, LCP, PACKET

read

public int read(byte[] data,
                int len)

Perform a blocking read on the connection

Parameters:

data - byte array to store the results.

len - max number of bytes to read

Returns:

actual number of bytes read, return < 0 for error

write

public int write(byte[] data,
                 int len)

Perform a blocking write on the connection

Parameters:

data - byte array to be written.

len - number of bytes to write

Returns:

actual number of bytes written, return < 0 for error

openInputStream

public InputStream openInputStream()

Return the InputStream for this connection.

Specified by:

openInputStream in interface InputConnection

Returns:

the input stream

See Also:

NXTInputStream

openOutputStream

public OutputStream openOutputStream()

Return the OutputStream for this connection

Specified by:

openOutputStream in interface OutputConnection

Returns:

the output stream

See Also:

NXTOutputStream

openDataInputStream

public DataInputStream openDataInputStream()

Return the DataInputStream for this connect

Specified by:

openDataInputStream in interface InputConnection

Returns:

the data input stream

openDataOutputStream

public DataOutputStream openDataOutputStream()

Return the DataOutputStream for this connection.

Specified by:

openDataOutputStream in interface OutputConnection

Returns:

the data output stream

close

public void close()

Close the connection. Flush any pending output. Informs the remote side that the connection is now closed and frees resources.

Specified by:

close in interface Connection

readPacket

public int readPacket(byte[] buf,
                      int len)

Read a packet from the stream. Do not block and for small packets (< [package access scope variable] bufSz), do not return a partial packet.

Parameters:

buf - Buffer to read data into.

len - Number of bytes to read.

Returns:

> 0 number of bytes read. Other values see read.

See Also:

read(byte[],int,boolean)

sendPacket

public int sendPacket(byte[] buf,
                      int bufLen)

Send a data packet. Must be in data mode.

Parameters:

buf - the data to send

bufLen - the number of bytes to send

Returns:

number of bytes written