Package jdk.dio.generic

Interfaces and classes for controlling devices using generic I/O operations.

See: Description

Interface Summary

Interface	Description
GenericBufferIODevice	The GenericBufferIODevice interface defines generic methods for accessing and controlling devices using read and write operations.
GenericDevice	The GenericDevice interface defines methods for setting and getting device-specific configuration and access (I/O) controls as well as registering event listeners.
GenericEventListener	The GenericEventListener interface defines methods for getting notified of events fired by devices that implement the GenericDevice interface.

Class Summary

Class	Description
GenericDeviceConfig	The GenericDeviceConfig class encapsulates the hardware addressing information of generic device.
GenericDeviceConfig.Builder	The Builder class allows for creating and initializing GenericDeviceConfig objects.
GenericDeviceControl<T>	The class GenericDeviceControl encapsulates a generic device's configuration and access (I/O) control.
GenericEvent	The GenericEvent class encapsulates events fired by devices that implement the GenericDevice interface.
GenericPermission	The GenericPermission class defines permissions for g device access.

Package jdk.dio.generic Description

Interfaces and classes for controlling devices using generic I/O operations.

The generic device API allows for accessing devices when there are no more specific standard Java API such as I2CDevice, SPIDevice, GPIOPin or GPIOPort...

This API offers 2 main interfaces:

GenericDevice

Device control operations and event listener registration. A device may implements this sole interface if it does not support any read and write operations.

GenericBufferIODevice

Device control operations and event listener registration as inherited from GenericDevice and byte buffer read and write operations.

In order to access a device using its generic interface, an application should first open and obtain a GenericDevice instance for the device using its numeric ID, name, type (interface) and/or properties:

Using its ID

 GenericDevice device = (GenericDevice) DeviceManager.open(17);
 

Using its name and interface

 GeneriBufferIODevice device = DeviceManager.open("STORAGE", GeneriBufferIODevice.class, null);
 

Once the device opened, the application can set and get controls, read and write data using methods of the GenericDevice or GenericBufferIODevice interfaces.

 device.read(buffer, 0, buffer.length);
 

When done, the application should call the GenericDevice.close method to close the Generic device.

 device.close();
 

The following sample code gives an example of using the Generic API to access a Real Time Clock device:

 public static final int EVT_ALARM = 0;
 public static final GenericDeviceControl<Byte> SECONDS = new GenericDeviceControl<>(0, Byte.class);
 public static final GenericDeviceControl<Byte> SEC_ALARM = new GenericDeviceControl<>(1, Byte.class);
 public static final GenericDeviceControl<Byte> MINUTES = new GenericDeviceControl<>(2, Byte.class);
 public static final GenericDeviceControl<Byte> MIN_ALARM = new GenericDeviceControl<>(3, Byte.class);
 public static final GenericDeviceControl<Byte> HR_ALARM = new GenericDeviceControl<>(4, Byte.class);
 public static final GenericDeviceControl<Byte> HOURS = new GenericDeviceControl<>(5, Byte.class);
 public static final GenericDeviceControl<Boolean> ALARM_ENABLED = new GenericDeviceControl<>(6, Boolean.class);
 
 // Sets the daily alarm for after some delay
 public void setAlarm(byte delaySeconds, byte delayMinutes, byte delayHours) throws IOException, DeviceException {
     try (GenericDevice rtc = DeviceManager.open("RTC", GenericDevice.class, (String) null)) {
         byte currentSeconds = rtc.getControl(SECONDS);
         byte currentMinutes = rtc.getControl(MINUTES);
         byte currentHours = rtc.getControl(HOURS);
         byte i = (byte) ((currentSeconds + delaySeconds) % 60);
         byte j = (byte) ((currentSeconds + delaySeconds) / 60);
         rtc.setControl(SEC_ALARM, i);
         i = (byte) ((currentMinutes + delayMinutes + j) % 60);
         j = (byte) ((currentMinutes + delayMinutes + j) / 60);
         rtc.setControl(MIN_ALARM, i);
         i = (byte) ((currentHours + delayHours + j) % 24);
         rtc.setControl(HR_ALARM, i);
 
         rtc.setEventListener(EVT_ALARM, new GenericEventListener() {
 
             public void eventDispatched(GenericEvent event) {
                 GenericDevice rtc = event.getDevice();
                 // Notify application of alarm
             }
         });
         // Enable alarm.
         rtc.setControl(ALARM_ENABLED, true);
     }
 }
 

The following sample code gives an example of using the Generic API to control and capture audio input from a microphone such a USB microphone exposed as a GenericDevice:

 public static final int EVT_VOLUME_CHANGED = 0;
 public static final GenericDeviceControl<Float> MIC_VOLUME = new GenericDeviceControl<>(0, Float.class);
 public static final GenericDeviceControl<Float> MIC_SAMPLE_RATE = new GenericDeviceControl<>(1, Float.class);
 public static final GenericDeviceControl<Boolean> MIC_AUTOMATIC_GAIN = new GenericDeviceControl<>(2, Boolean.class);
 public static final GenericDeviceControl<Boolean> MIC_MUTE = new GenericDeviceControl<>(3, Boolean.class);
 
 public void audioCapture(ByteBuffer buffer, float sampleRate, boolean agc) throws IOException, DeviceException {
     try (GenericBufferIODevice mic = DeviceManager.open("MICROPHONE", GenericBufferIODevice.class, (String) null)) {
         mic.setControl(MIC_SAMPLE_RATE, sampleRate);
         mic.setControl(MIC_AUTOMATIC_GAIN, agc);
         mic.setControl(MIC_MUTE, false);
 
         mic.setEventListener(EVT_VOLUME_CHANGED, new GenericEventListener() {
 
             public void eventDispatched(GenericEvent event) {
                 GenericDevice mic = event.getDevice();
                 try {
                     float currentVolume = mic.getControl(MIC_VOLUME);
                     // ...
                 } catch (ClosedDeviceException ex) {
                     ex.printStackTrace();
                 } catch (IOException ex) {
                     ex.printStackTrace();
                 }
             }
         });
         mic.read(buffer);
     }
 }
 

The preceding examples are using a try-with-resources statement; the GenericDevice.close method is automatically invoked by the platform at the end of the statement

Unless otherwise noted, permission and security checks that may cause a SecurityException to be thrown must be performed in priority to any other checks or operations once performed the checking of the input parameters from which the permission target names and action lists are retrieved and assembled.

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a NullPointerException to be thrown.

Since:

1.0