EDML — The Electrical Design Modeling Language

Both the Wire and the Cavity statement accept a list of IDs instead of only a single ID like other object declarations. For instance

can be written compactly as follows:

All attributes and properties in such a definition refer to all IDs in the statement, i. e.,

creates three wires that have a red color marker and an attribute Diameter with value 2 mm.

In particular the cavities of a connector are often numbered sequentially. Generator expressions provide a convenient way to create wires and cavities. Their syntax is

where <PREFIX> and <SUFFIX> are arbitrary (possibly empty) strings consisting of digits, letters, and underscores; <n> and <m> are integer numbers with 0 ≤ n ≤ m.

This expression is equivalent to writing

For instance, W(1:5)_out yields W1_out, W2_out, W3_out, W4_out, W5_out. The following listing shows how these generator expressions are used.

The first line generates ten wires W1_out, W2_out, …​, W10_out. Similarly, Line 5 yields ten cavities at the connector A of component S1; their IDs (and names) are 1, 2, …​, 10. The second Cavity statement in Line 10 creates cavities with IDs and names x1, x2, …​, x10.

Line 6 (Join (1:10) → W(1:10)_out;) connects all ten cavities of S1 to the ten wires. The first element of the left generator expression is connected to the first element of the right one, the second to the second etc. Therefore the generator expressions left and right of the arrow need to have the same width; otherwise the compiler reports an error. As we can see in Line 11, the ranges of the two generator expressions do not have to be the same, only their widths have to match.

The resulting schematic is shown in Figure 2.

Every object (wire, component, connector, cavity, multicore, module) in an EDML file can be enriched with an arbitrary number of user-defined attributes. An attribute is a name–value pair, where both name and value can be arbitrary strings, enclosed in double quotes and separated by an equality sign. Note that attributes whose name starts with a space character are reserved for internal purposes. Both name and value of an attribute may consist of several lines of text. The lines need to be separated using \n. If the name or value contains a double quote, it must be specified as \". Several attributes with the same name are allowed.

One can access the additional information in EEvision by selecting the object and then opening the info window or by opening the balloon window with a right-click on the object (the latter requires the “balloon” plugin to be activated).

To see the effect of attributes, let us replace in Listing 1 the first line Wire W1; with the following code:

Then EEvision displays the schematics as shown in Figure 3 (here with the attributes listed in the balloon window).

In contrast to attributes, properties influence how objects are displayed in EEvision. Besides the property Name, we have already seen the property Type in Listing 1:

It tells the compiler that we want to see a twisted pair of wires. If we replace this line by

the two wires are displayed as shielded instead (cf. Figure 4).

Properties look similar to attributes, but they have fixed names that are not enclosed in double quotes. The value of a property is either pre-defined and not enclosed in quotes (like in Type=twisted) or a user-defined string, written in double quotes (like Name="Temperature Sensor"). Sometimes the user-defined string needs to follow a certain syntax, for instance, the Color property of components requires that the value is a color description. So it must be either one of the pre-defined color names like red or palevioletred or a hexadecimal RGB-value like #FF0000 (the same as red) plus an optional transparency specifier like in #FF0000/7F or red/50% for half-transparent red.

Which properties are supported depends on the type of the object (with the exceptions listed below in Table 1). Also the allowed values are often specific for the object type. We provide a table with the supported properties, their allowed values, and their meaning when we describe the different objects.

The following table lists those properties that are supported by all object types. The first column contains the name of the property, the second column the allowed values. An entry "string" means that an arbitrary string is supported; "syntax" stands for a user-defined string that needs to have a certain format. Otherwise the supported fixed values are listed. The column "Repeat" specifies whether the property is allowed to occur multiple times at the same object or not.

The Name property has already been introduced in Section 3.1. The three properties Href, Image, and Video are used to generate special kinds of attributes, which are shown in EEvision in the info window and the balloon window. Their syntax is a follows:

Consider the following example:

Figure 5 shows the resulting entries in the balloon window of EEvision.

Finally, the property Subtype allows to assign to each object a sub-type, which is used by EEvision to group objects of the same type (Wire, Multicore, etc). The sub-type does not have any influence on how objects are rendered.

Not only the objects in the database can be equipped with attributes and properties, but also the database itself. Adding database attributes is done using the Attributes statement.

This example creates two root attributes Author with value John Doe and Revision with value 1.1-beta. Additionally, it uses the property Index to tell EEvision (or rather its file select page) to list the values of the attributes Author and Revision when displaying the dataset details is enabled. To do so, the attribute names are listed as the value of the Index property, separated by tabulators. Note that tabulators are specified in EDML as \t.

Besides the properties listed in Table 1, the following root property is supported:

The basic device is created using the keyword Component. It is typically used for ECUs, sensors, motors, and many more. The main characteristic is that wires are connected to such a device via connectors. Examples of such components are contained, e. g., in Listing 1 and Listing 5.

