NAV Navbar
shell javascript

Introduction

OpenAVI (Open Audio Visual Interface or OAVI) is proposed as a new standard for the acquisition of data and control of lighting and audio/visual devices.

The OpenAVI platform becomes an additional layer in the control network allowing the integration of multiple devices on the same network. The system would act as way to quickly visualise data, update settings, change profiles and complete other predefined and manufacturer specific commands.

Definitions

Versioning

The OpenAVI standard is currently designated as v1.

OpenAVI Platform

Discovery Platform

Discovery Response

{
    "id": "com.onlx.ctrl-for-ipad",
    "port": 80,
    "name": "ON LX iPad",
    "instance": "765ca13a22093f31a87eb73b75ea6e07"
}

Contact our team for more information and code samples for the Discovery Platform.

OpenAVI Tiers

Integration of the OpenAVI standard is classified under one of two tiers:

Integrating

This section documents the workings and design of the OpenAVI Platform.

The platform requires a dedicated root scope of /api/ which forms the command address. Manufacturers remain free to use other forms of HTTP commands providing they do not sit in the OpenAVI scope.

Requests

Requests made to nodes must follow the notation pattern as below. Additional chaining is possible ensuring it follows a logical pattern.

Pattern Description
/api/<version>/<property> Top Level Property
/api/<version>/<property>/<id> Single object from top Level Property
/api/<version>/<property>/<id>/<cmd> Command on single object
/api/<version>/<property>/<id>/<cmd>/<id> Part of single object

Methods

The OpenAVI Platform uses the HTTP methods GET, POST and DELETE.
The body of requests made using the POST method must be a valid JSON format.

Method Description
Read information from the node
Set or update a property on the node
Delete a property on the node

Response

Successful Response

{
    "key": "value"
}

Bad Response

{
    "status": 400,
    "response": "The request ID provided was invalid"
}

The responses provided by a node must be a valid JSON object. Responses must include the relevant status (see Response Codes) in the header and data. In the case of POST or DELETE requests confirmation must be provided using the applicable Response Code with an optional response key providing a plain text explanation.

Globals

All integrations of the platform are required to include three global commands. Global commands do not require authentication as these endpoints are used during the Tier 1 discovery process.

OpenAVI Version - Response

{
    "version": "v1",
    "spec": "oavi"
}

The node must provide a version/spec endpoint to allow a client to determine that it is using the OpenAVI standard. A controller will also use this endpoint as part of the discovery process to enusre communication occurs using the correct standard version.

Device Info - Response

{
    "id": "com.onlx.ctrl-for-ipad",
    "type": "Ctrl for iPad",
    "name": "ON LX iPad",
    "manufacturer": "ON LX Limited",
    "version": "2.0.0"
}

The node must provide information including unique identifier, type and manufacturer all other fields are optional.

Network - Response

{
    "interfaces": [
        {
            "name": "eth0",
            "address": "10.0.0.1",
            "netmask": "255.0.0.0",
            "mac_address": "AA:BB:CC:DD:EE:FF"
        }
    ]
}

The node must provide information on its network interface(s) including address, netmask and mac address.

Authentication

curl -X POST \
  http://127.0.0.1/api/authorise \
  -H 'Content-Type: application/json' \
  -d '{
        "username": "User",
        "password": "pass"
    }'

var request = require("request");

var options = {
    method: 'POST',
    url: 'http://127.0.0.1/api/authorise',
    headers: {
        'Content-Type': 'application/json'
    },
    body: {
        username: 'User',
        password: 'pass'
    },
    json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Token Response

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInVCJ9.eyJzdWIiOiIxMjM0…",
    "expires": 3600,
    "scope": "read write delete"
}

/api/authorise

If authorisation is used in the product, all node commands would be required to include an authentication header. A secure connection using HTTPS would be recommended however would likely cause issues if deployed on a local network due to the use of self signed certificates. The platform specifies the use of JSON Web Tokens to generate a single token with the user providing a username/password for validation on the node.

Manufacturers are free to implement user management and permission groups/scopes as applicable.

Further details on JSON Web Tokens (JWT) and implementation can be found at jwt.io.

Response Codes

A response code will be provided along with requested data or response in a successfully state or an error message in an error state. The status code of the header must match the status code provided in the body.

A response should look like this

{
    "status": 400,
    "response": "Bad Request. Request made by client is invalid"
}
Response Code Meaning
200 OK. Successful response
400 Bad Request. Request made by client is invalid
401 Unauthorised. Client is not authenticated or authentication is invalid
403 Forbidden. Access to the endpoint is forbidden
404 Not Found. The endpoint could not be found
405 Method Not Allowed - The request method is invalid
406 Not Acceptable - The format requested is invalid
500 Internal Server Error - The node experienced an error

Case Study

The diagram below illustrates the system configuration of an event within a receiving venue. The event requires multiple acts, consequently with multiple touring LD’s and their chosen brand of console. The nature of the event requires quick changeovers between the consoles used.

Case Study

The rig includes the following equipment:

Usage

The OpenAVI standard is freely available for use to any person(s). Its usage must comply with the requirement set out in the standards document and specify the implemented Tier level.

All person(s) wishing to implement OpenAVI should contact the team at ON LX Limited for further documentation and to obtain an OEM code.

The OpenAVI mark can be used on packaging / on devices directly to show compliance with this standard and used freely with the permission of ON LX Limited following compliance testing, fair usage will be monitored by ON LX Limited.

OpenAVI™ and Labs by ON LX™ are trademarks of ON LX Limited.
"ON LX" and "ON LX - Technical Services" are trading names of ON LX Limited.
ON LX Limited is a registered company in England and Wales. Registered Office: 5 Aviary Way, Crawley Down, West Sussex RH10 4XR. Company number 08366675

References

shell javascript