Well, the conclusion of the RXTX posts in this blog may have been written in this code sample. It will help you to establish serial port operations (connect / disconnect / add data available listener / get serial port’s OutputStream/InputStream).

I put this on the blog, because I keep moving around project to project. Hence, it always take a lot of time to find it from one of the project folders. At least, if I keep it online, google will help me to find it when I need it.

/*
 * Copyright (c) 2008, Daniel Widyanto
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Daniel Widyanto ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Daniel Widyanto BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package com.kunilkuda.sms;

import gnu.io.CommPortIdentifier;
import gnu.io.SerialPort;

import gnu.io.NoSuchPortException;
import gnu.io.PortInUseException;
import gnu.io.UnsupportedCommOperationException;
import java.util.TooManyListenersException;

import gnu.io.SerialPortEvent;
import gnu.io.SerialPortEventListener;

import java.io.InputStream;
import java.io.OutputStream;
import java.io.IOException;

import java.util.ArrayList;
import java.util.Enumeration;

/**
 * \brief Additional help to handle serial connect / disconnect, and registering
 *        interrupt handler
 */
public class SerialHelper {

    private SerialPort serialPort;
    private OutputStream outStream;
    private InputStream inStream;

    /**
     * \brief List the available serial ports
     *
     * \return Array of string for the available serial port names
     */
    public static String[] listSerialPorts() {
        Enumeration ports = CommPortIdentifier.getPortIdentifiers();
        ArrayList portList = new ArrayList();
        String portArray[] = null;
        while (ports.hasMoreElements()) {
            CommPortIdentifier port = (CommPortIdentifier) ports.nextElement();
            if (port.getPortType() == CommPortIdentifier.PORT_SERIAL) {
                portList.add(port.getName());
            }
        }
        portArray = (String[]) portList.toArray(new String[0]);
        return portArray;
    }

    /**
     * \brief Connect to the selected serial port with 57600bps-8N1 mode
     */
    public void connect(String portName) throws IOException {
        try {
            // Obtain a CommPortIdentifier object for the port you want to open
            CommPortIdentifier portId =
                    CommPortIdentifier.getPortIdentifier(portName);

            // Get the port's ownership
            serialPort = (SerialPort) portId.open("Demo application", 5000);

            // Set the parameters of the connection.
            setSerialPortParameters();

            // Open the input and output streams for the connection.
            // If they won't open, close the port before throwing an
            // exception.
            outStream = serialPort.getOutputStream();
            inStream = serialPort.getInputStream();
        } catch (NoSuchPortException e) {
            throw new IOException(e.getMessage());
        } catch (PortInUseException e) {
            throw new IOException(e.getMessage());
        } catch (IOException e) {
            serialPort.close();
            throw e;
        }
    }

    /**
     * \brief Get the serial port input stream
     * \return The serial port input stream
     */
    public InputStream getSerialInputStream() {
        return inStream;
    }

    /**
     * \brief Get the serial port output stream
     * \return The serial port output stream
     */
    public OutputStream getSerialOutputStream() {
        return outStream;
    }

    /**
     * \brief Sets the serial port parameters to 57600bps-8N1
     */
    protected void setSerialPortParameters() throws IOException {

        final int baudRate = 57600; // 57600bps

        try {
            // Set serial port to 57600bps-8N1..my favourite
            serialPort.setSerialPortParams(
                    baudRate,
                    SerialPort.DATABITS_8,
                    SerialPort.STOPBITS_1,
                    SerialPort.PARITY_NONE);

            serialPort.setFlowControlMode(SerialPort.FLOWCONTROL_NONE);
        } catch (UnsupportedCommOperationException ex) {
            throw new IOException("Unsupported serial port parameter");
        }
    }

    /**
     * \brief Register listener for data available event
     *
     * @param dataAvailableListener The data available listener
     */
    public void addDataAvailableListener(SerialPortEventListener dataAvailableListener)
            throws TooManyListenersException {
        // Add the serial port event listener
        serialPort.addEventListener(dataAvailableListener);
        serialPort.notifyOnDataAvailable(true);
    }

    /**
     * \brief Disconnect the serial port
     */
    public void disconnect() {
        if (serialPort != null) {
            try {
                // close the i/o streams.
                outStream.close();
                inStream.close();
            } catch (IOException ex) {
                // don't care
            }
            // Close the port.
            serialPort.close();
            serialPort = null;
        }
    }

    /**
     * \brief Private inner class to test and debug the SerialHelper class
     */
    public static class SerialHelperTester implements SerialPortEventListener {

