Merge pull request #99 from Awarepoint/master

Fix compiler warnings and improve documentation
This commit is contained in:
Will Hedgecock 2018-01-03 18:34:43 -06:00 committed by GitHub
commit c75e8d731b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 273 additions and 199 deletions

14
AUTHORS
View File

@ -1,14 +0,0 @@
Maintainer
----------
Will Hedgecock <will.hedgecock@fazecast.com>
Original Authors
----------------
Will Hedgecock <will.hedgecock@fazecast.com>
Contributors
------------
Will Hedgecock <will.hedgecock@fazecast.com>
Frederik Schubert <https://github.com/frederikschubert>
Farrell Farahbod <https://github.com/farrellf>
Michael Kaesbauer <https://github.com/Michael-Kaesbauer>

14
AUTHORS.md Normal file
View File

@ -0,0 +1,14 @@
# Maintainer
Will Hedgecock <will.hedgecock@fazecast.com>
# Original Authors
Will Hedgecock <will.hedgecock@fazecast.com>
# Contributors
* Will Hedgecock <will.hedgecock@fazecast.com>
* Frederik Schubert <https://github.com/frederikschubert>
* Farrell Farahbod <https://github.com/farrellf>
* Michael Kaesbauer <https://github.com/Michael-Kaesbauer>

151
INSTALL
View File

@ -1,151 +0,0 @@
----------
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 ahead to the "USAGE" section.
If you do choose to build this library for your specific system, the recommended methodology is to use Gradle coupled with the Java SDK, version 1.6 (for backward compatibility).
Java SDK 1.6 can be downloaded from http://www.oracle.com/technetwork/java/archive-139210.html
Gradle can be downloaded from https://gradle.org/
Once the Java SDK 1.6 has been installed, ensure that you have an environment variable called JDK_HOME set to the base directory of your JDK installation. Once this has been done, refer to the section corresponding to your specific Operating System for further instructions.
Please note, if you would like to edit any of the source code or view it in an IDE (such as Eclipse), you can automatically build the Eclipse project files by entering the following on a command line or terminal from the base directory of this project (.../jSerialComm/): gradle eclipse
You can then Import the project using the "Existing Project into Workspace" import tool in Eclipse. (Note that if you use Eclipse as an IDE, you will probably want to install the Eclipse CDT plugin for proper handling of the C source code)
------------
LINUX/UNIX
------------
Ensure that the following tools are installed on your Linux distribution: gcc make glibc-devel.x86_64 glibc-devel.i686 (on some distros, these may be called multilib tools for gcc and binutils)
Ensure that the JDK_HOME environment variable has been set for the 1.6 version of your Java SDK. The correct directory can usually be found by entering the following command: readlink -f /usr/bin/java
Export the result of this command UP TO BUT NOT INCLUDING the /jre/... portion using the 'export' command. For example, if 'readlink' produced "/usr/lib/jvm/java-6-jdk/jre/bin/java" as an output, the export command would look like: export JDK_HOME=/usr/lib/jvm/java-6-jdk
Change directories to the following project directory: ".../jSerialComm/src/main/c/Linux/"
Run the following commands in order:
make
cd ../../../..
gradle build
The resulting jSerialComm library can be found in the project directory ".../jSerialComm/build/libs/" under the name "jSerialComm-{VERSION}.jar"
--------------------------------------
ARM-BASED MOBILE LINUX (NON-ANDROID)
--------------------------------------
Ensure that you have a cross-compiler installed on your Linux distribution capable of compiling for ARM-based architectures. I prefer crosstool-ng for this purpose.
Ensure that the JDK_HOME environment variable has been set for the 1.6 version of your Java SDK. The correct directory can usually be found by entering the following command: readlink -f /usr/bin/java
Export the result of this command UP TO BUT NOT INCLUDING the /jre/... portion using the 'export' command. For example, if 'readlink' produced "/usr/lib/jvm/java-6-jdk/jre/bin/java" as an output, the export command would look like: export JDK_HOME=/usr/lib/jvm/java-6-jdk
Change directories to the following project directory: ".../jSerialComm/src/main/c/Linux/"
Run the following commands in order:
make arm
cd ../../../..
gradle build
The resulting jSerialComm library can be found in the project directory ".../jSerialComm/build/libs/" under the name "jSerialComm-{VERSION}.jar"
---------
ANDROID
---------
Ensure that the Android NDK is installed on your system. For purposes of these instructions, assume that it is installed at {NDK_HOME}.
Change directories to the following project directory: ".../jSerialComm/src/main/c/Android/"
Run the following commands in order:
{NDK_HOME}/ndk-build
cd ../../../..
gradle build
The resulting jSerialComm library can be found in the project directory ".../jSerialComm/build/libs/" under the name "jSerialComm-{VERSION}.jar"
----------
MAC OS X
----------
Ensure that Xcode is installed on your system. If it is not, it can be downloaded via the App Store. You must also make sure that the Xcode Command Line Tools are installed. This can be done by entering the following command in a terminal: xcode-select --install
Change directories to the following project directory: ".../jSerialComm/src/main/c/OSX/"
Run the following commands in order:
make
cd ../../../..
gradle build
The resulting jSerialComm library can be found in the project directory ".../jSerialComm/build/libs/" under the name "jSerialComm-{VERSION}.jar"
---------
WINDOWS
---------
Ensure that the Visual Studio C++ Compiler is installed on your system. If it is not, you can download a free version (Visual C++ 2010 Express) from https://www.visualstudio.com/downloads/download-visual-studio-vs.
Open up a command prompt (Run->'cmd') and change to the following project directory: "...\jSerialComm\src\main\c\Windows\"
On Windows, the Visual Studio Compiler must be configured to build either 32- or 64-bit binaries but never both at the same time. Therefore, you will have to build binaries for the two architectures separately.
For the following commands, {VC_DIRECTORY} is the installation directory of your Visual Studio C++ Compiler (for example: C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC). Run the following commands in order:
{VC_DIRECTORY}\vcvarsall.bat x64
nmake win64
{VC_DIRECTORY}\vcvarsall.bat x86
nmake win32
cd ..\..\..\..
gradle build
The resulting jSerialComm library can be found in the project directory "...\jSerialComm\build\libs\" under the name "jSerialComm-{VERSION}.jar"
-------
USAGE
-------
In order to use the jSerialComm library in your own project, you must simply include the jSerialComm 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)'
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)"]

