View on GitHub jSerialComm

Platform-independent serial port access for Java

Download this project as a .zip file Download this project as a tar.gz file Download this library as a .jar file

What is jSerialComm?

jSerialComm is a Java library designed to provide a platform-independent way to access standard serial ports without requiring external libraries, native code, or any other tools. It is meant as an alternative to RxTx and the (deprecated) Java Communications API, with increased ease-of-use, an enhanced support for timeouts, and the ability to open multiple ports simultaneously.

Some of the features of this library include:

Additionally, this library can be used in any Java project intended for use on the following platforms:

How can use this library in my own project?

One of the most convenient features of this library is that it allows you to simply include the JAR file in your custom project, and it will automatically select and load the correct native library for your platform and architecture. As such, you can make use of this library by simply copying the jSerialComm.jar file into your project directory and linking to it as you would any other JAR file.

To access the contents of the library in your project, make sure to import com.fazecast.jSerialComm.* into your java files. You can then generate a list of all available serial ports on your system (real or virtual), by calling the following static method:

SerialPort.getCommPorts()

This will return an array of SerialPort objects through which you can iterate. See the Javadoc Library Reference for a complete overview of this library and its methods. Alternately, if you already know the port descriptor of the port you wish to use (e.g., "/dev/ttyS0" or "COM3"), or if you are using this library with pseudo-terminals (e.g., "/dev/pts/14"), you can create a SerialPort object using the following static method:

SerialPort.getCommPort(String portDescriptor)

Note for Linux users: Serial port access is limited to certain users and groups in Linux. To enable user access, you must open a terminal and enter the following commands before jSerialComm will be able to access the ports on your system. Don't worry if some of the commands fail. All of these groups may not exist on every Linux distro. (Note, this process must only be done once for each user):

sudo usermod -a -G uucp username
sudo usermod -a -G dialout username
sudo usermod -a -G lock username
sudo usermod -a -G tty username

Replace the username parameter with your current username. (If you are not sure what your username is, type whoami and it will tell you.) If you are using SUSE 11.3 or higher, replace the '-a -G' flags with a single '-A' flag. Log out and you should have access to the serial port after logging back in.

Additionally, if you are using an automated build system (such as Maven), you can import this library directly into your project as a dependency from the Maven Central Repository instead of copying the .jar file manually. Use one of the following dependency declarations depending on the build system you are using:

<dependency>
   <groupId>com.fazecast</groupId>
   <artifactId>jSerialComm</artifactId>
   <version>1.3.11</version>
</dependency>
<dependency org="com.fazecast" name="jSerialComm" rev="1.3.11"/>
@Grab(group='com.fazecast', module='jSerialComm', version='1.3.11')
compile 'com.fazecast:jSerialComm:1.3.11'
compile.with 'com.fazecast:jSerialComm:jar:1.3.11'
libraryDependencies += "com.fazecast" % "jSerialComm" % "1.3.11"
[com.fazecast/jSerialComm "1.3.11"]

Are there any usage examples?

Although this library was designed to be as simple and flexible as possible, you can enable a number of different modes of operation via manipulation of the serial port timeout values and the interface through which you choose to access the serial port.

For a description of the various modes of operation available in this library, please refer to the Modes of Operation wiki article. For code-based examples of how to use this library in your own project, we provide a Usage Examples wiki.

Finally, you can view the API Documentation for further information on how to use this library.

Authors and Contributors

This library was created and developed by Will Hedgecock (@willhedgecock) of Fazecast, Inc. (@fazecast)

Support or Contact

Having trouble with this library? Check out the documentation or open an issue report and we’ll help you sort it out.