        public static void main(String[] args) {
            if (args.length < 1) {
                System.out.println(
                        "Usage: java SerialHelperTester <dataToBeSentToSerialPort>");
                System.exit(1);
            }

            SerialHelper serialHelper = new SerialHelper();

            checkListSerialPorts(serialHelper);
            checkConnect(serialHelper);
            checkAddDataAvailableListener(serialHelper, args[0]);
            checkDisconnect(serialHelper);
        }

        private static void checkListSerialPorts(SerialHelper serialHelper) {
            System.out.println("Check the listSerialPorts");
            System.out.println("-------------------------");
            String[] serialPorts = SerialHelper.listSerialPorts();
            if (serialPorts != null) {
                for (int i = 0; i < serialPorts.length; i++) {
                    System.out.println("Port name: " + serialPorts[i]);
                }
            }
            System.out.println();
        }

        private static void checkConnect(SerialHelper serialHelper) {
            // Replace it with the tested serial port
            final String serialPort = "/dev/ttyACM0";

            System.out.println("Connect to serial port");
            System.out.println("-------------------------");
            try {
                serialHelper.connect(serialPort);
            } catch (Exception e) {
                System.err.println(e.getMessage());
            }

            System.out.println();
        }

        private static void checkAddDataAvailableListener(
                SerialHelper serialHelper, String data) {
            System.out.println("Check data available listener");
            System.out.println("-----------------------------");

            SerialHelperTester tester =
                    new SerialHelperTester(serialHelper.getSerialInputStream(),
                    serialHelper.getSerialOutputStream());

            try {
                serialHelper.addDataAvailableListener(tester);
            } catch (TooManyListenersException ex) {
                System.err.println(ex.getMessage());
            }

            OutputStream outStream = serialHelper.getSerialOutputStream();
            data = data + "\r";
            try {
                outStream.write(data.getBytes());
            } catch (IOException ex) {
                System.err.println(ex.getMessage());
            }

            try {
                // Sleep for 10-secs
                Thread.sleep(10000);
            } catch (InterruptedException ex) {
            }
        }

        private static void checkDisconnect(SerialHelper serialHelper) {
            System.out.println("Disconnect from serial port");
            System.out.println("---------------------------");
            serialHelper.disconnect();
            System.out.println("done");
        }
        /**
         * Buffer to hold the reading
         */
        private byte[] readBuffer = new byte[400];
        /**
         * I/O stream for serial port
         */
        private InputStream inStream;
        private OutputStream outStream;

        public SerialHelperTester(InputStream inStream, OutputStream outStream) {
            this.inStream = inStream;
            this.outStream = outStream;
        }

        private void readSerial() {
            try {
                int availableBytes = inStream.available();
                if (availableBytes > 0) {
                    // Read the serial port
                    inStream.read(readBuffer, 0, availableBytes);

                    // Print it out
                    System.out.println("Recv :" +
                            new String(readBuffer, 0, availableBytes));
                }
            } catch (IOException e) {
            }
        }

        public void serialEvent(SerialPortEvent events) {
            switch (events.getEventType()) {
                case SerialPortEvent.DATA_AVAILABLE:
                    readSerial();
            }
        }
    }
}

This second loopback program is to test RXTX’s serial event (data available event). Note that you need serial loopback to use this source code.

import gnu.io.CommPortIdentifier;
import gnu.io.NoSuchPortException;
import gnu.io.PortInUseException;
import gnu.io.SerialPort;
import gnu.io.SerialPortEvent;
import gnu.io.SerialPortEventListener;
import gnu.io.UnsupportedCommOperationException;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.TooManyListenersException;

public class LoopbackEventTest {

    private SerialPort serialPort;
    private OutputStream outStream;
    private InputStream inStream;

    public void connect(String portName) throws IOException {
        try {
            // Obtain a CommPortIdentifier object for the port you want to open
            CommPortIdentifier portId =
                    CommPortIdentifier.getPortIdentifier(portName);

            // Get the port's ownership
            serialPort =
                    (SerialPort) portId.open("Demo application", 5000);

            // Set the parameters of the connection.
            setSerialPortParameters();

            // Open the input and output streams for the connection.
            // If they won't open, close the port before throwing an
            // exception.
            outStream = serialPort.getOutputStream();
            inStream = serialPort.getInputStream();
        } catch (NoSuchPortException e) {
            throw new IOException(e.getMessage());
        } catch (PortInUseException e) {
            throw new IOException(e.getMessage());
        } catch (IOException e) {
            serialPort.close();
            throw e;
        }
    }

