Skip to content

Data Dictionary Plugin Development

Jump to bottom
lfronc edited this page Nov 19, 2014 · 10 revisions

This page was used as iterative steps to get to the Data dictionary we have now, some information may be out of date.

The current implementation of the Data Dictionary consists of Primitive Data Types which are transformed from the Bitwalker XML. Additional information that shall be capture is (if applicable):

  • Minimum valid value
  • Maximum valid value
  • Resolution
  • Bit length
  • Unit

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 a dynamic data structure and is defined in the XML by an element Packet which 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 element 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.

Approaches

UML Profile

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.

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 <<variable>> extending metaclass Class to denote variable specifications.
  • Stereotype <<packet>> extending metaclass Class to denote packet specifications.
  • Stereotype <<Conditional>> extending metaclass Property to denote conditional sections in packets. This stereotype contains one property: the condition.
  • Stereotype <<Loop>> 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 <<conditional>> or <<loop>> 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 : Gradient Profile, NID_PACKET, Q_GDIR (in Papyrus)

gradientprofile nid_packet q_gdir

The corresponding model is easily readable and manually modifiable.

model

Comments on this approach

This proposal remains close to the XML representation, 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.
  • may be difficult to integrate into SCADE System.

SysML value types

Value types allow to capture additional information like dimension and unit. The dimensions in the example below are originated from the variable name encoding description in D2.4.

SCADE encoding

The file subste-026-7.scade in the model shows a representative example of representation of a packet : National_Values (packet n°3, subset 026-7, sec 7.4.2).

type
National_Values = { 
	NID_PACKET : int 	 /* Packet =   3 */ ,
	Q_DIR : int ,
	L_PACKET : int ,
	Q_SCALE : int ,
	D_VALIDNV : int ,
	NID_C : int ,
	Struct0 : SVar30,
	V_NVSHUNT : int ,
	V_NVSTFF : int ,
	V_NVONSIGHT : int ,
	V_NVLIMSUPERV : int ,
	V_NVUNFIT : int ,
	V_NVREL : int ,
	D_NVROLL : int ,
	Q_NVSBTSMPERM : int ,
	Q_NVEMRRLS : int ,
	Q_NVGUIPERM : int ,
	Q_NVSBFBPERM : int ,
	Q_NVINHSMICPERM : int ,
	V_NVALLOWOVTRP : int ,
	V_NVSUPOVTRP : int ,
	D_NVOVTRP : int ,
	T_NVOVTRP : int ,
	D_NVPOTRP : int ,
	M_NVCONTACT : int ,
	T_NVCONTACT : int ,
	M_NVDERUN : int ,
	D_NVSTFF : int ,
	Q_NVDRIVER_ADHES : int ,
	A_NVMAXREDADH1 : real ,
	A_NVMAXREDADH2 : real ,
	A_NVMAXREDADH3 : real ,
	Q_NVLOCACC : int ,
	M_NVAVADH : real ,
	M_NVEBCL : int ,
	Q_NVKINT : int ,
	Q_NVKVINTSET : int ,
	A_NVP12 : real ,
	A_NVP23 : real ,
	V_NVKVINT : int ,
	M_NVKVINT : real ,
	Struct1 : SVar31,
	Struct2 : SVar32,
	L_NVKRINT : int ,
	M_NVKRINT : real ,
	Struct4 : SVar34,
	M_NVKTINT : real 
};

With helper data types for loop and conditional blocks:

type Var30 = { 
	NID_C : int
};
type AVar30 = Var30 ^33 ;
type SVar30 = { 
	 N_ITER : int,
	 Array : AVar30
};

type Var31 = { 
	V_NVKVINT : int,
	M_NVKVINT : real
};
type AVar31 = Var31 ^33 ;
type SVar31 = { 
	 N_ITER : int,
	 Array : AVar31
};

type Var32 = { 
	Q_NVKVINTSET : int,
	A_NVP12 : real,
	A_NVP23 : real,
	V_NVKVINT : int,
	M_NVKVINT : real,
	Struct51 : SVar33
};
type AVar32 = Var32 ^33 ;
type SVar32 = { 
	 N_ITER : int,
	 Array : AVar32
};

type Var33 = { 
	V_NVKVINT : int,
	M_NVKVINT : real
};
type AVar33 = Var33 ^33 ;
type SVar33 = { 
	 N_ITER : int,
	 Array : AVar33
};

type Var34 = { 
	L_NVKRINT : int,
	M_NVKRINT : real
};
type AVar34 = Var34 ^33 ;
type SVar34 = { 
	 N_ITER : int,
	 Array : AVar34
};

We can see that loops are implemented using arrays of 33 elements (N_ITER has length 5 bits). This is problematic because in practice we will not have a full array but an array of size N_ITER.

We can easily provide a similar representation using SysML datatypes, but the split in different datatypes will produce a model that is hard to read and modify. A solution would be to provide a transformation from SysML to a textual format for reviews.

For variables with special values (ie., enumeration literal values), we can see the following code in SCADE:

type Q_MARQSTREASON = enum { 
	#pragma kcg enum_val 1 #end Q_MARQSTREASON_Start_selected_by_driver ,
	#pragma kcg enum_val 2 #end Q_MARQSTREASON_Time_before_reaching_preindication_location_for_the_EOA_or_LOA_reached ,
	#pragma kcg enum_val 4 #end Q_MARQSTREASON_Time_before_a_section_timer_or_LOA_speed_timer_expires_reached ,
	#pragma kcg enum_val 8 #end Q_MARQSTREASON_Track_description_deleted ,
	#pragma kcg enum_val 16 #end Q_MARQSTREASON_TAF_up_to_level_2_or_3_transition_location 
};

This concerns variable Q_MARQSTREASON, however enumeration literals cannot have values in UML and SysML. Thus we can expect that SCADE system SysML importer will not produce this kind of code. Here we need to ask a SCADE / SysML expert how this can be achieved.

UML model respecting SCADE limitations (future SysML model)

The actual implementation produces a model for subset 026-7. This section shows an excerpt from the model, as previously we focus on:

  • gradient profile packet:

gradient profile packet

  • NID_PACKET variable :

NID_PACKET

  • Q_GDIR variable :

Q_GDIR

We can see that many attributes are stored as comments, this is mainly due to SCADE importer limitations. Moreover this model is simple and has few structural constraints. Some of these comments can be transformed into static attributes but we have no knowledge how this will be handled by SCADE system, and because they are comments in the SCADE example we did the same.

Clone this wiki locally