Overview of syntax

CDP configuration system has two types of XML files. Model XML files describe model syntax and configuration values (same as class definition in c++) and component XML files that are created one per CDPComponent inheriting instance whose syntax the model files describe (model files may use the same new xml syntax they have declared).

Model files contain four main type of Tags and each tag has different set of built in attributes that can be used in the tag.

Model File Items

• Model file header tags <Model> <ModelTypeClass/> <BaseModel/> </Model> describing models name and inheritance

  Model Header Tags

  • <Model Name="MyModel"> model name
  • <ModelTypeClass/> and <BaseModel/> have no attributes
  • <Template Name="T" Value="double; float; int"/> useful when creating model for a class using C++ templates.
• Element declaring tags <Element Name='MyElement'></Element> describing new elements for component files or model files (usually for nesting other model instances, but may declare element Property configuration value)

  Element Tag Attributes

  • <Element Name="MyElement"> name of the element. Will mandate usage of <MyElement> henceforth (also in derived models)
  • <Element Name="MyProperty" Type="double" Value="0"> defines an Element Property configuration value. Additional attributes (like Description, TypeHint etc.) described for Attribute type Properties may also be used.
  • <Element Property="0"> when set to 0 this element will not be regarded as configuration element property but as part of structure syntax of component files
  • <Element Name="MyElement" AcceptsModel="MyModelName"> will make the element <MyElement> instantiate MyModelName when used, will also create configuration drop target for that type
  • <Element Name="MyElement" AcceptsBase="MyModelBase"> will make the element drop target for anything derived from MyModelBase including MyModelBase, Needs prototype or declaration to use Model attribute <MyElement Model="MyModel"> to instantiate concrete model
• Attributes declaring attribute tags <Attributes> <Attribute/> </Attributes> used to add new configuration values of type CDPProperty to model

  Attribute Tag Attributes

  • <Attribute Name="MyAttribute"> name of the attribute
  • <Attribute Type="int"> defines the attribute value type from selection of: string;bool;char;unsigned char;short;unsigned short;int;unsigned int;int64_t;uint64_t;float;double
  • <Attribute Description="Description of attribute"> end user targeted description of the attribute, also used in UI hints
  • <Attribute TypeHint="Selection" Selection="a;b;c"> type hint is targeted to presentation layer to help indicating the way or type of presentation. Studio supports TypeHints: Routing, RoutingList, Selection, File, Radix, Flags, ScopedNode, ScopedNodeList, Angle.
  • <Attribute DisplayHint="Internal"> display hint is targeted to presentation layer to help determine which nodes are most important to user. Studio supports DisplayHints: Internal, Default, Important.
  • <Attribute ReadOnly="1"> make the attribute not editable in the presentation layer
  • <Attribute IgnoreInDiff="1"> hints that runtime changes to this node should not be committed to version control.
  • <Attribute Required="1"> when set to 1 will make the attribute required in component file
  • <Attribute IsSetting="1"> used by SettingAsAttribute resource to create CDPSetting based configuration value instead of CDPProperty from the attribute as PropertyAsAttribute resource does For Element tags that don't declare Property="0" attribute, instantiating a CDPProperty, all attributes will be CDPSettings by default)
• Prototype instantiation tags <MyClass/> creating instance of element declared before or in base model

  Prototype Attributes

  • <MyElement Name="NodeName"> instance name of the prototype
  • <MyElement Name="NodeName2" TypeHint="Radix" Radix="16" DisplayHint="Important"> prototype with TypeHint and DisplayHint used
  • <MyElement Model="MyConcreteModel"> used when AcceptsModel uses list of models or AcceptsBase base has multiple inheriting models to indicate the concrete model type

Model file built-in elements

Model file should always start with xml version declaration <?xml version="1.0" ?>

<Model/>

Model xml-element declares the name of the model and model syntax version number. Model name is used to refer to the model from other model files and also to create instance from a model in code.

The built-in xml-attributes are Name and Version

<Model Name="UDPIOServer" Version="2.0"></Model>  <!--File name: UDPIOServer.xml -->

<Model Name="Signal&lt;unsigned int&gt;" Version="2.0"></Model>  <!--File name: Signal_unsigned_int.xml C++-typename: Signal<unsigned int>-->

