How to implement the motion sensor API?

1. INTRODUCTION

The ZR(ZoomRooms) would sleep when out of operation time if you have configured the device operation time in the web portal. It's a natural and convenient way to wake up the ZR when detecting the motions in the room. These days, many of the ZRC(ZoomRooms Controller) devices have motion sensors(e.g. the PIR sensor). Therefore, we defined the Motion Sensor API in our Vendor OS API to support the motion sensor wake-up. By implementing the motion sensor API, the ZRC could support the device operation time sleep wake-up automatically (Though we should add the verified device to our motion sensor whitelist). Similarly, the motion sensor wake-up also applies to the digital signage except for the digital signage-only rooms. The motion events would wake up the digital signage as well, i.e. stop playing the digital signage content once detecting the motions.

There are 2 scenarios of motion sensor wake-up:

• If the ZR is in operation time sleep or playing the digital signage content, and subsequently the motion sensor on the ZRC device detects there is a person in the room(motions are detected), the ZRC would wake up the ZR immediately.
• If the motion sensor on the ZRC device detects there are motions continuously, the ZR would stay idle and not go into operation time sleep or play digital signage content until the motion in the room has ceased for a period of time. The time duration depends on the configurations in the web portal. For example, if you have enabled the device operation time, then the duration is the idle time out or the default 18-minute delay that is part of the schedule-based operation time out. The digital signage is also similar.

2. INTERFACES

2.1 The Sensor Capability

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 {
    /**
     * Define the capability of sensor manager API
     * <p>
     * <b><i>Required Field</i></b>
     */
    public static final int ZRAPI_CAP_SENSOR = 0x08;

    /**
     * Get sensor manager interface
     *
     * @return {@link ISensorManager}
     */
    public ISensorManager getSensorManager() {
        ...
    }
}

Besides the motion sensors, there are many other sensors, like the temperature sensor, the humidity sensor, etc. So the ISensorManager uses the SensorCapability to get the capabilities of different sensors:

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

The Vendor OS API adds a broadcast Intent(i.e. EVENT_SENSOR_DETECT_MOTION, see the code below) to let the partner's firmware notify the motion they have detected to the ZRC application. Additionally, to prevent flooded motion events, the EVENT_SENSOR_DETECT_MOTION could 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 ZRC a motion event intent right away once motion occurs.
• If a motion event intent had been sent in the prior 15 seconds period, and motion occurs, schedule to send the ZRC an intent in the future(Next 15 seconds period).

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

public interface ZRIntentDefinition {
    /**
     * Event for vendor system to notify the ZR app that motion has been detected and prevent the system from entering
     * Device Operation Time sleep (or wake it from currently being in Device Operation Time sleep); only emit this event
     * when the room state is {@link ZoomRoomsState#ZOOM_ROOMS_IDLE}, and only emit it every 15 seconds.
     */
    public static final String EVENT_SENSOR_DETECT_MOTION = "us.zoom.zr.vendoros.event.SENSOR_DETECT_MOTION";    
}

2.3 Start/Stop the Motion Detection

As we mentioned in the previous section, the motion sensors are used for waking up the ZR. But if you are doing something on the ZR, e.g. having a meeting, drawing the whiteboard, etc. The ZR would not sleep or play digital signage actually. Then motion detection is not necessary anymore. Stopping the detection while it is useless would be better because it is possibly energy-consuming. As a matter of fact, there is a convenient/tricky way to start or stop the motion sensors in real time. That is, start the motion detection when the ZR is in an idle state(The room state is 0), and stop the motion detection when the ZR is not in an idle state. To clarify it, the Vendor OS adds the ZOOM_ROOMS_IDLE room state to stand for the idle state:

/**
 * Zoom Rooms state definition
 */
public interface ZoomRoomsState {
    /**
     * Zoom Room is idle
     * <p>
     * After receiving this state when the work mode is {@link ISystemManager#ZRCWorkMode_Controller}
     * which is reported by {@link ISystemManager#reportWorkMode(int)}, you could start the motion detection
     * and send the motion sensor events by {@link ZRIntentDefinition#EVENT_SENSOR_DETECT_MOTION}. In
     * addition, you could stop the motion detection when you receive the non-idle state.
     */
    public static final int ZOOM_ROOMS_IDLE = 0x0;
}

3. WHITELIST

The motion sensor API is implemented in the Vendor OS API and called by the ZRC application. To enable the motion sensor wake-up feature, the ZRC device should be added to the Zoom cloud whitelist even if this API has been implemented. Only the devices which have passed the motion sensor test could be added to the whitelist. Certainly, if the motion sensor API is corrupted by accident while upgrading the firmware, you could contact us to remove it from the whitelist. This would disable the motion sensor wake-up temporarily.

4. DIAGRAM