-
Notifications
You must be signed in to change notification settings - Fork 293
Modes of Operation
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:
- Non-Blocking Mode
- Read Semi-Blocking Mode
- Read/Write Semi-Blocking Mode
- Read Semi-Blocking/Write Full-Blocking Mode
- Read Full-Blocking Mode
- Read Full-Blocking/Write Semi-Blocking Mode
- Read/Write Full-Blocking Mode
- Event-Driven Callback Mode
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
Copyright © 2012-2024 Fazecast, Inc. All rights reserved.