13 UART

The com.oracle.deviceaccess.uart package contains interfaces and classes for controlling and reading and writing from/to Universal Asynchronous Receiver/Transmitter (UART), with optional Modem signals control. In order to access and control a specific UART device, an application should first open and obtain an UART instance for the UART device using its numerical ID, name, type (interface) and/or properties.

Example 13-1 and Example 13-2 demonstrate how to use the UART APIs to communicate with a host.

Example 13-1 Communicating using the UART API

import com.oracle.deviceaccess.PeripheralException;
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.uart.UART;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
 
public class UARTExample1 {
 
    UART host = null;
    InputStream is = null;
    OutputStream os = null;
 
    public UARTExample1() {
        try {
            host = (UART) PeripheralManager.open("HOST", UART.class,
                (String[]) null);
            is = host.getInputStream();
            os = host.getOutputStream();
            StringBuffer cmd = new StringBuffer();
            int c = 0;
            while (true) {
                os.write('$');
                os.write(' '); // echo prompt
                while (c != '\n' && c != '\003') { // echo input
                    c = is.read();
                    os.write(c);
                    cmd.append(c);
                }
                if (c == '\003') { // CTL-C
                    break;
                }
                // process(cmd);
            }
        } catch (IOException ioe) {
            // Handle exception
        } catch (PeripheralException pe) {
            // Handle exception
        } finally {
            if (is != null) {
                try {
                    is.close();
                } catch (IOException ex) {
                }
            }
            if (os != null) {
                try {
                    os.close();
                } catch (IOException ex) {
                }
            }
            if (host != null) {
                try {
                    host.close();
                } catch (IOException ex) {
                }
            }
        }
    }
}

Example 13-2 Using a ModemUART to Communicate

import com.oracle.deviceaccess.PeripheralException;
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.modem.ModemSignalEvent;
import com.oracle.deviceaccess.modem.ModemSignalListener;
import com.oracle.deviceaccess.modem.ModemSignalsControl;
import com.oracle.deviceaccess.uart.ModemUART;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
 
public class UARTExample2 {
 
    ModemUART modem = null;
    InputStream is = null;
    OutputStream os = null;
 
    public UARTExample2() {
        try {
            modem = (ModemUART) PeripheralManager.open("HOST",
                       ModemUART.class, (String[]) null);
            is = modem.getInputStream();
            os = modem.getOutputStream();
            modem.setSignalChangeListener(new ModemSignalListener() {
                public void signalStateChanged(ModemSignalEvent event) {
                    if (event.getSignalState() == false) {
                        ModemUART modem = (ModemUART) event.getPeripheral();
                        // Process MODEM hang-up...
                    }
                }
            }, ModemSignalsControl.DCD_SIGNAL);
            // Process input and output...
        } catch (IOException ioe) {
            // Handle exception
        } catch (PeripheralException pe) {
            // Handle exception
        } finally {
            // Close UART, and input and output streams
        }
 
    }
}

Note that the preceding example is using a try-with-resources statement and that the UART.close(), InputStream.close() and OutputStream.close() methods are automatically invoked by the platform at the end of the statement.

UARTs are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. The com.oracle.deviceaccess.uart permission allows access to be granted to UART devices as a whole. This permission must be requested in the JAD file under MIDlet-Permissions or MIDlet-Permissions-Opt, and the application must be digitally signed by a trusted authority to gain access to the APIs. Alternatively, the permission may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

The ModemUART Interface

