public interface UART extends Peripheral<UART>, java.nio.channels.ByteChannel, BufferAccess<java.nio.ByteBuffer>
UART
interface provides methods for controlling and accessing a UART (Universal Asynchronous
Receiver/Transmitter).
A UART device may be identified by the numerical ID and by the name (if any defined) that correspond to its
registered configuration. A UART
instance can be opened by a call to one of the
PeripheralManager.open(id,...)
methods using its ID or by a call to one of the
PeripheralManager.open(name,...)
methods using its name. When a UART
instance is opened with an ad-hoc
UARTConfig
configuration (which includes its hardware addressing information) using one of the
PeripheralManager.open(config,...)
it is not
assigned any ID nor name.
Once opened, an application can read the received data bytes and write the data bytes to be transmitted through the
UART using methods of the ByteChannel
interface.
An application can register a UARTEventListener
instance which will get asynchronously notified of input data
availability, input buffer overrun and/or empty output buffer conditions. Note that the input and output buffers for
which these events may be notified may not necessarily correspond to the transmit and receive FIFO buffers of the
UART hardware but may be buffers allocated by the underlying native driver. To register a UARTEventListener
instance, the application must call the setEventListener(int, UARTEventListener)
method. The registered
listener can later on be removed by calling the same method with a null
listener parameter.
When done, an application should call the UART.close()
method to close the UART. Any further attempt
to access or control a UART which has been closed will result in a ClosedPeripheralException
been thrown.UARTPermission
,
ClosedPeripheralException
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
Modifier and Type | Method and Description |
---|---|
void |
generateBreak(int duration)
Generates a break condition for the specified duration.
|
int |
getBaudRate()
Gets the current baud rate.
|
int |
getDataBits()
Gets the current number of bits per character.
|
int |
getParity()
Gets the current parity.
|
int |
getReceiveTriggerLevel()
Gets the current receive trigger level.
|
int |
getStopBits()
Gets the current number of stop bits per character.
|
int |
read(java.nio.ByteBuffer dst)
Reads a sequence of bytes from this UART into the given buffer.
|
void |
setBaudRate(int baudRate)
Sets the baud rate.
|
void |
setDataBits(int dataBits)
Sets the number of bits per character.
|
void |
setEventListener(int eventId,
UARTEventListener listener)
Registers a
UARTEventListener instance to monitor input data availability, input buffer overrun and/or
empty output buffer conditions. |
void |
setParity(int parity)
Sets the parity.
|
void |
setReceiveTriggerLevel(int level)
Sets the receive trigger level.
|
void |
setStopBits(int stopBits)
Sets the number of stop bits per character.
|
void |
startReading(java.nio.ByteBuffer src1,
java.nio.ByteBuffer src2,
InputRoundListener<UART,java.nio.ByteBuffer> listener)
Starts asynchronous reading in sucessive rounds.
|
void |
startReading(java.nio.ByteBuffer src,
InputRoundListener<UART,java.nio.ByteBuffer> listener)
Starts asynchronous reading in sucessive rounds - reading data into the provided
buffer.
|
void |
startWriting(java.nio.ByteBuffer src1,
java.nio.ByteBuffer src2,
OutputRoundListener<UART,java.nio.ByteBuffer> listener)
Starts asynchronous writing in successive rounds.
|
void |
startWriting(java.nio.ByteBuffer src,
OutputRoundListener<UART,java.nio.ByteBuffer> listener)
Starts asynchronous writing in sucessive rounds - initially writing the data remaining in the provided
buffer.
|
void |
stopReading()
Stops (cancels) the currently active reading session.
|
void |
stopWriting()
Stops (cancels) the currently active writing session.
|
int |
write(java.nio.ByteBuffer src)
Writes a sequence of bytes to this UART from the given buffer.
|
close, getDescriptor, isOpen, tryLock, unlock
getInputBuffer, getOutputBuffer
int getBaudRate() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setBaudRate(int)
the
peripheral configuration-specific default value is returned.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getDataBits() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
UARTConfig.DATABITS_5
, UARTConfig.DATABITS_6
,
UARTConfig.DATABITS_7
, UARTConfig.DATABITS_8
or UARTConfig.DATABITS_9
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getParity() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
UARTConfig.PARITY_ODD
, UARTConfig.PARITY_EVEN
,
UARTConfig.PARITY_MARK
, UARTConfig.PARITY_SPACE
, or UARTConfig.PARITY_NONE
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getStopBits() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
UARTConfig.STOPBITS_1
, UARTConfig.STOPBITS_1_5
, or
UARTConfig.STOPBITS_2
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void setBaudRate(int baudRate) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
baudRate
- the baud rate to set.java.lang.UnsupportedOperationException
- if this UART cannot be configured with the requested baud rate.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void setDataBits(int dataBits) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
dataBits
- the number bits per character: UARTConfig.DATABITS_5
, UARTConfig.DATABITS_6
,
UARTConfig.DATABITS_7
, UARTConfig.DATABITS_8
or UARTConfig.DATABITS_9
.java.lang.UnsupportedOperationException
- if this UART cannot be configured with the requested number of bits per character.java.lang.IllegalArgumentException
- if dataBits
is not one of the defined values.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void setEventListener(int eventId, UARTEventListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
UARTEventListener
instance to monitor input data availability, input buffer overrun and/or
empty output buffer conditions. While the listener can be triggered by hardware interrupts, there are no
real-time guarantees of when the listener will be called.
A list of event type IDs is defined in UARTEvent
.
If listener
is null
then listener previously registered for the specified event type will be
removed.
Only one listener can be registered at a particular time for a particular event type.eventId
- ID of the native event to listen to: UARTEvent.INPUT_DATA_AVAILABLE
,
UARTEvent.INPUT_BUFFER_OVERRUN
,
UARTEvent.OUTPUT_BUFFER_EMPTY
, UARTEvent.BREAK_INTERRUPT
,
UARTEvent.FRAMING_ERROR
or UARTEvent.PARITY_ERROR
.listener
- the UARTEventListener
instance to be notified upon occurrence of the designated event.java.io.IOException
- if some other I/O error occurs.java.lang.IllegalArgumentException
- if eventId
does not correspond to any of the supported event types.java.lang.IllegalStateException
- if listener
is not null
and a listener is already registered for the specified event
type.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.UnsupportedOperationException
- if this UART does not support asynchronous event notification of the requested conditions (eg. input data availability, input
buffer overrun, empty output buffer and/or error conditions).void setParity(int parity) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
parity
- the speed parity: UARTConfig.PARITY_ODD
, UARTConfig.PARITY_EVEN
,
UARTConfig.PARITY_MARK
, UARTConfig.PARITY_SPACE
, or UARTConfig.PARITY_NONE
.java.lang.UnsupportedOperationException
- if this UART cannot be configured with the requested parity.java.lang.IllegalArgumentException
- if parity
is not one of the defined values.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void setStopBits(int stopBits) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
stopBits
- the number of stop bits per character: UARTConfig.STOPBITS_1
, UARTConfig.STOPBITS_1_5
,
or UARTConfig.STOPBITS_2
.java.lang.UnsupportedOperationException
- if this UART cannot be configured with the requested number of stop bits per character.java.lang.IllegalArgumentException
- if stopBits
is not one of the defined values.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void startWriting(java.nio.ByteBuffer src, OutputRoundListener<UART,java.nio.ByteBuffer> listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
OutputRoundListener
instance once the initial data have been written. The initial data to be written
is retrieved from the provided buffer; the data to write during the subsequent rounds is retrieved
from that very same buffer upon invocation od the provided OutputRoundListener
instance.
Writing can be stopped by a call to stopWriting()
.
The data will be written according to the current baud rate as returned by getBaudRate()
. The
baud rate and other configuration parameters can be changed by the provided OutputRoundListener
instance
upon notification of each round.
Only one write operation (synchronous or asynchronous) can be going on at any time.src
- the buffer for the data to be written.listener
- the OutputRoundListener
instance to be notified when the all the data remaining
in the buffer has been written.java.lang.NullPointerException
- If src
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous output operation is already active.void startWriting(java.nio.ByteBuffer src1, java.nio.ByteBuffer src2, OutputRoundListener<UART,java.nio.ByteBuffer> listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
startWriting(ByteBuffer, OutputRoundListener)
excepts that it
uses double-buffering. Notification will happen when all the data remaining in the working buffer has been written
and writing will proceed with the alternate buffer (which will become the
working buffer). Writing will only be suspended if the previous event has not yet been handled.
Only one write operation (synchronous or asynchronous) can be going on at any time.src1
- the first buffer for the data to be written.src2
- the second buffer for the data to be written.listener
- the OutputRoundListener
instance to be notified when all
the data remaining in the working buffer has been written.java.lang.NullPointerException
- If src1
, src2
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous output operation is already active.void stopWriting() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void startReading(java.nio.ByteBuffer src, InputRoundListener<UART,java.nio.ByteBuffer> listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
InputRoundListener
is cyclicly notified when the provided buffer has been filled
with input data. Reading into the buffer and notification will only resume once the
event has been handled. Reading and notification will immediately start and will repeat until it is stopped by a
call to stopReading()
.
The data will be read according to the current baud rate as returned by getBaudRate()
. The
baud rate and other configuration parameters can be changed by the provided InputRoundListener
instance
upon notification of each round.
Only one read operation (synchronous or asynchronous) can be going on at any time.src
- the buffer for the data to be read.listener
- the InputRoundListener
instance to be notified when the all remaining
space in the buffer has been filled with input data.java.lang.NullPointerException
- If src
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous input operation is already active.void startReading(java.nio.ByteBuffer src1, java.nio.ByteBuffer src2, InputRoundListener<UART,java.nio.ByteBuffer> listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
startReading(ByteBuffer, InputRoundListener)
excepts that it
uses double-buffering. Notification will happen when all the remaining space in the working buffer has been filled
and reading will proceed with the alternate buffer (which will become the
working buffer). Reading will only be suspended if the previous event has not yet been handled.
Only one read operation (synchronous or asynchronous) can be going on at any time.src1
- the first buffer for the data to be read.src2
- the second buffer for the data to be read.listener
- the InputRoundListener
instance to be notified when all
the sapce remaining in the working buffer has been filled with input data.java.lang.NullPointerException
- If src1
, src2
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous input operation is already active.void stopReading() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void generateBreak(int duration) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
duration
- duration of the break condition to generate.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.UnsupportedOperationException
- if this UART cannot be configured with the requested receive trigger level.void setReceiveTriggerLevel(int level) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
UARTEventListener
instance registered
for UARTEvent.INPUT_DATA_AVAILABLE
events (if any) will get notified after
the specified number of bytes have been received in the input buffer.level
- the trigger level, in bytes.java.lang.UnsupportedOperationException
- if this UART cannot be configured with the requested receive trigger level.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getReceiveTriggerLevel() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
0
if this feature is not supported.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int read(java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
UARTEvent
with ID
UARTEvent.INPUT_DATA_AVAILABLE
according to the receive trigger level
as set by setReceiveTriggerLevel(int)
.
read
in interface java.nio.channels.ReadableByteChannel
dst
- The buffer into which bytes are to be transferred-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If dst
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- if an I/O error occurred such as the device is not readable.int write(java.nio.ByteBuffer src) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
UARTEvent
with ID
UARTEvent.OUTPUT_BUFFER_EMPTY
.
write
in interface java.nio.channels.WritableByteChannel
src
- The buffer from which bytes are to be retrievedjava.lang.NullPointerException
- If src
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- if an I/O error occurred such as the device is not writable.Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved.
Legal Notices