diff --git a/docs/Controllers.md b/docs/Controllers.md new file mode 100644 index 0000000..33e5454 --- /dev/null +++ b/docs/Controllers.md @@ -0,0 +1,115 @@ +# Controllers + +_(c) AMWA 2022, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_ + +## Introduction + +A Controller is Client software that interacts with the NMOS APIs to discover, connect and manage resources (Nodes, Devices, Senders and Receivers) within a networked media system. + +* This document includes normative references to be followed when implementing a Controller. +* This document covers how the Controller interacts with the NMOS APIs only. + It does not cover other features of the Controller software, such as presentation. +* This document does not cover any requirements relating to where a Controller is additionally acting as a Node (e.g. receiving monitoring information via IS-07). + +Where this document refers to a User, this can include both human operators who drive a Controller manually and automation systems that drive a Controller programmatically. + +## General + +### HTTP APIs + +#### Trailing Slashes + +Controllers appending paths to `href` type attributes MUST support URLs both with and without a trailing slash, to avoid doubled or missing slashes. + +Controllers performing requests other than `GET` or `HEAD` (i.e `PUT`, `POST`, `DELETE`, `OPTIONS` etc.) MUST use URLs with no trailing slash present. + +#### API Versions + +The versioning format is `v.` +* `MINOR` increments will be performed for non-breaking changes (such as the addition of attributes in a response) +* `MAJOR` increments will be performed for breaking changes (such as the renaming of a resource or attribute) + +Versions MUST be represented as complete strings. Parsing MUST proceed as follows: separate into two strings, using the point (`.`) as a delimiter. Compare integer representations of `MAJOR`, `MINOR` version (such that v1.12 is greater than v1.5). + +Implementers of Controllers are RECOMMENDED to support multiple versions of the NMOS APIs simultaneously in order to ease the upgrade process in live facilities. + +#### Error Codes & Responses + +The NMOS APIs use HTTP status codes to indicate success, failure and other cases to Controllers as per [RFC 7231](https://tools.ietf.org/html/rfc7231) and related standards. + +As explicit handling of every possible HTTP response code is not expected, Controllers MUST implement generic handling for ranges of response codes (`1xx`, `2xx`, `3xx`, `4xx` and `5xx`). +However, where the API specifies explicit response codes the Controller SHOULD handle these cases explicitly. + +When a Controller performs `GET` and `HEAD` requests, it MUST correctly handle a `301` (Moved Permanently) redirect to accommodate the API implementations permitted in the [APIs: URLs: Approach to Trailing Slashes](APIs.md#urls-approach-to-trailing-slashes) section of this specification. + +If a Controller receives an HTTP `5xx` or `4xx` response code from the API, a failure has occurred. +The Controller SHOULD display the content of the response's `error` field to the User if possible. + +## Connection Management + +The Controller MUST implement connection management according to the [APIs section](APIs.md) of this specification. + +The Controller MUST be able to perform an immediate activation between a specified Sender and Receiver via the IS-05 Connection API. + +The Controller MUST allow removal of active connections via the IS-05 Connection API. + +The Controller MUST monitor and update the connection status of all discovered IS-05 Senders and Receivers. For instance: +* The Controller MUST identify that a connection to a Receiver has been activated. +* The Controller MUST be able to identify when an NMOS Sender is connected to that Receiver. +* The Controller MUST identify when the Receiver connection has been deactivated. + +Where making requests to a large number of Senders and/or Receivers on the same Device, Controllers SHOULD make use of the `/bulk` endpoint to bundle them into a single request. + +When altering the transport parameters in the `/staged` endpoint, the Controller SHOULD check the `/constraints` endpoint for the available choices of parameters accepted by the particular Sender or Receiver. + +When `PATCH`ing to the transport parameters, parameters could possibly have changed since the last `GET`. +Therefore the Controller SHOULD set parameters that are important for a connection (e.g. `master_enable` and `rtp_enable`) in the `PATCH` request, even if the Controller believes they are already set as required. + +When connecting a Receiver to an NMOS Sender, the Controller SHOULD communicate the Sender UUID to the receiver using the `sender_id` parameter of the `/staged` endpoint. + +## Client Side Implementation Notes + +Controllers MUST adhere to the [Client Side Implementation Notes]((APIs%20-%20Client%20Side%20Implementation.md) described in this specification, such as the sections on Conformance to Schemas, RTP Operating Point, and Failure Modes. + +## Interoperability + +### Interoperability with IS-04 + +#### API Common Keys + +Controllers MUST follow the requirements for common API keys specified in the [IS-04 APIs: Common Keys](https://specs.amwa.tv/is-04/releases/v1.3.1/docs/2.1._APIs_-_Common_Keys.html) document including the requirements regarding [use of URNs](https://specs.amwa.tv/is-04/releases/v1.3.1/docs/2.1._APIs_-_Common_Keys.html#use-of-urns). + +#### Identifying Active Connections + +As is described in the [Interoperability: IS-04: Identifying Active Connections](Interoperability%20-%20IS-04.md#identifying-active-connections) section of this specification, +in order to populate the subscription attribute of IS-04 Senders and Receivers, the Connection API includes keys for `sender_id` and `receiver_id` in its `/active` and `/staged` parameters. +These are used to signal that a Sender or Receiver is connected to an NMOS Receiver or Sender. +The Controller MUST set and unset (using `null`) the `sender_id` or `receiver_id` parameters when modifying the `transport_params` or `transport_file`. + +### Interacting with Non-NMOS Devices + +Controllers MUST follow the requirements for a Client interacting with non-NMOS Devices, as described in the [Interoperability: Non-NMOS Devices](Interoperability%20-%20Non-NMOS%20Devices.md) section of this Specification. + +## Behaviour + +### Operation with SMPTE 2022-7 + +When the Controller is interacting with Receivers that support SMPTE 2022-7 it MUST follow the requirements for Clients described in the [Behaviour: RTP Transport Type: Operation with SMPTE 2022-7](Behaviour%20-%20RTP%20Transport%20Type.md#operation-with-smpte-2022-7) section of this specification. + +### Version Timestamp + +The Controller SHOULD use an IS-04 Query API WebSocket connection to monitor version timestamp increments on Senders and Receivers being controlled. + +A version timestamp increment indicates that the properties of a resource have changed, for example by the action of another Controller, and as such any information cached by the Controller could possibly be stale. + +### Sender Multicast Address + +The Controller MUST allow the User to configure the multicast transmit information (using IS-05 `transport_params`) before or in the same transaction as enabling the transmitter (setting `master_enable` to `true`). +This allows avoiding conflicts with other senders' configurations, in particular when a Sender is added to a new system. + +### TCP Sessions + +The Controller SHOULD use persistent TCP connections wherever possible, +to allow multiple operations to be performed without repeatedly closing and reopening connections for each operation. + +If the Controller uses HTTP pipelining, the guidelines set out in [RFC 7230 section 6.3.2](https://datatracker.ietf.org/doc/html/rfc7230#section-6.3.2) apply. diff --git a/docs/Overview.md b/docs/Overview.md index 73d8d61..4f298c9 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -21,7 +21,8 @@ The Specification includes: IS-05 is intended to be used in conjunction with an [IS-04 NMOS Discovery & Registration](https://specs.amwa.tv/is-04) deployment; however it has been written in such a way to provide useful functionality even in the absence of such a system. -The terms 'Node', 'Device', 'Sender' and 'Receiver' are used extensively in this documenation set. The [NMOS Technical Overview](https://specs.amwa.tv/nmos/main/docs/2.0._Technical_Overview.html) provides an outline of these terms, and IS-04 provides corresponding schema definitions. +The terms 'Node', 'Device', 'Sender' and 'Receiver' are used extensively in this documentation set. +The [NMOS Technical Overview](https://specs.amwa.tv/nmos/main/docs/2.0._Technical_Overview.html) and the [NMOS Glossary][Glossary] define these and other common terms that have specific meanings in NMOS. ## Use of Normative Language @@ -68,4 +69,5 @@ The following sequence diagram shows the interactions between a client and the A ![Connection Management Sequence](images/direct_seq_diagram.png) +[Glossary]: https://specs.amwa.tv/nmos/main/docs/Glossary.html "NMOS Glossary" [RFC-2119]: https://tools.ietf.org/html/rfc2119 "Key words for use in RFCs" diff --git a/docs/README.md b/docs/README.md index 2f33b1f..f02bd7f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,6 +21,10 @@ - [MQTT Transport Type](Behaviour%20-%20MQTT%20Transport%20Type.md) - [WebSocket Transport Type](Behaviour%20-%20WebSocket%20Transport%20Type.md) +### Controllers + +- [General](Controllers.md) + ### Miscellaneous - [Upgrade Path](Upgrade%20Path.md)