The Android sensor framework

supports a wide variety of sensor types to measure the conditions of the

physical environment and read the raw data from apps. Using sensor drivers, your

apps can extend this framework and add new sensor devices connected over

Peripheral I/O.

The data from these sensors is delivered through the same

SensorManager APIs as the

built-in Android sensors. Your app can implement a driver to connect a new

sensor of a known type, such as an accelerometer, or a sensor type that Android

doesn't currently define, such as a blood glucose sensor.

Adding the required permission

Add the required permission for the user driver to your app's manifest file:

Note:See the

BMx280 Sensor driver

sample on GitHub.

Implementing the driver

The framework polls your driver periodically when listeners are registered for

sensor updates. To respond to poll requests for new data, extend the

UserSensorDriver class and override the read() method. Each call to read

should return a new UserSensorReading containing the current sensor data.

Note:For more information on the data format expected for known sensor types,

see sensor event values.

The framework may call read() at a time when the driver is not able to produce

a sensor reading. When this occurs, your driver should throw an IOException.

UserSensorDriver driver = new UserSensorDriver() {

// Sensor data values

float x, y, z;

@Override

public UserSensorReading read() {

try {

// ...read the sensor hardware...

// Return a new reading

return new UserSensorReading(new float[]{x, y, z});

} catch (Exception e) {

// Error occurred reading the sensor hardware

throw new IOException("Unable to read sensor");

}

}

};

If your sensor supports low power or sleep modes, override the setEnabled()

method of your driver implementation to activate them. The framework calls this

method to indicate that sensors should be ramped up to deliver readings or put

to sleep to save power:

UserSensorDriver driver = new UserSensorDriver() {

...

// Called by the framework to toggle low power modes

@Override

public void setEnabled(boolean enabled) {

if (enabled) {

// Exit low power mode

} else {

// Enter low power mode

}

}

};Note:Sensors without low power modes can still use this callback to increase or

reduce the reporting frequency of the data in order to manage power consumption.

Describing the sensor

To add a new sensor driver to the Android framework:

Use the UserSensor.Builder to declare the sensor's type.

For most apps, the sensor type should match one of Android's existing known

Sensor types.

Provide the sensor name and vendor name of your driver.

Apply the range, resolution, update frequency (delay), and power

requirements (if available) of your sensor to the builder. These values

assist the framework in selecting the best sensor based on the requests

received by SensorManager.

Attach your UserSensorDriver implementation with the setDriver() method.

UserSensor accelerometer = UserSensor.builder()

.setName("GroveAccelerometer")

.setVendor("Seeed")

.setType(Sensor.TYPE_ACCELEROMETER)

.setDriver(driver)

.build();

When implementing a sensor for which Android does not have a defined type:

Replace setType() with setCustomType() in the builder.

Provide a numeric sensor type that is TYPE_DEVICE_PRIVATE_BASE or larger.

Include a unique string name for the sensor type. This name should be unique

system-wide, so using reverse domain notation is recommended.

Include the sensor reporting mode.

UserSensor custom = UserSensor.builder()

.setName("MySensor")

.setVendor("MyCompany")

.setCustomType(Sensor.TYPE_DEVICE_PRIVATE_BASE,

"com.example.mysensor",

Sensor.REPORTING_MODE_CONTINUOUS)

.setDriver(driver)

.build();

Registering the sensor

Connect your new sensor to the framework by registering it with the

UserDriverManager:

import com.google.android.things.userdriver.UserDriverManager;

...

public class SensorDriverService extends Service {

UserSensor accelerometer;

@Override

public void onCreate() {

super.onCreate();

...

UserDriverManager manager = UserDriverManager.getInstance();

// Create a new driver implementation

accelerometer = ...;

// Register the new driver with the framework

manager.registerSensor(accelerometer);

}

@Override

public void onDestroy() {

super.onDestroy();

...

UserDriverManager manager = UserDriverManager.getInstance();

// Unregister the driver when finished

manager.unregisterSensor(accelerometer);

}

}

With the driver properly registered, apps can receive updates from the

associated device using the existing Android sensor framework

services.

The registration process can take some time before the sensor is available to

clients. Apps interested in a user sensor should register a

DynamicSensorCallback

to be notified when it is available before registering a listener for sensor

readings:

public class SensorActivity extends Activity implements SensorEventListener {

private SensorManager sensorManager;

private SensorCallback callback = new SensorCallback();

@Override

protected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

...

sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);

sensorManager.registerDynamicSensorCallback(callback);

}

@Override

protected void onDestroy() {

super.onDestroy();

...

sensorManager.unregisterDynamicSensorCallback(callback);

}

@Override

public void onSensorChanged(SensorEvent event) {

...

}

@Override

public void onAccuracyChanged(Sensor sensor, int accuracy) {

...

}

// Listen for registration events from the sensor driver

private class SensorCallback extends SensorManager.DynamicSensorCallback {

@Override

public void onDynamicSensorConnected(Sensor sensor) {

// Begin listening for sensor readings

sensorManager.registerListener(SensorActivity.this, sensor,

SensorManager.SENSOR_DELAY_NORMAL);

}

@Override

public void onDynamicSensorDisconnected(Sensor sensor) {

// Stop receiving sensor readings

sensorManager.unregisterListener(SensorActivity.this);

}

}

}