<Model Name="Signal&lt;T&gt;" Version="2.0"></Model>  <!--File name: Signal_T.xml C++-typename: Signal<T>-->

<ModelTypeClass/>

The allowed values for xml-element Model type class are "XML" and "C++". Models that can be instantiated with CDPBuilder by providing in the models name should use "C++" as the value.

Models that are alternative models of some other C++ based model (like preconfigured CDPIOServer with Modbus and UDP) should use "XML". For such models first base model with value "C++" for ModelTypeClass are instantiated trough CDPBuilder.

<BaseModel/>

Specifies inherited base model (Lowest base model that can be used is "CDPNode")

Template is used to replace string specified in Name attribute with each item in semicolon separated list specified in Value attribute. Useful when creating model for a class using C++ templates. Note that <Template> element is not inherited from BaseModel, it must be redeclared in inheriting model.

<Model Name="MyClass&lt;T&gt;" Version="2.0">
  <Template Name="T" Value="int64_t; uint64_t; double; float; int; unsigned int; short;
      unsigned short; char; unsigned char; bool"/>
  <BaseModel>CDPOperator&lt;T&gt;</BaseModel>
  <Attributes>
    <Attribute Name="Type" Type="string" Value="T"></Attribute>
    <Attribute Name="Value" Type="T" Value="0"></Attribute>
  </Attributes>
</Model>

<Attributes/>

Grouping element for <Attribute/> elements directly tied to the model.

<Attribute/>

Specifies an XML attribute of either the model, a prototype or element/property.

<Element/>

Element <Element Name="MyElement"> describes the component file xml-element <MyElement>. When Element has xml-attribute AcceptsModel or AccpetsBase then the <Element Name="MyElement"> describes the component file xml-element "<MyElement>" model relation.

Prototypes like <MyElement/>

Usages of xml-elements declared by model and basemodels. For ex. using <MyElement> after it has been declared by Element tag <Element Name="MyElement">. Declaring an element like this makes the configurator always generate it into the configuration when an instance of this model is made.

Prototypes may also use ReadOnly, TypeHint and DisplayHint attributes to affect the presentation and editing of given instance in presentation layer.

<Element/> built-in attributes

Name=""

Name of the generated xml-element in component file.

Type=""

Defines the value type of the Element. Value types start with lower case and is one of the following: string, bool, char, unsigned char, short, unsigned short, int, unsigned int, int64_t, uint64_t, double, float

Property=""

Indicates if a by default property should be generated from the element. Default value "1" means CDPProperty node will be generated to represent the containing xml-element. This is represented by PropertyAsElement resource. All attributes added to such element tag will be of type CDPSetting.

If Property="1" (default), additional attributes (like Description, TypeHint etc.) described for Attribute type Properties may also be used.

AcceptsModel=""

The AcceptsModel-keyword in AggregateModel resource is used to indicate a list of specific types that can be placed within the configuration subtree. Below is an example showing how it is used. The value of the attribute has to be a valid model name. The AcceptsModel-restriction can accept a semi-colon separated list of models, where one or several items can be specified to only accept generic types. When specifying AcceptsModel='MyModel&lt;&gt;', template models named 'Type<double>', 'Type<int>' etc are accepted (model named 'MyModel' is not accepted).

<Element Name="CDPSignals/CDPSignal" Property="0" AcceptsModel="CDPSignal&lt;&gt;"/>
<Element Name="Alarms/Alarm" Property="0" AcceptsModel="CDPAlarm"/>

The grouping tag like "CDPSignals" is an a AggregateGroup resource this allows all "CDPSignal" tags to be grouped in the XML file.

<Element Name="TPDO" Property="0" Description="Add CDPChannels to receive values from node"></Element>
<Element Name="TPDO/CDPChannel" AcceptsModel="CDPSignalChannel&lt;&gt;" Property="0" />

This is a mechanism that allows you to write in model <Element Name="CDPSignals/CDPSignal" Property="0" AcceptsModel="CDPSignal&lt;&gt;" />, and make the prototype <CDPSignal Name="cdpsignal" Type="double" Model='CDPSignal&lt;double&gt;' /> and it will create the prototype from model CDPSignal<double>, even though the descriptor only stated AcceptsModel="CDPSignal".