22
README
View File

@ -1,22 +0,0 @@
------------------------------------------------------------
jSerialComm
------------
A platform-independent serial port access library for Java
------------------------------------------------------------
For building and/or installation instructions, please refer to the INSTALL file
For usage examples, please refer to the Usage Wiki at https://github.com/Fazecast/jSerialComm/wiki/Usage-Examples
-----------------
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 at https://github.com/Fazecast/jSerialComm/wiki/Troubleshooting.
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 Wiki at https://github.com/Fazecast/jSerialComm/wiki/Usage-Examples or the Troubleshooting Wiki at 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.

241
README.md Normal file
View File

@ -0,0 +1,241 @@
# 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).
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)'
```
* 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).
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, the recommended
methodology is to use [Gradle](https://gradle.org/) coupled with the
Java SDK, [version 1.6](http://www.oracle.com/technetwork/java/archive-139210.html)
(for backward compatibility).
Once the Java SDK 1.6 has been installed, ensure that you have an environment
variable called ```JDK_HOME``` set to the base directory of your JDK installation.
Once this has been done, refer to the section corresponding to your specific
Operating System for further instructions.
Please note, if you would like to edit any of the source code or view it in an
IDE (such as Eclipse), you can automatically build the Eclipse project files by
entering the following on a command line or terminal from the base directory of
this project:
gradle eclipse
You can then Import the project using the "Existing Project into Workspace" import
tool in Eclipse. (Note that if you use Eclipse as an IDE, you will probably want
to install the Eclipse CDT plugin for proper handling of the C source code).
### Linux/UNIX
Ensure that the following tools are installed on your Linux distribution:
# On some distros, these may be called multilib tools for gcc and binutils
gcc make glibc-devel.x86_64 glibc-devel.i686
Ensure that the ```JDK_HOME``` environment variable has been set for the 1.6
version of your Java SDK. The correct directory can usually be found by entering
the following command:
readlink -f /usr/bin/java
Export the result of this command ***up to but not including*** the
```/jre/...``` portion using the ```export``` command. For example, if
```readlink``` produced ```/usr/lib/jvm/java-6-jdk/jre/bin/java``` as an output,
the export command would look like: ```export JDK_HOME=/usr/lib/jvm/java-6-jdk```
Run the following commands:
cd src/main/c/Linux
make
cd ../../../..
gradle build
The resulting ```jSerialComm``` library can be found in the project directory
```build/libs``` under the name ```jSerialComm-{VERSION}.jar```.
### ARM-Based Mobile Linux (non-Android)
Ensure that you have a cross-compiler installed on your Linux distribution
capable of compiling for ARM-based architectures. I prefer ```crosstool-ng```
for this purpose.
Ensure that the ```JDK_HOME``` environment variable has been set for the 1.6
version of your Java SDK. The correct directory can usually be found by entering
the following command:
readlink -f /usr/bin/java
Export the result of this command ***up to but not including*** the
```/jre/...``` portion using the ```export``` command. For example, if
```readlink``` produced ```/usr/lib/jvm/java-6-jdk/jre/bin/java``` as an output,
the export command would look like: ```export JDK_HOME=/usr/lib/jvm/java-6-jdk```
Run the following commands:
cd src/main/c/Linux
make arm
cd ../../../..
gradle build
The resulting ```jSerialComm``` library can be found in the project directory
```build/libs``` under the name ```jSerialComm-{VERSION}.jar```.
### Android
Ensure that the Android NDK is installed on your system. For purposes of these
instructions, assume that it is installed at ```{NDK_HOME}```.
Run the following commands in order:
cd src/main/c/Android
{NDK_HOME}/ndk-build
cd ../../../..
gradle build
The resulting ```jSerialComm``` library can be found in the project directory
```build/libs``` under the name ```jSerialComm-{VERSION}.jar```
### macOS X
Ensure that [Xcode](https://developer.apple.com/xcode/) is installed on your system.
If it is not, it can be downloaded via the App Store. You must also make sure
that the ```Xcode Command Line Tools``` are installed. This can be done by
entering the following command in a terminal: ```xcode-select --install```
Run the following commands in order:
cd src/main/c/OSX
make
cd ../../../..
gradle build
The resulting ```jSerialComm``` library can be found in the project directory
```build/libs``` under the name ```jSerialComm-{VERSION}.jar```
### Windows
Ensure that the [Visual Studio C++ Compiler](https://www.visualstudio.com/) is
installed on your system.
On Windows, the Visual Studio Compiler must be configured to build either
32- or 64-bit binaries but never both at the same time. Therefore, you will have
to build binaries for the two architectures separately.
Open a command prompt and run the following command:
SET VC_DIRECTORY="C:\Program Files (x86)\Microsoft Visual Studio [version]\VC"
where ```[version]``` matches the version of the ```Visual Studio C++ Compiler```
that is installed.
Then run:
PUSHD src\main\c\Windows
%VC_DIRECTORY%\vcvarsall.bat x64
nmake win64
%VC_DIRECTORY%\vcvarsall.bat x86
nmake win32
POPD
gradle build
The resulting ```jSerialComm``` library can be found in the project directory
```build/libs``` under the name ```jSerialComm-{VERSION}.jar```

View File

@ -35,12 +35,12 @@ JAVA_CLASS = $(JAVA_CLASS_DIR)\SerialPort.class
all :
$(PRINT).
$(PRINT) Must specify a target (either win32 or win64), but not both at the same time since different versions of the Microsoft Compiler are required for difference architectures.
$(PRINT).
$(PRINT).
$(PRINT) NOTE: Before attempting to use this Makefile, make sure that you have called 'vcvarsall.bat' for your intended architecture. This file can normally be found in "C:\Program Files (x86)\Microsoft Visual Studio [version]\VC\".
$(PRINT).
$(PRINT) Example: To build 64-bit Windows libraries, you would call:
$(PRINT) C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat x64
$(PRINT) nmake
$(PRINT) nmake win64
$(PRINT).
# Builds 32-bit Windows libraries
@ -71,7 +71,7 @@ $(BUILD_DIR)\x86\$(LIBRARY_NAME) : $(JNI_HEADER) $(OBJECTSx86)
# Rule to build 64-bit library
$(BUILD_DIR)\x86_64\$(LIBRARY_NAME) : $(JNI_HEADER) $(OBJECTSx86_64)
$(LINK) $(LDFLAGS) /MACHINE:X64 /OUT:$@ $(OBJECTSx86_64) $(LIBRARIES)
# Suffix rules to get from *.c -> *.obj
$(OBJECTSx86_64) :
$(COMPILE) $(CFLAGS) $(INCLUDES) $(*B).c -Fo$@

View File

@ -385,7 +385,7 @@ public final class SerialPort
try { Thread.sleep(500); } catch (InterruptedException e) { return false; }
}
}
if ((portHandle = openPortNative()) > 0)
{
inputStream = new SerialPortInputStream();
@ -395,7 +395,7 @@ public final class SerialPort
}
return isOpened;
}
/**
* Opens this serial port for reading and writing.
* <p>
@ -464,7 +464,7 @@ public final class SerialPort
* @return The number of bytes currently available to be read, or -1 if the port is not open.
*/
public final int bytesAvailable() { return bytesAvailable(portHandle); }
/**
* Returns the number of bytes still waiting to be written in the device's output queue.
* <p>
@ -506,33 +506,39 @@ public final class SerialPort
/**
* Sets the BREAK signal on the serial control line.
* @return true if successful, false if not.
*/
public final void setBreak() { setBreak(portHandle); }
public final boolean setBreak() { return setBreak(portHandle); }
/**
* Clears the BREAK signal from the serial control line.
* @return true if successful, false if not.
*/
public final void clearBreak() { clearBreak(portHandle); }
public final boolean clearBreak() { return clearBreak(portHandle); }
/**
* Sets the state of the RTS line to 1.
* @return true if successful, false if not.
*/
public final void setRTS() { setRTS(portHandle); }
public final boolean setRTS() { return setRTS(portHandle); }
/**
* Clears the state of the RTS line to 0.
* @return true if successful, false if not.
*/
public final void clearRTS() { clearRTS(portHandle); }
public final boolean clearRTS() { return clearRTS(portHandle); }
/**
* Sets the state of the DTR line to 1.
* @return true if successful, false if not.
*/
public final void setDTR() { setDTR(portHandle); }
public final boolean setDTR() { return setDTR(portHandle); }
/**
* Clears the state of the DTR line to 0.
* @return true if successful, false if not.
*/
public final void clearDTR() { clearDTR(portHandle); }
public final boolean clearDTR() { return clearDTR(portHandle); }
// Default Constructor
private SerialPort() {}