android-15.0.0_r3/s

/*
 * Copyright (C) 2024 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";

package com.android.ranging.generic.proto;

option java_package = "com.android.ranging.generic.proto";
option java_multiple_files = true;

enum ConfidenceLevel {
CL_UNSPECIFIED = 0;
CL_95 = 1;    // 95 %
CL_97P5 = 2;  // 97.5 %
CL_99 = 3;    // 99 %
}

// Configuration for MultiSensorFinder including the configuration of sub
// components.
message MultiSensorFinderConfig {
// If unset, default values will be used.
ParticleFilterConfig particle_filter_config = 1;

// If enabled, the filter will use UWB measurements.
bool use_uwb_measurements = 2;

// If enabled, the filter will use Wi-Fi RTT measurements.
bool use_wifi_rtt_measurements = 3;

// If unset, default values will be used.
RangeMeasurementConfig uwb_range_measurement_config = 4;

// If unset, default values will be used.
RangeMeasurementConfig wifi_rtt_range_measurement_config = 5;

// If unset, default values will be used.
FuzzyUpdateSchedulerConfig fuzzy_update_scheduler_configuration = 6;

double default_xy_update_process_noise_stddev_m = 7;

// If unset, default values will be used.
OdometryNoiseAdderConfig odometry_noise_adder_config = 8;

// If unset, trilateration measurement updater will not be used.
TrilaterationMeasurementUpdaterConfig
trilateration_measurement_updater_config = 9;

// The rate at which finder will poll the odometry provider, which is also
// the maximum rate at which finder will generate estimates.
uint32 odometry_polling_rate_hz = 10;

// If unset, odometry throttler will not be used.
OdometryThrottlerConfig odometry_throttler_config = 11;

// If unset, OBEP will not be used.
OdometryBasedEstimatePropagatorConfig
odometry_based_estimate_propagator_config = 12;

// If unset, the NIS divergence detector will not be used.
NisDivergenceDetectorConfig nis_divergence_detector_config = 13;

InitialStateSamplerConfig uwb_initial_state_sampler_config = 14;

InitialStateSamplerConfig wifi_rtt_initial_state_sampler_config = 15;

// Used to input and output logs for development and debugging. If unset,
// the debug logger will not be used.
DebugLoggerConfiguration debug_logger_configuration = 16;
}

// Configuration for the generic sensor model, which is simply a combination of
// a Gaussian and a Uniform distribution.
message GenericRangeSensorModelConfig {
double gaussian_std_dev_m = 1;
double max_sensor_range_m = 2;
}

// Configuration for the trilateration measurement updater, which uses
// trilateration on a set of UWB range measurements to determine if the incoming
// range measurements are consistent over some spatial region.
message TrilaterationMeasurementUpdaterConfig {
int32 num_measurements_for_trilateration = 2;
double max_trilateration_rmse_m = 3;
}

// Configuration for the sensor model associated with a range measurement and
// any additional checks/modifiers. Currently, only the GenericRangeSensorModel
// is supported.
message RangeMeasurementConfig {
// Currently supported models for a range sensor. If unspecified, the generic
// model will be used.
enum RangeSensorModelType {
UNSPECIFIED = 0;
// A generic model that consists of a Gaussian + Uniform distribution.
// The configuration message associated with this model is
// GenericRangeSensorModelConfig.
GENERIC = 1;
// Switches the measurement model based on the variance heuristic.
VARIANCE_BASED_SWITCHING = 2;
}
RangeSensorModelType sensor_model_type = 1;
GenericRangeSensorModelConfig generic_range_sensor_model_configuration = 2;
VarianceBasedSwitchingMeasurementModelConfig
variance_based_switching_measurement_model_config = 4;
// If unset, the distance traveled check will not be used.
DistanceTraveledCheckConfig distance_traveled_check_config = 3;
}

// Configuration for a scheduler which determines when a motion + measurement
// update should be done.
//
// For each odometry sample, it creates a frame (or window) of +-
// max_frame_size_nanos, and waits max_wait_time_nanos for all data to show up
// in this frame.
//
// max_wait_time_nanos is directly proportional to the filter latency.
// Increasing max_frame_size_nanos will increase the number of measurements
// used, but can decrease accuracy because of a greater tolerance on the
// mismatch in timestamps between odometry and range sensor data.
message FuzzyUpdateSchedulerConfig {
uint64 max_wait_time_nanos = 1;
uint64 max_frame_size_nanos = 2;
int32 max_buffer_size = 3;
}

// The distance traveled check blocks measurements from being continually
// absorbed if a user stands still. It's a simple way to prevent particle
// depletion.
message DistanceTraveledCheckConfig {
double distance_traveled_threshold_m = 2;
}

message ParticleFilterConfig {
int32 number_of_particles = 1;
}

// The odometry noise adder adds noise during a motion update based on the speed
// of the user.
//
// The mapping from speed to noise stays flat at min_noise_std_dev until the
// speed reaches min_speed_mps, after which it ramps linearly up to
// max_speed_mps. For speed greater than max_speed_mps, it stays at
// max_noise_std_dev.
//
//
//                    max_speed_mps
//                    /
//         ^          *
//         |          ------------ max_noise_std_dev
// sigma m |         /
//         |        /
//         | ------/  min_noise_std_dev
//         ----------------------------------> Speed m/s`
//                 *
//                /
//    min_speed_mps
message OdometryNoiseAdderConfig {
int32 num_speed_filter_taps = 2;
double min_noise_std_dev_m = 3;
double max_noise_std_dev_m = 4;
double min_speed_mps = 5;
double max_speed_mps = 6;
}

message OdometryThrottlerConfig {
int64 throttling_dt_nanos = 1;
}

message OdometryBasedEstimatePropagatorConfig {
// The size of the odometry buffer. Set this based on the odometry polling
// rate.
int32 buffer_size = 1;
}

// Uses the Normalized Innovation Squared criteria to determine if the filter
// has diverged. The Filter will reset if divergence is detected.
message NisDivergenceDetectorConfig {
// A larger buffer reduces sensitivity to noisy measurements.
int32 nis_buffer_size = 1;

// A higher level yields fewer false positives.
ConfidenceLevel confidence_level = 2;

// Caps the NIS score to reduce sensitivity to outliers. For example, a value
// of 1 sigma will cap the NIS score to the 68.3 % Gaussian interval about the
// mean.
double nis_sigma_bound = 3;

// The detector will only be active if the std dev of the filter's error in
// the estimated beacon position is below this threshold.
double activation_threshold_m = 4;

// The default noise covariance used when computing the NIS for UWB if an
// online computed value is not provided to the detector.
double default_uwb_noise_covariance = 5;

// The default noise covariance used when computing the NIS for Wi-Fi RTT if
// an online computed value is not provided to the detector.
double default_wifi_rtt_noise_covariance = 6;
}

message UniformModelConfig {
double min_value = 1;
double max_value = 2;
}

message GaussianModelConfig {
double loc = 1;
double scale = 2;
}

message ExponentiallyWeightedGaussianModelConfig {
double lambda_scaled = 1;
double loc = 2;
double scale = 3;
}

message ModelConfigContainer {
oneof model {
UniformModelConfig uniform_model_config = 1;
GaussianModelConfig gaussian_model_config = 2;
ExponentiallyWeightedGaussianModelConfig
exponentially_weighted_gaussian_model_config = 3;
}
}

// Configuration for the variance based switching model.
message VarianceBasedSwitchingMeasurementModelConfig {
double switching_threshold = 1;

ModelConfigContainer low_variance_model_config = 2;

// If unset, measurement updates will not be done while the sensor range
// variance is above the variance_threshold.
ModelConfigContainer high_variance_model_config = 3;

// The size of the window over which the variance used by this model is
// computed.
int32 variance_window_size = 4;
}

// Configuration for an initial state sampler.
//
// Please note that the mean of the distribution specified in the sampler
// configs are about the measured value; if a Gaussian sampler is used with loc
// = 0.1 and scale = 10, then the samples will be generated using:
//
// measured_range + Gaussian(loc, scale).
//
// Additionally, note that the exponential distribution will be flipped such
// that it is skewed towardes -ve axis rather than the standard which is skewed
// towardes the +ve axis.
message InitialStateSamplerConfig {
ModelConfigContainer range_sampler_config = 1;
ModelConfigContainer bearing_sampler_config = 2;
}

message DebugLoggerConfiguration {
// Debug logs will be automatically emitted to the sink when they exceed this
// size.
int32 autodump_size_threshold_bytes = 1;
// The rate at which odometry inputs will be throttled. Throttling is disabled
// if set to 0.
int64 odometry_throttling_nanos = 2;
// The rate at which UWB range measurements will be throttled. Throttling is
// disabled if set to 0.
int64 uwb_throttling_nanos = 3;
// The rate at which output estimates will be throttled. Throttling is
// disabled if set to 0.
int64 estimate_throttling_nanos = 4;
}