Cloud APIsLocal APIs
Local Documentation
nureva.com
Start typing to search…

Set room layout zones information

📘

This feature is supported by HDL300, Dual HDL300, HDL410, and HDX systems.

This tutorial shows how to configure the zones layout for the room where Nureva® audio devices are located.

What can be controlled with the API?

Zones can be added, modified, and removed by configuring the zones within the list zones.

  • zones: The list of configured zones in the room. Each zone is defined by the following attributes:
    • type: The zone type. Possible values are "Switching" and "Active". A value of "Switching" indicates that the zone is a camera zone, and a value of "Active" indicates that the zone is an active zone.
    • activeZoneControl: This property can only be configured for active zones. It describes the audio bar the zone is attached to. For Dual HDL300 devices, possible values are "AUDIO_BAR_0" for the primary audio component, and "AUDIO_BAR_1" for the secondary audio component. For HDL300 devices, the only possible value is "AUDIO_BAR_0".
    • on: A boolean representing whether or not the zone is on. This value can be configured for active zones, but camera zones must always be on.
    • geometry: The position of the zone defined by two coordinates, point1 and point2. The attributes point1 and point2 represent the opposite corners of the rectangular or square zone.
      • point1: The x and y location of one corner of the zone's bounding box in millimeters.
      • point2: The x and y location of the opposite corner of the zone's bounding box in millimeters.
    • label: The label given to the zone.
    • id: The unique identifier of the zone.

The same coordinate system is used for audio component positions, zone positions and sound location data. Refer to the coordinate system diagram in the Start Device Data Stream endpoint. The origin is defined as the center back of the primary audio component.


Validations

HDL300 and Dual HDL300

  • HDL300 and Dual HDL300 devices only support active zones.
  • One of the edges of the active zone must be lined up with an audio component, and the audio component must be centered on that edge.
  • Only one active zone is supported.
  • The minimum allowed size for an active zone is 8ft by 8ft.
  • The maximum allowed size for an active zone is 25ft by 25 ft.

HDL410

  • HDL410 devices only support camera zones.
  • Camera zones can be positioned outside of the configured room dimensions, however, the zones cannot overlap.
  • For HDL410 devices, a maximum of eight camera zones can be created in each room.
  • For HDL410 devices, the minimum size of a camera zone is 8ft by 8ft.
  • Camera zones cannot be turned off.

HDX

  • HDX devices only support camera zones.
  • Camera zones can be positioned outside of the configured room dimensions, however, the zones cannot overlap.
  • For HDX devices, a maximum of sixteen camera zones can be created in each room.
  • For HDX devices, the minimum size of a camera zone is 1m by 1m.
  • Camera zones cannot be turned off.

Minimum role required: integrator

The Set Room Layout endpoint can be accessed with the integrator role or any role of a higher level.


Overview

  1. Use the Get Room Layout endpoint to get the current zones configuration.
  2. Use the Set Room Layout endpoint to make a request to change the zones configuration.
  3. Use the Get Room Layout endpoint to check that the change has been applied successfully.

Instructions

Step 1 - Make a request to get the current zones configuration

Use the Get Room Layout Information endpoint:

  1. Set the path with the IP address of the Nureva® device followed by /api/v1/room/layout.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint.
  3. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
  4. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
  5. Send the GET request. The code sample below is a request to retrieve the zones configuration of the room of the device with the IP address of 10.0.0.1.
curl --request GET \
     --url https://10.0.0.1/api/v1/room/layout \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'
  1. If the call is successful, an HTTP status code of 200 OK will be returned.

Step 2 - Make a request to update the zones configuration

Use the Set Room Layout Information endpoint:

  1. Set the path with the IP address of the Nureva® device followed by /api/v1/room/layout.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint.
  3. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
  4. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
  5. Update the headers to include Content-type as key and application/json as value.
  6. Update the request body to send a JSON object with updated zones information
curl --request PATCH \
     --url https://10.0.0.1/api/v1/room/layout \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'\
     --header 'Content-type: application/json' \
     --data '{"zones": [{"type": "Switching","on": true,"geometry": {"point1": {"x": -1680,"y": 55},"point2": {"x": 2500,"y": 3729}},"label": "Camera Zone 1","id": "898f31e7-f72c-478f-ba62-4c7a058e7081"}]}'
  1. Send the PATCH request.
  2. If the call is successful, an HTTP status code of 200 OK will be returned.

Step 3 - Check that the change has been applied successfully

Use the Get Room Layout Information endpoint:

  1. Set the path with the IP address of the Nureva® device followed by /api/v1/room/layout.
  2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint.
  3. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
  4. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
  5. Send the GET request. The code sample below is a request to retrieve the zones configuration of the room of the device with the IP address of 10.0.0.1.
curl --request GET \
     --url https://10.0.0.1/api/v1/room/layout \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'
  1. If the call is successful, an HTTP status code of 200 OK will be returned.
  2. Check that the value of zones matches the zones sent in step 2.

The example below indicates that the change was successfully applied, for the PATCH call in step 2.

{
  "zones": [
    {
      "type": "Switching",
      "on": true,
      "geometry": {
        "point1": {
          "x": -1680,
          "y": 55
        },
        "point2": {
          "x": 2500,
          "y": 3729
        }
      },
      "label": "Camera Zone 1",
      "id": "898f31e7-f72c-478f-ba62-4c7a058e7081"
    }
  ]
}

✅

Tutorial complete!

You now know how to set the zones configuration information.

Updated about 3 hours ago