chromeos/components/sensors/mojom/sensor.mojom

// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Next min version: 1

// NOTE: This mojom exists in two places and must be kept in sync:
//       Chromium:  //chromeos/components/sensors/mojom/
//       Chrome OS: src/platform2/iioservice/mojo/
//       Note: Other repos downstream of Chromium might also use this mojom.
// Example: A backwards-compatible mojom change (and corresponding
// implementation change) can be made in Chrome OS first, then replicated to the
// clients (Chromium, other downstream repos) later.

module chromeos.sensors.mojom;

const string kScale = "scale";
const string kSamplingFrequencyAvailable = "sampling_frequency_available";
const string kLocation = "location";

const string kLocationBase = "base";
const string kLocationLid = "lid";
const string kLocationCamera = "camera";

// As Mojo doesn't support const arrays of strings and char, and also axes are
// trivial, let Sensor clients append the axes.
// Supported axes: {"x", "y", "z"}. Ex: "accel_x".
const string kAccelerometerChannel = "accel";
const string kGyroscopeChannel = "anglvel";
const string kMagnetometerChannel = "magn";

// The light sensor may have not only channel "illuminance", but three color
// channels: illuminance_red, illuminance_green, and illuminance_blue.
const string kLightChannel = "illuminance";
const string kPressureChannel = "pressure";

const string kTimestampChannel = "timestamp";

enum DeviceType {
  NONE = 0,  // invalid device type
  ACCEL = 1,
  ANGLVEL = 2,
  LIGHT = 3,
  COUNT = 4,
  MAGN = 5,
  ANGL = 6,
  BARO = 7,
  MAX = 8,
};

enum ObserverErrorType {
  ALREADY_STARTED = 0,
  SET_FREQUENCY_IO_FAILED = 1,
  FREQUENCY_INVALID = 2,
  NO_ENABLED_CHANNELS = 3,
  GET_FD_FAILED = 4,
  READ_FAILED = 5,
  READ_TIMEOUT = 6,
};

// SensorService, an interface to search and get SensorDevices. A User can get
// multiple isolated SensorDevices for one physical device, if it wants
// different frequencies of that device's samples.
//
// Next method ID: 4
interface SensorService {
  // Gets device ids as a vector of int given the device's type. Only devices
  // with id having "iio:device" as the prefix would be available.
  // Gets an empty vector if no device can be found.
  GetDeviceIds@0(DeviceType type) => (array<int32> iio_device_ids);

  // Gets all device ids and their types. Only devices with id having
  // "iio:device" as the prefix would be available. For combo sensors, there are
  // multiple types in the array of types.
  // Gets an empty vector if no device can be found.
  GetAllDeviceIds@1() => (map<int32, array<DeviceType>> iio_device_ids_types);

  // Creates a new Mojo channel to the iioservice as an isolated client. Upon
  // successfully binding of |device_request|, the caller will have an
  // established Mojo channel to iioservice.
  // If failed, the request won't be bound and will be destroyed directly.
  GetDevice@2(int32 iio_device_id,
      pending_receiver<SensorDevice> device_request);

  // Registers a SensorServiceNewDevicesObserver to iioservice. Users will get
  // notified when new devices are added and visible to iioservice.
  RegisterNewDevicesObserver
      @3(pending_remote<SensorServiceNewDevicesObserver> observer);
};

// SensorDevice, an interface sending requests for a physical device
// (libiio:iio_device). It is an isolated client in iioservice's point of view.
//
// Next method ID: 9
interface SensorDevice {
  // Sets |timeout| in milliseconds for I/O operations, mainly for reading
  // samples. Sets |timeout| as 0 to specify that no timeout should occur.
  // Default: 5000 milliseconds.
  SetTimeout@0(uint32 timeout);

  // Gets the |attr_names| attributes of this device into |values| as strings.
  // When an attribute cannot be read, its value in |values| is set to null.
  // |values| and |attr_names| always have the same size.
  GetAttributes@1(array<string> attr_names) => (array<string?> values);

  // Sets the frequency in Hz of the device before starting to read samples.
  // If no frequency or an invalid frequency is set, an
  // ObserverErrorType::FREQUENCY_INVALID error will occur after calling
  // |StartReadingSamples|.
  // After starting to read samples, the client can set the frequency to 0 to
  // pause the reading, and set a valid frequency later to resume the reading.
  // |result_freq| would be the frequency set by iioservice for the client.
  SetFrequency@2(double frequency) => (double result_freq);

  // Starts reading samples with the frequency set by |SetFrequency|. Samples or
  // errors will be pushed to the observer. It's the user's responsibility to
  // keep |observer| active while reading.
  StartReadingSamples@3(pending_remote<SensorDeviceSamplesObserver> observer);

  // Stops reading samples in this device. Reading can be restarted by calling
  // |StartReadingSamples| again.
  StopReadingSamples@4();

  // Gets all channels' ids as a vector of string. The ids are ordered and the
  // user should use the indices of channels to send further requests and
  // receive samples.
  GetAllChannelIds@5() => (array<string> iio_chn_ids);

  // Sets channels' enabled status to |en| with channel indices
  // |iio_chn_indices|. Returns an array of channel indices |failed_indices| if
  // there are some invalid or duplicate indices.
  SetChannelsEnabled @6(array<int32> iio_chn_indices, bool en)
    => (array<int32> failed_indices);

  // Returns an array of bool indicating if channels are enabled.
  GetChannelsEnabled@7(array<int32> iio_chn_indices) => (array<bool> enabled);

  // Gets the |attr_name| attribute of channels as a group into |values| in
  // string.
  // Returns base::nullopt if the attribute in the channel cannot be read.
  GetChannelsAttributes@8(array<int32> iio_chn_indices, string attr_name)
    => (array<string?> values);
};

// One observer is created to track one specific device's samples, using
// SensorDevice::StartReadingSamples to register the observer.
//
// Next method ID: 2
interface SensorDeviceSamplesObserver {
  // |sample| arrives and is sent to the client as a map from iio_chn_indices to
  // data (64 bit integer).
  OnSampleUpdated@0(map<int32, int64> sample);

  // An error occurs and is sent to the client as an enum type.
  OnErrorOccurred@1(ObserverErrorType type);
};

// One observer is created to track new sensors updated to iioservice, using
// SensorService::RegisterNewDevicesObserver to register the observer.
//
// Next method ID: 1
interface SensorServiceNewDevicesObserver {
  // A new IIO device with |iio_device_id| and |types| is added and visible to
  // iioservice. Sensor clients can get access to this device with the id.
  OnNewDeviceAdded@0(int32 iio_device_id, array<DeviceType> types);
};