UartDeviceDriver

public interface UartDeviceDriver
implements UartDevice

com.google.android.things.userdriver.pio.UartDeviceDriver


UART user driver. A UartDeviceDriver must implement all UART functions, but additionally this class provides an open() function that will be called whenever a process obtains ownership of the UART, to match the existing close() function.

Summary

Inherited constants

From interface com.google.android.things.pio.UartDevice

Public methods

abstract void close()

Closes the UART.

default String getName()

Returns null.

abstract void open()

Opens the UART.

abstract void registerUartDeviceCallback(Handler handler, UartDeviceCallback callback)

Registers an interrupt callback on the UART.

Inherited methods

From interface com.google.android.things.pio.UartDevice
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Public methods

close

void close ()

Closes the UART. This will be called when the UART is closed by its owner. Any resources that need to be cleaned up should be done so here. This method may throw IOException to indicate I/O failure, but will still be considered closed and may attempt to be re-opened in the future.

Throws
IOException on I/O failure; the driver will still be considered closed.

getName

String getName ()

Returns null. I/O user drivers can be registered under any name so this returns null by default. Child classes may override this if other behavior is desired.

Returns
String

open

void open ()

Opens the UART. This will be called when ownership of a UART is obtained. The driver should do any initialization needed to configure the UART for use here.

Throws
IOException on I/O failure; the driver will remain closed.

registerUartDeviceCallback

void registerUartDeviceCallback (Handler handler, 
                UartDeviceCallback callback)

Registers an interrupt callback on the UART. See registerGpioCallback(Handler, GpioCallback) for information on how callbacks work for user drivers. A typical use-case for UART user driver interrupts is an external UART chip which uses a GPIO line to indicate when data is ready to read. In this case, the driver code might look something like this:

 public class UartWithInterruptDriver implements UartDeviceDriver {
     // The data-ready signal GPIO.
     private Gpio mInterruptGpio;

     // Our GPIO interrupt handler.
     private InterruptCallback mInterruptCallback;

     // Implement other UartDeviceDriver functionality.
     // ...

     @Override
     public void registerUartDeviceCallback(Handler handler, UartDeviceCallback callback)
             throws IOException {
         // Configure mInterruptGpio to begin listening for interrupts.
         mInterruptCallback = new InterruptCallback(callback);
         mInterruptGpio.setEdgeTriggerType(Gpio.EDGE_RISING);
         mInterruptGpio.registerGpioCallback(handler, mInterruptCallback);
     }

     @Override
     public void unregisterUartDeviceCallback(UartDeviceCallback callback) {
         mInterruptGpio.unregisterGpioCallback(mInterruptCallback);
         mInterruptGpio.setEdgeTriggerType(Gpio.EDGE_NONE);
         mInterruptCallback = null;
     }

     // Bounces the underlying GPIO callbacks into the registered UART callback.
     private class InterruptCallback implements GpioCallback {
         private final UartDeviceCallback mUartCallback;

         public InterruptCallback(UartDeviceCallback uartCallback) {
             mUartCallback = uartCallback;
         }

         @Override
         public boolean onGpioEdge(Gpio gpio) {
             return mUartCallback.onUartDeviceDataAvailable(null);
         }

         @Override
         public void onGpioError(Gpio gpio, int error) {
             // The underlying interrupt GPIO failed, we won't get any more callbacks.
             mUartCallback.onUartDeviceError(null, error);
         }
     }
 }
 

Parameters
handler Handler: Handler to optionally run callbacks on. Provided as a convenience if needed, but it's not required to execute callbacks on this.

callback UartDeviceCallback: UartDeviceCallback to register; only one will ever be registered at a time.

Throws
IOException if this UART doesn't support interrupts.