Add draft content

README.md

@@ -1,4 +1,4 @@
-# \[Work In Progress\] AMWA NMOS Template Specification
+# \[Work In Progress\] AMWA BCP-00X-0X: Receiver status monitoring
 
 [![Lint Status](https://github.com/AMWA-TV/bcp-template/workflows/Lint/badge.svg)](https://github.com/AMWA-TV/bcp-template/actions?query=workflow%3ALint)
 [![Render Status](https://github.com/AMWA-TV/bcp-template/workflows/Render/badge.svg)](https://github.com/AMWA-TV/bcp-template/actions?query=workflow%3ARender)
@@ -9,19 +9,18 @@ This repository holds the source for this Specification, part of the family of [
 
 ### What does it do?
 
-- It provides a template for AMWA NMOS Interface Specifcations.
+- It provides a standard way of monitoring the statuses of Receivers
 
 ### Why does it matter?
 
-- It helps ensure consistency between NMOS Specifications.
-- It helps us test our continuous integration.
+- It offers standard models for minimum status reporting
+- It provides guidance, sets out expectations and requirements for receiver status monitoring
 
 ### How does it work?
 
-- It contains examples of [documentation](docs/), and [examples](examples/)
-- It provides a style guide and other advice for specification authors
-  - This includes how to configure the repo for automatic linting and rendering to `specs.amwa.tv`
-- Select `AMWA-TV/bcp-template` as the template when creating the new repo.
+- It documents the standard models Devices have to use in order to offer receiver status monitoring
+- It lists the prerequisites and dependencies in terms of NMOS specifications
+- It describes the status monitoring domains along with expectations, behaviour and conformance requirements
 
 <!-- INTRO-END -->
 

docs/Overview.md

@@ -1,4 +1,4 @@
-# AMWA NMOS Best Common Practice Template: Overview
+# AMWA BCP-00X-0X: Receiver status monitoring
 {:.no_toc}
 
 * A markdown unordered list which will be replaced with the ToC, excluding the "Contents header" from above
@@ -8,50 +8,174 @@ _(c) AMWA 2021, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_
 
 ![NMOS logo](images/NMOS-logo.png)
 
-> ## Instructions
->
-> **Delete this section after creating a new repo from this template.**
->
->Use this template repo to create a new AMWA NMOS Best Common Practice repo.
->
-> Add your content as (GitHub Flavoured) Markdown documents.
->
-> - For consistency with other specifications, keep this `Overview.md` but remove these Instructions.
->
-> Put diagrams (ideally PNG with encapsulated draw.io source) in the `images/` sub-directory.
->
-> Follow the [Style Guide](Style%20Guide.md).
->
-> Make a bulleted list of documents in `README.md` in this directory.
-> 
-> Set the repo name used to get the Lint and Render status in the top-level `README.md` (four changes needed).
->
-> Set the value of `amwa_id` in `.render/_config.yml` to the AMWA-assigned ID.
-
 ## Introduction
 
-> Provide an overview of the Specification.
+The aim of this BCP document is to describe the expectations, behaviour and conformance requirements for Devices with stream Receivers in terms of status monitoring.
+
+This document relies on previous familiarity with the following existing documents:
+
+* [NMOS Control Framework](https://specs.amwa.tv/ms-05-02/)
+* [NMOS Control Protocol](https://specs.amwa.tv/is-12/)
+* [NMOS Discovery and Registration](https://specs.amwa.tv/is-04/)
+* [NMOS Device Connection Management](https://specs.amwa.tv/is-05/)
 
-Familiarity with the [JT-NM Reference Architecture](https://jt-nm.org/reference-architecture/) is assumed.
+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/).
 
-See also the [NMOS Technical Overview](https://specs.amwa.tv/nmos/main/docs/Technical_Overview.html).
+The following domains are covered in terms of status monitoring with specific sections for each:
 
+* [Receiver connectivity](#receiver-connectivity)
+* [Receiver synchronization](#receiver-synchronization)
+* [Receiver stream validation](#receiver-stream-validation)
 
 ## 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][RFC-2119].
+and "OPTIONAL" in this document are to be interpreted as described in [RFC-2119](https://datatracker.ietf.org/doc/html/rfc2119).
 
 ## Definitions
 
-The NMOS terms 'Node', ... are used as defined in the [NMOS Glossary](https://specs.amwa.tv/nmos/main/docs/Glossary.html).
+The NMOS terms 'Controller', 'Node', 'Source', 'Flow', 'Sender', 'Receiver' are used as defined in the [NMOS Glossary](https://specs.amwa.tv/nmos/main/docs/Glossary.html).
+
+## Prerequisites
+
+Devices in conformance to this BCP MUST use [NMOS Control Framework](https://specs.amwa.tv/ms-05-02/) for generating device models.  
+Devices in conformance to this BCP MUST use [NMOS Control Protocol](https://specs.amwa.tv/is-12/) to expose device models via a standard API with full support for notifications.  
+Devices in conformance to this BCP MUST use [NMOS Discovery and Registration](https://specs.amwa.tv/is-04/) to create and register Nodes, Devices and Receiver resources.  
+Devices in conformance to this BCP MUST use [NMOS Device Connection Management](https://specs.amwa.tv/is-05/) to perform connection management actions against Receiver resources.  
+
+## Receiver overall status
+
+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).
+
+This model MUST inherit from the baseline status monitoring model [NcStatusMonitor](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-status-reporting/monitoring/#ncstatusmonitor)
+
+The purpose of the overall status 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. A good practice is to populate the status message property with details of the worst status causing the current value of the overall status.
+
+`Note`: The overall status might remain the same even when specific domain statuses change but the overall status message might change because a different combination of internal states is causing the current overall status value.
+
+The following recommendations are in place when mapping specific domain statuses in the combined overall status:
+
+* Inactive/Not used states are neutral and do no affect the overall status
+* The overall status takes the worst state across the different domains (if one status is PartiallyHealthy (or equivalent) and another is Unhealthy (or equivalent) then the overall status would be Unhealthy)
+* The overall status is Healthy only when all domain statuses are either Healthy or a neutral state (Inactive/Not used)
+
+The proposed models are minimal and they can be implemented as is or derived in [vendor specific variants](https://specs.amwa.tv/ms-05-02/latest/docs/Introduction.html) which can add more statuses, properties and methods.
+
+| ![Receiver monitoring model](images/receiver-model-minimal.png) |
+|:--:|
+| _**Receiver monitoring model**_ |
+
+## Receiver connectivity
+
+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).  
+This includes the following specific items which cover the connectivity domain:
+
+* Properties
+  * linkStatus
+  * linkStatusMessage
+  * connectionStatus
+  * connectionStatusMessage
+* Methods
+  * GetLostPackets
+  * GetLatePackets
+  * ResetPacketCounters
+
+| ![Receiver connectivity](images/receiver-model-connectivity.png) |
+|:--:|
+| _**Receiver connectivity**_ |
+
+### Link status monitoring
+
+Link status monitoring allows devices to expose the health of all the physical links associated with the receiver.
+
+Devices specify if:
+
+* All interfaces are Down (equivalent to an Unhealthy state)
+* Some of the interfaces are Down (equivalent to a PartiallyHealthy state)
+* All of the interfaces are Up (equivalent to a Healthy state)
+
+The link status message is an optional nullable property where devices can offer the reason and further details as to why the current status value was chosen.
+
+### Connection status monitoring
+
+Connection status monitoring allows devices to expose the health of the receiver with regards to receiving stream packets successfully.
+
+`Note`: Other connection problems like 802.1x authorization, DHCP and other causes are also reflected in the connection status.
+
+Devices specify:
+
+* When the receiver is Inactive (is a neutral state)
+* Healthy when the receiver is Active and receiving packets without using any form of loss recovery
+* PartiallyHealthy when the receiver is Active and is receiving packets but some form of loss recovery is being used (e.g. redundant leg recovery or some form of FEC)
+* Unhealthy when the receiver is active and is either not receiving any packets or receiving packets but has unrecoverable errors
+
+The connection status message is an optional nullable property where devices can offer the reason and further details as to why the current status value was chosen.
+
+### 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-monitoring) or [connection status](#connection-status-monitoring) indicate problems.
+
+The feature is expressed with the following methods:
+
+* GetLostPackets - returns a numeric value of the lost packets
+* GetLatePackets - returns a numeric value of the late packets
+* ResetPacketCounters - allows a client application to reset both the Lost and Late packet counters to 0.
+
+## Receiver synchronization
+
+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).  
+This includes the following specific items which cover the synchronization domain:
+
+* Properties
+  * synchronizationStatus
+  * synchronizationStatusMessage
+  * grandMasterClockId
+
+| ![Receiver synchronization](images/receiver-model-synchronization.png) |
+|:--:|
+| _**Receiver synchronization**_ |
+
+### Synchronization status monitoring
+
+Synchronization status monitoring allows devices to expose the health of the receiver with regards to its time synchronization mechanisms.
+
+Devices specify:
+
+* When the receiver is not using external synchronization (is a neutral state)
+* When the receiver is baseband locked (is equivalent to a Healthy state)
+* When the receiver is partially baseband locked (is equivalent to a PartiallyHealthy state)
+* When the receiver is network locked (is equivalent to a Healthy state)
+* When the receiver is partially network locked (is equivalent to a PartiallyHealthy state)
+* When the receiver is not locked (is equivalent to an Unhealthy state)
+
+The synchronization status message is an optional nullable property where devices can offer the reason and further details as to why the current status value was chosen.
+
+### Grandmaster change
+
+When devices are configured to use network synchronization they MUST publish the grandmaster clock id currently being used and update the property whenever it changes. For devices which are not using network synchronization this property MUST be set to `null`.
+
+## Receiver stream validation
+
+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).  
+This includes the following specific items which cover the stream validation domain:
+
+* Properties
+  * streamStatus
+  * streamStatusMessage
+
+| ![Receiver stream validation](images/receiver-model-stream-validation.png) |
+|:--:|
+| _**Receiver stream validation**_ |
 
-> List as appropriate
+### Stream status monitoring
 
-This specification also defines the following terms.
+Stream status monitoring allows devices to expose the health of the receiver with regards to the validity of the stream being received.
 
-### Example Term
+Devices specify:
 
-Example definition
+* When the receiver is Inactive (is a neutral state)
+* Healthy when the receiver is Active and can decode the incoming stream without any 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
 
-[RFC-2119]: https://tools.ietf.org/html/rfc2119 "Key words for use in RFCs"
+The stream status message is an optional nullable property where devices can offer the reason and further details as to why the current status value was chosen.

docs/README.md

@@ -21,8 +21,3 @@ See https://github.com/AMWA-TV/nmos-template/docs/README.md for an example of th
 ### Introduction
 
 - [Overview](Overview.md)
-- [Style Guide](Style%20Guide.md)
-
-### Miscellaneous
-
-- [Further Info](Further%20Info.md)