1. Introduction

WASP (Web AudioScience Protocol) is an HTTP based control protocol for AudioScience devices.

This document describes all the information published by an AudioScience device that implements a WASP server. Enough detail is provided to implement both very simple clients and more advanced clients (more caching and control update tracking).

2. Overview

At the highest level of abstraction a WASP device publishes two types of documents:

  1. Machine readable schemas that specifies WASP object instances.

  2. WASP object instances that can be queried and updated.

Properties in WASP objects represent either protocol related information or object state information and settings. Property names starting with an underscore _ character are protocol related and do not represent object settings or state. For example, all WASP objects have an _id property identifying it for lookup purposes and a ctrl:trim_level object has a level property controlling the full scale voltage of the analog input or output associated with the object.

3. Protocol description

WASP is a set of conventions and restrictions on HTTP 1.1 request and responses specified in the following sections.

3.1. HTTP URLs prefix

All URL destinations for WASP requests start with the /wasp/r2 prefix.

3.2. HTTP URLs endpoints

Endpoint paths are concatenated to the URL prefix. The following endpoints are available:

Endpoint path Summary Supported HTTP method

/device/auth

Authenticate a client.

/device/info

Retrieve information for this device.

GET, HEAD

/device/ping

Check if the device is reachable and responsive.

GET

/objects

Device objects array

This endpoint allows bulk enumeration of all WASP objects present on the device.

GET, HEAD, PATCH

/objects/{id}

Retrieve or update object by {id}

GET, PATCH

/objects/{id}/{prop}

Retrieve or update property {prop} of object {id}

GET, PATCH

/schemas

Schema array

This endpoint allows bulk enumeration of all WASP schemas present on the device.

GET

/schemas/{id}

Retrieve schema by {id}

GET

3.2.1. /device/auth

Authenticate a client.

3.2.1.1. POST - Request an authentication token.

Allows clients to request an autentication token to be used for requests to other API endpoints. Currently the authentication token request does not require any credentials i.e. the device allows password-less access. In the future the authentication mechanism will be extended to require credentials. Clients currenly authenticate by sending a POST request to the /device/auth endpoint including an Authorization: Hawk HTTP header.

The body of the request is empty

Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

3.2.1.1.1. Response status 200 - Request successful.

The authentication token is returned in the id field of the JSON reply. Clients then transmit the token as part of all API requests in the Authorization header like so: Authorization: Hawk id="OBTAINED_ID".

Response body with Content-Type: application/json
Response body example
{
    "id": "dh37fgj492je"
}

3.2.2. /device/info

Retrieve information for this device.

3.2.2.1. GET - Retrieve device information.

Allows clients to retrieve device information without enumerating all objects on the device. The body of the response is a list of objects with information about the device. The object list includes a device:user_data object, a device:sw_desc object and a device:hw_desc object. The WASP API version and the device firmware version are returned in the response as HTTP headers independently of the payload. See the headers description for further details.

The body of the request is empty

3.2.2.1.1. Response status 200 - Request successful.

The response body is an instance of a device:user_data object.

Response body with Content-Type: application/json
Response body example
{
    "_id": 4,
    "_parent": null,
    "_schema": "_DeviceUserData",
    "_type": "device:user_data",
    "label": ""
}
Response headers
Allow - List HTTP methods allowed on this endpoint.

Example header: Allow: GET, HEAD

X-Wasp-Api-Version - WASP API version

Example header: X-Wasp-Api-Version: 2.0.7

X-Wasp-Firmware-Version - Device firmware version.

Example header: X-Wasp-Firmware-Version: 1.0.2

X-Wasp-Objects-Digest - Digest of object list.

This value changes when the object list available for retrieval from the /objects endpoint changes. The object list is considered changed when an object is added or removed from the list or when an object type changes.

Example header: X-Wasp-Objects-Digest: 17dd9372df55ffdcc2eb43e3eda5def0

X-Wasp-Schemas-Digest - Digest of object schemas.

This value changes when the schemas available for retrieval from the /schemas endpoint change.

Example header: X-Wasp-Schemas-Digest: 17dd9372df55ffdcc2eb43e3eda5def0

3.2.2.2. HEAD - Retrieve API and firmware version information.

The WASP API version and the device firmware version are returned in the response as HTTP headers. See the headers description for further details.

The body of the request is empty

3.2.2.2.1. Response status 200 - Request successful.

The body of the response is empty

Response headers
Allow - List HTTP methods allowed on this endpoint.

Example header: Allow: GET, HEAD

X-Wasp-Api-Version - WASP API version

Example header: X-Wasp-Api-Version: 2.0.7

X-Wasp-Firmware-Version - Device firmware version.

Example header: X-Wasp-Firmware-Version: 1.0.2

X-Wasp-Objects-Digest - Digest of object list.

This value changes when the object list available for retrieval from the /objects endpoint changes. The object list is considered changed when an object is added or removed from the list or when an object type changes.

Example header: X-Wasp-Objects-Digest: 17dd9372df55ffdcc2eb43e3eda5def0

X-Wasp-Schemas-Digest - Digest of object schemas.

This value changes when the schemas available for retrieval from the /schemas endpoint change.

Example header: X-Wasp-Schemas-Digest: 17dd9372df55ffdcc2eb43e3eda5def0

3.2.3. /device/ping

Check if the device is reachable and responsive.

3.2.3.1. GET - Check if the device is reachable and responsive.

The body of the request is empty

3.2.3.1.1. Response status 200 - Device alive and well

If the request times out or the device does not respond within a resonable interval the client should assume it became unavailable. The client may re-try connecting to the device periodically.

To avoid oveloading the device, when trying to connect periodically, connection attempts should not exceed one attempt per second and the interval between attempts should increase exponentially each time the connection fails.

The X-Wasp-poll-interval is included in each response to provide a minimum ping interval guideline for clients.

The body of the response is empty

Response headers
X-Wasp-poll-interval - Recommended client polling intervals.

This header is included in all responses returning status 202 (Accepted/In Progress) and /device/ping GET responses. The format of the header is a triple of numbers separated by commas. The first number is the expected time for completion of the request in milliseconds and should be used as the minimum initial polling interval. The second number is the minimum polling interval in milliseconds after the initial polling interval. The third number is the request timeout in milliseconds. A request timeout of -1 indicates no timeout. In all valid timeout cases, the returned request timeout will be greater than the minimum initial polling interval.

Example header: X-Wasp-poll-interval: 200,100,1000

3.2.4. /objects

Device objects array

This endpoint allows bulk enumeration of all WASP objects present on the device.

3.2.4.1. GET - Enumerate objects

The body of the request is empty

Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Range - Restrict index range of items returned.

This request header informs the server to restrict the items included in the response to a (zero based) interval of indexes. For instance, if the client includes the header Range: items=0-9 in its request, the server will respond by listing only items from index 0 to index 9 (included).

The format of the header is Range: items=START_INDEX-[END_INDEX] where END_INDEX is optional and if missing will be interpreted to mean the last item available.

3.2.4.1.1. Response status 200 - Get all objects.

The response body is an array containing the current state of all WASP objects present on the device.

