Model XML

The system model XML format is used by the model importer/exporter to make changes to the GreenBus system model. Modifications to the existing system should be made by first exporting the current state, making changes in the outputted XML, and re-importing.

When exported or created from scratch, an individual XML document represents a fragment of the total model, defined by the root elements present in the equipment and endpoint models. The fragment extends to children (through the owns model hierarchy) of the equipment roots, and the exporter will also include any Endpoints that reference the equipment model's Points and Commands.

On re-import, the fragment in the XML is compared to the same fragment in the current live system, and elements missing from the XML are deleted. Model objects in the current system not in the fragment are not deleted. Therefore, if a system has more than one root node, and the XML represents an export of only one root, re-importing that XML does not imply the other roots and their children should be deleted.

Relationships between objects in the fragment and those outside it (for instance, if the root in the XML is actually a child of an actual root node in the system) are represented by external relationship elements such as <externalOwners>. If these elements have been removed on re-import the model relationship will be deleted in the system.

High-level Structure

The model configuration schema consists of a <configuration> root element that contains two major subsections, the equipment model and the endpoint (communications) model. They contain a list of <equipment> and <endpoint> elements, respectively, and <equipment> elements may recursively include sub-equipment.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration xmlns="xml.ldr.greenbus.io">
    <equipmentModel>
        <equipment name="RootA">
            ...
        </equipment>
        <equipment name="RootB">
            ...
        </equipment>
    </equipmentModel>
    <endpointModel>
        <endpoint name="EndpointA" protocol="protocolA">
            ...
        </endpoint>
        <endpoint name="EndpointB" protocol="protocolB">
            ...
        </endpoint>
</configuration>

Common Elements

Identification

Model objects are identified by a combination of a name attribute and an optional uuid attribute. When creating new objects through the XML the UUID may be left absent to be generated by the services. Renaming objects requires the UUID to be present so that the XML element with the new name can be correlated with the model object with the old name.

Model relationships in the XML model (<reference>, <relationship>, <source>) are also identified by the combination of name and uuid attributes. In this case, one of the two attributes must be present. If both are present, the UUID is considered to be the stronger identification.

Types

The <type> element represents the presence of a type in a model object. It contains the single attribute name that contains the type name.

Example:

<type name="TypeA"/>

Key Values

The <keyValue> element represents a key value attached to a model objects. It contains a key attribute specifying the name of the key, as well as one of the following value attributes:

Attribute	Value Type	Description
`stringValue`	string	A string value.
`booleanValue`	boolean	A boolean value, `true` or `false`.
`intValue`	long	An integer value
`doubleValue`	double	A floating point value.
`bytesSize`	long	A byte array value referenced only by its size. Can be deleted by removing it but not modified.
`fileName`	string	A byte array value referenced by the name of another file.

External Relationships

Objects in the equipment model define ownership relationships to sub-equipment, points, and commands according to the presence of full descriptions of those objects in the XML hierarchy. Relationships to objects elsewhere in the XML or not present in the model fragment are specified by the <externalOwners>, <parentRelationships>, and <childRelationships> elements.

The <externalOwners> element contains a collection of <reference> elements. References contain attributes for name and uuid, and at least one must be present.

Example:

<externalOwners>
    <reference name="RootNotInXml" uuid="..."/>
</externalOwners>

The <parentRelationships> and <childRelationships> elements contain collections of <relationship> elements. In the parent relationship collection, the referenced object is the parent of the object. In the child relationship collection, the referenced object is the child of the object. Relationships contain name and uuid as in a reference, but also specify a relation attribute that defines the relationship type. Examples:

<parentRelationships>
    <relationship name="SomeOtherObjectA" uuid="..." relation="relatesTo"/>
    <relationship name="SomeOtherObjectB" uuid="..." relation="relatesTo"/>
</externalOwners>
<childRelationships>
    <relationship name="SomeOtherObjectC" uuid="..." relation="relatesTo"/>
    <relationship name="SomeOtherObjectD" uuid="..." relation="relatesTo"/>
</childRelationships>

Equipment

Model entities are represented in the XML by <equipment> elements. Equipment may recursively include sub-equipment, forming a tree, and may also contain elements for Points and Commands.

Additionally, <equipment> elements contain the common sub-elements for objects in the model: types, key values, and external relationships.

