Networked Media Open Specifications

AMWA BCP-008-02: NMOS Sender Status

Index↑

NMOS logo

Introduction

Alarms are context and workflow specific, and in general determined by a higher level monitoring system, with different calculations for different users. For example, a hardware error status (such as link down) from a device not actively being used would not cause an alarm to a live workflow operator, but the same status condition would escalate an alarm to a maintenance engineer who needs to prepare that device for future operational use.

This BCP document does not attempt to define alarms but instead it describes the expectations, behavior and conformance requirements for Devices with stream Senders in terms of status monitoring.

The overall status concepts defined in this document are intended to make it easy to calculate a typical operator alarm condition. In simple systems with no higher level monitoring system, the overallStatus can be used directly as a simple pre-defined non-configurable operator alarm condition, without in any way limiting a monitoring system’s ability to take the same status values and calculate one or more different alarm conditions appropriate to other desired workflows or users.

This document relies on previous familiarity with the following existing documents:

The technical models referenced in this document are fully published in the Monitoring NMOS Control Feature Set.

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

Use of Normative Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

Definitions

The NMOS terms ‘Controller’, ‘Node’, ‘Source’, ‘Flow’, ‘Sender’, ‘Receiver’ are used as defined in the NMOS Glossary.

Sender activation - An IS-05 activation which results in the Sender having the required transport parameters and a master_enable status of true. This can happen for an idle sender but also when the sender is already activated and a client is applying new transport parameters.

Prerequisites

Devices in conformance to this BCP MUST comply with NMOS Control Framework for generating device models.
Devices in conformance to this BCP MUST comply with NMOS Control Protocol to expose device models via a standard API with full support for notifications.
Devices in conformance to this BCP MUST comply with NMOS Discovery and Registration create, describe and register Nodes, Devices and Sender resources.
Devices in conformance to this BCP MUST comply with NMOS Device Connection Management to perform connection management actions against Sender resources.

Sender monitoring

The technical model describing the monitoring requirements for a sender is NcSenderMonitor.

This model inherits from the baseline status monitoring model NcStatusMonitor.

Sender monitors MUST implement NcSenderMonitor directly or derive a vendor specific variant from NcSenderMonitor which MAY add more statuses, properties and methods but MUST still comply with the requirements set out in this specification.

Sender monitoring model
Sender monitoring model

Sender status reporting delay

The statusReportingDelay property allows clients to customize the reporting delay used by devices to report statuses. Devices are RECOMMENDED to use 3s as the default value when the sender monitor object is first constructed and MUST allow it to be changed to values within the device’s published constraints. Devices MUST allow setting the statusReportingDelay property to a value of 3s. All domain specific statuses are impacted by the configured statusReportingDelay as follows:

Status reporting delay
Status reporting delay example

Sender overall status

The purpose of the overallStatus is to abstract and combine the specific domain statuses of a monitor into a single status which can be more easily observed and displayed by a simple client.

Note: The overallStatus might remain the same even when specific domain statuses change but the overallStatusMessage might change because a different combination of internal states is causing the current overallStatus value.

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

Overall status mapping examples
Overall status mapping examples

Sender connectivity

NcSenderMonitor includes the following specific items covering the connectivity domain:

Sender connectivity
Sender connectivity (explanatory notes are informative)

The linkStatus property allows devices to expose the health of all the physical links associated with the sender.

Devices MUST report the linkStatus as follows:

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

Devices are RECOMMENDED to publish information about which interfaces are down in the linkStatusMessage.

Example:

NIC1, NIC2 are down

Transmission status

The transmissionStatus property allows devices to expose the health of the sender with regards to transmitting a stream successfully. Other connection problems like 802.1x authorization, DHCP and other causes are also reflected in the transmissionStatus.

Devices MUST report the transmissionStatus as follows:

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

Transmission error counters

The sender monitoring model provides means of gathering metrics around transmission errors. These are not statuses but instead enable further analysis when link status or transmission status indicate problems (are PartiallyHealthy or Unhealthy).

Devices with capabilities to detect transmission errors MUST implement the following methods:

The autoResetErrorCounters property allows clients to configure if the error counters automatically reset with each Sender activation (by default devices are RECOMMENDED to have this enabled). If this is enabled, senders MUST reset all error counters to 0 after each activation. Devices MUST allow setting the autoResetErrorCounters property to a value of true and MAY allow setting the property to false.

Devices that do not have the capability to detect transmission errors MUST:

Sender synchronization

NcSenderMonitor includes the following specific items covering the synchronization domain:

Sender synchronization
Sender synchronization (explanatory notes are informative)

External synchronization status

The externalSynchronizationStatus property allows devices to expose the health of the sender with regards to its time synchronization mechanisms.

Devices MUST report the externalSynchronizationStatus as follows:

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

Devices are RECOMMENDED to publish in the externalSynchronizationStatusMessage property information about the previous synchronization source and originating interface as well as the current synchronization source and its originating interface.

Example:

previousSync:baseband from SDI1, currentSync: 0x00:0c:ec:ff:fe:0a:2b:a1 from NIC1

or

previousSync:0x70:35:09:ff:fe:c7:da:00 from NIC1, currentSync: 0x00:0c:ec:ff:fe:0a:2b:a1 from NIC2

Synchronization source change

When devices intend to use external synchronization they MUST publish the synchronization source id currently being used in the synchronizationSourceId property and update the externalSynchronizationStatus property whenever it changes, using null if a synchronization source cannot be discovered. Devices which are not intending to use external synchronization MUST populate this property with internal or their own id if they themselves are the synchronization source (e.g. the device is a grandmaster).

When devices suffer a synchronization source change the externalSynchronizationStatus property MUST temporarily transition to a PartiallyUnhealthy state. It can then return to a different state if the operating conditions match it more closely (returning to a healthier state MUST respect the requirements in the status reporting delay section).

Devices MUST report any synchronization source change as an increment to the synchronizationSourceChanges counter property.

Devices MUST be able to reset the synchronizationSourceChanges counter property in the following two ways:

When devices do not use external synchronization they MUST:

Sender essence validation

NcSenderMonitor includes the following specific items covering the essence validation domain:

Sender essence validation
Sender essence validation (explanatory notes are informative)

Essence status

The essenceStatus property allows devices to expose the health of the sender with regards to the validity of the essence being transmitted.

Devices MUST report the essenceStatus as follows:

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

Examples:

Unexpected format

Parameter X does not match expectations

Deactivating a sender

A Sender is deactivated after an IS-05 activation results in the Sender master_enable becoming false.

When a sender is being deactivated it MUST cleanly interrupt its transmission by not generating intermediate unhealthy states (PartiallyHealthy or Unhealthy) and instead transition directly and immediately (without being delayed by the statusReportingDelay) to Inactive for the following statuses:

Deactivation transition example
Deactivation transition example

Touchpoints and IS-04 senders

Sender monitors make use of the Touchpoints mechanism inherited from NcObject to attach to the correct sender identity.

The touchpoints property of any NcSenderMonitor MUST have one or more touchpoints of which one and only one entry MUST be of type NcTouchpointNmos where the resourceType field MUST be set to “sender” and the id field MUST be set to the associated IS-04 sender UUID.

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

Touchpoints example:

[
  {
    "contextNamespace": "x-nmos",
    "resource": {
      "resourceType": "sender",
      "id": "9bfe1101-5513-45fa-ae3b-7e668e317bd5"
    }
  }
]

NcWorker inheritance

NcStatusMonitor inherits from the NcWorker model.

Since NcSenderMonitor inherits from the NcStatusMonitor model then it also indirectly inherits from the NcWorker model.

Sender monitors MUST always have the enabled property set to true.

Sender monitors MUST NOT allow changes to the enabled property and instead MUST return InvalidRequest to Set method invocations for this property.

Index↑

Documentation built at 09:51:58 CST on 2024-12-12.
(c) AMWA 2024. RAML/JSON licensed under Apache 2.0. Documentation licensed under CC BY-ND 4.0.