// @file sns_std_sensor.proto
//
// Defines standard message types for all Sensors. All physical Sensors are
// required to implement this API as is or derive from it. For all other
// Sensors, these messages are highly recommended. That being said, Sensor
// developers may choose to define Sensor-specific message API for any
// new/Sensor-specific functionality.
//
// Copyright (c) 2016-2018,2020 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.

syntax = "proto2";
import "nanopb.proto";

enum sns_std_sensor_msgid
{
  option (nanopb_enumopt).long_names = false;

  // Uses message: sns_std_sensor_config
  // Purpose:
  //   1. A stream request from a client to a sensor.
  //   2. A config/ack event from a sensor to the client.
  SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_CONFIG = 513;

  // Does not use any message body.
  // Purpose:
  //   1. An enable request from a client to an on-change sensor.
  //      Subsequent request from same client will be treated as NOP
  //   2. A config/ack event from an on-change sensor to the client.
  // Requirements for on-change sensors are listed in a section below.
  SNS_STD_SENSOR_MSGID_SNS_STD_ON_CHANGE_CONFIG  = 514;

  // Uses message: sns_std_sensor_physical_config_event
  // Purpose: A configuration event from a Physical Sensor (streaming and event)
  //          to the client.
  // Requirements for physical configuration events are listed in a section
  // below.
  SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_PHYSICAL_CONFIG_EVENT = 768;

  // Uses message: sns_std_sensor_event
  // Purpose: A data event from a Sensor.
  SNS_STD_SENSOR_MSGID_SNS_STD_SENSOR_EVENT = 1025;
}

// Status for each sensor sample
enum sns_std_sensor_sample_status
{
  option (nanopb_enumopt).long_names = false;

  // Sample is unreliable.
  SNS_STD_SENSOR_SAMPLE_STATUS_UNRELIABLE = 0;

  // Sample is low accuracy.
  SNS_STD_SENSOR_SAMPLE_STATUS_ACCURACY_LOW = 1;

  // Sample is medium accuracy.
  SNS_STD_SENSOR_SAMPLE_STATUS_ACCURACY_MEDIUM = 2;

  // Sample is high accuracy.
  SNS_STD_SENSOR_SAMPLE_STATUS_ACCURACY_HIGH = 3;
}

// Attribute IDs available for use by Sensors
// Some are marked as REQUIRED, and must be published by every Sensor.  Others
// are OPTIONAL, and may be only necessary for physical Sensors.
//
// Each Sensor may define their own custom attributes, using the form:
// <proto_name>_attr_id.  Attribute IDs have the following reserved ranges:
// 0-511 : Held for sns_std_sensor_attr_id
// 512-1023 : Reserved for internal QTI use
// 1024-1535 : Available for use by Sensor developers
enum sns_std_sensor_attr_id
{
  option (nanopb_enumopt).long_names = false;

  // REQUIRED
  // String
  // Human-readable sensor name
  SNS_STD_SENSOR_ATTRID_NAME = 0;

  // REQUIRED
  // String
  // Human-readable vendor name
  SNS_STD_SENSOR_ATTRID_VENDOR = 1;

  // REQUIRED
  // String
  // Data Type used by this Sensor
  SNS_STD_SENSOR_ATTRID_TYPE = 2;

  // REQUIRED
  // Boolean
  // Whether this Sensor is available for clients
  SNS_STD_SENSOR_ATTRID_AVAILABLE = 3;

  // REQUIRED
  // Integer 64-bit version number represented as major[31:16].minor[15:8].revision[7:0],  [63:32] be 0
  // Example in hexadecimal: major:0x0002 minor:0x00 revision:0x36  #define DRIVER_VERSION 0x00020036
  // Sensor version
  SNS_STD_SENSOR_ATTRID_VERSION = 4;

  // REQUIRED
  // [String]
  // .proto files specifying the incoming request and outgoing event messages
  SNS_STD_SENSOR_ATTRID_API = 5;

  // OPTIONAL
  // [Float]
  // Supported sample rates in Hz
  SNS_STD_SENSOR_ATTRID_RATES = 6;

  // OPTIONAL
  // [Float]
  // Supported resolutions
  SNS_STD_SENSOR_ATTRID_RESOLUTIONS = 7;

  // OPTIONAL
  // Integer
  // Supported FIFO depth in number of samples
  SNS_STD_SENSOR_ATTRID_FIFO_SIZE = 8;