<equipment name="EquipmentA" uuid="...">

    <!-- List of types -->
    <type name="Equipment"/>
    <type name="TypeA"/>

    <!-- List of key values -->
    <keyValue key="keyA" stringValue="A Value"/>
    <keyValue key="keyB" fileName="file01.txt"/>

    <!-- List of sub-equipment -->
    <equipment name="SubEquipment1">
        ...
    </equipment>

    <!-- Points/Commands owned by the equipment -->
    <status ...> ... </status>
    <analog ...> ... </analog>
    <counter ...> ... </counter>
    <control ...> ... </control>
    <setpoint ...> ... </setpoint>

    <!-- Other relationships, each element occurs zero or one time -->
    <externalOwners ...> ... </externalOwners>
    <parentRelationships ...> ... </parentRelationships>
    <childRelationships ...> ... </childRelationships>

</equipment>

Points

Points in the model are represented by <status>, <analog>, or <counter> elements, with the element type determining the Point category. Points contain the common sub-elements for objects in the model: types, key values, and external relationships.

The feedback relationship between Points and Commands is modeled in the <commands> sub-element, which is a list of references to Command objects elsewhere in the model.

The Point elements also contain the <triggers> and <calculation> sub-elements, which are discussed in the processing and calculation XML documentation.

Example/structure:

<analog name="PointA" uuid="..." unit="unitA">

    <!-- List of types -->
    <type name="Point"/>
    <type name="TypeA"/>

    <!-- List of key values -->
    <keyValue key="keyA" stringValue="A Value"/>
    <keyValue key="keyB" fileName="file01.txt"/>

    <!-- Processing configuration -->
    <triggers>
        ...
    </triggers>

    <!-- Calculation configuration -->
    <calculation>
        ...
    </calculation>

    <!-- List of feedback references to Commands -->
    <commands>
        <reference name="CommandA"/>
        <reference name="CommandB"/>
    </commands>

    <!-- Other relationships, each element occurs zero or one time -->
    <externalOwners ...> ... </externalOwners>
    <parentRelationships ...> ... </parentRelationships>
    <childRelationships ...> ... </childRelationships>

</analog>

Commands

Commands in the model are represented by <control> and <setpoint> elements, with the element type determining the Command category. Commands contain the common sub-elements for objects in the model: types, key values, and external relationships.

Both the <control> and <setpoint> elements contain the displayName attribute (a string value), and the <setpoint> element additionally contains the setpointType attribute, which has possible values double, integer, or string.

Example/structure:

<control name="ControlA" uuid="..." displayName="Control A">

    <!-- List of types -->
    <type name="Command"/>
    <type name="TypeA"/>

    <!-- List of key values -->
    <keyValue key="keyA" stringValue="A Value"/>
    <keyValue key="keyB" fileName="file01.txt"/>

    <!-- Other relationships, each element occurs zero or one time -->
    <externalOwners ...> ... </externalOwners>
    <parentRelationships ...> ... </parentRelationships>
    <childRelationships ...> ... </childRelationships>

</control>

<setpoint name="SetpointA" uuid="..." displayName="Setpoint A" setpointType="double"/>
    ...
</setpoint>

Endpoints

Endpoints in the model are represented by <endpoint> elements. Endpoints contain the common sub-elements for objects in the model: types, key values, and external relationships.

The protocol attribute defines the Endpoint protocol.

Endpoints contain a series of <source> sub-elements that are references to Points and Commands the Endpoint serves as a data source for. The <source> elements are identical to <reference> elements, containing one or both of a name and uuid attribute.

Example/structure:

<endpoint name="Simulated_PV" uuid="..." protocol="simulator">

    <!-- List of types -->
    <type name="Endpoint" />
    <type name="TypeA"/>

    <!-- List of key values -->
    <keyValue key="protocolConfig" fileName="configuration.file"/>
    <keyValue key="keyA" stringValue="A Value"/>

    <!-- List of source relationships -->
    <source name="PointA" uuid="..."/>
    <source name="CommandA" uuid="..."/>

    <!-- Other relationships, each element occurs zero or one time -->
    <externalOwners ...> ... </externalOwners>
    <parentRelationships ...> ... </parentRelationships>
    <childRelationships ...> ... </childRelationships>

</endpoint>