Altair EEvision Startup by URL & Settings

Startup the Main GUI

The following URL starts the EEvision main GUI:

https://server/eevhome/main.html

… with additional URL parameter (all UTF-8 encoded). These URL parameters control if and how additional filter steps are applied to the EDB data at startup time. The following filter operations are supported:

• filter-by-modules
• filter-attributes
• filter-wire-types
• filter-by-signal
• filter-block

Multiple filters can be applied in one step. In this case, they are executed in the order listed above. Note that applying both filter-by-signal and filter-block has the same effect as only applying filter-block (as long as they are applied with the same flags). To avoid unexpected effects, it is not recommended to apply both filter-by-signal and filter-block simultaneously.

In the table below, the “multiple” check means that this parameter may be repeated to define a list of entities. The right-most column shows links to the service function BuildURLParams that helps building those URLs.

Here are two simple URL examples with only the edb parameter that will start an EEvision session from the EDB file p1/d.edb and d2.edb, respectively:

https://server/eevhome/main.html?edb=p1/d.edb
https://server/eevhome/main.html?edb=d2.edb

Filter by Modules – 100% Filtering

If the EDB file stores a so-called 150% data set, then it includes config/always Modules that refer to sub-sets of the contents. A set of those modules usually defines a so-called 100% sub-set of the data. This set of modules must be given to perform a 100% filtering; either by (a) a set of f=id parameters – each specifying a module by ID – or (b) a set of fv=var parameters – see below. For (a) the caller may get the module IDs from the 150% data set, e.g., by direct JSON access.

As an alternative to the f= parameters, the proper set of modules can also be specified by Boolean expressions, stored in each config Module's "␣expr" attribute. Each of these expr attribute is evaluated to true or false, if it is true, then this config Module is taken to be part of the filtering, otherwise it is not. In this mode, the always Modules are always part of the filtering. The Boolean expression is based on variables that are either given by the fv=var parameters (interpreted as true) or not (interpreted as false). These Boolean expressions support and/or/not operators and > and < operators to compare integer numbers. For those comparisons, an integer can be assigned to the given parameters like fv=var=number.

Filter Attributes – Language Selection

The Language Selection can only address the objects' attribute values and the objects' names. Here, we only describe the recommended default mode famo=2. If the EDB file maintains multiple languages, then it stores multiple attribute values (one per language), and multiple object names (one per language). The target language is selected by the URL parameter fattr=suffix, for example fattr=(de).

Object attribute: In the EDB, each object stores an arbitrary number of attributes. Multi-language support for object attributes comes by selecting one object attribute from a set of object attributes, assuming the attribute names follow the pattern “basename(lang)”. Example:

Desc(en) = brake control unit
Desc(de) = Bremssteuergerät
Desc = brake controller
Desc(fr) = calculateur de frein
Desc(hun) = fékvezérlő egység
Desc(hebrew) = יחידת בקרת בלמים
Desc(chn) = 制动控制单元

Desc = יחידת בקרת בלמים

Desc = brake controller

Object name: In the EDB, each object stores one name only – so multi-language support for object names comes with a set of object attributes with empty basename. Example:

(en) = ignition
(de) = Zündung
(fr) = allumage
(hun) = gyújtás
(hebrew) = הַצָתָה
(chn) = 点火

Filter Wire Types

The wire type filter allows to remove all wires of certain types. For instance, all logical nets (i.e., connections between cavities whose physical implementation with inliners, splices, and eyelets has not yet been determined) can be removed, keeping only the physical wires; similarly, all power and ground wires can be removed.

To do so, those wire types need to be listed that should be preserved. For instance, removing power and ground wires is done using the following parameters: fwt=-undef&fwt=-bus&fwt=-logical&fwt=-hv.

The following types are available:

-undef

all wires without an explicitly defined type.

-power

power wires.

-ground

ground wires.

-logical

wires describing logical (rather than physical) connections.

-bus

wire that are part of a bus (like CAN or LIN).

-hv

high-voltage wires.

Filter by Signals – Logical Mode

In logical mode, all electrical connections between device cavities (i.e., all components except inliners, splices, and eyelets) are merged into single nets, even if they encompass several wires. The intermediate objects, i.e., inliners, splices, and eyelets, which are used to establish electrical connections between wires, are removed and replaced by direct connections. The result is a view of the system that shows only devices and the electrical connections between their cavities.

