Sensor

传感器

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.

Android 的 传感器框架 支持的传感器类型相对广泛，使用该框架可以测量物理环境的状态并从应用中读取原始数据。而通过使用传感器驱动，您的应用可以扩展这个框架，并且可以添加连接到 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.

从这些传感器中获取的数据被通过 和 Android 内置传感器相同的 SensorManager APIs 传递。 您的应用可以实现一个驱动，用来连接一个新的已知类型的传感器设备，例如加速度计，或者是当前 Android 未定义的设备类型，比如血糖传感器。

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.

当监听器已被注册接收传感器更新时，framework 会间歇性地拉取您的驱动。为了响应拉取请求以提供新的数据，需要继承 UserSensorDriver 类并覆写 read() 方法。每次调用这个方法时，应当返回包含当前传感器数据的 UserSensorReading 实例。

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.

当传感器驱动不能产生数据更新时，framework 也可能会调用 read() 方法，当这种情况出现时，您的驱动应当抛出一个 IOException。

  1. UserSensorDriver mDriver = new UserSensorDriver() {
  2.     // Sensor data values
  3.     float x, y, z;
  5.     @Override
  6.     public UserSensorReading read() {
  7.         try {
  8.             // ...read the sensor hardware...
  10.             // Return a new reading
  11.             return new UserSensorReading(new float[]{x, y, z});
  12.         } (catch Exception e) {
  13.             // Error occurred reading the sensor hardware
  14.             throw new IOException("Unable to read sensor");
  15.         }
  16.     }
  17. };

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:

如果您的传感器支持低功耗或睡眠模式，重写驱动实现中的 setEnabled() 方法来激活该功能。Framework 调用这个方法来表征这个传感器应当被唤起传递数据或是进入睡眠模式节能：

  1. UserSensorDriver mDriver = new UserSensorDriver() {
  2.     ...
  4.     // Called by the framework to toggle low power modes
  5.     @Override
  6.     public void setEnabled(boolean enabled) {
  7.         if (enabled) {
  8.             // Exit low power mode
  9.         } else {
  10.             // Enter low power mode
  11.         }
  12.     }
  13. };

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:

在 Android framework 中添加一种新的传感器需要：

  1. Use the UserSensor.Builder to declare the sensor’s type.

    使用 UserSensor.Builder 来声明一种传感器类型。

    For most apps, the sensor type should match one of Android’s existing known Sensor types.

    对于大部分应用来说，传感器类型应当与 Android 系统中已有的 传感器 类型匹配。

  2. Provide the sensor name and vendor name of your driver.

    为您的驱动提供传感器名称和供应商的名称。

  3. 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.

    在构建器中提供您的传感器的范围，分辨率，更新频率（延迟），以及能耗需求（如果可用的话）。这些值可以帮助 framework 根据 SensorManager 收到的需求选择最佳的传感器。

  4. Attach your UserSensorDriver implementation with the setDriver() method.

    使用 setDriver() 方法添加您的 UserSensorDriver 实现。

  1. UserSensor accelerometer = UserSensor.builder()
  2.         .setName("GroveAccelerometer")
  3.         .setVendor("Seeed")
  4.         .setType(Sensor.TYPE_ACCELEROMETER)
  5.         .setDriver(mDriver)
  6.         .build();

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

当实现一种 Android 系统未定义的传感器时：

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

    在构建器中使用 setCustomType() 替换setType()。

  2. Provide a numeric sensor type that is TYPE_DEVICE_PRIVATE_BASE or larger.

    提供一个数值为 TYPE_DEVICE_PRIVATE_BASE 或更大的数字型传感器类型。

  3. Include a unique string name for the sensor type. This name should be unique system-wide, so using reverse domain notation is recommended.

    为传感器类型提供一个唯一的字符名。这个名称应当在系统范围内唯一，因此推荐使用倒置的域名记号。

  4. Include the sensor reporting mode.

    提供传感器的上报模式。

  1. UserSensor custom = UserSensor.builder()
  2.         .setName("MySensor")
  3.         .setVendor("MyCompany")
  4.         .setCustomType(Sensor.TYPE_DEVICE_PRIVATE_BASE,
  5.                 "com.example.mysensor",
  6.                 Sensor.REPORTING_MODE_CONTINUOUS)
  7.         .setDriver(mDriver)
  8.         .build();
  2. ## Registering the sensor
  4. ## 注册传感器
  6. * * *
  8. Connect your new sensor to the framework by registering it with the `UserDriverManager`:
  10. 使用 `UserDriverManager` 将新传感器注册到 framework 中：
  12. ~~~ java
  13. public class SensorDriverService extends Service {
  15.     UserSensor mAccelerometer;
  17.     @Override
  18.     public void onCreate() {
  19.         super.onCreate();
  20.         ...
  21.         UserDriverManager manager = UserDriverManager.getManager();
  23.         // Create a new driver implementation
  24.         mAccelerometer = ...;
  25.         // Register the new driver with the framework
  26.         manager.registerSensor(mAccelerometer);
  27.     }
  29.     @Override
  30.     public void onDestroy() {
  31.         super.onDestroy();
  32.         ...
  33.         UserDriverManager manager = UserDriverManager.getManager();
  34.         // Unregister the driver when finished
  35.         manager.unregisterSensor(mAccelerometer);
  36.     }
  37. }

With the driver properly registered, apps can receive updates from the associated device using the existing Android sensor framework services.

当传感器被正确注册后，应用可以使用 Android 现有的 传感器框架服务 从相关传感器设备处获取更新。

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:

在传感器可用之前，注册过程可能会需要一些时间。在注册传感器数据监听器之前，对用户传感器敏感的应用应当注册一个 DynamicSensorCallback ，这样，当传感器可用时，它将会告知应用：

  1. public class SensorActivity extends Activity implements SensorEventListener {
  3.     private SensorManager mSensorManager;
  4.     private SensorCallback mCallback = new SensorCallback();
  6.     @Override
  7.     protected void onCreate(Bundle savedInstanceState) {
  8.         super.onCreate(savedInstanceState);
  9.         ...
  10.         mSensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
  11.         mSensorManager.registerDynamicSensorCallback(mCallback);
  12.     }
  14.     @Override
  15.     protected void onDestroy() {
  16.         super.onDestroy();
  17.         ...
  18.         mSensorManager.unregisterDynamicSensorCallback(mCallback);
  19.     }
  21.     @Override
  22.     public void onSensorChanged(SensorEvent event) {
  23.         ...
  24.     }
  26.     @Override
  27.     public void onAccuracyChanged(Sensor sensor, int accuracy) {
  28.         ...
  29.     }
  31.     // Listen for registration events from the sensor driver
  32.     private class SensorCallback extends SensorManager.DynamicSensorCallback {
  33.         @Override
  34.         public void onDynamicSensorConnected(Sensor sensor) {
  35.             // Begin listening for sensor readings
  36.             mSensorManager.registerListener(SensorActivity.this, sensor,
  37.                     SensorManager.SENSOR_DELAY_NORMAL);
  38.         }
  40.         @Override
  41.         public void onDynamicSensorDisconnected(Sensor sensor) {
  42.             // Stop receiving sensor readings
  43.             mSensorManager.unregisterListener(SensorActivity.this);
  44.         }
  45.     }
  46. }

Adding the required permission

添加必需权限

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

在您应用的清单文件中添加用户驱动所需的权限：

  1. <uses-permission android:name="com.google.android.things.permission.MANAGE_SENSOR_DRIVERS" />