Response body with Content-Type: application/json
Response body example
[
    {
        "_id": 4,
        "_parent": null,
        "_schema": "_DeviceUserData",
        "_type": "device:user_data",
        "label": ""
    },
    {
        "_id": 5,
        "_parent": null,
        "_schema": "_SoftwareDescriptor",
        "_type": "device:sw_desc",
        "name": "Iyo Dante firmware",
        "vendor": "AudioScience Inc",
        "version": "1.0.2"
    },
    {
        "_id": 6,
        "_parent": null,
        "_schema": "_HardwareDescriptor",
        "_type": "device:hw_desc",
        "manufacturer": "AudioScience Inc",
        "name": "Iyo Dante 32.32M",
        "part_number": "ASI2703",
        "revision": "1.0.2",
        "serial_number": "75643"
    },
    {
        "_id": 9,
        "_parent": 7,
        "_schema": "_TrimControl",
        "_type": "ctrl:trim_level",
        "level": 14
    }
]
Response headers
Accept-Ranges - Items range accepted.

WASP always includes this header in replies to requests that can accept a restriction on the range of items included in the response. The included header always appears as follows: Accept-Ranges: items.

Content-Range - Indicate range of items included in the response and total available count.

WASP always includes this header in replies to requests that can accept a restriction on the range of items included in the response. When no range restriction is specified in the request, the header reports the full range of items e.g. in the case of a 50 items array, the header will show Content-Range: items 0-49/50.

When the request specifies a range restriction, the reply will include the requested interval plus the total available item count e.g. in the case of a request with Range: items=0-9 on a resource which has 50 items available, the reply will include Content-Range: items 0-9/50

3.2.4.1.2. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.4.2. HEAD - Enumerate objects

The body of the request is empty

Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Range - Restrict index range of items returned.

This request header informs the server to restrict the items included in the response to a (zero based) interval of indexes. For instance, if the client includes the header Range: items=0-9 in its request, the server will respond by listing only items from index 0 to index 9 (included).

The format of the header is Range: items=START_INDEX-[END_INDEX] where END_INDEX is optional and if missing will be interpreted to mean the last item available.

3.2.4.2.1. Response status 200 - Get number of device objects.

The response contains useful header information and the body of the response may be ignored. A client can obtain the total count of objects on the device from the returned headers.

The body of the response is empty

Response headers
Accept-Ranges - Items range accepted.

WASP always includes this header in replies to requests that can accept a restriction on the range of items included in the response. The included header always appears as follows: Accept-Ranges: items.

Allow - List HTTP methods allowed on this endpoint.

Example header: Allow: GET, HEAD

Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Content-Range - Indicate range of items included in the response and total available count.

WASP always includes this header in replies to requests that can accept a restriction on the range of items included in the response. When no range restriction is specified in the request, the header reports the full range of items e.g. in the case of a 50 items array, the header will show Content-Range: items 0-49/50.

When the request specifies a range restriction, the reply will include the requested interval plus the total available item count e.g. in the case of a request with Range: items=0-9 on a resource which has 50 items available, the reply will include Content-Range: items 0-9/50

3.2.4.2.2. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.4.3. PATCH - Update one or more objects with a single request.

The body of a bulk PATCH request is a list of mappings. Each mapping is equivalent to the body of a standalone PATCH request with the addition of an _id property which indicates which object ID the update mapping is intended for. Only updated properties need to appear in the mapping. For instance a PATCH request to a ctrl:trim_level object with ID equal to 34 only needs to contain the mapping {"_id": 34, "level": 3} to change the level to 3.

When the request fails because one of the object updates carried in the body is rejected, a standard Link header with rel="self" is included in the response to identify which object update caused the request to fail. Object updates are applied, in order, up to but excluding the failing update. No object updates after the failing update are applied.

Request body with Content-Type: application/json
Request body example
[
    {
        "_id": 34,
        "level": 3
    },
    {
        "_id": 38,
        "level": 7
    },
    {
        "_id": 36,
        "level": 0
    }
]
Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Range - Restrict index range of items returned.

This request header informs the server to restrict the items included in the response to a (zero based) interval of indexes. For instance, if the client includes the header Range: items=0-9 in its request, the server will respond by listing only items from index 0 to index 9 (included).

The format of the header is Range: items=START_INDEX-[END_INDEX] where END_INDEX is optional and if missing will be interpreted to mean the last item available.

3.2.4.3.1. Response status 200 - Update completed successfully.

The body of the response is empty

3.2.4.3.2. Response status 202 - Update request accepted and in progress.

The device responds with this status code when one of more of the requested property updates cannot complete synchronously. The client can poll the object state following the intervals suggested by the values carried by the X-Wasp-poll-interval header to find out if/when the changes have taken effect. If the client is connected to the object update event stream, then polling is not necessary and a value update event for the relevant updated properties will be received through the object update stream. When listening to object update events, the client should still consider the request as timed out if no update event appears in the event stream before the timeout interval specified by the X-Wasp-poll-interval header.

The body of the response is empty

Response headers
X-Wasp-poll-interval - Recommended client polling intervals.

This header is included in all responses returning status 202 (Accepted/In Progress) and /device/ping GET responses. The format of the header is a triple of numbers separated by commas. The first number is the expected time for completion of the request in milliseconds and should be used as the minimum initial polling interval. The second number is the minimum polling interval in milliseconds after the initial polling interval. The third number is the request timeout in milliseconds. A request timeout of -1 indicates no timeout. In all valid timeout cases, the returned request timeout will be greater than the minimum initial polling interval.

Example header: X-Wasp-poll-interval: 200,100,1000

3.2.4.3.3. Response status 400 - Invalid request.

The request was rejected because one or more of its parameters was invalid. In case of a bulk PATCH operation a standard Link header with rel="self" is included in the response to identify which object update caused the request to fail.

The body of the response is empty

Response headers
Link - Link header used to associate URLs with a specific relationship with a resource.

Example header: Link: </objects/8>; rel="self"

3.2.4.3.4. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.5. /objects/{id}

Retrieve or update object by {id}

3.2.5.1. GET - Get an object

The body of the request is empty

Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Content-Length - Clients must include this header within their request when sending a body.

Size of the request’s (or response) body in bytes.

3.2.5.1.1. Response status 200 - Request successful.

The current state of the object instance at index {id} is returned as the body of the response. The object layout (i.e. the number, name, type and values of its properties) depends on its WASP type carried by the _type property.

Response body with Content-Type: application/json
Response body example
{
    "_id": 8,
    "_parent": 7,
    "_schema": "_PhantomPowerControl",
    "_type": "ctrl:phantom",
    "active": true,
    "voltage": 48
}
3.2.5.1.2. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.5.2. PATCH - Update one or more properties of an object.

The body of a PATCH request is a mapping between properties and their new values. Only updated properties need to appear in the mapping. For instance a PATCH request to a ctrl:trim_level object only needs to contain the mapping {"level": 3} to change the level to 3.

Request body with Content-Type: application/json
Request body example
{
    "level": 3
}
Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Content-Length - Clients must include this header within their request when sending a body.

Size of the request’s (or response) body in bytes.

3.2.5.2.1. Response status 200 - Update completed successfully.

The body of the response is empty

3.2.5.2.2. Response status 202 - Update request accepted and in progress.

The device responds with this status code when one of more of the requested property updates cannot complete synchronously. The client can poll the object state following the intervals suggested by the values carried by the X-Wasp-poll-interval header to find out if/when the changes have taken effect. If the client is connected to the object update event stream, then polling is not necessary and a value update event for the relevant updated properties will be received through the object update stream. When listening to object update events, the client should still consider the request as timed out if no update event appears in the event stream before the timeout interval specified by the X-Wasp-poll-interval header.

The body of the response is empty

Response headers
X-Wasp-poll-interval - Recommended client polling intervals.

