A comment line is started with a ; or a # mark. When the ini reader sees either of these marks at the start a line, the rest of the line is ignored by the software. Comments can be used to describe what some INI element will do.

; This is my little mill configuration file.
; I set it up on January 12, 2006

Comments can also be used to select between several values of a single variable.

DISPLAY = axis
# DISPLAY = touchy

In this list, the DISPLAY variable will be set to axis because the other one is commented out. If someone carelessly edits a list like this and leaves two of the lines uncommented, the first one encountered will be used.

Note that inside a variable, the "#" and ";" characters do not denote comments:

INCORRECT = value     # and a comment
# Correct Comment
CORRECT = value

Related parts of an ini file are separated into sections. A section line looks like [THIS_SECTION]. The name of the section is enclosed in brackets. The order of sections is unimportant. The following sections are used by EMC:

A variable line is made up of a variable name, an equals sign(=), and a value. Everything from the first non-white space character after the = up to the end of the line is passed as the value, so you can embed spaces in string symbols if you want to or need to. A variable name is often called a keyword.

The following sections detail each section of the configuration file, using sample values for the configuration lines.

Some of the variables are used by EMC, and must always use the section names and variable names shown. Other variables are used only by HAL, and the section names and variable names shown are those used in the sample configuration files.

Different user interface programs use different options, and not every option is supported by every user interface. The main two interfaces for EMC are AXIS and Touchy. Axis is an interface for use with normal computer and monitor, Touchy is for use with touch screens. Descriptions of the interfaces are in the Interfaces section of the User Manual.

DISPLAY = axis The name of the user interface to use. Valid options may include:

The following [DISPLAY] items are used only if you select AXIS as your user interface program.

The following [DISPLAY] items are not used if you select AXIS as your user interface program.

AXIS has the ability to send loaded files through a filter program. This filter can do any desired task: Something as simple as making sure the file ends with M2, or something as complicated as detecting whether the input is a depth image, and generating g-code to mill the shape it defines. The [FILTER] section of the ini file controls how filters work. First, for each type of file, write a PROGRAM_EXTENSION line. Then, specify the program to execute for each type of file. This program is given the name of the input file as its first argument, and must write rs274ngc code to standard output. This output is what will be displayed in the text area, previewed in the display area, and executed by EMC when Run.

The following lines add support for the image-to-gcode converter included with EMC2:

PROGRAM_EXTENSION = .png,.gif Greyscale Depth Image

It is also possible to specify an interpreter:

PROGRAM_EXTENSION = .py Python Script

In this way, any Python script can be opened, and its output is treated as g-code. One such example script is available at nc_files/holecircle.py. This script creates g-code for drilling a series of holes along the circumference of a circle. Many more g-code generators are on the EMC Wiki site http://wiki.linuxcnc.org/cgi-bin/emcinfo.pl.

If the environment variable AXIS_PROGRESS_BAR is set, then lines written to stderr of the form

FILTER_PROGRESS=%d

Sets the AXIS progress bar to the given percentage. This feature should be used by any filter that runs for a long time.

Example:

PARAMETER_FILE = myfile.var

Example:

Example:

SUBROUTINE_PATH = ncsubroutines:/tmp/testsubs:lathesubs:millsubs

Example:

USER_M_PATH = myfuncs:/tmp/mcodes:experimentalmcodes

A search is made for each possible user defined function, typically (M100-M199). The search order is:

The first executable M1xx found in the search is used for each M1xx.

You may find other entries in this section and they should not be changed.

The [TRAJ] section contains general parameters for the trajectory planning module in EMCMOT.

The [AXIS_0], [AXIS_1], etc. sections contains general parameters for the individual components in the axis control module. The axis section names begin numbering at 0, and run through the number of axes specified in the [TRAJ] AXES entry minus 1.

Homing seems simple enough - just move each joint to a known location, and set EMC’s internal variables accordingly. However, different machines have different requirements, and homing is actually quite complicated.

There are four possible homing sequences, along with the associated configuration parameters as shown in the following table. For a more detailed description of what each configuration parameter does, see the following section.

There are six pieces of information that determine exactly how the home sequence behaves. They are defined in an [AXIS] section of the inifile.

Homing Sequences. When EMC’s interpreter was first written, it was designed for mills. That is why the default plane is XY (G17). A normal lathe only uses the XZ plane (G18). To change the default plane place the following line in the .ini file in the RS274NGC section.

RS274NGC_STARTUP_CODE = G18

The following .ini settings are needed for lathe mode in addition to or replacing normal settings in the .ini file.

[DISPLAY]
DISPLAY = axis
LATHE = 1
[TRAJ]
AXES = 3
COORDINATES = X Z
[AXIS_0]
...
[AXIS_2]
...

Motion is loaded with the motmod command. A kins should be loaded before motion.

loadrt motmod [base_period_nsec=period] [servo_period_nsec=period] [traj_period_nsec=period] [num_joints=[0-9] ([num_dio=1-64] num_aio=1-16])]

If the number of digital I/O needed is above the default of 4 you can add up to 64 digital I/O by using the num_dio option when loading motmod.

If the number of analog I/O needed is more that the default of 4 you can add up to 16 analog I/O by using the num_aio option when loading motmod.

These pins, parameters, and functions are created by the realtime motmod module.

Many of these parameters serve as debugging aids, and are subject to change or removal at any time.

Generally, these functions are both added to the servo-thread in the order shown.

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:

Figure 6.1. Hal Pin Change

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.

Figure 6.2. Buttons

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.

Figure 6.3. Scale

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:

Figure 6.4. SpinButton

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.

Hint: if you find some part of your gladevcp application is grayed out (insensitive), see whether a container’s pin is unset.

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:

def on_led_pin_changed(self,hal_led,data=None):
print "on_led_pin_changed() - HAL pin value:",hal_led.hal_pin.get()

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

Example LEDs:

Figure 6.5. LED

Note: This widget might go away. Use the HAL_HBar and HAL_VBar widgets instead.

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

It has the following properties:

Figure 6.6. Progressbar

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:

Figure 6.7. Bars

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

Examples:

Figure 6.8. Hal Meter

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:

Figure 6.9. Gremlin

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:

nhits = 0
def on_button_press(gtkobj,data=None):
global nhits
nhits += 1
gtkobj.set_label("hits: %d" % nhits)

gladevcp -u <myhandler>.py mygui.ui

Class MyCallbacks :
def on_this_signal(self,obj,data=None):
print "this_signal happened, obj=",obj
def get_handlers(halcomp,builder,useropts):
return [MyCallbacks ()]

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:

debug = 0
...
def get_handlers(halcomp,builder,useropts):
...
global debug # assuming there's a global var
for cmd in useropts:
exec cmd in globals()

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

gladevcp -U debug=42 -U "print debug=%d % debug" …

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:

self.ini_filename = __name__ + '.ini'
self.ini = IniFile(self.ini_filename,self.defaults,self.builder)
self.ini.restore_state(self)

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

self.nhits = 0
self.a = 1.67
self.d = True
self.c = "a string"

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:

def on_destroy(self,obj,data=None):
    self.ini.save_state(self)

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:

import hal_glib
...
# in your handler class __init__():
self.example_trigger = hal_glib.GPin(halcomp.newpin('example-trigger', hal.HAL_BIT, hal.HAL_IN))

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

self.example_trigger.connect('value-changed', self._on_example_trigger_change)

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

# note '_' - this method will not be visible to the widget tree
def _on_example_trigger_change(self,pin,userdata=None):
print "pin value changed to:" % (pin.get())

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:

def _on_timer_tick(self,userdata=None):
...
return True # to restart the timer; return False for on-shot
...
# demonstrate a slow background timer - granularity is one second
# for a faster timer (granularity 1msec), use this:
# glib.timeout_add(100, self._on_timer_tick,userdata) # 10Hz
glib.timeout_add_seconds(1, self._on_timer_tick)

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.

The command "loadrt" loads a real time HAL component. Real time component functions need to be added to a thread to be updated at the rate of the thread. You cannot load a user space component into the real time space.

The syntax and an example:

loadrt <component> <options>
loadrt mux4 count=1

The command "addf" adds a real time component function to a thread. You have to add a function from a HAL real time component to a thread to get the function to update at the rate of the thread.

If you used the Stepper Config Wizard to generate your config you will have two threads.

The syntax and an example:

addf <component> <thread>
addf mux4 servo-thread

The command "loadusr" loads a user space HAL component. User space programs are their own separate processes, which optionally talk to other HAL components via pins and parameters. You cannot load real time components into user space.

Flags may be one or more of the following:

The syntax and examples:

loadusr <component> <options>
loadusr halui
loadusr -Wn spindle gs2_vfd -n spindle
in English it means "loadusr wait for name spindle component gs2_vfd name spindle."

The command "net" creates a "connection" between a signal and and one or more pins. If the signal does not exist net creates the new signal. This replaces the need to use the command newsig. The direction indicators "⇐ and ⇒" are only to make it easier for humans to follow the logic and are not used by the net command.

The syntax and an example:

net <signal-name> <pin-name> <opt-direction> <opt-pin-name>
net both-home-y <= parport.0.pin-11-in

