Controller implementation tutorial
←Device implementation tutorial · Index↑ · How To practical examples→
- Controller implementation tutorial
- Guidance
- How to
This section covers the basis for quickly building an MS-05 / IS-12 controller implementation.
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 |
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.
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:
- Device manager
- Class manager
 |
|---|
| 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 the device model |
As per the MS-05-01 specification there are different types of identifiers which ultimately can be split into two categories:
- dynamic identifiers (object identifiers)
- persistent identifiers (roles, class identities and data type names)
 |
|---|
| 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.
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.
Context identity mapping (Receiver monitor example)
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.
One such example is the ReceiverMonitor control class which is used to express connection and payload statuses for an attached stream receiver.
The touchpoint mechanism allows for 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 identity which NMOS IS-04 receiver is associated with a given Receiver monitor object).
 |
|---|
| 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 branching off 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.
 |
|---|
| Non-standard branching |
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.
How to
HOW TO practical examples are available here.
←Device implementation tutorial · Index↑ · How To practical examples→