com.oracle.deviceaccess.uart

Interface UART

All Superinterfaces:

java.lang.AutoCloseable, BufferAccess<java.nio.ByteBuffer>, java.nio.channels.ByteChannel, java.nio.channels.Channel, java.io.Closeable, Peripheral<UART>, java.nio.channels.ReadableByteChannel, java.nio.channels.WritableByteChannel

All Known Subinterfaces:

ModemUART

public interface UART
extends Peripheral<UART>, java.nio.channels.ByteChannel, BufferAccess<java.nio.ByteBuffer>

The 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.

See Also:

UARTPermission, ClosedPeripheralException

Field Summary

Fields inherited from interface com.oracle.deviceaccess.Peripheral

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

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.

Methods inherited from interface com.oracle.deviceaccess.Peripheral

close, getDescriptor, isOpen, tryLock, unlock

Methods inherited from interface com.oracle.deviceaccess.BufferAccess

getInputBuffer, getOutputBuffer

Method Detail

getBaudRate

int getBaudRate()
                throws java.io.IOException,
                       UnavailablePeripheralException,
                       ClosedPeripheralException

Gets the current baud rate. If the baud rate was not set previously using setBaudRate(int) the peripheral configuration-specific default value is returned.

Returns:

the current baud rate.

Throws:

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.

getDataBits

int getDataBits()
                throws java.io.IOException,
                       UnavailablePeripheralException,
                       ClosedPeripheralException

Gets the current number of bits per character.

Returns:

the number bits per character: UARTConfig.DATABITS_5, UARTConfig.DATABITS_6, UARTConfig.DATABITS_7, UARTConfig.DATABITS_8 or UARTConfig.DATABITS_9.

Throws:

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.

getParity

int getParity()
              throws java.io.IOException,
                     UnavailablePeripheralException,
                     ClosedPeripheralException

Gets the current parity.

Returns:

the speed parity: UARTConfig.PARITY_ODD, UARTConfig.PARITY_EVEN, UARTConfig.PARITY_MARK, UARTConfig.PARITY_SPACE, or UARTConfig.PARITY_NONE.

Throws:

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.

getStopBits

int getStopBits()
                throws java.io.IOException,
                       UnavailablePeripheralException,
                       ClosedPeripheralException

Gets the current number of stop bits per character.

Returns:

the number of stop bits per character: UARTConfig.STOPBITS_1, UARTConfig.STOPBITS_1_5, or UARTConfig.STOPBITS_2.

Throws:

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.

setBaudRate

void setBaudRate(int baudRate)
                 throws java.io.IOException,
                        UnavailablePeripheralException,
                        ClosedPeripheralException

Sets the baud rate.

Parameters:

baudRate - the baud rate to set.

Throws:

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.

setDataBits

void setDataBits(int dataBits)
                 throws java.io.IOException,
                        UnavailablePeripheralException,
                        ClosedPeripheralException

Sets the number of bits per character.

Parameters:

dataBits - the number bits per character: UARTConfig.DATABITS_5, UARTConfig.DATABITS_6, UARTConfig.DATABITS_7, UARTConfig.DATABITS_8 or UARTConfig.DATABITS_9.

Throws:

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.

setEventListener

void setEventListener(int eventId,
                    UARTEventListener listener)
                      throws java.io.IOException,
                             UnavailablePeripheralException,
                             ClosedPeripheralException

Registers a 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.

Parameters:

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.

Throws:

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).

setParity

void setParity(int parity)
               throws java.io.IOException,
                      UnavailablePeripheralException,
                      ClosedPeripheralException

Sets the parity.

Parameters:

parity - the speed parity: UARTConfig.PARITY_ODD, UARTConfig.PARITY_EVEN, UARTConfig.PARITY_MARK, UARTConfig.PARITY_SPACE, or UARTConfig.PARITY_NONE.

Throws:

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.

setStopBits

void setStopBits(int stopBits)
                 throws java.io.IOException,
                        UnavailablePeripheralException,
                        ClosedPeripheralException

Sets the number of stop bits per character.