The ModemUART interface provides methods for controlling and accessing a UART (Universal Asynchronous Receiver/Transmitter) with Modem control lines. Note that even if CTS/RTS hardware flow control is enabled using the UARTConfig.getFlowControlMode() method, registering for notification of CTS signal state changes (see ModemSignalsControl.setSignalChangeListener(com.oracle.deviceaccess.modem.ModemSignalListener, int) may not always be supported. Additionally, when supported, CTS signal state change notification may only be indicative because of latency: CTS flow control may be handled directly by the hardware or by the native driver.

The UART Interface

The UART interface provides methods for controlling and accessing a UART (Universal Asynchronous Receiver/Transmitter). Each UART device is identified by a numerical ID and by a name. A UART instance can be opened by a call to one of the PeripheralManager.open() methods. Once opened, an application can obtain an input stream and an output stream using the getInputStream() and getOutputStream() methods and can then read the received data bytes and respectively write the data bytes to be transmitted through the UART. An application can register a UARTEventListener instance which will get asynchronously notified of input data availability, input buffer overrun, 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 release the UART. Any further attempt to access or control a UART which has been closed will result in a PeripheralNotAvailableException been thrown.

The UART interface consists of several methods:

void close() throws java.io.IOException, PeripheralNotAvailableException

This method closes and releases the underlying peripheral device, making it available to other applications. Once released, subsequent operations on that very same Peripheral instance will throw a PeripheralNotAvailableException. This method has no effects if the peripheral device has already been closed. Note that closing a UART will also close the device's InputStream and OutputStream..
int getBaudRate() throws java.io.IOException, PeripheralNotAvailableException

This method returns the current baud rate. If the baud rate was not set previously using the setBaudRate(int) method, the peripheral configuration-specific default value is returned.
void setBaudRate(int baudRate) throws java.io.IOException, PeripheralNotAvailableException

This method sets the baud rate.
int getDataBits() throws java.io.IOException, PeripheralNotAvailableException

This method returns the current number of bits per character.
void setDataBits(int dataBits) throws java.io.IOException, PeripheralNotAvailableException

This method sets the number of bits per character.
int getParity() throws java.io.IOException, PeripheralNotAvailableException

This method returns the current parity.
void setParity(int parity) throws java.io.IOException, PeripheralNotAvailableException

This method sets the parity.
int getStopBits() throws java.io.IOException, PeripheralNotAvailableException

This method returns the current number of stop bits per character.
void setStopBits(int stopBits) throws java.io.IOException, PeripheralNotAvailableException

This method sets the number of stop bits per character.
java.io.InputStream getInputStream() throws java.io.IOException, PeripheralNotAvailableException

This method returns this UART's input stream. The same InputStream instance is returned upon subsequent calls. Note that if this UART's input stream has been previously closed, this method returns the closed input stream without attempting to re-open it.
java.io.OutputStream getOutputStream() throws java.io.IOException, PeripheralNotAvailableException

This method returns this UART's output stream. The same OutputStream instance is returned upon subsequent calls. Note that if this UART's output stream has been previously closed, this method returns the same closed output stream without attempting to re-open it.
void setEventListener(int eventId, UARTEventListener listener) throws java.io.IOException, PeripheralNotAvailableException

This method 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.

The UARTEventListener Interface

The UARTEventListener interface defines methods for getting notified of events fired by peripheral devices that implement the UART interface. A UARTEventListener can be registered using the UART.setEventListener(int, UARTEventListener) method.

The UARTEventListener interface consists of only one method:

void eventDispatched(UARTEvent event)

This method is invoked when an event is fired by peripheral device.

The UARTConfig Class

The UARTConfig class encapsulates the hardware addressing information, as well as the static and dynamic configuration parameters, of a UART. Some hardware addressing parameter, and static and dynamic configuration parameters, may be set to PeripheralConfig.DEFAULT. Whether such default settings are supported is both platform-dependent and peripheral driver-dependent. An instance of UARTConfig can be passed to the PeripheralManager.open(PeripheralConfig) or PeripheralManager.open(Class, PeripheralConfig) method to open the designated UART with the specified configuration. A PeripheralConfigInvalidException is thrown when attempting to open a peripheral device with an invalid or unsupported configuration.

The UARTConfig class consists of a number of static integer constants, as shown in Table 13-1.

Table 13-1 UARTConfig Constants

Constant	Description
`DATABITS_5`	5 data bit format
`DATABITS_6`	6 data bit format
`DATABITS_7`	7 data bit format
`DATABITS_8`	8 data bit format
`DATABITS_9`	9 data bit format
`FLOWCONTROL_NONE`	Flow control off
`FLOWCONTROL_RTSCTS_IN`	RTS/CTS (hardware) flow control on input
`FLOWCONTROL_RTSCTS_OUT`	RTS/CTS (hardware) flow control on output
`FLOWCONTROL_XONXOFF_IN`	XON/XOFF (software) flow control on input
`FLOWCONTROL_XONXOFF_OUT`	XON/XOFF (software) flow control on output
`PARITY_EVEN`	EVEN parity scheme
`PARITY_MARK`	MARK parity scheme
`PARITY_NONE`	No parity bit
`PARITY_ODD`	ODD parity scheme
`PARITY_SPACE`	SPACE parity scheme
`STOPBITS_1`	Number of STOP bits is 1
`STOPBITS_1_5`	Number of STOP bits is 1.5
`STOPBITS_2`	Number of STOP bits is 2

The UARTConfig class consists of two constructors and several methods:

public UARTConfig(int uartNumber, int baudRate, int dataBits, int parity, int stopBits, int flowcontrol)

This constructor creates a new UARTConfig with the specified hardware addressing information and configuration parameters.
public UARTConfig(int uartNumber, int baudRate, int dataBits, int parity, int stopBits, int flowcontrol, int inputBufferSize, int outputBufferSize)

This constructor creates a new UARTConfig with the specified hardware addressing information and configuration parameters. The platform or underlying driver may or may not allocate the requested sizes for the input and output buffers.
public int getUARTNumber()

This method returns the configured UART number.
public int getFlowControlMode()

This method returns the configured flow control mode.
public int getBaudRate()

This method returns the configured default/initial speed in Bauds.
public int getDataBits()

This method returns the configured default/initial number of bits per character.
public int getParity()

This method returns the configured default/initial parity.
public int getStopBits()

This method returns the configured default/initial number of stop bits per character.
public int getInputBufferSize()

This method returns the requested input buffer size. The platform/underlying driver may or may not allocate the requested size for the input buffer.
public int getOutputBufferSize()

This method returns the requested output buffer size. The platform/underlying driver may or may not allocate the requested size for the output buffer.

The UARTEvent Class

The UARTEvent class encapsulates events fired by peripherals that implement the UART interface.

The UARTEvent class consists of three constants:

public static final int INPUT_DATA_AVAILABLE

Event ID indicating that input data is available for reading.
public static final int INPUT_BUFFER_OVERRUN

Event ID indicating that input buffer overrun.
public static final int OUTPUT_BUFFER_EMPTY

Event ID indicating that the output buffer is empty and that additional data may be written.

The UARTEvent class also consists of two constructors and one method:

public UARTEvent(UART uart, int id)

This constructor creates a new UARTEvent with the specified value. The event is then time-stamped with the current time.
public UARTEvent(UART uart, int id, long timeStamp, int timeStampMicros)

This constructor creates a new UARTEvent with the specified value and timestamp.
public int getID()

This method returns the event's ID..