Supervisor XML grammar

[m8pple]

Devices types have an InputPin and OutputPin, but SupervisorTypes have SupervisorInPin and SupervisorOutPin. Is this because SupervisorTypes might have InputPins? It is a bit confusing as they have both an attribute called "SupervisorInPin" and an element called "SupervisorInPin". I sort of get the idea that the attribute is connected to explicit aspects of the device-type "SupervisorOutPin" (I think?), but given it is a "SupervisorType", why not just have "SupervisorType/InputPin"?

Also, attributes have generally used initial lower-case, so it would be "supervisorInPin" as an attribute, vs "SupervisorInPin" as an element.

Neither of these are that a big deal, as design of supervisors was deferred to Southampton to give maximum implementation efficiency and speed. So we can generate and parse however you like, but it seems a bit inconsistent.

[heliosfa]

Is this because SupervisorTypes might have InputPins?

Correct.

Devices (and Supervisors) have SupervisorInPins and SupervisorOutPins for the implicit connections (that don't appear in the XML) between devices and supervisors.

There is some possibility of having explicit connections in future for more complex functionality, so InputPin and OutputPin was left free for future expansion.

It is a bit confusing as they have both an attribute called "SupervisorInPin" and an element called "SupervisorInPin".

Where are you seeing "SupervisorInPin" as an attribute? I don't recall anywhere it is used in the XML spec other than as an element name.

[m8pple]

Ah, ok - I was wondering about explicit connections, and wasn't sure whether you could also make them to the same pins.

Where are you seeing "SupervisorInPin" as an attribute? I don't recall anywhere it is used in the XML spec other than as an element name.

It's mentioned in application.md.

Umm, not sure how to link to markdown lines. In the following text it is an attribute:

Graphs/GraphType/DeviceTypes/SupervisorType

Contains the type definition for all supervisor devices.

This element must occur at most once in each :DeviceTypes: section. Valid attributes:

id (must occur exactly once): Currently unused.

SupervisorInPin (must occur at most once): Defines the :SupervisorType - SupervisorInPin to be used to consume incoming messages from normal devices over implicit connections. If this attribute is used, it must match the value of the id of a :SupervisorType - SupervisorInPin. If this attribute is not used, the implicit connections from normal devices to their supervisor device are disabled in this application.

And there are examples which have it too:

<SupervisorType id="" SupervisorInPin="tracker">
        <!-- There is one supervisor device type in a given application. This
             particular supervisor is written assuming there is only one
             instance for simplicity.

It also appears in the xml grammar file: https://github.com/POETSII/Orchestrator/blob/6c6daa6f29eabebed4516bad25540a51ffde1504/Config/V4Grammar3.ocfg#L42

[heliosfa]

It also appears in the xml grammar file:

Ah, at the SupervisorType level. Yeah, I think this (and the note in applications.md) is a holdover from an earlier iteration from ADB or just an error on our part: the SupervisorInPin and SupervisorOutPin attributes are not actually used during parsing and a Supervisor can have a maximum of one SupervisorOutPin and one SupervisorInPin so there is no need to explixitly mark one for implicit connections.

Soes that soudn about right @mvousden ?

[mvousden]

Source went ahead of documentation on this one. I'll fix this and open a PR.