This header is included in all responses returning status 202 (Accepted/In Progress) and /device/ping GET responses. The format of the header is a triple of numbers separated by commas. The first number is the expected time for completion of the request in milliseconds and should be used as the minimum initial polling interval. The second number is the minimum polling interval in milliseconds after the initial polling interval. The third number is the request timeout in milliseconds. A request timeout of -1 indicates no timeout. In all valid timeout cases, the returned request timeout will be greater than the minimum initial polling interval.

Example header: X-Wasp-poll-interval: 200,100,1000

3.2.5.2.3. Response status 400 - Invalid request.

The request was rejected because one or more of its parameters was invalid. In case of a bulk PATCH operation a standard Link header with rel="self" is included in the response to identify which object update caused the request to fail.

The body of the response is empty

Response headers
Link - Link header used to associate URLs with a specific relationship with a resource.

Example header: Link: </objects/8>; rel="self"

3.2.5.2.4. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.6. /objects/{id}/{prop}

Retrieve or update property {prop} of object {id}

3.2.6.1. GET - Get the value of property {prop} of object {id}.

The body of the request is empty

Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Content-Length - Clients must include this header within their request when sending a body.

Size of the request’s (or response) body in bytes.

3.2.6.1.1. Response status 200 - Request successful.

The current state of the property {prop} of the object instance at index {id} is returned as the body of the response.

For instance, if the level property of a ctrl:trim_level object is requested using this endpoint, the response will contain just the naked value of the requested property i.e. if the value is 3, the body of the response will be 3, not {"level": 3}.

Response body with Content-Type: application/json
3.2.6.1.2. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.6.2. PATCH - Update the value of property {prop} of object {id}.

The body of a PATCH request is the naked (new) value of the property the client is requesting to change.

For instance, if the client wishes to change the level property of a ctrl:trim_level object, it will send a request body containing only the naked value of the property i.e. if the new value is 7, the body of the request will be 7 not {"level": 7}.

Request body with Content-Type: application/json
Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

Content-Length - Clients must include this header within their request when sending a body.

Size of the request’s (or response) body in bytes.

3.2.6.2.1. Response status 200 - Update completed successfully.

The body of the response is empty

3.2.6.2.2. Response status 202 - Update request accepted and in progress.

The device responds with this status code when one of more of the requested property updates cannot complete synchronously. The client can poll the object state following the intervals suggested by the values carried by the X-Wasp-poll-interval header to find out if/when the changes have taken effect. If the client is connected to the object update event stream, then polling is not necessary and a value update event for the relevant updated properties will be received through the object update stream. When listening to object update events, the client should still consider the request as timed out if no update event appears in the event stream before the timeout interval specified by the X-Wasp-poll-interval header.

The body of the response is empty

Response headers
X-Wasp-poll-interval - Recommended client polling intervals.

This header is included in all responses returning status 202 (Accepted/In Progress) and /device/ping GET responses. The format of the header is a triple of numbers separated by commas. The first number is the expected time for completion of the request in milliseconds and should be used as the minimum initial polling interval. The second number is the minimum polling interval in milliseconds after the initial polling interval. The third number is the request timeout in milliseconds. A request timeout of -1 indicates no timeout. In all valid timeout cases, the returned request timeout will be greater than the minimum initial polling interval.

Example header: X-Wasp-poll-interval: 200,100,1000

3.2.6.2.3. Response status 400 - Invalid request.

The request was rejected because one or more of its parameters was invalid. In case of a bulk PATCH operation a standard Link header with rel="self" is included in the response to identify which object update caused the request to fail.

The body of the response is empty

Response headers
Link - Link header used to associate URLs with a specific relationship with a resource.

Example header: Link: </objects/8>; rel="self"

3.2.6.2.4. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.7. /schemas

Schema array

This endpoint allows bulk enumeration of all WASP schemas present on the device.

3.2.7.1. GET - Enumerate schemas

The body of the request is empty

Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

3.2.7.1.1. Response status 200 - Get a list of schemas.

This endpoint allows bulk enumeration of all WASP schemas present on the device.

Response body with Content-Type: application/json
3.2.7.1.2. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.2.8. /schemas/{id}

Retrieve schema by {id}

3.2.8.1. GET - Get a schema by {id}

The body of the request is empty

Request headers
Authorization - Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

3.2.8.1.1. Response status 200 - Get a schema by {id}.
Response body with Content-Type: application/json
3.2.8.1.2. Response status 401 - The request is not authorized.

The client should obtain a new authentication token from the /device/auth endpoint and retry the request including the new token.

The body of the response is empty

Response headers
WWW-Authenticate - Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.3. HTTP methods

WASP supports GET and PATCH HTTP methods respectively mapped to Retrieve and Update CRUD operations on WASP objects and properties.

3.4. HTTP statuses

WASP uses HTTP statuses as specified in the latest revision of the HTTP 1.1 protocol. The following statuses are listed here to clarify their meaning in the context of WASP transactions:

  • 200 : The request completed successfully and its side-effect was applied.

  • 202 : The request was accepted for execution and is in progress. Its side-effect may not be applied when this status is received.

3.5. HTTP headers

A WASP server supports a number of standard and extension HTTP headers. Unsupported headers are ignored.

3.5.1. Accept-Ranges

Items range accepted.

WASP always includes this header in replies to requests that can accept a restriction on the range of items included in the response. The included header always appears as follows: Accept-Ranges: items.

3.5.2. Allow

List HTTP methods allowed on this endpoint.

Example header: Allow: GET, HEAD

3.5.3. Authorization

Client authorization information.

This request header carries the client authorization information to enable server side access control. If this header is missing and the requested resource requires authorization the server will respond with 401 Not Authorized. If the header carries invalid or expired authorization information the server will respond with 401 Not Authorized.

The format of the header is Authorization: Hawk id="AUTH_ID" where AUTH_ID is the authorization token obtained from the /device/auth endpoint.

3.5.4. Connection

WASP uses the Connection header in its responses to inform the client if the connection should be closed or kept alive. A missing Connection header means Connection: keep-alive as specified by HTTP 1.1.

3.5.5. Content-Length

Clients must include this header within their request when sending a body.

Size of the request’s (or response) body in bytes.

3.5.6. Content-Range

Indicate range of items included in the response and total available count.

WASP always includes this header in replies to requests that can accept a restriction on the range of items included in the response. When no range restriction is specified in the request, the header reports the full range of items e.g. in the case of a 50 items array, the header will show Content-Range: items 0-49/50.

When the request specifies a range restriction, the reply will include the requested interval plus the total available item count e.g. in the case of a request with Range: items=0-9 on a resource which has 50 items available, the reply will include Content-Range: items 0-9/50

3.5.7. Content-Type

Clients must include this header within their request when sending a body.

WASP currently recognizes only Content-Type: application/json.

3.5.8. Link

Link header used to associate URLs with a specific relationship with a resource.

Example header: Link: </objects/8>; rel="self"

3.5.9. Range

Restrict index range of items returned.

This request header informs the server to restrict the items included in the response to a (zero based) interval of indexes. For instance, if the client includes the header Range: items=0-9 in its request, the server will respond by listing only items from index 0 to index 9 (included).

The format of the header is Range: items=START_INDEX-[END_INDEX] where END_INDEX is optional and if missing will be interpreted to mean the last item available.

3.5.10. WWW-Authenticate

Request authentication.

This response header is included with 401 Not Authorized responses and informs the client that authorization is required to access a resource.

The format of the header is WWW-Authenticate: AUTH_METHOD where AUTH_METHOD is always the string Hawk.

3.5.11. X-HTTP-Method-Override

A client missing support for HTTP methods other than GET can include X-HTTP-Method-Override: METHOD in its request to work around the lack of support.

