Fix the language about the NMOS Controller makeing IS-05 connections (active/inactive Sender, keep/change configuration of Sender, use real/fictious Receivers) #109
Conversation
Clarify the language of NMOS Controller to support the case of an active or inactive Sender. It must be possible to connect a number of Receivers to an already active Sender, making sure the resulting constraint_sets are a subset of the active constraints of the Sender.
Rework the language again to be about keeping or changing the configuration of the Sender. Also allow fictious target Receivers or real effective Receivers to allow the Controller toconfigure the Sender without using real Receiver devices that may become available on the network only after configuring the Senders.
Fix a word fic·ti·tious
|
I like the intention. Although I understand what you mean, I'm not sure whether the terminology of "effective/real" and "target/fictitious" is right yet. Maybe we need a naming brainstorm on Slack. 😄 The duplication between the "If changing the configuration" and the "If keeping the configuration" paragraphs makes each one easy to read, but I wonder if some of the commonality can be factored out. |
|
Thanks for your comment. I agree that the "effective/real" and "target/fictitious" expressions are not the best .. Initially I just wanted to express the objectives of the modification and I would appreciate your comments about making the language better. Initially we must agree about the objectives and then fix the language. |
| @@ -2,7 +2,13 @@ | |||
|
|
|||
| ## Active Constraints of Sender | |||
|
|
|||
| Before making an [IS-05][IS-05] connection, NMOS Controller chooses a Sender and a number of Receivers. Then NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, NMOS Controller SHOULD inform the user about it. After that NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections if the Constraints have been applied succesfully to the Sender. After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender. | |||
| Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY use effective Receivers (real devices) or target Receivers (fictitious devices). The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration. | |||
There was a problem hiding this comment.
| Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY use effective Receivers (real devices) or target Receivers (fictitious devices). The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration. | |
| Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration. |
There was a problem hiding this comment.
The spec doesn't prohibit changing the configuration of an active Sender, so we can remove this distinction or emphasize that deactivating such Sender MAY be required and depends on the Sender itself.
There was a problem hiding this comment.
Agree with Nikita. Also I prefer "current configuration" to "actual configuration".
|
|
||
| If keeping the configuration of the Sender, the NMOS Controller MUST `GET /constraints/supported` and `GET /constraints/active` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, the NMOS Controller SHOULD inform the user about it. If the resulting `constraint_sets` is not a subset of the active constraints of the sender the NMOS Controller SHOULD inform the user about it. After that the NMOS Controller SHOULD make the IS-05 connection of the Receivers. | ||
|
|
||
| After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender after making it inactive. |
There was a problem hiding this comment.
| After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender after making it inactive. | |
| After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender after making it inactive. | |
| In order to change the configuration of the Sender without establishing an IS-05 connection, NMOS Controller MUST use `PUT /constraints/active` endpoint. If the Sender is active, NMOS Controller SHOULD deactivate it first. |
There was a problem hiding this comment.
I like that way of introducing the alternate approach "In order to change the configuration of the Sender without establishing an IS-05 connection".
With this phrasing and the "MAY choose to connect the Receivers to an active Sender or an inactive Sender" along with the accompanying text seems to cover all the possibilities.
It would be nice to look at the final text as a single piece to make sure everything is there.
There was a problem hiding this comment.
Is that recommendation to deactivate before changing the active constraints covered anywhere else in the spec so far?
| @@ -2,7 +2,13 @@ | |||
|
|
|||
| ## Active Constraints of Sender | |||
|
|
|||
| Before making an [IS-05][IS-05] connection, NMOS Controller chooses a Sender and a number of Receivers. Then NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, NMOS Controller SHOULD inform the user about it. After that NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections if the Constraints have been applied succesfully to the Sender. After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender. | |||
| Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY use effective Receivers (real devices) or target Receivers (fictitious devices). The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration. | |||
There was a problem hiding this comment.
The spec doesn't prohibit changing the configuration of an active Sender, so we can remove this distinction or emphasize that deactivating such Sender MAY be required and depends on the Sender itself.
|
|
||
| If changing the configuration of the Sender, the NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, the NMOS Controller SHOULD inform the user about it. After that the NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections of the Receivers if the Constraints have been applied succesfully to the Sender. | ||
|
|
||
| If keeping the configuration of the Sender, the NMOS Controller MUST `GET /constraints/supported` and `GET /constraints/active` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, the NMOS Controller SHOULD inform the user about it. If the resulting `constraint_sets` is not a subset of the active constraints of the sender the NMOS Controller SHOULD inform the user about it. After that the NMOS Controller SHOULD make the IS-05 connection of the Receivers. |
There was a problem hiding this comment.
is not a subset
Maybe requires a definition of subset. Here is one that Gareth and me formulated for the nmos-cpp PR:
Constraint Set B is a subset of Constraint Set A if all Parameter Constraints of Constraint Set A are present in Constraint Set B, and for each Parameter Constraint that is present in both, the Parameter Constraint of Constraint Set B is a subconstraint of the Parameter Constraint of Constraint Set A.
Constraint B is a subconstraint of Constraint A if:
- Constraint B has enum keyword when Constraint A has it and enumerated values of Constraint B are a subset of enumerated values of Constraint A
- Constraint B has enum or minimum keyword when Constraint A has minimum keyword and allowed values of Constraint B are greater than minimum value of Constraint A
- Constraint B has enum or maximum keyword when Constraint A has maximum keyword and allowed values of Constraint B are less than maximum value of Constraint A
There was a problem hiding this comment.
I made a mistake in the sentence .. It shall be the reverse "If the active constraints are not a subset of the resulting constraint_sets" ... that is: the new constraint_sets must not be more constrained than the actual ones because it would mean that a stream/flow produces by the active sender would not be compliant with the new receiver(s).
My definition of a subset is different ... Constraint Sets A is a subset of Constraint Sets B if a stream/flow compliant with CS-A is also compliant with CS-B. I don't think we should define the complete algorithm that ensure that CS-A is a subset with CS-B but dictate what such subset represent.
There was a problem hiding this comment.
Hm, yeah, use of subset at this point is interesting, given we've been over the spec language before...
The current statement above that a Controller "make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender" is quite vague but could be implemented as intersection of the Receivers' constraint_sets. Effectively, Nikita and I had to come up with the above subset/intersection definition when implementing this.
When we have access to the Sender's own capabilities... which we didn't quite finish off specifying (#63).... the Controller would sensibly consider including those in the processing/subset to ensure it will get a 200 not a 422!
There was a problem hiding this comment.
Hm, actually, isn't this whole paragraph a bit confused... The fact that the "processing of the Receiver Capabilities" results in a subset or not doesn't mean that the Sender's current configuration will match all those Receivers, since the current stream might be within the Sender's current active constraints but not in the subset supported by the new Receivers?
Unless the Controller applies these new active constraints with a PUT request, it cannot guarantee either way?
Unless I've misunderstood, in order to guarantee to satisfy the new Receivers, the Controller MUST apply the new active constraints unless the current ones are a subset of the new ones?
There was a problem hiding this comment.
Aha, yes, I see @alabou made same comment... I agree with your idea!
There was a problem hiding this comment.
If the resulting
constraint_setsis not a subset of the active constraints of the sender the NMOS Controller SHOULD inform the user about it.
So, putting this the right way round, avoiding "subset", clarifying the rationale for informing the user, and expanding, something like:
If there can be streams compliant with the current active constraints of the Sender that would not be compliant with the resulting
constraint_sets, the NMOS Controller SHOULD inform the User that the Receivers cannot be accommodated without replacing the active constraints.
Long winded, so maybe needs breaking into several sentences...
There was a problem hiding this comment.
OK with that wording.
| Before making an [IS-05][IS-05] connection, NMOS Controller chooses a Sender and a number of Receivers. Then NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, NMOS Controller SHOULD inform the user about it. After that NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections if the Constraints have been applied succesfully to the Sender. After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender. | ||
| Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY use effective Receivers (real devices) or target Receivers (fictitious devices). The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration. | ||
|
|
||
| If changing the configuration of the Sender, the NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, the NMOS Controller SHOULD inform the user about it. After that the NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections of the Receivers if the Constraints have been applied succesfully to the Sender. |
There was a problem hiding this comment.
If the processing of the Receiver Capabilities results in an empty
constraint_setsof Active Constraints, the NMOS Controller SHOULD inform the user about it.
Does empty constraint_sets mean no Constraint Sets at all, i.e. it was impossible to come up with any Constraint Set that would satisfy all of the Receivers? If so, is SHOULD enough? How would the Controller be expected to proceed if it cannot make the connection to all of the Receivers that the User requested? I think the answer is that something like this:
If the processing of the Receiver Capabilities results in an empty
constraint_sets, the NMOS Controller SHOULD inform the User that not all of the specified Receivers can be satisfied at the same time.
There was a problem hiding this comment.
Is this read better?
If the processing of the Receiver Capabilities results in an empty constraint_sets, the NMOS Controller SHOULD inform the User that all of the specified Receivers cannot be satisfied at the same time.
I think we should keep the SHOULD to allow the controller to decide in some scenarios ...
| Before making an [IS-05][IS-05] connection, NMOS Controller chooses a Sender and a number of Receivers. Then NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, NMOS Controller SHOULD inform the user about it. After that NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections if the Constraints have been applied succesfully to the Sender. After breaking these connections via IS-05, NMOS Controller is RECOMMENDED to `DELETE /constraints/active` of the Sender. | ||
| Before making an [IS-05][IS-05] connection, an NMOS Controller chooses a Sender and a number of Receivers. The NMOS Controller MAY use effective Receivers (real devices) or target Receivers (fictitious devices). The NMOS Controller MAY choose to connect the Receivers to an active Sender or an inactive Sender. If the Sender is active, the NMOS Controller MAY keep the actual configuration of the Sender or deactivate the Sender and change its configuration. If the Sender is inactive, the NMOS Controller MAY keep the actual configuration of the Sender or change its configuration. | ||
|
|
||
| If changing the configuration of the Sender, the NMOS Controller MUST `GET /constraints/supported` from the Sender, MUST collect Receiver Capabilities from the Receivers and make such processing of them that they can be utilized for building Active Constraints satisfying all (by default) or some (depending on user preferences) of the Receivers and using Parameter Constraint URNs supported by the Sender. If the Sender supports fewer Parameter Constraint URNs than used in the Receiver Capabilities, the NMOS Controller SHOULD inform the user about it. If the processing of the Receiver Capabilities results in an empty `constraint_sets` of Active Constraints, the NMOS Controller SHOULD inform the user about it. After that the NMOS Controller MUST `PUT /constraints/active` to the Sender and SHOULD make the IS-05 connections of the Receivers if the Constraints have been applied succesfully to the Sender. |
There was a problem hiding this comment.
"User" is a defined NMOS term now - https://specs.amwa.tv/nmos/branches/main/docs/Glossary.html#user - so we could capitalize it like other terms if we like?
|
Closed in favor of #115 |
The actual language about the NMOS Controller is too restrictive and does not cover the cases where the Sender is already active and Receivers are to be connected to it without changing the configuration of the Sender. There are also scenarios involving not real actual Receivers of the NMOS environment but targeted fictitious Receivers that are use to preset the Sender.
The new language attempt to capture the active/inactive state of the Sender selected by the NMOS Controller and the fact that the configuration of such Sender is to be kept or changed. Finally to allow an NMOS Controller to configure a Sender without considering real effective Receivers the new language allow the use of target fictitious Receivers.
It seems reasonable to allow more flexibility in the use of IS-11 by an NMOS Controller.