For assigning names to the abstract electric connections, the name of a wire attribute can be specified as fsig=attrName. The value of this attribute is used as the name of the merged wires. If the value of this attribute is not the same for all electrically connected wires, the different values are concatenated, separated by slashes, to get the name of the net. If no attrName is specified, the resulting connections in the logical view only get a name if they correspond to exactly one wire in the original database.

The parameter fsigf allows to specify different options, e.g., to ignore all ground wires. The available options are:

-ignore-ground

The filtering will ignore interconnected ground wires (EdbWireTGROUND) when creating logical nets.

-ignore-power

The filtering will ignore interconnected power wires (EdbWireTPOWER) when creating logical nets.

-ignore-arcs

Ignore arcs (electrical connections between the pins of a component) when computing the logical view of a database. In this case the arcs are added to the database without modification.

-open-inliners

Preserve “half” inliners, which have connectors without partners. They are typically connection points where a cable harness can be extended.

-default

Normal behavior (as if no option is given).

Filter Blocks – Block Mode

EEvision's block mode provides an abstract view on the connectivity of a data set. All devices (i.e., all components except splices, eyelets, and inliners) are replaced by boxes. Two of these boxes are connected by a wire if there is some electrical connection (possibly via inliners, splices, or eyelets) between them.

Filter Blocks accepts the same flags as the fsigf parameter of Filter by Signals except -open-inliners.

If EEvision starts with fblock, then the configuration settings "powerWire" and "groundWire" are forced to "stub" regardless of the settings in the eev.conf (this is done to display power/ground stub symbols, instead of wire routing).

Enable Tool Feature

EEvision can start as EEvisionBasic (tool=basic), EEvisionPro (tool=pro) with optional features signoff, docgen or edbdiff.

Permission API to check for data permissions

If the Tcl file “checkPermissions.tcl” exists in the srv directory (/eevhome/srv/), and if a user-id is given (by HTTP authentication), then that Tcl file is sourced and expected to define the procedure checkPermissions with two parameters, the user-id and the EDB file name. This procedure is called before EEvision reads the EDB file, so it is up to that procedure to grant the permission (just return) or deny the permission (return a Tcl error). Here is a Tcl example for checkPermissions.tcl:

proc checkPermissions {user edbFname} {
    #...
    if {$granted} {
        return
    } else {
        return -code error "Permission denied for $user reading $edbFname"
    }
}

Direct JSON Access

There is an extra CGI Program “json.cgi” that provides REST access to the contents of the (unfiltered) EDB files via the JSON format. This is an alternative to the GUI API functions QueryJsonList and QueryJsonObj, which can be used inside an active EEvision session. The query is passed as a HTTP GET request with the following URL:

https://server/eevhome/srv/json.cgi

This URL accepts the same parameters as for starting the EEvision main GUI (BuildURLParams) plus the following parameters:

Here are some examples:

1. https://server/eevhome/srv/json.cgi?edb=d2.edb
2. https://server/eevhome/srv/json.cgi?edb=d2.edb&jflags=-wire
3. https://server/eevhome/srv/json.cgi?edb=d2.edb&jflags=-flat+-cavity
4. https://server/eevhome/srv/json.cgi?edb=d2.edb&jid=12
5. https://server/eevhome/srv/json.cgi?edb=d2.edb&ff=-full
6. https://server/eevhome/srv/json.cgi?edb=d2.edb&ff=-full&jflags=-wire
7. https://server/eevhome/srv/json.cgi?edb=d2.edb&jflags=-component&jname=U42

The first four and the seventh will return the same JSON data as calls to the API functions QueryJsonList, QueryJsonObj or QueryJsonListByName after starting an EEvision session from https://server/eevhome/main.html?edb=d2.edb:

1. QueryJsonList('');
2. QueryJsonList('-wire');
3. QueryJsonList('-flat -cavity');
4. QueryJsonObj('', 12);
7. QueryJsonListByName('-component', 'U42');

The fifth and sixth example will return the same JSON data as calls to the API functions QueryJsonList after starting an EEvision session from https://server/eevhome/main.html?edb=d2.edb&ff=-full:

5. QueryJsonList('');
6. QueryJsonList('-wire');

Build URL Params

For convenience, there is a JavaScript file urlparams.js that defines a function to build the query section of an URL (where the parameters are) controlled from a simple set of key-value pairs.

function BuildURLParams(def, oldquery);

The def argument's key-value pairs define certain parameter to be added to the URL. The return value is an encoded query section of an URL (parameter string), ready to be appended to the base, like:

var def = { ... };
var query = BuildURLParams(def);
var url = 'https://server/eevhome/main.html?' + query;

update mode: If the optional argument oldquery is given, then BuildURLParams runs in update mode. The oldquery specifies the current URL parameters, as available from window.location.search (without leading “?”). In this case, BuildURLParams returns an updated version of oldquery and the def argument's key-value pairs define three states: not mentioned keys are kept unchanged (as in the oldquery), keys with null values are removed, and keys with other values are added. The typical usage (in update mode) is here:

var def = { ... };
var oldquery = window.location.search.substr(1);
var newquery = BuildURLParams(def, oldquery);
var url = window.location.origin + window.location.pathname + '?' + newquery;

The following def argument's key-value pairs are supported:

The following ff flags are supported:

-full

If specified, then there should be no idList (it would be ignored). With -full, the filtering is done as if all config/always Modules (those with type -config or -always) were specified. This usually leads to a 150% situation. There is a difference to just not filtering in one little aspect: if all the config/always Modules together do not cover all data stored in the EDB, then filtering will remove them.

-pwire

If specified, then (after filtering by modules) a post-process will check for parallel wires and will remove them – actually merging parallel wires into one. Parallel wires are identified by the same multiterm connections on both sides – or by connecting the same Splice elements.

The following fsigf flags and fblock flags are supported:

-ignore-ground

the filtering will not merge interconnected ground wires (EdbWireTGROUND) into logical nets

-ignore-power

the filtering will not merge interconnected power wires (EdbWireTPOWER) into logical nets

-halfdots

Assume that all halfdot cavities (EdbCavityTHALFDOT) of a component are electrically connected.

-default

normal behavior (as if no option is given).

Register URL Params

If the number of f or fv parameters is high, then the resulting URL may become too long for most Web Browsers. This long URL can be shortened by passing those parameters to the Web Server with a HTTP POST to register them. This set of parameters is then referred to with a short-cut, specified as new parameter flnk. The JavaScript file urlparams.js defines the function RegisterURLParams.

function RegisterURLParams(query, doneFunc[, proxyBase]);

The query argument is a given query section of an URL as returned by BuildURLParams or the current URL parameters as available from window.location.search (without leading “?”). After the registration, the modified query section is returned as value (first argument) in the doneFunc(). In case of an error, the second argument (the error message) is set. Here is an example:

const def = { ... };
const query = BuildURLParams(def);
let url;
if (query.length < 100) {
    url = 'https://server/eevhome/main.html?' + query;
} else {
    RegisterURLParams(query, function(value, errmsg) {
        if (errmsg) { console.error(errmsg); return; }
        url = 'https://server/eevhome/main.html?' + value;
    });
}

Internally, this function queries the CGI program srv/proxy.cgi. However, in case the function is called outside of an EEvision session (e.g., in the main HTML document in order to generate the URL to initialize the EEvision session in an iframe), the proxy CGI does not necessarily have to be located in the srv directory relative to the caller environment.

Therefore, a third optional argument proxyBase can be specified to define the path prefix of the proxy CGI relative to the document, which provides the RegisterURLParams function (default is “srv/”).

Conversely, previously registered URL parameters can be queried by using the GetURLParams function.

function GetURLParams(link, doneFunc[, proxyBase]);

The link argument specifies the name of the link file containing the URL parameters (as returned from the RegisterURLParams function). An array of URL parameters is returned as value (first argument) in the doneFunc(). In case of an error, the second argument (the error message) is set. Likewise to RegisterURLParams, the optional proxyBase argument specifies the path to the proxy CGI executable.

Selection Pages

The following startup pages are available to choose an EDB file (or a set of KBL files) before starting the main GUI. They are pretty simple examples and can be replaced easily by a customer solution.

https://server/eevhome/fileselect.html
https://server/eevhome/fileupload.html
https://server/eevhome/kblselect.html
https://server/eevhome/kblupload.html
https://server/eevhome/filter.html
https://server/eevhome

The first URL is a file selection page to choose from a set of EDB files located in the Web Server's dataRoot directory to start an EEvision session. The seconds URL is a file selector to upload an EDB file from the local PC's file system (where the Web Browser is running) in order to start an EEvision session for it (internally using the /eevhome/srv/upload.cgi program).

The third and forth URL are file selector and uploader for dealing with KBL-Files instead of EDB files.

The fifth URL is invoked indirectly from the selection pages above to additionally perform some filtering before starting the main GUI – including the so-called 150% to 100% filtering.