3.5.12. X-Wasp-Api-Version

WASP API version

Example header: X-Wasp-Api-Version: 2.0.7

3.5.13. X-Wasp-Firmware-Version

Device firmware version.

Example header: X-Wasp-Firmware-Version: 1.0.2

3.5.14. X-Wasp-Objects-Digest

Digest of object list.

This value changes when the object list available for retrieval from the /objects endpoint changes. The object list is considered changed when an object is added or removed from the list or when an object type changes.

Example header: X-Wasp-Objects-Digest: 17dd9372df55ffdcc2eb43e3eda5def0

3.5.15. X-Wasp-Schemas-Digest

Digest of object schemas.

This value changes when the schemas available for retrieval from the /schemas endpoint change.

Example header: X-Wasp-Schemas-Digest: 17dd9372df55ffdcc2eb43e3eda5def0

3.5.16. X-Wasp-Stream-Exclude-Obj-Type

Object update stream exclude directive.

This header is only supported by requests to the objects update stream (/u2/objects). All and X-Wasp-Stream-Exclude-Obj-Type headers included in the request are also included in the response.

The value of this header is a semicolon separated list of WASP object type IDs to be excluded from the object update stream. As a special case the * (star) character is allowed in place of a WASP type name and represents all WASP types.

When no X-Wasp-Stream-Exclude-Obj-Type header is sent with a request, a WASP server will send updates for all the object types that are sent by default.

If multiple X-Wasp-Stream-Exclude-Obj-Type headers are sent with a request they are applied in the order they are received by server to establish which object updates to exclude.

Example header: X-Wasp-Stream-Exclude-Obj-Type: ctrl:meter

3.5.17. X-Wasp-Stream-Min-Update-Period

Update stream minimum update period setting in milliseconds.

Selectively apply a minimum update period to one or more object types transmitted by the server via the update stream.

This header is only supported by requests to the objects update stream (/u2/objects). The X-Wasp-Stream-Min-Update-Period header included in the request is also included in the response.

The value of this header is as follows: PERIOD_MS,DISPERSION_MS TYPE_ID[;TYPE_ID] where PERIOD_MS is the minimum period in milliseconds between updates for the semicolon separated list of TYPE_IDs in the same header, and DISPERSION_MS is a maximum value in milliseconds for an uniformly distributed random variable that is added to PERIOD_MS each time an update is sent. The wildcard '*' can be used in place of TYPE_ID to rate limit all updates.

Example header: X-Wasp-Stream-Min-Update-Period: 1000,100 ctrl:meter This sets meter updates to occur every 1000 milliseconds + a random time in the range of 0 to 100 milliseconds.

3.5.18. X-Wasp-poll-interval

Recommended client polling intervals.

This header is included in all responses returning status 202 (Accepted/In Progress) and /device/ping GET responses. The format of the header is a triple of numbers separated by commas. The first number is the expected time for completion of the request in milliseconds and should be used as the minimum initial polling interval. The second number is the minimum polling interval in milliseconds after the initial polling interval. The third number is the request timeout in milliseconds. A request timeout of -1 indicates no timeout. In all valid timeout cases, the returned request timeout will be greater than the minimum initial polling interval.

Example header: X-Wasp-poll-interval: 200,100,1000

3.6. Authentication and sessions

WASP limits access of API endpoints to authenticated clients with the exception of /device/ping and /device/info so client must authenticate to be able to access all API endpoints.

When a client authenticates a new WASP session is created. Sessions expire after a few minutes of client inactivity. WASP considers a client active when it sends requests or it is connected to an object update stream.

3.6.1. Authentication

WASP currently supports authentication without credentials. In other words authentication is used to track client sessions only. In future versions of the protocols the authentication mechanism will require credentials to grant access to the API.

Clients authenticate by sending a POST request to the /device/auth endpoint including an Authorization: Hawk HTTP header. The server will respond with an authentication token ID in the id field of a JSON object. For instance, if the server responds with {"id":"2fds293djs"} than the ID is the 2fds293djs string. Once the client has obtained the authentication ID, it must send it with every request by including an Authorization HTTP header. For instance, if the authorization ID is 2fds293djs the HTTP header will be as follows: Authorization: Hawk id="2fds293djs".

A Client can detect when its authentication token ID has expired by checking the response status code: a response status code of 401 indicates the client is not authorized. Upon receiving a 401 status response the client must discard the entire session bound state and can obtain a new authentication token as described above.

3.6.2. Connection

When a client connects (as opposed to re-connect after detecting a disconnection) if should first execute a GET request to the /device/info endpoint to check basic information about the device it is connecting to. Headers starting with X-Wasp- carried by the response include information about the device firmware and API versions which the client can use to adapt its behavior.

If the client is caching any device state during its operation the values of all headers starting with X-Wasp- should be stored for use if/when a re-connection is attempted.

The client can then proceed with the API requests it needs to perform which may require to complete the authentication step first.

3.6.3. Detect disconnection and re-connect

If any client initiated request times out or result in a network error the client should start a re-connection attempt. A re-connection attempt starts by issuing GET requests the the /device/ping endpoint until the device responds with a 200 status code. Failed ping requests should be re-tried after a minimum interval starting at 1 second and increasing exponentially with each attempt possibly augmented with a random duration between 0 and the next calculated delay.

A client should also implement a maximum retry count and give up re-connection when the maximum retry count is reached.

When the ping request succeeds the client should execute a GET request to the /device/info endpoint and compare all headers starting X-Wasp- included with the response with values of the same headers stored when connecting for the first time. If any of the headers' values differ the client must discard all device state cached and continue as connecting to the device for the first time.

3.7. Client side state

4. Object update stream

4.1. URL Endpoint and HTTP headers

WASP provides an optional HTTP based event stream for a client to track object updates. The update stream endpoint is /wasp/u2/objects. GET and HEAD requests are supported and HTTP status replies follow standard meanings (e.g. the expected response status 202 indicates that the request was accepted, whereas status 404 indicates the endpoint was not available).

In case of a 202 status reply, HTTP headers will include (but not be limited to):

Cache-Control: no-cache
Content-Type: text/event-stream+json
Transfer-Encoding: chunked

The update stream behaviour can be controlled by including X-Wasp-Stream-Min-Update-Period and X-Wasp-Stream-Exclude-Obj-Type headers within the request.

4.2. Event stream transport format

The event stream is a sequence of JSON encoded chunks as specified by RFC7230, additionally to the HTTP chunk framing an ASCII framing is also present to support frame re-assembly in web browsers.

The ASCII framing consists of a header made up by three dashes followed by a newline (---\n) and a trailer made up by a single newline character (\n). The text wrapped by the frame header and trailer is a valid JSON UTF-8 sequence of bytes.

4.3. Event format

Each JSON encoded event transported by the event stream has a _type field. Valid values for the _type field are: update:checkpoint, update:obj, update:group_prefix.

4.3.1. update:checkpoint - Current state of all objects in a single message.

Table 1. Properties specific to object type update:checkpoint
Property name Required Basic schema Description

_type

True

 
{
    "enum": [
        "update:checkpoint"
    ],
    "type": "string"
}

body

True

 
{
    "items": {
        "type": "object"
    },
    "type": "array"
}

Array containing all WASP objects.

path

True

 
{
    "enum": [
        "/objects"
    ],
    "type": "string"
}