  // OPTIONAL
  // [Integer]
  // Active currents in uA for all sns_attr_op_modes. Length of the array
  // of active currents must match the length of the array of operation modes.
  SNS_STD_SENSOR_ATTRID_ACTIVE_CURRENT = 9;

  // OPTIONAL
  // Integer
  // Inactive current in uA
  SNS_STD_SENSOR_ATTRID_SLEEP_CURRENT = 10;

  // OPTIONAL
  // [{float,float}]
  // Supported operating ranges
  SNS_STD_SENSOR_ATTRID_RANGES = 11;

  // OPTIONAL
  // String
  // Operating Modes ("LPM", "HIGH_PERF", "NORMAL", "OFF")
  SNS_STD_SENSOR_ATTRID_OP_MODES = 12;

  // OPTIONAL
  // Boolean
  // Whether the Sensor supports Data Ready Interrupt (DRI) or IBI
  // (In Band Interrupt).
  SNS_STD_SENSOR_ATTRID_DRI = 13;

  // OPTIONAL
  // Boolean
  // Whether a Sensor support synchronized streaming.
  SNS_STD_SENSOR_ATTRID_STREAM_SYNC = 14;

  // OPTIONAL
  // Integer
  // Encoded message size of the data event generated most often by the Sensor
  SNS_STD_SENSOR_ATTRID_EVENT_SIZE = 15;

  // REQUIRED
  // Integer: sns_std_sensor_stream_type
  // Streaming Type
  SNS_STD_SENSOR_ATTRID_STREAM_TYPE = 16;

  // OPTIONAL
  // Boolean
  // Whether this Sensor is dynamic (connected/disconnected at runtime)
  SNS_STD_SENSOR_ATTRID_DYNAMIC = 17;

  // OPTIONAL
  // Integer
  // When multiple Sensors of the same hardware exist, this attribute differentiates.
  SNS_STD_SENSOR_ATTRID_HW_ID = 18;

  // OPTIONAL
  // Integer: sns_std_sensor_rigid_body_type
  // The rigid body on which the Sensor is placed.
  SNS_STD_SENSOR_ATTRID_RIGID_BODY = 19;

  // OPTIONAL
  // float[12]
  // Location and orientation of sensor element in the device frame.
  SNS_STD_SENSOR_ATTRID_PLACEMENT = 20;

  // OPTIONAL
  // Boolean
  // Boolean: True for a physical sensor
  SNS_STD_SENSOR_ATTRID_PHYSICAL_SENSOR = 21;

  // OPTIONAL
  // [Integer]
  // List of supported self-test types from sns_physical_sensor_test_type.
  SNS_STD_SENSOR_ATTRID_PHYSICAL_SENSOR_TESTS = 22;

  // OPTIONAL
  // Float
  // Sensors chosen resolution in it's engineering units.
  SNS_STD_SENSOR_ATTRID_SELECTED_RESOLUTION = 23;

  // OPTIONAL
  // float[2]
  // Sensors chosen {min, max} range in it's engineering units.
  SNS_STD_SENSOR_ATTRID_SELECTED_RANGE = 24;

  // OPTIONAL
  // [float]
  // List of additional sample rates for low latency clients in Hz.
  // These are additional rates for low latency clients extended from list
  // of rates published in attribute SNS_STD_SENSOR_ATTRID_RATES.
  // This is supported for internal clients only. External clients shall not use this API.
  SNS_STD_SENSOR_ATTRID_ADDITIONAL_LOW_LATENCY_RATES = 25;
  
  // OPTIONAL
  // Boolean
  // Boolean: True if the sensor supports passive request, False otherwise.
  // If this attribute is not supported, then the sensor does not support passive requests.
  // Sensors that do not support passive requests, will service all requests as active requests.
  SNS_STD_SENSOR_ATTRID_PASSIVE_REQUEST = 26;
}

// Sensor stream configuration request
// or configuration change message
message sns_std_sensor_config
{
  // Sample rate in Hz.
  required float sample_rate = 1;
}

// Sensor data event
message sns_std_sensor_event
{
  // Output data field for all Sensor.
  repeated float data = 1;

  // Event sample status.
  required sns_std_sensor_sample_status status = 2 [default = SNS_STD_SENSOR_SAMPLE_STATUS_UNRELIABLE];
}