    /**
     * Get the serial port input stream
     * @return The serial port input stream
     */
    public InputStream getSerialInputStream() {
        return inStream;
    }

    /**
     * Get the serial port output stream
     * @return The serial port output stream
     */
    public OutputStream getSerialOutputStream() {
        return outStream;
    }

    /**
     * Register event handler for data available event
     *
     * @param eventHandler Event handler
     */
    public void addDataAvailableEventHandler(
            SerialPortEventListener eventHandler) {
        try {
            // Add the serial port event listener
            serialPort.addEventListener(eventHandler);
            serialPort.notifyOnDataAvailable(true);
        } catch (TooManyListenersException ex) {
            System.err.println(ex.getMessage());
        }
    }

    /**
     * Disconnect the serial port
     */
    public void disconnect() {
        if (serialPort != null) {
            try {
                // close the i/o streams.
                outStream.close();
                inStream.close();
            } catch (IOException ex) {
                // don't care
                }
            // Close the port.
            serialPort.close();
        }
    }

    /**
     * Sets the serial port parameters to 57600bps-8N1
     */
    private void setSerialPortParameters() throws IOException {
        int baudRate = 57600; // 57600bps

        try {
            // Set serial port to 57600bps-8N1..my favourite
            serialPort.setSerialPortParams(
                    baudRate,
                    SerialPort.DATABITS_8,
                    SerialPort.STOPBITS_1,
                    SerialPort.PARITY_NONE);

            serialPort.setFlowControlMode(
                    SerialPort.FLOWCONTROL_NONE);
        } catch (UnsupportedCommOperationException ex) {
            throw new IOException("Unsupported serial port parameter");
        }
    }

    public static class SerialEventHandler implements SerialPortEventListener {

        private InputStream inStream;
        private int readBufferLen;
        private int readBufferOffset;
        private byte[] readBuffer;

        public SerialEventHandler(InputStream inStream, int readBufferLen) {
            this.inStream = inStream;
            this.readBufferLen = readBufferLen;
            readBuffer = new byte[readBufferLen];
        }

        public boolean isBufferFull() {
            return (readBufferOffset == readBufferLen);
        }

        public String getReadBuffer() {
            return new String(readBuffer);
        }

        public void serialEvent(SerialPortEvent event) {
            switch (event.getEventType()) {
                case SerialPortEvent.DATA_AVAILABLE:
                    readSerial();
                    break;
            }
        }

        private void readSerial() {
            try {
                int availableBytes = inStream.available();
                if (availableBytes > 0) {
                    // Read the serial port
                    readBufferOffset +=
                            inStream.read(readBuffer, readBufferOffset,
                            availableBytes);
                }
            } catch (IOException e) {
            }
        }

        public static void main(String[] args) {
            // Timeout = 1s
            final int TIMEOUT_VALUE = 10000;

            LoopbackTest loopbackTest = new LoopbackTest();
            try {
                // Open serial port
                loopbackTest.connect("/dev/ttyUSB0");

                // Register the serial event handler
                String testString = "The quick brown fox jumps over " +
                        "the lazy dog";
                InputStream inStream =
                        loopbackTest.getSerialInputStream();

                SerialEventHandler serialEventHandler =
                        new SerialEventHandler(inStream, testString.length());
                loopbackTest.addDataAvailableEventHandler(serialEventHandler);

                // Send the testing string
                OutputStream outStream =
                        loopbackTest.getSerialOutputStream();
                outStream.write(testString.getBytes());

                // Wait until all the data is received
                long startTime = System.currentTimeMillis();
                long elapsedTime;
                do {
                    try {
                        Thread.sleep(100);
                    } catch (InterruptedException ex) {
                    }
                    elapsedTime = System.currentTimeMillis() - startTime;
                } while ((elapsedTime < TIMEOUT_VALUE) &&
                        (!serialEventHandler.isBufferFull()));

                // Check the data if not TIMEOUT
                if (elapsedTime < TIMEOUT_VALUE) {
                    if (testString.equals(serialEventHandler.getReadBuffer())) {
                        System.out.println("All data is received successfully");
                    } else {
                        System.out.println("Test failed");
                        System.out.println("Sent:" + testString);
                        System.out.println("Received:" +
                                serialEventHandler.getReadBuffer());
                    }
                } else {
                    System.err.println("Timeout");
                }

                System.out.println("Test done");
                loopbackTest.disconnect();
            } catch (IOException ex) {
                System.err.println(ex.getMessage());
            }
        }
    }
}

