Class Serial

  extended byjosx.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:

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


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.

The number of bytes received.
See Also:
isPacketAvailable(), setDataBuffer(byte[])


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.


public static boolean isPacketAvailable()
Checks to see if a packet is available. Call this method before calling receivePacket.


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.

false if a packet is already being sent.


public static void setRangeLong()
Sets long range transmision.


public static void setRangeShort()
Sets short range transmision.


public static void resetSerial()
Resets serial communications. It can be used to disable buffers set with setDataBuffer.


public static boolean isSending()
Return true if a message is being sent.


public static void waitTillSent()
                         throws InterruptedException
Wait until a message has been sent.



public static void addSerialListener(SerialListener aListener)
Adds a listener of receive events. There can be at most 4 listeners.