GladeVCP

GladeVCP is an EMC2 component which adds the ability to add a virtual control panel to EMC user interfaces like Axis or Touchy. It is similar to PyVCP; whereas PyVCP panels are created by editing an XML file manually, GladeVCP uses the glade WYSIWYG user interface editor. Therefore, it’s faster and easier to create visually pleasing panels with GladeVCP.

Either modify an existing UI component, or start a new one with running glade. In the left tab, expand the HAL Python components. Create a window as top level window from the Toplevels section, which by default will be named window1. Leave that name as is - gladevcp assumes the top level window has this name. Add a HAL_Box or a HAL_Table from HAL Python to the frame, and pick and place some elements like LED, button etc in its box.

This will look like so:

Select File-]Save as, give it a name like myui.ui and make sure it`s saved as GtkBuilder file (radio button left bottom corner in Save dialog). The convention for GtkBuilder file extension is .ui. You can now run it with:

While you could run your UI as a separate top level window side-by-side with Axis, having it within the Axis frame as a tab side-by-side with the Preview and DRO tabs is more elegant. To do so, edit your .ini file and add two variables to the DISPLAY section of ini file:

Try it out by running Axis - there should be a new tab called GladeVCP near the DRO tab. Select that tab, you should see the example panel nicely fit within Axis like so:

Touchy also understands EMBED_TAB_NAME/EMBED_TAB_COMMAND variables from INI file so instructions for it are equal to Axis.

To be useful, the pins in your UI need to be linked to the rest of your setup. Usually this is done by running one or several HAL files through the HALFILE and POSTGUI_HALFILE statements in the HAL section of your .ini file.

For gladevcp components this not currently possible because all of these HALFILE statements are run before gladevcp is started, so linking to your UI’s pins from there would refer to pins which do not yet exist. You therefore need to prepare a file of all HAL commands which refer to / link with your UI’s pins and pass it to the gladevcp command in the EMBED_TAB_COMMAND statement like so:

There is an example gladevcp-test.hal file in the emc2-dev/lib/python/gladevcp directory. Before using it in the EMBED_TAB_NAME statement, make sure the loadusr statements at the top are commented out.

This is just a very minimal example to convey the idea - for a detailed description on how to program a gladevcp application, see GladeVCPprogramming and HalWidgets.

gladevcp cannot only manipulate or display HAL pins, you can also write regular event handlers in Python. This could be used, among others, to execute MDI commands. Here’s how you do it:

Write a Python module like so and save as e.g. handlers.py:

In glade, define a button or HAL button, select the Signals tab, and in the GtkButton properties select the pressed line. Enter on_button_press there, and save the glade file.

Then add the option -u handlers.py to the gladevcp command line. If your event handlers are spread over several files, just add multiple -u [pyfilename] options.

Now, pressing the button should change its label since it’s set in the callback function.

What the -u flag does is: all Python functions in this file are collected and setup as potential callback handlers for your Gtk widgets - they can be referenced from glade Signals tabs. The callback handlers are called with the particular object instance as parameter, like the GtkButton instance above, so you can apply any GtkButton method from there.

Or do some more useful stuff, like calling an MDI command!

See also man gladevcp . This is the usage message when you run gladevcp -h:

Usage: gladevcp [options] myfile.ui

Options:

Stock gladevcp can be used pretty much in the style of PyVCP - the major difference being that in the case of gladevcp, the glade user interface editor is used to design a screen layout, whereas PyVCP is driven by manually edited XML files. Also, PyVCP uses the TkInter widgets, whereas gladevcp uses the much richer GTK toolkit. Both support HAL widgets - widgets with one or more associated HAL pin which is the interface to the rest of EMC. Stock gladevcp and PyVCP panels are really just a bunch of virtual switches, dials, leds an so forth, wired to the outside world through the HAL layer, designed to set and read ints, bits and floats values.

Most widget sets, and their associated user interface editors, support the concept of callbacks - functions in user-written code which are executed when something happens in the UI - events like mouse clicks, characters typed, mouse movement, timer events, window hiding and exposure and so forth. Both PyVCP and stock gladevcp mainly do two things: mapping events on HAL widgets to actions like a value change of the associated HAL pin, and in the other direction - detecting if HAL pin values changed and updating the associated widget, like a LED, a meter, a bar, or just some label displaying a value. However, neither PyVCP nor stock gladevcp provide support for other actions than changing HAL values. Doing something more complex, like executing MDI commands to call a G-code subroutine, is outside scope.

GladeVcp includes a collection of Gtk widgets with attached HAL pins called HAL Widgets, intended to control, display or otherwise interact with the EMC HAL layer. They are intended to be used with the glade user interface editor. With proper installation, the HAL Widgets should show up in glade’s HAL Python widget group. Many HAL specific fields in the glade General section have an associated mouse-over tool tip.

HAL signals come in two variants, bits and numbers. Bits are off/on signals. Numbers can be "float", "s32" or "u32". For more information on HAL data types see the [-]] section. The GladeVcp widgets can either display the value of the signal with an indicator widget, or modify the signal value with a control widget. Thus there are four classes of GladeVcp widgets that you can connect to a HAL signal. Another class of helper widgets allow you to organize and label your panel.

HAL Widgets inherit methods, properties and signals from the underlying Gtk widgets, so it is helpful to consult the Gtk and PyGTK documentation as well.

Most HAL widgets have a single associated HAL pin with the same name as the widget (glade: General-]Name). Exceptions to this rule currently are the HAL_Spinbutton, which has two pins: a [widgetname]-f (float) and a [widgetname]-s (s32) pin, and the HAL_ProgressBar, which has a [widgetname] value input pin, and a [widgetname].scale input pin.

As a general rule, if you need to set a HAL output widget’s value from Python code, do so by calling the underlying Gtk setter (e.g. set_active(), set_value()) - do not try to set the associated pin’s value by halcomp[pinname] = value directly because the widget will not notice.

It might be tempting to set HAL widget input pins programmatically. Note this defeats the purpose of an input pin in the first place - it should be linked to, and react to signals generated by other HAL components. While there is currently no write protection on writing to input pins in HAL Python, this doesn’t make sense. You might use setp pinname value in the associated halfile for testing though.

It is perfectly OK to set an output HAL pin’s value with halcomp[pinname] = value provided this HAL pin is not associated with a widget, that is, has been created by the hal_glib.GPin(halcomp.newpin([name],[type],[direction]) method (see GladeVCProgramming for an example).

Event-driven programming means that the UI tells you when "something happens" - through a callback, like when a button was pressed. The output HAL widgets (those which display a HAL pin’s value) like LED, Bar, VBar, Meter etc, support the hal-pin-changed signal which may cause a callback into your Python code when - well, a HAL pin changes its value. This means there’s no more need for permanent polling of HAL pin changes in your code, the widgets do that in the background and let you know. The example in configs/gladevcp/examples/complex shows how this is handled in Python.

Here is an example how to set a hal-pin-changed signal for a HAL_LED in the glade UI editor:

This group of widget is derived from various Gtk buttons and consists of HAL_Button, HAL_ToggleButton, HAL_RadioButton and CheckButton widgets. All of them have a single output BIT pin named identical to the widget. Buttons have no additional properties compared to their base Gtk classes.

HAL_Button: instantaneous action, does not retain state. Important signal: pressed

HAL_ToggleButton, HAL_CheckButton: retains on/off state. Important signal: toggled

HAL_RadioButton: a one-of-many group. Important signal: toggled (per button).

Important common methods: set_active(), get_active()

Important properties: label, image

Hint: Defining radio button groups in glade:

See configs/gladevcp/by-widget/radiobutton for a gladevcp application and UI file for working with radio buttons.

HAL_HScale and HAL_VScale are derived from the GtkHScale and GtkVScale respectively. They have one output FLOAT pin with name equal to widget name. Scales have no additional properties.

Hint: To make a scale useful in glade, add an Adjustment (General-]Adjustment-]New or existing adjustment) and edit the adjustment object. It defines the default/min/max/increment

values. Also, set adjustment Page size and Page increment to zero to avoid warnings.

HAL SpinButton is derived from GtkSpinButton and holds two pins:

Hint: to be useful, Spinbuttons need an adjustment value like scales, see above.

HAL_Label is simple widget based on GtkLabel which represents a HAL pin value in a user-defined format. The pin’s HAL type depends on the label_pin_type property (0:S32, 1:float, 2:U32), see also the tooltip on General-]HAL pin type (note this is different from PyVCP which has three label widgets, one for each type).

The text displayed depends on the text_template property - an Python format string to represent the pin value. It defaults to "%s" (values are converted by the str() function) but may contain anything legit in a as argument to Pythons format() method.

Example: Distance: %.03f will display the text and the pin value with 3 fractional digits padded with zeros for a FLOAT pin.

Compared to their Gtk counterparts they have one input BIT pin which controls if their child widgets are sensitive or not. If the pin is low then child widgets are inactive which is the default.

The HAL_Led simulates a real indicator LED . It has a single input BIT pin which controls it’s state: ON or OFF. Leds have several properties which control their look and feel:

As an input widget, LED also supports the hal-pin-changed signal. If you want to get a notification in your code when the LED’s HAL pin was changed, then connect this signal to a handler, for example on_led_pin_changed and provide the handler as follows:

This will be called at any edge of the signal and also during program start up to report the current value.

Example LEDs:

The HAL_ProgressBar is derived from gtk.ProgressBar and has two float HAL input pins:

It has the following properties:

HAL_ComboBox is derived from gtk.ComboBox. It enables choice of a value from a dropdown list.

It exports two HAL pins:

It has the following property which can be set in glade:

column: the column index, type S32, defaults to -1, range from -1..100 .

In default mode this widgets sets the pins to the index of the chosen list entry. So if your widget has three labels, it may only assume values 0,1 and 2.

In column mode (column ] -1), the value reported is chosen from the ListStore array as defined in Glade. So typically your widget definition would have two columns in the ListStore , one with text displayed in the dropdown, and an int or float value to use for that choice.

There’s an example in configs/gladevcp/by-widget/combobox/combobox.{py,ui} which uses column mode to pick a float value from the ListStore.

If you’re confused like me about how to edit ComboBox ListStores and CellRenderer , see http://www.youtube.com/watch?v=Z5_F-rW2cL8.

HAL Bar and VBar widgets for horizontal and vertical bars representing float values. They have one input FLOAT hal pin. Both bars have the following properties:

Examples:

HAL Meter is widget like PyVCP meter representing float value. It have one input FLOAT hal pin. Widget has following properties:

Examples:

Gremlin is a plot preview widget similar to the Axis preview window. It assumes a running EMC environment like Axis or Touchy. To connect to it, inspects the INI_FILE_NAME environment variable. Gremlin displays the current .ngc file - it does monitor for changes and reloads the ngc file if the file name in Axis/Touchy changes. If you run it in a gladevcp application when EMC is not running you might get a traceback because the Gremlin widget cant find EMC status, like the current file name.

Gremlin does not export any HAL pins. It has the following properties:

Example:

GladeVcp includes a collection of "canned actions" called EMC Action Widgets for the glade user interface editor. Other than HAL widgets, which interact with HAL pins, EMC Actions interact with EMC and the G-code interpreter.

EMC Action Widgets are derived from the Gtk.Action widget. The Action widget in a nutshell:

The appearance of EMC Actions in glade is roughly as follows:

Tooltip hovers provide a description.

These are one-shot type widgets. They implement a single action and are for use in simple buttons, menu entries or radio/check groups.

These are bi-modal widgets. They implement two actions or use a second (usually pressed) state to indicate that currently an action is running. Toggle actions are aimed for use in ToggleButtons, ToggleToolButtons or toggling menu items. A simplex example is the ESTOP toggle button.

Currently the following widgets are available:

The following toggle actions have only one associated command and use the pressed state to indicate that the requested operation is running:

These widgets provide a means to execute arbitrary MDI commands.

Here’s a glade UI file which conveys the basics:

Open it in glade and study how it’s done. Start Axis, and then start this from a terminal window with gladevcp whoareyou.ui . See the hal_action_mdi1 Action and it’s MDI command property - this just executes (MSG, "Hi, I’m an EMC_Action_MDI") so there should be a message popup in Axis like so:

You’ll notice that the button associated with the Action_MDI action is grayed out if the machine is off, in E-Stop or the program is running. It will automatically become active when the machine is turned on and out of E-Stop, and the program is idle.

Optionally, MDI command strings may have parameters substituted before they are passed to the interpreter. Parameters currently may be names of HAL pins in the gladevcp component (in a later release, this will be extended to cover HAL pins of other components as well). This is how it works:

Here’s the example UI file for gladevcp: , and here’s what you get:

It’s perfectly OK to call an O-word subroutine in an MDI command, and pass HAL pin values as actual parameters. Here’s an example UI file upload:owordsub.ui and O-word sub:

Place oword.ngc so Axis can find it, and run gladevcp owordsub.ui from a terminal window. This looks like so:

The EMC G-Code interpreter has a single global set of variables, like feed, spindle speed, relative/absolute mode and others. If you use G code commands or O-word subs, some of these variables might get changed by the command or subroutine - for example, a probing subroutine will very likely set the feed value quite low. With no further precautions, your previous feed setting will be overwritten by the probing subroutine’s value.

To deal with this surprising and undesirable side effect of a given O-word subroutine or G-code statement executed with an EMC ToggleAction_MDI, you might associate pre-MDI and post-MDI handlers with a given EMC ToggleAction_MDI. These handlers are optional and provide a way to save any state before executing the MDI Action, and to restore it to previous values. The signal names are mdi-command-start and mdi-command-stop; the handler names can be set in glade like any other handler.

Here’s an example how a feed value might be saved and restored by such handlers (note that EMC command and status channels are available as self.emc and self.stat through the _EMC_ActionBase class:

Only the Action_MDI Toggle widget supports these signals.

Many actions depend on EMC status - is it in manual, MDI or auto mode? is a program running, paused or idle? You cannot start an MDI command while a G-code program is running, so this needs to be taken care of. Many EMC actions take care of this themselves, and related buttons and menu entries are deactivated when the operation is currently impossible.

When using Python event handlers - which are at a lower level than Actions - one needs to take care of dealing with status dependencies oneself. For this purpose, there’s the EMC Stat widget: to associate EMC status changes with event handlers.

EMC Stat has no visible component - you just add it to your UI with glade. Once added, you can associate handlers with its following signals:

As most of the infrastructure to support user-defined actions in glade and the GTK widget set is in place, the new gladevcp version really just provides a way for the user to write a Python module whose class methods - or in the simple case, just functions - can be referred to in glade as event handlers, a way to import this module(s) into gladevcp at runtime and properly link it with the rest of the HAL layer.

We also extended the way the HAL input pins interact with the gladevcp panel. Beyond HAL widgets displaying pin values, there is now a way to attach a value-changed callback to a HAL pin, which fits nicely with the event-driven structure of a typical widget application: every activity, be it mouse click, key, timer expired, or the change of a HAL pin’s value, generates a callback and is handled by the same orthogonal mechanism.

Note that the above refers to explicitly declared HAL pins. HAL widgets come with a pre-defined signal hal-pin-changed, see the HalWidgets page for details.

See the Adding HAL pins section below for details.

A annoying aspect of gladevcp in its earlier form and pyvcp is the fact that you may change values through text entry, sliders, spin boxes, toggle buttons etc, but their settings are not saved and restored at the next run of EMC - they start at the default value as set in the panel or widget definition. Therefore I added an easy-to-use mechanism to save and restore the state of HAL widgets, and program variables (in fact instance attributes) as well. This mechanism uses the popular .ini file syntax and has safeguards against the .ini file and the corresponding user interface or program variables getting out of sync - just imagine renaming, adding or deleting widgets in glade: an .ini file lying around from a previous program version, or an entirely different user interface, would be not be able to restore the state properly. This situation is detected through a signature which depends on all object names and types which are saved and to be restored. In the case of signature mismatch, a new .ini file with default settings is generated.

The overall protocol is as follows:

For simple tasks it’s sufficient to define functions named after the glade signal handlers. These will be called when the corresponding event happens in the widget tree. Here’s a trivial example - it assumes that the pressed signal of a GTK Button or HAL Button is linked to a callback called on_button_press:

Add this function to a Python file and run as follows:

Note communication between handlers has to go through global variables, which does not scale well and is positively un-pythonic. This is why we came up with the class-based handler model.

The idea here is: handlers are linked to class methods. The underlying class(es) are instantiated and inspected during gladevcp startup and linked to the widget tree as signal handlers. So the task now is to write:

Here is a minimum user-defined handler example module:

Now, on_this_signal will be available as signal handler to your widget tree.

If during module inspection gladevcp finds a function get_handlers, it calls it as follows:

the arguments are:

gladevcp then inspects the list of class instances and retrieves their method names. Qualifying method names are connected to the widget tree as signal handlers. Only method names which do not begin with an _ (underscore) are considered.

Note that regardless whether you’re using the libglade or the new GtkBuilder format for your glade UI, widgets can always be referred to as builder.get_object([widgetname]). Also, the complete list of widgets is available as builder.get_objects() regardless of UI format.

It is important to know in which state of affairs your get_handlers() function is called so you know what is safe to do there and what not. First, modules are imported and initialized in command line order. After successful import, get_handlers() is called in the following state:

Once all modules have been imported and method names extracted, the following steps happen:

So when your handler class is initialized, all widgets are existent but not yet realized (displayed on screen). And the HAL component isn’t ready as well, so its unsafe to access pins values in your __init__() method.

If you want to have a callback to execute at program start after it is safe to access HAL pins, then a connect a handler to the realize signal of the top level window1 (which might be its only real purpose). At this point gladevcp is done with all setup tasks, the halfile has been run, and gladevcp is about to enter the gtk main loop.

Within a class, method names must be unique. However, it is OK to have multiple class instances passed to gladevcp by get_handlers() with identically named methods. When the corresponding signal occurs, these methods will be called in definition order - module by module, and within a module, in the order class instances are returned by get_handlers().

Instead of extending gladevcp for any conceivable option which could potentially be useful for a handler class, you may use the -U [useroption] flag (repeatedly if you wish). This flag collects a list of [useroption] strings. This list is passed to the get_handlers() function (useropts argument). Your code is free to interpret these strings as you see fit. An possible usage would be to pass them to the Python exec function in your get_handlers() as follows:

This way you can pass arbitrary Python statements to your module through the gladevcp -U option, for example:

This should set debug to 2 and confirm that your module actually did it.

If you want any of: GTK widget state, HAL widgets output pin’s values and/or class attributes of your handler class to be retained across invocations, proceed as follows:

and associate an .ini file with this descriptor:

after restore_state(), self will have attributes set if as running the following:

Note that types are saved and preserved on restore. This example assumes that the ini file didn’t exist or had the default values from self.defaults.

After this incantation, you can use the following IniFil methods:

To save the widget and/or variable state on exit, connect a signal handler to the window1 (toplevel) destroy event:

Next time you start the gladevcp application, the widgets should come up in the state when the application was closed.

You can do that, but note that the values in self.defaults override your edits if there is a syntax or type error in your edit. The error is detected, a console message will hint about that happened, and the bad inifile will be renamed to have the .BAD suffix. Subsequent bad ini files overwrite earlier .BAD files.

If you need HAL pins which are not associated with a specific HAL widget, add them as follows:

To get a callback when this pin’s value changes, associate a value-change callback with this pin, add:

and define a callback method (or function, in this case leave out the self parameter):

Since gladevcp uses GTK widgets which rely on the GObject base class, the full glib functionally is available. Here is an example for a timer callback:

We believe key handling works OK, but since it is new code, we’re telling about it you so you can watch out for problems; please let us know of errors or odd behavior. This is the story:

Axis uses the TkInter widget set. GladeVCP applications use Gtk widgets and run in a separate process context. They are hooked into Axis with the Xembed protocol. This allows a child application like gladevcp to properly fit in a parent’s window, and - in theory - have integrated event handling.

However, this assumes that both parent and child application properly support the Xembed protocol, which Gtk does, but TkInter doesn’t. A consequence of this is that certain keys would not be forwarded from a gladevcp panel to Axis properly under all circumstances. One of these situations was the case when an Entry, or SpinButton widget had focus: in this case, for instance an Escape key would not have been forwarded to Axis and cause an abort as it should, with potentially disastrous consequences.

Therefore, key events in gladevcp are explicitly handled, and selectively forwarded to Axis, to assure that such situations cannot arise. For details, see the keyboard_forward() function in lib/python/gladevcp/xembed.py.

Visit emc2/configs/gladevcp for running examples. The templates subdirectory has starters for your own projects.