If everything is okay, the data that’s received should be the same as the data that’s sent (“The quick brown fox jumps over the lazy dog”). If it’s jumbled than it’s not okay.

For me, using Linux 2.6 SuSE SLED 10, Java 5, and RXTX 2.1.7, everything is normal (the data is not jumbled). Please post comment if it doesn’t work for you.

One comment that I had in this site said that the RXTX library is not very reliable in the receiving part (using data available event).

I’m unsure whether it happens because of the RXTX implementation (in the application side) or RXTX library has internal bug. So, here’s some simple loopback test program to test the RXTX.

Note that you will need the RS232 loopback plug (it’s pin-3 and pin-2 are connected), like the schematic below, to use the program.

RS232 Loopback

import gnu.io.CommPortIdentifier;
import gnu.io.NoSuchPortException;
import gnu.io.PortInUseException;
import gnu.io.SerialPort;
import gnu.io.SerialPortEventListener;
import gnu.io.UnsupportedCommOperationException;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.TooManyListenersException;

/**
 * RXTX input/output reliability test
 *
 * @author kunil
 */
public class LoopbackTest {

    private SerialPort serialPort;
    private OutputStream outStream;
    private InputStream inStream;

    public void connect(String portName) throws IOException {
        try {
            // Obtain a CommPortIdentifier object for the port you want to open
            CommPortIdentifier portId =
                    CommPortIdentifier.getPortIdentifier(portName);

            // Get the port's ownership
            serialPort =
                    (SerialPort) portId.open("Demo application", 5000);

            // Set the parameters of the connection.
            setSerialPortParameters();

            // Open the input and output streams for the connection.
            // If they won't open, close the port before throwing an exception.
            outStream = serialPort.getOutputStream();
            inStream = serialPort.getInputStream();
        } catch (NoSuchPortException e) {
            throw new IOException(e.getMessage());
        } catch (PortInUseException e) {
            throw new IOException(e.getMessage());
        } catch (IOException e) {
            serialPort.close();
            throw e;
        }
    }

    /**
     * Get the serial port input stream
     * @return The serial port input stream
     */
    public InputStream getSerialInputStream() {
        return inStream;
    }

    /**
     * Get the serial port output stream
     * @return The serial port output stream
     */
    public OutputStream getSerialOutputStream() {
        return outStream;
    }

    /**
     * Register event handler for data available event
     *
     * @param eventHandler Event handler
     */
    public void addDataAvailableEventHandler(
            SerialPortEventListener eventHandler) {
        try {
            // Add the serial port event listener
            serialPort.addEventListener(eventHandler);
            serialPort.notifyOnDataAvailable(true);
        } catch (TooManyListenersException ex) {
            System.err.println(ex.getMessage());
        }
    }

    /**
     * Disconnect the serial port
     */
    public void disconnect() {
        if (serialPort != null) {
            try {
                // close the i/o streams.
                outStream.close();
                inStream.close();
            } catch (IOException ex) {
                // don't care
                }
            // Close the port.
            serialPort.close();
        }
    }

    /**
     * Sets the serial port parameters to 57600bps-8N1
     */
    private void setSerialPortParameters() throws IOException {
        int baudRate = 57600; // 57600bps

        try {
            // Set serial port to 57600bps-8N1..my favourite
            serialPort.setSerialPortParams(
                    baudRate,
                    SerialPort.DATABITS_8,
                    SerialPort.STOPBITS_1,
                    SerialPort.PARITY_NONE);

            serialPort.setFlowControlMode(
                    SerialPort.FLOWCONTROL_NONE);
        } catch (UnsupportedCommOperationException ex) {
            throw new IOException("Unsupported serial port parameter");
        }
    }