// Stream types
enum sns_std_sensor_stream_type
{
  option (nanopb_enumopt).long_names = false;

  // Used for Sensors that report data periodically.
  // Example: accel, gyro, mag
  SNS_STD_SENSOR_STREAM_TYPE_STREAMING = 0;

  // Used for Sensors that report data only on change in value.
  // Example: proximity, hall
  SNS_STD_SENSOR_STREAM_TYPE_ON_CHANGE = 1;

  // Used for Sensors that have a single data event in reponse to a request.
  // Example: SUID, motion detect
  SNS_STD_SENSOR_STREAM_TYPE_SINGLE_OUTPUT = 2;
}

// Rigid body types
enum sns_std_sensor_rigid_body_type
{
  option (nanopb_enumopt).long_names = false;

  // Used for a Sensor mounted on the same rigid body as the display.
  SNS_STD_SENSOR_RIGID_BODY_TYPE_DISPLAY = 0;

  // Used for a Sensor mounted on the same rigid body as a keyboard.
  SNS_STD_SENSOR_RIGID_BODY_TYPE_KEYBOARD = 1;

  // Used for a Sensor that is mounted on an external device.
  SNS_STD_SENSOR_RIGID_BODY_TYPE_EXTERNAL = 2;
}

// Sensor stream configuration event
message sns_std_sensor_config_event
{
  // Current sample rate in Hz
   required float sample_rate = 1;
}

// Physical sensor stream configuration. This message reflects the current
// configuration of the physical sensor.
message sns_std_sensor_physical_config_event
{
  // Current sample rate in Hz for streaming sensors only, 0 if sensor is disabled
  // ( ex: when event gated or in passive mode and not streaming )
  // Note: if stream will be synchronized via S4S or I3C, this is the sample
  // rate after synchronization is complete.
  optional float sample_rate = 1;

  // Current hardware water mark setting. 1 if FIFO not in use.
  optional uint32 water_mark = 2;

  // Sensor sample value min and max range
  repeated float range = 3 [(nanopb).max_count = 2];

  // Sensor sample value Resolution
  optional float resolution = 4;

  // Sensor operation mode
  // If all requests to the sensor are passive then it shall use
  // operating_mode = "OFF"
  optional string operation_mode = 5;

  // Sensor active current in uA
  optional uint32 active_current = 6;

  // Sensor streaming is synchronized via methods like S4S and/or I3C.
  // Note: if the stream is not yet synchronized, this field should be
  // false, and an additional config event sent with stream_is_synchronous
  // set to true once the clocks have been synchronized.
  optional bool stream_is_synchronous = 7;

  // Sensor has enabled Data Ready Interrupt
  optional bool dri_enabled = 8;

  // Current DAE water mark setting. 0 if non-DAE sensor.
  optional uint32 DAE_watermark = 9;

  // The sync anchor is only valid for polled or synchronized sensors.
  // It is a timestamp of a future (or past) sns_std_sensor_event.
  // For synchronous sensors: this may be used by clients to determine the
  // synchronized timeline before it is synchronized.
  optional uint64 sync_ts_anchor = 10;
}

