// @file sns_mag.proto
//
// Defines the API for Magnetometer Sensors.
// All Magnetometer Sensor drivers are required to comply with this API.
// Any new functionality for Magnetometer Sensor can be defined in a
// device specific API file.
//
// Copyright (c) 2016-2017 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.

syntax = "proto2";
import "nanopb.proto";
import "sns_std_sensor.proto";
import "sns_physical_sensor_test.proto";
import "sns_cal.proto";

// Attribute requirements:
// The Magnetometer Sensor publishes:
// 1. SNS_STD_SENSOR_ATTRID_TYPE attribute value as "mag".
// 2. SNS_STD_SENSOR_ATTRID_RESOLUTIONS attribute value in µT/LSB.
// 3. SNS_STD_SENSOR_ATTRID_RANGES attribute values in µT unit.
// 4. See sns_std_sensor.proto for other attributes.

// Handling stream requests:
// 1. The Magnetometer Sensor handles the sns_std_sensor_config
//    message request for all stream enable/update requests.
// 2. If the physical sensor supports hardware FIFO then the Magnetometer
//    Sensor uses batching_period item in sns_std_request as the requested
//    batching rate to determine hardware FIFO watermark.

// Handling stream events:
// 1. The Magnetometer Sensor publishes ambient magnetic field data events
//    using the sns_std_sensor_event message.
// 2. Each stream event contains three output data fields where data is
//    in µT (micro Tesla) units and is factory calibrated.
// 3. Data in the stream is adjusted to Android coordinate system relative to a
//    mobile device held with screen facing the user in it's natural orientation:
//    X-axis: parallel to the screen pointing to the right
//    Y-axis: parallel to the screen pointing to the top
//    Z-axis: perpendicular to the screen pointing towards the user
//    This conforms to the mobile device axes orientation as specified by the
//    Android Sensor API.
// 4. Data in the stream event is ordered as:
//    data[0] = X-axis
//    data[1] = Y-axis
//    data[2] = Z-axis
// 5. Each stream event publishes an accuracy field:
//    SNS_STD_SENSOR_SAMPLE_STATUS_UNRELIABLE to mark invalid samples when hardware is
//    yet to stabilize after the sensor is configured.
//    SNS_STD_SENSOR_SAMPLE_STATUS_ACCURACY_HIGH to mark samples when they are valid.
// 6. The Magnetometer Sensor publishes a configuration event using the
//    sns_std_sensor_physical_config_event message.
//    It publishes this event each time there is change in hardware config of the sensor
//    and contains current physical sensor config of the sensor.
// 7. The Magnetometer Sensor publishes a factory calibration event using the
//    sns_cal_event message. It uses bias and comp_matrix fields in this event.
//    It publishes this event each time there is change in it's factory calibration
//    data or when a client sends a new streaming request.

// Handling self-test requests:
// 1. The Magnetometer Sensor implements SNS_PHYSICAL_SENSOR_TEST_TYPE_COM test
//    type using the physical sensor test API.
// 2. The Magnetometer Sensor implements SNS_PHYSICAL_SENSOR_TEST_TYPE_FACTORY test
//    type to determine factory calibration parameters using the physical
//    sensor test API.
// 3. The Magnetometer Sensor could implement other test types.

// Handling test events:
// 1. The Magnetometer Sensor uses sns_physical_sensor_test_event message to publish
//    a test completion event.
// 2. The test_passed field in sns_physical_sensor_test_event is used to output the
//    pass/fail result of self-test execution.
// 3. The test_data field in sns_physical_sensor_test_event could be used to output any
//    driver-specific error data.
