Modes of Operation

Will Hedgecock edited this page Jan 5, 2018 · 20 revisions

Although this library was designed to be as simple and flexible as possible, you can enable a number of different modes of operation via manipulation of the serial port timeout values and the interface through which you choose to access the serial port.

The following list indicates the modes of operation possible using this library, as well as a description of what each mode entails and how to enable it:

Note that no matter what mode you choose: any call to the Java InputStream.read() function will always block forever until the next byte of data is available. This occurs in order to adhere to the Java standard.

If you simply open a port without specifying any particular mode of operation, it will default to opening in Non-Blocking Mode.


Non-Blocking Mode

In non-blocking mode, a call to any of the read() or readBytes() methods will return immediately with any available data. If no data is available, it will return immediately with a 0 to indicate no data.

To specify this mode of operation, you must call the setComPortTimeouts() method with a timeout mode of TIMEOUT_NONBLOCKING.

Read Semi-Blocking Mode

In this mode, a call to any of the read() or readBytes() methods will block until the number of milliseconds specified by the newReadTimeout parameter has elapsed or at least 1 byte of data can be read.

To specify this mode of operation, you must call the setComPortTimeouts() method with a timeout mode of TIMEOUT_READ_SEMI_BLOCKING.

Read/Write Semi-Blocking Mode

In this mode, a call to any of the read(), readBytes(), write(), or writeBytes() methods will block until the numbers of milliseconds specified by the newReadTimeout or newWriteTimeout parameters have elapsed or at least 1 byte of data can be read or written.

To specify this mode of operation, you must call the setComPortTimeouts() method with an OR'd timeout mode of TIMEOUT_READ_SEMI_BLOCKING.

Read Semi-Blocking/Write Full-Blocking Mode

In this mode, a call to any of the read() or readBytes() methods will block until the number of milliseconds specified by the newReadTimeout parameter has elapsed or at least 1 byte of data can be read. A call to any of the write() or writeBytes() methods will block until the number of milliseconds specified by the newWriteTimeout parameter has elapsed or the total number of requested bytes can be written.

To specify this mode of operation, you must call the setComPortTimeouts() method with an OR'd timeout mode of TIMEOUT_READ_SEMI_BLOCKING.

Read Full-Blocking Mode

In this mode, a call to any of the read() or readBytes() methods will block until the number of milliseconds specified by the newReadTimeout parameter has elapsed or the total number of requested bytes can be read.

To specify this mode of operation, you must call the setComPortTimeouts() method with a timeout mode of TIMEOUT_READ_BLOCKING.

Read Full-Blocking/Write Semi-Blocking Mode

In this mode, a call to any of the read() or readBytes() methods will block until the number of milliseconds specified by the newReadTimeout parameter has elapsed or the total number of requested bytes can be read. A call to any of the write() or writeBytes() methods will block until the number of milliseconds specified by the newWriteTimeout parameter has elapsed or at least 1 byte of data can be written.

To specify this mode of operation, you must call the setComPortTimeouts() method with an OR'd timeout mode of TIMEOUT_READ_BLOCKING.

Read/Write Full-Blocking Mode

In this mode, a call to any of the read(), readBytes(), write(), or writeBytes() methods will block until the numbers of milliseconds specified by the newReadTimeout or newWriteTimeout parameters have elapsed or the total number of requested bytes can be read or written.

To specify this mode of operation, you must call the setComPortTimeouts() method with an OR'd timeout mode of TIMEOUT_READ_BLOCKING.

Event-Driven Callback Mode

In any of the event-driven callback modes, you can register your own custom callback to be triggered upon certain serial I/O events. Note that none of the timeouts you may have specified in an earlier call to setComPortTimeouts() will be adhered to in this mode.

The events you can listen for are:

For Data Availability

In this case, your callback will be triggered whenever there is any data available to be read over the serial port. Once your callback is triggered, you can optionally call bytesAvailable() to determine how much data is available to read, and you actually read the data using any of the read() or readBytes() methods.

To specify this mode of operation, you simply register a SerialPortDataListener that implements your custom callback using the addDataListener() method. Note that you must override the getListeningEvents() method to return LISTENING_EVENT_DATA_AVAILABLE to enable this mode. Please refer to this usage wiki for an example of how to use this functionality.

For Write Status

In this case, your callback will be triggered whenever all data you have written using any of the write() or writeBytes() methods has actually been transmitted.

Note that this mode of operation is only functional on Windows operating systems due to limitations in Linux's handling of serial writes.

To specify this mode of operation, you simply register a SerialPortDataListener that implements your custom callback using the addDataListener() method. Note that you must override the getListeningEvents() method to return LISTENING_EVENT_DATA_WRITTEN to enable this mode.

For Full Packet Data Reception

In this case, your callback will be triggered whenever a set amount of data has been read from the serial port. This raw data will be returned to you within your own callback, so there is no further need to read directly from the serial port.

To specify this mode of operation, you simply register a SerialPortPacketListener that implements your custom callback using the addDataListener() method. Note that in order to enable this mode, you must override both the getListeningEvents() method to return LISTENING_EVENT_DATA_RECEIVED and the getPacketSize() method to return the number of data bytes you expect receive when your callback is triggered. Please refer to this usage wiki for an example of how to use this functionality.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.