How to implement the motion sensor API?

1. INTRODUCTION

When Zoom Rooms are configured for Device Operation Time (DOT), Zoom Rooms devices will "sleep" in non-operating hours (schedule-based DOT) or after a configurable period of time (time-out-based DOT). Similarly, when Zoom Rooms are configured to display Digital Signage content, Zoom Rooms devices will show that content while the Zoom Room is idle (based on configurable timers). Many Zoom Rooms and Zoom Rooms Controller devices now offer motion sensing capabilities such as passive infrared (PIR) sensors or ultrasound-based detection, and always-on cameras with people-counting capabilities. Accordingly, Zoom is enhancing the ZR and ZRC Vendor OS APIs to support the motion sensor-based "wake-up" so the room may transition to a ready-to-use state when users enter the space. By implementing the motion sensor API, a ZR or ZRC device can facilitate the automatic "wake-up" of the Zoom Room. Please note that devices must be added to a Zoom motion sensor allow-list before motion sensor "wake-up" will be usable in production. Engage your Zoom Rooms Hardware Partnerships contact to initiate the process of getting your device allow-listed.

1.1. Use cases There are 4 primary use cases for motion sensor APIs:

If the ZR is in DOT sleep or playing the digital signage content, and subsequently the motion sensor of the ZR/ZRC device detects there is a person in the room (motions are detected), the ZR will "wake-up" automatically. For example:
(1) If a Zoom Room has DOT enabled and is sleeping, after motion is detected the Zoom Room will "wake up" and show the idle screen. (2) If a Zoom Room has Digital Signage enabled and is currently playing Digital Signage content, after motion is detected the Zoom Room will "wake up" and show the idle screen.
If the motion sensor of the ZR/ZRC device detects there is continuous motion, the ZR will remain in the "idle" state and not return to DOT sleep or play Digital Signage content until the motion in the room has ceased for a period of time. Put differently, continuous motion prevents ZR from beginning its internal timers to return to DOT non-operating state and/or begin Digital Signage playback. For example: (1) If a customer enables DOT based on schedule, and the ZR is currently in non-operating hours, the ZR will remain "awake" until motion ceases and ~18-minutes elapses, then return to "non-operating" state. (2) If a customer enables DOT based on time-out, the ZR will remain "awake" until motion ceases and the DOT time-out period elapses, then return to "non-operating" state. (3) If a customer enables Digital Signage, the ZR will not restart Digital Signage content playback until motion ceases and the "Start displaying content {x} min after a meeting ends" period elapses.
Automatic check-in for Zoom Rooms based on motion sensor data.
Display occupancy status for Zoom Rooms when motion is detected.

2. INTERFACES

2.1 The Sensor Capability

The ZR VendorOS API has defined a sensor capability since version 1.4. The ZRC Vendor OS API added a new sensor capability in version 1.9. Specifically, it added 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() {
        ...
    }
}

The ZR VendorOS API has defined the ISensorManager interface and a SensorCapability for motion sensors since version 1.5.

The ZRC Vendor OS API added a new ISensorManager interface and a SensorCapability for motion sensors in version 1.9.

By signaling the ZRAPI_SENSOR_CAP_MOTION_DETECT capability, the vendor firmware signals it is capable of sending events when motion is detected.

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

public interface SensorCapability {
    /**
     * The capability of motion detection
     */
    public static final int ZRAPI_SENSOR_CAP_MOTION_DETECT = 0x40;
}

2.2 The Motion Sensor Events

/**
 * States / Events Broadcasts intent definition
 */

public interface ZRIntentDefinition {
    /**
     * [OPTIONAL, MUST if needs to support motion sensor]
     * <p>
     * Event for vendor system to notify the ZR app that motion has been 
     * detected; emit this notification every 15 seconds. These motion 
     * events are useful, for instance, to prevent the system from entering 
     * Device Operation Time sleep or to wake it from its current Device 
     * Operation Time sleep state.
     */
    public static final String EVENT_SENSOR_DETECT_MOTION 
        = "us.zoom.zr.vendoros.event.SENSOR_DETECT_MOTION";    
}

The Vendor OS API adds a broadcast Intent (i.e. EVENT_SENSOR_DETECT_MOTION, see the code above) to be used by vendor firmware to notify ZR/ZRC app that motion has been detected. To prevent flooding of motion events, the EVENT_SENSOR_DETECT_MOTION must only be emitted every 15 seconds. The sending strategy is:

If there has been no motion in the prior 15 seconds period, and no motion event intent sent in the prior 15 seconds period, the Vendor OS should send the ZR/ZRC app a motion event intent immediately once motion occurs.
If a motion event intent had been sent in the prior 15 second period, and new motion occurs, schedule to send the ZR/ZRC app a motion event intent in the future (when the current 15 second period elapses).

3. ALLOW-LIST

The motion sensor API is implemented in the ZR/ZRC Vendor OS API and used by the ZR/ZRC application, but the ZR/ZRC device must be added to a Zoom cloud allow-list in order for motion sensor-dependent features to function. If the device has not been added to the allow-list, motion sensor event intents will be ignored. Only the devices which have passed motion sensor testing will be added to the allow-list. Please contact your Zoom HW partnerships representative for further details about motion sensor testing.

4. DIAGRAM

ZRC_Motion_Sensor_API_Diagram

# How to implement the motion sensor API?

# 1. INTRODUCTION

# 2. INTERFACES

# 2.1 The Sensor Capability

# 2.2 The Motion Sensor Events

# 3. ALLOW-LIST