138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# jSerialComm
|
|
|
|
_A platform-independent serial port access library for Java._
|
|
|
|
|
|
## Usage
|
|
|
|
For usage examples, please refer to the [Usage wiki](https://github.com/Fazecast/jSerialComm/wiki/Usage-Examples).
|
|
|
|
If you intend to use the library in multiple applications simultaneously, please make sure
|
|
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:
|
|
```
|
|
System.setProperty("fazecast.jSerialComm.appid", "YOUR_APPLICATION_IDENTIFIER")
|
|
```
|
|
|
|
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.*;```.
|
|
|
|
Alternatively, 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)"]
|
|
```
|
|
|
|
|
|
## 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](https://github.com/Fazecast/jSerialComm/wiki/Troubleshooting).
|
|
|
|
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``,
|
|
``armv6-hf``, ``armv7``, ``armv7-hf``, ``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](https://github.com/Fazecast/jSerialComm/wiki/Usage-Examples)
|
|
or the [Troubleshooting Wiki](https://github.com/Fazecast/jSerialComm/wiki/Troubleshooting).
|
|
|
|
If your question is still not answered, feel free to open an issue report on
|
|
this project's [GitHub page](https://github.com/Fazecast/jSerialComm/issues),
|
|
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](#usage)
|
|
section.
|
|
|
|
If you do choose to build this library for your specific system, please follow
|
|
the instructions in the [Building Tutorial](https://github.com/Fazecast/jSerialComm/wiki/Building-Tutorial)
|
|
to set up the required native cross-compilation toolchains.
|