Installation

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, or you can include it as a dependency using a package/build manager like Gradle or Maven.

Alternately, if you are working on a high-security device that does not allow extracting or executing files from your system-wide temporary or personal home directory, you can specify a different directory to use for native file extraction by adding the following flag to your Java startup command: -Djava.io.tmpdir="<DESIRED_TMPDIR_HERE>". Finally, if your device 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 more difficult and error-prone.

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 files under 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.

---

Usage with a Terminal-Built Java Application

If you are looking to use jSerialComm with a simple command-line Java application, this can be achieved through the following steps:

1. Copy jSerialComm-X.X.X.jar into the same directory as your main Java source code file, where X.X.X refers to the current version of the jSerialComm library.
2. Assuming your main Java source file is named Main.java, compile your Java application using the following command: javac -cp ".:./jSerialComm-X.X.X.jar" Main.java
3. Run the compiled application using: java -cp ".:./jSerialComm-X.X.X.jar" Main

---

Import Using an Automated Build System

Instead of manually copying the jSerialComm.jar file into your own project, you can automatically add it as a dependency from the Maven Central Repository. Use one of the following dependency declarations depending on the build system you are using:

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)"/>

Grape

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

Gradle

'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)'

SBT

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

Leiningen

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