Parameters:

stopBits - the number of stop bits per character: UARTConfig.STOPBITS_1, UARTConfig.STOPBITS_1_5, or UARTConfig.STOPBITS_2.

Throws:

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.

startWriting

void startWriting(java.nio.ByteBuffer src,
                OutputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailablePeripheralException,
                         ClosedPeripheralException

Starts asynchronous writing in sucessive rounds - initially writing the data remaining in the provided buffer. Additional rounds are asynchronously fetched by notifying the provided 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.

Parameters:

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.

Throws:

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.

startWriting

void startWriting(java.nio.ByteBuffer src1,
                java.nio.ByteBuffer src2,
                OutputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailablePeripheralException,
                         ClosedPeripheralException

Starts asynchronous writing in successive rounds.

This method behaves identically to 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.

Parameters:

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.

Throws:

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.

stopWriting

void stopWriting()
                 throws java.io.IOException,
                        UnavailablePeripheralException,
                        ClosedPeripheralException

Stops (cancels) the currently active writing session.

This method return silently if no writing session is currently active.

Throws:

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.

startReading

void startReading(java.nio.ByteBuffer src,
                InputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailablePeripheralException,
                         ClosedPeripheralException

Starts asynchronous reading in sucessive rounds - reading data into the provided buffer. The provided 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.

Parameters:

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.

Throws:

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.

startReading

void startReading(java.nio.ByteBuffer src1,
                java.nio.ByteBuffer src2,
                InputRoundListener<UART,java.nio.ByteBuffer> listener)
                  throws java.io.IOException,
                         UnavailablePeripheralException,
                         ClosedPeripheralException

Starts asynchronous reading in sucessive rounds.

This method behaves identically to 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.

Parameters:

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.

Throws:

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.

stopReading

void stopReading()
                 throws java.io.IOException,
                        UnavailablePeripheralException,
                        ClosedPeripheralException

Stops (cancels) the currently active reading session.

This method return silently if no reading session is currently active.

Throws:

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.

generateBreak

void generateBreak(int duration)
                   throws java.io.IOException,
                          UnavailablePeripheralException,
                          ClosedPeripheralException

Generates a break condition for the specified duration.

Parameters:

duration - duration of the break condition to generate.

Throws:

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.

setReceiveTriggerLevel

void setReceiveTriggerLevel(int level)
                            throws java.io.IOException,
                                   UnavailablePeripheralException,
                                   ClosedPeripheralException

Sets the receive trigger level. The 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.

Parameters:

level - the trigger level, in bytes.

Throws:

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.

getReceiveTriggerLevel

int getReceiveTriggerLevel()
                           throws java.io.IOException,
                                  UnavailablePeripheralException,
                                  ClosedPeripheralException

Gets the current receive trigger level.

Returns:

the trigger level, in bytes or 0 if this feature is not supported.

Throws:

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.

read

int read(java.nio.ByteBuffer dst)
         throws java.io.IOException,
                UnavailablePeripheralException,
                ClosedPeripheralException

Reads a sequence of bytes from this UART into the given buffer.

Note that the availability of new input data may be notified through an UARTEvent with ID UARTEvent.INPUT_DATA_AVAILABLE according to the receive trigger level as set by setReceiveTriggerLevel(int).

Specified by:

read in interface java.nio.channels.ReadableByteChannel

Parameters:

dst - The buffer into which bytes are to be transferred

Returns:

The number of bytes read, possibly zero, or -1 if the device has reached end-of-stream

Throws:

java.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.

write

int write(java.nio.ByteBuffer src)
          throws java.io.IOException,
                 UnavailablePeripheralException,
                 ClosedPeripheralException

Writes a sequence of bytes to this UART from the given buffer.

Note that an empty output buffer condition may be notified through an UARTEvent with ID UARTEvent.OUTPUT_BUFFER_EMPTY.

Specified by:

write in interface java.nio.channels.WritableByteChannel

Parameters:

src - The buffer from which bytes are to be retrieved

Returns:

The number of bytes written, possibly zero.

Throws:

java.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.