Documentation changes (#16)

Documentation changes after the feedback from other E&T group members was received

Author: cristian-recoseanu

README.md

@@ -1,14 +1,17 @@
 # [Work In Progress] AMWA IS-07 NMOS Event & Tally Specification
 
-This repository contains details of this AMWA Specification, including core models, transports, event types and a late joiners API.
+This repository contains details of this AMWA Specification, including message types, event types, core models, transports, rest api and measurement units guidelines.
 
 ## Getting started
 
 Readers are advised to be familiar with:
+
 * The JT-NM Reference Architecture (http://jt-nm.org/)
 * The [overview of Networked Media Open Specifications](https://amwa-tv.github.io/nmos)
+* The [NMOS Discovery and Registration Specification](https://github.com/AMWA-TV/nmos-discovery-registration) (IS-04)
+* The [NMOS Connection Management Specification](https://github.com/AMWA-TV/nmos-device-connection-management) (IS-05)
 
-Readers should read the [documentation](docs/) in this repository.
+Readers should read the [documentation](docs/) in this repository, and the [APIs](APIs/), which are written in RAML.
 
 HTML renders of this repo will be made available through [GitHub Pages](https://amwa-tv.github.io/nmos-event-tally)
 
@@ -18,8 +21,11 @@ It is recommended that the tagged releases are used as a reference for developme
 
 Each version of the specification is available under a v<#MAJOR>.<#MINOR> tag such as 'v1.0'. Once a specification has been released, any updates to its documentation and schemas which do not modify the specification will be made available via a v<#MAJOR>.<#MINOR>.<#UPDATE> tag such as 'v1.0.1'.
 
+## Contents
 
 * README.md -- This file
-* [docs](docs/) -- Documentation
+* [docs/](docs/) -- Documentation
+* [APIs/](APIs/) -- API descriptions
+* [examples/](examples/) -- Example JSON requests, responses and event messages
 * [LICENSE](LICENSE) -- Licenses for software and text documents
 * [NOTICE](NOTICE) -- Disclaimer

docs/1.0. Overview.md

@@ -12,11 +12,11 @@ The purpose of the Event & Tally specification is to provide a mechanism by whic
 
 The specification is split into the following sections:
 
-* [Message types](2.0.%20Message_types.md)
-* [Event types](3.0.%20Event_types.md)
-* [Core models](4.0.%20Core_models.md)
+* [Message types](2.0.%20Message%20types.md)
+* [Event types](3.0.%20Event%20types.md)
+* [Core models](4.0.%20Core%20models.md)
 * [Transports](5.0.%20Transports.md)
   * [MQTT](5.1.%20Transport%20-%20MQTT.md)
   * [Websocket](5.2.%20Transport%20-%20Websocket.md)  
-* [Event & Tally REST API](6.0.%20Event_and_tally_rest_api.md)
-* [Measurement units guidelines](7.0.%20Measurement_units_guidelines.md)
+* [Event & Tally REST API](6.0.%20Event%20and%20tally%20rest%20api.md)
+* [Measurement units guidelines](7.0.%20Measurement%20units%20guidelines.md)

docs/2.0. Message_types.md docs/2.0. Message types.mddocs/2.0. Message_types.md renamed to docs/2.0. Message types.md

@@ -19,9 +19,11 @@ These are the supported message types:
 * connection_lost (only used by MQTT connections)
 * health (only used by WebSocket connections)
 
+For clarity, all MQTT message types are sent using the same MQTT topic defined through the transport parameter `broker_topic`.
+
 ### 1.1. The state message type
 
-The `state` message type will always be sent when the emitter changes state and issues a new event or in a response to a query state request to the [Event & Tally REST API](6.0.%20Event_and_tally_rest_api.md).  
+The `state` message type will always be sent when the emitter changes state and issues a new event or in a response to a query state request to the [Event & Tally REST API](6.0.%20Event%20and%20tally%20rest%20api.md).  
 These will be the predominant message types being sent in an Event & Tally system.
 
 The message structure shall have the following items:
@@ -38,7 +40,8 @@ Message structure
 {
     "identity":
     {
-        "source_id": "6cbd0441-7882-44cd-9557-842243a0d618"
+        "source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
+        "flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
     },
     "event_type": "boolean",
     "timing":
@@ -63,7 +66,9 @@ The `"action_timestamp"` represents the timestamp at which an event should be tr
 
 The `"action_timestamp"` is not intended to be associated with delays of more than a few seconds, not for example to allow events scheduled in the future, it allows synchronisation of events in complex workflows.
 
-The payload depends on the associated event_type (see [Event types](3.0.%20Event_types.md)).
+The payload depends on the associated event_type (see [Event types](3.0.%20Event%20types.md)).
+
+The `flow_id` will _NOT_ be included in the response to a rest apy query state because the state is held by the source which has no dependency on a flow. It will, however, appear when being sent through one of the two specified transports because it will pass from the source through a flow and out on the network through the sender.
 
 ### 1.2. The reboot message type
 
@@ -80,7 +85,8 @@ Message structure
 ```json
 {
   "identity":{
-    "source_id": "6cbd0441-7882-44cd-9557-842243a0d618"
+    "source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
+    "flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
   },
   "timing":{
     "creation_timestamp": "1531680501:280709600"
@@ -106,7 +112,8 @@ Message structure
 ```json
 {
   "identity":{
-    "source_id": "6cbd0441-7882-44cd-9557-842243a0d618"
+    "source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
+    "flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
   },
   "timing":{
     "creation_timestamp": "1531680501:280709600"
@@ -134,17 +141,23 @@ Message structure
 ```json
 {
   "identity":{
-    "source_id": "6cbd0441-7882-44cd-9557-842243a0d618"
+    "source_id": "6cbd0441-7882-44cd-9557-842243a0d618",
+    "flow_id": "ff455cf3-fb17-448b-8f4c-e6c0e294f5ed"
   },
   "message_type": "connection_lost"
 }
 ```
 
+For more information about `MQTT WILL` messages consult the MQTT specification and other MQTT materials:
+
+* http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/csprd02/mqtt-v3.1.1-csprd02.html
+* https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament
+
 ### 1.5. The health message
 
 The `health` message will only be sent on a WebSocket connection as a response to a `health` command see [Websocket transport](5.2.%20Transport%20-%20Websocket.md).
 
-The recommendation for receivers is to detect missing `health` responses (no `health` response is sent back within 5 seconds) and after 2 consecutive missed `health` responses  either attempt to reconnect to the WebSocket and re-initialise the subscriptions list or park the subscription and update the IS-04 model in the registry.
+The recommendation for receivers is to detect missing `health` responses (no `health` response is sent back within 5 seconds) and after a 12 seconds timeout (two consecutive missed `health` responses plus 2 seconds to allow for latencies) either attempt to reconnect to the WebSocket and re-initialise the subscriptions list or park the subscription and update the IS-04 model in the registry.
 
 The message structure shall have the following items:
 

docs/3.0. Event_types.md docs/3.0. Event types.mddocs/3.0. Event_types.md renamed to docs/3.0. Event types.md

@@ -16,7 +16,7 @@ These are the supported event types:
 * enum
 * object (out of scope for version 1.0 of this specification)
 
-The types are identified by the corresponding values in the event_type field in an event message and the NMOS source. When additional restrictions are applied to an event type, the *type definition object* will be provided using the Event & Tally REST API (see [Event & Tally REST API](6.0.%20Event_and_tally_rest_api.md)). The type definition object will always define the type of the `value` field and can define restrictions on the value.
+The types are identified by the corresponding values in the event_type field in an event message and the NMOS source. When additional restrictions are applied to an event type, the *type definition object* will be provided using the Event & Tally REST API (see [Event & Tally REST API](6.0.%20Event%20and%20tally%20rest%20api.md)). The type definition object will always define the type of the `value` field and can define restrictions on the value.
 
 ## 2. Base types
 
@@ -143,7 +143,7 @@ In the case where a unit of measure is specified for the number type, the event
 
 The definition of the units of measure is out of scope of this specification but the SI system of units is highly recommended.
 
-The recommended strategy for naming measurement units can be read in the [Measurement units guidelines](7.0.%20Measurement_units_guidelines.md) section.
+The recommended strategy for naming measurement units can be read in the [Measurement units guidelines](7.0.%20Measurement%20units%20guidelines.md) section.
 
 #### _Example_:
 
@@ -291,7 +291,7 @@ _Type definition_:
 An on/off switch with a bit of added metadata.
 
 _Event Type_:
-`bool/enum/OnOff`
+`boolean/enum/OnOff`
 
 _Payload_:
 
@@ -386,16 +386,21 @@ Sources `"event_type"` field always needs to have an exact specific event type (
 
 Receivers `"event_types"` field can have a specific event type or may have a derived partial event type using a wildcard (`*`).
 
-A wildcard (`*`) can only be used at the end of an event_type definition.
+A wildcard (`*`) must replace a whole word and can only be used at the end of an event_type definition.
 
-More details about NMOS resources in the section [Core models](4.0.%20Core_models.md).
+More details about NMOS resources in the section [Core models](4.0.%20Core%20models.md).
 
 The wildcard allows a smart receiver to advertise a wider capability with a specific category above. This is useful information when building a user interface which handles connection management but also matches capabilities between senders and receivers.
 
 An example of a receiver which may use a wildcard could be a smart software gauge which can auto-calibrate. This could advertise its capability as `number/*`.
 
 Another example could be for a temperature receiver which supports any measurement unit. This could advertise its capability as `number/Temperature/*`.
 
-Finally a temperature receiver which only supports degrees Celsius would advertise its capability as `number/Temperature/C`.
+A third example could be that of a temperature receiver which only supports degrees Celsius. It would advertise its capability as `number/Temperature/C`.
+
+The following examples are invalid uses for a wildcard:
+
+* `number/Tempera*`
+* `number/*/C`
 
 ![Event types capability management](images/event-types-capability-management.png)