    @SuppressWarnings("empty-statement")
    public static void main(String[] args) {
        // Start the loopback testing
        String testString = "The quick brown fox jumps over the lazy dog";
        // Timeout: 1s
        final int TIMEOUT_VALUE = 1000;

        // Get the serial port
        LoopbackTest loopbackTest = new LoopbackTest();
        try {
            loopbackTest.connect("/dev/ttyUSB0");

            InputStream inStream = loopbackTest.getSerialInputStream();
            OutputStream outStream = loopbackTest.getSerialOutputStream();
            for (int i = 0; i < testString.length(); i++) {
                // Write to serial port
                outStream.write(testString.charAt(i));

                // wait until we got the loopback data
                // Dont forget the timeout
                long startTime = System.currentTimeMillis();
                long elapsedTime;
                do {
                    elapsedTime = System.currentTimeMillis() - startTime;
                } while ((elapsedTime < TIMEOUT_VALUE) &&
                        (inStream.available() == 0));

                if (elapsedTime < TIMEOUT_VALUE) {
                    // Compare the result
                    int readChar = inStream.read();
                    if (readChar != testString.charAt(i)) {
                        System.err.println("Received: " + readChar +
                                " Sent:" + testString.charAt(i));
                    }
                }
                else {
                    // Get out from the loop..
                    System.err.println("Received nothing from serial port");
                    break;
                }
            }
        } catch (IOException ex) {
            System.err.println(ex.getMessage());
        }

        System.out.println("Test done\r\n");
        loopbackTest.disconnect();
    }
}

The program will simply send 1-character and wait to receive 1-character to be compared.

The program has not tested the main issue yet (problem with data available event), but this basic test should be ok for any platform and any version of Java / RXTX. I use Linux 2.6 SUSE SLED 10, Java 6, and RXTX 2.1.7 when testing this, and it’s okay for me.

Please post a comment if it doesn’t work for you.

Changelog

20080829 – Add timeout, for case where you forget the loopback. Fix the exception.

Once you’ve got the serial InputStream, reading would be easy. Here’s an example of code to read the serial port using InputStream:

/**
 * Buffer to hold the reading
 */
private byte[] readBuffer = new byte[400];

private void readSerial() {
    try {
        int availableBytes = inStream.available();
        if (availableBytes > 0) {
            // Read the serial port
            inStream.read(readBuffer, 0, availableBytes);

            // Print it out
            System.out.println(
                    new String(readBuffer, 0, availableBytes));
        }
    } catch (IOException e) {
    }
}

But the real problem comes from the place where you should place the code.

You can put inside the SerialPortEvent.DATA_AVAILABLE: event, like this:

private class SerialEventHandler implements SerialPortEventListener {
    public void serialEvent(SerialPortEvent event) {
        switch (event.getEventType()) {
            case SerialPortEvent.DATA_AVAILABLE:
                readSerial();
                break;
        }
    }
}

Don’t forget to register the event handler, before you run the application

/**
 * Set the serial event handler
 */
private void setSerialEventHandler(SerialPort serialPort) {
    try {
        // Add the serial port event listener
        serialPort.addEventListener(new SerialEventHandler());
        serialPort.notifyOnDataAvailable(true);
    } catch (TooManyListenersException ex) {
        System.err.println(ex.getMessage());
    }
}

The result is the read procedure is only called when new data is accepted.

The other way to read the serial port data continously is by using other thread to read:

private class ReadThread implements Runnable {
    public void run() {
        while(true) {
            readSerial();
        }
    }
}

Here’s how you start the thread:

public void setSerialListener() {
    new Thread(new ReadThread()).start();
}

Conclusion

So, which one that is better, put the reading inside different thread or in the event handler ? Well..I don’t know about it yet. I’ll post it once I found the answer.

So, what do you expect from serial port event ? Most probably is the notification whether you’ve got new data in the buffer or not. But for some people (like me) who deals with real modem (I use GSM modem for server communication), we need RTS/CTS notification as well. Otherwise, we will flood the modem with data, since most PCs are faster than modem.

I’ve tested some of rxtx serial port events in Linux, and here’s some report that you might be interested.

The Theory

To handle serial port’s event, you’ll need a class that implements SerialPortEventListener. The signature for the class is like this:

class SerialListener implements SerialPortEventListener {
    public void serialEvent(SerialPortEvent event) {
        // do your event handler stuff here
    }
}

To determine which kind of serial event that you want to handle (ie. new data received in the buffer, CTS raised, parity error, etc), check the SerialPortEvent documentation. Here’s some example of how to check whether there’s new data on buffer or not:

public void serialEvent(SerialPortEvent event) {
    switch (event.getEventType()) {
        case SerialPortEvent.DATA_AVAILABLE:
            System.out.println("Data available");
            break;
        }
    }
}

After that, as usual, if you have event handler, you have to register your handler to the library. Like this:

serialPort.addEventListener(new SerialListener());

serialPort is the SerialPort’s object, while SerialListener is a class that implements SerialPortEventListener. Anyway, this event listener is a bit different, since you have to describe what kind of event that you want to handle. Like this (for example):

serialPort.notifyOnDataAvailable(true);

If you want to check other event, other than notify when data available in buffer, check out the SerialPort’s documentation here.

