Controller implementation tutorial
←Device implementation tutorial · Index↑ · How To practical examples→
- Controller implementation tutorial
- Guidance
- Discovering the device control endpoint (in NMOS IS-04)
- Creating a control session
- Sending heartbeats
- Sending commands and receiving responses
- Exploring the device tree structure
- Subscribing and receiving notifications
- Context identity mapping (Receiver monitor example)
- Discovering vendor specific control classes and data types
- How to
- Guidance
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.
Creating a control session
As per the NMOS IS-12 specification a controller first needs to create a control session by sending a CreateSession message.
The control session provides the control context for issuing subsequent commands, receiving responses and notifications. It also specifies how often heartbeats are sent (see Sending heartbeats).
The value received in the Create session response message is the control session id the device has allocated for use. It needs to be used in every subsequent communication with the device.
Note: It is expected that if the WebSocket connection fails for any reason, the controller will reconnect to the WebSocket endpoint and create a new control session. Control sessions are not persisted across reconnections.
Sending heartbeats
As per the NMOS IS-12 specification a controller needs to send Heartbeat messages for their control sessions at the intervals specified when creating the session (see Creating a control session).
Devices will acknowledge each heartbeat with a response.
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 messages array.
As per the MS-05-02 specification all control classes must 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 a control class or set the value of a property in a control class if write allowed.
Exploring the device tree structure
As per the MS-05-02 specification all MS-05 / IS-12 devices will 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 will have at least three managers listed in the root block:
- Device manager
- Subscription 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 will also discover the implemented managers in the root block by checking their class identity or roles.
 |
|---|
| Exploring device tree |
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 must inherit from NcObject which specifies the PropertyChanged event.
This means any properties in any control class can be subscribed to in order to receive change notifications. Subscriptions are handled by the Subscription manager.
A controller is expected to Subscribe to object ids it is interested in by sending commands to the Subscription manager.
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 expose and 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.
This 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 control class instance).
 |
|---|
| Context identity mapping |
Discovering vendor specific control classes and data types
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.
Vendor specific 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 an identity of [1, 2] and adds the authority key (in this case 0, but should be a negative number if the vendor has an OUI or CID) followed by the index 1.
{
"role": "DemoClassAlpha",
"oid": 111,
"constantOid": true,
"identity": {
"id": [
1,
2,
0,
1
],
"version": "1.0.0"
},
"userLabel": "Demo class alpha",
"owner": 1,
"description": "Demo control class alpha",
"constraints": null
}
A subsequent vendor specific worker would look like this:
{
"role": "DemoClassBeta",
"oid": 150,
"constantOid": true,
"identity": {
"id": [
1,
2,
0,
2
],
"version": "1.0.0"
},
"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 vendor specific control class.
 |
|---|
| Vendor specific 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→