Besides the general properties in Table 1, Component objects support additional properties, which are listed in Table 5.

The Color property is used to assign a certain color to the component. It follows the same syntax as the Color property of wires (see the syntax description following Table 3) with the exception that one or two color values are accepted. In case of a single value, it specifies the component’s fill color; if two values are given, the first is the fill color, the second the border color. If only the border color should be set, the first color may be specified as “?”.

The property Imagedsp (do not confuse it with Image!) can be used to display an SVG, PNG, or JPG image inside the components body. The format of the string is one of the following three possibilities:

where <filename> is the name of the image file; <width> and <height> are dimension-less numbers specifying width and height of the image in pixels. If <height> or both are missing, 100 is used as the default.

For instance, a component with a small “Motor” icon could look as follows:

EEvision is shipped with a few built-in symbols, loosely following the German standard DIN 40719-2. All of them have a one letter name, which is specified in the Imagedsp property without file extension. That means Imagedsp="A,50,50" uses the built-in symbol A, while Imagedsp="A.svg,50,50 uses the user-provided file A.svg for the symbol.

Table 6 shows the list of available symbols.

LComponent objects are very similar to Component object, but do not have any connectors. The cavities are not grouped and can permute freely in order to minimize wire crossings. They support the same properties as Component objects. The same holds for their cavities. Also arcs are supported at LComponent objects.

Listing 13 shows an example how LComponent objects are created.

Inliners represent two cables that are connected to each other via connectors. Therefore they contain connectors and partnered cavities as shown in Listing 14. They keyword Inliner is used to create such an object. Connectors and cavities are added in the same way as to a Component object. However, we need to specify, which cavities on the two sides of the inliner are partnered (i. e., electrically connected). This is done using the keyword Partner.

In rather rare cases, an inliner can have more than one connector per side. In this case, the partner information alone is not sufficient, but we also have to tell EEvision which connectors are placed on the same side. Providing this information is the purpose of the connector type anti. All connectors on one of the two sides need to get this Type=anti flag as in the following example:

Splices and Eyelets are used to establish an electrical connection between several wires. In EDML they are created using the keywords Splice and Eyelet, respectively. Both of them do not have connectors, but only cavities, as shown in Listing 15. Typically, both splices and eyelets get one cavity per wire that is connected to them. Cavity names of splices are not displayed in EEvision; cavity names of eyelets are. If this is not wanted, the name of eyelet cavities need to be explicitly removed as shown in Listing 15.

EEvision offers the possibility to have user-defined symbol shapes for components. Such components have to be declared with the keyword SVGComponent. As the name of the keyword suggests, the outline is typically given by an SVG image that is displayed as the component’s body. Then mainly the positions of the cavities need to be declared.

An SVGComponent (like an LComponent) does not have connectors.

For details about the Symlib language, we refer to the Nlview documentation.

EEvision allows to display the value of arbitrary attributes as labels at components, connectors, and cavities (at cavities only for components of type Component and LComponent). In the following example we use the value of the attribute Desc as the label value at components, connectors, and cavities. Note that the default configuration of EEvision in the file eev.conf needs to be adapted accordingly. The configuration keys compAttrdsp and connAttrdsp expect a list of attribute name; the values of the specified attributes are displayed, separated by newlines. In contrast, cavAttrdsp expects a single attribute name.

Then the following listing create two components with labels at the components, their connectors and cavities:

Labels are possible at all types of components, the connectors of Component, Inliner, and HierComponent objects (except invisible connectors), and the cavities of Component and LComponent objects.

It is a very common situation that a whole component together with all of its connectors and cavities has to be added to a module. Listing all connectors and cavities explicitly is both time consuming and error prone. For this case, EDML offers a shorthand notation.

Consider the following example:

It creates a function module that contains the components Sensor and Actor together with their connectors and cavities as well as both wires W1 and W2.

In this case we could also write

The ` following a component ID means that we want to add the component, all of its connectors, and all cavities to the module. Similarly, `Sensor.A would add the connector A of Sensor with all its cavities to the module. If we add ` as a suffix to a wire ID like `W1, the wire, all cavities it is connected to plus their connector and component are added. In our example, W1+ is equivalent to W1, Sensor.A.x, Sensor.A, Sensor, Actor.X.1, Actor.X, Actor.

This shorthand notation is possible for all types of modules. Duplicate objects are only added once.

A hierarchical box is created using the keyword HierBox. It has neither connectors nor cavities; attributes and properties can be specified as usual. The content of the box follows after the keyword HierContent in curly braces:

The properties Name, Href, Image, Video, and Color are supported. The latter is used to color the body and/or the border of the box; by default, HierBoxes have a transparent background.

Wires may cross the boundaries of a HierBox, i. e., the same wire can connect to cavities outside of a HierBox and within a HierBox. For this to work, the wire has to be declared on the deepest hierarchy level that contains all cavities the wire is connected to. The following example illustrates how to create wire connections.

