This documentation is no longer maintained. For documentation of the current version of emc2, please see http://www.linuxcnc.org/docview/html


Internal Components


Stepgen

This component provides software based generation of step pulses in response to position commands. It has a built in pre-tuned position loop, so PID tuning is not required. This component is strongly recommended for stepper based EMC machines, since it eliminates the need to use (and tune) a separate PID loop. It is a realtime component only, and depending on CPU speed, etc, is capable of maximum step rates of 10kHz to perhaps 50kHz. Figure [*] shows three block diagrams, each is a single step pulse generator. The first diagram is for step type '0', (step and direction). The second is for step type '1' (up/down, or pseudo-PWM), and the third is for step types 2 through 14 (various stepping patterns).

Figure: Step Pulse Generator Block Diagram
\includegraphics[clip,width=7.5in,height=8.5in,keepaspectratio]{stepgen-block-diag}

Installing

emc2$ halcmd loadrt stepgen step_type=<config-array>
<config-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. For example:

emc2# halcmd loadrt stepgen.o step_type=0,0,2
will install three step generators, two with step type '0' (step and direction) and one with step type '2' (quadrature). 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.

Removing

emc2$ halcmd unloadrt stepgen

Pins

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

Parameters

The values of maxfreq 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.


Step Types

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 [*] for the meaning of these parameters. The parameters are integers, and represent a number of calls to make_pulses(). For example, if make_pulses() is called every 16uS, and steplen is 2, then the step pulses will be 2 x 16 = 32uS long. The default value for all four of the parameters is 1. Since one step requires steplen periods high and stepspace periods low, the maximum frequency is the thread frequency 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.

Figure: Step and Direction Timing
\includegraphics[width=7in,height=4in,keepaspectratio]{stepgen-type0}

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 one thread period long, and the pulses are separated by at least one thread period. As a result, the maximum step frequency is half of the thread rate. 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 [*], [*], and [*] show the output patterns as a function of the state counter. The maximum frequency is the same as the thread rate, and as in the other modes, maxfreq will be lowered if it is above the limit.

Figure: Quadrature and Three Phase Step Types
\includegraphics[width=6in,height=4in,keepaspectratio]{stepgen-type2-4}

Figure: Four-Phase Step Types
\includegraphics[width=7.5in,height=8.5in,keepaspectratio,angle=90]{stepgen-type5-10}

Figure: Five-Phase Step Types
\includegraphics[width=7.5in,height=8.5in,keepaspectratio]{stepgen-type11-14}

Functions

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, and is also the time unit used by the length, space, setup, and hold parameters (step type 0). The other two functions can be called at a much lower rate.


Freqgen

