sdk/fidl/fuchsia.input.report/sensor.fidl

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.input.report;

/// A hardcoded number of max sensor values. This should be increased in the future
/// if we ever see a sensor with more values.
const uint32 SENSOR_MAX_VALUES = 100;

/// Each sensor value has a corresponding SensorType, which explains what the
/// value is measuring in the world.
enum SensorType : uint32 {
    /// Acceleration on the X axis.
    ACCELEROMETER_X = 1;
    /// Acceleration on the Y axis.
    ACCELEROMETER_Y = 2;
    /// Acceleration on the Z axis.
    ACCELEROMETER_Z = 3;
    /// Strength of the Magnetic Field in the X axis.
    MAGNETOMETER_X = 4;
    /// Strength of the Magnetic Field in the Y axis.
    MAGNETOMETER_Y = 5;
    /// Strength of the Magnetic Field in the Z axis.
    MAGNETOMETER_Z = 6;
    /// Angular Velocity in the X direction moving counter-clockwise.
    GYROSCOPE_X = 7;
    /// Angular Velocity in the Y direction moving counter-clockwise.
    GYROSCOPE_Y = 8;
    /// Angular Velocity in the Z direction moving counter-clockwise.
    GYROSCOPE_Z = 9;
    /// Ambient level of Light.
    LIGHT_ILLUMINANCE = 10;
    /// Ambient level of Red Light.
    LIGHT_RED = 11;
    /// Ambient level of Green Light.
    LIGHT_GREEN = 12;
    /// Ambient level of Blue Light.
    LIGHT_BLUE = 13;
};

/// A `SensorAxis` is a normal `Axis` with an additional `SensorType` to describe what the
/// axis is measuring.
struct SensorAxis {
    Axis axis;
    SensorType type;
};

/// Describes the format of the input report that will be sent from the sensor
/// to the device.
table SensorInputDescriptor {
    /// Each `SensorAxis` in `values` describes what a sensor is measuring and its range.
    /// These will directly correspond to the values in `SensorReport`.
    1: vector<SensorAxis>:SENSOR_MAX_VALUES values;
};

/// `SensorReportingState` determines when a sensor will send reports.
enum SensorReportingState : uint32 {
    /// No events will be sent from the sensor.
    REPORT_NO_EVENTS = 1;
    /// All events will be sent from the sensor. For most sensors, this
    /// frequency can be set by `report_interval`.
    REPORT_ALL_EVENTS = 2;
    /// Only events that cross a threshold will be reported.
    REPORT_THRESHOLD_EVENTS = 3;
};

/// Describes the format of the sensor's feature report. Feature reports can be
/// requested from the sensor, or sent to the sensor.
table SensorFeatureDescriptor {
    /// Describes the minimum and maximum reporting interval this sensor
    /// supports.
    1: Axis report_interval;
    /// If this is true then SensorFeatureReport supports setting a
    /// SensorReportingState.
    3: bool supports_reporting_state;
    /// Sets the sensitivity for the given `SensorType`.
    2: vector<SensorAxis>:SENSOR_MAX_VALUES sensitivity;
    /// Sets the high threshold values for the given `SensorType`.
    4: vector<SensorAxis>:SENSOR_MAX_VALUES threshold_high;
    /// Sets the low threshold values for the given `SensorType`.
    5: vector<SensorAxis>:SENSOR_MAX_VALUES threshold_low;
};

/// The capabilities of a sensor device.
table SensorDescriptor {
    1: SensorInputDescriptor input;
    2: SensorFeatureDescriptor feature;
};

/// `SensorReport` gives the values measured by a sensor at a given point in time.
table SensorInputReport {
    /// The ordering of `values` will always directly correspond to the ordering of
    /// the values in `SensorDescriptor`.
    1: vector<int64>:SENSOR_MAX_VALUES values;
};

/// A SensorFeatureReport describes the features of a given sensor. If a
/// FeatureReport is sent to the Input Device it sets the configuration of the device.
/// If a FeatureReport is requested from the Input Device it shows the device's
/// current configuration.
table SensorFeatureReport {
    /// The time between reports sent by the sensor.
    1: int64 report_interval;
    /// This determines when the sensor will send reports.
    3: SensorReportingState reporting_state;
    /// The sensitivity for various `SensorType`. This vector must be given in
    /// the order of the descriptor's `sensitivity` vector.
    2: vector<int64>:SENSOR_MAX_VALUES sensitivity;
    /// The high thresholds for various `SensorType`. This vector must be given in
    /// the order of the descriptor's `threshold_high` vector.
    4: vector<int64>:SENSOR_MAX_VALUES threshold_high;
    /// The low thresholds for various `SensorType`. This vector must be given in
    /// the order of the descriptor's `threshold_low` vector.
    5: vector<int64>:SENSOR_MAX_VALUES threshold_low;
};