The sixth URL (referring the base directory) is internally redirected to “fileselect.html” (the first URL), assuming this redirection is configured as Start Page.

The diagram (on the right side) illustrates how the EEvision GUI in main.html is started from the five "selection pages" listed above. They all pass details to the main.html via URL parameters, so it is also easy to startup the EEvision GUI in a customer environment bypassing the selection pages.

The EEvision Start Modes

The EEvision's Logical, Block and Wire Modes (that can, e.g., be started from the tool-bar's More menu) are actually full restarts of the EEvision session. Each red arrow (in diagram on the right side) represents a Web-Browser page load, controlled by a URL with parameters.

The fattr controls the filter-attributes process (that is used, e.g., for Language Selection). The f or fv control the filter-by-modules process (that is used for 100% filtering). The fsig and fsigf control the filter-by-signal process (that is used for Logical Mode). The fblock controls the filter-block process (that is used for Block Mode). The fwt controls the filter-wire-types process (that is used for Wire Mode). When starting one of this three modes from the tool-bar's More menu, the other URL parameters (fattr, f, fv, edb) are forwarded 1:1.

Home: In addition to these URL parameters, there is also an optional home parameter that stores the Home-URL to be used by EEvision's Home button, for returning to the corresponding "selection page". This Home button preserves also the fattr parameter (that is used, e.g., for Language Selection) and passes it back to fileselect.html. However, other parameters (responsible for other filter tasks) are not passed back and so get lost for the next EEvision start. The fattr parameter, if available, is passed through all red arrows in the diagram on the right.

THE CONFIGURATION FILE

Unrelated to any (potentially needed) Web Server configuration, there is an optional eev.conf file that can be used to configure the behavior and preferences of the EEvision GUI, (aka EEvision Settings). At initial startup, EEvision checks for this eev.conf at two locations, first in the directory of the edb file (as defined by the edb= URL parameter) and second in the tools eevhome directory, at https://server/eevhome/eev.conf. There is a little gray circuit indicator character in the EEvision Settings Dialog that shows the source of these settings: Ⓑuilt-in, Ⓜain eev.conf (in eevhome), Ⓓata eev.conf (in the same directory as the edb file), from the Browser Ⓗistory, and only for the plugins: from the Browser Ⓒookie. The eev.conf must be in JSON format. The string values must not include a newline (\n) or tab (\t) character, also the array of strings. Here is an example eev.conf – as shipped with the release package – that shows all supported config keys with their built-in default values or highlighted if the value is only defined in the eev.conf but not as built-in default value. The gray entries define the initial colors for the Settings Dialog only, but not the wire colors themselves.

{
    "searchMax":   20,
    "searchAttrs": [ "Desc", "PartNo", "Alias", "Signal" ],
    "searchAny":   true,
    "extractMax":  0,
    "multicores":  "none",
    "selectColor": "#d4772a",
    "preciseAppear": 1,
    "startColor":  "#1a1aff",
    "wireMark":    true,
    "wireTop":     false, "wireTopAttr": "Signal",
    "wireBot":     false, "wireBotAttr": "Diameter",
    "wireBotFmt":  "",
    "wireFilter":  [ "-undef", "-power", "-ground", "-bus", "-hv" ],
    "compAttrdsp": [ "Desc" ],
    "connAttrdsp": [],
    "cavAttrdsp":  "Desc",
    "signalAttr":  "Signal",
    "powerWire":   "std", "powerWireCol":  "#ff0000", "powerWireEx":  true,
    "groundWire":  "std", "groundWireCol": "#88540b", "groundWireEx": true,
    "logicalWire": "std", "logicalWireCol":"#8080ff",
    "busWire":     "std", "busWireCol":    "#00ff00",
    "hvWire":      "std", "hvWireCol":     "#ff8c00",
    "rotate90":    false,
    "showToolbar": true,
    "license":     null,
    "space4wirelabel": false,
    "autoOptimize": 0,
    "markioEx": false,
    "explodeSplices": true,
    "plugins":     [],
    "debug":       0
}

THE EEVISION SETTINGS

At startup, the EEvision Settings are taken from the configuration file eev.conf, but can be manually overwritten with the EEvision's Settings Dialog. They are stored in the Browser history – this means the Settings may change with the Browser's back button – and can be saved to or loaded from an external file on the Browser PC with the Save or Load button. The list of the supported settings with their built-in defaults are listed above and some details are below.

