![[EEvision Startup]](img/EEvision_Startup.png)
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.
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:
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.
| parameter | multiple | description | Build URL Params | |
|---|---|---|---|---|
| edb=filename | the name of the EDB file, that is opened for the session. The filename must be relative to the Web Server's dataRoot. This edb file can be protected by the permission API. | def.edb | ||
| f=id | ✓ | enables the filter-by-modules post-process; the id defines a Module. | def.f | |
| fv=var | ✓ | enables the filter-by-modules-by-expression post-process; the var defines a variable to the module's Boolean expression. | def.fv | |
| ff=flag | ✓ | specifies additional flags to the filter-by-modules or filter-by-module-by-expression post-process; | def.ff | |
| famo=num | defines a mode for the filter-attributes post-process (deprecated). | def.famo | ||
| fattr=suffix | enables the filter-attributes post-process; by specifying the suffix to attribute names. | def.fattr | ||
| fwt=wireType | ✓ | enables the filter-wire-types post-process; by listing the types of wires that should be preserved. | def.fwt | |
| fsig=attrName | enables the filter-by-signal post-process; by specifying the signal attrName (attribute name). | def.fsig | ||
| fsig | enables the filter-by-signal post-process; by specifying no signal attribute name (def.fsig empty string). | |||
| fsigf=flag | ✓ | enables the filter-by-signal post-process; by specifying additional flags. | def.fsigf | |
| fblock | enables the filter-block post-process; without additional options. | def.fblock | ||
| fblock=flag | ✓ | enables the filter-block post-process; additional flags can be specified. | ||
| tool=flag | ✓ | enable the features to run as the tool/app as identified by the given flags. This defines the Altair License that is requested at startup. | def.tool | |
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
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.
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) = 制动控制单元For this example, the URL parameter fattr=(hebrew) would replace the 7 attributes above with the single one
Desc = יחידת בקרת בלמיםwhereas the URL parameter fattr=(greek) could not find any match and would remove the 6 language attributes above and just preserve the default one:
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) = 点火For this example, the URL parameter fattr=(hebrew) would replace the object name with הַצָתָה and remove the 6 language attributes above, but the URL parameter fattr=(greek) could not find any match and would just remove the 6 language attributes above but let the object name unchanged.
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:
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.
The parameter fsigf allows to specify different options, e.g., to ignore all ground wires. The available options are:
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.
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).
EEvision can start as EEvisionBasic (tool=basic), EEvisionPro (tool=pro) with optional features signoff, docgen or diff.
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"
}
}
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:
| parameter | multiple | description | ||
|---|---|---|---|---|
| jid=id | the id of the EDB object – if given, then the GUI-API function QueryJsonObj(flags,id) is executed and the result will be a JSON object. | |||
| jname=name | the name of the EDB object(s) – if given, then the GUI-API function QueryJsonListByName(flags,name) is executed and the result will be a JSON list of objects. | |||
| jextr=id | the id of an EDB Cavity (or Connector or Component) object – if given, then it is used as a start point for an extraction, performed by the GUI-API function ExtractOne(id,doneFunc). The result is returned as a JSON list of component and wire objects, with any jflags applied as for the QueryJsonList function. | |||
| jextr=id | ✓ | if more than one EDB Cavity id is given, then they are used as terminal points for an n-way shortest path extraction, performed by the GUI-API function ExtractPaths(idList,doneFunc). The result is returned as a JSON list of component and wire objects, exactly as above. | ||
| jesig=id | the id of an EDB object – if given, then it is used as a start point for a signal extraction, collecting a network of interconnected wires, splices, inliner, etc. The result is returned as a JSON list of component and wire objects, with any jflags applied as for the QueryJsonList function. | |||
| j150 | a switch – if given, then the Boolean expressions in all modules' " expr" attributes are analyzed and returned as a Json list of the used Boolean variable names. These are the same variable names that can be given to the fv URL parameters. | |||
| If none of jid, jname, jextr, jesig or j150 is given, then the GUI-API function QueryJsonList(flags) is executed and the result will be a JSON list. | ||||
| jflags=flags | the “jflags” parameter is optional, if set, then it can define a blank-separated list of flags to control the JSON result exactly as supported as “flags” argument to the QueryJsonObj, QueryJsonList and QueryJsonListByName GUI-API calls. | |||
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');
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:
| key | type | description |
|---|---|---|
| edb | string | defines the name of the EDB file, that is opened for the session. The value string is the filename, that may include directories and must be relative to the Web Server's dataRoot. For example: edb: 'dir/file.edb'. |
| key | type | description (100% filtering by config modules) |
| f | list of integer | enables filter-by-modules from the given modules. The value is a list of module ids. For example: f: [3, 15, 32]. |
| fv | list of strings | enables filter-by-modules-by-expression (to be matched against the Boolean expression, expected in module's " expr" attribute). The value is a list of variables, that is used to evaluate each module's Boolean expression to true or false. Each variable can be just a name (to set it true) or name=value to set it to an integer value. The fv is mutually exclusive with f above. For example: fv: ['alpha', 'beta=12', 'gamma']. |
| ff | list of strings | specify additional flags for filter-by-modules. The value is a list of flags. For example: ff: ['-full']. The supported flags are described below. |
| f fv ff |
null null null |
disables the filter-by-modules (in update mode), no filtering will apply. For example: f: null, fv: null, ff: null. |
|
The parameters f and fv are
mutually exclusive.
The f, fv and ff keys together control, if the data will be filtered-by-modules. If at least one of them is given, then the filtering will apply. If neither of these keys are defined, then (in update mode), the current filtering will stay unchanged. |
||
| key | type | description (language filtering for the attribute values) |
| famo | integer | deprecated: defines a mode for filter-attributes if fattr is given. The default is 2 and only famo: 2 is fully supported. |
| fattr | string | enables filter-attributes. The string value (suffix) defines the class of attributes to be taken, For example: fattr: '(de)'. |
| fattr | null | disables filter-attributes (in update mode). |
| The fattr key controls, if certain EDB attributes will be filtered. If it is given, then it will take effect. If it is not defined, then (in update mode) the current filtering will stay unchanged. | ||
| key | type | description (filter wires w.r.t. their type) |
| fwt | list of strings | enables filter-by-wire-types. The value is a list of wire type flags, which are described above. If the list is empty, then all wires are removed. |
| fwt | null | disables filter-by-wire-types (in update mode). |
| The fwt key controls whether wires of certain types will be filtered out or not. If it is given, then the wire type filter will take effect. If it is not defined, then (in update mode) the current filtering will stay unchanged. | ||
| key | type | description (extract a logical view by following the signals) |
| fsig | string | enables filter-by-signal. The value string is the attribute name (attrNm) passed to the filtering procedure. It may be an empty string if unavailable. For example: fsig: ''. |
| fsigf | list of strings | enables filter-by-signal. The value is a list of flags. The supported flags are described below. |
| fsig fsigf |
null null |
disables filter-by-signal (in update mode), no filtering will apply. For example: fsig: null or fsigf: null. |
| The fsig and fsigf keys together control, if the EDB will be filtered by signals. If at least one of them is given, then they will take effect. If neither fsig nor fsigf is defined, then (in update mode) the current filtering will stay unchanged. | ||
| key | type | description (extract a simplified block view) |
| fblock | list of strings | enables filter-block. The value is a flag that controls the behavior of the filter step. It may be an empty list if unavailable; for example: fblock: []. The supported flags are the same as for fsigf and described below. |
| key | type | description (enable the given feature or all) |
| tool | list of keywords | enables the features identified by the given flags. This defines the Altair License that is requested at startup. It may be an empty list defaults to "basic". The supported flags are basic, pro, signoff, docgen and diff. |
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:
var def = { ... };
var query = BuildURLParams(def);
var 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.
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.
![[EEvision Startup Modes]](img/EEvision_Startup_Modes.png)
The EEvision Start ModesThe 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.
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
}
![[Settings Dialog]](img/settings1.png)
THE EEVISION SETTINGSAt 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:
Copyright © 2019–2024 by Altair Engineering Inc.
All rights reserved.