// Attribute requirements:
// The Physical Sensor publishes:
// 1. SNS_STD_SENSOR_ATTRID_AVAILABLE attribute value (bool) as true when it's dependencies
//    are met and the hardware is present and responsive.
// 2. SNS_STD_SENSOR_ATTRID_NAME attribute value (string) as the name of the sensor model.
// 3. SNS_STD_SENSOR_ATTRID_VENDOR attribute value (string) as the name of the sensor vendor.
// 4. SNS_STD_SENSOR_ATTRID_VERSION attribute value (decimal) as the version of the driver.
// 5. SNS_STD_SENSOR_ATTRID_RATES attribute as a float array of supported sample rates in Hz
//    for streaming sensors. On-change sensors publish the highest rate of value change.
// 6. SNS_STD_SENSOR_ATTRID_FIFO_SIZE attribute value (decimal) as the maximum FIFO depth in
//    number of sensor samples available to it when enabled standalone.
//    The value can be zero if FIFO is not supported.
// 7. SNS_STD_SENSOR_ATTRID_ACTIVE_CURRENT attribute as an integer  array representing active
//    currents in uA corresponding to the sns_attr_op_modes attribute.
// 8. SNS_STD_SENSOR_ATTRID_SLEEP_CURRENT attribute value (float) as the current in uA when
//    the sensor is in power down mode.
// 9. SNS_STD_SENSOR_ATTRID_OP_MODES attribute value as an array of string values
//     representing different hardware operating modes.
// 10. SNS_STD_SENSOR_ATTRID_DRI attribute value (bool) as true when it supports
//     interrupt based streaming else false when polling.
//     The source of data ready interrupt (DRI) could be completion of measurement
//     cycle, FIFO water mark (if sns_attr_fifo_size value is greater than 0),
//     threshold, etc.
//     If the sensor is capable of streaming in both polling and DRI modes then
//     it publishes separate Sensors for each mode such that the one with DRI
//     publishes SNS_STD_SENSOR_ATTRID_DRI value as true and the one with polling
//     publishes SNS_STD_SENSOR_ATTRID_DRI as false.
// 11. SNS_STD_SENSOR_ATTRID_STREAM_SYNC attribute value (bool) as true when it
//     it supports a synchronous streaming mechanism like S4S and/or I3C.
// 12. SNS_STD_SENSOR_ATTRID_EVENT_SIZE attribute value (decimal) as number of bytes in the
//     output data event for the Sensor.
// 13. SNS_STD_SENSOR_ATTRID_STREAM_TYPE attribute value (sns_std_sensor_stream_type) as the
//     supported stream type.
// 14. SNS_STD_SENSOR_ATTRID_DYNAMIC attribute value (bool) to indicate whether the sensor
//     can be added at runtime.
// 15. SNS_STD_SENSOR_ATTRID_HW_ID attribute value (string) to uniquely identify multiple
//     sensor hardware of the same model on a platform.
// 16. SNS_STD_SENSOR_ATTRID_RIGID_BODY attribute value (sns_std_sensor_rigid_body_type) as the rigid
//     body on which the sensor is mounted.
// 17. SNS_STD_SENSOR_ATTRID_PLACEMENT attribute value as the location and orientation of
//     the sensor hardware.
// 18. SNS_STD_SENSOR_ATTRID_PHYSICAL_SENSOR attribute value (bool) to indicate if the sensor is
//     a physical sensor
// 19. SNS_STD_SENSOR_ATTRID_PHYSICAL_SENSOR_TESTS attribute value as array of supported
//     sns_physical_sensor_test_type test types.
// 20. SNS_STD_SENSOR_ATTRID_SELECTED_RESOLUTION attribute value chosen from the
//     SNS_STD_SENSOR_ATTRID_RESOLUTIONS attribute array.
// 21. SNS_STD_SENSOR_ATTRID_SELECTED_RANGE attribute value chosen from the
//     SNS_STD_SENSOR_ATTRID_RANGES array.
// 22. SNS_STD_SENSOR_ATTRID_ADDITIONAL_LOW_LATENCY_RATES attribute as a float array of supported
//     sample rates in Hz additional to rates in SNS_STD_SENSOR_ATTRID_RATES, this is only for low
//     latency clients like direct report mode.
// See sensor specific .proto files for sensor specific attribute information.

// Recommendation for device drivers to select configuration:
// 1. Choose fastest sample_rate among all client requests.
// 2. Choose fastest batch rate (using batch_period) among all client requests. For streaming clients,
//    treat batch rate equal to requested sample rate for that request.
// 3. If HW FIFO is supported then:
//     a. If all requests are max_batch then the driver configures highest FIFO watermark.
//        If DAE is supported, the DAE watermark should be INT_MAX.
//     b. Else FIFO watermark is determined based on sample_rate from #1 and batch rate from #2.

// Requirements for on-change sensors:
// 1. Timestamp in data events. When a second (or subsequent) client request
//    is processed, by a given sensor, an initial data event must be generated.
//    The timestamp in this event must be equal to the timestamp of the most
//    recent state transition. The timestamp of the last occurring state
//    transition can be latched (e.g. in a state structure), per on-change
//    sensor SUID.

// Requirements for physical configuration events:
// 1. Timestamp in physical configuration events. When a second (or subsequent)
//    client request is processed, by a given sensor, a physical configuration
//    event must be generated. The timestamp, in the physical configuration
//    event, must be equal to the timestamp of the most recent physical
//    configuration change. The timestamp of the last occurring physical
//    configuration change can be latched (e.g. in a state structure).
