Android ZRC Vendor OS API for sensor data collection

1. INTRODUCTION

Multiple devices with environmental sensors, such as companion whiteboards, companion ZRTs, or controllers, may coexist in the same Zoom Room and generate sensor data. However, the current design of ZR VendorOS APIs for sensors (humidity, temperature, VOC, etc.) assumes that only the Zoom Room appliance collects this data. To address this limitation, the ZRC VendorOS APIs (Version 1.12) will be enhanced to allow multiple ZR/ZRC devices to collect sensor data and calculate an average for display on the Zoom Rooms' display, Zoom Rooms Controllers, Zoom Rooms Scheduling Displays and in Zoom Dashboard.

2. INTERFACES

2.1 Sensor Capabilities

To support the sensors, the Vendor OS API adds the sensor capability. Specifically, it adds the ZRAPI_CAP_SENSOR capability bit field and the ISensorManager interface:

public class VendorOSManager {
    /**
     * [OPTIONAL, MUST if needs to support sensors, e.g. passive infrared, ultrasonic or camera-based motion sensors.]
     * <p>
     * Define the capability of sensor manager API
     * <p>
     * <b><i>Required Field</i></b>
     */
    public static final int ZRAPI_CAP_SENSOR = 0x08;
    
    /**
     * [OPTIONAL, MUST if needs to support sensors, e.g. passive infrared, ultrasonic or camera-based motion sensors.]
     * <p>
     * Get sensor manager interface
     *
     * @return {@link ISensorManager}
     */
    public ISensorManager getSensorManager() {
        ...
    }
}

There are many sensors, like the temperature sensor, the humidity sensor, etc. The ZRC Vendor OS API has gained multiple SensorCapability capabilities, similar to the ZR VendorOS API, as shown below:

public interface SensorCapability {
    /**
     * [OPTIONAL, MUST if needs to support temperature sensor]
     * <p>
     * The capability of temperature sensor
     */
    public static final int ZRAPI_SENSOR_CAP_TEMPERATURE            = 0x02;

    /**
     * [OPTIONAL, MUST if needs to support CO2 sensor]
     * <p>
     * The capability of CO2 sensor
     */
    public static final int ZRAPI_SENSOR_CAP_CO2_CONCENTRATION      = 0x04;

    /**
     * [OPTIONAL, MUST if needs to support VOC sensor]
     * <p>
     * The capability of VOC sensor
     */
    public static final int ZRAPI_SENSOR_CAP_VOC_CONCENTRATION      = 0x08;

    /**
     * [OPTIONAL, MUST if needs to support Humidity sensor]
     * <p>
     * The capability of Humidity sensor
     */
    public static final int ZRAPI_SENSOR_CAP_HUMIDITY               = 0x10;

    /**
     * [OPTIONAL, MUST if needs to support PM 2.5 sensor]
     * <p>
     * The capability of PM 2.5 sensor
     */
    public static final int ZRAPI_SENSOR_CAP_PM25                   = 0x80;

    /**
     * [OPTIONAL, MUST if needs to support PM 10 sensor]
     * <p>
     * The capability of PM 10 sensor
     */
    public static final int ZRAPI_SENSOR_CAP_PM10                   = 0x100;

    /**
     * [OPTIONAL, MUST if needs to support air pressure sensor]
     * <p>
     * The capability of air pressure sensor
     */
    public static final int ZRAPI_SENSOR_CAP_AIR_PRESSURE           = 0x200;
}

2.2 Get the sensor data

To obtain current sensor data, the ZRC Vendor OS has added ISensorManager methods corresponding to the SensorCapability types mentioned above, such as ZRAPI_SENSOR_CAP_TEMPERATURE, ZRAPI_SENSOR_CAP_CO2_CONCENTRATION, and others. These methods are described below:

public interface ISensorManager {
    /**
     * [MUST]
     * <p>
     * Get system sensor control capability
     *
     * @return Capability flags defined in {@link SensorCapability}
     */
    int getCapability();

    /**
     * [OPTIONAL, MUST if needs to support sensors.]
     * Get room temperature in celsius
     *
     * @return temperature in celsius
     */
    double getTemperature();

    /**
     * [OPTIONAL, MUST if needs to support sensors.]
     * Get CO2 concentration
     *
     * @return the value of the CO2 concentration
     */
    double getCo2Concentration();

    /**
     * [OPTIONAL, MUST if needs to support sensors.]
     * Get VOC concentration
     *
     * @return the value of the VOC concentration
     */
    double getVocConcentration();

    /**
     * [OPTIONAL, MUST if needs to support sensors.]
     * Get humidity
     *
     * @return the value of the humidity
     */
    double getHumidity();

    /**
     * [OPTIONAL, MUST if needs to support sensors.]
     * Get pm2.5
     *
     * @return the value of the pm2.5(µg/m³)
     */
    double getPM25();
    /**
     * [OPTIONAL, MUST if needs to support sensors.]
     * Get pm10
     *
     * @return the value of the pm10(µg/m³)
     */
    double getPM10();
    /**
     * [OPTIONAL, MUST if needs to support sensors.]
     * Get air pressure
     *
     * @return the value of the air pressure(Pa)
     */
    double getAirPressure();
}

Because the sensors continuously detect data, the ZRC Vendor OS API specifies an Android Intent the firmware must send to provide change notification as follows:

public interface ZRIntentDefinition {
    /**
     * [OPTIONAL]
     * <p>
     * Event for vendor to broadcast that sensor data has changed
     * <p>
     * <b>Intent Extras</b>
     * <ul>
     * <li><b>eventType</b>&nbsp;&nbsp;<i>{@link ZRSystemSensorEvent}</i>: vendor system sensor event. </li>
     * </ul>
     */
    public static final String EVENT_SYSTEM_SENSOR_VALUE_CHANGED = "us.zoom.zr.vendoros.event.SYSTEM_SENSOR_VALUE_CHANGED";
}

/**
 * Vendor system sensor event definition
 */
public interface ZRSystemSensorEvent {
    /**
     * CO2 sensor event
     */
    public static final int SENSOR_EVENT_CO2_CONCENTRATION  = 0;

    /**
     * VOC (Volatile organic compounds) sensor event
     */
    public static final int SENSOR_EVENT_VOC_CONCENTRATION  = 1;

    /**
     * Humidity sensor event
     */
    public static final int SENSOR_EVENT_HUMIDITY           = 2;

    /**
     * Temperature sensor event
     */
    public static final int SENSOR_EVENT_TEMPERATURE        = 3;

    /**
     * pm2.5 sensor event
     */
    public static final int SENSOR_EVENT_PM25_CONCENTRATION = 5;
    /**
     * pm10 sensor event
     */
    public static final int SENSOR_EVENT_PM10_CONCENTRATION = 6;
    /**
     * air pressure sensor event
     */
    public static final int SENSOR_EVENT_AIR_PRESSURE       = 7;
}