emGUI

is a stand-alone windowing environment for application-level manipulation with siliXcon devices. It is a GUI counterpart to the yosctl tool.

Functional description

emGUI is built around the tree of managed items - the data model of the device (maintained by its operating system). Using the siliXcon service protocol, emGUI provides a mechanism of dynamically synchronizing the data model as well as content with the device or multiple devices. emGUI holds an internal image of the model together with values and it provides a user interface for its comprehensive reading/writing/importing/exporting/executing.

tip

For a quick start, you may rather want to check our basic emGUI tutorial.

CLI options

emGUI accepts standard connection options. The non-option arguments are treated as file names with SXapi/Python plugin code. If one or more scripts are specified, the emGUI window starts in quiet (hidden) mode. If only a single script is specified, it is run in exclusive mode. Without any scripts, the quiet mode can be still forced by specifying the -q option. In this case, emGUI runs as a daemon and is auto-terminated within 30 seconds (unless a SXapi/Server client establishes a connection).

Main menu

The main menu features a few topics of global program commands/configuration.

info

If a sub-menu item name ends with '...', it suggests that a follow-up dialog will be invoked.

File

The generic (mostly) file-related operations can be triggered there. Namely:

1. Starting a SXapi plugin in either exclusive or non-exclusive mode. Exclusive mode dedicates the global Python interpreter to the single plugin, whereas non-exclusive mode, using sub-interpreters, allows one to run multiple plugins at the same time.
2. Importing/exporting variables to/from a file (for all discovered nodes). This will pop up a dialog that allows directory selection, import/export options, etc. Two shortcut icons are offered in a dock widget for the same operations:

3. Search operation trigger (and discarding of the current tree). The Search shortcut icon is offered in a dock widget for the same operation:

4. Global value push / pull (for all discovered nodes). Two shortcut icons are offered in a dock widget for the same operations (F1 and F2 shortcuts apply):

5. Exit the program

Edit

The tree editing commands and viewing options can be tweaked from here. Namely:

1. Copy&Paste You can export/import all/selected tree(subtree) entries and their values to/from a clipboard (Standard ctrl+c and ctrl+v shortcuts apply).
2. Diff flag Turning on the diff flag will make the tree only show variables whose values have been changed from their defaults. A shortcut icon is offered in a dock widget for this flag:

2. Multi-selection flag enables working with multiple entries at once. This can also be engaged by holding the ctrl key while clicking on an entry. A shortcut icon is offered in a dock widget for this flag:

tip

When Multi-selection is enabled, certain operations are offered in group mode. For exp. exporting/importing, getting/setting or plotting can be triggered on multiple entries at once.

Interface

The communications interface can be selected and configured from here. This menu can be only accessed when the Connection status is Disconnected. Namely:

1. Configuration will open a dialog that will display information about the currently loaded interface driver and a textbox for editing its option string.

   

2. Unload will unload the currently loaded interface driver.

3. (up to nth) These checkable items hold the names of the discovered interface drivers. You may load the one you want.

4. Custom load a custom interface driver by specifying it's path.

Connection

The status of the connection, as well as link addressing, can be manipulated from here. Namely:

1. Connect and disconnect will initialize / deinitialize the link. The Search operation auto-initializes (if loaded and not initialized).

2. Addressing will open up a link-layer addressing options dialog.

3. Protocols shows a sub-menu that allows user to select alternate protocol configuration, if available.

Options

Various, otherwise unclassified global options can be adjusted here. Namely:

1. Authentication will show a pop-up dialog where the user can adjust the authentication token:

   

2. Fixed point base through submenu allows to set the global radix for fixed-point values stringification. Note that string parsing is not affected (base is selected by the prefix e.g. '0x20', '0b101' etc.)

3. Floating point precision through the submenu allows to set of several options for global floating-point values stringification. Note that string parsing is not affected.

4. Search options through submenu offers to toggle several flags for the Search operation.

Help

1. Visit website is a link to the siliXcon website with this documentation. The siliXcon logo on the right features the same function as a button.
2. About Shows a pop-up dialog with the tool description and build version.

tip

The adjusting under Interface, Addressing, Protocols and Authentication is for advanced usage only. The content presented here is already defined in connection options and is passed to the emGUI during start-up (either from the local environment or from the global connection option set).