AcceptsBase=""

The AcceptsBase-keyword in AggregateBaseModel resource is used to indicate a that types with the specified base can be placed within the configuration subtree.

<Element Name="Subcomponents" Property="0"></Element>
<Element Name="Subcomponents/Subcomponent" Property="0" AcceptsBase="CDPComponent"></Element>

Configurable=""

Valid only when element has AcceptModel or AcceptsBase attribute.

"Configurable='0'" prevents the entry of an accepted prototype from model file to be written to the component configuration file. The default, and assumed value if not present, is "Configurable='1'". As of now, the descriptor for Messages, States and State Transitions has Configurable='0' This differs from the 'ReadOnly'-attribute. 'ReadOnly' still makes the prototype written to the the component configuration file, but it can not be altered by user.

Overriding attributes of aggregated models

When aggregating models using AcceptsModel or AcceptsBase, it is possible to override some of the attributes. The following code will allow to aggregate CDPSignalChannel<> elements but overrides their Input attribute to have read-only Value="1".

<Element Name="CDPChannel" AcceptsModel="CDPSignalChannel&lt;&gt;" Property="0">
  <Attribute Name="Input" Value="1" ReadOnly="1" Type="bool"></Attribute>
</Element>

<Attribute/> built-in attributes

Name=""

Defines the name of the xml-attribute. It is a string value and should start with capital letter

Type=""

Defines the value type of the Attribute value types start with lower case and is one of the following: string, bool, char, unsigned char, short, unsigned short, int, unsigned int, int64_t, uint64_t, double, float

Value=""

Sets the default value of the Attribute.

Description=""

Is short text describing the function of the attribute

TypeHint=""

The type hint attribute is used to provide metadata about a value. These are a fixed set of values (that is still to be fully decided).

As of now, the following type hints exist

• Routing - attribute is a path to given type of object
• RoutingList - attribute is a semicolon-separated list of paths to given type of object
• Selection - attribute is a semicolon-separated list of possible values restricted to the given object. For numeric values, a description can be added for every possible value (after the hyphen). Quotation can be used to include the separator (hyphen) in the value or description.
• MultiLineText - attribute is to be edited in a separate editor. Useful for attributes that can have long text with newlines in it. MultiLineText attribute can specify the programming/scripting language names (currently supported are "C++", "ChaiScript" and "Protobuf") whose syntax highlighting to use in the editor.
• File - attribute is a URL to a file
• Radix - attribute is to be viewed in given number base
• Trigger - attribute is self clearing value presented as a button (with set value true or 1) with given text.
• Flags - attribute is to be viewed and edited as flags. Flag is a separately changeable part of the attribute value, shown as a single character and changeable as a checkbox. For numeric attributes, flag is a bit position in the value. For string attributes, flag is a unique character in the string.
• ScopedNode - attribute is to be viewed and edited as a named node selectable from list of nodes based on given type, available directly under any of the parents from the current attribute location. In the case of multiple nodes with the same name the node nearest takes precedence. Number of parent levels to search from can be limited by prefixing type name with the corresponding number of dots.
• ScopedNodeList - attribute is to be viewed and edited as semicolon-separated list selectable from list of nodes based on given type, available directly under any of the parents from the current attribute location. In the case of multiple nodes with the same name the node nearest takes precedence. Number of parent levels to search from can be limited by prefixing type name with the corresponding number of dots.
• Angle - attribute will be treated as an angle, that will be displayed and can be edited both in degrees and in radians simultaneously. The actual format (Radians or Degrees) that is used to store in configuration is specified in Angle attribute.

Example usages of the built-in attributes:

<Attribute Name="Routing" Type="string" Description="Target signal whose value is regularly copied to this object" Required="0" TypeHint="Routing" Routing="CDPSignal&lt;&gt;"/>
<Attribute Name="RoutingList" Type="string" TypeHint="RoutingList" RoutingList="CDPBaseObject" Description="Target objects to send the message to"/>
<Attribute Name="Type" TypeHint="Selection" Selection="double;int;char" />
<Attribute Name="Script" TypeHint="MultiLineText" MultiLineText="ChaiScript" />
<Attribute Name="Mode" Type="char" TypeHint="Selection" Selection="0 - Description for mode zero;1 - Description for mode #1;&quot;-1&quot; - &quot;Description for mode -1&quot;" />
<Attribute Name="Document" Type="string" TypeHint="File" File="Images (*.png *.jpg *.svg);;Text files (*.txt *.rtf *.md)"/>
<Attribute Name="Mask" Type="int" TypeHint="Radix" Radix="16" /> <!-- specify mask as hex to ease usage -->
<Attribute Name="StartButton" Type="bool" TypeHint="Trigger" Trigger="Start" />
<Attribute Name="NumericFlaggedValue" Type="unsigned char" TypeHint="Flags" Flags="A - Flag A descripton (first bit of the value);;B - Flag B description (third bit of the value)" />
<Attribute Name="StringFlaggedValue" Type="string" TypeHint="Flags" Flags="A - Flag A description (letter A);B - Flag B description (letter B)" />
<Attribute Name="Channel" Type="string" TypeHint="ScopedNode" ScopedNode="..InputChannel;..OutputChannel"/>
<Attribute Name="UsersOrGroups" Type="string" TypeHint="ScopedNodeList" ScopedNodeList="User;Group"/>
<Attribute Name="SomeAngleInRadians" Type="double" Unit="rad" TypeHint="Angle" Angle="Radians"/>
<Attribute Name="SomeAngleInDegrees" Type="double" Unit="deg" TypeHint="Angle" Angle="Degrees"/>

ReadOnly=""

The 'ReadOnly'-attribute prevents the user to alter the value of the node. This can be explicitly or implicitly defined for the INodes. If the model node contains "ReadOnly='1'", the INode will explicitly be set read only.

However, if a model provides prototype for Signals, Alarms and so on, the attribute 'Name' as inherited from CDPObject is set as read only.

<Attribute Name="SomeValue" Value="Good" Type="string" TypeHint="Selection" Selection="Good;Bad" ReadOnly="1"></Attribute>

IgnoreInDiff=""

The 'IgnoreInDiff' attribute hints that runtime changes to the value of the node should not be committed to version control. Useful for values that must persist over CDP application reboot but are not part of the application configuration.

<Attribute Name="TimeLastChanged" Type="string" IgnoreInDiff="1"></Attribute>

DisplayHint=""

Gives hint to the presentation layer how the node should be shown.

The following display hints can be specified:

• Internal - hint that node is an implementation detail and should not be visible to user
• Default - same as omitting the DisplayHint attribute
• Important - hint this node is important and should be visible for the user

How CDP Studio handles display hints is described in Configure mode Filtering chapter

IsSetting=""

The default implementation of xml-element Attribute in CDP is CDPProperty. IsSetting is intended to provide override to the default Attribute implementation based on CDPSetting. CDPSetting is strictly name, value pair and only built-in xml-attributes are allowed in addition. Type must be a primitive type. The default value of IsSetting is "0".

<Attribute Name="SomeValue" Value="10" Type="int" IsSetting="1"></Attribute>

Prototype built-in attributes

Name=""

Instance Name is required and must be unique among other instances on the same level. The name should be alphanumeric and may contain space and underscore (name may not contain slashes or dots).

Model=""

When AcceptsModel uses list of models or AcceptsBase base has multiple inheriting models, 'Model' is used to indicate the concrete model type to be created for this instance of the prototype.

Attribute forward declarations

Attribute forward declarations are created by setting Property="0", like this:

<Attribute Name="SomeValue" Property="0"></Attribute>

This forward declares a attribute to be part of the API of some future model. This also affects what columns are shown in visualization when different type models with common base model are in the same section.

Model file naming

Model files must be named correctly for CDP to be able to find model. Follow one of these rules when setting model file name:

• model name + XML extension. Fe. model <Model Name="MyClass"> should be stored in file named MyClass.xml
• modelname + _ + typename + XML extension. Fe. templated model <Model Name="MyClass&lt;int&gt;"> should be stored in file named MyClass_int.xml
• modelname + _T + XML extension. Fe. templated model <Model Name="MyClass&lt;T&gt;"> should be stored in file named MyClass_T.xml