rusefi
/
jSerialComm
mirror of https://github.com/rusefi/jSerialComm.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updating all Javadoc documentation.

This commit is contained in:
hedgecrw85 2015-03-12 18:09:39 -05:00
parent 42bfd6e1df
commit 51c4cae9d9
6 changed files with 232 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
INSTALL
View File

@ -12,7 +12,7 @@ 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 CDT plugin (http:....) for proper handling of the C/C++ source code)
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/C++ source code)
------------

7
src/main/java/com/fazecast/jSerialComm/SerialPort.java
View File

@ -2,7 +2,7 @@
* SerialPort.java
*
* Created on: Feb 25, 2012
* Last Updated on: Feb 27, 2015
* Last Updated on: Mar 12, 2015
* Author: Will Hedgecock
*
* Copyright (C) 2012-2015 Fazecast, Inc.
@ -34,8 +34,8 @@ import java.io.OutputStream;
/**
* This class provides native access to serial ports and devices without requiring external libraries or tools.
*
* @author Will Hedgecock <will.hedgecock@gmail.com>
* @version 1.0
* @author Will Hedgecock <will.hedgecock@fazecast.com>
* @version 1.0.0
* @see java.io.InputStream
* @see java.io.OutputStream
*/
@ -753,6 +753,7 @@ public final class SerialPort
bytesRead = readBytes(buffer, 1l);
if (bytesRead > 0)
return ((int)buffer[0] & 0x000000FF);
try { Thread.sleep(2); } catch (Exception e) {}
}
throw new IOException("This port appears to have been shutdown or disconnected.");
}

60
src/main/java/com/fazecast/jSerialComm/SerialPortDataListener.java
View File

@ -1,13 +1,67 @@
/*
* SerialPortDataListener.java
*
* Created on: Feb 25, 2015
* Last Updated on: Mar 12, 2015
* Author: Will Hedgecock
*
* Copyright (C) 2012-2015 Fazecast, Inc.
*
* This file is part of jSerialComm.
*
* jSerialComm is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published
* by the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* jSerialComm is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with jSerialComm. If not, see <http://www.gnu.org/licenses/>.
*/
package com.fazecast.jSerialComm;
import java.util.EventListener;
/**
* This interface must be implemented to enable simple event-based serial port I/O.
*
* @author Will Hedgecock &lt;will.hedgecock@fazecast.com&gt;
* @version 1.0.0
* @see java.util.EventListener
*/
public interface SerialPortDataListener extends EventListener
{
// TODO: Documentation - can OR together desired listening events
// Reading vs data available precedence
/**
* Must be overridden to return one or more desired event constants for which the {@link #serialEvent(SerialPortEvent)} callback should be triggered.
* <p>
* Valid event constants are:
* <p>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_AVAILABLE}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_WRITTEN}<br>
* <p>
* If you choose to listen for the {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED} event, you should implement the sub-interface {@link SerialPortPacketListener} instead of this one.
* <p>
* Two or more events may be OR'd together to listen for multiple events; however, if {@link SerialPort#LISTENING_EVENT_DATA_AVAILABLE} is OR'd with {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}, the {@link SerialPort#LISTENING_EVENT_DATA_RECEIVED} flag will take precedence.
* <p>
*
* @return The event constants that should trigger the {@link #serialEvent(SerialPortEvent)} callback.
* @see SerialPort#LISTENING_EVENT_DATA_AVAILABLE
* @see SerialPort#LISTENING_EVENT_DATA_RECEIVED
* @see SerialPort#LISTENING_EVENT_DATA_WRITTEN
*/
public abstract int getListeningEvents();
// TODO: Documentation
/**
* Called whenever one of the serial port events specified by the {@link #getListeningEvents()} method occurs.
*
* @param event A {@link SerialPortEvent} object containing information and/or data about the serial event that occurred.
* @see SerialPortEvent
*/
public abstract void serialEvent(SerialPortEvent event);
}

111
src/main/java/com/fazecast/jSerialComm/SerialPortEvent.java
View File

