= WASP (Web AudioScience Protocol) 3.1.0-dev8 :source-highlighter: highlightjs AudioScience Inc 2018 (C) All Rights Reserved - support@audioscience.com :toc: left :toclevels: 3 :numbered: :sectnumlevels: 5 == 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). == 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 <> object has a `level` property controlling the full scale voltage of the analog input or output associated with the object. == Protocol description WASP is a set of conventions and restrictions on HTTP 1.1 request and responses specified in the following sections. === HTTP URLs prefix All URL destinations for WASP requests start with the `/wasp/r2` prefix. === HTTP URLs endpoints Endpoint paths are concatenated to the URL prefix. The following endpoints are available: [%header,cols="3*"] |=== a|Endpoint path a|Summary a|Supported HTTP method a|/device/auth a|Authenticate a client. a| a|/device/info a|Retrieve information for this device. a|`GET`, `HEAD` a|/device/ping a|Check if the device is reachable and responsive. a|`GET` a|/objects a|Device objects array This endpoint allows bulk enumeration of all WASP objects present on the device. a|`GET`, `HEAD`, `PATCH` a|/objects/{id} a|Retrieve or update object by {id} a|`GET`, `PATCH` a|/objects/{id}/{prop} a|Retrieve or update property {prop} of object {id} a|`GET`, `PATCH` a|/schemas a|Schema array This endpoint allows bulk enumeration of all WASP schemas present on the device. a|`GET` a|/schemas/{id} a|Retrieve schema by {id} a|`GET` |=== - - - ==== `/device/auth` Authenticate a client. ===== `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 ==== [discrete] ====== Request headers [discrete] ====== `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. ==== ====== 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"`. [discrete] ====== Response body with `Content-Type: application/json` .Response body example [source, json] ---- { "id": "dh37fgj492je" } ---- - - - ==== `/device/info` Retrieve information for this device. ===== `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 <> object, a <> object and a <> 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 ==== ====== Response status `200` - Request successful. The response body is an instance of a <> object. [discrete] ====== Response body with `Content-Type: application/json` .Response body example [source, json] ---- { "_id": 4, "_parent": null, "_schema": "_DeviceUserData", "_type": "device:user_data", "label": "" } ---- [discrete] ====== Response headers [discrete] ====== `Allow` - List HTTP methods allowed on this endpoint. ==== Example header: `Allow: GET, HEAD` ==== [discrete] ====== `X-Wasp-Api-Version` - WASP API version ==== Example header: `X-Wasp-Api-Version: 2.0.7` ==== [discrete] ====== `X-Wasp-Firmware-Version` - Device firmware version. ==== Example header: `X-Wasp-Firmware-Version: 1.0.2` ==== [discrete] ====== `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` ==== [discrete] ====== `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` ==== ===== `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 ==== ====== Response status `200` - Request successful. ==== The body of the response is empty ==== [discrete] ====== Response headers [discrete] ====== `Allow` - List HTTP methods allowed on this endpoint. ==== Example header: `Allow: GET, HEAD` ==== [discrete] ====== `X-Wasp-Api-Version` - WASP API version ==== Example header: `X-Wasp-Api-Version: 2.0.7` ==== [discrete] ====== `X-Wasp-Firmware-Version` - Device firmware version. ==== Example header: `X-Wasp-Firmware-Version: 1.0.2` ==== [discrete] ====== `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` ==== [discrete] ====== `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` ==== - - - ==== `/device/ping` Check if the device is reachable and responsive. ===== `GET` - Check if the device is reachable and responsive. ==== The body of the request is empty ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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` ==== - - - ==== `/objects` Device objects array This endpoint allows bulk enumeration of all WASP objects present on the device. ===== `GET` - Enumerate objects ==== The body of the request is empty ==== [discrete] ====== Request headers [discrete] ====== `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. ==== [discrete] ====== `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. ==== ====== Response status `200` - Get all objects. The response body is an array containing the current state of all WASP objects present on the device. [discrete] ====== Response body with `Content-Type: application/json` .Response body example [source, json] ---- [ { "_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 } ] ---- [discrete] ====== Response headers [discrete] ====== `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`. ==== [discrete] ====== `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` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== ===== `HEAD` - Enumerate objects ==== The body of the request is empty ==== [discrete] ====== Request headers [discrete] ====== `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. ==== [discrete] ====== `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. ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== [discrete] ====== `Allow` - List HTTP methods allowed on this endpoint. ==== Example header: `Allow: GET, HEAD` ==== [discrete] ====== `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. ==== [discrete] ====== `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` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== ===== `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 <> 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. [discrete] ====== Request body with `Content-Type: application/json` .Request body example [source, json] ---- [ { "_id": 34, "level": 3 }, { "_id": 38, "level": 7 }, { "_id": 36, "level": 0 } ] ---- [discrete] ====== Request headers [discrete] ====== `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. ==== [discrete] ====== `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. ==== ====== Response status `200` - Update completed successfully. ==== The body of the response is empty ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `Link` - Link header used to associate URLs with a specific relationship with a resource. ==== Example header: `Link: ; rel="self"` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== - - - ==== `/objects/{id}` Retrieve or update object by {id} ===== `GET` - Get an object ==== The body of the request is empty ==== [discrete] ====== Request headers [discrete] ====== `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. ==== [discrete] ====== `Content-Length` - Clients must include this header within their request when sending a body. ==== Size of the request's (or response) body in bytes. ==== ====== 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. [discrete] ====== Response body with `Content-Type: application/json` .Response body example [source, json] ---- { "_id": 8, "_parent": 7, "_schema": "_PhantomPowerControl", "_type": "ctrl:phantom", "active": true, "voltage": 48 } ---- ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== ===== `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 <> object only needs to contain the mapping `{"level": 3}` to change the level to `3`. [discrete] ====== Request body with `Content-Type: application/json` .Request body example [source, json] ---- { "level": 3 } ---- [discrete] ====== Request headers [discrete] ====== `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. ==== [discrete] ====== `Content-Length` - Clients must include this header within their request when sending a body. ==== Size of the request's (or response) body in bytes. ==== ====== Response status `200` - Update completed successfully. ==== The body of the response is empty ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `Link` - Link header used to associate URLs with a specific relationship with a resource. ==== Example header: `Link: ; rel="self"` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== - - - ==== `/objects/{id}/{prop}` Retrieve or update property {prop} of object {id} ===== `GET` - Get the value of property {prop} of object {id}. ==== The body of the request is empty ==== [discrete] ====== Request headers [discrete] ====== `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. ==== [discrete] ====== `Content-Length` - Clients must include this header within their request when sending a body. ==== Size of the request's (or response) body in bytes. ==== ====== 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 <> 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}`. [discrete] ====== Response body with `Content-Type: application/json` ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== ===== `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 <> 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}`. [discrete] ====== Request body with `Content-Type: application/json` [discrete] ====== Request headers [discrete] ====== `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. ==== [discrete] ====== `Content-Length` - Clients must include this header within their request when sending a body. ==== Size of the request's (or response) body in bytes. ==== ====== Response status `200` - Update completed successfully. ==== The body of the response is empty ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `Link` - Link header used to associate URLs with a specific relationship with a resource. ==== Example header: `Link: ; rel="self"` ==== ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== - - - ==== `/schemas` Schema array This endpoint allows bulk enumeration of all WASP schemas present on the device. ===== `GET` - Enumerate schemas ==== The body of the request is empty ==== [discrete] ====== Request headers [discrete] ====== `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. ==== ====== Response status `200` - Get a list of schemas. This endpoint allows bulk enumeration of all WASP schemas present on the device. [discrete] ====== Response body with `Content-Type: application/json` ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== - - - ==== `/schemas/{id}` Retrieve schema by {id} ===== `GET` - Get a schema by {id} ==== The body of the request is empty ==== [discrete] ====== Request headers [discrete] ====== `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. ==== ====== Response status `200` - Get a schema by {id}. [discrete] ====== Response body with `Content-Type: application/json` ====== 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 ==== [discrete] ====== Response headers [discrete] ====== `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`. ==== === HTTP methods WASP supports `GET` and `PATCH` HTTP methods respectively mapped to Retrieve and Update CRUD operations on WASP objects and properties. === 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. === HTTP headers A WASP server supports a number of standard and extension HTTP headers. Unsupported headers are ignored. ==== 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. ==== 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. ==== Content-Length Clients must include this header within their request when sending a body. Size of the request's (or response) body in bytes. ==== 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` ==== Content-Type Clients must include this header within their request when sending a body. WASP currently recognizes only `Content-Type: application/json`. ==== Link Link header used to associate URLs with a specific relationship with a resource. Example header: `Link: ; rel="self"` ==== 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. ==== 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`. ==== 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. ==== 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` ==== 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` === 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. ==== 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. ==== 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. ==== 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. === Client side state [complete this section] == Object update stream === 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 ---- === Event stream transport format The event stream is a sequence of JSON encoded _chunks_ as specified by https://tools.ietf.org/html/rfc7230#section-4.1[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. === 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:checkpoint]] ==== `update:checkpoint` - Current state of all objects in a single message. .Properties specific to object type `update:checkpoint` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|_type a|True a| [source, json] ---- { "enum": [ "update:checkpoint" ], "type": "string" } ---- a| a|body a|True a| [source, json] ---- { "items": { "type": "object" }, "type": "array" } ---- a|Array containing all WASP objects. a|path a|True a| [source, json] ---- { "enum": [ "/objects" ], "type": "string" } ---- a|URL path to object being updated. Always `/objects`. |=== .Example 1 for WASP object type `update:checkpoint` [source, json] ---- { "_type": "update:checkpoint", "body": [ { "_id": 3, "_type": "ctrl:level", "level": 14 }, { "_id": 4, "_type": "ctrl:level", "level": 24 } ], "path": "/objects" } ---- [[update:group_prefix, update:group_prefix]] ==== `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 ---- .Properties specific to object type `update:group_prefix` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|_type a|True a| [source, json] ---- { "enum": [ "update:group_prefix" ], "type": "string" } ---- a| a|body a|True a| [source, json] ---- { "items": { "type": "object" }, "type": "object" } ---- a|Object mapping each ID of an object being updated with the new value of its `{prop}` property. a|prefix a|True a| [source, json] ---- { "type": "string" } ---- a|URL path prefix of all objects updates included in this event. a|prop a|True a| [source, json] ---- { "type": "string" } ---- a|Property name updated by all objects updates included in this event. |=== .Example 1 for WASP object type `update:group_prefix` [source, json] ---- { "_type": "update:group_prefix", "body": { "5": -37, "6": -40, "7": -3 }, "prefix": "/objects/", "prop": "peak" } ---- [[update:obj, update:obj]] ==== `update:obj` - Object update event. .Properties specific to object type `update:obj` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|_type a|True a| [source, json] ---- { "enum": [ "update:obj" ], "type": "string" } ---- a| a|body a|True a| [source, json] ---- { "type": "object" } ---- a|Object mapping each updated property with its new value. a|path a|True a| [source, json] ---- { "type": "string" } ---- a|URL path to object being updated. |=== .Example 1 for WASP object type `update:obj` [source, json] ---- { "_type": "update:obj", "body": { "property1": "new_value1", "property2": "new_value2", "propertyN": "new_valueN" }, "path": "/objects/34" } ---- === Event stream behaviour The first event sent by the server upon successful client connection is of type <>. 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. == 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. === Common object properties All objects published by WASP share a common set of properties shown in the following table. .Properties common to all WASP objects [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|_id a|True a| [source, json] ---- { "format": "object_id", "minimum": 0, "readOnly": true, "type": "number", "wasp-const": true } ---- a|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. a|_parent a|True a| [source, json] ---- { "format": "object_id", "minimum": 0, "readOnly": true, "type": [ "number", "null" ], "wasp-const": true } ---- a|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. a|_schema a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|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. a|_type a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|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: [source, json] ---- { "_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. === WASP object schema WASP objects are described using http://json-schema.org[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 https://json-schema.org/latest/json-schema-validation.html[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. .WASP extension validation keywords [%header,cols="4*"] |=== a|Keyword a|Type a|Default value a|Description a|`wasp-label` a|string a|`null` a|If present, it suggests a default label string for use in user interfaces. a|`wasp-const` a|boolean a|`false` a|If true, the value of the property does not change during the lifetime of the session. a|`wasp-persist` a|boolean a|`false` a|If true, the value of the property is saved and persists across device restarts. a|`wasp-unit` a|string a|`null` a|If present, it indicates the units of measurement of the associated property's value. |=== === 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: <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <>, <> and their set of properties. Each of these object types is documented in the following sections. [[ctrl:aes67_discovery, ctrl:aes67_discovery]] ==== `ctrl:aes67_discovery` - AES67 Transmitter (Source) Discovery. .Properties specific to object type `ctrl:aes67_discovery` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|aes67_transmitters a|True a| [source, json] ---- { "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" } ---- a|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` [source, json] ---- { "_id": 25, "_parent": null, "_schema": "_AES67DiscoveryControl", "_type": "ctrl:aes67_discovery", "aes67_transmitters": [] } ---- [[ctrl:aes67_receive_flows, ctrl:aes67_receive_flows]] ==== `ctrl:aes67_receive_flows` - AES67 Receive Flows. .Properties specific to object type `ctrl:aes67_receive_flows` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|default_flow_channel_count a|True a| [source, json] ---- { "default": 8, "maximum": 8, "minimum": 1, "type": "number", "wasp-persist": true } ---- a|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` [source, json] ---- { "_id": 25, "_parent": null, "_schema": "_AES67ReceiveFlowsControl", "_type": "ctrl:aes67_receive_flows", "default_flow_channel_count": 2 } ---- [[ctrl:aes67_receiver, ctrl:aes67_receiver]] ==== `ctrl:aes67_receiver` - AES67 Receiver Configuration. .Properties specific to object type `ctrl:aes67_receiver` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|status a|True a| [source, json] ---- { "default": "not-connected", "enum": [ "connected", "not-connected" ], "readOnly": true, "type": "string", "wasp-persist": false } ---- a|AES67 flow status. a|subscribed_flow_channel a|True a| [source, json] ---- { "default": null, "type": [ "number", "null" ], "wasp-persist": false } ---- a|Channel within the flow. a|subscribed_flow_transport_ipv4 a|True a| [source, json] ---- { "default": null, "format": "ipv4", "type": [ "string", "null" ], "wasp-persist": false } ---- a|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` [source, json] ---- { "_id": 20, "_parent": 7, "_schema": "_AES67ReceiverControl", "_type": "ctrl:aes67_receiver", "status": "connected", "subscribed_flow_channel": 1, "subscribed_flow_transport_ipv4": "239.69.1.131" } ---- [[ctrl:aes67_settings, ctrl:aes67_settings]] ==== `ctrl:aes67_settings` - AES67 Settings. .Properties specific to object type `ctrl:aes67_settings` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|enabled a|True a| [source, json] ---- { "default": false, "readOnly": true, "type": "boolean" } ---- a|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` [source, json] ---- { "_id": 25, "_parent": null, "_schema": "_AES67SettingsControl", "_type": "ctrl:aes67_settings", "enabled": false } ---- [[ctrl:aes67_transmit_flows, ctrl:aes67_transmit_flows]] ==== `ctrl:aes67_transmit_flows` - AES67 Transmit Flows. .Properties specific to object type `ctrl:aes67_transmit_flows` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|aes67_transmit_flows a|True a| [source, json] ---- { "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" } ---- a|List of AES67 transmit flows. a|default_flow_channel_count a|True a| [source, json] ---- { "default": 8, "maximum": 8, "minimum": 1, "type": "number", "wasp-persist": true } ---- a|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` [source, json] ---- { "_id": 25, "_parent": null, "_schema": "_AES67TransmitFlowsControl", "_type": "ctrl:aes67_transmit_flows", "aes67_transmit_flows": [] } ---- [[ctrl:aes67_transmitter, ctrl:aes67_transmitter]] ==== `ctrl:aes67_transmitter` - AES67 Transmitter Configuration. .Properties specific to object type `ctrl:aes67_transmitter` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|channel a|True a| [source, json] ---- { "default": null, "type": [ "number", "null" ], "wasp-persist": false } ---- a|Channel within the flow. a|status a|True a| [source, json] ---- { "default": "stopped", "enum": [ "started", "stopped" ], "type": "string", "wasp-persist": false } ---- a|AES67 flow status. a|transport_ipv4 a|True a| [source, json] ---- { "default": null, "format": "ipv4", "type": [ "string", "null" ], "wasp-persist": false } ---- a|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` [source, json] ---- { "_id": 21, "_parent": 8, "_schema": "_AES67TransmitterControl", "_type": "ctrl:aes67_transmitter", "status": "started", "transport_ipv4": "239.69.1.132" } ---- [[ctrl:avb_listener_stream, ctrl:avb_listener_stream]] ==== `ctrl:avb_listener_stream` - AVB Listener Stream. .Properties specific to object type `ctrl:avb_listener_stream` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|connected a|True a| [source, json] ---- { "default": false, "readOnly": true, "type": "boolean" } ---- a|Listener AVB IEEE1722.1 connection status. a|media_locked a|True a| [source, json] ---- { "default": false, "readOnly": true, "type": "boolean" } ---- a|Indicates whether the stream is correctly sychronized with the media clock. a|missed_packet_count a|True a| [source, json] ---- { "default": 0, "readOnly": true, "type": "number" } ---- a|The number of missed packets for this stream. This field is reset to zero every time the stream is restarted. a|reconnect_count a|True a| [source, json] ---- { "default": 0, "readOnly": true, "type": "number" } ---- a|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. a|streaming a|True a| [source, json] ---- { "default": false, "readOnly": true, "type": "boolean" } ---- a|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` [source, json] ---- { "_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 } ---- [[ctrl:avb_talker_stream, ctrl:avb_talker_stream]] ==== `ctrl:avb_talker_stream` - AVB Talker Stream. .Properties specific to object type `ctrl:avb_talker_stream` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|active a|True a| [source, json] ---- { "default": false, "readOnly": true, "type": "boolean" } ---- a|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` [source, json] ---- { "_id": 26, "_parent": null, "_schema": "_AvbTalkerStreamControl", "_type": "ctrl:avb_talker_stream", "active": true } ---- [[ctrl:front_panel_led_diagnostics, ctrl:front_panel_led_diagnostics]] ==== `ctrl:front_panel_led_diagnostics` - Front panel LED diagnostics. WASP objects of this type are identified by having `_type == "device:front_panel_led_diagnostics"`. .Properties specific to object type `ctrl:front_panel_led_diagnostics` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|all_leds_on a|True a| [source, json] ---- { "default": false, "type": "boolean" } ---- a|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` [source, json] ---- { "_id": 11, "_parent": null, "_schema": "_DeviceFrontPanelLEDDiagnostics", "_type": "ctrl:front_panel_led_diagnostics", "led_state": false } ---- [[ctrl:front_panel_led_settings, ctrl:front_panel_led_settings]] ==== `ctrl:front_panel_led_settings` - Front panel LED settings. WASP objects of this type are identified by having `_type == "device:front_panel_led_settings"`. .Properties specific to object type `ctrl:front_panel_led_settings` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|led_brightness a|True a| [source, json] ---- { "default": 100, "maximum": 100, "minimum": 0, "type": "number", "wasp-persist": true, "wasp-unit": "%" } ---- a|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. |=== Common properties of this object type are described in <<_common_object_properties>>. .Example 1 for WASP object type `ctrl:front_panel_led_settings` [source, json] ---- { "_id": 10, "_parent": null, "_schema": "_DeviceFrontPanelLEDSettings", "_type": "ctrl:front_panel_led_settings", "led_brightness": 100 } ---- [[ctrl:hw_status, ctrl:hw_status]] ==== `ctrl:hw_status` - Report device hardware status information. .Properties specific to object type `ctrl:hw_status` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|error_log a|True a| [source, json] ---- { "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" } ---- a|Log of recorded hardware errors. a|status a|True a| [source, json] ---- { "default": "ok", "enum": [ "ok", "error" ], "readOnly": true, "type": "string" } ---- a|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` [source, json] ---- { "_id": 46, "_parent": null, "_schema": "_DeviceHardwareStatus", "_type": "ctrl:hw_status", "error_log": null, "status": "ok" } ---- [[device:identify, device:identify]] ==== `device:identify` - Activate or deactivate the device's identify function. .Properties specific to object type `device:identify` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|identify a|True a| [source, json] ---- { "default": false, "type": "boolean" } ---- a|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` [source, json] ---- { "_id": 45, "_parent": null, "_schema": "_DeviceIdentify", "_type": "device:identify", "identify": false } ---- [[device:ptp, device:ptp]] ==== `device:ptp` - PTP (IEEE1588) configuration information. .Properties specific to object type `device:ptp` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|ports a|True a| [source, json] ---- { "default": [], "items": { "format": "object_id", "minimum": 0, "readOnly": true, "type": "number", "wasp-const": true }, "readOnly": true, "type": "array" } ---- a|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` [source, json] ---- { "_id": 25, "_parent": null, "_schema": "_DevicePtp", "_type": "device:ptp", "ports": [ 17, 18 ] } ---- [[device:ptp_port, device:ptp_port]] ==== `device:ptp_port` - A PTP port .Properties specific to object type `device:ptp_port` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|interface a|True a| [source, json] ---- { "format": "object_id", "minimum": 0, "readOnly": true, "type": "number", "wasp-const": true } ---- a|Object ID of the MAC interface object associated with this PTP port. a|role a|True a| [source, json] ---- { "default": "initializing", "enum": [ "initializing", "faulty", "disabled", "listening", "pre-master", "master", "passive", "uncalibrated", "slave" ], "readOnly": true, "type": "string" } ---- a|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` [source, json] ---- { "_id": 25, "_parent": null, "_schema": "_DevicePtpPort", "_type": "device:ptp_port", "interface": 12, "role": "unknown" } ---- [[device:user_data, device:user_data]] ==== `device:user_data` - User defined information about the device. WASP objects of this type are identified by having `_type == "device:user_data"`. .Properties specific to object type `device:user_data` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|label a|True a| [source, json] ---- { "default": "", "type": "string", "wasp-persist": true } ---- a|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` [source, json] ---- { "_id": 4, "_parent": null, "_schema": "_DeviceUserData", "_type": "device:user_data", "label": "" } ---- [[ctrl:gpi_port, ctrl:gpi_port]] ==== `ctrl:gpi_port` - General Purpose Input control. WASP objects of this type are identified by having `_type == "ctrl:gpi_port"`. .Properties specific to object type `ctrl:gpi_port` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|bits_state a|True a| [source, json] ---- { "default": "00000", "maxLength": 5, "minLength": 5, "pattern": "^[01]*$", "readOnly": true, "type": "string" } ---- a|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` [source, json] ---- { "_id": 9, "_parent": null, "_schema": "_GPIBitsControl", "_type": "ctrl:gpi_port", "bits_state": "00110" } ---- [[ctrl:gpo_port, ctrl:gpo_port]] ==== `ctrl:gpo_port` - General Purpose Output control. WASP objects of this type are identified by having `_type == "ctrl:gpo_port"`. .Properties specific to object type `ctrl:gpo_port` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|bits_state a|True a| [source, json] ---- { "default": "00000", "maxLength": 5, "minLength": 5, "pattern": "^[01]*$", "type": "string", "wasp-persist": true } ---- a|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. a|clear_bits a|False a| [source, json] ---- { "maxLength": 5, "minLength": 5, "pattern": "^[01]*$", "type": "string", "writeOnly": true } ---- a|Updating this property with a value `v` updates bits_state as follows: `bits_state := bits_state bitwise-and (bitwise-not v)`. a|gpi_port_to_follow a|False a| [source, json] ---- { "default": null, "type": [ "string", "null" ], "wasp-persist": true } ---- a|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] a|set_bits a|False a| [source, json] ---- { "maxLength": 5, "minLength": 5, "pattern": "^[01]*$", "type": "string", "writeOnly": true } ---- a|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` [source, json] ---- { "_id": 9, "_parent": null, "_schema": "_GPIOBitsControl", "_type": "ctrl:gpo_port", "bits_state": "00110" } ---- [[device:hw_desc, device:hw_desc]] ==== `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"`. .Properties specific to object type `device:hw_desc` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|manufacturer a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|The manufacturer of the hardware. a|name a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|The name of the hardware. a|part_number a|False a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|The part number of the hardware. a|revision a|False a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|The hardware revision of the hardware. a|serial_number a|False a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|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` [source, json] ---- { "_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" } ---- [[block:io, block:io]] ==== `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"`. .Properties specific to object type `block:io` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|io_dir a|True a| [source, json] ---- { "enum": [ "in", "out" ], "readOnly": true, "type": "string", "wasp-const": true } ---- a|The i/o block signal direction. a|io_idx a|True a| [source, json] ---- { "minimum": 0, "readOnly": true, "type": "integer", "wasp-const": true } ---- a|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. a|io_type a|True a| [source, json] ---- { "enum": [ "analog", "aes3", "aes67", "gpio" ], "readOnly": true, "type": "string", "wasp-const": true } ---- a|The i/o block type. a|label a|False a| [source, json] ---- { "type": "string", "wasp-persist": true } ---- a|The i/o block user read/write label string. a|members a|True a| [source, json] ---- { "items": { "format": "object_id", "minimum": 0, "readOnly": true, "type": "number", "wasp-const": true }, "readOnly": true, "type": "array" } ---- a|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` [source, json] ---- { "_id": 7, "_parent": null, "_schema": "_IOBlock", "_type": "block:io", "io_dir": "in", "io_idx": 2, "io_type": "analog", "label": "Line/Mic 2" } ---- [[ctrl:ipv4_interface, ctrl:ipv4_interface]] ==== `ctrl:ipv4_interface` - IPv4 address control. .Properties specific to object type `ctrl:ipv4_interface` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|address a|True a| [source, json] ---- { "default": null, "format": "ipv4", "type": [ "string", "null" ] } ---- a|The IPv4 address. a|address_assignment_mode a|True a| [source, json] ---- { "default": "dhcp", "enum": [ "static", "dhcp" ], "type": "string" } ---- a|Configure the method used to assign an IP address. a|dnsserver a|True a| [source, json] ---- { "default": null, "format": "ipv4", "type": [ "string", "null" ] } ---- a|The IPv4 address of the domain name server. a|gateway a|True a| [source, json] ---- { "default": null, "format": "ipv4", "type": [ "string", "null" ] } ---- a|The IPv4 address of the gateway a|mac_interface a|True a| [source, json] ---- { "format": "object_id", "minimum": 0, "readOnly": true, "type": "number", "wasp-const": true } ---- a|Object ID of the MAC interface object this IP address belongs to. a|netmask a|True a| [source, json] ---- { "default": null, "format": "ipv4", "type": [ "string", "null" ] } ---- a|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` [source, json] ---- { "_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" } ---- [[ctrl:mac_interface, ctrl:mac_interface]] ==== `ctrl:mac_interface` - MAC interface control. .Properties specific to object type `ctrl:mac_interface` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|label a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|The friendly name for the MAC interface. a|link_speed a|True a| [source, json] ---- { "default": 0, "readOnly": true, "type": "number" } ---- a|The link speed in megabits/second. a|link_status a|True a| [source, json] ---- { "default": "inactive", "enum": [ "active", "inactive" ], "readOnly": true, "type": "string" } ---- a|The state of the link. a|mac_address a|True a| [source, json] ---- { "readOnly": true, "type": "string" } ---- a|The MAC address. |=== Common properties of this object type are described in <<_common_object_properties>>. .Example 1 for WASP object type `ctrl:mac_interface` [source, json] ---- { "_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" } ---- [[ctrl:meter, ctrl:meter]] ==== `ctrl:meter` - Meter control. WASP objects of this type are identified by having `_type == "ctrl:meter"`. .Properties specific to object type `ctrl:meter` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|peak a|True a| [source, json] ---- { "readOnly": true, "type": "number", "wasp-unit": "dB" } ---- a|Meter reading. |=== Common properties of this object type are described in <<_common_object_properties>>. .Example 1 for WASP object type `ctrl:meter` [source, json] ---- { "_id": 9, "_parent": 7, "_schema": "_MeterControl", "_type": "ctrl:meter", "peak": -7 } ---- [[ctrl:mute, ctrl:mute]] ==== `ctrl:mute` - Mute control. Mute is controlled by the `active` property. WASP objects of this type are identified by having `_type == "ctrl:mute"`. .Properties specific to object type `ctrl:mute` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|active a|True a| [source, json] ---- { "default": false, "type": "boolean", "wasp-persist": true } ---- a|This property allows the mute to be turned off and on. a|button_enabled a|False a| [source, json] ---- { "default": true, "type": "boolean", "wasp-persist": true } ---- a|Enable control of mute function via the associated button. a|button_mode a|False a| [source, json] ---- { "default": "latching", "enum": [ "latching", "momentary" ], "type": "string", "wasp-persist": true } ---- a|Mute control button mode. a|button_state a|False a| [source, json] ---- { "default": "released", "enum": [ "pressed", "released" ], "readOnly": true, "type": "string" } ---- a|Mute button state. |=== Common properties of this object type are described in <<_common_object_properties>>. .Example 1 for WASP object type `ctrl:mute` [source, json] ---- { "_id": 8, "_parent": 7, "_schema": "_MuteControl", "_type": "ctrl:mute", "active": true } ---- [[ctrl:phantom, ctrl:phantom]] ==== `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"`. .Properties specific to object type `ctrl:phantom` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|active a|True a| [source, json] ---- { "default": false, "type": "boolean", "wasp-persist": true } ---- a|This property allows the phantom power to be turned off and on. a|voltage a|True a| [source, json] ---- { "readOnly": true, "type": "number", "wasp-const": true, "wasp-unit": "V" } ---- a|Phantom power voltage. |=== Common properties of this object type are described in <<_common_object_properties>>. .Example 1 for WASP object type `ctrl:phantom` [source, json] ---- { "_id": 8, "_parent": 7, "_schema": "_PhantomPowerControl", "_type": "ctrl:phantom", "active": true, "voltage": 48 } ---- [[device:sw_desc, device:sw_desc]] ==== `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"`. .Properties specific to object type `device:sw_desc` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|name a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|The name of the software module. a|vendor a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|The entity that wrote or produced the software module. a|version a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|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` [source, json] ---- { "_id": 5, "_parent": null, "_schema": "_SoftwareDescriptor", "_type": "device:sw_desc", "name": "Iyo Dante firmware", "vendor": "AudioScience Inc", "version": "1.0.2" } ---- [[ctrl:temperature_sensor, ctrl:temperature_sensor]] ==== `ctrl:temperature_sensor` - Temperature sensor reading .Properties specific to object type `ctrl:temperature_sensor` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|location a|True a| [source, json] ---- { "readOnly": true, "type": "string", "wasp-const": true } ---- a|Where the sensor is located. a|temperature a|True a| [source, json] ---- { "readOnly": true, "type": "number", "wasp-unit": "C" } ---- a|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` [source, json] ---- { "_id": 19, "_parent": null, "_schema": "_TemperatureSensorControl", "_type": "ctrl:temperature_sensor", "temperature": 45 } ---- [[ctrl:trim_level, ctrl:trim_level]] ==== `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"`. .Properties specific to object type `ctrl:trim_level` [%header,cols="1,1,10,10"] |=== a|Property name a|Required a|Basic schema a|Description a|level a|True a| [source, json] ---- { "type": "number", "wasp-persist": true, "wasp-unit": "dBu" } ---- a|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` [source, json] ---- { "_id": 9, "_parent": 7, "_schema": "_TrimControl", "_type": "ctrl:trim_level", "level": 14 } ----