Controlling the plugins: please don't confuse, the EEvision's Settings Dialog also control the active plugins, that are also initialized from config.plugins, and can be manually overwritten, but they are NOT part of the Browser history and stored in a Browser Cookie (to make them permanent). There is a “Default” button to delete this Cookie to re-apply the default plugins as defined in config.plugins at the next startup.

Details: the EEvision Settings control the behavior and appearance of the EEvision Main GUI – and partly of the behavior of the GUI API. Here are the most important config items with [JSON-type] and some description:

searchMax [integer]

The search function's result list is limited to the given number of entries (or unlimited if 0).

searchAttrs [array]

The search function always searches objects by their names and by their attributes' values – but consider only those attributes whose names are listed here.

compAttrdsp [array]

When displaying ECU, SVG, UNDEF or INLINER Components, their names will be displayed at the top of the symbol body plus the values of the component attributes listed here. (The compAttrdsp defines a list of attribute names).

connAttrdsp [array]

When displaying Connectors at ECU, INLINER or HIER Components the values of the named connector attributes are also displayed – below the connector. (The connAttrdsp defines a list of attribute names).

cavAttrdsp [string]

At each cavity pin, the value of the named cavity attribute is displayed at the inner side aligned to the pin. (The cavAttrdsp defines an attribute name).

signalAttr [string]

This setting defines a wire attribute, that is only consulted when computing the logical view – as done when restarting the EEvision GUI with the URL parameter fsig=signalAttr – meaning the signalAttr value is passed to the fsig parameter (this logical view is, e.g., triggered from the Logical button in the More menu). If this signalAttr setting is not specified, then an empty string will be passed to fsig.

multicores [string]

This enumeration defines the display of multicores (shielding and twisting trees). It supports the values “none”, “bundle” (display as one bundled wire), “basic” (display the tree as long as it is not too complicated), “full” (display the tree, no matter what it costs).

wireTop [bool] & wireTopAttr [string]

The wireTop is a switch to enable/disable the display of a label above each wire. The label is taken from the wire attribute whose name is given by the wireTopAttr setting.

wireBot [bool] & wireBotAttr [string] & wireBotFmt [string]

The wireBot is a switch to enable/disable the display of a label below each wire. The label is taken from the wire attribute whose name is given by the wireBotAttr setting. The wireBotFmt is a string. It must be empty, or one color (defining the background color of the displayed attribute value) or two colors separated by a space (defining the background and foreground colors of the displayed attribute value). For example wireBotFmt = "#ffd080 #000000" displays the attribute value black on beige background.

wireMark [bool]

The wireMark is a switch to enable/disable the display of the wire color(s) centered on each wire. The wire color is taken from the wire attribute whose name is “ color” (see also the reserved attributes).

wireFilter [array]

The wireFilter is a list of wire types. It is used to determined which wires to preserve when switching to wire filter mode. All wires whose type is not listed in the array are removed by the filter step. Allowed types are: "-undef", "-power", "-ground", "-bus", "-logical", and "-hv".

autoOptimize [integer]

The autoOptimize setting can be used to automatically optimize the vertical layout of the schematic (similar to the Optimize button in the main GUI) after incrementally adding new objects or expanding/collapsing connectors. Possible flags (values can be combined) are:

• 0x1: Optimize after adding new objects (by double-click or with EEvisionAPI.AddObj or the + in main GUI's live-search result window).
• 0x2: Optimize after expanding/collapsing connectors (with the +/- buttons of the connector).
• 0x4: Optimize after unfolding/folding hierarchical components (with the +/- buttons of the component).

The default is 0, no automatic optimization.

markioEx [bool]

The markioEx Boolean switch controls if small direction arrows are added to the wires to identify the flow of a path from the smartstop objects to the start object. This only works for smart extraction, see also the GUI-API EEvisionAPI.ExtractOne() function and its markio parameter. The default is false, no arrows.

explodeSplices [bool]

The explodeSplices Boolean switch controls if Splices are displayed with all pins (including the currently non-displayed connections). Displaying all pins gives visual feedback in incomplete schematic diagrams, that common with the new smart extraction or with incremental schematic navigation. The default is true in the eev.conf, showing "exploded" Splices.

debug [int]

The debug setting controls the amount of messages displayed in the Javascript console. If debug is on, then reserved attributes are additionally displayed in the info info window.

showArcs [bool]

The showArcs setting controls if EDB Arcs are displayed in the schematic or not. This feature is experimental and is intended for debugging the EDB contents; it requires an additional Load or Extract to come into effect.