@ -1,35 +1,122 @@
/*
* SerialPortEvent.java
*
* Created on: Feb 25, 2015
* Last Updated on: Mar 12, 2015
* Author: Will Hedgecock
*
* Copyright (C) 2012-2015 Fazecast, Inc.
*
* This file is part of jSerialComm.
*
* jSerialComm is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published
* by the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* jSerialComm is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with jSerialComm. If not, see <http://www.gnu.org/licenses/>.
*/
package com.fazecast.jSerialComm;
import java.util.EventObject;
/**
* This class describes an asynchronous serial port event.
*
* @author Will Hedgecock &lt;will.hedgecock@fazecast.com&gt;
* @version 1.0.0
* @see java.util.EventObject
*/
public final class SerialPortEvent extends EventObject
{
private static final long serialVersionUID = 3060830619653354150L;
private final int eventType;
private final byte[] serialData;
public SerialPortEvent(Object source, int serialEventType)
/**
* Constructs a {@link SerialPortEvent} object corresponding to the specified serial event type.
* <p>
* This constructor should only be used when the {@link SerialPortEvent} does not contain any data bytes.
* <p>
* Valid serial event types are:
* <p>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_AVAILABLE}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_WRITTEN}<br>
* <p>
*
* @param comPort The {@link SerialPort} about which this object is being created.
* @param serialEventType The type of serial port event that this object describes.
* @see SerialPort#LISTENING_EVENT_DATA_AVAILABLE
* @see SerialPort#LISTENING_EVENT_DATA_RECEIVED
* @see SerialPort#LISTENING_EVENT_DATA_WRITTEN
*/
public SerialPortEvent(SerialPort comPort, int serialEventType)
{
super(source);
super(comPort);
eventType = serialEventType;
serialData = null;
}
public SerialPortEvent(Object source, int serialEventType, byte[] data)
/**
* Constructs a {@link SerialPortEvent} object corresponding to the specified serial event type and containing the passed-in data bytes.
* <p>
* Valid serial event types are:
* <p>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_AVAILABLE}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_WRITTEN}<br>
* <p>
*
* @param comPort The {@link SerialPort} about which this object is being created.
* @param serialEventType The type of serial port event that this object describes.
* @param data The raw data bytes corresponding to this serial port event.
* @see SerialPort#LISTENING_EVENT_DATA_AVAILABLE
* @see SerialPort#LISTENING_EVENT_DATA_RECEIVED
* @see SerialPort#LISTENING_EVENT_DATA_WRITTEN
*/
public SerialPortEvent(SerialPort comPort, int serialEventType, byte[] data)
{
super(source);
super(comPort);
eventType = serialEventType;
serialData = data;
}
/**
* Returns the {@link SerialPort} that triggered this event.
*
* @return The {@link SerialPort} that triggered this event.
*/
public final SerialPort getSerialPort() { return (SerialPort)source; }
/**
* Returns the type of serial port event that caused this object to be created.
* <p>
* Return values will be one and only one of the following:
* <p>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_AVAILABLE}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_RECEIVED}<br>
* &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{@link SerialPort#LISTENING_EVENT_DATA_WRITTEN}<br>
* <p>
*
* @return The serial port event that this object describes.
* @see SerialPort#LISTENING_EVENT_DATA_AVAILABLE
* @see SerialPort#LISTENING_EVENT_DATA_RECEIVED
* @see SerialPort#LISTENING_EVENT_DATA_WRITTEN
*/
public final int getEventType() { return eventType; }
/**
* Returns any raw data bytes associated with this serial port event.
*
* @return Any data bytes associated with this serial port event or null if none exist.
*/
public final byte[] getReceivedData() { return serialData; }
//TODO: Implementations: DataAvailableListener(void), return how much data is available
//TODO: Implementations: DataReceivedListener(Set amount of data to read before notifying)
//Should not mix DataReceivedListener with direct reads (read(), readBytes(), etc) or with InputStream usage
//Note: Using DataReceivedListener will negate any COM port read timeout settings since they make no sense in this context
//TODO: Implementations: DataWrittenListener(Return with number of bytes written)
}

40
src/main/java/com/fazecast/jSerialComm/SerialPortPacketListener.java
View File