URL path to object being updated. Always /objects.
Example 1 for WASP object type update:checkpoint
{
    "_type": "update:checkpoint",
    "body": [
        {
            "_id": 3,
            "_type": "ctrl:level",
            "level": 14
        },
        {
            "_id": 4,
            "_type": "ctrl:level",
            "level": 24
        }
    ],
    "path": "/objects"
}

4.3.2. update:group_prefix - Event carrying updated values to different objects sharing the same target property.

This pseudo code snippet shows how to apply updates encoded by this event type:

for key, value in event.body:
  lookup_object_by_path(prefix + key).prop = value
Table 2. Properties specific to object type update:group_prefix
Property name Required Basic schema Description

_type

True

 
{
    "enum": [
        "update:group_prefix"
    ],
    "type": "string"
}

body

True

 
{
    "items": {
        "type": "object"
    },
    "type": "object"
}

Object mapping each ID of an object being updated with the new value of its {prop} property.

prefix

True

 
{
    "type": "string"
}

URL path prefix of all objects updates included in this event.

prop

True

 
{
    "type": "string"
}

Property name updated by all objects updates included in this event.
Example 1 for WASP object type update:group_prefix
{
    "_type": "update:group_prefix",
    "body": {
        "5": -37,
        "6": -40,
        "7": -3
    },
    "prefix": "/objects/",
    "prop": "peak"
}

4.3.3. update:obj - Object update event.

Table 3. Properties specific to object type update:obj
Property name Required Basic schema Description

_type

True

 
{
    "enum": [
        "update:obj"
    ],
    "type": "string"
}

body

True

 
{
    "type": "object"
}

Object mapping each updated property with its new value.

path

True

 
{
    "type": "string"
}

URL path to object being updated.
Example 1 for WASP object type update:obj
{
    "_type": "update:obj",
    "body": {
        "property1": "new_value1",
        "property2": "new_value2",
        "propertyN": "new_valueN"
    },
    "path": "/objects/34"
}

4.4. Event stream behaviour

The first event sent by the server upon successful client connection is of type update:checkpoint. Following events can be of any supported type.

The server can close the event stream connection at any time. If the server closes the stream connection, the client should check whether the device is still reachable. Once the device is determined to be reachable the client can attempt to reconnect after a backoff period.

5. WASP object space

A WASP device publishes a list of objects for clients to retrieve. Clients can retrieve all objects from a single object list with a single request. By default all properties of objects are included in the response.

Objects can also be retrieved one by one using their ID and updated one by one by including a set of property: new_value mappings as content of a PATCH request.

5.1. Common object properties

All objects published by WASP share a common set of properties shown in the following table.

Table 4. Properties common to all WASP objects
Property name Required Basic schema Description

_id

True

 
{
    "format": "object_id",
    "minimum": 0,
    "readOnly": true,
    "type": "number",
    "wasp-const": true
}

Numeric Object ID, which is also the index of the object in the objects array. This property is a positive integer which uniquely identifies a WASP object instance and it can be used to retrieve or update a single object.

_parent

True

 
{
    "format": "object_id",
    "minimum": 0,
    "readOnly": true,
    "type": [
        "number",
        "null"
    ],
    "wasp-const": true
}

Numeric Object ID and index of an object’s parent in the objects array. Each WASP object instance can be contained by (at most) one other WASP object instance.

_schema

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

Schema ID string. The schema ID identifies the validation schema used to validate an object instance. The ID is only valid for the duration of the session.

_type

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

Object type ID string. The object type ID identifies the type of a WASP object instance.

For instance the response to a GET request sent to a device:user_data object contains the following information:

{
    "_id": 4,
    "_parent": null,
    "_schema": "_DeviceUserData",
    "_type": "device:user_data",
    "label": ""
}

Available WASP object types (acceptable values for the _type property) are described in the WASP object types section.

5.2. WASP object schema

WASP objects are described using JSON Schema. Schemas can be requested using the WASP schema dedicated URL endpoint. Schemas are meant to be used for validation, documentation and providing hints for user interfaces. In particular, schemas allow clients to compute valid values or range of values for properties in WASP objects.

Use of schemas by a client is optional. If a client uses schemas it should ignore validation keywords it doesn’t know how to process. This also allows some degree of forward compatibility between clients and future versions of JSON Schema and WASP. Standard validation keywords are defined in this document.

WASP also defines a set of extension validation keywords on top of those defined by the JSON Schema standard. Extension validation keywords not recognized by the client should be ignored.

Table 5. WASP extension validation keywords
Keyword Type Default value Description

wasp-label

string

null

If present, it suggests a default label string for use in user interfaces.

wasp-const

boolean

false

If true, the value of the property does not change during the lifetime of the session.

wasp-persist

boolean

false

If true, the value of the property is saved and persists across device restarts.

wasp-unit

string

null

If present, it indicates the units of measurement of the associated property’s value.

5.3. WASP object types

The WASP type of an object instance is identified by the _type property of each object.

WASP defines the following object types: ctrl:hw_status, ctrl:aes67_discovery, ctrl:aes67_transmit_flows, ctrl:ipv4_interface, ctrl:gpo_port, device:identify, device:sw_desc, block:io, device:ptp_port, ctrl:front_panel_led_diagnostics, ctrl:front_panel_led_settings, device:user_data, ctrl:meter, ctrl:aes67_transmitter, ctrl:avb_listener_stream, ctrl:gpi_port, ctrl:aes67_receiver, ctrl:aes67_receive_flows, ctrl:temperature_sensor, ctrl:mute, ctrl:mac_interface, ctrl:avb_talker_stream, ctrl:aes67_settings, ctrl:phantom, ctrl:trim_level, device:ptp, device:hw_desc and their set of properties. Each of these object types is documented in the following sections.

5.3.1. ctrl:aes67_discovery - AES67 Transmitter (Source) Discovery.

Table 6. Properties specific to object type ctrl:aes67_discovery
Property name Required Basic schema Description

aes67_transmitters

True

 
{
    "default": [],
    "items": {
        "properties": {
            "channels": {
                "description": "The number of channels in the transmitter flow.",
                "type": "number"
            },
            "ipv4": {
                "description": "The IPv4 transport address.",
                "format": "ipv4",
                "type": [
                    "string",
                    "null"
                ]
            },
            "session_name": {
                "description": "The session name.",
                "type": "string"
            }
        },
        "required": [
            "session_name",
            "ipv4",
            "channels"
        ],
        "type": "object"
    },
    "readOnly": true,
    "type": "array"
}

List of AES67 transmitter streams/flows.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:aes67_discovery
{
    "_id": 25,
    "_parent": null,
    "_schema": "_AES67DiscoveryControl",
    "_type": "ctrl:aes67_discovery",
    "aes67_transmitters": []
}

5.3.2. ctrl:aes67_receive_flows - AES67 Receive Flows.

Table 7. Properties specific to object type ctrl:aes67_receive_flows
Property name Required Basic schema Description

default_flow_channel_count

True

 
{
    "default": 8,
    "maximum": 8,
    "minimum": 1,
    "type": "number",
    "wasp-persist": true
}

The fixed channel count of AES67 receive flows derived automatically from subscribed_flow_transport_ipv4 changes to AES67 Receiver objects.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:aes67_receive_flows
{
    "_id": 25,
    "_parent": null,
    "_schema": "_AES67ReceiveFlowsControl",
    "_type": "ctrl:aes67_receive_flows",
    "default_flow_channel_count": 2
}

5.3.3. ctrl:aes67_receiver - AES67 Receiver Configuration.

Table 8. Properties specific to object type ctrl:aes67_receiver
Property name Required Basic schema Description

status

