josx.platform.rcx
Class Serial

java.lang.Object
  josx.platform.rcx.Serial

public class Serial

extends Object

Low-level API for infra-red (IR) communication between an RCX and the IR tower or between two RCXs. For protocol details, Kekoa Proudfoot's Opcode Reference is highly recommended. See Kekoa's RCX Internals page. Kekoa Proudfoot has also written a C based tool (Send) which you can use to send packets to the RCX. If you prefer to write everything in Java, you should become familiar with the Java Communications API. Frameworks based on this API have already been developed by Dario Laverde (see RCXLoader) and Scott Lewis (see RCXPort). The Java Communications API is officially supported on Windows and Solaris.

Examples that use the leJOS Serial class can be found in:

• examples/serial --- Receiver for certain opcodes, such as MotorOn.
• examples/serial2rcx --- Communication between two RCXs.
• examples/remotectl --- Receiver for Lego remote control.

The basic pattern for a Receiver is:

    byte[] packet = new byte[8];
    for (;;)
    {
      if (Serial.isPacketAvailable())
      {
        Serial.readPacket (packet);
        byte opcode = packet[0];
        if (opcode == AN_OPCODE)
          ...
          ...
        // Possibly send a response here
        packet = ~packet[0];
        Serial.sendPacket (packet, 0, PACKET_LENGTH);
      }
    }
 

Method Summary

static void	addSerialListener(SerialListener aListener) Adds a listener of receive events.
static boolean	isPacketAvailable() Checks to see if a packet is available.
static boolean	isSending() Return true if a message is being sent.
static int	readPacket(byte[] aBuffer) Reads a packet received by the RCX, if one is available.
static void	resetSerial() Resets serial communications.
static boolean	sendPacket(byte[] aBuffer, int aOffset, int aLen) Sends a packet to the IR tower or another RCX.
static void	setDataBuffer(byte[] aData) Sets the buffer that will be used to save data transferred with opcode 0x45.
static void	setRangeLong() Sets long range transmision.
static void	setRangeShort() Sets short range transmision.
static void	waitTillSent() Wait until a message has been sent.

Methods inherited from class java.lang.Object

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

Method Detail

readPacket

public static int readPacket(byte[] aBuffer)

Reads a packet received by the RCX, if one is available. The first byte in the buffer is the opcode. Opcode 0x45 (Transfer Data) is received in a special way: If you had previously called setDataBuffer(), packet data will be copied into the buffer provided. Note the caveats regarding setDataBuffer() use.

Returns:

The number of bytes received.

See Also:

isPacketAvailable(), setDataBuffer(byte[])

setDataBuffer

public static void setDataBuffer(byte[] aData)

Sets the buffer that will be used to save data transferred with opcode 0x45.

Note: This method must be used with caution. A pointer to the data buffer is passed to the ROM for asynchronous use. If more data is received than can be stored in the buffer, the VM's memory will be corrupted and it will crash or at least misbehave.

isPacketAvailable

public static boolean isPacketAvailable()

Checks to see if a packet is available. Call this method before calling receivePacket.

sendPacket

public static boolean sendPacket(byte[] aBuffer,
                                 int aOffset,
                                 int aLen)

Sends a packet to the IR tower or another RCX. In general, the IR tower will only receive responses to messages it has sent. The call returns immediately.

Returns:

false if a packet is already being sent.

setRangeLong

public static void setRangeLong()

Sets long range transmision.

setRangeShort

public static void setRangeShort()

Sets short range transmision.

resetSerial

public static void resetSerial()

Resets serial communications. It can be used to disable buffers set with setDataBuffer.

isSending

public static boolean isSending()

Return true if a message is being sent.

waitTillSent

public static void waitTillSent()
                         throws InterruptedException

Wait until a message has been sent.

Throws:

InterruptedException

addSerialListener

public static void addSerialListener(SerialListener aListener)

Adds a listener of receive events. There can be at most 4 listeners.