A platform-independent serial port access library for Java.
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.
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 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.