@ -1,6 +1,46 @@
/*
* SerialPortPacketListener.java
*
* Created on: Feb 25, 2015
* Last Updated on: Mar 12, 2015
* Author: Will Hedgecock
*
* Copyright (C) 2012-2015 Fazecast, Inc.
*
* This file is part of jSerialComm.
*
* jSerialComm is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published
* by the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* jSerialComm is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with jSerialComm. If not, see <http://www.gnu.org/licenses/>.
*/
package com.fazecast.jSerialComm;
/**
* This interface must be implemented to enable full packet reads using event-based serial port I/O.
* <p>
* <i>Note</i>: Using this interface will negate any serial port read timeout settings since they make no sense in an asynchronous context.
*
* @author Will Hedgecock &lt;will.hedgecock@fazecast.com&gt;
* @version 1.0.0
* @see com.fazecast.jSerialComm.SerialPortDataListener
* @see java.util.EventListener
*/
public interface SerialPortPacketListener extends SerialPortDataListener
{
/**
* Must be overridden to return the desired number of bytes that <b>must</b> be read before the {@link #serialEvent(SerialPortEvent)} callback is triggered.
*
* @return The number of bytes that must be read before the {@link #serialEvent(SerialPortEvent)} callback is triggered.
*/
public abstract int getPacketSize();
}

42
src/test/java/com/fazecast/jSerialComm/SerialPortTest.java
View File

@ -2,7 +2,7 @@
* SerialPortTest.java
*
* Created on: Feb 27, 2015
* Last Updated on: Feb 27, 2015
* Last Updated on: Mar 12, 2015
* Author: Will Hedgecock
*
* Copyright (C) 2012-2015 Fazecast, Inc.
@ -37,13 +37,30 @@ import java.io.InputStream;
*/
public class SerialPortTest
{
private static final class PacketListener implements SerialPortPacketListener
{
@Override
public int getListeningEvents() { return SerialPort.LISTENING_EVENT_DATA_RECEIVED; }
@Override
public void serialEvent(SerialPortEvent event)
{
byte[] newData = event.getReceivedData();
System.out.println("Received data of size: " + newData.length);
for (int i = 0; i < newData.length; ++i)
System.out.print((char)newData[i]);
System.out.println("\n");
}
@Override
public int getPacketSize() { return 100; }
}
static public void main(String[] args)
{
SerialPort[] ports = SerialPort.getCommPorts();
System.out.println("\nPorts:\n");
for (int i = 0; i < ports.length; ++i)
System.out.println(" " + ports[i].getSystemPortName() + ": " + ports[i].getDescriptivePortName());
SerialPort ubxPort = ports[0];
SerialPort ubxPort = ports[(args.length > 0) ? Integer.parseInt(args[0]) : 0];
byte[] readBuffer = new byte[2048];
System.out.println("\nOpening " + ubxPort.getDescriptivePortName() + ": " + ubxPort.openPort());
@ -108,22 +125,25 @@ public class SerialPortTest
}
} catch (Exception e) { e.printStackTrace(); }
System.out.println("\nSwitching over to event-based reading");
ubxPort.addDataListener(new SerialPortPacketListener() {
System.out.println("\nListening for any amount of data available\n");
ubxPort.addDataListener(new SerialPortDataListener() {
@Override
public int getListeningEvents() { return SerialPort.LISTENING_EVENT_DATA_RECEIVED; }
public int getListeningEvents() { return SerialPort.LISTENING_EVENT_DATA_AVAILABLE; }
@Override
public void serialEvent(SerialPortEvent event)
{
byte[] newData = event.getReceivedData();
System.out.println("Received data of size: " + newData.length);
for (int i = 0; i < newData.length; ++i)
System.out.print((char)newData[i]);
System.out.println("\n");
SerialPort comPort = event.getSerialPort();
byte[] newData = new byte[comPort.bytesAvailable()];
int numRead = comPort.readBytes(newData, newData.length);
System.out.println("Read " + numRead + " bytes.");
}
@Override
public int getPacketSize() { return 100; }
});
try { Thread.sleep(5000); } catch (Exception e) {}
ubxPort.removeDataListener();
System.out.println("\nNow listening for full 100-byte data packets\n");
PacketListener listener = new PacketListener();
ubxPort.addDataListener(listener);
try { Thread.sleep(5000); } catch (Exception e) {}
System.out.println("\n\nClosing " + ubxPort.getDescriptivePortName() + ": " + ubxPort.closePort());
ubxPort.removeDataListener();
try { Thread.sleep(1000); } catch (InterruptedException e1) { e1.printStackTrace(); }