And that’s the end of the theory..Let’s see on what I’ve found during testing.

The Test Results

• There is no new data event notification (my mistake in testing application..sorry)
  

This is true if you use USB-serial converter, under Linux. It has been reported here, but we cannot change it since it is linux’s usbserial driver problem. If you use normal serial port (with /dev/ttyS0 or /dev/ttyS1), this event is reported.

• CTS event works like a charm

No matter if you use USB-serial or normal serial port, this event works like a charm. Here’s a code pieces to make it work:

// Enable CTS event
serialPort.notifyOnCTS(true);

..lots of code

// The CTS event handler
switch (event.getEventType()) {
    case SerialPortEvent.CTS:
        System.out.println("CTS changed");
        if (serialPort.isCTS()) {
            System.out.println("CTS asserted");
        }
        else {
            System.out.println("CTS de-asserted");
        }
        break;
    }
}

• DSR event works perfectly

I need DSR to check whether the modem is ready or not to operate. Using my testing program, I confirm that it works perfectly, using USB-serial and normal serial port.

• No OUTPUT_BUFFER_EMPTY event

The event is suppose to be fired if the outputstream buffer is empty, but it is system dependable (not available in all of the platform). Not sure about the other platform, but rxtx on Linux obviously doesn’t have this event. It would not be triggerred. Futhermore, enabling this event will make other events hang.

• DATA_AVAILABLE event works like level triggered interrupt

Simply means that this event will trigger as long as the data from serial port has not been read.

Writing to serial port is easy once you’ve got the serial port’s outputstream. Just do something like this:

String serialMessage = "AT\r\n";
OutputStream outstream = serialPort.getOutputStream();
outstream.write(serialMessage.getBytes());

Refer to my previous post for opening and getting the output stream for the serial port.

Additional Notes

From wikibooks Serial Java, comes a good advice, do not use Reader/Writer for AT command, since Reader/Writer will translate the AT command into the Unicode (your code might work as it is, or might not work if you use different Unicode than latin/ISO-8859-1 as default Unicode in the system).

Okay..I want to build an application that is nice enough to other application. So, if other application asking my port ownership, my application may give it (or not, depends on the user response).

I may also need to be notified, if I get or lose the port’s ownership. Therefore, I can do connection retry, before sending the data to serial port that I don’t own.

Hence, I’ve done some simple test on rxtx, and the result is quite suprising.

The Theory

To handle the ownership event, you’ll need a class that implements CommPortOwnershipListener. Something like this:

class SerialOwnershipHandler implements CommPortOwnershipListener
{
    public void ownershipChange(int type) {
        switch (type) {
            case CommPortOwnershipListener.PORT_OWNED:
                System.out.println("We got the port");
                break;
            case CommPortOwnershipListener.PORT_UNOWNED:
                System.out.println("We've just lost our port ownership");
                break;
            case CommPortOwnershipListener.PORT_OWNERSHIP_REQUESTED:
                System.out.println("Someone is asking our port's ownership");
                break;
        }
    }
}

After that, we need to register our event handler to CommPortIdentifier class (using CommPortIdentifier’s addPortOwnershipListener() method).

And, here’s what the class supposed to do:

• If the port has just been owned (ie. CommPortIdentifier’s open() method is called and success), the CommPortOwnershipListener.PORT_OWNED will be returned in ownershipChange(), printing “We got the port” to the stdout.
• If the port has just been released (ie. SerialPort’s close() method is called), the CommPortOwnershipListener.PORT_UNOWNED will be returned in ownershipChange(), printing “We’ve just lost our port ownership” to the stdout.
• If other application asks our port’s ownership, the CommPortOwnershipListener.PORT_OWNERSHIP_REQUESTED will be returned in ownershipChange(), printing “Someone is asking our port’s ownership” to the stdout.

The Test Result

• CORRECT: If the port has just been owned (ie. CommPortIdentifier’s open() method is called and success), the CommPortOwnershipListener.PORT_OWNED will be returned in ownershipChange(), printing “We got the port” to the stdout.
• CORRECT: If the port has just been released (ie. SerialPort’s close() method is called), the CommPortOwnershipListener.PORT_UNOWNED will be returned in ownershipChange(), printing “We’ve just lost our port ownership” to the stdout.
• FALSE: If other application asks our port’s ownership, the CommPortOwnershipListener.PORT_OWNERSHIP_REQUESTED will be returned in ownershipChange(), printing “Someone is asking our port’s ownership” to the stdout.

