sdk/fidl/fuchsia.sensors.types/types.fidl

// Copyright 2024 The Fuchsia Authors.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.sensors.types;

using fuchsia.math as math;
using zx;

/// Labels for different types of sensors.
///
/// These values are from:
/// https://android.googlesource.com/platform/hardware/interfaces/+/main/sensors/1.0/types.hal#118
type SensorType = flexible enum : uint32 {
    /// Raw inertial measurement.
    ACCELEROMETER_UNCALIBRATED = 35;
    GYROSCOPE_UNCALIBRATED = 16;
    MAGNETIC_FIELD_UNCALIBRATED = 14;

    /// Calibrated inertial measurement.
    ACCELEROMETER = 1;
    GYROSCOPE = 4;
    MAGNETIC_FIELD = 2;

    /// Derived/fused from inertial measurement.
    ORIENTATION = 3;
    GRAVITY = 9;
    LINEAR_ACCELERATION = 10;
    ROTATION_VECTOR = 11;
    GAME_ROTATION_VECTOR = 15;
    SIGNIFICANT_MOTION = 17;
    STEP_DETECTOR = 18;
    STEP_COUNTER = 19;
    GEOMAGNETIC_ROTATION_VECTOR = 20;
    TILT_DETECTOR = 22;
    WAKE_GESTURE = 23;
    GLANCE_GESTURE = 24;
    PICK_UP_GESTURE = 25;
    WRIST_TILT_GESTURE = 26;
    DEVICE_ORIENTATION = 27;
    POSE_6DOF = 28;
    STATIONARY_DETECT = 29;
    MOTION_DETECT = 30;
    LOW_LATENCY_OFFBODY_DETECT = 34;

    /// Environmental.
    LIGHT = 5;
    PRESSURE = 6;
    PROXIMITY = 8;
    RELATIVE_HUMIDITY = 12;
    AMBIENT_TEMPERATURE = 13;

    /// Biometric.
    HEART_RATE = 21;
    HEART_BEAT = 31;

    /// Base for device manufacturers' private sensor types.
    DEVICE_PRIVATE_BASE = 0x10000;
};

/// Describes a sensor's wake-up behavior. A wake-up sensor will wake up the
/// application processor when there is new data available. A non wake-up sensor
/// will not.
type SensorWakeUpType = flexible enum : uint32 {
    NON_WAKE_UP = 0;

    WAKE_UP = 1;
};

/// Describes a sensor's reporting mode.
type SensorReportingMode = flexible enum : uint32 {
    /// Continous reporting will continuously deliver samples, subject to the
    /// requested sampling rate and maximum reporting latency.
    CONTINUOUS = 0;

    /// On-change reporting will deliver a sample any time the sensor value
    /// changes, subject to the requested sampling rate and max reporting
    /// latency.
    ON_CHANGE = 1;

    // One-shot reporting will deliver a single sample and then disable the
    // sensor.
    ONE_SHOT = 2;
};

/// Uniquely identifies a sensor in the sensor APIs.
///
/// Defined to be compatible with:
/// https://android.googlesource.com/platform/hardware/interfaces/+/main/sensors/1.0/types.hal#817
alias SensorId = int32;

/// A revision number for the part/driver combination. The value must be updated
/// when the driver is updated in a way that changes the output of the sensor.
/// This is important for fused sensors when the fusion algorithm is updated.
///
/// Defined to be compatible with:
/// https://android.googlesource.com/platform/hardware/interfaces/+/main/sensors/1.0/types.hal#834
alias SensorVersion = int32;