Each signal can only have one source (a HAL "Dir out” pin) and as many readers (a HAL "Dir in" pin) as you like. In the Dir column of the HAL Configuration window you can see which pins are "in" and which are "out". The following figure shows the "direction" of the signal from the source, through the signal, and then out to the reader(s).

Figure 7.2. Signal Direction

This example shows the signal xStep with the source being stepgen.0.out and with two readers, parport.0.pin-02-out and parport.0.pin-08-out. Basically the value of stepgen.0.out is send to the signal xStep and that value is then sent to parport.0.pin-02-out and parport.0.pin-08-out.

   signal    source            destination          destination
net xStep stepgen.0.out => parport.0.pin-02-out parport.0.pin-08-out

Since the signal xStep contains the value of stepgen.0.out (the source) you can use the same signal again to send the value to another reader. To do this just use the signal with the readers on another line.

net xStep <= stepgen.0.out => parport.0.pin-02-out

The so called I/O pins like index-enable do not follow this rule.

The command "setp" sets the value of a pin or parameter. The valid values will depend on the type of the pin or parameter. It is an error if the data types do not match.

Some components have parameters that need to be set before use. Parameters can be set before use or while running as needed. You cannot use setp on a pin that is connected to a signal.

The syntax and an example:

setp <pin/parameter-name> <value>
setp parport.0.pin-08-out TRUE

The command "unlinkp" unlinks a pin from the connected signal. If no signal was connected to the pin prior running the command, nothing happens.

The syntax and an example:

unlinkp <pin-name>

unlinkp parport.0.pin-02-out

A bit value is an on or off.

A "float" is a floating point number. In other words the decimal point can move as needed.

For more information on floating point numbers see:

http://en.wikipedia.org/wiki/Floating_point

An "s32" number is a whole number that can have a negative or positive value.

A "u32" number is a whole number that is positive only.

The "and2" component is a two input "and" gate. The truth table below shows the output based on each combination of input.

Syntax

and2 [count=N] or [names=name1[,name2...]]

Functions

and2.n

Pins

and2.N.in0 (bit, in) +
and2.N.in1 (bit, in) +
and2.N.out (bit, out)

Truth Table

The "not" component is a bit inverter.

Syntax

not [count=n] or [names=name1[,name2...]]

Functions

not.all +
not.n

Pins

not.n.in (bit, in) +
not.n.out (bit, out)

Truth Table

The "or2" component is a two input OR gate.

Syntax

or2[count=n] or [names=name1[,name2...]]

Functions

or2.n

Pins

or2.n.in0 (bit, in) +
or2.n.in1 (bit, in) +
or2.n.out (bit, out)

Truth Table

The "xor2" component is a two input XOR (exclusive OR)gate.

Syntax

xor2[count=n] or [names=name1[,name2...]]

Functions

xor2.n

Pins

xor2.n.in0 (bit, in) +
xor2.n.in1 (bit, in) +
xor2.n.out (bit, out)

Truth Table

An "and2" example connecting two inputs to one output.

loadrt and2 count=1 +
addf and2.0 servo-thread +
net my-sigin1 and2.0.in0 <= parport.0.pin-11-in +
net my-sigin2 and2.0.in1 <= parport.0.pin-12-in +
net both-on parport.0.pin-14-out <= and2.0.out

In the above example one copy of and2 is loaded into real time space and added to the servo thread. Next pin 11 of the parallel port is connected to the in0 bit of the and gate. Next pin 12 is connected to the in1 bit of the and gate. Last we connect the and2 out bit to the parallel port pin 14. So following the truth table for and2 if pin 11 and pin 12 are on then the output pin 14 will be on.

The weighted_sum converts a group of bits to an integer. The conversion is the sum of the "weights" of the bits that are on plus any offset. This is similar to a binary coded decimal but with more options. The "hold" bit stops processing the input changes so the "sum" will not change.

The following syntax is used to load the weighted_sum component.

loadrt weighted_sum wsum_sizes=size[,size,...]

Creates weighted sum groups each with the given number of input bits (size).

To update the weighted_sum you need to attach process_wsums to a thread.

addf process_wsums servo-thread

This updates the weighted_sum component.

In the following example clipped from the HAL Configuration window in Axis the bits "0" and "2" are true and there is no offset. The "weight" of 0 is 1 and the "weight" of 2 is 4 so the sum is 5.

Figure 7.3. weighted_sum

Halshow is in the AXIS menu under Machine/Show Hal Configuration.

Halshow is in the TkEMC menu under Scripts/Hal Show.

At the left of its display as shown in figure  [cap:Halshow-Layout] is a tree view, somewhat like you might see with some file browsers. At the right is a tabbed notebook with tabs for show and watch.

Figure 7.4. Halshow Layout

The tree shows all of the major parts of a HAL. In front of each is a small plus (+) or minus (-) sign in a box. Clicking the plus will expand that tree node to display what is under it. If that box shows a minus sign, clicking it will collapse that section of the tree.

You can also expand or collapse the tree display using the Tree View menu at the upper left edge of the display. Under Tree View you will find: Expand Tree, Collapse Tree; Expand Pins, Expand Parameters, Expand Signals; and Erase Watch. (Note that Erase Watch erases’all' previously set watches, you cannot erase just one watch.)

Figure 7.5. Show Menu

Clicking on the node name, the word "Components" for example, will show you (under the "Show" tab) all that hal knows about the contents of that node. Figure  [cap:Halshow-Layout] shows a list exactly like you will see if you click the "Components" name while you are running a standard m5i20 servo card. The information display is exactly like those shown in traditional text based HAL analysis tools. The advantage here is that we have mouse click access, access that can be as broad or as focused as you need.

If we take a closer look at the tree display we can see that the six major parts of a HAL can all be expanded at least one level. As these levels are expanded you can get more focused with the reply when you click on the rightmost tree node. You will find that there are some hal pins and parameters that show more than one reply. This is due to the nature of the search routines in halcmd itself. If you search one pin you may get two, like this:

Component Pins: +
Owner Type Dir Value Name +
06 bit -W TRUE parport.0.pin-10-in +
06 bit -W FALSE parport.0.pin-10-in-not

The second pin’s name contains the complete name of the first.

Below the show area on the right is a set of widgets that will allow you to play with the running HAL. The commands you enter here and the effect that they have on the running HAL are not saved. They will persist as long as EMC remains up but are gone as soon as EMC is.

The entry box labeled "Test Hal Command:" will accept any of the commands listed for halcmd. These include:

This little editor will enter a command any time you press <enter> or push the execute button. An error message from halcmd will show below this entry widget when these commands are not properly formed. If you are not certain how to set up a proper command you’ll need to read again the documentation on halcmd and the specific modules that you are working with.

Let’s use this editor to add a differential module to a hal and connect it to axis position so that we could see the rate of change in position, i.e., acceleration. We first need to load a hal module named blocks, add it to the servo thread, then connect it to the position pin of an axis. Once that is done we can find the output of the differentiator in halscope. So let’s go. (Yes, I looked this one up.)

loadrt blocks ddt=1

Now look at the components node and you should see blocks in there someplace.

Loaded HAL Components: +
ID Type Name +
10 User halcmd29800 +
09 User halcmd29374 +
08 RT blocks +
06 RT hal_parport +
05 RT scope_rt +
04 RT stepgen +
03 RT motmod +
02 User iocontrol

Sure enough there it is. Notice that its ID is 08. Next we need to find out what functions are available with it so we look at functions:

Exported Functions: +
Owner CodeAddr Arg FP Users Name +
08 E0B97630 E0DC7674 YES 0 ddt.0 +
03 E0DEF83C 00000000 YES 1 motion-command-handler +
03 E0DF0BF3 00000000 YES 1 motion-controller +
06 E0B541FE E0DC75B8 NO 1 parport.0.read +
06 E0B54270 E0DC75B8 NO 1 parport.0.write +
06 E0B54309 E0DC75B8 NO 0 parport.read-all +
06 E0B5433A E0DC75B8 NO 0 parport.write-all +
05 E0AD712D 00000000 NO 0 scope.sample +
04 E0B618C1 E0DC7448 YES 1 stepgen.capture-position +
04 E0B612F5 E0DC7448 NO 1 stepgen.make-pulses +
04 E0B614AD E0DC7448 YES 1 stepgen.update-freq

Here we look for owner #08 and see that blocks has exported a function named ddt.0. We should be able to add ddt.0 to the servo thread and it will do its math each time the servo thread is updated. Once again we look up the addf command and find that it uses three arguments like this:

addf <functname> <threadname> [<position>]

We already know the functname=ddt.0 so let’s get the thread name right by expanding the thread node in the tree. Here we see two threads, servo-thread and base-thread. The position of ddt.0 in the thread is not critical. So we add the function ddt.0 to the servo-thread:

addf ddt.0 servo-thread

This is just for viewing, so we leave position blank and get the last position in the thread. Figure  [cap:Addf-Command] shows the state of halshow after this command has been issued.

Figure 7.6. Addf Command

Next we need to connect this block to something. But how do we know what pins are available? The answer is to look under pins. There we find ddt and see this:

Component Pins: +
Owner Type Dir Value Name +
08 float R- 0.00000e+00 ddt.0.in +
08 float -W 0.00000e+00 ddt.0.out

That looks easy enough to understand, but what signal or pin do we want to connect to it? It could be an axis pin, a stepgen pin, or a signal. We see this when we look at axis.0:

Component Pins: +
Owner Type Dir Value Name +
03 float -W 0.00000e+00 axis.0.motor-pos-cmd ==> Xpos-cmd

So it looks like Xpos-cmd should be a good signal to use. Back to the editor where we enter the following command:

linksp Xpos-cmd ddt.0.in

Now if we look at the Xpos-cmd signal using the tree node we’ll see what we’ve done:

Signals: +
Type Value Name +
float 0.00000e+00 Xpos-cmd +
<== axis.0.motor-pos-cmd +
==> ddt.0.in +
==> stepgen.0.position-cmd

We see that this signal comes from axis.o.motor-pos-cmd and goes to both ddt.0.in and stepgen.0.position-cmd. By connecting our block to the signal we have avoided any complications with the normal flow of this motion command.

The Hal Show Area uses halcmd to discover what is happening in a running HAL. It gives you complete information about what it has discovered. It also updates as you issue commands from the little editor panel to modify that HAL. There are times when you want a different set of things displayed without all of the information available in this area. That is where the Hal Watch Area is of value.

Clicking the watch tab produces a blank canvas. You can add signals and pins to this canvas and watch their values.^[5] You can add signals or pins when the watch tab is displayed by clicking on the name of it. Figure [cap:Watch-Display] shows this canvas with several "bit" type signals. These signals include enable-out for the first three axes and two of the three iocontrol "estop" signals. Notice that the axes are not enabled even though the estop signals say that EMC is not in estop. A quick look at TkEMC shows that the condition of EMC is ESTOP RESET. The amp enables do not turn true until the machine has been turned on.

Figure 7.7. Watch Display

Watch displays bit type (binary) values using colored circles representing LEDs. They show as dark brown when a bit signal or pin is false, and as light yellow whenever that signal is true. If you select a pin or signal that is not a bit type (binary) signal, watch will show it as a numerical value.

Watch will quickly allow you to test switches or see the effect of changes that you make to EMC while using the graphical interface. Watch’s refresh rate is a bit slow to see stepper pulses, but you can use it for these if you move an axis very slowly or in very small increments of distance. If you’ve used IO_Show in EMC, the watch page in halshow can be set up to watch a parport much as IO_Show did.

This file contains several HAL commands, and usually looks like this:

# standard pinout config file for 3-axis steppers
# using a parport for I/O
#
# first load the parport driver
loadrt hal_parport cfg="0x0378"
#
# next connect the parport functions to threads
# read inputs first
addf parport.0.read base-thread 1
# write outputs last
addf parport.0.write base-thread -1
#
# finally connect physical pins to the signals
net Xstep => parport.0.pin-03-out
net Xdir  => parport.0.pin-02-out
net Ystep => parport.0.pin-05-out
net Ydir  => parport.0.pin-04-out
net Zstep => parport.0.pin-07-out
net Zdir  => parport.0.pin-06-out

# create a signal for the estop loopback
net estop-loop iocontrol.0.user-enable-out iocontrol.0.emc-enable-in

# create signals for tool loading loopback
net tool-prep-loop iocontrol.0.tool-prepare iocontrol.0.tool-prepared
net tool-change-loop iocontrol.0.tool-change iocontrol.0.tool-changed

# connect "spindle on" motion controller pin to a physical pin
net spindle-on motion.spindle-on => parport.0.pin-09-out

###
### You might use something like this to enable chopper drives when machine ON
### the Xen signal is defined in core_stepper.hal
###

# net Xen => parport.0.pin-01-out

###
### If you want active low for this pin, invert it like this:
###

# setp parport.0.pin-01-out-invert 1

###
### A sample home switch on the X axis (axis 0).  make a signal,
### link the incoming parport pin to the signal, then link the signal
### to EMC's axis 0 home switch input pin
###

# net Xhome parport.0.pin-10-in => axis.0.home-sw-in

###
### Shared home switches all on one parallel port pin?
### that's ok, hook the same signal to all the axes, but be sure to
### set HOME_IS_SHARED and HOME_SEQUENCE in the ini file.  See the
### user manual!
###

# net homeswitches <= parport.0.pin-10-in
# net homeswitches => axis.0.home-sw-in
# net homeswitches => axis.1.home-sw-in
# net homeswitches => axis.2.home-sw-in

###
### Sample separate limit switches on the X axis (axis 0)
###

# net X-neg-limit parport.0.pin-11-in => axis.0.neg-lim-sw-in
# net X-pos-limit parport.0.pin-12-in => axis.0.pos-lim-sw-in

###
### Just like the shared home switches example, you can wire together
### limit switches.  Beware if you hit one, EMC will stop but can't tell
### you which switch/axis has faulted.  Use caution when recovering from this.
###

# net Xlimits parport.0.pin-13-in => axis.0.neg-lim-sw-in axis.0.pos-lim-sw-in

The files starting with # are comments, and their only purpose is to guide the reader through the file.

There are a couple of operations that get executed when the standard_pinout.hal gets executed / interpreted:

If you want to change the standard_pinout.hal file, all you need is a text editor. Open the file and locate the parts you want to change.

If you want for example to change the pin for the X-axis Step & Directions signals, all you need to do is to change the number in the parport.0.pin-XX-out name:

net Xstep parport.0.pin-03-out

can be changed to:

net Xstep parport.0.pin-02-out

or basically any other numbers you like.

Hint: make sure you don’t have more than one signal connected to the same pin.

If external hardware expects an “active low” signal, set the corresponding -invert parameter. For instance, to invert the spindle control signal:

setp parport.0.pin-09-invert TRUE

If your spindle can be controlled by a PWM signal, use the pwmgen component to create the signal:

loadrt pwmgen output_type=0

This assumes that the spindle controller’s response to PWM is simple: 0% PWM gives 0 RPM, 10% PWM gives 180 RPM, etc. If there is a minimum PWM required to get the spindle to turn, follow the example in the nist-lathe sample configuration to use a scale component.

Some amplifiers (drives) require an enable signal before they accept and command movement of the motors. For this reason there are already defined signals called Xen, Yen, Zen.

To connect them use the following example:

net Xen parport.0.pin-08-out

You can either have one single pin that enables all drives; or several, depending on the setup you have. Note, however, that usually when one axis faults, all the other drives will be disabled as well, so having only one enable signal / pin for all drives is a common practice.

As you can see in [sub:standard_pinout.hal] by default the stepper configuration assumes no external ESTOP button. ^[8]

To add a simple external button you need to replace the line:

net estop-loop iocontrol.0.user-enable-out iocontrol.0.emc-enable-in

with

net estop-loop parport.0.pin-01-in iocontrol.0.emc-enable-in

This assumes an ESTOP switch connected to pin 01 on the parport. As long as the switch will stay pushed^[9], EMC2 will be in the ESTOP state. When the external button gets released EMC2 will imediately switch to the ESTOP-RESET state, and all you need to do is switch to Machine On and you’ll be able to continue your work with EMC2.

Compute the absolute value and sign of the input signal

loadrt abs [count=N|names=name1[,name2...]]

addf abs.N|name thread-name

abs.N.in (float in) Input value
abs.N.out (float out) Output Value, always positive
abs.N.sign (bit out) Sign of Input, false = positive, true = negative

The first abs loaded will be abs.0 and each one after that the "N" number will increment.

Two-input AND gate. For out to be true both inputs must be true

loadrt and2 [count=N|names=name1[,name2...]]

addf and2.N|name thread-name

and2.N.in0 (bit in) Input 0
and2.N.in1 (bit in) Input 1
and2.N.out (bit out) Output

proportional/integral/derivative controller with auto tuning

accepts NML motion commands, interacts with HAL in realtime

Biquad IIR filter

3-wire Bipolar trapezoidal commutation BLDC motor driver using Hall sensors

Perform linear interpolation between two values

loadrt blend [count=N|names=name1[,name2...]]

addf blend.N|name thread-name

blend.N.in1 (float in) First input.
blend.N.in2 (float in) Second input.
blend.N.select (float in) Select input.
blend.N.out (float out) Output value.

blend.N.open (bit r/w)

If select is equal to 0.0 output is equal to in1.

If select is equal to 1.0, the output is equal to in2.

For select values between 0.0 and 1.0, the output changes linearly from in1 to in2.

If blend.N.open is true, select values outside the range 0.0 to 1.0 give values outside the range in1 to in2. If false, outputs are clamped to the the range in1 to in2

Create a square-wave for the "charge pump" input of some controller boards

loadrt charge_pump

addf charge-pump

charge-pump.out (bit out)
charge-pump.enable (bit in) default = TRUE

Outputs a square wave if enable is TRUE or unconnected, low if enable is FALSE

Two input version of Clarke transform

loadrt clarke2 [count=N|names=name1[,name2...]]

addf clarke2.N | name

clarke2.N.a (float in) phase a input
clarke2.N.b (float in) phase b input
clarke2.N.x (float out) cartesian components of output
clarke2.N.y (float out) cartesian components of output

The Clarke transform can be used to translate a vector quantity from a three phase system (three components 120 degrees apart) to a two phase Cartesian system.

clarke2 implements a special case of the Clarke transform, which only needs two of the three input phases. In a three wire three phase system, the sum of the three phase currents or voltages must always be zero. As a result only two of the three are needed to completely define the current or voltage. clarke2 assumes that the sum is zero, so it only uses phases A and B of the input. Since the H (homopolar) output will always be zero in this case, it is not generated.

Clarke (3 phase to cartesian) transform

loadrt clarke3 [count=N|names=name1[,name2...]]

addf clarke3.N | name

clarke3.N.a (float in) three phase input vector
clarke3.N.b (float in) three phase input vector
clarke3.N.c (float in) three phase input vector
clarke3.N.x (float out) cartesian components of output
clarke3.N.y (float out) cartesian components of output
clarke3.N.h (float out) homopolar component of output

The Clarke transform can be used to translate a vector quantity from a three phase system (three components 120 degrees apart) to a two phase Cartesian system (plus a homopolar component if the three phases don’t sum to zero).

clarke3 implements the general case of the transform, using all three phases. If the three phases are known to sum to zero, see clarke2 for a simpler version.

Inverse Clarke transform

loadrt clarkeinv [count=N|names=name1[,name2...]]

addf clarkeinv.N | name

clarkeinv.N.x (float in) cartesian components of input
clarkeinv.N.y (float in) cartesian components of input
clarkeinv.N.h (float in) homopolar component of input (usually zero)
clarkeinv.N.a (float out) three phase output vector
clarkeinv.N.b (float out) three phase output vector
clarkeinv.N.c (float out) three phase output vector

.

The inverse Clarke transform can be used to translate a vector quantity from Cartesian coordinate system to a three phase system (three components 120 degrees apart).

Realtime software plc based on ladder logic

Two input comparator with hysteresis

Use a parameter to set the value of a pin

Convert a value from bit to s32

Convert a value from bit to u32

Convert a value from float to s32

Convert a value from float to u32

Convert a value from s32 to bit

Convert a value from u32 to bit

Convert a value from s32 to u32

Convert a value from u32 to bit

Convert a value from u32 to float

Convert a value from u32 to s32

counts input pulses (deprecated)

Compute the derivative of the input function

Return the center if within the threshold

filter noisy digital inputs, for more information see [sec:Debounce]

Edge detector

software counting of quadrature encoder signals, for more information see [sec:Encoder]

an electronic gear to synchronize two axes

ESTOP latch

Multiply the input by the ratio of current velocity to the feed rate

D type flip-flop

software step pulse generation

A kinematics module that maps one axis to multiple joints

Select from one two speed ranges

Gives six degrees of freedom in position and orientation (XYZABC). The location of the motors is defined at compile time.

Kinematics that can model a general serial-link manipulator with up to 6 angular joints.

HAL driver for the Mesa Electronics 7i43 EPP Anything IO board with HostMot2

HAL driver for the Mesa Electronics 5i20, 5i22, 5i23, 4i65, and 4i68 Anything IO boards, with HostMot2 firmware

HAL driver for the Mesa Electronics HostMot2 firmware

Three-input hypotenuse (Euclidean distance) calculator

Low-pass filter with integer inputs and outputs

Integrator

Compute the inverse of the input signal

sets nonlinear joypad movements, deadbands and scales

kinematics definitions for emc2

Convert counts (probably from an encoder) to a float value

Limit the output signal to fall between min and max

Limit the output signal to fall between min and max

Limit the output signal to fall between min and max

Experimental general logic function component

Low-pass filter

Arbitrary 5-input logic function based on a look-up table

Compute the majority of 3 inputs

8-bit binary match detector

Kinematics for a tabletop 5 axis mill named "max" with tilting head (B axis) and horizintal rotary mounted to the table (C axis). Provides UVW motion in the rotated coordinate system. The source file, maxkins.c, may be a useful starting point for other 5-axis systems.

Track the minimum and maximum values of the input to the outputs

accepts NML motion commands, interacts with HAL in realtime

Product of two inputs

Select from one of two input values

Select from one of four input values

Select from one of eight input values

Determine whether two values are roughly equal

Inverter

Adds an offset to an input, and subtracts it from the feedback value

one-shot pulse generator

Two-input OR gate

proportional/integral/derivative controller, for more information see [sec:PID]

Hardware driver and firmware for the Pluto-P parallel-port FPGA, for use with servos

Hardware driver and firmware for the Pluto-P parallel-port FPGA, for use with steppers

software PWM/PDM generation, for more information see [sec:PWMgen]

The X and Y axes are rotated 45 degrees compared to the joints 0 and 1.

Sample and Hold

sample data from HAL in real time

applies a scale and offset to its input

kinematics for SCARA-type robots

8-bit binary match detector

Hardware driver for the digital I/O bits of the 8250 and 16550 serial port

signal generator, for more information see [sec:Siggen]

simulated quadrature encoder, for more information see [sec:Simulated-Encoder]

Probe a pretend hemisphere

software step pulse generation, for more information see [sec:Stepgen]

Used by Stepconf to allow testing of acceleration and velocity values for an axis

stream file data into HAL in real time

Sum of two inputs (each with a gain) and an offset

set output pins with values from parameters (deprecated)

Torch Height Control using a Mesa THC card.

creates hard realtime HAL threads

component for testing thread behavior

The equivalent of a time-delay relay

component that measures thread scheduling timing behavior

push-on, push-off from momentary pushbuttons

toggle button to nist logic

The joints represent the distance of the controlled point from three predefined locations (the motors), giving three degrees of freedom in position (XYZ)

Place a signal on an I/O pin only when enabled, similar to a tristate buffer in electronics

Place a signal on an I/O pin only when enabled, similar to a tristate buffer in electronics

There is a 1:1 correspondence between joints and axes. Most standard milling machines and lathes use the trivial kinematics module.

Counts up or down, with optional limits and wraparound behavior

Window comparator

convert a group of bits to an integer

Two-input XOR (exclusive OR) gate

.

.

.

.

.

 emc2$ *halcmd loadrt stepgen step_type=<type-array>
[ctrl_type=<ctrl_array>]*

<type-array> is a series of comma separated decimal integers. Each number causes a single step pulse generator to be loaded, the value of the number determines the stepping type. <ctrl_array> is a comma separated series of “p`” or “`v`” characters, to specify position or velocity mode. `ctrl_type is optional, if ommitted, all of the step generators will be position mode. For example:

emc2# *halcmd loadrt stepgen step_type=0,0,2 ctrl_type=p,p,v*

will install three step generators. The first two use step type 0 (step and direction) and run in position mode. The last one uses step type 2 (quadrature) and runs in velocity mode. The default value for <config-array> is “0,0,0” which will install three type 0 (step/dir) generators. The maximum number of step generators is 8 (as defined by MAX_CHAN in stepgen.c). Each generator is independent, but all are updated by the same function(s) at the same time. In the following descriptions, <chan> is the number of a specific generator. The first generator is number 0.

emc2$ *halcmd unloadrt stepgen*

Each step pulse generator will have only some of these pins, depending on the step type and control type selected.

In position mode, the values of maxvel and maxaccel are used by the internal position loop to avoid generating step pulse trains that the motor cannot follow. When set to values that are appropriate for the motor, even a large instantaneous change in commanded position will result in a smooth trapezoidal move to the new location. The algorithm works by measuring both position error and velocity error, and calculating an acceleration that attempts to reduce both to zero at the same time. For more details, including the contents of the “control equation” box, consult the code.

In velocity mode, maxvel is a simple limit that is applied to the commanded velocity, and maxaccel is used to ramp the actual frequency if the commanded velocity changes abruptly. As in position mode, proper values for these parameters ensure that the motor can follow the generated pulse train.

The step generator supports 15 different “step types”. Step type 0 is the most familiar, standard step and direction. When configured for step type 0, there are four extra parameters that determine the exact timing of the step and direction signals. See figure [fig:StepDir-timing] for the meaning of these parameters. The parameters are in nanoseconds, but will be rounded up to an integer multiple of the thread period for the threaed that calls make_pulses(). For example, if make_pulses() is called every 16uS, and steplen is 20000, then the step pulses will be 2 x 16 = 32uS long. The default value for all four of the parameters is 1nS, but the automatic rounding takes effect the first time the code runs. Since one step requires steplen nS high and stepspace nS low, the maximum frequency is 1,000,000,000 divided by (steplen+stepspace). If maxfreq is set higher than that limit, it will be lowered automatically. If maxfreq is zero, it will remain zero, but the output frequency will still be limited.

Step and Direction Timing. Step type 1 has two outputs, up and down. Pulses appear on one or the other, depending on the direction of travel. Each pulse is steplen nS long, and the pulses are separated by at least stepspace nS. The maximum frequency is the same as for step type 0. If maxfreq is set higher than the limit it will be lowered. If maxfreq is zero, it will remain zero but the output frequency will still be limited.

Step types 2 through 14 are state based, and have from two to five outputs. On each step, a state counter is incremented or decremented. Figures [fig:Quad-Three-Phase], [fig:Four-Phase], and [fig:Five-Phase] show the output patterns as a function of the state counter. The maximum frequency is 1,000,000,000 divided by steplen, and as in the other modes, maxfreq will be lowered if it is above the limit.

Five-Phase Step Types. The component exports three functions. Each function acts on all of the step pulse generators - running different generators in different threads is not supported.

The high speed function stepgen.make-pulses should be run in a very fast thread, from 10 to 50uS depending on the capabilities of the computer. That thread’s period determines the maximum step frequency, since steplen, stepspace, dirsetup, dirhold, and dirdelay are all rounded up to a integer multiple of the thread periond in nanoseconds. The other two functions can be called at a much lower rate.

emc2$

<config-array> is a series of comma separated decimal integers. Each number causes a single PWM generator to be loaded, the value of the number determines the output type. For example:

emc2$

will install three PWM generators. The first one will use output type 0 (PWM only), the next uses output type 1 (PWM and direction) and the last one uses output type 2 (UP and DOWN). There is no default value, if <config-array> is not specified, no PWM generators will be installed. The maximum number of frequency generators is 8 (as defined by MAX_CHAN in pwmgen.c). Each generator is independent, but all are updated by the same function(s) at the same time. In the following descriptions, <chan> is the number of a specific generator. The first generator is number 0.

emc2$

Each PWM generator will have the following pins:

Each PWM generator will also have some of these pins, depending on the output type selected:

The PWM generator supports three different “output types”. Type 0 has a single output pin. Only positive commands are accepted, negative values are treated as zero (and will be affected by min-dc if it is non-zero). Type 1 has two output pins, one for the PWM/PDM signal and one to indicate direction. The duty cycle on the PWM pin is based on the absolute value of the command, so negative values are acceptable. The direction pin is false for positive commands, and true for negative commands. Finally, type 2 also has two outputs, called up and down. For positive commands, the PWM signal appears on the up output, and the down output remains false. For negative commands, the PWM signal appears on the down output, and the up output remains false. Output type 2 is suitable for driving most H-bridges.

The component exports two functions. Each function acts on all of the PWM generators - running different generators in different threads is not supported.

The high speed function pwmgen.make-pulses should be run in a very fast thread, from 10 to 50uS depending on the capabilities of the computer. That thread’s period determines the maximum PWM carrier frequency, as well as the resolution of the PWM or PDM signals. The other function can be called at a much lower rate.

Encoder Counter Block Diagram. 

emc2$

<counters> is the number of encoder counters that you want to install. If numchan is not specified, three counters will be installed. The maximum number of counters is 8 (as defined by MAX_CHAN in encoder.c). Each counter is independent, but all are updated by the same function(s) at the same time. In the following descriptions, <chan> is the number of a specific counter. The first counter is number 0.

emc2$

The component exports two functions. Each function acts on all of the encoder counters - running different counters in different threads is not supported.

PID Loop Block Diagram. 

emc2$

<loops> is the number of PID loops that you want to install. If numchan is not specified, one loop will be installed. The maximum number of loops is 16 (as defined by MAX_CHAN in pid.c). Each loop is completely independent. In the following descriptions, <loopnum> is the loop number of a specific loop. The first loop is number 0.

If debug=1 is specified, the component will export a few extra parameters that may be useful during debugging and tuning. By default, the extra parameters are not exported, to save shared memory space and avoid cluttering the parameter list.

emc2$

The three most important pins are

For a position loop, command and feedback are in position units. For a linear axis, this could be inches, mm, meters, or whatever is relevant. Likewise, for an angular axis, it could be degrees, radians, etc. The units of the output pin represent the change needed to make the feedback match the command. As such, for a position loop Output is a velocity, in inches/sec, mm/sec, degrees/sec, etc. Time units are always seconds, and the velocity units match the position units. If command and feedback are in meters, then output is in meters per second.

Each loop has two pins which are used to monitor or control the general operation of the component.

Pins used to report saturation. Saturation occurs when the output of the PID block is at its maximum or minimum limit.

The PID gains, limits, and other tunable features of the loop are implemented as parameters.

All of the max??? limits are implemented such that if the parameter value is zero, there is no limit.

If debug=1 was specified when the component was installed, four additional parameters will be exported:

The component exports one function for each PID loop. This function performs all the calculations needed for the loop. Since each loop has its own function, individual loops can be included in different threads and execute at different rates.

If you want to understand the exact algorithm used to compute the output of the PID loop, refer to figure [fig:PID-block-diag], the comments at the beginning of emc2/src/hal/components/pid.c , and of course to the code itself. The loop calculations are in the C function calc_pid().

emc2$ *halcmd loadrt sim-encoder num_chan=<number>*

<number> is the number of encoders that you want to simulate. If not specified, one encoder will be installed. The maximum number is 8 (as defined by MAX_CHAN in sim_encoder.c).

emc2$ *halcmd unloadrt sim-encoder*

When .speed is positive, .phase-A leads .phase-B.

Note that pulses per revolution is not the same as counts per revolution. A pulse is a complete quadrature cycle. Most encoder counters will count four times during one complete cycle.

The component exports two functions. Each function affects all simulated encoders.

emc2$ *halcmd loadrt debounce cfg=<config-string>*

<config-string> is a series of comma separated decimal integers. Each number installs a group of identical debounce filters, the number determines how many filters are in the group. For example:

emc2$ *halcmd loadrt debounce cfg=1,4,2*

will install three groups of filters. Group 0 contains one filter, group 1 contains four, and group 2 contains two filters. The default value for <config-string> is "1" which will install a single group containing a single filter. The maximum number of groups 8 (as defined by MAX_GROUPS in debounce.c). The maximum number of filters in a group is limited only by shared memory space. Each group is completely independent. All filters in a single group are identical, and they are all updated by the same function at the same time. In the following descriptions, <G> is the group number and <F> is the filter number within the group. The first filter is group 0, filter 0.

emc2$ *halcmd unloadrt debounce*

Each individual filter has two pins.

Each group of filters has one parameter^[11].

The filter delay is in units of thread periods. The minimum delay is zero. The output of a zero delay filter exactly follows its input - it doesn’t filter anything. As delay increases, longer and longer glitches are rejected. If delay is 4, all glitches less than or equal to four thread periods will be rejected.

Each group of filters has one function, which updates all the filters in that group “simultaneously”. Different groups of filters can be updated from different threads at different periods.

emc2$ *halcmd loadrt siggen [num_chan=<chans>]*

<chans> is the number of signal generators that you want to install. If numchan is not specified, one signal generator will be installed. The maximum number of generators is 16 (as defined by MAX_CHAN in siggen.c). Each generator is completely independent. In the following descriptions, <chan> is the number of a specific signal generator (the numbers start at 0).

emc2$ *halcmd unloadrt siggen*

Each generator has five output pins.

All five outputs have the same frequency, amplitude, and offset.

In addition to the output pins, there are three control pins:

For example, if siggen.0.amplitude is 1.0 and siggen.0.offset is 0.0, the outputs will swing from -1.0 to +1.0. If siggen.0.amplitude is 2.5 and siggen.0.offset is 10.0, then the outputs will swing from 7.5 to 12.5.

None. ^[12]

loadrt hal_parport cfg="<config-string>"

loadrt hal_parport cfg="0"

loadrt hal_parport cfg="0x278 0x378 in 0x20A0 out"

For each pin, <portnum> is the port number, and <pinnum> is the physical pin number in the 25 pin D-shell connector.

For each physical output pin, the driver creates a single HAL pin, for example parport.0.pin-14-out . Pins 2 through 9 are part of the data group and are output pins if the port is defined as an output port. (Output is the default.) Pins 1, 14, 16, and 17 are outputs in all modes. These HAL pins control the state of the corresponding physical pins.

For each physical input pin, the driver creates two HAL pins, for example parport.0.pin-12-in and parport.0.pin-12-in-not . Pins 10, 11, 12, 13, and 15 are always input pins. Pins 2 through 9 are input pins only if the port is defined as an input port. The -in HAL pin is TRUE if the physical pin is high, and FALSE if the physical pin is low. The -in-not HAL pin is inverted — it is FALSE if the physical pin is high. By connecting a signal to one or the other, the user can determine the state of the input. In "x" mode, pins 1, 14, 16, and 17 are also input pins.

The -invert parameter determines whether an output pin is active high or active low. If -invert is FALSE, setting the HAL -out pin TRUE drives the physical pin high, and FALSE drives it low. If -invert is TRUE, then setting the HAL -out pin TRUE will drive the physical pin low.

The individual functions are provided for situations where one port needs to be updated in a very fast thread, but other ports can be updated in a slower thread to save CPU time. It is probably not a good idea to use both an -all function and an individual function at the same time.

If loading the module reports

insmod: error inserting '/home/jepler/emc2/rtlib/hal_parport.ko': +
-1 Device or resource busy

then ensure that the standard kernel module parport_pc is not loaded^[13] and that no other device in the system has claimed the I/O ports.

If the module loads but does not appear to function, then the port address is incorrect or the probe_parport module is required.

To setup DoubleStep on the parallel port you must add the function parport.n.reset after parport.n.write and configure stepspace to 0 and the reset time wanted. So that step can be asserted on every period in HAL and then toggled off by parport after being asserted for time specificed by parport.n.reset-time.

For example:

loadrt hal_parport cfg="0x378 out"
setp parport.0.reset-time 5000
loadrt stepgen step_type=0,0,0
addf parport.0.read base-thread
addf stepgen.make-pulses base-thread
addf parport.0.write base-thread
addf parport.0.reset base-thread
addf stepgen.capture-position servo-thread
...
setp stepgen.0.steplen 1
setp stepgen.0.stepspace 0

loadrt probe_parport

loadrt hal_parport ...

If the Linux kernel prints a message similar to

parport: PnPBIOS parport detected.

when the parport_pc module is loaded (sudo modprobe -a parport_pc; sudo rmmod parport_pc) then use of this module is probably required.

<n> is a number between 0 and 8 and selected.

<n> is a number between 0 and 8 and selected.

The maximum linear velocity can be adjusted from 0 to the MAX_VELOCITY that is set in the [TRAJ] section of the ini file.

Sometimes the user wants to add more complicated tasks to be performed by the activation of a HAL pin. This is possible using the following MDI commands scheme:

Each widget is described briefly, followed by the markup used, and a screen shot. All tags inside the main widget tag are optional.

At the present time, both a tag-based and an attribute-based syntax are supported. For instance, the following XML fragments are treated identically:

<led halpin="my-led"/>

and

<led><halpin>"my-led"</halpin></led>

When the attribute-based syntax is used, the following rules are used to turn the attributes value into a Python value:

When the tag-based syntax is used, the text within the tag is always evaluated as a Python expression.

The examples below show a mix of formats.

To add a comment use the xml syntax for a comment.

<!-- My Comment -->

Edit the XML file with a text editor. In most cases you can right click on the file and select "open with text editor" or similar.

Colors can be specified using the X11 rgb colors by name "gray75" or hex "#0000ff”. A complete list is located here http://sedition.com/perl/rgb.html.

Common Colors (colors with numbers indicate shades of that color)

HAL pins provide a means to "connect" the widget to something. Once you create a HAL pin for your widget you can "connect" it to another HAL pin with a "net" command in a .hal file. For more information on the "net" command see the HAL Commands section ( [sec:Hal-Commands]).

A label is a piece of text on your panel.

The label has an optional disable pin that is created when you add <disable_pin>True</disable_pin>.

<label>

The above code produced this example.

A LED is used to indicate the status of a "bit" halpin. The LED color will be on_color when the halpin is true, and off_color otherwise.

<led>

<vbox>

A button is used to control a BIT pin. The pin will be set True when the button is pressed and held down, and will be set False when the button is released. Buttons can use the following formatting options

<button>

<checkbutton>

<radiobutton>

Number displays can use the following formatting options

<number>

<font>("courier 10 pitch",100)</font>

<s32>

<bar>

<meter>

Image displays use only .gif image format. All of the images must be the same size. The images must be in the same directory as your ini file (or in the current directory if running from the command line with halrun/halcmd).

<image name='fwd' file='fwd.gif'/>

<image name='stb' file='stb.gif'/>

Containers are widgets that contain other widgets. Containers are used to group other widgets.

<hbox>

<vbox>

<labelframe text="Group Title">

<table flexible_rows="[2]" flexible_columns="[1,4]">

<tabs>

Open up the custompanel.xml file by right clicking on it and selecting "open with text editor". Between the <pyvcp></pyvcp> tags we will add the widgets for our panel.

Look in the pyVCP Widgets Reference section of the manual for more detailed information on each widget.

In your custompanel.xml file we will add the description of the widgets.

<pyvcp>

<labelframe text="Jog Buttons"> +
<font>("Helvetica",16)</font>

<!--- the X jog buttons ---> +
<hbox> +
<relief>RAISED</relief> +
<bd>3</bd> +
<button> +
<font>("Helvetica",20)</font> +
<width>3</width> +
<halpin>"x-plus"</halpin> +
<text>"X+"</text> +
</button> +
<button> +
<font>("Helvetica",20)</font> +
<width>3</width> +
<halpin>"x-minus"</halpin> +
<text>"X-"</text> +
</button> +
</hbox>

<!--- the Y jog buttons ---> +
<hbox> +
<relief>RAISED</relief> +
<bd>3</bd> +
<button> +
<font>("Helvetica",20)</font> +
<width>3</width> +
<halpin>"y-plus"</halpin> +
<text>"Y+"</text> +
</button> +
<button> +
<font>("Helvetica",20)</font> +
<width>3</width> +
<halpin>"y-minus"</halpin> +
<text>"Y-"</text> +
</button> +
</hbox>

<!--- the Z jog buttons ---> +
<hbox> +
<relief>RAISED</relief> +
<bd>3</bd> +
<button> +
<font>("Helvetica",20)</font> +
<width>3</width> +
<halpin>"z-plus"</halpin> +
<text>"Z+"</text> +
</button> +
<button> +
<font>("Helvetica",20)</font> +
<width>3</width> +
<halpin>"z-minus"</halpin> +
<text>"Z-"</text> +
</button> +
</hbox>

<!--- the jog speed slider ---> +
<vbox> +
<relief>RAISED</relief> +
<bd>3</bd> +
<label> +
<text>"Jog Speed"</text> +
<font>("Helvetica",16)</font> +
</label> +
<scale> +
<font>("Helvetica",14)</font> +
<halpin>"jog-speed"</halpin> +
<resolution>1</resolution> +
<orient>HORIZONTAL</orient> +
<min_>0</min_> +
<max_>80</max_> +
</scale> +
</vbox>

</labelframe>

</pyvcp>

 After adding the above you now will have a pyVCP panel that looks like
the following attached to the right side of AXIS. It looks nice but it
does not do anything until you "connect" the buttons to halui. If you
get an error when you try and run scroll down to the bottom of the pop
up window and usually the error is a spelling or syntax error and it
will be there.

.Jog Buttons[[cap:Jog-Buttons]]

image::images/xyz_buttons.png[]

To make the connections needed open up your custom_postgui.hal file and add the following.

# connect the X pyVCP buttons +
net my-jogxminus halui.jog.0.minus <= pyvcp.x-minus +
net my-jogxplus halui.jog.0.plus <= pyvcp.x-plus

# connect the Y pyVCP buttons +
net my-jogyminus halui.jog.1.minus <= pyvcp.y-minus +
net my-jogyplus halui.jog.1.plus <= pyvcp.y-plus

# connect the Z pyVCP buttons +
net my-jogzminus halui.jog.2.minus <= pyvcp.z-minus +
net my-jogzplus halui.jog.2.plus <= pyvcp.z-plus

# connect the pyVCP jog speed slider  +
net my-jogspeed halui.jog-speed <= pyvcp.jog-speed-f

After resetting the E-Stop and putting it into jog mode and moving the jog speed slider in the pyVCP panel to a value greater than zero the pyVCP jog buttons should work. You can not jog when running a g code file or while paused or while the MDI tab is selected.

To create the panel we add the following to the .xml file.

<pyvcp>

<!-- the RPM meter --> +
<hbox> +
<relief>RAISED</relief> +
<bd>3</bd> +
<meter> +
<halpin>"spindle_rpm"</halpin> +
<text>"Spindle"</text> +
<subtext>"RPM"</subtext> +
<size>200</size> +
<min_>0</min_> +
<max_>3000</max_> +
<majorscale>500</majorscale> +
<minorscale>100</minorscale> +
<region1>0,10,"yellow"</region1> +
</meter> +
</hbox>

<!-- the On Led --> +
<hbox> +
<relief>RAISED</relief> +
<bd>3</bd> +
<vbox> +
<relief>RAISED</relief> +
<bd>2</bd> +
<label> +
<text>"On"</text> +
<font>("Helvetica",18)</font> +
</label> +
<width>5</width> +
 <hbox> +
<label width=”2”/> <!-- used to center the led --> +
<rectled> +
<halpin>"on-led"</halpin> +
<height>"30"</height> +
<width>"30"</width> +
<on_color>"green"</on_color> +
<off_color>"red"</off_color> +
</rectled> +
</hbox> +
</vbox>

<!-- the FWD Led --> +
<vbox> +
<relief>RAISED</relief> +
<bd>2</bd> +
<label> +
<text>"FWD"</text> +
<font>("Helvetica",18)</font> +
<width>5</width> +
</label> +
<label width=”2”/> +
<rectled> +
<halpin>"fwd-led"</halpin> +
<height>"30"</height> +
<width>"30"</width> +
<on_color>"green"</on_color> +
<off_color>"red"</off_color> +
</rectled> +
</vbox>

<!-- the REV Led --> +
<vbox> +
<relief>RAISED</relief> +
<bd>2</bd> +
<label> +
<text>"REV"</text> +
<font>("Helvetica",18)</font> +
<width>5</width> +
</label> +
<label width=”2”/> +
<rectled> +
<halpin>"rev-led"</halpin> +
<height>"30"</height> +
<width>"30"</width> +
<on_color>"red"</on_color> +
<off_color>"green"</off_color> +
</rectled> +
</vbox> +
</hbox> +
</pyvcp>

The above gives us a pyVCP panel that looks like the following.

Figure 14.4. GS2 Panel

To make it work we add the following code to the custom_postgui.hal file.

# display the rpm based on freq * rpm per hz +
loadrt mult2 +
addf mult2.0 servo-thread +
setp mult2.0.in1 28.75 +
net cypher_speed mult2.0.in0 <= spindle-vfd.frequency-out +
net speed_out pyvcp.spindle_rpm <= mult2.0.out

# run led +
net gs2-run => pyvcp.on-led

# fwd led +
net gs2-fwd => pyvcp.fwd-led

# rev led +
net running-rev spindle-vfd.spindle-rev => pyvcp.rev-led

Some of the lines might need some explanations. The fwd led line uses the signal created in the custom.hal file where as the rev led needs to use the spindle-rev bit. You can’t link the spindle-fwd bit twice so you use the signal that it was linked to.

has_bit::: 

 (bit i/o) True if the watchdog has bit, False if the watchdog has not
bit. If the watchdog has bit and the has_bit bit is True, the user can
reset it to False to resume operation.

timeout_ns::: 

 (u32 read/write) Watchdog timeout, in nanoseconds. This is initialized
to 1,000,000,000 (1 second) at module load time. If more than this
amount of time passes between calls to the pet_watchdog() function, the
watchdog will bite.