IS 04 05 Node
Please refer to the Generic API Server page as a starting point before considering the specifics below.
A list of open source IS-04 registry implementations which may be of use when developing a Node is available from the NMOS Solutions page.
- Expose an IS-04 Node API and IS-05 Connection API from a suitable port on your host (preferably 80 for HTTP and 443 for HTTPS)
- Discover an appropriate IS-04 Registration API using DNS Service Discovery.
- Select the maximum API version from those supported by the Registration API which your Node also supports.
- Issue a POST request to the /resource resource of the Registration API for each resource from your Node API. Simultaneously issue periodic heartbeats to the /health/nodes/id resource, where 'id' matches your Node ID.
- Issue POST requests to the /resource resource of the Registration API each time one of your Node's resources is modified, ensuring that the 'version' attribute of the resource is updated when doing so.
- Observe and interpret all of the TXT records returned with the DNS Service Discovery responses. These indicate the preferred API instance to use (via 'pri'), the API versions supported (via 'api_ver') and the protocol supported (via 'api_proto').
- If a Registration API request fails, follow the procedures described here and in the notes below, including use of exponential backoff when error responses are returned.
- Permit re-configuration of your Node's heartbeat interval, whilst observing the required defaults.
- Expose configuration options where multiple modes of operation exist. These may include, but are not limited to:
- Registration version: Providing the option between 'auto' if supported, or a list of supported versions.
- Discovery mode: Providing the option between 'auto', 'unicast' or 'multicast' DNS.
- Protocol: Providing the option between 'http' or 'https' if both are supported.
The following flowchart shows the current best practice for a state machine which handles registrations with an IS-04 Registration API.
Persistent identity helps to ensure that users' expectations meet with reality. For example, if a piece of equipment is switched off and back on, the user would expect it to return with the same signals routed to and from the same ports. A control system managing this can only do so if the identifiers used by the Node remain the same.
UUIDs are used throughout the NMOS data model, and can be generated in a number of ways (including from hardware addresses) in order to achieve consistent behaviour (see RFC 4122).
Some Node implementations may find it useful to expose their APIs via multiple network interfaces. In particular this may be true for Nodes which do not have a separate management or control network connection, but do have two media network connections intended for operation with SMPTE 2022-7. When operating in this mode, the following guidance may be useful for implementers:
-
Node APIs should expose identical JSON representations via any interfaces which they are bound to. A Node's '/self' resource in IS-04 cannot for example expose a different 'href' when viewed from one network interface versus another. Within the '/self' resource, the 'href' is deprecated and instead use of the 'endpoints' array which permits specifying multiple interface addresses is preferred. This condition ensures that any IS-04 resource with a given ID has identical attributes no matter which interface it is viewed from.
-
When populating IS-04's Node 'services' or Device 'controls' arrays, a Node may list multiple entries for the same service or control 'type' with differing 'href' attributes. This can be used (for example) to signal from IS-04 that an IS-05 API is available via two different network interfaces.
-
When interacting with a registry from a Node with multiple interfaces it is recommended that the Node only interacts with a single Registration API at any one time. The Node may use a fallback Registration API which is available via a different network interface in the case of a link failure, but it should not interact with two Registration API instances at the same time. The single exception to this rule is where a system is being deployed with two independent registries on two separate networks which the Node has access to. In this case a Node may be required to maintain a registration in two places at once. This exception should only be permitted if the Node has been explicitly configured in this way.
Some Node implementations may be developed to simultaneously support a range of versions of the IS-04 specification in order to ensure maximal interoperability. Where this is the case, the following guidelines should assist with implementations of Registration API interactions:
-
When a Node first comes online, it is recommended that it defaults to registering using the highest common API version supported by both the Node and any visible registries.
-
Once a Node has registered with a registry, it should continue to carry out transactions using the same API version, even if the registry begins to advertise a new higher API version which the Node also supports. The Node should only transition to using this new preferred API version if it is explicitly requested to do so (perhaps via a reboot).
-
When transitioning between being registered at one API version to being registered at another, a Node must first ensure all of its existing resources have been removed from the registry (via HTTP DELETE) in order to ensure it is not registered using multiple conflicting versions at the same time. The same requirement applies whether this transition is being performed against a single Registration API instance, or between two separate Registration API instances available via the network.
-
A Node implementer may choose to provide the option to lock the Node's Registration API interactions to a specific version such that dynamic transitions may be limited in a production environment.
See the DNS Configuration Guide for how to configure a DNS server to advertise a Registration or Query API.
The IS-05 Device Connection Management specification shares a data model with the 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 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 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 API are published, further control endpoints may be advertised for Devices which support multiple versions simultaneously.
A given instance of the Connection 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.
The UUIDs used to advertise Senders and Receivers in the Connection API must match those used in a corresponding IS-04 implementation.
In order to prevent unnecessary polling of the Connection 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 updated to the instant of the activation.