Clarify the behaviour of auto parameters, remove the restriction on a…

…dittional transport parameters, provided guidance on parameters exposed for different device support, add examples of uninitialised state Clarify the behaviour of auto parameters, remove the restriction on adittional transport parameters, provided guidance on parameters exposed for different device support, add examples of uninitialised state
AMWA-TV · Jul 11, 2017 · e6cd9a9 · e6cd9a9
1 parent e4f3ab9
commit e6cd9a9
Show file tree

Hide file tree

Showing 9 changed files with 193 additions and 51 deletions.
diff --git a/APIs/ConnectionAPI.raml b/APIs/ConnectionAPI.raml
@@ -18,7 +18,6 @@ documentation:
   - title: API Structure
     content: |
       The API presents two distinct interfaces. A "bulk" interface for controlling multiple senders/receivers, and a "single" interface to control single devices.
-
 /:
   displayName: Base
   get:
@@ -147,13 +146,13 @@ documentation:
                The first entry is the constraints for the primary leg.
                If SMPTE 2022-7 is not in use only one entry should be present in the outer array.
              responses:
-               200:
+              200:
                  body:
                    type: !include schemas/v1.0-constraints-schema.json
                    examples:
                      SMPTE2022-7: !include ../examples/v1.0-sender-constraints-get-200-2022-7.json
                      No2022-7: !include ../examples/v1.0-sender-constraints-get-200.json
-               404:
+              404:
                  description: Returned when the requested resource does not exist
          /staged:
            get:
@@ -169,7 +168,9 @@ documentation:
                 description: Additionally constrained by the constraints at /constraints
                 body:
                  type: !include schemas/v1.0-sender-response-schema.json
-                 example: !include ../examples/v1.0-sender-get-200.json
+                 examples:
+                   Normal: !include ../examples/v1.0-sender-get-200.json
+                   Uninitialised: !include ../examples/v1.0-sender-get-200-uninit.json
                404:
                  description: Returned when the requested resource does not exist
            patch:
@@ -242,12 +243,21 @@ documentation:
                  example: !include ../examples/v1.0-stage-error.json
          /active:
            get:
-             description: Get active sender parameters
+             description: >
+              Get active sender parameters. On activation all instances of "auto" should be resolved
+              into the actual values that will be used by the sender. For example if a sender has the `destination_ip`
+              parameter set to `auto` in /staged then `destination_ip` in /active should show the multicast IP
+              chosen by the receiver. The parameter will remain set to `auto` in staged, and may be resolve to
+              a different value at each activation. In cases, such as `destination_ip`, where the parameter changing unexpectedly
+              at activation through re-resolution may be un-desirable, care should be taken in implementation
+              to manage this.
              responses:
                200:
                  body:
                    type: !include schemas/v1.0-sender-active-schema.json
-                   example: !include ../examples/v1.0-sender-active-get.json
+                   examples:
+                     Normal: !include ../examples/v1.0-sender-active-get.json
+                     Uninitialised: !include ../examples/v1.0-sender-active-get-uninit.json
                404:
                  description: Returned when the requested resource does not exist
          /transportfile:
@@ -323,6 +333,7 @@ documentation:
                  examples:
                    Normal: !include ../examples/v1.0-receiver-get-200.json
                    Pending: !include ../examples/v1.0-receiver-pending-get-200.json
+                   uninitialised: !include ../examples/v1.0-receiver-get-200-uninit.json
              404:
                description: Returned when the requested resource does not exist
          patch:
@@ -342,6 +353,8 @@ documentation:
             The transport parameters should be updated from the transport file in `data` on every PATCH
             request that includes the `data` field. Even if the value of `data` in the request
             matches the value of `data` currently stored in the API the transport parameters are still re-populated.
+            In the case where the transport file and transport parameters are updated in the same PATCH request
+            transport parameters specified in the request object take precidence over those in the transport file.
             In SMPTE 2022-7 operation element 0 of the `transport_params`
             array shall be the parameters applied to the primary leg, and element 1 the secondary leg.
             There shall only be one element present in `transport_params` when SMPTE 2022-7 is not in use.
@@ -410,11 +423,20 @@ documentation:
                  example: !include ../examples/v1.0-stage-error.json
        /active:
          get:
-           description: Get active receiver parameters
+           description: >
+            Get active receiver parameters. On activation all instances of "auto" should be resolved
+            into the actual values that will be used by the receiver. For example if a receiver has the `interface_ip`
+            parameter set to `auto` in /staged then `interface_ip` in /active should show the IP address of the interface
+            chosen by the receiver. The parameter will remain set to `auto` in staged, and may be resolve to
+            a different value at activation. In cases, such as `interface_ip`, where the parameter changing unexpectedly
+            at activation through re-resolution may be un-desirable, care should be taken in implementation
+            to manage this.
            responses:
              200:
                body:
                  type: !include schemas/v1.0-receiver-active-schema.json
-                 example: !include ../examples/v1.0-receiver-active-get-200.json
+                 examples:
+                   running-state: !include ../examples/v1.0-receiver-active-get-200.json
+                   uninitialised: !include ../examples/v1.0-receiver-active-get-200-uninit.json
              404:
                description: Returned when the requested resource does not exist
diff --git a/APIs/schemas/v1.0_receiver_transport_params_rtp.json b/APIs/schemas/v1.0_receiver_transport_params_rtp.json
@@ -1,19 +1,18 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
-    "description": "Describes RTP Receiver transport parameters. The constraints in this schema are minimum constraints, but may be further constrained at the constraints endpoint.",
+    "description": "Describes RTP Receiver transport parameters. The constraints in this schema are minimum constraints, but may be further constrained at the constraints endpoint. Receivers must support at least the `source_ip`, `interface_ip`, `rtp_enabled` and `destination_port` parameters, and must support the `multicast_ip` parameter is they are capable of multicast operation. Receivers supporting fec and/or rtcp must support parameters prefixed with fec and rtcp respectively.",
     "title": "RTP Receiver Transport Parameters",
     "type": "array",
     "items": {
         "type": "object",
         "title": "Receiver Input",
-        "additionalProperties": false,
         "properties": {
             "source_ip": {
                 "type": [
                     "string",
                     "null"
                 ],
-                "description": "Source IP address of RTP packets in unicast mode, source filter for source specific multicast. A null value indicates that the receiver has not yet been configured.",
+                "description": "Source IP address of RTP packets in unicast mode, source filter for source specific multicast. A null value indicates that the receiver has not yet been configured, or in any-source multicast mode.",
                 "anyOf": [
                     {
                         "format": "ipv4"
@@ -31,7 +30,7 @@
                     "string",
                     "null"
                 ],
-                "description": "IP multicast group address used in multicast operation only. Should be set to null during unicast operation.",
+                "description": "IP multicast group address used in multicast operation only. Should be set to null during unicast operation. A null value indicates the parameter has not been configured, or the receiver is operating in unicast mode.",
                 "anyOf": [
                     {
                         "format": "ipv4"
@@ -46,7 +45,7 @@
             },
             "interface_ip":{
                 "type": "string",
-                "description": "IP address of the network interface the receiver should use. The receiver should provide an enum in the constraints endpoint, which should contain 'auto', and the available interface addresses. If set to auto in multicast mode the receiver should determine which interface to use for itself. The behaviour of auto is undefined in unicast mode, and controllers should supply a specific interface address.",
+                "description": "IP address of the network interface the receiver should use. The receiver should provide an enum in the constraints endpoint, which should contain 'auto', and the available interface addresses. If set to auto in multicast mode the receiver should determine which interface to use for itself, for example by using the routing tables. The behaviour of auto is undefined in unicast mode, and controllers should supply a specific interface address.",
                 "anyOf": [
                     {
                         "format": "ipv4"
@@ -61,11 +60,15 @@
                 "default": "auto"
             },
             "destination_port": {
-                "type": "integer",
-                "description": "destination port for RTP packets",
+                "type": [
+                    "integer",
+                    "string"
+                ],
+                "description": "destination port for RTP packets, auto=5004",
                 "minimum": 1,
                 "maximum": 65535,
-                "default": 5004
+                "pattern": "^auto$",
+                "default": "auto"
             },
             "fec_enabled": {
                 "type": "boolean",
@@ -154,7 +157,7 @@
                     "integer",
                     "string"
                 ],
-                "description": "destination port for RTCP packets (auto = RTP dest_port+1 )",
+                "description": "destination port for RTCP packets (auto = next highest odd port number after RTP source_port)",
                 "minimum": 1,
                 "maximum": 65535,
                 "pattern": "^auto$",
@@ -166,6 +169,5 @@
                 "default": true
             }
         }
-    },
-    "maxItems": 2
+    }
 }
diff --git a/APIs/schemas/v1.0_sender_transport_params_rtp.json b/APIs/schemas/v1.0_sender_transport_params_rtp.json
@@ -1,16 +1,15 @@
 {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "array",
-    "description": "Describes RTP Sender transport parameters. The constraints in this schema are minimum constraints, but may be further constrained at the constraints endpoint.",
+    "description": "Describes RTP Sender transport parameters. The constraints in this schema are minimum constraints, but may be further constrained at the constraints endpoint. As a minimum all senders must support `source_ip`, `destination_ip`, `source_port`, `rtp_enabled` and `destination_port`. Senders supporting fec and/or rtcp must support parameters prefixed with fec and rtcp respectively.",
     "title": "RTP Sender Transport Parameters",
     "items": {
         "type": "object",
         "title": "Sender Output",
-        "additionalProperties": false,
         "properties": {
             "source_ip": {
                 "type": "string",
-                "description": "IP address from which RTP packets will be sent (IP address of interface bound to this output)",
+                "description": "IP address from which RTP packets will be sent (IP address of interface bound to this output). The sender should provide an enum in the constraints endpoint, which should contain 'auto', and the available interface addresses. If the parameter is set to auto the sender should establish for itself which interface it should use, based on routing rules or its own internal configuration.",
                 "anyOf": [
                     {
                         "format": "ipv4"
@@ -26,7 +25,7 @@
             },
             "destination_ip": {
                 "type": "string",
-                "description": "IP address to which RTP packets will be sent",
+                "description": "IP address to which RTP packets will be sent. If auto is set the sender should select a multicast address to send to itself. For example it my implement MADCAP (RFC 2730), ZMAAP, or be allocated address by some other system responsible for co-ordination multicast address use.",
                 "anyOf": [
                     {
                         "format": "ipv4"
@@ -44,18 +43,22 @@
                     "integer",
                     "string"
                 ],
-                "description": "source port for RTP packets",
+                "description": "source port for RTP packets, auto=5004",
                 "minimum": 0,
                 "maximum": 65535,
                 "pattern": "^auto$",
                 "default": "auto"
             },
             "destination_port": {
-                "type": "integer",
-                "description": "destination port for RTP packets",
+                "type": [
+                    "integer",
+                    "string"
+                ],
+                "description": "destination port for RTP packets, auto=5004",
                 "minimum": 1,
                 "maximum": 65535,
-                "default": 5004
+                "pattern": "^auto$",
+                "default": "auto"
             },
             "fec_enabled": {
                 "type": "boolean",
@@ -64,7 +67,7 @@
             },
             "fec_destination_ip": {
                 "type": "string",
-                "description": "May be used if NAT is being used at the destination (auto = rtp_dest_ip)",
+                "description": "May be used if NAT is being used at the destination (auto = rtp_destination_ip)",
                 "anyOf": [
                     {
                         "format": "ipv4"
@@ -115,7 +118,7 @@
                     "integer",
                     "string"
                 ],
-                "description": "destination port for RTP Column FEC packets (auto = RTP dest_port+2)",
+                "description": "destination port for RTP Column FEC packets (auto = RTP destination_port+2)",
                 "minimum": 1,
                 "maximum": 65535,
                 "pattern": "^auto$",
@@ -126,7 +129,7 @@
                     "integer",
                     "string"
                 ],
-                "description": "destination port for RTP Row FEC packets (auto = RTP dest_port+4)",
+                "description": "destination port for RTP Row FEC packets (auto = RTP destination_port+4)",
                 "minimum": 1,
                 "maximum": 65535,
                 "pattern": "^auto$",
@@ -137,7 +140,7 @@
                     "integer",
                     "string"
                 ],
-                "description": "source port for RTP FEC packets (auto = generated by server)",
+                "description": "source port for RTP FEC packets (auto = RTP source_port + 2)",
                 "minimum": 0,
                 "maximum": 65535,
                 "pattern": "^auto$",
@@ -148,19 +151,20 @@
                     "integer",
                     "string"
                 ],
-                "description": "source port for RTP FEC packets (auto = generated by server)",
+                "description": "source port for RTP FEC packets (auto = RTP source_port + 4)",
                 "minimum": 0,
                 "maximum": 65535,
                 "pattern": "^auto$",
                 "default": "auto"
             },
             "rtcp_enabled": {
                 "type": "boolean",
-                "description": "rtcp on/off"
+                "description": "rtcp on/off",
+                "default": false
             },
             "rtcp_destination_ip": {
                 "type": "string",
-                "description": "IP address to which RTCP packets will be sent (auto = same as RTP dest_ip)",
+                "description": "IP address to which RTCP packets will be sent (auto = same as RTP destination_ip)",
                 "anyOf": [
                     {
                         "format": "ipv4"
@@ -179,7 +183,7 @@
                     "integer",
                     "string"
                 ],
-                "description": "destination port for RTCP packets",
+                "description": "destination port for RTCP packets (auto = next highest odd port number after RTP source_port)",
                 "minimum": 1,
                 "maximum": 65535,
                 "pattern": "^auto$",
@@ -190,7 +194,7 @@
                     "integer",
                     "string"
                 ],
-                "description": "source port for RTCP packets. (auto = generated by server)",
+                "description": "source port for RTCP packets. (auto = next highest odd port number after RTP source_port)",
                 "minimum": 0,
                 "maximum": 65535,
                 "pattern": "^auto$",
@@ -202,6 +206,5 @@
                 "default": true
             }
         }
-    },
-    "maxItems": 2
+    }
 }
diff --git a/examples/v1.0-receiver-active-get-200-uninit.json b/examples/v1.0-receiver-active-get-200-uninit.json
@@ -0,0 +1,28 @@
+{
+    "sender_id": null,
+    "master_enable": true,
+    "activation":{
+        "mode": null,
+        "activation_time": null
+    },
+    "transport_file":{
+        "data": null,
+        "type" : null
+    },
+    "transport_params": [{
+	"source_ip": null,
+	"multicast_ip": null,
+        "interface_ip": "172.23.19.35",
+	"destination_port": 5004,
+        "fec_enabled": false,
+        "fec_destination_ip": "172.23.19.35",
+	"fec_type": "XOR",
+	"fec_mode": "1D",
+	"fec1D_destination_port": 5006,
+	"fec2D_destination_port": 5008,
+        "rtcp_enabled": false,
+        "rtcp_destination_ip": "172.23.19.35",
+	"rtcp_destination_port": 5005,
+	"rtp_enabled": true
+    }]
+}
diff --git a/examples/v1.0-receiver-active-get-200.json b/examples/v1.0-receiver-active-get-200.json
@@ -17,10 +17,10 @@
         "fec_enabled": false,
 	"fec_type": "XOR",
 	"fec_mode": "2D",
-	"fec1D_destination_port": "auto",
-	"fec2D_destination_port": "auto",
+	"fec1D_destination_port": 5012,
+	"fec2D_destination_port": 5014,
         "rtcp_enabled": false,
-        "rtcp_destination_ip": "auto",
+        "rtcp_destination_ip": "232.250.98.80",
 	"rtcp_destination_port": 5001,
 	"rtp_enabled": true
     }]

diff --git a/examples/v1.0-receiver-get-200-uninit.json b/examples/v1.0-receiver-get-200-uninit.json
@@ -0,0 +1,28 @@
+{
+    "sender_id": null,
+    "master_enable": true,
+    "activation":{
+        "mode": null,
+        "requested_time": null
+    },
+    "transport_file":{
+        "data": null,
+        "type": null
+    },
+    "transport_params": [{
+	"source_ip": null,
+        "multicast_ip": null,
+        "interface_ip": "auto",
+	"destination_port": "auto",
+        "fec_enabled": false,
+        "fec_destination_ip": "auto",
+	"fec_type": "XOR",
+	"fec_mode": "1D",
+	"fec1D_destination_port": "auto",
+	"fec2D_destination_port": "auto",
+        "rtcp_enabled": false,
+        "rtcp_destination_ip": "auto",
+	"rtcp_destination_port": "auto",
+	"rtp_enabled": true
+    }]
+}