Set room dimensions

📘

Only HDL410 systems support this feature.

This tutorial shows how to set the room dimensions of the room where Nureva® audio devices are located.

What can be controlled with the API?

• roomDimensionsVerified: Whether or not the room dimensions have been verified. Possible values are:
  • true
  • false
• roomDimensions: The dimensions of the room where the audio devices are located. All numeric values for the room dimensions are in millimeters. The room dimensions are defined by the following four points:
  • xMin: The x-coordinate of the room wall along the negative x-axis, relative to the origin. This value is negative or zero.
  • xMax: The x-coordinate of the room wall along the positive x-axis, relative to the origin. This value is positive or zero.
  • yMin: The y-coordinate of the room wall along the negative y-axis, relative to the origin. This value is negative or zero.
  • yMax: The y-coordinate of the room wall along the positive y-axis, relative to the origin. This value is positive or zero.

Room dimensions

Coordinate system

The origin of the coordinate system is the center back of the primary audio component. The room dimensions are defined by four points, (xMin, 0), (xMax, 0), (0, yMin), and (0, yMax), each relative to the origin. Refer to the following diagram for a visual representation of xMin, xMax, yMin, yMax. The numeric values for the points are in millimeters.

Validations

HDL410

• The minimum room size supported for HDL410 devices is 12' x 12' (3.7 x 3.7 m). Room layout configurations smaller than this are not permitted.
• The maximum room size supported for HDL410 devices is 35' x 55' (10.7 x 16.8 m). Room layout configurations larger than this are permitted but audio performance may not be optimal.
• The room dimensions cannot be modified such that one or more audio components would be partially or fully outside of the room.

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 room dimensions.
2. Use the Set Room Layout endpoint to make a request to change the room dimensions.
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 room dimensions

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 room dimensions 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'

6. If the call is successful, an HTTP status code of 200 OK will be returned.

Step 2 - Make a request to update the room dimensions

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 room dimensions

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 '{"roomDimensionsVerified":true,"roomDimensions":"xMin":-3000,"xMax":3000,"yMin":-500,"yMax":9000}'

7. Send the PATCH request.
8. 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 room dimensions 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'

6. If the call is successful, an HTTP status code of 200 OK will be returned.
7. Check that the value of roomDimensions matches the roomDimensions sent in step 2.

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

{
  "roomDimensionsVerified": true,
  "roomDimensions": {
    "xMin": -3000,
    "xMax": 3000,
    "yMin": -500,
    "yMax": 9000
  }
}

✅

Tutorial complete!

You now know how to get the room layout information.