This component provides software based generation of step pulses from a frequency or velocity command. EMC normally uses position commands, not velocity commands, and stepgen (described in section [*] is more appropriate. However, there may be applications where velocity based pulses are needed. One such application is using step type 1 as a pseudo-PWM output. Combined with a PID loop. the software encoder counter module, and a simple H-bridge, this has been used to run small DC servomotors, however now that the pwmgen component has been added, it is a better choice for this purpose. Another possible use for freqgen is to simply spin a stepper motor at a constant (or adjustable) rate, while ignoring position. Freqgen uses the same pulse generator core as stepgen, however it has no position loop. It is a realtime component only, and depending on CPU speed, etc, is capable of maximum step rates of 10kHz to perhaps 50kHz. Figure [*] shows three block diagrams, each is a single step pulse generator. The first diagram is for step type '0', (step and direction). The second is for step type '1' (up/down, or pseudo-PWM), and the third is for step types 2 through 14 (various stepping patterns).

Figure: Step Pulse Generator Block Diagram
\includegraphics[clip,width=7.5in,height=8.5in,keepaspectratio]{freqgen-block-diag}

Installing

emc2$ halcmd loadrt freqgen step_type=<config-array>
<config-array> is a series of comma separated decimal integers. Each number causes a single frequency generator to be loaded, the value of the number determines the stepping type. For example:

emc2$ halcmd loadrt freqgen step_type=0,0,2
will install three frequency generators, two with step type '0' (step and direction) and one with step type '2' (quadrature). The default value for <config-array> is ``0,0,0'' which will install three type '0' (step/dir) generators. The maximum number of frequency generators is 8 (as defined by MAX_CHAN in freqgen.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.

Removing

emc2$ halcmd unloadrt freqgen

Pins

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

Parameters

Step Types

The frequency generator supports 15 different ``step types''. Except for stepping type 1, they are identical to those generated by the stepgen component. Refer to section [*] for more information.

There is one difference between stepgen and freqgen. 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 one thread period long. Stepgen assumes that you need a distinct pulse for each step, so it limits the frequency to half of the thread rate, to allow for one low period between pulses. However, freqgen allows higher frequencies, up to the thread rate. This allows step type 1 to be used as a pseudo-PWM source, or filtered to use as a D-to-A converter. At the maximum frequency (equal to the thread rate), the up or down output will remain on constantly.

Functions

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 freqgen.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, and is also the time unit used by the length, space, setup, and hold parameters (step type 0). The other two functions can be called at a much lower rate.


PWMgen

This component provides software based generation of PWM (Pulse Width Modulation) and PDM (Pulse Density Modulation) waveforms. It is a realtime component only, and depending on CPU speed, etc, is capable of PWM frequencies from a few hundred Hertz at pretty good resolution, to perhaps 10KHz with limited resolution.

Installing

emc2$ halcmd loadrt pwmgen output_type=<config-array>
<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$ halcmd loadrt pwmgen step_type=0,1,2
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.

Removing

emc2$ halcmd unloadrt pwmgen

Pins

Each PWM generator will have the following pins:

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

Parameters

Output Types

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.

Functions

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

This component provides software based counting of signals from quadrature encoders. It is a realtime component only, and depending on CPU speed, etc, is capable of maximum count rates of 10kHz to perhaps 50kHz. Figure [*] is a block diagram of one channel of encoder counter.

Figure: Encoder Counter Block Diagram
\includegraphics[width=7in,height=6in,keepaspectratio]{encoder-block-diag}

Installing

emc2$ halcmd loadrt encoder [num_chan=<counters>]
<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.

Removing

emc2$ halcmd unloadrt encoder

Pins

Parameters

Functions

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


PID

This component provides Proportional/Integeral/Derivative control loops. It is a realtime component only. For simplicity, this discussion assumes that we are talking about position loops, however this component can be used to implement other feedback loops such as speed, torch height, temperature, etc. Figure [*] is a block diagram of a single PID loop.

Figure: PID Loop Block Diagram
\includegraphics[width=8in,height=10in,keepaspectratio,angle=90,origin=c]{pid-block-diag}

Installing

emc2$ halcmd loadrt pid [num_chan=<loops>] [debug=1]
<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.

Removing

emc2$ halcmd unloadrt pid

Pins

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 other pins which are used to monitor or control the general operation of the component.

Parameters

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:

Functions

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 [*], 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().


Simulated Encoder

The simulated encoder is exactly that. It produces quadrature pulses with an index pulse, at a speed controlled by a HAL pin. Mostly useful for testing.

Installing

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).

Removing

emc2$ halcmd unloadrt sim-encoder

Pins

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

Parameters

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.

Functions

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


Debounce

Debounce is a realtime component that can filter the glitches created by mechanical switch contacts. It may also be useful in other applications where short pulses are to be rejected.

Installing

emc2$ halcmd loadrt debounce cfg=''
<config-string> is a series of space 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.

Removing

emc2$ halcmd unloadrt debounce

Pins

Each individual filter has two pins.

Parameters

Each group of filters has one parameter1.2.

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.

Functions

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.


Blocks

Blocks is a realtime HAL component containing a number of simple functional blocks. They are primarily intended for testing and other offhand uses, but may prove useful for some EMC configurations as well.

Available Blocks

The complete list of available blocks is as follows:

Installing

emc2$ halcmd loadrt blocks <blockname>=<number>

<blockname> is the name of one of the functional blocks that the component can provide, and <number> is the desired quantity of that block. Multiple name/number pairs may be specified on the command line to install a variety of different blocks. For example:

emc2$ halcmd loadrt blocks wcomp=2 sum2=1 comp=3
installs two window comparators (wcomp), one two-input summer (sum2), and three standard comparators (comp).

Removing

emc2$ halcmd unloadrt blocks

Pins

The various blocks each have their own input and output pins. Each pin begins with the block name, then the block number, and finally the pin function.

Parameters

Some of the blocks have parameters that control and adjust the details of their operation. Like the pin names, they begin with the block name and the block number, then the parameter name.

Functions

Each individual block has its own function. This allows complete control over when each block executes. In general, blocks should execute in the order of signal flow. If the outputs of blocks A and B are connected to inputs of block C, then the functions for A and B should be executed before the function for C. Note that unless these functions are connected to a realtime thread so that they execute, the blocks do nothing at all.


Siggen

Siggen is a realtime component that generates square, triangle, and sine waves. It is primarily used for testing.

Installing

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).

Removing

emc2$ halcmd unloadrt siggen

Pins

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.

Parameters

None. 1.3

Functions



Footnotes

...1.1
FF2 is not currently implemented, but it will be added. Consider this note a ``FIXME'' for the code
... parameter1.2
Each individual filter also has an internal state variable. There is a compile time switch that can export that variable as a parameter. This is intended for testing, and simply wastes shared memory under normal circumstances.
...1.3
Prior to version 2.1, frequency, amplitude, and offset were parameters. They were changed to pins to allow control by other components.
2007-01-14