/// All the information to describe a specific sensor and its output.
type SensorInfo = table {
    /// Identifies this sensor.
    ///
    /// Required.
    1: sensor_id SensorId;

    /// Name of this sensor.
    /// All sensors of the same "type" must have a different "name".
    ///
    /// Required.
    2: name string:MAX;

    /// Vendor of the hardware part.
    ///
    /// Required.
    3: vendor string:MAX;

    /// Version number. See documentation for SensorVersion.
    ///
    /// Required.
    4: version SensorVersion;

    /// This sensor's type.
    ///
    /// Required.
    5: sensor_type SensorType;

    /// The wake-up behavior of this sensor.
    ///
    /// Required.
    6: wake_up SensorWakeUpType;

    /// The reporting mode of this sensor.
    ///
    /// Required.
    7: reporting_mode SensorReportingMode;
};

/// Uncalibrated samples from 3 axis sensors (eg. accelerometer, gyroscope,
/// magnetometer) come with bias data for each axis.
type UncalibratedVec3FSample = struct {
    sample math.Vec3F;

    biases math.Vec3F;
};

/// A 6 degree of freedom (“6DOF”) pose describes a position and orientation in
/// a 3D space.
type Pose = struct {
    /// A quaternion representing the orientation.
    rotation math.QuaternionF;

    /// A vector represeting the position.
    translation math.Vec3F;

    /// A quaternion describing the rotation from the last known orientation.
    rotation_delta math.QuaternionF;

    /// A vector describing the translation from the last known position.
    translation_delta math.Vec3F;
};

/// All of the potential data types a SensorEvent may carry depending on the
/// sensor type.
type EventPayload = flexible union {
    /// The following sensors emit basic 3D float vectors:
    /// ACCELEROMETER, MAGNETIC_FIELD, ORIENTATION, GYROSCOPE, GRAVITY,
    /// LINEAR_ACCELERATION.
    1: vec3 math.Vec3F;

    /// The following sensors emit floating point quaternions:
    /// ROTATION_VECTOR, GEOMAGNETIC_ROTATION_VECTOR, GAME_ROTATION_VECTOR.
    2: quaternion math.QuaternionF;

    /// The following sensors emit pairs of float vectors (see documentation for
    /// UncalibratedImuSample):
    /// MAGNETIC_FIELD_UNCALIBRATED, GYROSCOPE_UNCALIBRATED,
    /// ACCELEROMETER_UNCALIBRATED.
    3: uncalibrated_vec3 UncalibratedVec3FSample;

    /// The following sensors emit a single float:
    /// DEVICE_ORIENTATION, LIGHT, PRESSURE, TEMPERATURE, PROXIMITY,
    /// RELATIVE_HUMIDITY, AMBIENT_TEMPERATURE, SIGNIFICANT_MOTION,
    /// STEP_DETECTOR, TILT_DETECTOR, WAKE_GESTURE, GLANCE_GESTURE,
    /// PICK_UP_GESTURE, WRIST_TILT_GESTURE, STATIONARY_DETECT, MOTION_DETECT,
    /// HEART_BEAT, LOW_LATENCY_OFFBODY_DETECT, HEART_RATE.
    4: float float32;

    /// The following senors emit an unsigned 64-bit integer:
    /// STEP_COUNTER
    5: integer uint64;

    /// The following sensor types emit a pose (see documentation for Pose):
    /// POSE_6DOF.
    6: pose Pose;
};

/// A sample from a single sensor.
type SensorEvent = struct {
    /// The sample timestamp relative to device boot.
    timestamp zx.Time;

    /// The SensorId of the originating sensor.
    sensor_id SensorId;

    /// The type of the originating sensor.
    sensor_type SensorType;

    /// A sequence number that will be incremented for every sensor event
    /// emitted.
    sequence_number uint64;

    /// The sample data (see documentation for EventPayload).
    payload EventPayload;
};

/// Rate configuration given to Driver::ConfigureSensorRate and
/// Manager::ConfigureSensorRate.
type SensorRateConfig = table {
    /// The desired time period between samples arriving from the hardware.
    ///
    /// Required.
    1: sampling_period_ns zx.Duration;

    /// How long a sensor value may be buffered before it is emitted. A value of
    /// zero will result in no buffering.
    ///
    /// Required.
    2: max_reporting_latency_ns zx.Duration;
};