For the last case, where other application is run after rxtx get the ownership, I’ve tried using GNU screen (screen /dev/ttyUSB0 57600) and other rxtx application demo. I couldn’t generate the third case at all.

After several trial, I found out that the last case can only be done, if the CommPortIdentifier’s open() method is called more than once in the SAME application (same process ID..even other java program with rxtx cannot generate the last case because it used different process ID).

In case someone interested in the test program that I use, here’s the source code

public class SerialOwnership {

    private SerialPort serialPort;
    private OutputStream outStream;
    private InputStream inStream;

    public void connect(String portName, String id) throws IOException {
        try {
            // Obtain a CommPortIdentifier object for the port you want to open
            CommPortIdentifier portId =
                    CommPortIdentifier.getPortIdentifier(portName);

            // Add ownership event listener
            portId.addPortOwnershipListener(new SerialOwnershipHandler(id));

            // Get the port's ownership
            serialPort =
                    (SerialPort) portId.open("Demo application", 5000);

            // Set the parameters of the connection.
            setSerialPortParameters();

            // Open the input and output streams for the connection. If they won't
            // open, close the port before throwing an exception.
            outStream = serialPort.getOutputStream();
            inStream = serialPort.getInputStream();
        } catch (NoSuchPortException e) {
            throw new IOException(e.getMessage());
        } catch (PortInUseException e) {
            throw new IOException(e.getMessage());
        } catch (IOException e) {
            serialPort.close();
            throw e;
        }
    }

    /**
     * Get the serial port input stream
     * @return The serial port input stream
     */
    public InputStream getSerialInputStream() {
        return inStream;
    }

    /**
     * Get the serial port output stream
     * @return The serial port output stream
     */
    public OutputStream getSerialOutputStream() {
        return outStream;
    }

    public void disconnect() {
        if (serialPort != null) {
            try {
                // close the i/o streams.
                outStream.close();
                inStream.close();
            } catch (IOException ex) {
                // don't care
            }
            // Close the port.
            serialPort.close();
        }
    }

    /**
     * Sets the serial port parameters
     */
    private void setSerialPortParameters() throws IOException {
        int baudRate = 57600; // 57600bps

        try {
            // Set serial port to 57600bps-8N1..my favourite
            serialPort.setSerialPortParams(
                    baudRate,
                    SerialPort.DATABITS_8,
                    SerialPort.STOPBITS_1,
                    SerialPort.PARITY_NONE);

            serialPort.setFlowControlMode(
                    SerialPort.FLOWCONTROL_NONE);
        } catch (UnsupportedCommOperationException ex) {
            throw new IOException("Unsupported serial port parameter");
        }
    }

    private class SerialOwnershipHandler implements CommPortOwnershipListener
    {
        String id;

        public SerialOwnershipHandler(String id) {
            this.id = id;
        }

        public void ownershipChange(int type) {
            switch (type) {
                case CommPortOwnershipListener.PORT_OWNED:
                    System.out.println(id +
                            ":We got the port");
                    break;
                case CommPortOwnershipListener.PORT_UNOWNED:
                    System.out.println(id +
                            ":We've just lost our port ownership");
                    break;
                case CommPortOwnershipListener.PORT_OWNERSHIP_REQUESTED:
                    System.out.println(id +
                            ":Someone is asking our port's ownership");
                    break;
            }
        }
    }

    public static void main(String[] args) {
        SerialOwnership serialOwnershipTest = new SerialOwnership();

        try {
            serialOwnershipTest.connect("/dev/ttyUSB0", "1");
            Thread.sleep(10000);

            // Uncomment this to generate the third case
            //new SerialOwnership().connect("/dev/ttyUSB0", "2");
            Thread.sleep(10000);
        } catch (InterruptedException ex) {
        } catch (IOException ex) {
            System.err.println(ex.getMessage());
        }

        serialOwnershipTest.disconnect();
    }
}

This test is run on Linux Suse Enterprise Desktop 10 (kernel 2.6.16), Sun Java 1.6.0, and Rxtx 2.1.7

Well, you’ve opened the port. But how do you clean up your mess once you’ve done with the serial port ?

Here’s some hints to clean up your serial port mess

    public void disconnect() {
        if (serialPort != null) {
            try {
                // close the i/o streams.
                outStream.close();
                inStream.close();
            } catch (IOException ex) {
                // don't care
            }
            // Close the port.
            serialPort.close();
        }
    }

Ok. So here’s a brief explanation of how to open serial port in Java using rxtx.

