From 4c7f206f93818ff0de27996b412d61c8c0ff208e Mon Sep 17 00:00:00 2001 From: Josh Lubawy Date: Wed, 3 Jan 2018 14:50:22 -0800 Subject: [PATCH] Fix compiler warnings and improve documentation * Was getting compiler warnings for void return type not matching the expected boolean. * Converted README and AUTHORS text files to use Markdown. * Moved the contents of INSTALL into the README.md file. --- AUTHORS | 14 - AUTHORS.md | 14 + INSTALL | 151 ----------- README | 22 -- README.md | 241 ++++++++++++++++++ src/main/c/Windows/Makefile | 6 +- .../com/fazecast/jSerialComm/SerialPort.java | 24 +- 7 files changed, 273 insertions(+), 199 deletions(-) delete mode 100644 AUTHORS create mode 100644 AUTHORS.md delete mode 100644 INSTALL delete mode 100644 README create mode 100644 README.md diff --git a/AUTHORS b/AUTHORS deleted file mode 100644 index 313cf21..0000000 --- a/AUTHORS +++ /dev/null @@ -1,14 +0,0 @@ -Maintainer ----------- -Will Hedgecock - -Original Authors ----------------- -Will Hedgecock - -Contributors ------------- -Will Hedgecock -Frederik Schubert -Farrell Farahbod -Michael Kaesbauer diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..aabaffc --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,14 @@ +# Maintainer + +Will Hedgecock + +# Original Authors + +Will Hedgecock + +# Contributors + +* Will Hedgecock +* Frederik Schubert +* Farrell Farahbod +* Michael Kaesbauer diff --git a/INSTALL b/INSTALL deleted file mode 100644 index f69b46f..0000000 --- a/INSTALL +++ /dev/null @@ -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: - - - com.fazecast - jSerialComm - [2.0.0,3.0.0) - - -Ivy: - - - -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)"] diff --git a/README b/README deleted file mode 100644 index a839637..0000000 --- a/README +++ /dev/null @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..08105e7 --- /dev/null +++ b/README.md @@ -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: + +``` + + com.fazecast + jSerialComm + [2.0.0,3.0.0) + +``` + +* Ivy: + +``` + +``` + +* 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``` diff --git a/src/main/c/Windows/Makefile b/src/main/c/Windows/Makefile index 4fce64a..21bf8d7 100644 --- a/src/main/c/Windows/Makefile +++ b/src/main/c/Windows/Makefile @@ -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$@ diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPort.java b/src/main/java/com/fazecast/jSerialComm/SerialPort.java index 3598629..2559407 100644 --- a/src/main/java/com/fazecast/jSerialComm/SerialPort.java +++ b/src/main/java/com/fazecast/jSerialComm/SerialPort.java @@ -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. *

@@ -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. *

@@ -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() {}