True

 
{
    "default": "not-connected",
    "enum": [
        "connected",
        "not-connected"
    ],
    "readOnly": true,
    "type": "string",
    "wasp-persist": false
}

AES67 flow status.

subscribed_flow_channel

True

 
{
    "default": null,
    "type": [
        "number",
        "null"
    ],
    "wasp-persist": false
}

Channel within the flow.

subscribed_flow_transport_ipv4

True

 
{
    "default": null,
    "format": "ipv4",
    "type": [
        "string",
        "null"
    ],
    "wasp-persist": false
}

IPv4 addresss of the subscrcibed AES67 flow.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:aes67_receiver
{
    "_id": 20,
    "_parent": 7,
    "_schema": "_AES67ReceiverControl",
    "_type": "ctrl:aes67_receiver",
    "status": "connected",
    "subscribed_flow_channel": 1,
    "subscribed_flow_transport_ipv4": "239.69.1.131"
}

5.3.4. ctrl:aes67_settings - AES67 Settings.

Table 9. Properties specific to object type ctrl:aes67_settings
Property name Required Basic schema Description

enabled

True

 
{
    "default": false,
    "readOnly": true,
    "type": "boolean"
}

Whether AES67 is enabled (true) or not (false).

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:aes67_settings
{
    "_id": 25,
    "_parent": null,
    "_schema": "_AES67SettingsControl",
    "_type": "ctrl:aes67_settings",
    "enabled": false
}

5.3.5. ctrl:aes67_transmit_flows - AES67 Transmit Flows.

Table 10. Properties specific to object type ctrl:aes67_transmit_flows
Property name Required Basic schema Description

aes67_transmit_flows

True

 
{
    "default": [],
    "items": {
        "properties": {
            "channels": {
                "description": "The number of channels in the transmitter flow.",
                "type": "number"
            },
            "ipv4": {
                "description": "The IPv4 transport address.",
                "format": "ipv4",
                "type": [
                    "string",
                    "null"
                ]
            },
            "session_name": {
                "description": "The session name.",
                "type": "string"
            }
        },
        "required": [
            "session_name",
            "ipv4",
            "channels"
        ],
        "type": "object"
    },
    "readOnly": true,
    "type": "array"
}

List of AES67 transmit flows.

default_flow_channel_count

True

 
{
    "default": 8,
    "maximum": 8,
    "minimum": 1,
    "type": "number",
    "wasp-persist": true
}

The fixed channel count of AES67 transmit flows derived automatically from status changes to AES67 Transmitter objects.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:aes67_transmit_flows
{
    "_id": 25,
    "_parent": null,
    "_schema": "_AES67TransmitFlowsControl",
    "_type": "ctrl:aes67_transmit_flows",
    "aes67_transmit_flows": []
}

5.3.6. ctrl:aes67_transmitter - AES67 Transmitter Configuration.

Table 11. Properties specific to object type ctrl:aes67_transmitter
Property name Required Basic schema Description

channel

True

 
{
    "default": null,
    "type": [
        "number",
        "null"
    ],
    "wasp-persist": false
}

Channel within the flow.

status

True

 
{
    "default": "stopped",
    "enum": [
        "started",
        "stopped"
    ],
    "type": "string",
    "wasp-persist": false
}

AES67 flow status.

transport_ipv4

True

 
{
    "default": null,
    "format": "ipv4",
    "type": [
        "string",
        "null"
    ],
    "wasp-persist": false
}

IPv4 address of the AES67 flow.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:aes67_transmitter
{
    "_id": 21,
    "_parent": 8,
    "_schema": "_AES67TransmitterControl",
    "_type": "ctrl:aes67_transmitter",
    "status": "started",
    "transport_ipv4": "239.69.1.132"
}

5.3.7. ctrl:avb_listener_stream - AVB Listener Stream.

Table 12. Properties specific to object type ctrl:avb_listener_stream
Property name Required Basic schema Description

connected

True

 
{
    "default": false,
    "readOnly": true,
    "type": "boolean"
}

Listener AVB IEEE1722.1 connection status.

media_locked

True

 
{
    "default": false,
    "readOnly": true,
    "type": "boolean"
}

Indicates whether the stream is correctly sychronized with the media clock.

missed_packet_count

True

 
{
    "default": 0,
    "readOnly": true,
    "type": "number"
}

The number of missed packets for this stream. This field is reset to zero every time the stream is restarted.

reconnect_count

True

 
{
    "default": 0,
    "readOnly": true,
    "type": "number"
}

The number of times this stream has been reconnected. This is a total count of the number of times the stream has been reconnected. A 1722.1 connection command counts as a connection as does the auto-connect that occurs after a talker is disconnected and then reconnected to the network.

streaming

True

 
{
    "default": false,
    "readOnly": true,
    "type": "boolean"
}

Listener is receiving packets.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:avb_listener_stream
{
    "_id": 26,
    "_parent": null,
    "_schema": "_AvbListenerStreamControl",
    "_type": "ctrl:avb_listener_stream",
    "connected": false,
    "media_locked": true,
    "missed_packet_count": 0,
    "reconnect_count": 1,
    "streaming": false
}

5.3.8. ctrl:avb_talker_stream - AVB Talker Stream.

Table 13. Properties specific to object type ctrl:avb_talker_stream
Property name Required Basic schema Description

active

True

 
{
    "default": false,
    "readOnly": true,
    "type": "boolean"
}

Set to true when the stream is sending AVTP packets.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:avb_talker_stream
{
    "_id": 26,
    "_parent": null,
    "_schema": "_AvbTalkerStreamControl",
    "_type": "ctrl:avb_talker_stream",
    "active": true
}

5.3.9. ctrl:front_panel_led_diagnostics - Front panel LED diagnostics.

WASP objects of this type are identified by having _type == "device:front_panel_led_diagnostics".

Table 14. Properties specific to object type ctrl:front_panel_led_diagnostics
Property name Required Basic schema Description

all_leds_on

True

 
{
    "default": false,
    "type": "boolean"
}

Front panel LED diagnostic state. This control supports turning all LEDs on for diagnostic purposes.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:front_panel_led_diagnostics
{
    "_id": 11,
    "_parent": null,
    "_schema": "_DeviceFrontPanelLEDDiagnostics",
    "_type": "ctrl:front_panel_led_diagnostics",
    "led_state": false
}

5.3.10. ctrl:front_panel_led_settings - Front panel LED settings.

WASP objects of this type are identified by having _type == "device:front_panel_led_settings".

Table 15. Properties specific to object type ctrl:front_panel_led_settings
Property name Required Basic schema Description

led_brightness

True

 
{
    "default": 100,
    "maximum": 100,
    "minimum": 0,
    "type": "number",
    "wasp-persist": true,
    "wasp-unit": "%"
}

Front panel LED brightness. Note the server side processing may round the granularity of the brightness number. For example settings 5 and 10 may result in the same front panel LED bightness. On an Iyo Dante unit, settings of 25, 50, 75 and 100 will result in observable differences in LED brightness.

phantom_power_indication_enable

False

 
{
    "default": false,
    "type": "boolean",
    "wasp-persist": true
}

Front panel phantom power indication. When this control is enabled, the front panel LEDs indicate input channel phantom power status.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:front_panel_led_settings
{
    "_id": 10,
    "_parent": null,
    "_schema": "_DeviceFrontPanelLEDSettings",
    "_type": "ctrl:front_panel_led_settings",
    "led_brightness": 100
}

5.3.11. ctrl:hw_status - Report device hardware status information.

