From e6cd9a9745958d0408be68051dfe3c0ddb9e0a59 Mon Sep 17 00:00:00 2001 From: Simon Rankine Date: Wed, 5 Jul 2017 14:43:32 +0100 Subject: [PATCH] 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 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 --- APIs/ConnectionAPI.raml | 38 +++++++++++++---- .../v1.0_receiver_transport_params_rtp.json | 24 ++++++----- .../v1.0_sender_transport_params_rtp.json | 41 ++++++++++--------- .../v1.0-receiver-active-get-200-uninit.json | 28 +++++++++++++ examples/v1.0-receiver-active-get-200.json | 6 +-- examples/v1.0-receiver-get-200-uninit.json | 28 +++++++++++++ examples/v1.0-sender-active-get-uninit.json | 29 +++++++++++++ examples/v1.0-sender-active-get.json | 20 ++++----- examples/v1.0-sender-get-200-uninit.json | 30 ++++++++++++++ 9 files changed, 193 insertions(+), 51 deletions(-) create mode 100644 examples/v1.0-receiver-active-get-200-uninit.json create mode 100644 examples/v1.0-receiver-get-200-uninit.json create mode 100644 examples/v1.0-sender-active-get-uninit.json create mode 100644 examples/v1.0-sender-get-200-uninit.json diff --git a/APIs/ConnectionAPI.raml b/APIs/ConnectionAPI.raml index 81503488..3d924abd 100644 --- 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 index e62af0b9..ac2eeb74 100644 --- 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 index d2d2dc65..c7dc519a 100644 --- 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,7 +151,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 + 4)", "minimum": 0, "maximum": 65535, "pattern": "^auto$", @@ -156,11 +159,12 @@ }, "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 new file mode 100644 index 00000000..af00a4af --- /dev/null +++ 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 index 910962c2..c4872cc0 100644 --- 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 new file mode 100644 index 00000000..7f686b46 --- /dev/null +++ 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 + }] +} diff --git a/examples/v1.0-sender-active-get-uninit.json b/examples/v1.0-sender-active-get-uninit.json new file mode 100644 index 00000000..79d8f45d --- /dev/null +++ b/examples/v1.0-sender-active-get-uninit.json @@ -0,0 +1,29 @@ +{ + "receiver_id": null, + "master_enable": true, + "activation":{ + "mode": null, + "activation_time": null + }, + "transport_params": [{ + "source_ip": "172.29.82.23", + "destination_ip": "232.21.98.4", + "source_port": 5004, + "destination_port": 5004, + "fec_enabled": false, + "fec_destination_ip": "172.29.82.23", + "fec_type": "XOR", + "fec_mode": "1D", + "fec_block_width": 4, + "fec_block_height": 4, + "fec1D_destination_port": 5006, + "fec2D_destination_port": 5008, + "fec1D_source_port": 5006, + "fec2D_source_port": 5008, + "rtcp_enabled": false, + "rtcp_destination_ip": "172.29.82.23", + "rtcp_destination_port": 5005, + "rtcp_source_port": 5005, + "rtp_enabled": false + }] +} diff --git a/examples/v1.0-sender-active-get.json b/examples/v1.0-sender-active-get.json index 23ebb9f6..5ae9f75c 100644 --- a/examples/v1.0-sender-active-get.json +++ b/examples/v1.0-sender-active-get.json @@ -11,15 +11,15 @@ "source_port": 5000, "destination_port": 5000, "fec_enabled": true, - "fec_destination_ip": "auto", + "fec_destination_ip": "172.29.82.95", "fec_type": "XOR", "fec_mode": "2D", "fec_block_width": 50, "fec_block_height": 50, - "fec1D_destination_port": "auto", - "fec2D_destination_port": "auto", - "fec1D_source_port": 5010, - "fec2D_source_port": 5012, + "fec1D_destination_port": 5002, + "fec2D_destination_port": 5004, + "fec1D_source_port": 5002, + "fec2D_source_port": 5004, "rtcp_enabled": true, "rtcp_destination_ip": "172.29.82.24", "rtcp_destination_port": 5008, @@ -31,15 +31,15 @@ "source_port": 5000, "destination_port": 5000, "fec_enabled": true, - "fec_destination_ip": "auto", + "fec_destination_ip": "172.30.82.95", "fec_type": "XOR", "fec_mode": "2D", "fec_block_width": 50, "fec_block_height": 50, - "fec1D_destination_port": "auto", - "fec2D_destination_port": "auto", - "fec1D_source_port": 5010, - "fec2D_source_port": 5012, + "fec1D_destination_port": 5002, + "fec2D_destination_port": 5004, + "fec1D_source_port": 5002, + "fec2D_source_port": 5004, "rtcp_enabled": true, "rtcp_destination_ip": "172.30.82.24", "rtcp_destination_port": 5008, diff --git a/examples/v1.0-sender-get-200-uninit.json b/examples/v1.0-sender-get-200-uninit.json new file mode 100644 index 00000000..784a34a9 --- /dev/null +++ b/examples/v1.0-sender-get-200-uninit.json @@ -0,0 +1,30 @@ +{ + "receiver_id": null, + "master_enable": true, + "activation":{ + "mode": null, + "requested_time": null, + "scheduled_time": null + }, + "transport_params": [{ + "source_ip": "auto", + "destination_ip": "auto", + "source_port": "auto", + "destination_port": "auto", + "fec_enabled": false, + "fec_destination_ip": "auto", + "fec_type": "XOR", + "fec_mode": "1D", + "fec_block_width": 4, + "fec_block_height": 4, + "fec1D_destination_port": "auto", + "fec2D_destination_port": "auto", + "fec1D_source_port": "auto", + "fec2D_source_port": "auto", + "rtcp_enabled": false, + "rtcp_destination_ip": "auto", + "rtcp_destination_port": "auto", + "rtcp_source_port": "auto", + "rtp_enabled": true + }] +}