jSerialComm

A platform-independent serial port access library for Java.

Usage

For usage examples, please refer to the Usage wiki.

If you intend to use the library in multiple applications simultaneously, you may need to set the fazecast.jSerialComm.appid property before accessing the SerialPort class so that applications don't accidentally delete each others' temporary files during boot-up (this should almost never be necessary):

System.setProperty("fazecast.jSerialComm.appid", "YOUR_APPLICATION_IDENTIFIER")

Alternately, if you plan to use the library within an Apache Tomcat application, please set the jSerialComm.library.randomizeNativeName property to true before accessing the SerialPort class to address an issue whereby the Tomcat bootloader tries to reinitialize the library multiple times. This can either be done using -DjSerialComm.library.randomizeNativeName="true" as a command line parameter or by calling the following within your own application before using any SerialPort functionality:

System.setProperty("jSerialComm.library.randomizeNativeName", "true")

In order to use the jSerialComm library in your own project, you must simply include the JAR file in your build path and import it like any other Java package using import com.fazecast.jSerialComm.*;.

Alternately, you can automatically add jSerialComm to your project as a dependency from the Maven Central Repository. Use the following dependency declaration depending on your build system:

• Maven:

<dependency>
  <groupId>com.fazecast</groupId>
  <artifactId>jSerialComm</artifactId>
  <version>[2.0.0,3.0.0)</version>
</dependency>

• Ivy:

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

• Groovy:

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

• Gradle:

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

• Gradle (.kts):

compile("com.fazecast:jSerialComm:[2.0.0,3.0.0)")

• Buildr:

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

• Scala/SBT:

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

• Leiningen:

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

Finally, if you are working on a device that provides no other means of allowing temporary native files to run, jSerialComm supports loading a pre-extracted version of its native library from a user-defined location using the startup flag: -DjSerialComm.library.path="<LIB_PATH>", where LIB_PATH can either be a directory containing the single native jSerialComm library for your correct architecture or the entire extracted arch-specific directory structure from inside the jSerialComm JAR file; however, this should be used as a last resort as it makes versioning and upgrading much more difficult and error-prone.

Troubleshooting

If you are using Linux and this library does not appear to be working, ensure that you have the correct permissions set to access the serial port on your system. One way to test this is to run your application as root or by using the sudo command. If everything works, you will need to either run your application as root in the future or fix the permissions on your system. For further instructions, refer to the Troubleshooting wiki.

On some very few systems which use custom ARM-based CPUs and/or have extremely restrictive permissions, the library may be unable to determine that the underlying system architecture is ARM. In this case, you can force the library to disable its auto-detect functionality and instead directly specify the architecture using the Java os.arch_full system property. Acceptable values for this property are currently one of: armv5, armv6, armv7, armv8_32, armv8_64, ppc64le, x86, or x86_64.

Additionally, some systems may block execution of libraries from the system temp folder. If you are experiencing this problem, you can specify a different, less restrictive temp folder by adding System.setProperty("java.io.tmpdir", "/folder/where/execution/is/allowed") to your program before the first use of this library. When doing this, make sure that the folder you specify already exists and has the correct permissions set to allow execution of a shared library.

Optionally, the same result can be achieved by running your Java application from the command line and specifying the java.io.tmpdir directory as an additional parameter, e.g.: java -Djava.io.tmpdir=/folder/of/your/choice -jar yourApplication.jar

On Windows, you may be able to achieve the same result by setting the TMP environment variable (either through the Settings->System Properties->Environment Variables GUI or via SET TMP=C:\Desired\Tmp\Folder in a command terminal), although setting this variable through Java is preferable when possible.

An additional note for Linux users: If you are operating this library in event-based mode, the LISTENING_EVENT_DATA_WRITTEN event will never occur. This is not a bug, but rather a limitation of the Linux operating system.

For other troubleshooting issues, please see if you can find an answer in either the Usage-Examples wiki or the Troubleshooting Wiki.

If your question is still not answered, feel free to open an issue report on this project's GitHub page, and we will be glad to look into it.

Building

Building this library yourself is not advised (at least not for distribution) since it requires native compilation across multiple platforms. It is recommended to simply use the pre-built jSerialComm library in your application. For installation/usage instructions, please skip to the usage section.

If you do choose to build this library from source, please follow the instructions in the Building Tutorial to set up the required toolchains.