Table 16. Properties specific to object type ctrl:hw_status
Property name Required Basic schema Description

error_log

True

 
{
    "default": [],
    "items": {
        "properties": {
            "code": {
                "description": "The numeric error code.",
                "type": "number"
            },
            "message": {
                "description": "The error message.",
                "type": "string"
            }
        },
        "required": [
            "code",
            "message"
        ],
        "type": "object"
    },
    "readOnly": true,
    "type": "array"
}

Log of recorded hardware errors.

status

True

 
{
    "default": "ok",
    "enum": [
        "ok",
        "error"
    ],
    "readOnly": true,
    "type": "string"
}

Indicate hardware is ok or has an error.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:hw_status
{
    "_id": 46,
    "_parent": null,
    "_schema": "_DeviceHardwareStatus",
    "_type": "ctrl:hw_status",
    "error_log": null,
    "status": "ok"
}

5.3.12. device:identify - Activate or deactivate the device’s identify function.

Table 17. Properties specific to object type device:identify
Property name Required Basic schema Description

identify

True

 
{
    "default": false,
    "type": "boolean"
}

Set the identify property to true to activate a device specific identify function. For instance the device may blink or light a specific LED on the front panel.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type device:identify
{
    "_id": 45,
    "_parent": null,
    "_schema": "_DeviceIdentify",
    "_type": "device:identify",
    "identify": false
}

5.3.13. device:ptp - PTP (IEEE1588) configuration information.

Table 18. Properties specific to object type device:ptp
Property name Required Basic schema Description

ports

True

 
{
    "default": [],
    "items": {
        "format": "object_id",
        "minimum": 0,
        "readOnly": true,
        "type": "number",
        "wasp-const": true
    },
    "readOnly": true,
    "type": "array"
}

List of the numeric Object IDs of PTP ports.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type device:ptp
{
    "_id": 25,
    "_parent": null,
    "_schema": "_DevicePtp",
    "_type": "device:ptp",
    "ports": [
        17,
        18
    ]
}

5.3.14. device:ptp_port - A PTP port

Table 19. Properties specific to object type device:ptp_port
Property name Required Basic schema Description

interface

True

 
{
    "format": "object_id",
    "minimum": 0,
    "readOnly": true,
    "type": "number",
    "wasp-const": true
}

Object ID of the MAC interface object associated with this PTP port.

role

True

 
{
    "default": "initializing",
    "enum": [
        "initializing",
        "faulty",
        "disabled",
        "listening",
        "pre-master",
        "master",
        "passive",
        "uncalibrated",
        "slave"
    ],
    "readOnly": true,
    "type": "string"
}

The PTP role on this port.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type device:ptp_port
{
    "_id": 25,
    "_parent": null,
    "_schema": "_DevicePtpPort",
    "_type": "device:ptp_port",
    "interface": 12,
    "role": "unknown"
}

5.3.15. device:user_data - User defined information about the device.

WASP objects of this type are identified by having _type == "device:user_data".

Table 20. Properties specific to object type device:user_data
Property name Required Basic schema Description

label

True

 
{
    "default": "",
    "type": "string",
    "wasp-persist": true
}

User defined label string for the device.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type device:user_data
{
    "_id": 4,
    "_parent": null,
    "_schema": "_DeviceUserData",
    "_type": "device:user_data",
    "label": ""
}

5.3.16. ctrl:gpi_port - General Purpose Input control.

WASP objects of this type are identified by having _type == "ctrl:gpi_port".

Table 21. Properties specific to object type ctrl:gpi_port
Property name Required Basic schema Description

bits_state

True

 
{
    "default": "00000",
    "maxLength": 5,
    "minLength": 5,
    "pattern": "^[01]*$",
    "readOnly": true,
    "type": "string"
}

Current state of GPI bits. The format of the string is a sequence of the ASCII characters 1 and 0 representing the set and cleared respectively of the corresponding GPI pin. Bits in the string are indexed from left to right starting at 0 and the index of the digit in the string corresponds to the index of the GPI. The number of available bits is equal to the length of the string.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:gpi_port
{
    "_id": 9,
    "_parent": null,
    "_schema": "_GPIBitsControl",
    "_type": "ctrl:gpi_port",
    "bits_state": "00110"
}

5.3.17. ctrl:gpo_port - General Purpose Output control.

WASP objects of this type are identified by having _type == "ctrl:gpo_port".

Table 22. Properties specific to object type ctrl:gpo_port
Property name Required Basic schema Description

bits_state

True

 
{
    "default": "00000",
    "maxLength": 5,
    "minLength": 5,
    "pattern": "^[01]*$",
    "type": "string",
    "wasp-persist": true
}

Current state of GPO bits. The format of the string is a sequence of the ASCII characters 1 and 0 representing the set and cleared respectively of the corresponding GPO pin. Bits in the string are indexed from left to right starting at 0 and the index of the digit in the string corresponds to the index of the GPO. The number of available bits is equal to the length of the string.

clear_bits

False

 
{
    "maxLength": 5,
    "minLength": 5,
    "pattern": "^[01]*$",
    "type": "string",
    "writeOnly": true
}

Updating this property with a value v updates bits_state as follows: bits_state := bits_state bitwise-and (bitwise-not v).

gpi_port_to_follow

False

 
{
    "default": null,
    "type": [
        "string",
        "null"
    ],
    "wasp-persist": true
}

The description of another GPI port for this GPO port to follow. Any state change on the remote GPI shall be mirrored on this local GPO. Currently supported GPI protocols: LiveWire Routing Protocol (lwrp-gpi) Valid formats for this field: - lwrp-gpi://[IPv4 address string]/[GPI port index]

set_bits

False

 
{
    "maxLength": 5,
    "minLength": 5,
    "pattern": "^[01]*$",
    "type": "string",
    "writeOnly": true
}

Updating this property with a value v updates bits_state as follows: bits_state := bits_state bitwise-or v.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:gpo_port
{
    "_id": 9,
    "_parent": null,
    "_schema": "_GPIOBitsControl",
    "_type": "ctrl:gpo_port",
    "bits_state": "00110"
}

5.3.18. device:hw_desc - Descriptor for hardware information.

A device has one or more of these objects to describe its hardware. At least one hardware descriptor (with _parent == null) must be present to describe the device itself. WASP objects of this type are identified by having _type == "device:hw_desc".

Table 23. Properties specific to object type device:hw_desc
Property name Required Basic schema Description

manufacturer

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The manufacturer of the hardware.

name

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The name of the hardware.

part_number

False

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The part number of the hardware.

revision

False

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The hardware revision of the hardware.

serial_number

False

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The serial number of the hardware.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type device:hw_desc
{
    "_id": 6,
    "_parent": null,
    "_schema": "_HardwareDescriptor",
    "_type": "device:hw_desc",
    "manufacturer": "AudioScience Inc",
    "name": "Iyo Dante 32.32M",
    "part_number": "ASI2703",
    "revision": "D0",
    "serial_number": "75643"
}

5.3.19. block:io - I/O block.

This block contains all objects associated with a physical input or output. The member_ids propoerty lists the IDs of this block’s members and type, dir and idx identify the associated physical input or output. WASP objects of this type are identified by having _type == "block:io".

Table 24. Properties specific to object type block:io
Property name Required Basic schema Description

io_dir