First of all, you need to get the serial port’s ID

CommPortIdentifier portId =
  CommPortIdentifier.getPortIdentifier("/dev/ttyUSB0");

Then, you’ll need to ask the OS to give the serial port ownership to you.

SerialPort serialPort =
  (SerialPort) portId.open("Demo application", 5000);

The “Demo application” string is the application’s name. The rxtx will pass this value to OS as the application name who ask the serial port ownership (I think there’s some Unix command to view which application hold which system resource..I need to dig more on this use lsof /dev/<your serial device> to see which application that holds it. But I should remind you that “Demo application” string won’t come up using lsof or ps -ax).

The 5000 value is the timeout value that is given to the system to release the port (5000 ms = 5 seconds). If the current owner of the serial port doesn’t release the serial port within 5 seconds, rxtx will throw an IOException.

If you’re lucky (the current serial port owner willing to give the serial port to you, or nobody owns it currently), you can set the serial port parameters.

int baudRate = 57600; // 57600bps
try {
  // Set serial port to 57600bps-8N1..my favourite
  serialPort.setSerialPortParams(
    baudRate,
    SerialPort.DATABITS_8,
    SerialPort.STOPBITS_1,
    SerialPort.PARITY_NONE);
} catch (UnsupportedCommOperationException ex) {
  System.err.println(ex.getMessage());
}

Don’t forget to set its flow control

try {
  serialPort.setFlowControlMode(
        SerialPort.FLOWCONTROL_NONE);
  // OR
  // If CTS/RTS is needed
  //serialPort.setFlowControlMode(
  //      SerialPort.FLOWCONTROL_RTSCTS_IN |
  //      SerialPort.FLOWCONTROL_RTSCTS_OUT);
} catch (UnsupportedCommOperationException ex) {
  System.err.println(ex.getMessage());
}

Lastly, before you can read or write to serial port. You’ll need its inputstream and outputstream.

OutputStream outStream = serialPort.getOutputStream();
InputStream inStream = serialPort.getInputStream();

So, here’s the complete example of the method to open the serial port

public class SerialPortHandler {
    private SerialPort serialPort;
    private OutputStream outStream;
    private InputStream inStream;

    public void connect(String portName) throws IOException {
        try {
            // Obtain a CommPortIdentifier object for the port you want to open
            CommPortIdentifier portId =
                    CommPortIdentifier.getPortIdentifier(portName);

            // Get the port's ownership
            serialPort =
                    (SerialPort) portId.open("Demo application", 5000);

            // Set the parameters of the connection.
            setSerialPortParameters();

            // Open the input and output streams for the connection. If they won't
            // open, close the port before throwing an exception.
            outStream = serialPort.getOutputStream();
            inStream = serialPort.getInputStream();
        } catch (NoSuchPortException e) {
            throw new IOException(e.getMessage());
        } catch (PortInUseException e) {
            throw new IOException(e.getMessage());
        } catch (IOException e) {
            serialPort.close();
            throw e;
        }
    }

    /**
     * Get the serial port input stream
     * @return The serial port input stream
     */
    public InputStream getSerialInputStream() {
        return inStream;
    }

    /**
     * Get the serial port output stream
     * @return The serial port output stream
     */
    public OutputStream getSerialOutputStream() {
        return outStream;
    }

    /**
     * Sets the serial port parameters
     */
    private void setSerialPortParameters() throws IOException {
        int baudRate = 57600; // 57600bps

        try {
            // Set serial port to 57600bps-8N1..my favourite
            serialPort.setSerialPortParams(
                    baudRate,
                    SerialPort.DATABITS_8,
                    SerialPort.STOPBITS_1,
                    SerialPort.PARITY_NONE);

            serialPort.setFlowControlMode(
                    SerialPort.FLOWCONTROL_NONE);
        } catch (UnsupportedCommOperationException ex) {
            throw new IOException("Unsupported serial port parameter");
        }
    }
}

Sometimes, it is very annoying to know that you just cannot install your Rxtx library in the JAVA_HOME (lack of admin privilege, you don’t want to clutter your JAVA_HOME with trashes, you need easy uninstallation, etc).

So, I’ve looked around in JNI usage, and I found a way to handle this problem.

1. Put your Rxtx library (RXTXcomm.jar, librxtxParallel.so, librxtxSerial.so) in the local project directory.
2. Run your project with this argument: -Djava.library.path=<your local Rxtx project directory>

If you use Netbeans, you can add the argument in: Project Properties -> Run -> VM Options

Netbeans Project Properties