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 reports. Because report ID is only 8 bits, only 255
/// different reports are allowed at a time.
const MAX_REPORT_COUNT uint32 = 255;

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

/// Each sensor value has a corresponding SensorType, which explains what the
/// value is measuring in the world.
type SensorType = flexible enum : 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.
type SensorAxis = struct {
    axis Axis;
    type SensorType;
};

/// Describes the format of the input report that will be sent from the sensor
/// to the device.
type SensorInputDescriptor = table {
    /// Each `SensorAxis` in `values` describes what a sensor is measuring and its range.
    /// These will directly correspond to the values in `SensorReport`.
    1: values vector<SensorAxis>:SENSOR_MAX_VALUES;
    /// ReportID of current descriptor. Report with same report ID should be
    /// associated with this descriptor.
    2: report_id uint8;
};

/// `SensorReportingState` determines when a sensor will send reports.
type SensorReportingState = flexible enum : 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.
type SensorFeatureDescriptor = table {
    /// Describes the minimum and maximum reporting interval this sensor
    /// supports.
    1: report_interval Axis;
    /// If this is true then SensorFeatureReport supports setting a
    /// SensorReportingState.
    3: supports_reporting_state bool;
    /// Sets the sensitivity for the given `SensorType`.
    2: sensitivity vector<SensorAxis>:SENSOR_MAX_VALUES;
    /// Sets the high threshold values for the given `SensorType`.
    4: threshold_high vector<SensorAxis>:SENSOR_MAX_VALUES;
    /// Sets the low threshold values for the given `SensorType`.
    5: threshold_low vector<SensorAxis>:SENSOR_MAX_VALUES;
    /// Describes the minimum and maximum sampling rate this sensor supports.
    6: sampling_rate Axis;
    /// ReportID of current descriptor. Report with same report ID should be
    /// associated with this descriptor.
    7: report_id uint8;
};

/// The capabilities of a sensor device.
type SensorDescriptor = table {
    1: input vector<SensorInputDescriptor>:MAX_REPORT_COUNT;
    2: feature vector<SensorFeatureDescriptor>:MAX_REPORT_COUNT;
};

/// `SensorReport` gives the values measured by a sensor at a given point in time.
type SensorInputReport = table {
    /// The ordering of `values` will always directly correspond to the ordering of
    /// the values in `SensorDescriptor`.
    1: values vector<int64>:SENSOR_MAX_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.
type SensorFeatureReport = table {
    /// The time between reports sent by the sensor.
    1: report_interval int64;
    /// This determines when the sensor will send reports.
    3: reporting_state SensorReportingState;
    /// The sensitivity for various `SensorType`. This vector must be given in
    /// the order of the descriptor's `sensitivity` vector.
    2: sensitivity vector<int64>:SENSOR_MAX_VALUES;
    /// The high thresholds for various `SensorType`. This vector must be given in
    /// the order of the descriptor's `threshold_high` vector.
    4: threshold_high vector<int64>:SENSOR_MAX_VALUES;
    /// The low thresholds for various `SensorType`. This vector must be given in
    /// the order of the descriptor's `threshold_low` vector.
    5: threshold_low vector<int64>:SENSOR_MAX_VALUES;
    /// The rate at which the sensor is sampled.
    6: sampling_rate int64;
};