Zone
A Zone is user defined region comprised of three or more vertices. Users can define zones for the Notification API or the Search API. Each zone has a user defined name and color. The name can be used in notifications, whereas the color is purely for UI consistency across clients. A zone is specific to an Accessory. Zones are universal on the Accessory level, and all clients will see the same list of zones per Accessory. Zones are retrieved via Get Zones by Accessory Id and set via Set Zones by Accessory Id. A maximum of 5 user-defined zones are allowed.
There is a special system defined zone called the Remainder Zone.
Definition
attribute_name ::= "motionZones"
user_values ::= string
"z1"
| "z2"
| "z3"
| "z4"
| "z5"
system_values ::= string
"zR" Remainder Zone
Coordinate System
Each vertex is made up of two points, an X and a Y value. The coordinate system goes from 0 to 1.0 in each direction with (0,0) being the top left corner of the video frame, (1.0,1.0) being the bottom right, and (0.5,0.5) being the middle. X goes across the image, while Y goes down the image. Each point can be a full floating point value. Coordinate points are resolution independent and always use the full width as 1.0 and the full height as 1.0.

A zone is typically made up of four to eight vertices
Field Name | Type | Description |
---|---|---|
id | string | The zone id for this. Must be one of "z1", "z2", "z3", "z4" or "z5". This Zone Id is used in the Activity Filter Syntax. Must be unique within the zones for a given Accessory. |
name | string | The user supplied name for the zone. |
vertices | array of vertex objects | Each vertex is an object with keys x and y in floating point values. |
color | string | Used in UI for visual continuity. Must be unique within the zones for a given Accessory. Uses the same values as Object Color. |
interior | bool | true if this zone area the interior of the points. (Defaults to true, and can be left out.) |
aspectRatio | string | (Optional) defaults to "16:9" if not present. |
Examples
{
"id": "z1",
"name": "Front Window",
"vertices": [
{ "x": 0.25, "y": 0.25 },
{ "x": 0.75, "y": 0.25 },
{ "x": 0.75, "y": 0.75 },
{ "x": 0.25, "y": 0.75 }
],
"color": "BU",
}

The example below shows a complex shaped zone.
{
"id": "z2",
"name": "Funny Clock",
"vertices": [
{ "x": 0, "y": 0.5 },
{ "x": 0.125, "y": 0.25 },
{ "x": 0.375, "y": 0.25 },
{ "x": 0.5, "y": 0.5 },
{ "x": 0.375, "y": 0.75 },
{ "x": 0.125, "y": 0.75 },
],
"color": "YE",
}

Remainder Zone
The Remainder Zone is a special system defined Zone which represents all of the space which is not contained within any of the zones defined by the user. The remainder zone has a system wide unique id found below. It can be used in the Activity Filter Syntax as part of the Get Activities by Accessory Id and Notification Events filtering. The Remainder Zone will not be listed in the results of Get Zones by Accessory Id nor can be it set in Set Zones by Accessory Id as it is system calculated.
In the image below, the light green area is the automatically computed Remainder Zone, since z1
and z2
are user defined zones.

In the image below, since there are no user-defined zones, the Remainder Zone is the entire image.

Updated almost 4 years ago