True

 
{
    "enum": [
        "in",
        "out"
    ],
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The i/o block signal direction.

io_idx

True

 
{
    "minimum": 0,
    "readOnly": true,
    "type": "number",
    "wasp-const": true
}

Index of the signal input or output this block and its members are related to. The numbering of each I/O type are separate from each other, for instance: input type analog index 1 and input type aes3 index 1 represent different physical inputs.

io_type

True

 
{
    "enum": [
        "analog",
        "aes3",
        "aes67",
        "gpio"
    ],
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The i/o block type.

label

False

 
{
    "type": "string",
    "wasp-persist": true
}

The i/o block user read/write label string.

members

True

 
{
    "items": {
        "format": "object_id",
        "minimum": 0,
        "readOnly": true,
        "type": "number",
        "wasp-const": true
    },
    "readOnly": true,
    "type": "array"
}

List of the numeric Object IDs of this block’s members.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type block:io
{
    "_id": 7,
    "_parent": null,
    "_schema": "_IOBlock",
    "_type": "block:io",
    "io_dir": "in",
    "io_idx": 2,
    "io_type": "analog",
    "label": "Line/Mic 2"
}

5.3.20. ctrl:ipv4_interface - IPv4 address control.

Table 25. Properties specific to object type ctrl:ipv4_interface
Property name Required Basic schema Description

address

True

 
{
    "default": null,
    "format": "ipv4",
    "type": [
        "string",
        "null"
    ]
}

The IPv4 address.

address_assignment_mode

True

 
{
    "default": "dhcp",
    "enum": [
        "static",
        "dhcp"
    ],
    "type": "string"
}

Configure the method used to assign an IP address.

dnsserver

True

 
{
    "default": null,
    "format": "ipv4",
    "type": [
        "string",
        "null"
    ]
}

The IPv4 address of the domain name server.

gateway

True

 
{
    "default": null,
    "format": "ipv4",
    "type": [
        "string",
        "null"
    ]
}

The IPv4 address of the gateway

mac_interface

True

 
{
    "format": "object_id",
    "minimum": 0,
    "readOnly": true,
    "type": "number",
    "wasp-const": true
}

Object ID of the MAC interface object this IP address belongs to.

netmask

True

 
{
    "default": null,
    "format": "ipv4",
    "type": [
        "string",
        "null"
    ]
}

The network mask to apply.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:ipv4_interface
{
    "_id": 12,
    "_parent": null,
    "_schema": "_IPV4AddressControl",
    "_type": "ctrl:ipv4_interface",
    "address": "192.168.1.23",
    "address_assignment_mode": "dhcp",
    "dns_server": null,
    "gateway": null,
    "mac_interface": 9,
    "netmask": "255.255.255.0"
}

5.3.21. ctrl:mac_interface - MAC interface control.

Table 26. Properties specific to object type ctrl:mac_interface
Property name Required Basic schema Description

label

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The friendly name for the MAC interface.

link_speed

True

 
{
    "default": 0,
    "readOnly": true,
    "type": "number"
}

The link speed in megabits/second.

link_status

True

 
{
    "default": "inactive",
    "enum": [
        "active",
        "inactive"
    ],
    "readOnly": true,
    "type": "string"
}

The state of the link.

mac_address

True

 
{
    "readOnly": true,
    "type": "string"
}

The MAC address.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:mac_interface
{
    "_id": 12,
    "_parent": null,
    "_schema": "_MACInterfaceControl",
    "_type": "ctrl:mac_interface",
    "label": "primary",
    "link_ speed": 1000,
    "link_status": "active",
    "mac_address": "00:1D;:C1:01:62:84"
}

5.3.22. ctrl:meter - Meter control.

WASP objects of this type are identified by having _type == "ctrl:meter".

Table 27. Properties specific to object type ctrl:meter
Property name Required Basic schema Description

peak

True

 
{
    "readOnly": true,
    "type": "number",
    "wasp-unit": "dB"
}

Meter reading.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:meter
{
    "_id": 9,
    "_parent": 7,
    "_schema": "_MeterControl",
    "_type": "ctrl:meter",
    "peak": -7
}

5.3.23. ctrl:mute - Mute control.

Mute is controlled by the active property. WASP objects of this type are identified by having _type == "ctrl:mute".

Table 28. Properties specific to object type ctrl:mute
Property name Required Basic schema Description

active

True

 
{
    "default": false,
    "type": "boolean",
    "wasp-persist": true
}

This property allows the mute to be turned off and on.

button_enabled

False

 
{
    "default": true,
    "type": "boolean",
    "wasp-persist": true
}

Enable control of mute function via the associated button.

button_mode

False

 
{
    "default": "latching",
    "enum": [
        "latching",
        "momentary"
    ],
    "type": "string",
    "wasp-persist": true
}

Mute control button mode.

button_state

False

 
{
    "default": "released",
    "enum": [
        "pressed",
        "released"
    ],
    "readOnly": true,
    "type": "string"
}

Mute button state.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:mute
{
    "_id": 8,
    "_parent": 7,
    "_schema": "_MuteControl",
    "_type": "ctrl:mute",
    "active": true
}

5.3.24. ctrl:phantom - Phantom power control.

Phantom power is controlled by the active property. WASP objects of this type are identified by having _type == "ctrl:phantom".

Table 29. Properties specific to object type ctrl:phantom
Property name Required Basic schema Description

active

True

 
{
    "default": false,
    "type": "boolean",
    "wasp-persist": true
}

This property allows the phantom power to be turned off and on.

voltage

True

 
{
    "readOnly": true,
    "type": "number",
    "wasp-const": true,
    "wasp-unit": "V"
}

Phantom power voltage.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:phantom
{
    "_id": 8,
    "_parent": 7,
    "_schema": "_PhantomPowerControl",
    "_type": "ctrl:phantom",
    "active": true,
    "voltage": 48
}

5.3.25. device:sw_desc - Descriptor for software information.

A device has one or more of these objects to describe software running on it. At least one software descriptor with (_parent == null) must be present to describe the device’s firmware version. WASP objects of this type are identified by having _type == "device:sw_desc".

Table 30. Properties specific to object type device:sw_desc
Property name Required Basic schema Description

name

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The name of the software module.

vendor

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The entity that wrote or produced the software module.

version

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

The version of the software module.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type device:sw_desc
{
    "_id": 5,
    "_parent": null,
    "_schema": "_SoftwareDescriptor",
    "_type": "device:sw_desc",
    "name": "Iyo Dante firmware",
    "vendor": "AudioScience Inc",
    "version": "1.0.2"
}

5.3.26. ctrl:temperature_sensor - Temperature sensor reading

Table 31. Properties specific to object type ctrl:temperature_sensor
Property name Required Basic schema Description

location

True

 
{
    "readOnly": true,
    "type": "string",
    "wasp-const": true
}

Where the sensor is located.

temperature

True

 
{
    "readOnly": true,
    "type": "number",
    "wasp-unit": "C"
}

Temperature reading in centigrade.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:temperature_sensor
{
    "_id": 19,
    "_parent": null,
    "_schema": "_TemperatureSensorControl",
    "_type": "ctrl:temperature_sensor",
    "temperature": 45
}

5.3.27. ctrl:trim_level - Trim level control.

Level is controlled by the level property. WASP objects of this type are identified by having _type == "ctrl:trim_level".

Table 32. Properties specific to object type ctrl:trim_level
Property name Required Basic schema Description

level

True

 
{
    "type": "number",
    "wasp-persist": true,
    "wasp-unit": "dBu"
}

Adjust the trim level.

Common properties of this object type are described in Common object properties.

Example 1 for WASP object type ctrl:trim_level
{
    "_id": 9,
    "_parent": 7,
    "_schema": "_TrimControl",
    "_type": "ctrl:trim_level",
    "level": 14
}