Interoperability: NMOS IS-04
←Interoperability · Index↑ · Interoperability - Non-NMOS Devices→
The Connection Management API shares a data model with the NMOS IS-04 specification, and as a result it is designed to be used alongside it. The following implementation notes identify correct behaviour for doing this.
When this API is used alongside IS-04 in a deployment, the IS-04 APIs should be operating at version 1.2 or greater in order to ensure full interoperability.
Discovery
The Connection Management API should be advertised as a ‘control’ endpoint when publishing a compliant NMOS Device. By using the common type ‘urn:x-nmos:control:sr-ctrl/v1.0’, control interfaces can identify all Devices which implement the Connection Management API, and the URLs required to access them.
Example: The ‘controls’ attribute of a single NMOS Device
...
"controls": [
{
"type": "urn:x-nmos:control:sr-ctrl/v1.0",
"href": "http://192.168.10.3/x-nmos/connection/v1.0/"
}
]
...
Note as above that the API version is included in the ‘type’, and in the ‘href’. As new versions of the Connection Management API are published, further control endpoints may be advertised for Devices which support multiple versions simultaneously.
More details about multi-version support can be found in 5.0. Upgrade Path.
A given instance of the Connection Management API may offer control of multiple Devices in a Node from a single URI. Alternatively there may be multiple instances of the API on one Node, each corresponding to one Device. A separate ‘control’ endpoint for each Device’s Connection Management instance must be advertised, even if the URI is the same.
API implementations may list an ‘href’ with or without a trailing slash, provided that the trailing slash policy in 2.0. APIs is adhered to. In order to avoid cases of double slashes or missing slashes, clients are required to exercise caution when appending paths onto this ‘href’.
Sender & Receiver IDs
The UUIDs used to advertise Senders and Receivers in the Connection Management API must match those used in a corresponding IS-04 implementation.
Version Increments
In order to prevent unnecessary polling of the Connection Management API, changes to active connection parameters should be signalled via the IS-04 versioning mechanism. When the ‘active’ parameters of a Sender or Receiver are modified, or when a re-activation of the same parameters is performed, the version attribute of the relevant IS-04 Sender or Receiver must be incremented.
Identifying Active Connections
In order to populate the subscription attribute of IS-04 Senders and Receivers, the Connection Management API includes keys for sender_id and receiver_id in its staged parameters. These should be used to signal that a Sender or Receiver is being connected to another NMOS compatible Sender or Receiver. It is the client’s responsibility to set and unset (using null) the sender_id or receiver_id parameters when modifying the transport_params or transport_file.
Support For Legacy IS-04 Connection Management
The Connection Management API supersedes the now deprecated method of updating the ‘target’ resource on Node API Receivers in order to establish connections. The two methods of operation are likely to co-exist until Version 2.0 of IS-04. As such the following best practice should be followed when both are in use:
- Where a client updates the Node API subscription, the result on the Connection Management API should be the same as if the client had first staged the parameters and then called an immediate activation. That is to say that the new parameters will be reflected both in the staged and active endpoints of the Receiver.
- Where a client updates a Connection Management API Receiver the active
sender_idparameter should be populated in the Node API subscription parameter with keysender_id. - After a Connection Management API activation the corresponding Sender or Receiver’s
versionproperty should be updated to the instant of the activation.
Should staged modifications be present when a legacy activation is performed, these parameters must be discarded in favour of those provided via the Node API interface.
←Interoperability · Index↑ · Interoperability - Non-NMOS Devices→