Networked Media Open Specifications

Controller implementation tutorial

←Device implementation tutorial · Index↑ · How To practical examples→

This section covers quickly building an MS-05 / IS-12 / BCP-008 controller implementation.

Quick checklist

This is a summary of the main areas to consider when starting your implementation.

The following are other important areas relevant when working with devices which employ specific functionality.

Further detail for each step is included in the Guidance section.

Guidance

This section provides guidance in select focus areas required for controller implementations.

The basic controller workflow follows the diagram below where individual steps are detailed in the following subsections.

Basic controller sequence
Basic controller sequence

Exploring the device model

As per the MS-05-02 specification all MS-05 / IS-12 devices expose a structure starting with the root block which always has an oid of 1.

The root block, among other things holds Managers which are special singleton control classes which collate information which pertains to the entire device.

A minimal implementation of a device has at least two managers listed in the root block:

Typical device structure
Typical device structure

A controller is expected to Discover the structure of a device by recursively querying the members of nested blocks. It also discovers the implemented managers in the root block by checking their class identity or roles.

Exploring device model
Exploring the device model

As per the MS-05-01 specification there are different types of identifiers which ultimately can be split into two categories:

Identities
Identities

A controller is expected to be able to work with all the identifiers exposed by a device.

Note: Persistent identifiers like role paths can be used to consistently identify a particular control class instance in the device structure and then rediscover some of its properties including the runtime object id.

Control class definition discovery

Controllers are expected to use the Class manager in order to discover any control classes used by the devices they are connected to.

Data type definition discovery

Controllers are expected to use the Class manager in order to discover any data types used by the devices they are connected to.

Discovering the device control endpoint (in NMOS IS-04)

The NMOS IS-12 specification explains that the control endpoint is advertised in the controls array as part of the NMOS device resource. The schema for the NMOS device resource is available in the NMOS IS-04 specification.

This means that a controller can discover if an NMOS device exposes an NMOS IS-12 control endpoint by checking if the controls array in the NMOS device resource contains the control type of urn:x-nmos:control:ncp.

Control endpoint example:

{
  ...
    "senders": [
        ...
    ],
    "receivers": [
        ...
    ],
    "controls": [
        {
            "type": "urn:x-nmos:control:ncp/v1.0",
            "href": "ws://hostname/example"
        }
    ],
    "type": "urn:x-nmos:device:generic",
    "id": "58f6b536-ca4c-43fd-880a-9df2501fc125",
  ...
}

The controller can then use the discovered control endpoint to make the initial WebSocket connection which will subsequently be used for NMOS IS-12 parameter control.

Sending commands and receiving responses

As per the NMOS IS-12 specification a controller can send Commands and receive responses.

Note: Multiple commands can be sent in the commands array.

As per the MS-05-02 specification all control classes inherit from NcObject which specifies generic Get and Set methods.

These methods can be used by a controller to get the value of a property in an object or set the value of a property in an object if write allowed.

Subscribing and receiving notifications

As per the MS-05-02 specification all control classes inherit from NcObject which specifies the PropertyChanged event.

This means any object can be subscribed to in order to receive property change notifications.

A controller is expected to Subscribe to object ids it is interested in by sending Subscription messages as specified in NMOS IS-12.

Status monitors

BCP-008-01 and BCP-008-01 define specialised NcReceiverMonitor and NcSenderMonitor worker classes which report statuses, status messages and status transition counters for relevant domains like Connectivity, Synchronization or Stream validation.

Objects implementing these classes publish the IS-04 resource identity they are monitoring (Sender or Receiver) through the context identity mapping mechanism.

Sender and Receiver monitors derive from the base class NcStatusMonitor which specified an overallStatus property. This property combines the specific domain statuses of a monitor into a single status which can be more easily observed and displayed by a simple client.

Controllers are expected to be able to find all status monitors published by a device and be able to retrieve statuses, status messages and status transition counters for relevant domains from these objects. They are also expected to retrieve the overallStatus property of each status monitor object.

For full controller requirements check the relevant sections in BCP-008-01 and BCP-008-02.

Context identity mapping

MS-05-02 specifies an identity mapping mechanism available in the base NcObject class. This touchpoint mechanism can be used to associate identities from outside contexts with entities inside the control structure of the device.

Examples include Receiver monitors and Sender monitors which is express domain health statuses for an attached stream receiver or sender.

This allows a Receiver monitor to be associated with a specific NMOS IS-04 receiver.

A controller is expected to decode touchpoint information where available and associate identities if it has access to the data domains exposed (For example a controller would be able to identify which NMOS IS-04 receiver is associated with a given Receiver monitor object).

Context identity mapping
Context identity mapping

Discovering non-standard models used to model vendor specific functionality

As per the MS-05-02 specification the Class manager can be used to discover the properties of any control class and the fields of any data type.

Non-standard control classes can be created by inheriting from a standard control class and following the class ID generation guidelines specified in MS-05-01.

Here is an example of a new worker control class called DemoClassAlpha. It inherits from NcWorker which has a classId of [1, 2] and adds the authority key (in this case 0, but would be a negative number if the vendor has an OUI or CID) followed by the index 1.

{
  "role": "DemoClassAlpha",
  "oid": 111,
  "constantOid": true,
  "classId": [
      1,
      2,
      0,
      1
    ],
  "userLabel": "Demo class alpha",
  "owner": 1,
  "description": "Demo control class alpha",
  "constraints": null
}

A subsequent non-standard worker would look like this:

{
  "role": "DemoClassBeta",
  "oid": 150,
  "constantOid": true,
  "classId": [
      1,
      2,
      0,
      2
    ],
  "userLabel": "Demo class beta",
  "owner": 1,
  "description": "Demo control class beta",
  "constraints": null
}

ensuring class identity uniqueness.

Controllers are expected to use the class identity lineage information alongside their core framework knowledge to determine when a control class is a non-standard control class. The following diagram shows how a vendor created a vendor specific Receiver monitor by deriving the standard Receiver monitor class.

Non-standard branching
Non-standard branching

How to

HOW TO practical examples are available here.

←Device implementation tutorial · Index↑ · How To practical examples→

Documentation built at 04:46:45 CDT on 2025-07-09.
(c) AMWA 2025. RAML/JSON licensed under Apache 2.0. Documentation licensed under CC BY-ND 4.0.