Revise the Data Dictionary Implementation

[jastram]

Lukasz suggested to revise the Data Dictionary implementation, as currently some data in the XML is not exposed in the UML profile. Rather than working on the implementation right away, we will:

• Lukasz is not yet member of the toolchain repository, therefore, I assign Alexander for now.
• Update the DataDictionary spec to reflect the changes proposed by Lukasz
• If no spec exists, write it (look at the Traceability spec for inspiration
• Once complete and reviewed internally, coordinate with Uwe to get feedback from Esterel
• Implement it.

[astante]

There is the original proposal page on the wiki: https://github.com/openETCS/toolchain/wiki/Integration-of-Data-Dictionary-into-Papyrus However I think a more detailed description is necessary for proposing changes.

[lfronc]

I'd like to show the actual state of my proposal for the mapping from XML to UML, and discuss it.

My vision of the data dictionary is that its goal is to document all variables and packets used in the control system. Actually, all data is produced in bitwalker XML format form the textual specification. The goal of the plugin is to produce a UML model form XML files that can be used for documentation in SysML and SCADE models.

This UML model should not be directly used as implementation but referred by objects in the model for documentation and traceability.

The main requirement is to have a lossless transformation.

In the following sections, I summarize the bitwalker xml format, then propose how to perform the transformation to UML, and finally give an example made by hand in Papyrus.

Bitwalker XML source

Variables

The variables are defined in the XML by an element "Variable" containing the following elements:

• "DetailedName" which contains its name within a string body (required)
• "Description" which contains its description within a string body (optional)
• "Specs" which gives information about the variable (required)

  • Specs attributes:

    • "Length" variable length, units vary (required)
    • "MinVal" minimal value (optional)
    • "MaxVal" maximal value (optional)
    • "Formula" formula associated with variable (optional)

  • Specs body: optional list of "Special" elements with attributes:

    • "Value" (required)
    • "Description" (optional)

    Each special element is used as an enumeration literal and its value.

Packets

Each packet is defined in the XML by an element "Packet" with contains:

• required attributes:
  • "Number" : packet number (required)
  • "Name" : packet name (required)
  • "TransmissionMedia" : packet transmission media (required)
• a body formed of
  • "Description" describing the packet (optional)
  • "Content" containing packet data (required)

Packet data is a sequence of elements:

• "TlgVar" which is a field with attributes
  • "Name" (required)
  • "Length" (required)
  • "Comment" additional information about the variable or field (optional)
• "LoopDoWhile" : its body is a sequence of "TlgVar",
  "Conditional", or "LoopWhile". Each LoopDoWhile element
  contains a TglVar element with name ITER which denotes the
  number of iterations in the loop.
• "Conditional" is a condition on some variables, its body is:
  • "Condition" which is a string
  • "Variables" which is a sequence of "TlgVar", "Conditional", "LoopWhile" or "Conditional".
• "LoopWhile" : its body is a sequence of "TlgVar", "Conditional". Each LoopWhile elements contains a TglVar element with name ITER which denotes the number of iterations in the loop. The difference between LoopDoWhile and LoopWhile is that LoopWhile cannot contain nested loops.

UML mapping:

The goal of the mapping is to be easily readable with minimal number of UML elements used.

Each variable should be transformed into an UML classifier, allowing to add attributes as properties and specs as a nested classifier. Because this model will be used as documentation the kind of classifier does not really matter. However, only one classifier should be used for consistency.

Enumerations should not be used because we lose information about special values. Indeed, a value cannot be directly linked with an enumeration literal (except with comments).

Packets should be handed in the same way using nested classifiers for contents, conditional parts and loops.

To achieve this the usage of a new profile with new stereotypes is proposed:

• Stereotype <> extending metaclass Class to denote variable specifications.
• Stereotype <> extending metaclass Class to denote packet specifications.
• Stereotype <> extending metaclass Property to denote conditional sections in packets. This stereotype contains one property: the condition.
• Stereotype <> extending metaclass Property for conditional loop sections in packets. This stereotype contains one property: the iteration variable.

Each sequence of elements that are in a conditional, or a loop, should be encapsulated inside of a new classifier, and the property of type of this block should appear in the packet with <> or <> stereotype. For loops the iteration variable should appear preceding this block and should be referenced by a property of the stereotype for consistency.

Simple hand made example (in Papyrus)

As a proof of concept I propose a hand made version of "Gradient Profile" packet, NID_PACKET variable and Q_GDIR variable. This was made using Papyrus.

The corresponding model is easily readable and manually modifiable.

Comments on the proposal

This proposal remains close to the XML representation, we're not sure that it is the best approach. Mainly because:

• xml is just a temporary straight forward ad-hoc approach
• the loop/conditional structures are uncommon to describes data types. Perhaps this should be translated differently.

One direction could be the usage of plain SysML (primitive types, value types, dimensions, units). I toyed with this, but did not achieve anything satisfying.

[jastram]

@lfronc thanks for this proposal - this looks very promising. Two comments:

• Please make sure that the WP3 and WP4 stakeholders see this - at this stage, this is more important than WP7, as this describes the result that the modelers have to deal with.
• Please make sure that this is aligned with the existing spec. Eventually, the two should be merged and cleaned up.

[cecilebraun]

From 20.03.14 telco:

• record the new approach i the data dictionary documentation Document the data dictionnary approaches #328
• experiments with SysML value type SysML value Type possible implementation for data type representation  #327

[jastram]

Bump - any progress here? Also, it's still not possible to assign this to Lukasz.

[cecilebraun]

@lfronc proposed an implementation see fa51749