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:

• Platform-independent library deployment (automatically uses correct native library based on current architecture)
• Very lightweight and efficient implementation
• Enumerates all available serial ports on a machine
• Returns both a system port description and a friendly device description
• User-specifiable port descriptors including symbolic links
• Configurable ports according to baud rate, data bits, stop bits, and parity
• Configurable port timeouts (blocking and non-blocking) for both reading and writing
• Configurable flow control parameters for the serial port (CTS, RTS/CTS, DSR, DTR/DSR, XOn/XOff)
• Ability to read and write raw data bytes directly to the serial port
• Ability to read and write byte streams via Java's InputStream and OutputStream interfaces
• Event-based reading and writing via callbacks
• Callback notification when:
• New data is available for reading
• All data has been successfully written
• A complete fixed-length data packet has arrived
• A delimited string-based message has been received
• Modem control lines have changed state
• Communication errors have been encountered

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

• Windows XP and later (32-bit, 64-bit, ARM, and ARM64)
• Mac OS X Tiger (10.4) and later (32/64-bit Intel and Apple Silicon)
• All Linux distributions (32/64-bit x86, ARM, and PowerPC)
• Solaris 10 and later (32/64-bit x86 and SPARC)
• FreeBSD (32/64-bit x86 and ARM64)
• OpenBSD (32/64-bit x86)
• ARM/Intel/AMD Mobile Linux derivatives (e.g. RaspberryPi, Beaglebone, etc.)
• Android 4.1 (Jelly Bean) and later

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>[2.0.0,3.0.0)</version>
</dependency>

<dependency org="com.fazecast" name="jSerialComm" rev="[2.0.0,3.0.0)"/>

@Grab(group='com.fazecast', module='jSerialComm', version='[2.0.0,3.0.0)')

compile 'com.fazecast:jSerialComm:[2.0.0,3.0.0)'

compile.with 'com.fazecast:jSerialComm:jar:[2.0.0,3.0.0)'

libraryDependencies += "com.fazecast" % "jSerialComm" % "[2.0.0,3.0.0)"

[com.fazecast/jSerialComm "[2.0.0,3.0.0)"]

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.