Merge pull request #17 from AMWA-TV/publish-changes

Further clarifications / language tweaks and adding autoResetSynchronizationSourceChanges property

README.md

@@ -22,6 +22,20 @@ This repository holds the source for this Specification, part of the family of [
 - It lists the prerequisites and dependencies in terms of NMOS specifications
 - It describes the status monitoring domains along with expectations, behaviour and conformance requirements
 
+### Where to start?
+
+To quickly start your journey an implementation guide is available for [NMOS Control](https://specs.amwa.tv/info-006/).  
+An open source media node framework is available in the form of [nmos-cpp](https://github.com/sony/nmos-cpp).  
+An example mock application is available in the form of the [NMOS Device Control Mock Application](https://github.com/AMWA-TV/nmos-device-control-mock).  
+A testing tool is available in the form of the [NMOS API Testing Tool](https://github.com/AMWA-TV/nmos-testing).
+
+This specification relies on familiarity with the following existing specifications:
+
+- [MS-05-02: NMOS Control Framework](https://specs.amwa.tv/ms-05-02/)
+- [IS-12: NMOS Control Protocol](https://specs.amwa.tv/is-12/)
+- [IS-04: NMOS Discovery and Registration](https://specs.amwa.tv/is-04/)
+- [IS-05: NMOS Device Connection Management](https://specs.amwa.tv/is-05/)
+
 <!-- INTRO-END -->
 
 ## Getting started

docs/Overview.md

@@ -63,9 +63,9 @@ Receiver monitors MUST implement [NcReceiverMonitor](https://specs.amwa.tv/nmos-
 
 ### Receiver 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 receiver 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:
+The `statusReportingDelay` property allows clients to customize the reporting delay used by devices to report statuses. Devices MUST use 3s as the default value when the receiver 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:
 
-* A receiver is expected to go through a period of instability upon activation. Therefore, on Receiver activation domain specific statuses offering an `Inactive` option MUST transition immediately to the Healthy state. Furthermore, after activation they MUST delay the reporting of non Healthy states for the duration specified by `statusReportingDelay`, as long as the Receiver isn't being [deactivated](#deactivating-a-receiver), and then transition to any other appropriate state.
+* A receiver is expected to go through a period of instability upon activation. Therefore, on Receiver activation domain specific statuses offering an `Inactive` option MUST transition immediately to the Healthy state. Furthermore, after activation, as long as the Receiver isn’t being [deactivated](#deactivating-a-receiver), it MUST delay the reporting of non Healthy states for the duration specified by `statusReportingDelay`, and then transition to any other appropriate state.
 
 * Once any Receiver activation `statusReportingDelay` has elapsed and the Receiver isn't being [deactivated](#deactivating-a-receiver), all domain specific statuses MUST delay the transition to a more healthy state by the configured `statusReportingDelay` value and MUST only make the transition if the healthier state is maintained for the duration. All domain specific statuses MUST make a transition to a less healthy state without delay.
 
@@ -77,13 +77,13 @@ The `statusReportingDelay` property allows clients to customize the reporting de
 
 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.
+`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.
 
 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
-* When the Receiver is Active the overallStatus takes the worst state across the different domains (if one status is PartiallyHealthy (or equivalent) and another is Unhealthy (or equivalent) then the overallStatus would be Unhealthy)
-* The overallStatus is Healthy only when all domain statuses are either Healthy or a neutral state (e.g. Not used)
+* When the Receiver is Active the overallStatus takes the least healthy state of all domain statuses (if one status is PartiallyHealthy (or equivalent) and another is Unhealthy (or equivalent) then the overallStatus would be Unhealthy)
+* The overallStatus is Healthy only when all domain statuses are either Healthy or a neutral state (e.g. Not used, Inactive)
 
 | ![Overall status mapping examples](images/overall-status.png) |
 |:--:|
@@ -145,15 +145,15 @@ The connectionStatusMessage is a nullable property where devices MAY offer the r
 
 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).
 
-Lost packets are packets that never arrived. Late packets are packets that arrived but arrived too late to be usable by the essence reconstruction process without increasing the link offset delay.
+Lost packets are packets that never arrived. Late packets are packets that arrived but arrived too late to be usable by presentation time.
 
 Devices with capabilities to detect late or lost packets MUST implement the following methods:
 
 * GetLostPacketCounters - returns a non empty collection of counters which hold the name, description and numeric value of the counter (this allows more capable devices to report lost packets across different interfaces).
 * GetLatePacketCounters - returns a non empty collection of counters which hold the name, description and numeric value of the counter (this allows more capable devices to report late packets across different interfaces).
 * ResetPacketCounters - resets both the Lost and Late packet counters to 0.
 
-The `autoResetPacketCounters` property allows clients to configure if the packet counters automatically reset with each Receiver activation (by default devices are RECOMMENDED to have this enabled). If this is enabled, receivers MUST reset all packet counters to 0 after each activation. Devices MUST allow setting the `autoResetPacketCounters` property to a value of `true` and MAY allow setting the property to `false`.
+The `autoResetPacketCounters` property allows clients to configure if the packet counters automatically reset with each Receiver activation (by default devices MUST have this enabled). If this is enabled, receivers MUST reset all packet counters to 0 after each activation. Devices MUST allow setting the `autoResetPacketCounters` property to a value of `true` and MAY allow setting the property to `false`. This supports use cases where users do not want to clear counters when making a connection.
 
 For implementations which cannot measure individual late packets the late counters MUST at the very least increment every time the presentation is affected due to late packet arrival.
 
@@ -182,7 +182,7 @@ When devices do not have the capability to detect lost or late packets they MUST
 
 #### External synchronization status
 
-The externalSynchronizationStatus property allows devices to expose the health of the receiver with regards to its time synchronization mechanisms.
+The externalSynchronizationStatus property allows devices to expose the health of the receiver with regards to its synchronization mechanisms.
 
 Devices MUST report the externalSynchronizationStatus as follows:
 
@@ -220,6 +220,8 @@ Devices MUST be able to reset the `synchronizationSourceChanges` counter propert
 * When a receiver activation occurs
 * When a client invokes the `ResetSynchronizationSourceChanges` method
 
+The `autoResetSynchronizationSourceChanges` property allows clients to configure if synchronization source changes automatically reset with each Receiver activation (by default devices MUST have this enabled). If this is enabled, receivers MUST reset the property to 0 after each activation. Devices MUST allow setting the `autoResetSynchronizationSourceChanges` property to a value of `true` and MAY allow setting the property to `false`. This supports use cases where users do not want to reset automatically after each activation.
+
 When devices do not use external synchronization they MUST:
 
 * Implement the synchronizationSourceId property and set its value to `internal`