For basic usage, use LaunchPad to set your connection options.

Status bar

The status bar shows a quick overview of:

• the selected connection options. The color of the interface driver name indicates its loading status.
• the status of the connection. The color of the text value delimits normal and erroneous states.

Log

is a scrolling, read-only, detachable text frame displaying a textual log of significant events; primarily used for debugging. SXapi output is also directed there.

Main tree

The main tree is a depiction of the discovered device(s) and their data model(s). Selected tree nodes may be expanded and collapsed on demand. There are four columns in the tree widgets with distinct content:

• Name A textual representation of the entry identification.
• Type/access The entry type. In case of restricted access, the type will be appended with a string defining rights for the logged user. Logged user is prepended before the node's name.
• Contents A (truncated) evaluation of the data held within the entry. Note that for full display, a distinct dialog for each type is offered.
• Description A (truncated) evaluation of the entry's textual description.

Tree entries

The tree entries represent entities in the network of devices and their data models. The type of entry may be one of:

• node (device)
• floder
• variable
  • state variable
  • parameter
  • permenent variable
  • dynamic variable
• command
• arbitrary data
• i/o device

Only the most used entry types will be discussed here. Each tree entry type has a distinctive context menu, which may be accessed by right-clicking the entry. Double-clicking the entry will open the default entry's view/edit dialog (except for the Folder entry).

Node

The node is the root entry of the tree and is associated with the communication context with the device. The node's dialog displays the main device identifiers. Also, it allows you to configure auto-pull values for the entire device.

info

The Target status field indicates the status of the communication session with the device. The session is safely restored each time you initiate the Search operation, but your dialogs and plugins will lose their context. You may manage the session in the Session submenu and attempt to restore it once lost, without losing your work. The target status is also indicated with the icon (and color) of the node entry inside the tree.

The values are one of :

• READY : up and running
• STALL : waiting for an asynchronous event
• INCONSISTENT : the context between device and emGUI may have diverged
• LOST : communication was lost
• UNKNOWN : communication has not been established

The context menu of the node, apart from opening the node's dialog, features a set of actions related to the entire device. First of all, there is a section of predefined command managers.

• Save / load parameters dialog (on-board saving and loading of parameter values)
• Restore parameters dialog (factory settings by restoring all parameters to their default values)
• Plot manager (for managing the on-board plot service)
• Reboot command trigger
• Session management (where you can manage the existing data emGUI <-> device synchronization session)
• External tools triggering (scope, term, bl_srm)

The next two sections are identical to the ones offered by the Folder's context menu (see below).

Folder

The folder is a branching entry that typically corresponds to a folder inside the device's internal data model. The context menu of a folder, apart from opening the folder's dialog, offers mainly (re)synchronizing model and data of the descending tree:

• Fetch subtree will reload the data model from the device
• Fetch subtree and values will reload the model with values
• Drop subtree will cause forgetting the descending items del
• Pull subtree values will download the variable's values F1
• Push subtree values will upload the variable's values F2
• Drop will forget this item

The last section offers a few editing actions (clipboard and file import/export) for the descending tree:

• Copy variables the through-clipboard export trigger ctrl+c
• Paste variables the through-clipboard import triggered ctrl+v
• Import variables from file the through-file import trigger
• Export variables to file the through-file export triggered

The folder's dialog shows the optional description of the folder. Also, it allows you to configure auto-pull values for the descending tree.

Variable

The variable is a data entry with a well-known type and size. The variable's data (value) and metadata (description) are available for tweaking. Also, emGUI attempts to evaluate the variable's value in the Content column for in-line viewing and editing. The classes of variables are inherited from the YOS system. Each of them has a distinctive viewing/editing dialog (check our tutorials for examples):

• Parameter (read-write with rich presets), only the user can change
• Dynamic variable (read-write), the model can change in run-time
• State variable (read-only), only process can change
• Permanent variable (read-only), non-volatile memory

In all the variable dialogs, as well as in the content column, a special status of the value is indicated by a special color and style of its string:

• Bold : value has been changed from it's default
• Blue : value has not been synced with the device (marked inconsistent)
• Yellow : value has been imported from file/clipboard
• Green blink : value has just been read from the device
• Red blink : value has just been written to the device

In all the variable viewing dialogs, the bad result of the communication with the device regarding value exchange is indicated by a background color of the value's string:

• orange - an arbitration miss. The value exchange has not been successful.
• red - a critical error (no response from device, etc).

info

As mentioned above, the emGUI holds an internal mirror of the device's data model and also the values of the variables. The values are not automatically synchronized with the device. To get and set the value, you need to do a get/set action or push/pull action for the entire device/tree/sub-tree. You can set up automated pull for a part of the tree.

The context menu of a variable, apart from opening the variable's dialog, offers mainly actions to synchronize (get and set) the value from/to the device. Also, there is a shortcut for assigning the variable to the on-board sampling service (plot):

• Plot will allow (through sub-menu) to assign the variable to the on-board sampling service (plot).
• Get value will download the value from the device.
• Set value will upload the value to the device.
• Drop will forget this item

The last section offers a few editing actions (clipboard and file import/export). See above.

Command

The command is an entry linked to an executable command inside the device. A command can be executed on demand and a mechanism of passing input arguments, obtaining return value, as well as reading/writing input/output stream is provided.

There are two ways on how to exchange input and output with the commands:

• Arguments and result The dialog contains input string argument boxes and a single number result box. If up to four argument boxes are filled before execution, they will be passed on to the command. After execution, the return value is displayed in the result box.
• Standard input and output The dialog consists of standard input and output edit boxes. The input can be either filled before the execution or, when the command awaits an input, the standard input box will be highlighted.

Variable import/export

Variables and their values may be imported/exported on demand. This imports and exports the current state of the part of emGUI's content image, not the actual values in the device.

Choose what to export / where to import:

1. The entire tree. Use File or Edit menu. In case of more devices discovered, you will be prompted for each device separately.
2. A sub-tree. You may only select a single device or a folder.
3. A multi selection. Holding CTRL+selecting your entries (a selected folder will be crawled recursively).

Choose where to export / import from:

1. Local file. Use File->Export variables to file or File->Import variables from file for the entire tree or multi-selection. For sub-tree use the Context menu of the corresponding tree entry and select Export variables to file or Import variables from file. You will get a separate dialog for import and export, where you can specify the filename and related options:

   

   The example of the file content:

   # emgui version: 2.11.3
   # time generated: 2023-12-11, 17:07:07
   #
   # basename: 'fn'
   # hwid: 'esc5-ax1d_05kxa0810-800'
   # swid: 'BLDC_OPHION_generic v4.2.0-punk Jul 20 2023'
   # s/n: '895FMP114D4D'
   # uuid: '20383935464D5011004D004D'
   # class: '0E:AX'
   
   # type : 'parameter' (non-default value)
   "/driver/iref" : "60.0"
   "/driver/prest" : "1"

2. System clipboard. Either navigate to the Edit in main menu, Copy or Paste in the context menu, or use ctrl+c ctrl+v shortcuts. The example of the clipboard content:

   "/driver/supply/cap" : "0"
   "/driver/supply/current" : "0.0"
   "/driver/supply/currentf" : "0.0"
   "/driver/supply/voltage" : "0.028445"
   "/driver/energy" : "0"
   "/driver/iqmult" : "1.0"
   "/driver/irefr" : "0.0"

info

• If the file contains a variable(s) that do not match with the user's selection in the tree, it will not be imported.
• When using the clipboard, all variable types will be exported and only writable ones will be imported.

Frontend dialogs

are dedicated to single-shooting certain typical commands or sets of commands inside the device.

On-board save and load

A prompt dialog that serves as a frontend over the save and load commands. Pressing Save or Load will execute these. Optionally, there is also the Backup storage option. Checking Pull parameter values will do so after completion.

On-board restore default parameter values

A prompt dialog that serves as a frontend over the restore commands. Pressing Restore will execute that. Checking Pull parameter values will do so after completion.

Managers

are actively linked to certain services/processes inside the device through a set of commands.

Plot manager

is a simple active management of the plot service inside the device. For each plot, the window shows its status. Similarly, it allows for clearing trends and setting the sampling periods.