Skip to content

Some final tweaks #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cristian-recoseanu merged 6 commits into from
Jun 5, 2025
Merged

Some final tweaks #21

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
094c21b
Update links to feature sets register
cristian-recoseanu May 14, 2025
475eafd
Clarify that we mean "detected errors"
cristian-recoseanu May 15, 2025
7c2969e
Add recommendation for overallStatusMessage
cristian-recoseanu May 22, 2025
a0f9f18
Tweak NcWorker inheritance conformance guidance
cristian-recoseanu May 29, 2025
7eeff7e
Add further recommendations on retaining the previous status message
cristian-recoseanu May 29, 2025
30c60de
Further clarify overallStatusMessage recommendation
cristian-recoseanu May 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 64 additions & 16 deletions docs/Overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This document relies on previous familiarity with the following existing documen
* [NMOS Discovery and Registration](https://specs.amwa.tv/is-04/)
* [NMOS Device Connection Management](https://specs.amwa.tv/is-05/)

The technical models referenced in this document are fully published in the [Monitoring NMOS Control Feature Set](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/).
The technical models referenced in this document are fully published in the [Monitoring NMOS Control Feature Set](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/).

The following domains are covered in terms of status monitoring with specific sections for each:

Expand Down Expand Up @@ -51,11 +51,11 @@ Devices in conformance to this BCP MUST comply with [NMOS Device Connection Mana

## Receiver monitoring

The technical model describing the monitoring requirements for a receiver is [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor).
The technical model describing the monitoring requirements for a receiver is [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor).

This model inherits from the baseline status monitoring model [NcStatusMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncstatusmonitor).
This model inherits from the baseline status monitoring model [NcStatusMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncstatusmonitor).

Receiver monitors MUST implement [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor) directly or derive a [vendor specific variant from NcReceiverMonitor](https://specs.amwa.tv/ms-05-02/latest/docs/Introduction.html) which MAY add more statuses, properties and methods but MUST still comply with the requirements set out in this specification.
Receiver monitors MUST implement [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor) directly or derive a [vendor specific variant from NcReceiverMonitor](https://specs.amwa.tv/ms-05-02/latest/docs/Introduction.html) which MAY add more statuses, properties and methods but MUST still comply with the requirements set out in this specification.

| ![Receiver monitoring model](images/receiver-model-minimal.png) |
|:--:|
Expand Down Expand Up @@ -99,6 +99,22 @@ The purpose of the overallStatus is to abstract and combine the specific domain

`Note`: The overallStatus might remain the same even when specific domain statuses change. However, the overallStatusMessage might change to indicate that a different combination of internal states is causing the current overallStatus value.

Where possible, Device implementations are RECOMMENDED to populate the overallStatusMessage with the root causes which led to the current PartiallyHealthy or Unhealthy overallStatus.

For example, a number of domain statuses become less healthy when a network interface is down. In this case the overallStatusMessage could report the following root cause

```log
NIC 1 is down
```

Furthermore, where possible Device implementations are RECOMMENDED to retain the previous status message when returning to a Healthy state from a PartiallyHealthy or Unhealthy state by prepending the previous message with "Previously: ".

For example, upon recovery to a healthy state the overallStatusMessage could hold the following value

```log
Previously: NIC 1 is down
```

Devices MUST follow the rules listed below when mapping specific domain statuses in the combined overallStatus:

* When the Receiver is Inactive the overallStatus uses the Inactive option
Expand All @@ -111,7 +127,7 @@ Devices MUST follow the rules listed below when mapping specific domain statuses

### Receiver connectivity

[NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor) includes the following specific items covering the connectivity domain:
[NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor) includes the following specific items covering the connectivity domain:

* Properties
* linkStatus
Expand Down Expand Up @@ -148,6 +164,14 @@ Example:
NIC1, NIC2 are down
```

Furthermore, where possible Device implementations are RECOMMENDED to retain the previous status message when returning to a Healthy state from a PartiallyHealthy or Unhealthy state by prepending the previous message with "Previously: ".

For example, upon recovery to a healthy state the linkStatusMessage could hold the following value

```log
Previously: NIC1, NIC2 are down
```

#### Connection status

The connectionStatus property allows devices to expose the health of the receiver with regards to receiving stream packets successfully. Other connection problems like 802.1x authorization, DHCP and other causes are also reflected in the connectionStatus.
Expand All @@ -161,6 +185,14 @@ Devices MUST report the connectionStatus as follows:

The connectionStatusMessage is a nullable property where devices MAY offer the reason and further details as to why the current status value was chosen.

Furthermore, where possible Device implementations are RECOMMENDED to retain the previous status message when returning to a Healthy state from a PartiallyHealthy or Unhealthy state by prepending the previous message with "Previously: ".

For example, upon recovery to a healthy state the connectionStatusMessage could hold the following value

```log
Previously: Packet loss detected
```

#### Late and lost packets

The receiver monitoring model provides means of gathering metrics around late and lost stream packets. These are not statuses but instead enable further analysis when [link status](#link-status) or [connection status](#connection-status) indicate problems (are PartiallyHealthy or Unhealthy).
Expand All @@ -186,7 +218,7 @@ When devices do not have the capability to detect lost or late packets they MUST

### Receiver synchronization

[NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor) includes the following specific items covering the synchronization domain:
[NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor) includes the following specific items covering the synchronization domain:

* Properties
* externalSynchronizationStatus
Expand Down Expand Up @@ -216,13 +248,21 @@ Devices are RECOMMENDED to publish in the externalSynchronizationStatusMessage p
Example:

```log
previousSync:baseband from SDI1, currentSync: 0x00:0c:ec:ff:fe:0a:2b:a1 from NIC1
Sync source change, from:baseband on SDI1, to: 0x00:0c:ec:ff:fe:0a:2b:a1 on NIC1
```

or

```log
previousSync:0x70:35:09:ff:fe:c7:da:00 from NIC1, currentSync: 0x00:0c:ec:ff:fe:0a:2b:a1 from NIC2
Sync source change, from:0x70:35:09:ff:fe:c7:da:00 on NIC1, to: 0x00:0c:ec:ff:fe:0a:2b:a1 on NIC2
```

Furthermore, where possible Device implementations are RECOMMENDED to retain the previous status message when returning to a Healthy state from a PartiallyHealthy or Unhealthy state by prepending the previous message with "Previously: ".

For example, upon recovery to a healthy state the externalSynchronizationStatusMessage could hold the following value

```log
Previously: Sync source change, from:baseband on SDI1, to: 0x00:0c:ec:ff:fe:0a:2b:a1 on NIC1
```

#### Synchronization source change
Expand All @@ -233,7 +273,7 @@ When devices observe a synchronization source change the `externalSynchronizatio

### Receiver stream validation

[NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor) includes the following specific items covering the stream validation domain:
[NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor) includes the following specific items covering the stream validation domain:

* Properties
* streamStatus
Expand All @@ -251,7 +291,7 @@ The streamStatus property allows devices to expose the health of the receiver wi
Devices MUST report the streamStatus as follows:

* Inactive when the receiver is Inactive (this is a neutral state)
* Healthy when the receiver is Active and can decode the incoming stream without any errors
* Healthy when the receiver is Active and can decode the incoming stream without any detected errors
* PartiallyHealthy when the receiver is Active and can decode the incoming stream but there are inconsistencies in the stream with what the device is expecting
* Unhealthy when the receiver is active and cannot decode the incoming stream

Expand All @@ -271,6 +311,14 @@ Payload ID in RTP stream does not match SDP file
Parameter X does not match expectations
```

Furthermore, where possible Device implementations are RECOMMENDED to retain the previous status message when returning to a Healthy state from a PartiallyHealthy or Unhealthy state by prepending the previous message with "Previously: ".

For example, upon recovery to a healthy state the streamStatusMessage could hold the following value

```log
Previously: Payload ID in RTP stream does not match SDP file
```

### Deactivating a receiver

A Receiver is deactivated after an [IS-05 activation](https://specs.amwa.tv/is-05/latest/docs/Interoperability_-_IS-04.html#identifying-active-connections) results in the Receiver `master_enable` becoming `false`.
Expand All @@ -289,7 +337,7 @@ When a receiver is being deactivated it MUST cleanly disconnect from the current

Receiver monitors make use of the [Touchpoints](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html#touchpoints) mechanism inherited from [NcObject](https://specs.amwa.tv/ms-05-02/latest/docs/NcObject.html) to attach to the correct receiver identity.

The `touchpoints` property of any [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor) MUST have one or more touchpoints of which one and only one entry MUST be of type [NcTouchpointNmos](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#nctouchpointnmos) where the `resourceType` field MUST be set to "receiver" and the `id` field MUST be set to the associated IS-04 receiver UUID.
The `touchpoints` property of any [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor) MUST have one or more touchpoints of which one and only one entry MUST be of type [NcTouchpointNmos](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#nctouchpointnmos) where the `resourceType` field MUST be set to "receiver" and the `id` field MUST be set to the associated IS-04 receiver UUID.

Receiver monitors MUST maintain a 1 to 1 relationship between its role and the receiver resource it monitors (expressed via the `touchpoints` property) for the lifetime of the IS-04 receiver resource.

Expand All @@ -309,17 +357,17 @@ Touchpoints example:

### NcWorker inheritance

[NcStatusMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncstatusmonitor) inherits from the [NcWorker](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncworker) model.
[NcStatusMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncstatusmonitor) inherits from the [NcWorker](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncworker) model.

Since [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor) inherits from the [NcStatusMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncstatusmonitor) model then it also indirectly inherits from the [NcWorker](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncworker) model.
Since [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor) inherits from the [NcStatusMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncstatusmonitor) model then it also indirectly inherits from the [NcWorker](https://specs.amwa.tv/ms-05-02/latest/docs/Framework.html#ncworker) model.

Receiver monitors MUST always have the `enabled` property set to `true`.
In the case of Receiver monitors, the `enabled` property has no operational meaning and MUST NOT be interpreted in any way.

Receiver monitors MUST NOT allow changes to the `enabled` property and instead MUST return `InvalidRequest` to Set method invocations for this property.
Devices MAY choose to not allow changes to the `enabled` property and instead return `InvalidRequest` to Set method invocations for this property.

## Controller

Controllers MUST be capable to discover receiver monitor objects (objects which implement [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncreceivermonitor) directly or derive a [vendor specific variant from NcReceiverMonitor](https://specs.amwa.tv/ms-05-02/latest/docs/Introduction.html)) inside a device model and indicate them to the User. All blocks inside an MS-05-02 device allow [searching for members by their class id](https://specs.amwa.tv/ms-05-02/latest/docs/Blocks.html#search-methods).
Controllers MUST be capable to discover receiver monitor objects (objects which implement [NcReceiverMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/main/monitoring/#ncreceivermonitor) directly or derive a [vendor specific variant from NcReceiverMonitor](https://specs.amwa.tv/ms-05-02/latest/docs/Introduction.html)) inside a device model and indicate them to the User. All blocks inside an MS-05-02 device allow [searching for members by their class id](https://specs.amwa.tv/ms-05-02/latest/docs/Blocks.html#search-methods).

Controllers MUST be capable to find the associated IS-04 receiver identity for each receiver monitor by using the [touchpoints](#touchpoints-and-is-04-receivers) and indicate this relationship to the User.

Expand Down