GpioDriver

public interface GpioDriver
implements Gpio

com.google.android.things.userdriver.pio.GpioDriver

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

Summary

Inherited constants

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

Public methods

abstract void close()

Closes the GPIO pin.

default String getName()

Returns null.

abstract void open()

Opens the GPIO pin.

abstract void registerGpioCallback(Handler handler, GpioCallback callback)

Registers a callback for GPIO edge interrupts.

abstract void unregisterGpioCallback(GpioCallback callback)

Unregisters an interrupt callback.

Inherited methods

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

Public methods

close

void close ()

Closes the GPIO pin. This will be called when the GPIO 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 the GPIO 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 GPIO pin. This will be called when ownership of a GPIO is obtained. The driver should do any initialization needed to configure the GPIO pin for use here.

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

registerGpioCallback

void registerGpioCallback (Handler handler, 
                GpioCallback callback)

Registers a callback for GPIO edge interrupts. This API is shared with a standard Gpio, but for a GpioDriver some simplifying assumptions can be made:

  • Only one GpioCallback will ever be registered at a time.
  • The Gpio argument to the GpioCallback methods are not needed, so any value (or null) may be provided when making callbacks.
  • The return value from onGpioEdge(Gpio) will always be true and can be safely ignored.
  • The driver is allowed but not required to post callbacks on the provided Handler.
  • Currently the error value passed to onGpioError(Gpio, int) is ignored and OsConstants.ENODEV is always used instead.
Example: Shared GPIO interrupt line
This is common with I2C-to-GPIO expanders, where a bank of GPIOs will share one common interrupt line. The idea is that the GpioDriver receives the common interrupt signal, figures out which of the expander's GPIOs it actually came from, and then dispatch the interrupt to that particular GpioDriver. 
 // Implements a single GPIO on the expander.
 public class SharedInterruptGpioDriver implements GpioDriver {
     // The underlying GPIO shared between the whole GPIO bank.
     private Gpio mInterruptGpio;

     // Our callback implementation to handle shared GPIO interrupts.
     private SharedGpioCallback mSharedCallback;

     @Override
     public void registerGpioCallback(Handler handler, GpioCallback callback)
             throws IOException {
         mSharedCallback = new SharedGpioCallback(callback);
         mInterruptGpio.registerGpioCallback(handler, mSharedCallback);
     }

     @Override
     public void unregisterGpioCallback(GpioCallback callback) {
         mInterruptGpio.unregisterGpioCallback(mSharedCallback);
         mSharedCallback = null;
     }

     // Intercept the shared GPIO callback and if it was meant for us, dispatch to the
     // user-facing callback.
     private class SharedGpioCallback implements GpioCallback {
         // The callback registers on this GPIO driver that we dispatch events to.
         private final GpioCallback mRegisteredCallback;

         public SharedGpioCallback(GpioCallback registeredCallback) {
             mRegisteredCallback = registeredCallback;
         }

         @Override
         public boolean onGpioEdge(Gpio gpio) {
             // Do any checking necessary to determine if this is the GPIO that fired.
             //
             // This is for example purposes only and may be inefficient since each GPIO
             // checks the interrupt - better would be a single interrupt handler which
             // dispatches to the proper GPIO driver.
             if (thisGpioHadInterrupt()) {
                 return mRegisteredCallback.onGpioEdge(gpio);
             }

             // If it wasn't meant for this GPIO, do nothing and return true to keep
             // listening for events.
             return true;
         }

         @Override
         public void onGpioError(Gpio gpio, int error) {
             // The underlying interrupt GPIO failed, we won't get any more callbacks.
             mRegisteredCallback.onGpioError(gpio, 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 GpioCallback: GpioCallback to register; only one will ever be registered at a time.
Throws
IOException if this GPIO doesn't support interrupts.

unregisterGpioCallback

void unregisterGpioCallback (GpioCallback callback)

Unregisters an interrupt callback. Will only be called if a GpioCallback has been previously registered.

Parameters
callback GpioCallback: GpioCallback to unregister.