Compared to the simple HierBox components, the structure of hierarchical ECUs is quite similar to Inliner components with partnered connectors/cavities on the outside and the inside. Connectors whose type includes the flag anti are inside the hierarchical component, connectors without that flat on the outside. The Partner statement is used to partner corresponding cavities on the outside and inside.

The contents of a HierComponent are declared within a HierContent block, similar to HierBoxes. Besides the components, wires, and multicores that are declared within the HierContent block, the cavities of those connectors of the parent HierComponent that are declared with the anti flag can be access from within the HierContent block as part of a Join statement.

Wires may not cross the hierarchy border. A wire may only connect to cavities of components that are declared on the same hierarchy level or to cavities of the parent HierComponent whose connector’s type includes the flag anti.

The following example illustrates how to create a HierComponent.

In order to keep models readable and well structured, EDML allows to split a model into several files using the #include directive. The effect of an #include directive is that the EDML compiler replaces the line

with the contents of the referenced EDML file (which can also contain #include statements as long as there are no cycles). This mechanism is particularly handy combined with the possibility to define new component types as we have already seen in the introductory example. While arbitrary parts of the model can be moved to their own file, the include mechanism is typically used to include definitions of new component types, as described in the following section.

EDML not only provides the built-in component type Component, LComponent, SVGComponent, HierComponent, Splice, and Eyelet, but also allows users to define their own component types as refinements of the built-in ones.

For instance, consider the following EDML code:

It defines a new component type Sensor, which is a refinement of the built-in type Component. As we can see in Lines 13 and 16, we can create new components using the newly defined type Sensor. In this case, we obtain two components named S1 and S2, both with the property Color="yellow" and two connectors A and B, which are both male and have two cavities 1 and 2. Connecting wires to these components works in the same way as with built-in types.

So the effect of a Define statement is that the defined type is replaced by the compiler with its definition; only the ID is replaced with the ID of the defined object.

If we define new component types as described in the previous section, all instances of these types share all properties and attributes. However, in practice some of these properties and attributes need to get instance-specific values. EDML allows to add parameters to Define statements, which can be set when a user-defined component type is instantiated.

Parameters need to be declared in the Define statement after the name of the new type using the keyword Parameter, followed by a list of parameter names. The syntax of parameter names is the same as the syntax of object IDs. We can assign default values to parameters.

Listing 25 shows an example of a type definition that contains the parameters col, loc, harA, and harB; col, harA, and harB have default values: the default value of col is "yellow", the one of harA and harB is empty. Parameter without default values need to be specified when instantiating the component type. In contrast, parameters with default value can be omitted; in this case the take their default value. A special case of a value is the empty value (in the example: harA=, harB=). If a parameter has an empty value, the property or attribute that is assigned this value is omitted from the created object.

The declared parameters can be used in the component definition as the value of attributes and those properties that expect a string as their value; they can not only provide string values in the component itself, but also in its connectors and cavities, i. e., for everything within the curly braces of the Define statement. For obtaining the value of a parameter, its name is prefixed with a dollar sign ($col, $loc, etc.). Writing Color=$col assigns the value of the col parameter to the property Color.

Parameter assignment happens when a Sensor component is created (see Lines 14 and 19 of Listing 25). The syntax is the same as for properties: after the vertical bar |, the parameters are assigned; the parameter name is specified without quotation marks, followed by an equality sign and the parameter value. Note that parameter names must be different from the property names.

The executable of the compiler is named edml2edb (Linux/Unix) and edml2edb.exe (Windows), respectively. It can be found in the directory edb/ of the EEvision distribution. Note that it requires an EEvision PRO license for running.

The command for calling the compiler looks as follows:

where <design.edml> is the name of the input file. The compiler offers the following options:

The -srcref option deserves particular attention. It is used to facilitate debugging an electrical design in EEvision. If this option is specified when calling the compiler, the generated EDB file contains for each object the file name and line number where the object is created in the EDML model. This information makes it easy to identify the location in the EDML file that needs to be adjusted when errors in the model are found.

The option -srcref is used only during development. When the EDB file is released after having passed all checks, this option should be omitted.

The edml2edb compiler is an optional component of EEvision, which requires a separate license for running. Please refer to the EEvision documentation for licensing details or contact the EEvision support team of Altair Engineering.

The extension can be found in the EEvision package in the directory vscode. Its file name is edml.vsix. There are two possible ways to install it in Visual Studio Code:

Either on the command line by executing the following command in the directory that contains the extension file:

Alternatively, you can use the Install from VSIX command in the Extensions view command dropdown, or the Extensions: Install from VSIX command in the Command Palette. Then select the edml.vsix file.

For more information, see the official documentation on installing packaged extensions in Visual Studio Code.