Linux CNC Manual Pages

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 308

Download
Open PDF In Browser	View PDF

LinuxCNC(1)

The Enhanced Machine Controller

LinuxCNC(1)

NAME
linuxcnc − LinuxCNC (The Enhanced Machine Controller)

SYNOPSIS
linuxcnc [-v] [-d] [INIFILE]

DESCRIPTION
linuxcnc is used to start LinuxCNC (The Enhanced Machine Controller). It starts the realtime system and
then initializes a number of LinuxCNC components (IO, Motion, GUI, HAL, etc). The most important
parameter is INIFILE, which specifies the configuration name you would like to run. If INIFILE is not
specified, the linuxcnc script presents a graphical wizard to let you choose one.

OPTIONS
−v

Be a little bit verbose. This causes the script to print information as it works.

−d

Print lots of debug information. All executed commands are echoed to the screen. This mode is
useful when something is not working as it should.

INIFILE
The ini file is the main piece of an LinuxCNC configuration. It is not the entire configuration;
there are various other files that go with it (NML files, HAL files, TBL files, VAR files). It is, however, the most important one, because it is the file that holds the configuration together. It can
adjust a lot of parameters itself, but it also tells linuxcnc which other files to load and use.
There are several ways to specify which config to use:
Specify the absolute path to an ini, e.g.
linuxcnc /usr/local/linuxcnc/configs/sim/sim.ini
Specify a relative path from the current directory, e.g.
linuxcnc configs/sim/sim.ini
Otherwise, in the case where the INIFILE is not specified, the behavior will depend on whether
you configured linuxcnc with --enable-run-in-place. If so, the linuxcnc config chooser will
search only the configs directory in your source tree. If not (or if you are using a packaged version
of linuxcnc), it may search several directories. The config chooser is currently set to search the
path:
˜/linuxcnc/configs:/home/buildslave/emc2-buildbot/precise-amd64-clang/docs/build/configs

EXAMPLES
linuxcnc
linuxcnc configs/sim/sim.ini
linuxcnc /etc/linuxcnc/sample-configs/stepper/stepper_mm.ini

SEE ALSO
halcmd(1)
Much more information about LinuxCNC and HAL is available in the LinuxCNC and HAL User Manuals,
found at /usr/share/doc/linuxcnc/.

HISTORY

LinuxCNC Documentation

2006-02-20

LinuxCNC(1)

The Enhanced Machine Controller

LinuxCNC(1)

BUGS
None known at this time.

AUTHOR
This man page written by Alex Joni, as part of the LinuxCNC Enhanced Machine Controller project.

REPORTING BUGS
Report bugs to alex_joni AT users DOT sourceforge DOT net

COPYRIGHT
Copyright © 2006 Alex Joni.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

2006-02-20

LinuxCNC Documentation

axis-remote(1)

The Enhanced Machine Controller

axis-remote(1)

NAME
axis-remote − AXIS Remote Interface

SYNOPSIS
axis-remote OPTIONS|FILENAME

DESCRIPTION
axis-remote is a small script that triggers commands in a running AXIS GUI. Use axis-remote --help for
further information.

OPTIONS
--ping, -p
Check whether AXIS is running.
--reload, -r
Make AXIS reload the currently loaded file.
--clear, -c
Make AXIS clear the backplot.
--quit, -q
Make AXIS quit.
--help, -h, -?
Display a list of valid parameters for axis-remote.
--mdi COMMAND, -m COMMAND
Run the MDI command COMMAND.
FILENAME
Load the G-code file FILENAME.

SEE ALSO
axis(1)
Much more information about LinuxCNC and HAL is available in the LinuxCNC and HAL User Manuals,
found at /usr/share/doc/linuxcnc/.

HISTORY
BUGS
None known at this time.

AUTHOR
This man page written by Alex Joni, as part of the LinuxCNC project.

REPORTING BUGS
Report bugs to alex_joni AT users DOT sourceforge DOT net

COPYRIGHT
Copyright © 2007 Alex Joni.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC Documentation

2007-04-01

AXIS(1)

The Enhanced Machine Controller

AXIS(1)

NAME
axis − AXIS LinuxCNC Graphical User Interface

SYNOPSIS
axis -ini INIFILE

DESCRIPTION
axis is one of the Graphical User Interfaces (GUI) for LinuxCNC It gets run by the runscript usually.

OPTIONS
INIFILE
The ini file is the main piece of an LinuxCNC configuration. It is not the entire configuration;
there are various other files that go with it (NML files, HAL files, TBL files, VAR files). It is, however, the most important one, because it is the file that holds the configuration together. It can
adjust a lot of parameters itself, but it also tells LinuxCNC which other files to load and use.

SEE ALSO
LinuxCNC(1)
Much more information about LinuxCNC and HAL is available in the LinuxCNC and HAL User Manuals,
found at /usr/share/doc/LinuxCNC/.

HISTORY
BUGS
None known at this time.

AUTHOR
This man page written by Alex Joni, as part of the LinuxCNC project.

REPORTING BUGS
Report bugs to alex_joni AT users DOT sourceforge DOT net

COPYRIGHT
Copyright © 2007 Alex Joni.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

2007-04-01

LinuxCNC Documentation

comp(1)

The Enhanced Machine Controller

comp(1)

NAME
comp − Build, compile and install LinuxCNC HAL components

SYNOPSIS
comp [--compile|--preprocess|--document|--view-doc] compfile...
sudo comp [--install|--install-doc] compfile...
comp --compile --userspace cfile...
sudo comp --install --userspace cfile...
sudo comp --install --userspace pyfile...

DESCRIPTION
comp performs many different functions:
•

Compile .comp and .c files into .so or .ko HAL realtime components (the --compile flag)

•

Compile .comp and .c files into HAL userspace components (the --compile --userspace flag)

•

Preprocess .comp files into .c files (the --preprocess flag)

•

Extract documentation from .comp files into .9 manpage files (the --document flag)

•

Display documentation from .comp files onscreen (the --view-doc flag)

•

Compile and install .comp and .c files into the proper directory for HAL realtime components (the
--install flag), which may require sudo to write to system directories.

•

Install .c and .py files into the proper directory for HAL userspace components (the --install
--userspace flag), which may require sudo to write to system directories.

•

Extract documentation from .comp files into .9 manpage files in the proper system directory (the
--install flag), which may require sudo to write to system directories.

•

Preprocess .comp files into .c files (the --preprocess flag)

SEE ALSO
Comp HAL Component Generator in the LinuxCNC documentation for a full description of the .comp syntax, along with examples
pydoc hal and Creating Userspace Python Components in the LinuxCNC documentation for documentation on the Python interface to HAL components
comp(9) for documentation on the "two input comparator with hysteresis", a HAL realtime component
with the same name as this program

LinuxCNC Documentation

2007-10-17

GLADEVCP(1)

The Enhanced Machine Controller

GLADEVCP(1)

NAME
gladevcp − Virtual Control Panel for LinuxCNC based on Glade, Gtk and HAL widgets

SYNOPSIS
gladevcp [-g WxH+X+Y] [-c component-name] [-u handler] [-U useroption] [-H halfile] [-d] myfile.ui

OPTIONS
-g WxH+X+Y
This sets the initial geometry of the root window. Use ’WxH’ for just size, ’+X+Y’ for just position, or ’WxH+X+Y’ for both. Size / position use pixel units. Position is referenced from top left.
-c component-name
Use component-name as the HAL component name. If the component name is not specified, the
basename of the ui file is used.
-u handler
Instructs gladevcp to inspect the Python script handler for event handlers, and connect them to signals in the ui file.
-U useroption
gladevcp collects all useroption strings and passes them to the handler init() method as a list of
strings without further inspection.
-x XID Reparent gladevcp into an existing window XID instead of creating a new top level window.
-H halfile
gladevcp runs halfile - a list of HAL commands - by executing halcmd -c halfile after the HAL
component is finalized.
-d

enable debug output.

-R gtkrcfile
explicitly load a gtkrc file.
-t THEME
set gtk theme. Default is system theme. Different panels can have different themes.
-m MAXIMUM
force panel window to maxumize. Together with the -g geometry option one can move the panel
to a second monitor and force it to use all of the screen
-R

explicitly deactivate workaround for a gtk bug which makes matches of widget and widget_class
matches in gtk theme and gtkrc files fail. Normally not needed.

SEE ALSO
GladeVCP in the LinuxCNC documentation for a description of gladevcp’s capabilities and the associated
HAL widget set, along with examples

2010-12-20

LinuxCNC Documentation

gs2_vfd(1)

LinuxCNC Documentation

gs2_vfd(1)

NAME
gs2_vfd - HAL userspace component for Automation Direct GS2 VFD’s

SYNOPSIS
gs2_vfd [OPTIONS]

DESCRIPTION
This manual page explains the gs2_vfd component. This component reads and writes to the GS2 via a modbus connection.
gs2_vfd is for use with LinuxCNC

OPTIONS
-b, --bits
(default 8) Set number of data bits to , where n must be from 5 to 8 inclusive
-d, --device
(default /dev/ttyS0) Set the name of the serial device node to use.
-v, --verbose
Turn on verbose mode.
-g, --debug
Turn on debug messages. Note that if there are serial errors, this may become annoying. Debug
mode will cause all modbus messages to be printed in hex on the terminal.
-n, --name
(default gs2_vfd) Set the name of the HAL module. The HAL comp name will be set to ,
and all pin and parameter names will begin with .
-p, --parity [even,odd,none]
(default odd) Set serial parity to even, odd, or none.
-r, --rate
(default 38400) Set baud rate to . It is an error if the rate is not one of the following: 110, 300,
600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
-s, --stopbits [1,2]
(default 1) Set serial stop bits to 1 or 2
-t, --target
(default 1) Set MODBUS target (slave) number. This must match the device number you set on the
GS2.
-A, --accel-seconds
(default 10.0) Seconds to accelerate the spindle from 0 to Max RPM.
-D, --decel-seconds
(default 0.0) Seconds to decelerate the spindle from Max RPM to 0. If set to 0.0 the spindle will
be allowed to coast to a stop without controlled deceleration.
-R, --braking-resistor
This argument should be used when a braking resistor is installed on the GS2 VFD (see Appendix
A of the GS2 manual). It disables deceleration over-voltage stall prevention (see GS2 modbus
Parameter 6.05), allowing the VFD to keep braking even in situations where the motor is regenerating high voltage. The regenerated voltage gets safely dumped into the braking resistor.

PINS

GS2 VFD

January 1, 2009

gs2_vfd(1)

LinuxCNC Documentation

gs2_vfd(1)

.DC-bus-volts (float, out)
from the VFD
.at-speed (bit, out)
when drive is at commanded speed
.err-reset (bit, in)
reset errors sent to VFD
.firmware-revision (s32, out)
from the VFD
.frequency-command (float, out)
from the VFD
.frequency-out (float, out)
from the VFD
.is-stopped (bit, out)
when the VFD reports 0 Hz output
.load-percentage (float, out)
from the VFD
.motor-RPM (float, out)
from the VFD
.output-current (float, out)
from the VFD
.output-voltage (float, out)
from the VFD
.power-factor (float, out)
from the VFD
.scale-frequency (float, out)
from the VFD
.speed-command (float, in)
speed sent to VFD in RPM It is an error to send a speed faster than the Motor Max RPM as set in
the VFD
.spindle-fwd (bit, in)
1 for FWD and 0 for REV sent to VFD
.spindle-on (bit, in)
1 for ON and 0 for OFF sent to VFD, only on when running
.spindle-rev (bit, in)
1 for ON and 0 for OFF, only on when running
.status-1 (s32, out)
Drive Status of the VFD (see the GS2 manual)
.status-2 (s32, out)
Drive Status of the VFD (see the GS2 manual) Note that the value is a sum of all the bits that are
on. So a 163 which means the drive is in the run mode is the sum of 3 (run) + 32 (freq set by
serial) + 128 (operation set by serial).

PARAMETERS
.error-count (s32, RW)

January 1, 2009

GS2 VFD

gs2_vfd(1)

LinuxCNC Documentation

gs2_vfd(1)

.loop-time (float, RW)
how often the modbus is polled (default 0.1)
.nameplate-HZ (float, RW)
Nameplate Hz of motor (default 60)
.nameplate-RPM (float, RW)
Nameplate RPM of motor (default 1730)
.retval (s32, RW)
the return value of an error in HAL
.tolerance (float, RW)
speed tolerance (default 0.01)
.ack-delay (s32, RW)
number of read/write cycles before checking at-speed (default 2)

SEE ALSO
GS2 Driver in the LinuxCNC documentation for a full description of the GS2 syntax
GS2 Examples in the LinuxCNC documentation for examples using the GS2 component

BUGS
AUTHOR
John Thornton

LICENSE
GPL

GS2 VFD

January 1, 2009

HAL_INPUT(1)

HAL User’s Manual

HAL_INPUT(1)

NAME
hal_input − control HAL pins with any Linux input device, including USB HID devices

SYNOPSIS
loadusr hal_input [-KRAL] inputspec ...

DESCRIPTION
hal_input is an interface between HAL and any Linux input device, including USB HID devices. For each
device named, hal_input creates pins corresponding to its keys, absolute axes, and LEDs. At a fixed rate of
approximately 10ms, it synchronizes the device and the HAL pins.

INPUT SPECIFICATION
The inputspec may be in one of several forms:
A string S
A substring or shell-style pattern match will be tested against the "name" of the device, the "phys"
(which gives information about how it is connected), and the "id", which is a string of the form
"Bus=... Vendor=... Product=... Version=...". You can view the name, phys, and id of attached
devices by executing less /proc/bus/input/devices. Examples:
SpaceBall
"Vendor=001f Product=0001"
serio*/input0
A number N
This opens /dev/input/eventN. Except for devices that are always attached to the system, this
number may change over reboots or when the device is removed. For this reason, using an integer
is not recommended.
When several devices are identified by the same string, add ":N" where N is the index of the desired device.
For example, if Mouse matches input3 and input10, then Mouse and Mouse:0 select input3. Specifying
mouse:1 selects input10.
For devices that appear as multiple entries in /dev/input, these indices are likely to stay the same every time.
For multiple identical devices, these indices are likely to depend on the insertion order, but stay the same
across reboots as long as the devices are not moved to different ports or unplugged while the machine is
booted.
If the first character of the inputspec is a "+", then hal_input requests exclusive access to the device. The
first device matching an inputspec is used. Any number of inputspecs may be used.
A subset option may preceed each inputspec. The subset option begins with a dash. Each letter in the subset option specifies a device feature to include. Features that are not specified are excluded. For instance,
to export keyboard LEDs to HAL without exporting keys, use
hal_input -L keyboard ...

DEVICE FEATURES SUPPORTED
•

EV_KEY (buttons and keys). Subset -K

•

EV_ABS (absolute analog inputs). Subset -A

•

EV_REL (relative analog inputs). Subset -R

•

EV_LED (LED outputs). Subset -L

HAL PINS AND PARAMETERS
For buttons
input.N.btn-name bit out
input.N.btn-name-not bit out
Created for each button on the device.

2007-02-25

LinuxCNC Documentation

HAL_INPUT(1)

HAL User’s Manual

HAL_INPUT(1)

For keys
input.N.key-name
input.N.key-name-not
Created for each key on the device.
For absolute axes
input.N.abs-name-counts s32 out
input.N.abs-name-position float out
input.N.abs-name-scale parameter float rw
input.N.abs-name-offset parameter float rw
input.N.abs-name-fuzz parameter s32 rw
input.N.abs-name-flat parameter s32 rw
input.N.abs-name-min parameter s32 r
input.N.abs-name-max parameter s32 r
Created for each absolute axis on the device. Device positions closer than flat to offset are
reported as offset in counts, and counts does not change until the device position changes by at
least fuzz. The position is computed as position = (counts - offset) / scale. The default value of
scale and offset map the range of the axis reported by the operating system to [-1,1]. The default
values of fuzz and flat are those reported by the operating system. The values of min and max are
those reported by the operating system.
For relative axes
input.N.rel-name-counts s32 out
input.N.rel-name-position float out
input.N.rel-name-reset bit in
input.N.rel-name-scale parameter float rw
input.N.rel-name-absolute parameter s32 rw
input.N.rel-name-precision parameter s32 rw
input.N.rel-name-last parameter s32 rw
Created for each relative axis on the device. As long as reset is true, counts is reset to zero
regardless of any past or current axis movement. Otherwise, counts increases or decreases according to the motion of the axis. counts is divided by position-scale to give position. The default
value of position is 1. There are some devices, notably scroll wheels, which return signed values
with less resolution than 32 bits. The default value of precision is 32. precision can be set to 8
for a device that returns signed 8 bit values, or any other value from 1 to 32. absolute, when set
true, ignores duplicate events with the same value. This allows for devices that repeat events without any user action to work correctly. last shows the most recent count value returned by the
device, and is used in the implementation of absolute.
For LEDs
input.N.led-name bit out
input.N.led-name-invert parameter bit rw
Created for each LED on the device.

PERMISSIONS AND UDEV
By default, the input devices may not be accessible to regular users--hal_input requires read-write access,
even if the device has no outputs. To change the default permission of a device, add a new file to
/etc/udev/rules.d to set the device’s GROUP to "plugdev". You can do this for all input devices with this
rule:
SUBSYSTEM=="input", MODE="0660", GROUP="plugdev"
You can also make more specific rules for particular devices. For instance, a SpaceBall input device uses
the ’spaceball’ kernel module, so a udev entry for it would read:
DRIVER=="spaceball", MODE="0660", GROUP="plugdev"
the next time the device is attached to the system, it will be accessible to the "plugdev" group.
For USB devices, the udev line would refer to the device’s Vendor and Product values, such as
SYSFS{idProduct}=="c00e", SYSFS{idVendor}=="046d", MODE="0660", GROUP="plugdev"

LinuxCNC Documentation

2007-02-25

HAL_INPUT(1)

HAL User’s Manual

HAL_INPUT(1)

for a particular logictech-brand mouse.
For more information on writing udev rules, see udev(8).

BUGS
The initial state of keys, buttons, and absolute axes are erroneously reported as FALSE or 0 until an event is
received for that key, button, or axis.

SEE ALSO
hostmot2(9)

LICENSE
GPL

166

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

NAME
hostmot2 − LinuxCNC HAL driver for the Mesa Electronics HostMot2 firmware.

SYNOPSIS
See the config modparam section below for Mesa card configuration. Typically hostmot2 is loaded with no
parameters unless debugging is required.
loadrt hostmot2 [debug_idrom=N] [debug_module_descriptors=N] [debug_pin_descriptors=N]
[debug_modules=N]
debug_idrom [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 IDROM header.
debug_module_descriptors [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 Module Descriptors.
debug_pin_descriptors [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 Pin Descriptors.
debug_modules [default: 0]
Developer/debug use only! Enable debug logging of the HostMot2 Modules used.

DESCRIPTION
hostmot2 is a device driver that interfaces the Mesa HostMot2 firmware to the LinuxCNC HAL. This
driver by itself does nothing, the boards that actually run the firmware require their own drivers before anything can happen. Currently drivers are available for the 5i20, 5i22, 5i23, 5i25, 3x20, 4i65, and 4i68 (all
using the hm2_pci module) and the 7i43 (using the hm2_7i43 module).
The HostMot2 firmware provides modules such as encoders, PWM generators, step/dir generators, and general purpose I/O pins (GPIOs). These things are called "Modules". The firmware is configured, at
firmware compile time, to provide zero or more instances of each of these Modules.

Board I/O Pins
The HostMot2 firmware runs on an FPGA board. The board interfaces with the computer via PCI,
PC-104/Plus, or EPP, and interfaces with motion control hardware such as servos and stepper motors via
I/O pins on the board.
Each I/O pin can be configured, at board-driver load time, to serve one of two purposes: either as a particular I/O pin of a particular Module instance (encoder, pwmgen, stepgen etc), or as a general purpose digital
I/O pin. By default all Module instances are enabled, and all the board’s pins are used by the Module
instances.
The user can disable Module instances at board-driver load time, by specifying a hostmot2 config string
modparam. Any pins which belong to Module instances that have been disabled automatically become
GPIOs.
All IO pins have some HAL presence, whether they belong to an active module instance or are full GPIOs.
GPIOs can be changed (at run-time) between inputs, normal outputs, and open drains, and have a flexible
HAL interface. IO pins that belong to active Module instances are constrained by the requirements of the
owning Module, and have a more limited interface in HAL. This is described in the General Purpose I/O
section below.

config modparam
All the board-driver modules (hm2_pci and hm2_7i43) accept a load-time modparam of type string array,
named "config". This array has one config string for each board the driver should use. Each board’s config
string is passed to and parsed by the hostmot2 driver when the board-driver registers the board.
The config string can contain spaces, so it is usually a good idea to wrap the whole thing in double-quotes
(the " character).

LinuxCNC Documentation

2008-05-13

167

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

The comma character (,) separates members of the config array from each other.
For example, if your control computer has one 5i20 and one 5i23 you might load the hm2_pci driver with a
HAL command (in halcmd) something like this:

loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT num_encoders=3 num_pwmgens=3 num_stepgens=3,firmw
Note: this assumes that the hm2_pci driver detects the 5i20 first and the 5i23 second. If the detection order
does not match the order of the config strings, the hostmot2 driver will refuse to load the firmware and the
board-driver (hm2_pci or hm2_7i43) will fail to load. To the best of my knowledge, there is no way to predict the order in which PCI boards will be detected by the driver, but the detection order will be consistent
as long as PCI boards are not moved around. Best to try loading it and see what the detection order is.
The valid entries in the format string are:
[firmware=F]
[num_encoders=N]
[ssi_chan_N=abc%nq]
[biss_chan_N=abc%nq]
[fanuc_chan_N=abc%nq]
[num_resolvers=N]
[num_pwmgens=N]
[num_3pwmgens=N]
[num_stepgens=N]
[stepgen_width=N]
[sserial_port_0=00000000]
[num_leds=N]
[enable_raw]
firmware [optional]
Load the firmware specified by F into the FPGA on this board. If no "firmware=F"
string is specified, the FPGA will not be re-programmed but may continue to run a previously downloaded firmware.
The requested firmware F is fetched by udev. udev searches for the firmware in the system’s firmware search path, usually /lib/firmware. F typically has the form
"hm2//file.bit"; a typical value for F might be "hm2/5i20/SVST8_4.BIT".
The hostmot2 firmware files are supplied by the hostmot2-firmware packages, available
from linuxcnc.org and can normally be installed by entering the command "sudo apt-get
install hostmot2-firmware-5i23" to install the support files for the 5i23 for example.
The 5i25 / 6i25 come pre-programmed with firmware and no "firmware=" string should
be used with these cards. To change the firmware on a 5i25 or 6i25 the "mesaflash" utility
should be used (available from Mesa). It is perfectly valid and reasonable to load these
cards with no config string at all.
num_dplls [optional, default: -1]
The hm2dpll is a phase-locked loop timer module which may be used to trigger certain
types of encoder. This parameter can be used to disable the hm2dpll by setting the number to 0. There is only ever one module of this type, with 4 timer channels, so the other
valid numbers are -1 (enable all) and 1, both of which end up meaning the same thing.
num_encoders [optional, default: -1]
Only enable the first N encoders. If N is -1, all encoders are enabled. If N is 0, no
encoders are enabled. If N is greater than the number of encoders available in the
firmware, the board will fail to register.

168

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

ssi_chan_N [optional, default: ""]
Specifies how the bit stream from a Synchronous Serial Interface device will be interpreted. There should be an entry for each device connected. Only channels with a format
specifier will be enabled. (as the software can not guess data rates and bit lengths)
biss_chan_N [optional, default: ""]
As for ssi_chan_N, but for BiSS devices
fanuc_chan_N [optional, default: ""]
Specifies how the bit stream from a Fanuc absolute encoder will be interpreted. There
should be an entry for each device connected. Only channels with a format specifier will
be enabled. (as the software can not guess data rates and bit lengths)
num_resolvers [optional, default: -1]
Only enable the first N resolvers. If N = -1 then all resolvers are enabled. This module
does not work with generic resolvers (unlike the encoder module which works with any
encoder). At the time of writing the Hostmot2 Resolver function only works with the
Mesa 7i49 card.
num_pwmgens [optional, default: -1]
Only enable the first N pwmgens. If N is -1, all pwmgens are enabled. If N is 0, no
pwmgens are enabled. If N is greater than the number of pwmgens available in the
firmware, the board will fail to register.
num_3pwmgens [optional, default: -1]
Only enable the first N Three-phase pwmgens. If N is -1, all 3pwmgens are enabled. If N
is 0, no pwmgens are enabled. If N is greater than the number of pwmgens available in
the firmware, the board will fail to register.
num_stepgens [optional, default: -1]
Only enable the first N stepgens. If N is -1, all stepgens are enabled. If N is 0, no stepgens are enabled. If N is greater than the number of stepgens available in the firmware,
the board will fail to register.
stepgen_width [optional, default: 2]
Used to mask extra, unwanted, stepgen pins. Stepper drives typically
require only two pins (step and dir) but the Hostmot2 stepgen can drive
up to 8 output pins for specialised applications (depending on
firmware). This parameter applies to all stepgen instances. Unused,
masked pins will be available as GPIO.
sserial_port_N (N = 0 .. 3) [optional, default: 00000000 for all ports]
Up to 32 Smart Serial devices can be connected to a Mesa Anything IO
board depending on the firmware used and the number of physical connections on the board. These are arranged in 1-4 ports of 1 to 8 channels.
Some Smart Serial (SSLBP) cards offer more than one load-time configuration, for example all inputs, or all outputs, or offering additional
analogue input on some digital pins.
To set the modes for port 0 use, for example sserial_port_0=0120xxxx
A ’0’in the string sets the corresponding port to mode 0, 1 to mode 1,
and so on up to mode 9. An "x" in any position disables that channel
and makes the corresponding FPGA pins available as GPIO.
The string can be up to 8 characters long, and if it defines more modes
than there are channels on the port then the extras are ignored. Channel
numbering is left to right so the example above would set sserial device
0.0 to mode 0, 0.2 to mode2 and disable channels 0.4 onwards.
The sserial driver will auto-detect connected devices, no further configuration should be needed. Unconnected channels will default to GPIO,

LinuxCNC Documentation

2008-05-13

169

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

but the pin values will vary semi-randomly during boot when carddetection runs, to it is best to actively disable any channel that is to be
used for GPIO.
num_bspis [optional, default: -1]
Only enable the first N Buffered SPI drivers. If N is -1 then all the drivers are enabled. Each BSPI driver can address 16 devices.
num_leds [optional, default: -1]
Only enable the first N of the LEDs on the FPGA board. If N is -1, then
HAL pins for all the LEDs will be created. If N=0 then no pins will be
added.
enable_raw [optional]
If specified, this turns on a raw access mode, whereby a user can peek
and poke the firmware from HAL. See Raw Mode below.

dpll
The hm2dpll module has pins like "hm2_..dpll" It is likely
that the pin-count will decrease in the future and that some pins will become parameters.
This module is a phase-locked loop that will synchronise itself with the thread in which
the hostmot2 "read" function is installed and will trigger other functions that are allocated
to it at a specified time before or after the "read" function runs. This can currently only be
applied to the three absolute encoder types and is intended to ensure that the data is ready
when needed, and as fresh as possible.
Pins:
(float, in) hm2_..dpll.NN.timer-us
This pin sets the triggering offset of the associated timer. There are 4 timers
numbered 01 to 04, represented by the NN digits in the pin name. The units are
micro-seconds. Negative numbers indicate that the trigger should occur prior to
the main hostmot2 write. It is anticipated that this value will be calculated from
the known bit-count and data-rate of the functions to be triggered. Alternatively
you can just keep making the number more negative until the over-run error bit
in the encoder goes false. The default value is set to 100uS, enough time for
approximately 50 bits to be transmitted at 500kHz. For very critical systems it
may be worth reducing this until errors appear, and for very long bit-length or
slow encoders it will need to be increased.
(float, in) hm2_..dpll.base-freq-khz
This pin sets the base frequency of the phase-locked loop. by default it will be
set to the nominal frequency of the thread in which the PLL is running and wil
not normally need to be changed.
(float, out) hm2_..dpll.phase-error-us
Indicates the phase eror of the DPLL. If the number cycles by a large amount it
is likely that the PLL has failed to achieve lock and adjustments will need to be
made.
(u32, in) hm2_..dpll.time-const"
The filter time-constant for the PLL. Default 40960 (0xA000)
(u32, in) hm2_..dpll.plimit"
Sets the phase adjustment limit of the PLL. If the value is zero then the PLL will
free-run at the base frequency independent of the servo thread rate. This is probably not what you want. Default 4194304 (0x400000) Units not known...

170

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

(u32, out) hm2_..dpll.ddsize
Used internally by the driver, likely to disappear.
(u32, in) hm2_..dpll.prescale
Prescale factor for the rate generator. Default 1.

encoder
Encoders have names like "hm2_..encoder.".
"Instance" is a two-digit number that corresponds to the HostMot2 encoder instance number. There are ’num_encoders’ instances, starting with 00.
So, for example, the HAL pin that has the current position of the second encoder of the
first 5i20 board is: hm2_5i20.0.encoder.01.position (this assumes that the firmware in that
board is configured so that this HAL object is available)
Each encoder uses three or four input IO pins, depending on how the firmware was compiled. Three-pin encoders use A, B, and Index (sometimes also known as Z). Four-pin
encoders use A, B, Index, and Index-mask.
The hm2 encoder representation is similar to the one described by the Canonical Device
Interface (in the HAL General Reference document), and to the software encoder component. Each encoder instance has the following pins and parameters:
Pins:
(s32 out) count
Number of encoder counts since the previous reset.
(float out) position
Encoder position in position units (count / scale).
(float out) velocity
Estimated encoder velocity in position units per second.
(bit in) reset
When this pin is TRUE, the count and position pins are set to 0. (The value of
the velocity pin is not affected by this.) The driver does not reset this pin to
FALSE after resetting the count to 0, that is the user’s job.
(bit in/out) index-enable
When this pin is set to True, the count (and therefore also position) are reset to
zero on the next Index (Phase-Z) pulse. At the same time, index-enable is reset
to zero to indicate that the pulse has occurred.
(s32 out) rawcounts
Total number of encoder counts since the start, not adjusted for index or reset.
Parameters:

LinuxCNC Documentation

2008-05-13

171

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

(float r/w) scale
Converts from ’count’ units to ’position’ units.
(bit r/w) index-invert
If set to True, the rising edge of the Index input pin triggers the Index event (if
index-enable is True). If set to False, the falling edge triggers.
(bit r/w) index-mask
If set to True, the Index input pin only has an effect if the Index-Mask input pin
is True (or False, depending on the index-mask-invert pin below).
(bit r/w) index-mask-invert
If set to True, Index-Mask must be False for Index to have an effect. If set to
False, the Index-Mask pin must be True.
(bit r/w) counter-mode
Set to False (the default) for Quadrature. Set to True for Step/Dir (in which case
Step is on the A pin and Dir is on the B pin).
(bit r/w) filter
If set to True (the default), the quadrature counter needs 15 clocks to register a
change on any of the three input lines (any pulse shorter than this is rejected as
noise). If set to False, the quadrature counter needs only 3 clocks to register a
change. The encoder sample clock runs at 33 MHz on the PCI AnyIO cards and
50 MHz on the 7i43.
(float r/w) vel-timeout
When the encoder is moving slower than one pulse for each time that the driver
reads the count from the FPGA (in the hm2_read() function), the velocity is
harder to estimate. The driver can wait several iterations for the next pulse to
arrive, all the while reporting the upper bound of the encoder velocity, which can
be accurately guessed. This parameter specifies how long to wait for the next
pulse, before reporting the encoder stopped. This parameter is in seconds.

Synchronous Serial Interface (SSI)
(Not to be confused with the Smart Serial Interface)
One pin is created for each SSI instance regardless of data format: (bit, in)
hm2_XiXX.NN.ssi.MM.data-incomplete This pin will be set "true" if the module was
still transferring data when the value was read. When this problem exists there will also
be a limited number of error messages printed to the UI. This pin should be used to monitor whether the problem has been addressed by config changes. Solutions to the problem
dpend on whether the encoder read is being triggered by the hm2dpll phase-locked-loop
timer (described above) or by the trigger-encoders function (described below).
The names of the pins created by the SSI module will depend entirely on the format
string for each channel specified in the loadrt command line. A typical format string
might be
ssi_chan_0=error%1bposition%24g
This would interpret the LSB of the bit-stream as a bit-type pin named "error" and the
next 24 bits as a Gray-coded encoder counter. The encoder-related HAL pins would all

172

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

begin with "position".
There should be no spaces in the format string, as this is used as a delimiter by the lowlevel code.
The format consists of a string of alphanumeric characters that will form the HAL pin
names, followed by a % symbol, a bit-count and a data type. All bits in the packet must
be defined, even if they are not used. There is a limit of 64 bits in total.
The valid format characters and the pins they create are:
p: (Pad). Does not create any pins, used to ignore sections of the bit stream that are not
required.
b: (Boolean).
(bit, out) hm2_XiXX.N.ssi.MM.. If any bits in the designated field
width are non-zero then the HAL pin will be "true".
(bit, out) hm2_XiXX.N.ssi.MM.-not. An inverted version of the above,
the HAL pin will be "true" if all bits in the field are zero.
u: (Unsigned)
(float, out) hm2_XiXX.N.ssi.MM.. The value of the bits interpeted as
an unsigned integer then scaled such that the pin value will equal the scalemax
parameter value when all bits are high. (for example if the field is 8 bits wide
and the scalmax parameter was 20 then a value of 255 would return 20, and 0
would return 0.
s: (Signed)
(float, out) hm2_XiXX.N.ssi.MM.. The value of the bits interpreted as
a 2s complement signed number then scaled similarly to the unsigned variant,
except symmetrical around zero.
f: (bitField)
(bit, out) hm2_XiXX.N.ssi.MM.-NN. The value of each individual bit
in the data field. NN starts at 00 up to the number of bits in the field.
(bit, out) hm2_XiXX.N.ssi.MM.-NN-not. An inverted version of the
individual bit values.
e: (Encoder)
(s32, out) hm2_XiXX.N.ssi.MM..count. The lower 32 bits of the total
encoder counts. This value is reset both by the ...reset and the ...index- enable
pins.
(s32, out) hm2_XiXX.N.ssi.MM..rawcounts. The lower 32 bits of the
total encoder counts. The pin is not affected by reset and index.
(float, out) hm2_XiXX.N.ssi.MM..position. The encoder position in
machine units. This is calculated from the full 64-bit buffers so will show a true
value even after the counts pins have wrapped. It is zeroed by reset and index
enable.
(bit, IO) hm2_XiXX.N.ssi.MM..index-enable. When this pin is set
"true" the module will wait until the raw encoder counts next passes through an
integer multiple of the number of counts specified by counts-per-rev parameter
and then it will zero the counts and position pins, and set the index-enable pin
back to "false" as a signal to the system that "index" has been passed. this pin is
used for spindle-synchronised motion and index-homing.
(bit, in) (bit, out) hm2_XiXX.N.ssi.MM..reset. When this pin is set high
the counts and position pins are zeroed.

LinuxCNC Documentation

2008-05-13

173

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

h: (Split encoder, high-order bits)
Some encoders (Including Fanuc) place the encoder part-turn counts and fullturn counts in separate, non-contiguous fields. This tag defines the high-order
bits of such an encoder module. There can be only one h and one l tag per channel, the behaviour with multiple such channels will be undefined.
l: (Split encoder, low-order bits)
Low order bits (see "h")
g: (Gray-code). This is a modifier that indicates that the following
format string is gray-code encoded. This is only valid for encoders (e, h l) and
unsigned (u) data types.
Parameters:
Two parameters is universally created for all SSI instances
(float r/w) hm2_XiXX.N.ssi.MM.frequency-khz
This parameter sets the SSI clock frequency. The units are kHz, so 500 will give
a clock frequency of 500,000 Hz.
(u32 r/w) hm2_XiXX.N.ssi.MM.timer-num
This parameter allocates the SSI module to a specific hm2dpll timer instance.
This pin is only of use in firmwares which contain a hm2dpll function and will
default to 1 in cases where there is such a function, and 0 if there is not. The pin
can be used to disable reads of the encoder, by setting to a nonexistent timer
number, or to 0.
Other parameters depend on the data types specified in the config string.
p: (Pad) No Parameters.
b: (Boolean) No Parameters.
u: (Unsigned)
(float, r/w) hm2_XiXX.N.ssi.MM..scalemax. The scaling factor for the
channel.
s: (Signed)
(float, r/w) hm2_XiXX.N.ssi.MM..scalemax. The scaling factor for the
channel.
f: (bitField): No parameters.
e: (Encoder):
(float, r/w) hm2_XiXX.N.ssi.MM..scale: (float, r.w) The encoder scale
in counts per machine unit.
(u32, r/w) hm2_XiXX.N.ssi.MM..counts-per-rev (u32, r/w) Used to
emulate the index behaviour of an incemental+index encoder. This would normally be set to the actual counts per rev of the encoder, but can be any whole
number of revs. Integer divisors or multimpilers of the true PPR might be useful
for index-homing. Non-integer factors might be appropriate where there is a synchronous drive ratio between the encoder and the spindle or ballscrew.

BiSS
BiSS is a bidirectional variant of SSI. Currently only a single direction is supported by
LinuxCNC (encoder to PC).

174

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

One pin is created for each BiSS instance regardless of data format:
(bit, in) hm2_XiXX.NN.biss.MM.data-incomplete This pin will be set "true" if the module was still transferring data when the value was read. When this problem exists there
will also be a limited number of error messages printed to the UI. This pin should be used
to monitor whether the problem has been addressed by config changes. Solutions to the
problem dpend on whether the encoder read is being triggered by the hm2dpll phaselocked-loop timer (described above) or by the trigger-encoders function (described
below)
The names of the pins created by the BiSS module will depend entirely on the format
string for each channel specified in the loadrt command line and follow closely the format
defined above for SSI. Currently data packets of up to 96 bits are supported by the LinuxCNC driver, although the Mesa Hostmot2 module can handle 512 bit packets. It should
be possible to extend the number of packets supported by the driver if there is a requirement to do so.

Fanuc encoder.
The pins and format specifier for this module are identical to the SSI module described
above, except that at least one pre-configured format is provided. A modparam of
fanuc_chan_N=AA64 (case sensitive) will configure the channel for a Fanuc Aa64
encoder. The pins created are:
hm2_XiXX.N.fanuc.MM.batt
indicates battery state
hm2_XiXX.N.fanuc.MM.batt-not
inverted version of above
hm2_XiXX.N.fanuc.MM.comm
The 0-1023 absolute output for motor commutation
hm2_XXiX.N.fanuc.MM.crc
The CRC checksum. Currently HAL has no way
to use this
hm2_XiXX.N.fanuc.MM.encoder.count
Encoder counts
hm2_XiXX.N.fanuc.MM.encoder.index-enable Simulated index. Set by counts-per-rev
parameter
hm2_XiXX.N.fanuc.MM.encoder.position Counts scaled by the ...scale paramter
hm2_XiXX.N.fanuc.MM.encoder.rawcounts Raw counts, unaffected by reset or index
hm2_XiXX.N.fanuc.MM.encoder.reset
If high/true then counts and position = 0
hm2_XiXX.N.fanuc.MM.valid
Indicates that the absolute position is valid
hm2_XiXX.N.fanuc.MM.valid-not
Inverted version

resolver
Resolvers have names like hm2_..resolver..
..pwmgen.".
"Instance" is a two-digit number that corresponds to the HostMot2 pwmgen instance
number. There are ’num_pwmgens’ instances, starting with 00.
So, for example, the HAL pin that enables output from the fourth pwmgen of the first
7i43 board is: hm2_7i43.0.pwmgen.03.enable (this assumes that the firmware in that
board is configured so that this HAL object is available)
In HM2, each pwmgen uses three output IO pins: Not-Enable, Out0, and Out1.
The function of the Out0 and Out1 IO pins varies with output-type parameter (see below).
The hm2 pwmgen representation is similar to the software pwmgen component. Each
pwmgen instance has the following pins and parameters:
Pins:
(bit input) enable
If true, the pwmgen will set its Not-Enable pin false and output its pulses. If
’enable’ is false, pwmgen will set its Not-Enable pin true and not output any signals.
(float input) value
The current pwmgen command value, in arbitrary units.
Parameters:
(float rw) scale
Scaling factor to convert ’value’ from arbitrary units to duty cycle: dc = value /
scale. Duty cycle has an effective range of -1.0 to +1.0 inclusive, anything outside that range gets clipped. The default scale is 1.0.
(s32 rw) output-type
This emulates the output_type load-time argument to the software pwmgen component. This parameter may be changed at runtime, but most of the time you
probably want to set it at startup and then leave it alone. Accepted values are 1
(PWM on Out0 and Direction on Out1), 2 (Up on Out0 and Down on Out1), 3
(PDM mode, PDM on Out0 and Dir on Out1), and 4 (Direction on Out0 and
PWM on Out1, "for locked antiphase").
In addition to the per-instance HAL Parameters listed above, there are a couple

LinuxCNC Documentation

2008-05-13

177

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

of HAL Parameters that affect all the pwmgen instances:
(u32 rw) pwm_frequency
This specifies the PWM frequency, in Hz, of all the pwmgen instances running
in the PWM modes (modes 1 and 2). This is the frequency of the variable-dutycycle wave. Its effective range is from 1 Hz up to 193 kHz. Note that the max
frequency is determined by the ClockHigh frequency of the Anything IO board;
the 5i20 and 7i43 both have a 100 MHz clock, resulting in a 193 kHz max PWM
frequency. Other boards may have different clocks, resulting in different max
PWM frequencies. If the user attempts to set the frequency too high, it will be
clipped to the max supported frequency of the board. Frequencies below about 5
Hz are not terribly accurate, but above 5 Hz they’re pretty close. The default
pwm_frequency is 20,000 Hz (20 kHz).
(u32 rw) pdm_frequency
This specifies the PDM frequency, in Hz, of all the pwmgen instances running in
PDM mode (mode 3). This is the "pulse slot frequency"; the frequency at which
the pdm generator in the AnyIO board chooses whether to emit a pulse or a
space. Each pulse (and space) in the PDM pulse train has a duration of
1/pdm_frequency seconds. For example, setting the pdm_frequency to 2e6 (2
MHz) and the duty cycle to 50% results in a 1 MHz square wave, identical to a 1
MHz PWM signal with 50% duty cycle. The effective range of this parameter is
from about 1525 Hz up to just under 100 MHz. Note that the max frequency is
determined by the ClockHigh frequency of the Anything IO board; the 5i20 and
7i43 both have a 100 MHz clock, resulting in a 100 Mhz max PDM frequency.
Other boards may have different clocks, resulting in different max PDM frequencies. If the user attempts to set the frequency too high, it will be clipped to
the max supported frequency of the board. The default pdm_frequency is
20,000 Hz (20 kHz).

3ppwmgen
Three-Phase PWM generators (3pwmgens) are intended for controlling the high-side and
low-side gates in a 3-phase motor driver. The function is included to support the Mesa
motor controller daughter-cards but can be used to control an IGBT or similar driver
directly. 3pwmgens have names like "hm2_..3pwmgen." where is a 2-digit number. There will be num_3pwmgens
instances, starting at 00. Each instance allocates 7 output and one input pins on the Mesa
card connectors. Outputs are: PWM A, PWM B, PWM C, /PWM A, /PWM B, /PWM C,
Enable. The first three pins are the high side drivers, the second three are their complementary low-side drivers. The enable bit is intended to control the servo amplifier. The
input bit is a fault bit, typically wired to over-current detection. When set the PWM generator is disabled. The three phase duty-cycles are individually controllable from -Scale
to +Scale. Note that 0 corresponds to a 50% duty cycle and this is the inialization value.
Pins:
(float input) A-value, B-value, C-value: The PWM command value for each phase, limited to +/- "scale". Defaults to zero which is 50% duty cycle on high-side and low-sidepins (but see the "deadtime" parameter)
(bit input) enable
When high the PWM is enabled as long as the fault bit is not set by the external
fault input pin. When low the PWM is disabled, with both high- side and low-

178

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

side drivers low. This is not the same as 0 output (50% duty cycle on both sets of
pins) or negative full scale (where the low side drivers are "on" 100% of the
time)
(bit output) fault
Indicates the status of the fault bit. This output latches high once set by the physical fault pin until the "enable" pin is set to high.
Parameters:
(u32 rw) deadtime
Sets the dead-time between the high-side driver turning off and the low-side
driver turning on and vice-versa. Deadtime is subtracted from on time and added
to off time symmetrically. For example with 20 kHz PWM (50 uSec period),
50% duty cycle and zero dead time, the PWM and NPWM outputs would be
square waves (NPWM being inverted from PWM) with high times of 25 uS.
With the same settings but 1 uS of deadtime, the PWM and NPWM outputs
would both have high times of 23 uS (25 - (2X 1 uS), 1 uS per edge). The value
is specified in nS and defaults to a rather conservative 5000nS. Setting this
parameter to too low a value could be both expensive and dangerous as if both
gates are open at the same time there is effectively a short circuit accross the
supply.
(float rw) scale
Sets the half-scale of the specified 3-phase PWM generator. PWM values from
-scale to +scale are valid. Default is +/- 1.0
(bit rw) fault-invert
Sets the polarity of the fault input pin. A value of 1 means that a fault is triggered with the pin high, and 0 means that a fault it triggered when the pin is
pulled low. Default 0, fault = low so that the PWM works with the fault pin
unconnected.
(u32 rw) sample-time
Sets the time during the cycle when an ADC pulse is generated. 0 = start of
PWM cycle and 1 = end. Not currently useful to LinuxCNC. Default 0.5.
In addition the per-instance parameters above there is the following parameter
that affects all instances
(u32 rw) frequency
Sets the master PWM frequency. Maximum is approx 48kHz, minimum is 1kHz.
Defaults to 20kHz.

stepgen
stepgens have names like "hm2_..stepgen.".
"Instance" is a two-digit number that corresponds to the HostMot2 stepgen instance number. There are ’num_stepgens’ instances, starting with 00.
So, for example, the HAL pin that has the current position feedback from the first stepgen
of the second 5i22 board is: hm2_5i22.1.stepgen.00.position-fb (this assumes that the

LinuxCNC Documentation

2008-05-13

179

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

firmware in that board is configured so that this HAL object is available)
Each stepgen uses between 2 and 6 IO pins. The signals on these pins depends on the
step_type parameter (described below).
The stepgen representation is modeled on the stepgen software component. Each stepgen
instance has the following pins and parameters:
Pins:
(float input) position-cmd
Target position of stepper motion, in arbitrary position units. This pin is only
used when the stepgen is in position control mode (control-type=0).
(float input) velocity-cmd
Target velocity of stepper motion, in arbitrary position units per second. This
pin is only used when the stepgen is in velocity control mode (control-type=1).
(s32 output) counts
Feedback position in counts (number of steps).
(float output) position-fb
Feedback position in arbitrary position units. This is similar to "counts/position_scale", but has finer than step resolution.
(float output) velocity-fb
Feedback velocity in arbitrary position units per second.
(bit input) enable
This pin enables the step generator instance. When True, the stepgen instance
works as expected. When False, no steps are generated and velocity-fb goes
immediately to 0. If the stepgen is moving when enable goes false it stops
immediately, without obeying the maxaccel limit.
(bit input) control-type
Switches between position control mode (0) and velocity control mode (1).
Defaults to position control (0).
Parameters:
(float r/w) position-scale
Converts from counts to position units. position = counts / position_scale
(float r/w) maxvel
Maximum speed, in position units per second. If set to 0, the driver will always
use the maximum possible velocity based on the current step timings and position-scale. The max velocity will change if the step timings or position-scale
changes. Defaults to 0.

180

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

(float r/w) maxaccel
Maximum acceleration, in position units per second per second. Defaults to 1.0.
If set to 0, the driver will not limit its acceleration at all - this requires that the
position-cmd or velocity-cmd pin is driven in a way that does not exceed the
machine’s capabilities. This is probably what you want if you’re going to be
using the LinuxCNC trajectory planner to jog or run G-code.
(u32 r/w) steplen
Duration of the step signal, in nanoseconds.
(u32 r/w) stepspace
Minimum interval between step signals, in nanoseconds.
(u32 r/w) dirsetup
Minimum duration of stable Direction signal before a step begins, in nanoseconds.
(u32 r/w) dirhold
Minimum duration of stable Direction signal after a step ends, in nanoseconds.
(u32 r/w) step_type
Output format, like the step_type modparam to the software stegen(9) component. 0 = Step/Dir, 1 = Up/Down, 2 = Quadrature, 3+ = table-lookup mode. In
this mode the step_type parameter determines how long the step sequence is.
Additionally the stepgen_width parameter in the loadrt config string must be set
to suit the number of pins per stepgen required. Any stepgen pins above this
number will be available for GPIO. This mask defaults to 2. The maximum
length is 16. Note that Table mode is not enabled in all firmwares but if you see
GPIO pins between the stepgen instances in the dmesg/log hardware pin list then
the option may be available.
In Quadrature mode (step_type=2), the stepgen outputs one complete Gray cycle
(00 â 01 â 11 â 10 â 00) for each "step" it takes. In table mode up to 6 IO pins
are individually controlled in an arbitrary sequence up to 16 phases long.
(u32 r/w) table-data-N
There are 4 table-data-N parameters, table-data-0 to table-data-3. These each
contain 4 bytes corresponding to 4 stages in the step sequence. For example table-data-0 = 0x00000001 would set stepgen pin 0 (always called "Step" in the
dmesg output) on the first phase of the step sequence, and table-data-4 =
0x20000000 would set stepgen pin 6 ("Table5Pin" in the dmesg output) on the
16th stage of the step sequence.

Smart Serial Interface
The Smart Serial Interface allows up to 32 different devices such as the Mesa 8i20 2.2kW
3-phase drive or 7i64 48-way IO cards to be connected to a single FPGA card. The driver
auto-detects the connected hardware port, channel and device type. Devices can be connected in any order to any active channel of an active port. (see the config modparam
definition above).
For full details of the smart-serial devices see man sserial.

LinuxCNC Documentation

2008-05-13

181

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

BSPI
The BSPI (Buffered SPI) driver is unusual in that it does not create any HAL pins.
Instead the driver exports a set of functions that can be used by a sub -driver for the
attached hardware. Typically these would be written in the "comp" pre-processing language: see http://linuxcnc.org/docs/html/hal_comp.html or man comp for further details.
See man mesa_7i65 and the source of mesa_7i65.comp for details of a typical sub-driver.
See
man
hm2_bspi_setup_chan,
man
hm2_bspi_write_chan,
man
hm2_tram_add_bspi_frame, man hm2_allocate_bspi_tram, man hm2_bspi_set_read_funtion and man hm2_bspi_set_write_function for the exported functions.
The names of the available channels are printed to standard output during the driver loading process and take the form hm2_..bspi. For
example hm2_5i23.0.bspi.0

UART
The UART driver also does not create any HAL pins, instead it declares two simple
read/write functions and a setup function to be utilised by user-written code. Typically
this would be written in the "comp" pre-processing language: see http://linuxcnc.org/docs/html/hal_comp.html or man comp for further details. See man mesa_uart
and the source of mesa_uart.comp for details of a typical sub-driver. See man
hm2_uart_setup_chan, man hm2_uart_send, man hm2_uart_read and man hm2_uart_setup.
The names of the available uart channels are printed to standard output during the driver
loading process and take the form hm2_.uart. For
example hm2_5i23.0.uart.0

General Purpose I/O
I/O pins on the board which are not used by a module instance are exported to HAL as
"full" GPIO pins. Full GPIO pins can be configured at run-time to be inputs, outputs, or
open drains, and have a HAL interface that exposes this flexibility. IO pins that are
owned by an active module instance are constrained by the requirements of the owning
module, and have a restricted HAL interface.
GPIOs have names like "hm2_..gpio.". IONum is
a three-digit number. The mapping from IONum to connector and pin-on-that-connector
is written to the syslog when the driver loads, and it’s documented in Mesa’s manual for
the Anything I/O boards.
So, for example, the HAL pin that has the current inverted input value read from GPIO
012 of the second 7i43 board is: hm2_7i43.1.gpio.012.in-not (this assumes that the
firmware in that board is configured so that this HAL object is available)
The HAL parameter that controls whether the last GPIO of the first 5i22 is an input or an
output is: hm2_5i22.0.gpio.095.is_output (this assumes that the firmware in that board is
configured so that this HAL object is available)
The hm2 GPIO representation is modeled after the Digital Inputs and Digital Outputs
described in the Canonical Device Interface (part of the HAL General Reference document). Each GPIO can have the following HAL Pins:
(bit out) in & in_not: State (normal and inverted) of the hardware input pin. Both full
GPIO pins and IO pins used as inputs by active module instances have these pins.

182

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

(bit in) out
Value to be written (possibly inverted) to the hardware output pin. Only full
GPIO pins have this pin.
Each GPIO can have the following Parameters:
(bit r/w) is_output
If set to 0, the GPIO is an input. The IO pin is put in a high-impedance state
(weakly pulled high), to be driven by other devices. The logic value on the IO
pin is available in the "in" and "in_not" HAL pins. Writes to the "out" HAL pin
have no effect. If this parameter is set to 1, the GPIO is an output; its behavior
then depends on the "is_opendrain" parameter. Only full GPIO pins have this
parameter.
(bit r/w) is_opendrain
This parameter only has an effect if the "is_output" parameter is true. If this
parameter is false, the GPIO behaves as a normal output pin: the IO pin on the
connector is driven to the value specified by the "out" HAL pin (possibly
inverted), and the value of the "in" and "in_not" HAL pins is undefined. If this
parameter is true, the GPIO behaves as an open-drain pin. Writing 0 to the "out"
HAL pin drives the IO pin low, writing 1 to the "out" HAL pin puts the IO pin in
a high-impedance state. In this high-impedance state the IO pin floats (weakly
pulled high), and other devices can drive the value; the resulting value on the IO
pin is available on the "in" and "in_not" pins. Only full GPIO pins and IO pins
used as outputs by active module instances have this parameter.
(bit r/w) invert_output
This parameter only has an effect if the "is_output" parameter is true. If this
parameter is true, the output value of the GPIO will be the inverse of the value
on the "out" HAL pin. Only full GPIO pins and IO pins used as outputs by
active module instances have this parameter.

led
Creates HAL pins for the LEDs on the FPGA board.
Pins:
(bit in) CR
The pins are numbered from CR01 upwards with the name corresponding to the
PCB silkscreen. Setting the bit to "true" or 1 lights the led.

Watchdog
The HostMot2 firmware may include a watchdog Module; if it does, the hostmot2 driver
will use it. The HAL representation of the watchdog is named "hm2_..watchdog".
The watchdog starts out asleep and inactive. Once you access the board the first time by
running any the hm2 HAL functions read(), write(), or pet_watchdog() (see below), the
watchdog wakes up. From them on it must be petted periodically or it will bite. Pet the
watchdog by running the pet_watchdog() HAL function.
When the watchdog bites, all the board’s I/O pins are disconnected from their Module

LinuxCNC Documentation

2008-05-13

183

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

instances and become high-impedance inputs (pulled high), and all communication with
the board stops. The state of the HostMot2 firwmare modules is not disturbed (except for
the configuration of the IO Pins). Encoder instances keep counting quadrature pulses,
and pwm- and step-generators keep generating signals (which are *not* relayed to the
motors, because the IO Pins have become inputs).
Resetting the watchdog (by clearing the has_bit pin, see below) resumes communication
and resets the I/O pins to the configuration chosen at load-time.
If the firmware includes a watchdog, the following HAL objects will be exported:
Pins:
(bit in/out) has_bit
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.
Parameters:
(u32 read/write) timeout_ns
Watchdog timeout, in nanoseconds. This is initialized to 5,000,000 (5 milliseconds) at module load time. If more than this amount of time passes between
calls to the pet_watchdog() function, the watchdog will bite.
Functions:
pet_watchdog(): Calling this function resets the watchdog timer (postponing the
watchdog biting until timeout_ns nanoseconds later).

Raw Mode
If the "enable_raw" config keyword is specified, some extra debugging pins are made
available in HAL. The raw mode HAL pin names begin with "hm2_..raw".
With Raw mode enabled, a user may peek and poke the firmware from HAL, and may
dump the internal state of the hostmot2 driver to the syslog.
Pins:
(u32 in) read_address
The bottom 16 bits of this is used as the address to read from.
(u32 out) read_data
Each time the hm2_read() function is called, this pin is updated with the value at
.read_address.
(u32 in) write_address
The bottom 16 bits of this is used as the address to write to.
(u32 in) write_data
This is the value to write to .write_address.

184

2008-05-13

LinuxCNC Documentation

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

(bit in) write_strobe
Each time the hm2_write() function is called, this pin is examined. If it is True,
then value in .write_data is written to the address in .write_address, and
.write_strobe is set back to False.
(bit in/out) dump_state
This pin is normally False. If it gets set to True the hostmot2 driver will write its
representation of the board’s internal state to the syslog, and set the pin back to
False.

Setting up Smart Serial devices
See man setsserial for the current way to set smart-serial eeprom parameters.

FUNCTIONS
hm2_..read
This reads the encoder counters, stepgen feedbacks, and GPIO input pins from
the FPGA.
hm2_..write
This updates the PWM duty cycles, stepgen rates, and GPIO outputs on the
FPGA. Any changes to configuration pins such as stepgen timing, GPIO inversions, etc, are also effected by this function.
hm2_..pet-watchdog
Pet the watchdog to keep it from biting us for a while.
hm2_..read_gpio
Read the GPIO input pins. Note that the effect of this function is a subset of the
effect of the .read() function described above. Normally only .read() is used.
The only reason to call this function is if you want to do GPIO things in a fasterthan-servo thread. (This function is not available on the 7i43 due to limitations
of the EPP bus.)
hm2_..write_gpio
Write the GPIO control registers and output pins. Note that the effect of this
function is a subset of the effect of the .write() function described above. Normally only .write() is used. The only reason to call this function is if you want
to do GPIO things in a faster-than-servo thread. (This function is not available
on the 7i43 due to limitations of the EPP bus.)
hm2_..trigger-encoders
This function will only appear if the firmware contains a BiSS, Fanuc or SSI
encoder module and if the firmare does not contain a hm2dpll module (qv) or if
the modparam contains num_dplls=0. This function should be inserted first in
the thread so that the encoder data is ready when the main hm2_XiXX.NN.read
function runs. An error message will be printed if the encoder read is not finished in time. It may be possible to avoid this by increasing the data rate. If the
problem persists and if "stale" data is acceptable then the function may be placed
later in the thread, allowing a full servo cycle for the data to be transferred from
the devices. If available it is better to use the synchronous hm2dpll triggering
function.

SEE ALSO
hm2_7i43(9)
hm2_pci(9)
Mesa’s documentation for the Anything I/O boards, at

LinuxCNC Documentation

2008-05-13

185

HOSTMOT2(9)

HAL Component

HOSTMOT2(9)

LICENSE
GPL

186

2008-05-13

LinuxCNC Documentation

HYPOT(9)

HAL Component

HYPOT(9)

NAME
hypot − Three-input hypotenuse (Euclidean distance) calculator

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

FUNCTIONS
hypot.N (requires a floating-point thread)

PINS
hypot.N.in0 float in
hypot.N.in1 float in
hypot.N.in2 float in
hypot.N.out float out
out = sqrt(in0ˆ2 + in1ˆ2 + in2ˆ2)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

187

ILOWPASS(9)

HAL Component

ILOWPASS(9)

NAME
ilowpass − Low-pass filter with integer inputs and outputs

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

DESCRIPTION
While it may find other applications, this component was written to create smoother motion while jogging
with an MPG.
In a machine with high acceleration, a short jog can behave almost like a step function. By putting the
ilowpass component between the MPG encoder counts output and the axis jog-counts input, this can be
smoothed.
Choose scale conservatively so that during a single session there will never be more than about 2e9/scale
pulses seen on the MPG. Choose gain according to the smoothing level desired. Divide the axis.N.jogscale values by scale.

FUNCTIONS
ilowpass.N (requires a floating-point thread)
Update the output based on the input and parameters

PINS
ilowpass.N.in s32 in
ilowpass.N.out s32 out
out tracks in*scale through a low-pass filter of gain per period.

PARAMETERS
ilowpass.N.scale float rw (default: 1024)
A scale factor applied to the output value of the low-pass filter.
ilowpass.N.gain float rw (default: .5)
Together with the period, sets the rate at which the output changes. Useful range is between 0 and
1, with higher values causing the input value to be tracked more quickly. For instance, a setting of
0.9 causes the output value to go 90% of the way towards the input value in each period

AUTHOR
Jeff Epler

LICENSE
GPL

188

2014-12-18

LinuxCNC Documentation

INTEG(9)

HAL Component

INTEG(9)

NAME
integ − Integrator with gain pin and windup limits

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

FUNCTIONS
integ.N (requires a floating-point thread)

PINS
integ.N.in float in
integ.N.gain float in (default: 1.0)
integ.N.out float out
The discrete integral of ’gain * in’ since ’reset’ was deasserted
integ.N.reset bit in
When asserted, set out to 0
integ.N.max float in (default: 1e20)
integ.N.min float in (default: -1e20)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

189

INVERT(9)

HAL Component

INVERT(9)

NAME
invert − Compute the inverse of the input signal

SYNOPSIS
The output will be the mathematical inverse of the input, ie out = 1/in. The parameter deadband can be
used to control how close to 0 the denominator can be before the output is clamped to 0. deadband must
be at least 1e-8, and must be positive.

FUNCTIONS
invert.N (requires a floating-point thread)

PINS
invert.N.in float in
Analog input value
invert.N.out float out
Analog output value

PARAMETERS
invert.N.deadband float rw
The out will be zero if in is between -deadband and +deadband

LICENSE
GPL

190

2014-12-18

LinuxCNC Documentation

JOYHANDLE(9)

HAL Component

JOYHANDLE(9)

NAME
joyhandle − sets nonlinear joypad movements, deadbands and scales

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

DESCRIPTION
The component joyhandle uses the following formula for a non linear joypad movements:
y = (scale * (a*xˆpower + b*x)) + offset
The parameters a and b are adjusted in such a way, that the function starts at (deadband,offset) and ends at
(1,scale+offset).
Negative values will be treated point symetrically to origin. Values -deadband < x < +deadband will be set
to zero.
Values x > 1 and x < -1 will be skipped to ±(scale+offset). Invert transforms the function to a progressive
movement.
With power one can adjust the nonlinearity (default = 2). Default for deadband is 0.
Valid values are: power >= 1.0 (reasonable values are 1.x .. 4-5, take higher power-values for higher deadbands (>0.5), if you want to start with a nearly horizontal slope), 0 <= deadband < 0.99 (reasonable 0.1).
An additional offset component can be set in special cases (default = 0).
All values can be adjusted for each instance separately.

FUNCTIONS
joyhandle.N (requires a floating-point thread)

PINS
joyhandle.N.in float in
joyhandle.N.out float out

PARAMETERS
joyhandle.N.power float rw (default: 2.0)
joyhandle.N.deadband float rw (default: 0.)
joyhandle.N.scale float rw (default: 1.)
joyhandle.N.offset float rw (default: 0.)
joyhandle.N.inverse bit rw (default: 0)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

191

KINS(9)

HAL Component

KINS(9)

NAME
kins − kinematics definitions for LinuxCNC

SYNOPSIS
loadrt trivkins
loadrt rotatekins
loadrt tripodkins
loadrt genhexkins
loadrt maxkins
loadrt genserkins
loadrt pumakins
loadrt scarakins

DESCRIPTION
Rather than exporting HAL pins and functions, these components provide the forward and inverse kinematics definitions for LinuxCNC.
trivkins − Trivial Kinematics
There is a 1:1 correspondence between joints and axes. Most standard milling machines and lathes use the
trivial kinematics module.
rotatekins − Rotated Kinematics
The X and Y axes are rotated 45 degrees compared to the joints 0 and 1.
tripodkins − Tripod Kinematics
The joints represent the distance of the controlled point from three predefined locations (the motors), giving
three degrees of freedom in position (XYZ)
tripodkins.Bx
tripodkins.Cx
tripodkins.Cy
The location of the three motors is (0,0), (Bx,0), and (Cx,Cy)
genhexkins − Hexapod Kinematics
Gives six degrees of freedom in position and orientation (XYZABC). The location of the motors is defined
at compile time.
maxkins − 5-axis kinematics example
Kinematics for Chris Radek’s 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.
genserkins − generalized serial kinematics
Kinematics that can model a general serial-link manipulator with up to 6 angular joints.
The kinematics use Denavit-Hartenberg definition for the joint and links. The DH definitions are the ones
used by John J Craig in "Introduction to Robotics: Mechanics and Control" The parameters for the manipulator are defined by hal pins.
genserkins.A-N
genserkins.ALPHA-N
genserkins.D-N
Parameters describing the Nth joint’s geometry.
pumakins − kinematics for puma typed robots
Kinematics for a puma-style robot with 6 joints

192

2007-01-20

LinuxCNC Documentation

KINS(9)

HAL Component

KINS(9)

pumakins.A2
pumakins.A3
pumakins.D3
pumakins.D4
Describe the geometry of the robot
scarakins − kinematics for SCARA-type robots
scarakins.D1
Vertical distance from the ground plane to the center of the inner arm.
scarakins.D2
Horizontal distance between joint[0] axis and joint[1] axis, ie. the length of the inner arm.
scarakins.D3
Vertical distance from the center of the inner arm to the center of the outer arm. May be positive
or negative depending on the structure of the robot.
scarakins.D4
Horizontal distance between joint[1] axis and joint[2] axis, ie. the length of the outer arm.
scarakins.D5
Vertical distance from the end effector to the tooltip. Positive means the tooltip is lower than the
end effector, and is the normal case.
scarakins.D6
Horizontal distance from the centerline of the end effector (and the joints 2 and 3 axis) and the
tooltip. Zero means the tooltip is on the centerline. Non-zero values should be positive, if negative they introduce a 180 degree offset on the value of joint[3].

SEE ALSO
Kinematics section in the LinuxCNC documentation

LinuxCNC Documentation

2007-01-20

193

KNOB2FLOAT(9)

HAL Component

KNOB2FLOAT(9)

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

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

FUNCTIONS
knob2float.N (requires a floating-point thread)

PINS
knob2float.N.counts s32 in
Counts
knob2float.N.enable bit in
When TRUE, output is controlled by count, when FALSE, output is fixed
knob2float.N.scale float in
Amount of output change per count
knob2float.N.out float out
Output value

PARAMETERS
knob2float.N.max-out float rw (default: 1.0)
Maximum output value, further increases in count will be ignored
knob2float.N.min-out float rw (default: 0.0)
Minimum output value, further decreases in count will be ignored

LICENSE
GPL

194

2014-12-18

LinuxCNC Documentation

LATENCYBINS(9)

HAL Component

LATENCYBINS(9)

NAME
latencybins − comp utility for scripts/latencyhistogram

SYNOPSIS
Usage:
Read availablebins pin for the number of bins available.
Set the maxbinnumber pin for the number of +/- bins.
Ensure maxbinnumber <= availablebins
For maxbinnumber = N, the bins are numbered:
-N ... 0 ... + N bins
(the -0 bin is not populated)
(total effective bins = 2*maxbinnumber +1)
Set nsbinsize pin for the binsize (ns)
Iterate:
Set index pin to a bin number: 0 <= index <= maxbinnumber.
Read check pin and verify that check pin == index pin.
Read pbinvalue,nbinvalue,pextra,nextra pins.
(pbinvalue is count for bin = +index)
(nbinvalue is count for bin = -index)
(pextra is count for all bins > maxbinnumber)
(nextra is count for all bins < maxbinnumber)
If index is out of range ( index < 0 or index > maxbinnumber)
then pbinvalue = nbinvalue = -1.
The reset pin may be used to restart.
The latency pin outputs the instantaneous latency.
Maintainers note: hardcoded for MAXBINNUMBER==1000

FUNCTIONS
latencybins.N

PINS
latencybins.N.maxbinnumber s32 in (default: 1000)
latencybins.N.index s32 in
latencybins.N.reset bit in
latencybins.N.nsbinsize s32 in
latencybins.N.check s32 out
latencybins.N.latency s32 out
latencybins.N.pbinvalue s32 out
latencybins.N.nbinvalue s32 out
latencybins.N.pextra s32 out
latencybins.N.nextra s32 out
latencybins.N.availablebins s32 out (default: 1000)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

195

LCD(9)

HAL Component

LCD(9)

NAME
lcd − Stream HAL data to an LCD screen

SYNOPSIS
loadrt lcd fmt_strings=""Plain Text %4.4f\nAnd So on|Second Page, Next Inst""

FUNCTIONS
lcd (requires a floating-point thread). All LCD instances are updated by the
same function.

PINS
lcd.NN.out (u32) out
The output byte stream is sent via this pin. One character is sent every thread invocation. There in
no handshaking provided.
lcd.NN.page.PP.arg.NN (float/s32/u32/bit) in
The input pins have types matched to the format string specifiers.
lcd.NN.page_num (u32) in
Selects the page number. Multiple layouts may be defined, and this pin switches between them.
lcd.NN.contrast (float) in
Attempts to set the contrast of the LCD screen using the byte sequence ESC C and then a value
from 0x20 to 0xBF. (matching the Mesa 7i73). The value should be between 0 and 1.

PARAMETERS
lcd.NN.decimal-separator (u32) rw
Sets the decimal separator used for floating point numbers. The default value is 46 (0x2E) which
corresponds to ".". If a comma is required then set this parameter to 44 (0x2C).

DESCRIPTION
lcd takes format strings much like those used in C and many other languages in the printf and scanf functions and their variants.
The component was written specifically to support the Mesa 7i73 pendant controller, however it may be of
use streaming data to other character devices and, as the output format mimics the ADM3 terminal format,
it could be used to stream data to a serial device. Perhaps even a genuine ADM3. The strings contain a
mixture of text values which are displayed directly, "escaped" formatting codes and numerical format
descriptors. For a detailed description of formatting codes see: http://en.wikipedia.org/wiki/Printf
The component can be configured to display an unlimited number of differently-formatted pages, which
may be selected with a HAL pin.
Escaped codes
\n Inserts a clear-to-end, carriage return and line feed character. This will still linefeed and clear
even if an automatic wrap has occurred (lcd has no knowledge of the width of the lcd display.) To
print in the rightmost column it is necessary to allow the format to wrap and omit the \n code.
\t Inserts a tab (actually 4 spaces in the current version rather than a true tab.)
\NN inserts the character defined by the hexadecimal code NN.
\\ Inserts a literal \.
Numerical formats
lcd differs slightly from the standard printf conventions. One significant difference is that width

196

2012-09-17

LinuxCNC Documentation

LCD(9)

HAL Component

LCD(9)

limits are strictly enforced to prevent the LCD display wrapping and spoiling the layout. The field
width includes the sign character so that negative numbers will often have a smaller valid range
than positive. Numbers that do not fit in the specified width are displayed as a line of asterisks
(********).
Each format begins with a "%" symbol. (For a literal % use "%%"). Immediately after the % the
following modifiers may be used:
" " (space) Pad the number to the specified width with spaces. This is the default and is not strictly
necessary.
"0" Pad the number to the specified width with the numeral 0.
"+" Force display of a + symbol before positive numbers. This (like the - sign) will appear immediately to the left of the digits for a space-padded number and in the extreme left position for a
0-padded number.
"1234567890" A numerical entry (other than the leading 0 above) defines the total number of
characters to display including the decimal separator and the sign. Whilst this number can be as
many digits as required the maximum field width is 20 characters. The inherent precison of the
"double" data type means that more than 14 digits will tend to show errors in the least significant
digits. The integer data types will never fill more than 10 decimal digits.
Following the width specifier should be the decimal specifier. This can only be a full-stop character (.) as the comma (,) is used as the instance separator. Currently lcd does not access the locale
information to determine the correct separator and the decimal-separator parameter should be
used.
Following the decimal separator should be a number that determines how many places of decimals
to display. This entry is ignored in the case of integer formats.
All the above modifiers are optional, but to specify a decimal precision the decimal point must precede the precision. For example %.3f.
The default decimal precision is 4.
The numerical formats supported are:
%f %F (for example, %+09.3f) These create a floating-point type HAL pin. The example would
be displayed in a 9-character field, with 3 places of decimals, . as a decimal separator, padded to
the left with 0s and with a sign displayed for both positive and negative. Conversely a plain %f
would be 6 digits of decimal, variable format width, with a sign only shown for negative numbers.
both %f and %F create exactly the same format.
%i %d (For example %+ 4d) Creates a signed (s32) HAL pin. The example would display the
value at a fixed 4 characters, space padded, width including the + giving a range of +999 to -999.
%i and %d create identical output.
%u (for example %08u) Creates an unsigned (u32) HAL pin. The example would be a fixed 8
characters wide, padded with zeros.
%x, %X Creates an unsigned (u32) HAL pin and displays the value in Hexadecimal. Both %x
and %X display capital letters for digits ABCDEF. A width may be specified, though the u32 HAL
type is only 8 hex digits wide.

LinuxCNC Documentation

2012-09-17

197

LCD(9)

HAL Component

LCD(9)

%o Creates an unsigned (u32) pin and displays the value in Octal.
%c Creates a u32 HAL pin and displays the character corresponding to the value of the pin. Values less than 32 (space) are suppressed. A width specifier may be used, for example %20c might
be used to create a complete line of one character.
%b This specifier has no equivalent in printf. It creates a bit (boolean) type HAL pin. The b
should be followed by two characters and the display will show the first of these when the pin is
true, and the second when false. Note that the characters follow, not preceed the "b", unlike the
case with other formats. The characters may be "escaped" Hex values. For example "%b\FF " will
display a solid black block if true, and a space if false and "%b\7F\7E" would display right-arrow
for false and left-arrow for true. An unexpected value of ’E’ indicates a formatting error.
Pages The page separator is the "|" (pipe) character. (if the actual character is needed then \7C may
be used). A "Page" in this context refers to a separate format which may be displayed on the same
display.
Instances The instance separator is the comma. This creates a completely separate lcd instance,
for example to drive a second lcd display on the second 7i73. The use of comma to separate
instances is built in to the modparam reading code so not even escaped commas "\," can be used. A
comma may be displayed by using the \2C sequence.

AUTHOR
Andy Pugh

LICENSE
GPL

198

2012-09-17

LinuxCNC Documentation

LIMIT1(9)

HAL Component

LIMIT1(9)

NAME
limit1 − Limit the output signal to fall between min and max

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

FUNCTIONS
limit1.N (requires a floating-point thread)

PINS
limit1.N.in float in
limit1.N.out float out

PARAMETERS
limit1.N.min float rw (default: -1e20)
limit1.N.max float rw (default: 1e20)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

199

LIMIT2(9)

HAL Component

LIMIT2(9)

NAME
limit2 − Limit the output signal to fall between min and max and limit its slew rate to less than maxv per
second. When the signal is a position, this means that position and velocity are limited.

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

FUNCTIONS
limit2.N (requires a floating-point thread)

PINS
limit2.N.in float in
limit2.N.out float out
limit2.N.load bit in
When TRUE, immediately set out to in, ignoring maxv

PARAMETERS
limit2.N.min float rw (default: -1e20)
limit2.N.max float rw (default: 1e20)
limit2.N.maxv float rw (default: 1e20)

LICENSE
GPL

200

2014-12-18

LinuxCNC Documentation

LIMIT3(9)

HAL Component

LIMIT3(9)

NAME
limit3 − Limit the output signal to fall between min and max, limit its slew rate to less than maxv per second, and limit its second derivative to less than maxa per second squared. When the signal is a position,
this means that the position, velocity, and acceleration are limited.

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

FUNCTIONS
limit3.N (requires a floating-point thread)

PINS
limit3.N.in float in
limit3.N.out float out
limit3.N.load bit in
When TRUE, immediately set out to in, ignoring maxv and maxa
limit3.N.min float in (default: -1e20)
limit3.N.max float in (default: 1e20)
limit3.N.maxv float in (default: 1e20)
limit3.N.maxa float in (default: 1e20)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

201

LINCURVE(9)

HAL Component

LINCURVE(9)

NAME
lincurve − one-dimensional lookup table

SYNOPSIS
loadrt lincurve [count=N|names=name1[,name2...]] [personality=P,P,...]

DESCRIPTION
This component can be used to map any floating-point input to a floating-point output. Typical uses would
include linearisation of thermocouples, defining PID gains that vary with external factors or to substitute for
any mathematical function where absolute accuracy is not required.
The component can be thought of as a 2-dimensional graph of points in (x,y) space joined by straight lines.
The input value is located on the x axis, followed up until it touches the line, and the output of the component is set to the corresponding y-value.
The (x,y) points are defined by the x-val-NN and y-val-NN parameters which need to be set in the HAL file
using "setp" commands.
The maximum number if (x,y) points supported is 16.
For input values less than the x-val-00 breakpoint the y-val-00 is returned. For x greater than the largest xval-NN the yval corresponding to x-max is returned (ie, no extrapolation is performed.)
Sample usage: loadrt lincurve count=3 personality=4,4,4 for a set of three 4-element graphs.

FUNCTIONS
lincurve.N (requires a floating-point thread)

PINS
lincurve.N.in float in
The input value
lincurve.N.out float out
The output value
lincurve.N.out-io float io
The output value, compatible with PID gains

PARAMETERS
lincurve.N.x-val-MM float rw (MM=00..personality)
axis breakpoints
lincurve.N.y-val-MM float rw (MM=00..personality)
output values to be interpolated

AUTHOR
Andy Pugh

LICENSE
GPL

202

2014-12-18

LinuxCNC Documentation

LOGIC(9)

HAL Component

LOGIC(9)

NAME
logic − LinuxCNC HAL component providing configurable logic functions

SYNOPSIS
loadrt logic [count=N|names=name1[,name2...]] [personality=P,P,...]

DESCRIPTION
General ‘logic function’ component. Can perform ‘and’, ‘or’ and ‘xor’ of up to 16 inputs.
Determine the proper value for ‘personality’ by adding the inputs and outputs then convert to hex:
•

The number of input pins, usually from 2 to 16

•

256 (0x100) if the ‘and’ output is desired

•

512 (0x200) if the ‘or’ output is desired

•

1024 (0x400) if the ‘xor’ (exclusive or) output is desired

Outputs can be combined, for example 2 + 256 + 1024 = 1282 converted to hex would be 0x502 and would
have two inputs and have both ‘xor’ and ‘and’ outputs.

FUNCTIONS
logic.N

PINS
logic.N.in-MM bit in (MM=00..personality & 0xff)
logic.N.and bit out [if personality & 0x100]
logic.N.or bit out [if personality & 0x200]
logic.N.xor bit out [if personality & 0x400]

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

203

LOWPASS(9)

HAL Component

LOWPASS(9)

NAME
lowpass − Low-pass filter

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

FUNCTIONS
lowpass.N (requires a floating-point thread)

PINS
lowpass.N.in float in
lowpass.N.out float out
out += (in - out) * gain
lowpass.N.load bit in
When TRUE, copy in to out instead of applying the filter equation.

PARAMETERS
lowpass.N.gain float rw

NOTES
The effect of a specific gain value is dependent on the period of the function that lowpass.N is added to

LICENSE
GPL

204

2014-12-18

LinuxCNC Documentation

LUT5(9)

HAL Component

LUT5(9)

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

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

DESCRIPTION
lut5 constructs a logic function with up to 5 inputs using a look-up table. The value for function can be
determined by writing the truth table, and computing the sum of all the weights for which the output value
would be TRUE. The weights are hexadecimal not decimal so hexadecimal math must be used to sum the
weights. A wiki page has a calculator to assist in computing the proper value for function.
http://wiki.linuxcnc.org/cgi-bin/wiki.pl?Lut5
Note that LUT5 will generate any of the 4,294,967,296 logical functions of 5 inputs so AND, OR, NAND,
NOR, XOR and every other combinatorial function is possible.
Example Functions
A 5-input and function is TRUE only when all the inputs are true, so the correct value for function is
0x80000000.
A 2-input or function would be the sum of 0x2 + 0x4 + 0x8, so the correct value for function is 0xe.
A 5-input or function is TRUE whenever any of the inputs are true, so the correct value for function is
0xfffffffe. Because every weight except 0x1 is true the function is the sum of every line except the first one.
A 2-input xor function is TRUE whenever exactly one of the inputs is true, so the correct value for function
is 0x6. Only in-0 and in-1 should be connected to signals, because if any other bit is TRUE then the output
will be FALSE.

LinuxCNC Documentation

2014-12-18

205

LUT5(9)

HAL Component

Bit 4
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1

LUT5(9)

Weights for each line of truth table
Bit 3
Bit 2
Bit 1
Bit 0
Weight
0
0
0
0
0x1
0
0
0
1
0x2
0
0
1
0
0x4
0
0
1
1
0x8
0
1
0
0
0x10
0
1
0
1
0x20
0
1
1
0
0x40
0
1
1
1
0x80
1
0
0
0
0x100
1
0
0
1
0x200
1
0
1
0
0x400
1
0
1
1
0x800
1
1
0
0
0x1000
1
1
0
1
0x2000
1
1
1
0
0x4000
1
1
1
1
0x8000
0
0
0
0
0x10000
0
0
0
1
0x20000
0
0
1
0
0x40000
0
0
1
1
0x80000
0
1
0
0
0x100000
0
1
0
1
0x200000
0
1
1
0
0x400000
0
1
1
1
0x800000
1
0
0
0
0x1000000
1
0
0
1
0x2000000
1
0
1
0
0x4000000
1
0
1
1
0x8000000
1
1
0
0
0x10000000
1
1
0
1
0x20000000
1
1
1
0
0x40000000
1
1
1
1
0x80000000

FUNCTIONS
lut5.N

PINS
lut5.N.in-0 bit in
lut5.N.in-1 bit in
lut5.N.in-2 bit in
lut5.N.in-3 bit in
lut5.N.in-4 bit in
lut5.N.out bit out

PARAMETERS
lut5.N.function u32 rw

LICENSE
GPL

206

2014-12-18

LinuxCNC Documentation

MAJ3(9)

HAL Component

MAJ3(9)

NAME
maj3 − Compute the majority of 3 inputs

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

FUNCTIONS
maj3.N

PINS
maj3.N.in1 bit in
maj3.N.in2 bit in
maj3.N.in3 bit in
maj3.N.out bit out

PARAMETERS
maj3.N.invert bit rw

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

207

MATCH8(9)

HAL Component

MATCH8(9)

NAME
match8 − 8-bit binary match detector

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

FUNCTIONS
match8.N

PINS
match8.N.in bit in (default: TRUE)
cascade input - if false, output is false regardless of other inputs
match8.N.a0 bit in
match8.N.a1 bit in
match8.N.a2 bit in
match8.N.a3 bit in
match8.N.a4 bit in
match8.N.a5 bit in
match8.N.a6 bit in
match8.N.a7 bit in
match8.N.b0 bit in
match8.N.b1 bit in
match8.N.b2 bit in
match8.N.b3 bit in
match8.N.b4 bit in
match8.N.b5 bit in
match8.N.b6 bit in
match8.N.b7 bit in
match8.N.out bit out
true only if in is true and a[m] matches b[m] for m = 0 thru 7

LICENSE
GPL

208

2014-12-18

LinuxCNC Documentation

MATRIX_KB(9)

HAL Component

MATRIX_KB(9)

NAME
matrix_kb − Convert integers to HAL pins. Optionally scan a matrix of IO ports to create those integers.

SYNOPSIS
loadrt matrix_kb config=RxCs,RxCs... names=name1,name2...
Creates a component configured for R rows and N columns of matrix keyboard.
If the s option is specified then a set of output rows will be cyclically toggled, and a set of input columns
will be scanned.
The names parameter is optional, but if used then the HAL pins and functions will use the specified names
rather than the default ones. This can be useful for readbility and 2-pass HAL parsing.
There must be no spaces in the parameter lists.

DESCRIPTION
This component was written to convert matrix keyboard scancodes into HAL pins. However, it might also
find uses in converting integers from 0 to N into N HAL pins.
The component can work in two ways, and the HAL pins created vary according to mode.
In the default mode the component expects to be given a scan code from a separate driver but could be any
integer from any source. Most typically this will be the keypad scancode from a Mesa 7i73. The default
codes for keyup and keydown are based on the Mesa 7i73 specification with 0x40 indicating a keydown and
0x80 a keyup event.
If using the 7i73 it is important to match the keypad size jumpers with the HAL component. Valid configs
for the 7i73 are 4x8 and 8x8. Note that the component will only work properly with the version 12 (0xC)
7i73 firmware. The firmware version is visible on the component parameters in HAL.
In the optional scan-generation mode the matrix_kb.N.keycode pin changes to an output pin and a set of
output row pins and input column pins are created. These need to be connected to physical inputs and outputs to scan the matrix and return values to HAL. Note the negative-logic parameter described below, this
will need to be set on the most common forms of inputs which float high when unconnected.
In both modes a set of HAL output pins are created corresponding to each node of the matrix.

FUNCTIONS
matrix_kb.N
Perform all requested functions. Should be run in a slow thread for effective debouncing.

PINS
matrix_kb.N.col-CC-in bit in
The input pin corresponding to column C.
matrix_kb.N.key.rRcC bit out
The pin corresponding to the key at row R column C of the matrix.
matrix_kb.N.keycode unsigned in or out depending on mode.
This pin should be connected to the scancode generator if hardware such as a 7i73 is being used.
In this mode it is an input pin. In the internally-generated scanning mode this pin is an output, but
will not normally be connected. matrix_kb.N.row-RR-out bit out The row scan drive
pins.Should be connected to external hardware pins connected to the keypad.

LinuxCNC Documentation

2013-03-24

209

MATRIX_KB(9)

HAL Component

MATRIX_KB(9)

PARAMETERS
matrix_kb.N.key_rollover unsigned r/w (default 2)
With most matrix keyboards the scancodes are only unambiguous with 1 or 2 keys pressed. With
more keys pressed phantom keystrokes can appear. Some keyboards are optimised to reduce this
problem, and some have internal diodes so that any number of keys may be pressed simultaneously. Increase the value of this parameter if such a keyboard is connected, or if phantom keystrokes are more acceptable than only two keys being active at one time.
matrix_kb.N.negative-logic bit r/w (default 1) only in scan mode
When no keys are pressed a typical digital input will float high. The input will then be pulled low
by the keypad when the corresponding poll line is low. Set this parameter to 0 if the IO in use
requires one row at a time to be high, and a high input corresponds to a button press.

210

2013-03-24

LinuxCNC Documentation

MESA_7I65(9)

HAL Component

MESA_7I65(9)

NAME
mesa_7i65 − Support for the Mesa 7i65 Octuple Servo Card

SYNOPSIS
loadrt mesa_7i65

DESCRIPTION
The component takes parameters in the form of a comma-separated list of bspi (buffered SPI) instance
names, for example:
loadrt mesa_7i65 bspi_chans=hm2_5i23.0.bspi.0, hm2_5i23.0.bspi.1
The BSPI instances are printed to the dmesg buffer during the Hostmot2 setup sequence, one for each bspi
instance included in the bitfile loaded to each installed card during the Hostmot2 setup sequence. Type
"dmesg" at the terminal prompt to view the output.

PINS
mesa-7i65.N.analogue.M.out float in (M=0..7)
Analogue output values. The value will be limited to a -1.0 to +1.0 range
mesa-7i65.N.analogue.M.in float out (M=0..7)
Analogue outputs read by the 7i65 (in Volts)
mesa-7i65.N.digital.M.in bit out (M=0..3)
Miscellaneous Digital Inputs
mesa-7i65.N.enable.M.out bit in (M=0..7)
Amplifier-enable control pins
mesa-7i65.N.watchdog.has-bit bit out
Indicates the status of the 7i65 Watchdog (which is separate from the FPGA card watchdog

PARAMETERS
mesa-7i65.N.scale-M float rw (M=0..7) (default: 10)
Analogue output scale factor. For example if the scale is 7 then an input of 1.0 will give 7V on the
output terminals
mesa-7i65.N.is-bipolar-M bit rw (M=0..7) (default: 1)
Set this value to TRUE for a plus/minus "scale" output. Set to 0 for a 0-"scale" output

AUTHOR
Andy Pugh / Cliff Blackburn

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

211

MESA_UART(9)

HAL Component

MESA_UART(9)

NAME
mesa_uart − An example component demonstrating how to access the Hostmot2 UART

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

DESCRIPTION
This component creates 16 input and 16 output pins. It transmits {name}.N.tx-bytes on the selected UART
every thread cycle and reads up to 16 bytes each cycle out of the recieve FIFO and writes the values to the
associated output pins. {name}.rx-bytes indicates how many pins have been written to. (pins > rx-bytes
simply hold their previous value)
This module uses the names= mode of loadrt declaration to specifiy which UART instances to enable. A
check is included to ensure that the count= option is not used instead.
The component takes parameters in the form of a comma-separated list of UART instance names, for example:
loadrt mesa_uart names=hm2_5i23.0.uart.0,hm2_5i23.0.uart.7
Note that no spaces are allowed in the string unless it is delimited by double quotes.
The UART instance names are printed to the dmesg buffer during the Hostmot2 setup sequence, one for
each bspi instance included in the bitfile loaded to each installed card during the Hostmot2 setup sequence.
Type "dmesg" at the terminal prompt to view the output.
The component exports two functions, send and receive, which need to be added to a realtime thread.
The above example will output data on UART channels 0 and 7 and the pins will have the names of the
individual UARTS. (they need not be on the same card, or even the same bus).
Read the documents on "comp" for help with writing realtime components: http://www.linuxcnc.org/docview/html/hal/comp.html

FUNCTIONS
mesa-uart.N.send (requires a floating-point thread)
mesa-uart.N.receive (requires a floating-point thread)

PINS
mesa-uart.N.tx-data-MM u32 in (MM=00..15)
Data to be transmitted
mesa-uart.N.rx-data-MM u32 out (MM=00..15)
Data recieved
mesa-uart.N.tx-bytes s32 in
Number of bytes to transmit
mesa-uart.N.rx-bytes s32 out
Number of Bytes received

AUTHOR
Andy Pugh andy@bodgesoc.org

LICENSE
GPL

212

2014-12-18

LinuxCNC Documentation

MESSAGE(9)

HAL Component

MESSAGE(9)

NAME
message − Display a message

SYNOPSIS
loadrt message [count=N|names=name1[,name2...]] [messages=N]
messages
The messages to display. These should be listed, comma-delimited, inside a single set of
quotes. See the "Description" section for an example. If there are more messages than
"count" or "names" then the excess will be ignored. If there are fewer messages than "count"
or "names" then an error will be raised and the component will not load.

DESCRIPTION
Allows HAL pins to trigger a message. Example hal commands:
loadrt message names=oillow,oilpressure,inverterfail messages="Slideway oil low,No oil pressure,Spindle
inverter fault"
addf oillow servo-thread
addf oilpressure servo-thread
addf inverterfail servo-thread
setp oillow.edge 0 #this pin should be active low
net no-oil classicladder.0.out-21 oillow.trigger
net no-pressure classicladder.0.out-22 oilpressure.trigger
net no-inverter classicladder.0.out-23 inverterfail.trigger
When any pin goes active, the corresponding message will be displayed.

FUNCTIONS
message.N
Display a message

PINS
message.N.trigger bit in (default: FALSE)
signal that triggers the message
message.N.force bit in (default: FALSE)
A FALSE->TRUE transition forces the message to be displayed again if the trigger is active

PARAMETERS
message.N.edge bit rw (default: TRUE)
Selects the desired edge: TRUE means falling, FALSE means rising

LICENSE
GPL v2

LinuxCNC Documentation

2014-12-18

213

MINMAX(9)

HAL Component

MINMAX(9)

NAME
minmax − Track the minimum and maximum values of the input to the outputs

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

FUNCTIONS
minmax.N (requires a floating-point thread)

PINS
minmax.N.in float in
minmax.N.reset bit in
When reset is asserted, ’in’ is copied to the outputs
minmax.N.max float out
minmax.N.min float out

LICENSE
GPL

214

2014-12-18

LinuxCNC Documentation

MOTION(9)

HAL Component

MOTION(9)

NAME
motion − accepts NML motion commands, interacts with HAL in realtime

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

DESCRIPTION
By default, the base thread does not support floating point. Software stepping, software encoder counting,
and software pwm do not use floating point. base_thread_fp can be used to enable floating point in the
base thread (for example for brushless DC motor control).
These pins and parameters are created by the realtime motmod module. This module provides a HAL interface for LinuxCNC’s motion planner. Basically motmod takes in a list of waypoints and generates a nice
blended and constraint-limited stream of joint positions to be fed to the motor drives.
Optionally the number of Digital I/O is set with num_dio. The number of Analog I/O is set with num_aio.
The default is 4 each.
Pin names starting with "axis" are actually joint values, but the pins and parameters are still called "axis.N".
They are read and updated by the motion-controller function.

PINS
axis.N.amp-enable-out OUT BIT
TRUE if the amplifier for this joint should be enabled
axis.N.amp-fault-in IN BIT
Should be driven TRUE if an external fault is detected with the amplifier for this joint
axis.N.home-sw-in IN BIT
Should be driven TRUE if the home switch for this joint is closed
axis.N.homing OUT BIT
TRUE if the joint is currently homing
axis.N.index-enable IO BIT
Should be attached to the index-enable pin of the joint’s encoder to enable homing to index pulse
axis.N.is-unlocked IN BIT
If the axis is a locked rotary the unlocked sensor should be connected to this pin
axis.N.jog-counts IN S32
Connect to the "counts" pin of an external encoder to use a physical jog wheel.
axis.N.jog-enable IN BIT
When TRUE (and in manual mode), any change to "jog-counts" will result in motion. When false,
"jog-counts" is ignored.

LinuxCNC Documentation

2007-08-25

215

MOTION(9)

HAL Component

MOTION(9)

axis.N.jog-scale IN FLOAT
Sets the distance moved for each count on "jog-counts", in machine units.
axis.N.jog-vel-mode IN BIT
When FALSE (the default), the jogwheel operates in position mode. The axis will move exactly
jog-scale units for each count, regardless of how long that might take. When TRUE, the wheel
operates in velocity mode - motion stops when the wheel stops, even if that means the commanded
motion is not completed.
axis.N.joint-pos-cmd OUT FLOAT
The joint (as opposed to motor) commanded position. There may be several offsets between the
joint and motor coordinates: backlash compensation, screw error compensation, and home offsets.
axis.N.joint-pos-fb OUT FLOAT
The joint feedback position. This value is computed from the actual motor position minus joint
offsets. Useful for machine visualization.
axis.N.motor-pos-cmd OUT FLOAT
The commanded position for this joint.
axis.N.motor-pos-fb IN FLOAT
The actual position for this joint.
axis.N.neg-lim-sw-in IN BIT
Should be driven TRUE if the negative limit switch for this joint is tripped.
axis.N.pos-lim-sw-in IN BIT
Should be driven TRUE if the positive limit switch for this joint is tripped.
axis.N.unlock OUT BIT
TRUE if the axis is a locked rotary and a move is commanded.
motion.adaptive-feed IN FLOAT
When adaptive feed is enabled with M52 P1, the commanded velocity is multiplied by this value.
This effect is multiplicative with the NML-level feed override value and motion.feed-hold.
motion.analog-in-NN IN FLOAT
These pins are used by M66 Enn wait-for-input mode.
motion.analog-out-NN OUT FLOAT
These pins are used by M67-68.
motion.coord-error OUT BIT
TRUE when motion has encountered an error, such as exceeding a soft limit
motion.coord-mode OUT BIT
TRUE when motion is in "coordinated mode", as opposed to "teleop mode"

216

2007-08-25

LinuxCNC Documentation

MOTION(9)

HAL Component

MOTION(9)

motion.current-vel OUT FLOAT
Current cartesian velocity
motion.digital-in-NN IN BIT
These pins are used by M66 Pnn wait-for-input mode.
motion.digital-out-NN OUT BIT
These pins are controlled by the M62 through M65 words.
motion.distance-to-go OUT FLOAT
Distance remaining in the current move
motion.enable IN BIT
If this bit is driven FALSE, motion stops, the machine is placed in the "machine off" state, and a
message is displayed for the operator. For normal motion, drive this bit TRUE.
motion.feed-hold IN BIT
When Feed Stop Control is enabled with M53 P1, and this bit is TRUE, the feed rate is set to 0.
motion.feed-inhibit IN BIT
When this bit is TRUE, the feed rate is set and held to 0. This will be delayed during spindle synch
moves till the end of the move.
motion.in-position OUT BIT
TRUE if the machine is in position (ie, not currently moving towards the commanded position).
motion.probe-input IN BIT
G38.x uses the value on this pin to determine when the probe has made contact. TRUE for probe
contact closed (touching), FALSE for probe contact open.
motion.program-line OUT S32
motion.requested-vel OUT FLOAT
The requested velocity with no adjustments for feed override
motion.spindle-at-speed IN BIT
Motion will pause until this pin is TRUE, under the following conditions: before the first feed
move after each spindle start or speed change; before the start of every chain of spindle-synchronized moves; and if in CSS mode, at every rapid->feed transition.
motion.spindle-brake OUT BIT
TRUE when the spindle brake should be applied
motion.spindle-forward OUT BIT
TRUE when the spindle should rotate forward
motion.spindle-index-enable I/O BIT
For correct operation of spindle synchronized moves, this signal must be hooked to the indexenable pin of the spindle encoder.

LinuxCNC Documentation

2007-08-25

217

MOTION(9)

HAL Component

MOTION(9)

motion.spindle-inhibit IN BIT
When TRUE, the spindle speed is set and held to 0.
motion.spindle-on OUT BIT
TRUE when spindle should rotate
motion.spindle-reverse OUT BIT
TRUE when the spindle should rotate backward
motion.spindle-revs IN FLOAT
For correct operation of spindle synchronized moves, this signal must be hooked to the position
pin of the spindle encoder.
motion.spindle-speed-in IN FLOAT
Actual spindle speed feedback in revolutions per second; used for G96 (constant surface speed)
and G95 (feed per revolution) modes.
motion.spindle-speed-out OUT FLOAT
Desired spindle speed in rotations per minute
motion.spindle-speed-out-abs OUT FLOAT
Desired spindle speed in rotations per minute, always positive regardless of spindle direction.
motion.spindle-speed-out-rps OUT float
Desired spindle speed in rotations per second
motion.spindle-speed-out-rps-abs OUT float
Desired spindle speed in rotations per second, always positive regardless of spindle direction.
motion.spindle-orient-angle OUT FLOAT
Desired spindle orientation for M19. Value of the M19 R word parameter plus the value of the
[RS274NGC]ORIENT_OFFSET ini parameter.
motion.spindle-orient-mode OUT BIT
Desired spindle rotation mode. Reflects M19 P parameter word.
motion.spindle-orient OUT BIT
Indicates start of spindle orient cycle. Set by M19. Cleared by any of M3,M4,M5. If spindle-orient-fault is not zero during spindle-orient true, the M19 command fails with an error message.
motion.spindle-is-oriented IN BIT
Acknowledge pin for spindle-orient. Completes orient cycle. If spindle-orient was true when spindle-is-oriented was asserted, the spindle-orient pin is cleared and the spindle-locked pin is
asserted. Also, the spindle-brake pin is asserted.
motion.spindle-orient-fault IN S32
Fault code input for orient cycle. Any value other than zero will cause the orient cycle to abort.

218

2007-08-25

LinuxCNC Documentation

MOTION(9)

HAL Component

MOTION(9)

motion.spindle-locked OUT BIT
Spindle orient complete pin. Cleared by any of M3,M4,M5.
motion.teleop-mode OUT bit
motion.tooloffset.x OUT FLOAT
motion.tooloffset.y OUT FLOAT
motion.tooloffset.z OUT FLOAT
motion.tooloffset.a OUT FLOAT
motion.tooloffset.b OUT FLOAT
motion.tooloffset.c OUT FLOAT
motion.tooloffset.u OUT FLOAT
motion.tooloffset.v OUT FLOAT
motion.tooloffset.w OUT FLOAT
Current tool offset in all 9 axes.

DEBUGGING PINS
Many of the pins below serve as debugging aids, and are subject to change or removal at any time.
axis.N.active OUT BIT
TRUE when this joint is active
axis.N.backlash-corr OUT FLOAT
Backlash or screw compensation raw value
axis.N.backlash-filt OUT FLOAT
Backlash or screw compensation filtered value (respecting motion limits)
axis.N.backlash-vel OUT FLOAT
Backlash or screw compensation velocity
axis.N.coarse-pos-cmd OUT FLOAT
axis.N.error OUT BIT
TRUE when this joint has encountered an error, such as a limit switch closing
axis.N.f-error OUT FLOAT
The actual following error

LinuxCNC Documentation

2007-08-25

219

MOTION(9)

HAL Component

MOTION(9)

axis.N.f-error-lim OUT FLOAT
The following error limit
axis.N.f-errored OUT BIT
TRUE when this joint has exceeded the following error limit
axis.N.faulted OUT BIT
axis.N.free-pos-cmd OUT FLOAT
The "free planner" commanded position for this joint.
axis.N.free-tp-enable OUT BIT
TRUE when the "free planner" is enabled for this joint
axis.N.free-vel-lim OUT FLOAT
The velocity limit for the free planner
axis.N.homed OUT BIT
TRUE if the joint has been homed
axis.N.in-position OUT BIT
TRUE if the joint is using the "free planner" and has come to a stop
axis.N.joint-vel-cmd OUT FLOAT
The joint’s commanded velocity
axis.N.kb-jog-active OUT BIT

axis.N.neg-hard-limit OUT BIT
The negative hard limit for the joint
axis.N.pos-hard-limit OUT BIT
The positive hard limit for the joint
axis.N.wheel-jog-active OUT BIT
motion.motion-enabled OUT BIT
motion.motion-type OUT S32
These values are from src/emc/nml_intf/motion_types.h
1: Traverse
2: Linear feed
3: Arc feed
4: Tool change
5: Probing

220

2007-08-25

LinuxCNC Documentation

MOTION(9)

HAL Component

MOTION(9)

6: Rotary axis indexing
motion.on-soft-limit OUT BIT
motion.program-line OUT S32

motion.teleop-mode OUT BIT
TRUE when motion is in "teleop mode", as opposed to "coordinated mode"

PARAMETERS
Many of the parameters serve as debugging aids, and are subject to change or removal at any time.
motion-command-handler.time
motion-command-handler.tmax
motion-controller.time
motion-controller.tmax
Show information about the execution time of these HAL functions in CPU cycles
motion.debug-*
These values are used for debugging purposes.
motion.servo.last-period
The number of CPU cycles between invocations of the servo thread. Typically, this number
divided by the CPU speed gives the time in seconds, and can be used to determine whether the
realtime motion controller is meeting its timing constraints
motion.servo.overruns
By noting large differences between successive values of motion.servo.last-period, the motion controller can determine that there has probably been a failure to meet its timing constraints. Each
time such a failure is detected, this value is incremented.

FUNCTIONS
Generally, these functions are both added to the servo-thread in the order shown.
motion-command-handler
Processes motion commands coming from user space
motion-controller
Runs the LinuxCNC motion controller

BUGS
This manual page is horribly incomplete.

LinuxCNC Documentation

2007-08-25

221

MOTION(9)

HAL Component

MOTION(9)

SEE ALSO
iocontrol(1)

222

2007-08-25

LinuxCNC Documentation

MULT2(9)

HAL Component

MULT2(9)

NAME
mult2 − Product of two inputs

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

FUNCTIONS
mult2.N (requires a floating-point thread)

PINS
mult2.N.in0 float in
mult2.N.in1 float in
mult2.N.out float out
out = in0 * in1

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

223

MULTICLICK(9)

HAL Component

MULTICLICK(9)

NAME
multiclick − Single-, double-, triple-, and quadruple-click detector

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

DESCRIPTION
A click is defined as a rising edge on the ’in’ pin, followed by the ’in’ pin being True for at most ’maxhold-ns’ nanoseconds, followed by a falling edge.
A double-click is defined as two clicks, separated by at most ’max-space-ns’ nanoseconds with the ’in’ pin
in the False state.
I bet you can guess the definition of triple- and quadruple-click.
You probably want to run the input signal through a debounce component before feeding it to the multiclick
detector, if the input is at all noisy.
The ’*-click’ pins go high as soon as the input detects the correct number of clicks.
The ’*-click-only’ pins go high a short while after the click, after the click separator space timeout has
expired to show that no further click is coming. This is useful for triggering halui MDI commands.

FUNCTIONS
multiclick.N
Detect single-, double-, triple-, and quadruple-clicks

PINS
multiclick.N.in bit in
The input line, this is where we look for clicks.
multiclick.N.single-click bit out
Goes high briefly when a single-click is detected on the ’in’ pin.
multiclick.N.single-click-only bit out
Goes high briefly when a single-click is detected on the ’in’ pin and no second click followed it.
multiclick.N.double-click bit out
Goes high briefly when a double-click is detected on the ’in’ pin.
multiclick.N.double-click-only bit out
Goes high briefly when a double-click is detected on the ’in’ pin and no third click followed it.
multiclick.N.triple-click bit out
Goes high briefly when a triple-click is detected on the ’in’ pin.
multiclick.N.triple-click-only bit out
Goes high briefly when a triple-click is detected on the ’in’ pin and no fourth click followed it.
multiclick.N.quadruple-click bit out
Goes high briefly when a quadruple-click is detected on the ’in’ pin.
multiclick.N.quadruple-click-only bit out
Goes high briefly when a quadruple-click is detected on the ’in’ pin and no fifth click followed it.
multiclick.N.state s32 out

PARAMETERS
multiclick.N.invert-input bit rw (default: FALSE)
If FALSE (the default), clicks start with rising edges. If TRUE, clicks start with falling edges.

224

2014-12-18

LinuxCNC Documentation

MULTICLICK(9)

HAL Component

MULTICLICK(9)

multiclick.N.max-hold-ns u32 rw (default: 250000000)
If the input is held down longer than this, it’s not part of a multi-click. (Default 250,000,000 ns,
250 ms.)
multiclick.N.max-space-ns u32 rw (default: 250000000)
If the input is released longer than this, it’s not part of a multi-click. (Default 250,000,000 ns, 250
ms.)
multiclick.N.output-hold-ns u32 rw (default: 100000000)
Positive pulses on the output pins last this long. (Default 100,000,000 ns, 100 ms.)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

225

MULTISWITCH(9)

HAL Component

MULTISWITCH(9)

NAME
multiswitch − This component toggles between a specified number of output bits

SYNOPSIS
loadrt multiswitch personality=P [cfg=N]
cfg

cfg should be a comma-separated list of sizes for example cfg=2,4,6 would create 3 instances
of 2, 4 and 6 bits respectively.
Ignore the "personality" parameter, that is auto-generated

FUNCTIONS
multiswitch.N (requires a floating-point thread)

PINS
multiswitch.N.up bit in (default: false)
Receives signal to toggle up
multiswitch.N.down bit in (default: false)
Receives signal to toggle down
multiswitch.N.bit-MM bit out (MM=00..personality) (default: false)
Output bits

PARAMETERS
multiswitch.N.top-position u32 rw
Number of positions
multiswitch.N.position s32 rw
Current state (may be set in the HAL)

AUTHOR
ArcEye schooner30@tiscali.co.uk / Andy Pugh andy@bodgesoc.org

LICENSE
GPL

226

2014-12-18

LinuxCNC Documentation

MUX16(9)

HAL Component

MUX16(9)

NAME
mux16 − Select from one of sixteen input values

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

FUNCTIONS
mux16.N (requires a floating-point thread)

PINS
mux16.N.use-graycode bit in
This signifies the input will use Gray code instead of binary. Gray code is a good choice when
using physical switches because for each increment only one select input changes at a time.
mux16.N.suppress-no-input bit in
This suppresses changing the output if all select lines are false. This stops unwanted jumps in output between transitions of input. but make in00 unavaliable.
mux16.N.debounce-time float in
sets debouce time in seconds. eg. .10 = a tenth of a second input must be stable this long before
outputs changes. This helps to ignore ’noisy’ switches.
mux16.N.selM bit in (M=0..3)
Together, these determine which inN value is copied to out.
mux16.N.out-f float out
mux16.N.out-s s32 out
Follows the value of one of the inN values according to the four sel values and whether use-graycode is active. The s32 value will be trunuated and limited to the max and min values of signed
values.
sel3=FALSE, sel2=FALSE, sel1=FALSE, sel0=FALSE
out follows in0
sel3=FALSE, sel2=FALSE, sel1=FALSE, sel0=TRUE
out follows in1
etc.
mux16.N.inMM float in (MM=00..15)
array of selectable outputs

PARAMETERS
mux16.N.elapsed float r
Current value of the internal debounce timer
for debugging.
mux16.N.selected s32 r
Current value of the internal selection variable after conversion
for debugging

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

227

MUX2(9)

HAL Component

MUX2(9)

NAME
mux2 − Select from one of two input values

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

FUNCTIONS
mux2.N (requires a floating-point thread)

PINS
mux2.N.sel bit in
mux2.N.out float out
Follows the value of in0 if sel is FALSE, or in1 if sel is TRUE
mux2.N.in1 float in
mux2.N.in0 float in

LICENSE
GPL

228

2014-12-18

LinuxCNC Documentation

MUX4(9)

HAL Component

MUX4(9)

NAME
mux4 − Select from one of four input values

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

FUNCTIONS
mux4.N (requires a floating-point thread)

PINS
mux4.N.sel0 bit in
mux4.N.sel1 bit in
Together, these determine which inN value is copied to out.
mux4.N.out float out
Follows the value of one of the inN values according to the two sel values
sel1=FALSE, sel0=FALSE
out follows in0
sel1=FALSE, sel0=TRUE
out follows in1
sel1=TRUE, sel0=FALSE
out follows in2
sel1=TRUE, sel0=TRUE
out follows in3
mux4.N.in0 float in
mux4.N.in1 float in
mux4.N.in2 float in
mux4.N.in3 float in

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

229

MUX8(9)

HAL Component

MUX8(9)

NAME
mux8 − Select from one of eight input values

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

FUNCTIONS
mux8.N (requires a floating-point thread)

PINS
mux8.N.sel0 bit in
mux8.N.sel1 bit in
mux8.N.sel2 bit in
Together, these determine which inN value is copied to out.
mux8.N.out float out
Follows the value of one of the inN values according to the three sel values
sel2=FALSE, sel1=FALSE, sel0=FALSE
out follows in0
sel2=FALSE, sel1=FALSE, sel0=TRUE
out follows in1
sel2=FALSE, sel1=TRUE, sel0=FALSE
out follows in2
sel2=FALSE, sel1=TRUE, sel0=TRUE
out follows in3
sel2=TRUE, sel1=FALSE, sel0=FALSE
out follows in4
sel2=TRUE, sel1=FALSE, sel0=TRUE
out follows in5
sel2=TRUE, sel1=TRUE, sel0=FALSE
out follows in6
sel2=TRUE, sel1=TRUE, sel0=TRUE
out follows in7
mux8.N.in0 float in
mux8.N.in1 float in
mux8.N.in2 float in
mux8.N.in3 float in
mux8.N.in4 float in
mux8.N.in5 float in
mux8.N.in6 float in
mux8.N.in7 float in

LICENSE
GPL

230

2014-12-18

LinuxCNC Documentation

MUX_GENERIC(9)

HAL Component

MUX_GENERIC(9)

NAME
mux_generic − choose one from several input values

SYNOPSIS
loadrt mux_generic config="bb8,fu12...."

FUNCTIONS
mux-gen.NN Depending on the data types can run in either a floating
point or non-floating point thread.

PINS
mux-gen.NN.suppress-no-input bit in
This suppresses changing the output if all select lines are false. This stops unwanted jumps in output between transitions of input. but makes in00 unavaliable.
mux-gen.NN.debounce-us unsigned in
sets debouce time in microseconds. eg. 100000 = a tenth of a second. The selection inputs must
be stable this long before the output changes. This helps to ignore ’noisy’ switches.
mux-gen.NN.sel-bitMMM bit in (M=0..N)
mux-gen.NN.sel-intMMM unsigned in
Together, these determine which inN value is copied to output. The bit pins are interpreted as
binary bits, and the result is simply added on to the integer pin input. It is expected that eoither one
or the other would normally be used. Hower, the possibility exists to use a higher-order bit to
"shift" the values set by the integer pin. The sel-bit pins are only created when the size of the
mux_gen component is an integer power of two. This component (unlike mux16) does not offer
the option of decoding gray-code, however the same effect can be achieved by arranging the order
of the input values to suit.
mux-gen.NN.out-[bit/float/s32/u32] variable-type out
Follows the value of one of the inN values according to the selection bits and/or the selection number. Values will be converted/truncated according to standard C rules. This means, for example
that a float input greater than 2147483647 will give an S32 output of -2147483648.
mux-gen.NN.in-[bit/float/s32/u32]-MM variable-type in
The possible output values that are selected by the selection pins.

PARAMETERS
mux-gen.N.elapsed float r
Current value of the internal debounce timer for debugging.
mux-gen.N.selected s32 r
Current value of the internal selection variable after conversion for debugging. Possibly useful for
setting up gray-code switches.

DESCRIPTION
This component is a more general version of the other multiplexing components. It allows the creation of
arbitrary-size multiplexers (up to 1024 entries) and also supports differing data types on the input and output pins. The configuration string is a comma-separated list of code-letters and numbers, such as
"bb4,fu12" This would create a 4-element bit-to-bit mux and a 12-element float-to-unsigned mux. The code
letters are b = bit, f = float, s = signed integer, u = unsigned integer. The first letter code is the input type,
the second is the output type. The codes are not case-sensitive. The order of the letters is significant but the
position in the string is not. Do not insert any spaces in the config string. Any non-zero float value will be

LinuxCNC Documentation

2013-05-27

231

MUX_GENERIC(9)

HAL Component

MUX_GENERIC(9)

converted to a "true" output in bit form. Be wary that float datatypes can be very, very, close to zero and not
actually be equal to zero.
Each mux has its own HAL function and must be added to a thread separately. If neither input nor output is
of type float then the function is base-thread (non floating-point) safe. Any mux_generic with a floating
point input or output can only be added to a floating-point thread.

LICENSE
GPL

AUTHOR
Andy Pugh

232

2013-05-27

LinuxCNC Documentation

NEAR(9)

HAL Component

NEAR(9)

NAME
near − Determine whether two values are roughly equal.

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

FUNCTIONS
near.N (requires a floating-point thread)

PINS
near.N.in1 float in
near.N.in2 float in
near.N.out bit out
out is true if in1 and in2 are within a factor of scale (i.e., for in1 positive, in1/scale <= in2 <=
in1*scale), OR if their absolute difference is no greater than difference (i.e., |in1-in2| <= difference). out is false otherwise.

PARAMETERS
near.N.scale float rw (default: 1)
near.N.difference float rw (default: 0)

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

233

NOT(9)

HAL Component

NOT(9)

NAME
not − Inverter

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

FUNCTIONS
not.N

PINS
not.N.in bit in
not.N.out bit out

LICENSE
GPL

234

2014-12-18

LinuxCNC Documentation

OFFSET(9)

HAL Component

OFFSET(9)

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

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

FUNCTIONS
offset.N.update-output (requires a floating-point thread)
Updated the output value by adding the offset to the input
offset.N.update-feedback (requires a floating-point thread)
Update the feedback value by subtracting the offset from the feedback

PINS
offset.N.offset float in
The offset value
offset.N.in float in
The input value
offset.N.out float out
The output value
offset.N.fb-in float in
The feedback input value
offset.N.fb-out float out
The feedback output value

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

235

ONESHOT(9)

HAL Component

ONESHOT(9)

NAME
oneshot − one-shot pulse generator

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

DESCRIPTION
creates a variable-length output pulse when the input changes state. This function needs to run in a thread
which supports floating point (typically the servo thread). This means that the pulse length has to be a multiple of that thread period, typically 1mS. For a similar function that can run in the base thread, and which
offers higher resolution, see "edge".

FUNCTIONS
oneshot.N (requires a floating-point thread)
Produce output pulses from input edges

PINS
oneshot.N.in bit in
Trigger input
oneshot.N.out bit out
Active high pulse
oneshot.N.out-not bit out
Active low pulse
oneshot.N.width float in (default: 0)
Pulse width in seconds
oneshot.N.time-left float out
Time left in current output pulse

PARAMETERS
oneshot.N.retriggerable bit rw (default: TRUE)
Allow additional edges to extend pulse
oneshot.N.rising bit rw (default: TRUE)
Trigger on rising edge
oneshot.N.falling bit rw (default: FALSE)
Trigger on falling edge

LICENSE
GPL

236

2014-12-18

LinuxCNC Documentation

OPTO_AC5(9)

HAL Component

OPTO_AC5(9)

NAME
opto_ac5 − Realtime driver for opto22 PCI-AC5 cards

SYNOPSIS
loadrt opto_ac5 [portconfig0=0xN] [portconfig1=0xN]

DESCRIPTION
These pins and parameters are created by the realtime opto_ac5 module. The portconfig0 and portconfig1
variables are used to configure the two ports of each card. The first 24 bits of a 32 bit number represent the
24 i/o points of each port. The lowest (rightmost) bit would be HAL pin 0 which is header connector pin
47. Then next bit to the left would be HAL pin 1, header connector pin 45 and so on, untill bit 24 would be
HAL pin 23 , header connector pin 1. "1" bits represent output points. So channel 0..11 as inputs and
12..23 as outputs would be represented by (in binary) 111111111111000000000000 which is 0xfff000 in
hexadecimal. That is the number you would use Eg. loadrt opto_ac5 portconfig0=0xfff000
If no portconfig variable is specified the default configuration is 12 inputs then 12 outputs.
Up to 4 boards are supported. Boards are numbered starting at 0.
Portnumber can be 0 or 1. Port 0 is closes to the card bracket.

PINS
opto_ac5.[BOARDNUMBER].port[PORTNUMBER].in-[PINNUMBER] OUT bit
opto_ac5.[BOARDNUMBER].port[PORTNUMBER].in-[PINNUMBER]-not OUT bit
Connect a hal bit signal to this pin to read an i/o point from the card. The PINNUMBER represents the position in the relay rack. Eg. PINNUMBER 0 is position 0 in a opto22 relay rack and
would be pin 47 on the 50 pin header connector. The -not pin is inverted so that LOW gives TRUE
and HIGH gives FALSE.
opto_ac5.[BOARDNUMBER].port[PORTNUMBER].out-[PINNUMBER] IN bit
Connect a hal bit signal to this pin to write to an i/o point of the card. The PINNUMBER represents the position in the relay rack.Eg. PINNUMBER 23 is position 23 in a opto22 relay rack and
would be pin 1 on the 50 pin header connector.
opto_ac5.[BOARDNUMBER].led[NUMBER] OUT bit
Turns one of the on board LEDS on/off. LEDS are numbered 0 to 3.

PARAMETERS
opto_ac5.[BOARDNUMBER].port[PORTNUMBER].out-[PINNUMBER]-invert W bit
When TRUE, invert the meaning of the corresponding -out pin so that TRUE gives LOW and
FALSE gives HIGH.

FUNCTIONS
opto_ac5.0.digital-read
Add this to a thread to read all the input points.
opto_ac5.0.digital-write
Add this to a thread to write all the output points and LEDS.

BUGS
All boards are loaded with the same port configurations as the first board.

LinuxCNC Documentation

2008-08-04

237

OPTO_AC5(9)

HAL Component

OPTO_AC5(9)

SEE ALSO
http://wiki.linuxcnc.org/cgi-bin/wiki.pl?OptoPciAc5

238

2008-08-04

LinuxCNC Documentation

OR2(9)

HAL Component

OR2(9)

NAME
or2 − Two-input OR gate

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

FUNCTIONS
or2.N

PINS
or2.N.in0 bit in
or2.N.in1 bit in
or2.N.out bit out
out is computed from the value of in0 and in1 according to the following rule:
in0=FALSE in1=FALSE
out=FALSE
Otherwise,
out=TRUE

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

239

ORIENT(9)

HAL Component

ORIENT(9)

NAME
orient − Provide a PID command input for orientation mode based on current spindle position, target angle
and orient mode

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

DESCRIPTION
This component is designed to support a spindle orientation PID loop by providing a command value, and
fit with the motion spindle-orient support pins to support the M19 code.
The spindle is assumed to have stopped in an arbitrary position. The spindle encoder position is linked to
the position pin. The current value of the position pin is sampled on a positive edge on the enable pin,
and command is computed and set as follows: floor(number of full spindle revolutions in the position sampled on positive edge) plus angle/360 (the fractional revolution) +1/-1/0 depending on mode.
The mode pin is interpreted as follows:
0: the spindle rotates in the direction with the lesser angle, which may be clockwise or counterclockwise.
1: the spindle rotates always rotates clockwise to the new angle.
2: the spindle rotates always rotates counterclockwise to the new angle.

HAL USAGE
On motion.spindle-orient disconnect the spindle control and connect to the orient-pid loop:
loadrt orient names=orient
loadrt pid names=orient-pid
net orient-angle motion.spindle-orient-angle orient.angle
net orient-mode motion.spindle-orient-mode orient.mode
net orient-enable motion.spindle-orient
orient.enable orient-pid.enable
net spindle-pos ...encoder..position orient.position orient-pid.feedback
net orient-command orient.command orient-pid.command

FUNCTIONS
orient.N (requires a floating-point thread)
Update command based on enable, position, mode and angle.

PINS
orient.N.enable bit in
enable angular output for orientation mode
orient.N.mode s32 in
0: rotate - shortest move; 1: always rotate clockwise; 2: always rotate counterclockwise
orient.N.position float in
spindle position input, unit 1 rev
orient.N.angle float in
orient target position in degrees, 0 <= angle < 360
orient.N.command float out
target spindle position, input to PID command

240

2014-12-18

LinuxCNC Documentation

ORIENT(9)

HAL Component

ORIENT(9)

orient.N.poserr float out
in degrees - aid for PID tuning

AUTHOR
Michael Haberler

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

241

PCL720(9)

HAL Component

PCL720(9)

NAME
pcl720 − Driver for the Advantech PCL 720 card.

SYNOPSIS
loadrt pcl720 [ioaddr=N]
ioaddr Base address of card. Separate each card base address with a comma but no space to load
more than one card. eg loadrt pcl720 ioaddr=0x200,0x200. use 0xNNN to define addresses in
Hex

DESCRIPTION
This driver supports the Advantech PCL720 ISA card. It might work with the PCI version too, but this is
untested.
It creates hal pins corresonding to the digital inputs and outputs, but does not support the the counters/timers.

FUNCTIONS
pcl720.N.read
Reads each of the digital inputs and updates the HAL pins
pcl720.N.write
Writes the values of the output HAL pins to the digital IO
pcl720.N.reset
Waits for the length of time specified by the reset-time parameter and resets any pins for which
the reset parameter has been set. This can be used to allow step generators to make a step every
thread rather than every other thread. This function must be added to the thread after the "write"
function.
Do not use this function if you do not wish to reset any pins.
the stepgen step-space parameter should be set to 0 to make use of this function.

PINS
pcl720.N.pin-MM-out bit in (MM=00..31)
Output pins
pcl720.N.pin-MM-in bit out (MM=00..31)
Input pins
pcl720.N.pin-MM-in-not bit out (MM=00..31)
Inverted version of each input pin
pcl720.N.wait-clocks u32 out

PARAMETERS
pcl720.N.reset-time u32 rw (default: 5000)
The time in nanoseconds after the write function has run to reset the pins for which the "reset"
parameter is set.
pcl720.N.pin-MM-reset bit rw (MM=00..31)
specifies if the pin should be reset by the "reset" function
pcl720.N.pin-MM-out-invert bit rw (MM=00..31)
Set to true to invert the sense of the output pin

AUTHOR
Andy Pugh

LICENSE
GPL

242

2014-12-18

LinuxCNC Documentation

PID(9)

HAL Component

PID(9)

NAME
pid − proportional/integral/derivative controller

SYNOPSIS
loadrt pid [num_chan=num | names=name1[,name2...]] [debug=dbg]

DESCRIPTION
pid is a classic Proportional/Integral/Derivative controller, used to control position or speed feedback loops
for servo motors and other closed-loop applications.
pid supports a maximum of sixteen controllers. The number that are actually loaded is set by the
num_chan argument when the module is loaded. Alternatively, specify names= and unique names separated by commas.
The num_chan= and names= specifiers are mutually exclusive. If neither num_chan= nor names= are
specified, the default value is three. If debug is set to 1 (the default is 0), some additional HAL parameters
will be exported, which might be useful for tuning, but are otherwise unnecessary.

FUNCTIONS
pid.N.do-pid-calcs (uses floating-point) Does the PID calculations for control loop N.

PINS
pid.N.command float in
The desired (commanded) value for the control loop.
pid.N.Pgain float in
Proportional gain. Results in a contribution to the output that is the error multiplied by Pgain.
pid.N.Igain float in
Integral gain. Results in a contribution to the output that is the integral of the error multiplied by
Igain. For example an error of 0.02 that lasted 10 seconds would result in an integrated error
(errorI) of 0.2, and if Igain is 20, the integral term would add 4.0 to the output.
pid.N.Dgain float in
Derivative gain. Results in a contribution to the output that is the rate of change (derivative) of the
error multiplied by Dgain. For example an error that changed from 0.02 to 0.03 over 0.2 seconds
would result in an error derivative (errorD) of of 0.05, and if Dgain is 5, the derivative term would
add 0.25 to the output.
pid.N.feedback float in
The actual (feedback) value, from some sensor such as an encoder.
pid.N.output float out
The output of the PID loop, which goes to some actuator such as a motor.
pid.N.command-deriv float in
The derivative of the desired (commanded) value for the control loop. If no signal is connected
then the derivative will be estimated numerically.
pid.N.feedback-deriv float in
The derivative of the actual (feedback) value for the control loop. If no signal is connected then
the derivative will be estimated numerically. When the feedback is from a quantized position

LinuxCNC Documentation

2007-01-16

243

PID(9)

HAL Component

PID(9)

source (e.g., encoder feedback position), behavior of the D term can be improved by using a better
velocity estimate here, such as the velocity output of encoder(9) or hostmot2(9).
pid.N.error-previous-target bit in
Use previous invocation’s target vs. current position for error calculation, like the motion controller expects. This may make torque-mode position loops and loops requiring a large I gain easier to tune, by eliminating velocity-dependent following error.
pid.N.error float out
The difference between command and feedback.
pid.N.enable bit in
When true, enables the PID calculations. When false, output is zero, and all internal integrators,
etc, are reset.
pid.N.index-enable bit in
On the falling edge of index-enable, pid does not update the internal command derivative estimate. On systems which use the encoder index pulse, this pin should be connected to the indexenable signal. When this is not done, and FF1 is nonzero, a step change in the input command
causes a single-cycle spike in the PID output. On systems which use exactly one of the -deriv
inputs, this affects the D term as well.
pid.N.bias float in
bias is a constant amount that is added to the output. In most cases it should be left at zero. However, it can sometimes be useful to compensate for offsets in servo amplifiers, or to balance the
weight of an object that moves vertically. bias is turned off when the PID loop is disabled, just like
all other components of the output. If a non-zero output is needed even when the PID loop is disabled, it should be added with an external HAL sum2 block.
pid.N.FF0 float in
Zero order feed-forward term. Produces a contribution to the output that is FF0 multiplied by the
commanded value. For position loops, it should usually be left at zero. For velocity loops, FF0
can compensate for friction or motor counter-EMF and may permit better tuning if used properly.
pid.N.FF1 float in
First order feed-forward term. Produces a contribution to the output that FF1 multiplied by the
derivative of the commanded value. For position loops, the contribution is proportional to speed,
and can be used to compensate for friction or motor CEMF. For velocity loops, it is proportional
to acceleration and can compensate for inertia. In both cases, it can result in better tuning if used
properly.
pid.N.FF2 float in
Second order feed-forward term. Produces a contribution to the output that is FF2 multiplied by
the second derivative of the commanded value. For position loops, the contribution is proportional
to acceleration, and can be used to compensate for inertia. For velocity loops, it should usually be
left at zero.
pid.N.deadband float in
Defines a range of "acceptable" error. If the absolute value of error is less than deadband, it will
be treated as if the error is zero. When using feedback devices such as encoders that are inherently
quantized, the deadband should be set slightly more than one-half count, to prevent the control
loop from hunting back and forth if the command is between two adjacent encoder values. When
the absolute value of the error is greater than the deadband, the deadband value is subtracted from
the error before performing the loop calculations, to prevent a step in the transfer function at the
edge of the deadband. (See BUGS.)
pid.N.maxoutput float in
Output limit. The absolute value of the output will not be permitted to exceed maxoutput, unless
maxoutput is zero. When the output is limited, the error integrator will hold instead of integrating, to prevent windup and overshoot.

244

2007-01-16

LinuxCNC Documentation

PID(9)

HAL Component

PID(9)

pid.N.maxerror float in
Limit on the internal error variable used for P, I, and D. Can be used to prevent high Pgain values
from generating large outputs under conditions when the error is large (for example, when the
command makes a step change). Not normally needed, but can be useful when tuning non-linear
systems.
pid.N.maxerrorD float in
Limit on the error derivative. The rate of change of error used by the Dgain term will be limited to
this value, unless the value is zero. Can be used to limit the effect of Dgain and prevent large output spikes due to steps on the command and/or feedback. Not normally needed.
pid.N.maxerrorI float in
Limit on error integrator. The error integrator used by the Igain term will be limited to this value,
unless it is zero. Can be used to prevent integrator windup and the resulting overshoot during/after
sustained errors. Not normally needed.
pid.N.maxcmdD float in
Limit on command derivative. The command derivative used by FF1 will be limited to this value,
unless the value is zero. Can be used to prevent FF1 from producing large output spikes if there is
a step change on the command. Not normally needed.
pid.N.maxcmdDD float in
Limit on command second derivative. The command second derivative used by FF2 will be limited to this value, unless the value is zero. Can be used to prevent FF2 from producing large output spikes if there is a step change on the command. Not normally needed.
pid.N.saturated bit out
When true, the current PID output is saturated. That is,
output = ± maxoutput.
pid.N.saturated-s float out
pid.N.saturated-count s32 out
When true, the output of PID was continually saturated for this many seconds (saturated-s) or
periods (saturated-count).

PARAMETERS
pid.N.errorI float ro (only if debug=1)
Integral of error. This is the value that is multiplied by Igain to produce the Integral term of the
output.
pid.N.errorD float ro (only if debug=1)
Derivative of error. This is the value that is multiplied by Dgain to produce the Derivative term of
the output.
pid.N.commandD float ro (only if debug=1)
Derivative of command. This is the value that is multiplied by FF1 to produce the first order feedforward term of the output.
pid.N.commandDD float ro (only if debug=1)
Second derivative of command. This is the value that is multiplied by FF2 to produce the second
order feed-forward term of the output.

BUGS
Some people would argue that deadband should be implemented such that error is treated as zero if it is
within the deadband, and be unmodified if it is outside the deadband. This was not done because it would
cause a step in the transfer function equal to the size of the deadband. People who prefer that behavior are
welcome to add a parameter that will change the behavior, or to write their own version of pid. However,
the default behavior should not be changed.
Negative gains may lead to unwanted behavior. It is possible in some situations that negative FF gains

LinuxCNC Documentation

2007-01-16

245

PID(9)

HAL Component

PID(9)

make sense, but in general all gains should be positive. If some output is in the wrong direction, negating
gains to fix it is a mistake; set the scaling correctly elsewhere instead.

246

2007-01-16

LinuxCNC Documentation

PLUTO_SERVO(9)

HAL Component

PLUTO_SERVO(9)

NAME
pluto_servo − Hardware driver and firmware for the Pluto-P parallel-port FPGA, for use with servo
machines.

SYNOPSIS
loadrt pluto_servo [ioaddr=N] [ioaddr_hi=N] [epp_wide=N] [watchdog=N] [test_encoder=N]
ioaddr [default: 0x378]
The base address of the parallel port.
ioaddr_hi [default: 0]
The secondary address of the parallel port, used to set EPP mode. 0 means to use ioaddr +
0x400. -1 means there is no secondary address. The secondary address is used to set the port
to EPP mode.
epp_wide [default: 1]
Set to zero to disable the "wide EPP mode". "Wide" mode allows a 16- and 32-bit EPP transfers, which can reduce the time spent in the read and write functions. However, this may not
work on all EPP parallel ports.
watchdog [default: 1]
Set to zero to disable the "hardware watchdog". "Watchdog" will tristate all outputs approximately 6ms after the last execution of pluto-servo.write, which adds some protection in the
case of LinuxCNC crashes.
test_encoder [default: 0]
Internally connect dout0..2 to QA0, QB0, QZ0 to test quadrature counting

DESCRIPTION
Pluto_servo is a LinuxCNC software driver and associated firmware that allow the Pluto-P board to be used
to control a servo-based CNC machine.
The driver has 4 PWM channels, 4 quadrature channels with index pulse, 18 digital outputs (8 shared with
PWM), and 20 digital inputs (12 shared with quadrature).
Encoders
The encoder pins and parameters conform to the ‘canonical encoder’ interface described in the HAL manual. It operates in ‘x4 mode’.
The sample rate of the encoder is 40MHz. The maximum number quadrature rate is 8191 counts per LinuxCNC servo cycle. For correct handling of the index pulse, the number of encoder counts per revolution
must be less than 8191.
PWM
The PWM pins and parameters conform to the ‘canonical analog output’ interface described in the HAL
manual. The output pins are ‘up/down’ or ‘pwm/dir’ pins as described in the documentation of the ‘pwmgen’ component.
Internally the PWM generator is based on a 12-bit, 40MHz counter, giving 4095 duty cycles from -100% to
+100% and a frequency of approximately 19.5kHz. In PDM mode, the duty periods are approximately
100ns long.
Digital I/O
The digital output pins conform to the ‘canonical digital output’ interface described in the HAL manual.
The digital input pins conform to the ‘canonical digital input’ interface described in the HAL manual.

LinuxCNC Documentation

2014-12-18

247

PLUTO_SERVO(9)

HAL Component

PLUTO_SERVO(9)

FUNCTIONS
pluto-servo.read (requires a floating-point thread)
Read all the inputs from the pluto-servo board
pluto-servo.write (requires a floating-point thread)
Write all the outputs on the pluto-servo board

PINS
pluto-servo.encoder.M.count s32 out (M=0..3)
pluto-servo.encoder.M.position float out (M=0..3)
pluto-servo.encoder.M.velocity float out (M=0..3)
pluto-servo.encoder.M.reset bit in (M=0..3)
pluto-servo.encoder.M.index-enable bit io (M=0..3)
encoder.M corresponds to the pins labeled QAM, QBM, and QZM on the pinout diagram
pluto-servo.pwm.M.value float in (M=0..3)
pluto-servo.pwm.M.enable bit in (M=0..3)
pwm.M corresponds to the pins labeled UPM and DNM on the pinout diagram
pluto-servo.dout.MM bit in (MM=00..19)
dout.0M corresponds to the pin labeled OUTM on the pinout diagram. Other pins are shared with
the PWM function, as follows:
Pin

Shared

Label

with

dout.10

UP0

dout.10

UP0

dout.12

UP1

dout.14

UP2

dout.18

UP3

dout.11

DOWN0

dout.13

DOWN1

dout.15

DOWN2

dout.19

DOWN3

pluto-servo.din.MM bit out (MM=00..19)
pluto-servo.din.MM-not bit out (MM=00..19)
For M=0 through 7, din.0M corresponds to the pin labeled INM on the pinout diagram. Other pins
are shared with the encoder function, as follows:

248

Shared

Label

with

din.8

QZ0

din.9

QZ1

din.10

QZ2

din.11

QZ3

din.12

QB0

din.13

QB1

din.14

QB2

din.15

QB3

din.16

QA0

2014-12-18

LinuxCNC Documentation

PLUTO_SERVO(9)

HAL Component

din.17

QA1

din.18

QA2

din.19

QA3

PLUTO_SERVO(9)

PARAMETERS
pluto-servo.encoder.M.scale float rw (M=0..3) (default: 1)
pluto-servo.encoder.z-polarity bit rw
Set to TRUE if the index pulse is active low, FALSE if it is active high. Affects all encoders.
pluto-servo.pwm.M.offset float rw (M=0..3)
pluto-servo.pwm.M.scale float rw (M=0..3) (default: 1)
pluto-servo.pwm.M.max-dc float rw (M=0..3) (default: 1)
pluto-servo.pwm.M.min-dc float rw (M=0..3) (default: 0)
pluto-servo.pwm.M.pwmdir bit rw (M=0..3) (default: 0)
Set to TRUE use PWM+direction mode. Set to FALSE to use Up/Down mode.
pluto-servo.pwm.is-pdm bit rw
Set to TRUE to use PDM (also called interleaved PWM) mode. Set to FALSE to use traditional
PWM mode. Affects all PWM outputs.
pluto-servo.dout.MM-invert bit rw (MM=00..19)
If TRUE, the output on the corresponding dout.MM is inverted.
pluto-servo.communication-error u32 rw
Incremented each time pluto-servo.read detects an error code in the EPP status register. While this
register is nonzero, new values are not being written to the Pluto-P board, and the status of digital
outputs and the PWM duty cycle of the PWM outputs will remain unchanged. If the watchdog is
enabled, it will activate soon after the communication error is detected. To continue after a communication error, set this parameter back to zero.
pluto-servo.debug-0 s32 rw
pluto-servo.debug-1 s32 rw
These parameters can display values which are useful to developers or for debugging the driver
and firmware. They are not useful for integrators or users.

SEE ALSO
The pluto_servo section in the HAL User Manual, which shows the location of each physical pin on the
pluto board.

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

249

PLUTO_STEP(9)

HAL Component

PLUTO_STEP(9)

NAME
pluto_step − Hardware driver and firmware for the Pluto-P parallel-port FPGA, for use with stepper
machines.

SYNOPSIS
loadrt pluto_step ioaddr=addr ioaddr_hi=addr epp_wide=[0|1]
ioaddr [default: 0x378]
The base address of the parallel port.
ioaddr_hi [default: 0]
The secondary address of the parallel port, used to set EPP mode. 0 means to use ioaddr +
0x400. -1 means there is no secondary address.
epp_wide [default: 1]
Set to zero to disable "wide EPP mode". "Wide" mode allows 16- and 32-bit EPP transfers,
which can reduce the time spent in the read and write functions. However, this mode may not
work on all EPP parallel ports.
watchdog [default: 1]
Set to zero to disable the "hardware watchdog". "Watchdog" will tristate all outputs approximately 6ms after the last execution of pluto-step.write, which adds some protection in the
case of LinuxCNC crashes.
speedrange [default: 0]
Selects one of four speed ranges:
0: Top speed 312.5kHz; minimum speed 610Hz
1: Top speed 156.25kHz; minimum speed 305Hz
2: Top speed 78.125kHz; minimum speed 153Hz
3: Top speed 39.06kHz; minimum speed 76Hz
Choosing the smallest maximum speed that is above the maximum for any one axis may give
improved step regularity at low step speeds.

DESCRIPTION
Pluto_step is a LinuxCNC software driver and associated firmware that allow the Pluto-P board to be used
to control a stepper-based CNC machine.
The driver has 4 step+direction channels, 14 dedicated digital outputs, and 16 dedicated digital inputs.
Step generators
The step generator takes a position input and output.
The step waveform includes step length/space and direction hold/setup time. Step length and direction setup/hold time is enforced in the FPGA. Step space is enforced by a velocity cap in the driver.
(all the following numbers are subject to change) In speedrange=0, the maximum step rate is 312.5kHz.
For position feedback to be accurate, the maximum step rate is 512 pulses per servo cycle (so a 1kHz servo
cycle does not impose any additional limitation). The maximum step rate may be lowered by the step
length and space parameters, which are rounded up to the nearest multiple of 1600ns.
In successive speedranges the maximum step rate is divided in half, as is the maximum steps per servo
cycle, and the minimum nonzero step rate.

250

2014-12-18

LinuxCNC Documentation

PLUTO_STEP(9)

HAL Component

PLUTO_STEP(9)

Digital I/O
The digital output pins conform to the ‘canonical digital output’ interface described in the HAL manual.
The digital input pins conform to the ‘canonical digital input’ interface described in the HAL manual.

FUNCTIONS
pluto-step.read (requires a floating-point thread)
Read all the inputs from the pluto-step board
pluto-step.write (requires a floating-point thread)
Write all the outputs on the pluto-step board

PINS
pluto-step.stepgen.M.position-cmd float in (M=0..3)
pluto-step.stepgen.M.velocity-fb float out (M=0..3)
pluto-step.stepgen.M.position-fb float out (M=0..3)
pluto-step.stepgen.M.counts s32 out (M=0..3)
pluto-step.stepgen.M.enable bit in (M=0..3)
pluto-step.stepgen.M.reset bit in (M=0..3)
When TRUE, reset position-fb to 0
pluto-step.dout.MM bit in (MM=00..13)
dout.MM corresponds to the pin labeled OUTM on the pinout diagram.
pluto-step.din.MM bit out (MM=00..15)
pluto-step.din.MM-not bit out (MM=00..15)
din.MM corresponds to the pin labeled INM on the pinout diagram.

PARAMETERS
pluto-step.stepgen.M.scale float rw (M=0..3) (default: 1.0)
pluto-step.stepgen.M.maxvel float rw (M=0..3) (default: 0)
pluto-step.stepgen.step-polarity bit rw
pluto-step.stepgen.steplen u32 rw
Step length in ns.
pluto-step.stepgen.stepspace u32 rw
Step space in ns
pluto-step.stepgen.dirtime u32 rw
Dir hold/setup in ns. Refer to the pdf documentation for a diagram of what these timings mean.
pluto-step.dout.MM-invert bit rw (MM=00..13)
If TRUE, the output on the corresponding dout.MM is inverted.
pluto-step.communication-error u32 rw
Incremented each time pluto-step.read detects an error code in the EPP status register. While this
register is nonzero, new values are not being written to the Pluto-P board, and the status of digital
outputs and the PWM duty cycle of the PWM outputs will remain unchanged. If the hardware
watchdog is enabled, it will activate shortly after the communication error is detected by LinuxCNC. To continue after a communication error, set this parameter back to zero.
pluto-step.debug-0 s32 rw
pluto-step.debug-1 s32 rw
pluto-step.debug-2 float rw (default: .5)
pluto-step.debug-3 float rw (default: 2.0)
Registers that hold debugging information of interest to developers

SEE ALSO
The pluto_step section in the HAL User Manual, which shows the location of each physical pin on the
pluto board.

LinuxCNC Documentation

2014-12-18

251

PLUTO_STEP(9)

HAL Component

PLUTO_STEP(9)

LICENSE
GPL

252

2014-12-18

LinuxCNC Documentation

PWMGEN(9)

HAL Component

PWMGEN(9)

NAME
pwmgen − software PWM/PDM generation

SYNOPSIS
loadrt pwmgen output_type=type0[,type1...]

DESCRIPTION
pwmgen is used to generate PWM (pulse width modulation) or PDM (pulse density modulation) signals.
The maximum PWM frequency and the resolution is quite limited compared to hardware-based approaches,
but in many cases software PWM can be very useful. If better performance is needed, a hardware PWM
generator is a better choice.
pwmgen supports a maximum of eight channels. The number of channels actually loaded depends on the
number of type values given. The value of each type determines the outputs for that channel.
type 0: single output
A single output pin, pwm, whose duty cycle is determined by the input value for positive inputs,
and which is off (or at min-dc) for negative inputs. Suitable for single ended circuits.
type 1: pwm/direction
Two output pins, pwm and dir. The duty cycle on pwm varies as a function of the input value.
dir is low for positive inputs and high for negative inputs.
type 2: up/down
Two output pins, up and down. For positive inputs, the PWM/PDM waveform appears on up,
while down is low. For negative inputs, the waveform appears on down, while up is low. Suitable
for driving the two sides of an H-bridge to generate a bipolar output.

FUNCTIONS
pwmgen.make-pulses (no floating-point)
Generates the actual PWM waveforms, using information computed by update. Must be called as
frequently as possible, to maximize the attainable PWM frequency and resolution, and minimize
jitter. Operates on all channels at once.
pwmgen.update (uses floating point)
Accepts an input value, performs scaling and limit checks, and converts it into a form usable by
make-pulses for PWM/PDM generation. Can (and should) be called less frequently than makepulses. Operates on all channels at once.

PINS
pwmgen.N.enable bit in
Enables PWM generator N - when false, all pwmgen.N output pins are low.
pwmgen.N.value float in
Commanded value. When value = 0.0, duty cycle is 0%, and when value = +/-scale, duty cycle is
+/- 100%. (Subject to min-dc and max-dc limitations.)
pwmgen.N.pwm bit out (output types 0 and 1 only)
PWM/PDM waveform.
pwmgen.N.dir bit out (output type 1 only)
Direction output: low for forward, high for reverse.
pwmgen.N.up bit out (output type 2 only)
PWM/PDM waveform for positive input values, low for negative inputs.
pwmgen.N.down bit out (output type 2 only)
PWM/PDM waveform for negative input values, low for positive inputs.

LinuxCNC Documentation

2007-01-16

253

PWMGEN(9)

HAL Component

PWMGEN(9)

PARAMETERS
pwmgen.N.curr-dc float ro
The current duty cycle, after all scaling and limits have been applied. Range is from -1.0 to +1.0.
pwmgen.N.max-dc float rw
The maximum duty cycle. A value of 1.0 corresponds to 100%. This can be useful when using
transistor drivers with bootstrapped power supplies, since the supply requires some low time to
recharge.
pwmgen.N.min-dc float rw
The minimum duty cycle. A value of 1.0 corresponds to 100%. Note that when the pwm generator is disabled, the outputs are constantly low, regardless of the setting of min-dc.
pwmgen.N.scale float rw
pwmgen.N.offset float rw
These parameters provide a scale and offset from the value pin to the actual duty cycle. The duty
cycle is calculated according to dc = (value/scale) + offset, with 1.0 meaning 100%.
pwmgen.N.pwm-freq float rw
PWM frequency in Hz. The upper limit is half of the frequency at which make-pulses is invoked,
and values above that limit will be changed to the limit. If dither-pwm is false, the value will be
changed to the nearest integer submultiple of the make-pulses frequency. A value of zero produces Pulse Density Modulation instead of Pulse Width Modulation.
pwmgen.N.dither-pwm bit rw
Because software-generated PWM uses a fairly slow timebase (several to many microseconds), it
has limited resolution. For example, if make-pulses is called at a 20KHz rate, and pwm-freq is
2KHz, there are only 10 possible duty cycles. If dither-pwm is false, the commanded duty cycle
will be rounded to the nearest of those values. Assuming value remains constant, the same output
will repeat every PWM cycle. If dither-pwm is true, the output duty cycle will be dithered
between the two closest values, so that the long-term average is closer to the desired level. ditherpwm has no effect if pwm-freq is zero (PDM mode), since PDM is an inherently dithered
process.

254

2007-01-16

LinuxCNC Documentation

SAMPLE_HOLD(9)

HAL Component

SAMPLE_HOLD(9)

NAME
sample_hold − Sample and Hold

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

FUNCTIONS
sample-hold.N

PINS
sample-hold.N.in s32 in
sample-hold.N.hold bit in
sample-hold.N.out s32 out

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

255

SAMPLER(9)

HAL User’s Manual

SAMPLER(9)

NAME
sampler − sample data from HAL in real time

SYNOPSIS
loadrt sampler depth=depth1[,depth2...] cfg=string1[,string2...]

DESCRIPTION
sampler and halsampler(1) are used together to sample HAL data in real time and store it in a file. sampler is a realtime HAL component that exports HAL pins and creates a FIFO in shared memory. It then
begins sampling data from the HAL and storing it to the FIFO. halsampler is a user space program that
copies data from the FIFO to stdout, where it can be redirected to a file or piped to some other program.

OPTIONS
depth=depth1[,depth2...]
sets the depth of the realtime->user FIFO that sampler creates to buffer the realtime data. Multiple values of depth (separated by commas) can be specified if you need more than one FIFO (for
example if you want to sample data from two different realtime threads).
cfg=string1[,string2...]
defines the set of HAL pins that sampler exports and later samples data from. One string must be
supplied for each FIFO, separated by commas. sampler exports one pin for each character in
string. Legal characters are:
F, f (float pin)
B, b (bit pin)
S, s (s32 pin)
U, u (u32 pin)

FUNCTIONS
sampler.N
One function is created per FIFO, numbered from zero.

PINS
sampler.N.pin.M input
Pin for the data that will wind up in column M of FIFO N (and in column M of the output file).
The pin type depends on the config string.
sampler.N.curr-depth s32 output
Current number of samples in the FIFO. When this reaches depth new data will begin overwriting
old data, and some samples will be lost.
sampler.N.full bit output
TRUE when the FIFO N is full, FALSE when there is room for another sample.
sampler.N.enable bit input
When TRUE, samples are captured and placed in FIFO N, when FALSE, no samples are acquired.
Defaults to TRUE.

PARAMETERS
sampler.N.overruns s32 read/write
The number of times that sampler has tried to write data to the HAL pins but found no room in
the FIFO. It increments whenever full is true, and can be reset by the setp command.

256

2006-11-18

LinuxCNC Documentation

SAMPLER(9)

HAL User’s Manual

SAMPLER(9)

sampler.N.sample-num s32 read/write
A number that identifies the sample. It is automatically incremented for each sample, and can be
reset using the setp command. The sample number can optionally be printed in the first column of
the output from halsampler, using the -t option. (see man 1 halsampler)

SEE ALSO
halsampler(1) streamer(9) halstreamer(1)

HISTORY
BUGS
AUTHOR
Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other members of the LinuxCNC development team.

REPORTING BUGS
Report bugs to jmkasunich AT users DOT sourceforge DOT net

LinuxCNC Documentation

2006-11-18

257

SCALE(9)

HAL Component

SCALE(9)

NAME
scale − LinuxCNC HAL component that applies a scale and offset to its input

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

FUNCTIONS
scale.N (requires a floating-point thread)

PINS
scale.N.in float in
scale.N.gain float in
scale.N.offset float in
scale.N.out float out
out = in * gain + offset

LICENSE
GPL

258

2014-12-18

LinuxCNC Documentation

SELECT8(9)

HAL Component

SELECT8(9)

NAME
select8 − 8-bit binary match detector

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

FUNCTIONS
select8.N

PINS
select8.N.sel s32 in
The number of the output to set TRUE. All other outputs well be set FALSE
select8.N.outM bit out (M=0..7)
Output bits. If enable is set and the sel input is between 0 and 7, then the corresponding output bit
will be set true

PARAMETERS
select8.N.enable bit rw (default: TRUE)
Set enable to FALSE to cause all outputs to be set FALSE

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

259

SERPORT(9)

HAL Component

SERPORT(9)

NAME
serport − Hardware driver for the digital I/O bits of the 8250 and 16550 serial port.

SYNOPSIS
loadrt serport io=addr[,addr...]
The pin numbers refer to the 9-pin serial pinout. Keep in mind that these ports generally use rs232 voltages, not 0/5V signals.
Specify the I/O address of the serial ports using the module parameter io=addr[,addr...]. These ports must
not be in use by the kernel. To free up the I/O ports after bootup, install setserial and execute a command
like:
sudo setserial /dev/ttyS0 uart none
but it is best to ensure that the serial port is never used or configured by the Linux kernel by setting a kernel
commandline parameter or not loading the serial kernel module if it is a modularized driver.

FUNCTIONS
serport.N.read
serport.N.write

PINS
serport.N.pin-1-in bit out
Also called DCD (data carrier detect); pin 8 on the 25-pin serial pinout
serport.N.pin-6-in bit out
Also called DSR (data set ready); pin 6 on the 25-pin serial pinout
serport.N.pin-8-in bit out
Also called CTS (clear to send); pin 5 on the 25-pin serial pinout
serport.N.pin-9-in bit out
Also called RI (ring indicator); pin 22 on the 25-pin serial pinout
serport.N.pin-1-in-not bit out
Inverted version of pin-1-in
serport.N.pin-6-in-not bit out
Inverted version of pin-6-in
serport.N.pin-8-in-not bit out
Inverted version of pin-8-in
serport.N.pin-9-in-not bit out
Inverted version of pin-9-in
serport.N.pin-3-out bit in
Also called TX (transmit data); pin 2 on the 25-pin serial pinout
serport.N.pin-4-out bit in
Also called DTR (data terminal ready); pin 20 on the 25-pin serial pinout
serport.N.pin-7-out bit in
Also called RTS (request to send); pin 4 on the 25-pin serial pinout

PARAMETERS
serport.N.pin-3-out-invert bit rw
serport.N.pin-4-out-invert bit rw
serport.N.pin-7-out-invert bit rw

260

2014-12-18

LinuxCNC Documentation

SERPORT(9)

HAL Component

SERPORT(9)

serport.N.ioaddr u32 r

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

261

SETSERIAL(9)

HAL Component

SETSERIAL(9)

NAME
setsserial - a utility for setting Smart Serial NVRAM parameters.

SYNOPSIS
loadrt setsserial cmd="set hm2_8i20.001f.nvmaxcurrent 750"

FUNCTIONS
None

PINS
None

USAGE
loadrt setsserial cmd="{command} {parameter/device} {value/filename}"
Commands available are set and flash.
This utility should be used under halcmd, without LinuxCNC running or any realtime threads running.
A typical command sequence would be:
halrun
loadrt hostmot2 use_serial_numbers=1
loadrt hm2_pci config="firmware=hm2/5i23/svss8_8.bit"
show param
loadrt setsserial cmd="set hm2_8i20.001f.nvmaxcurrent 750"
exit
This example uses the option to have the hal pins and parameters labelled by the serial number of the
remote. This is not necessary but can reduce the scope for confusion. (The serial number is normally on a
sticker on the device.)
The next line loads the hm2_pci driver in the normal way. The hm2_7i43 driver should work equally well,
as should any future 7i80 driver. If the card has already been strted up and a firmware has been loaded,
then the config string may be omitted.
"show param" is optional, but provides a handy list of all the devices and parameters. It also shows the current values of the parameters which can be useful for determining scaling. u32 pin values are always shown
in hex, but new values can be entered in decimal or hex. Use the Ox123ABC format to enter a hex value.
The next line invokes setsserial. This is run in a slightly strange way in order to have kernel-level access to
a live Hostmot2 config. It is basically a HAL module that always fails to load. This may lead to error messages being printed to the halcmd prompt. These can often be ignored. All the real feedback is via the
dmesg command. It is suggested to have a second terminal window open to run dmesg after each command.
On exiting there will typically be a further error message related to the driver failing to unload setsserial.
This can be ignored.
The parameter changes will not show up until the drivers are reloaded. //TODO// Add a "get" command to
avoid this problem.
Flashing Firmware To flash new firmware to an FPGA card such as the 5i25 or 5i20 the "mesaflash" utility should be used. Setsserial is only useful for changing/updating the firmare on smart-serial remote such
as the 8i20. The firmware should be placed somewhere in the /lib/firmware/hm2 tree, where the Linux
firmware loading macros can find it.
The flashing routine operates in a realtime thread, and can only send prompts to the user through the kernel

262

2012-10-28

LinuxCNC Documentation

SETSERIAL(9)

HAL Component

SETSERIAL(9)

log (dmesg). It is most convenient to open two terminal windows, one for command entry and one to monitor progress.
In the first terminal enter
tail -f /var/log/kern.log
This terminal will now display status information.
The second window will be used to enter the commands. It is important that LinuxCNC and/or HAL are not
already loaded when the process is started. To flash new firmware it is necessary to move a jumper on the
smart-serial remote drive and to switch smart-serial communication to a slower baudrate.
A typical command sequence is then
halrun
loadrt hostmot2 sserial_baudrate=115200
loadrt hm2_pci config="firmware=hm2/5i23/svss8_8.bit"
loadrt setsserial cmd="flash hm2_5i23.0.8i20.0.1 hm2/8i20/8i20T.BIN"
exit
It is not necessary (or useful) to specify a config string in a system using the 5i25 or 6i25 cards.
Note that it is necessary to exit halrun and unload the realtime environment before flashing the next card
(exit)
The correct sserial channel name to use can be seen in the dmesg output in the feedback terminal after the
loadrt hm2_pci step of the sequence.

LICENSE
GPL

LinuxCNC Documentation

2012-10-28

263

SIGGEN(9)

HAL Component

SIGGEN(9)

NAME
siggen − signal generator

SYNOPSIS
loadrt siggen [num_chan=num | names=name1[,name2...]]

DESCRIPTION
siggen is a signal generator that can be used for testing and other applications that need simple waveforms.
It produces sine, cosine, triangle, sawtooth, and square waves of variable frequency, amplitude, and offset,
which can be used as inputs to other HAL components.
siggen supports a maximum of sixteen channels. The number of channels actually loaded is set by the
num_chan argument when the module is loaded. Alternatively, specify names= and unique names separated by commas.
The num_chan= and names= specifiers are mutually exclusive. If neither num_chan= nor names= are
specified, the default value is one.

NAMING
The names for pins, parameters, and functions are prefixed as:
siggen.N. for N=0,1,...,num-1 when using num_chan=num
nameN. for nameN=name1,name2,... when using names=name1,name2,...
The siggen.N. format is shown in the following descriptions.

FUNCTIONS
siggen.N.update (uses floating-point)
Updates output pins for signal generator N. Each time it is called it calculates a new sample. It
should be called many times faster than the desired signal frequency, to avoid distortion and aliasing.

PINS
siggen.N.frequency float in
The output frequency for signal generator N, in Hertz. The default value is 1.0 Hertz.
siggen.N.amplitude float in
The output amplitude for signal generator N. If offset is zero, the outputs will swing from -amplitude to +amplitude. The default value is 1.00.
siggen.N.offset float in
The output offset for signal generator N. This value is added directly to the output signal. The
default value is zero.
siggen.N.clock bit out
The clock output. Bit type clock signal output at the commanded frequency.
siggen.N.square float out
The square wave output. Positive while triangle and cosine are ramping upwards, and while sine
is negative.
siggen.N.sine float out
The sine output. Lags cosine by 90 degrees.

264

2007-01-16

LinuxCNC Documentation

SIGGEN(9)

HAL Component

SIGGEN(9)

siggen.N.cosine float out
The cosine output. Leads sine by 90 degrees.
siggen.N.triangle float out
The triangle wave output. Ramps up while square is positive, and down while square is negative.
Reaches its positive and negative peaks at the same time as cosine.
siggen.N.sawtooth float out
The sawtooth output. Ramps upwards to its positive peak, then instantly drops to its negative peak
and starts ramping again. The drop occurs when triangle and cosine are at their positive peaks,
and coincides with the falling edge of square.

PARAMETERS
None

LinuxCNC Documentation

2007-01-16

265

SIM_ENCODER(9)

HAL Component

SIM_ENCODER(9)

NAME
sim_encoder − simulated quadrature encoder

SYNOPSIS
loadrt sim_encoder [num_chan=num | names=name1[,name2...]]

DESCRIPTION
sim_encoder can generate quadrature signals as if from an encoder. It also generates an index pulse once
per revolution. It is mostly used for testing and simulation, to replace hardware that may not be available.
It has a limited maximum frequency, as do all software based pulse generators.
sim_encoder supports a maximum of eight channels. The number of channels actually loaded is set by the
num_chan= argument when the module is loaded. Alternatively, specify names= and unique names separated by commas.
The num_chan= and names= specifiers are mutually exclusive. If neither num_chan= nor names= are
specified, the default value is one.

FUNCTIONS
sim-encoder.make-pulses (no floating-point)
Generates the actual quadrature and index pulses. Must be called as frequently as possible, to
maximize the count rate and minimize jitter. Operates on all channels at once.
sim-encoder.update-speed (uses floating-point)
Reads the speed command and other parameters and converts the data into a form that can be used
by make-pulses. Changes take effect only when update-speed runs. Can (and should) be called
less frequently than make-pulses. Operates on all channels at once.

NAMING
The names for pins and parameters are prefixed as:
sim-encoder.N. for N=0,1,...,num-1 when using num_chan=num
nameN. for nameN=name1,name2,... when using names=name1,name2,...
The sim-encoder.N. format is shown in the following descriptions.

PINS
sim-encoder.N.phase-A bit out
One of the quadrature outputs.
sim-encoder.N.phase-B bit out
The other quadrature output.
sim-encoder.N.phase-Z bit out
The index pulse.
sim-encoder.N.speed float in
The desired speed of the encoder, in user units per per second. This is divided by scale, and the
result is used as the encoder speed in revolutions per second.

PARAMETERS

266

2007-01-16

LinuxCNC Documentation

SIM_ENCODER(9)

HAL Component

SIM_ENCODER(9)

sim-encoder.N.ppr u32 rw
The pulses per revolution of the simulated encoder. Note that this is pulses, not counts, per revolution. Each pulse or cycle from the encoder results in four counts, because every edge is counted.
Default value is 100 ppr, or 400 counts per revolution.
sim-encoder.N.scale float rw
Scale factor for the speed input. The speed value is divided by scale to get the actual encoder
speed in revolutions per second. For example, if scale is set to 60, then speed is in revolutions per
minute (RPM) instead of revolutions per second. The default value is 1.00.

LinuxCNC Documentation

2007-01-16

267

SIM_SPINDLE(9)

HAL Component

SIM_SPINDLE(9)

NAME
sim_spindle − Simulated spindle with index pulse

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

FUNCTIONS
sim-spindle.N (requires a floating-point thread)

PINS
sim-spindle.N.velocity-cmd float in
Commanded speed
sim-spindle.N.position-fb float out
Feedback position, in revolutions
sim-spindle.N.index-enable bit io
Reset position-fb to 0 at the next full rotation

PARAMETERS
sim-spindle.N.scale float rw (default: 1.0)
factor applied to velocity-cmd.
The result of ’velocity-cmd * scale’ be in revolutions per second. For example, if velocity-cmd is
in revolutions/minute, scale should be set to 1/60 or 0.016666667.

LICENSE
GPL

268

2014-12-18

LinuxCNC Documentation

SPHEREPROBE(9)

HAL Component

SPHEREPROBE(9)

NAME
sphereprobe − Probe a pretend hemisphere

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

FUNCTIONS
sphereprobe.N
update probe-out based on inputs

PINS
sphereprobe.N.px s32 in
sphereprobe.N.py s32 in
sphereprobe.N.pz s32 in
rawcounts position from software encoder
sphereprobe.N.cx s32 in
sphereprobe.N.cy s32 in
sphereprobe.N.cz s32 in
Center of sphere in counts
sphereprobe.N.r s32 in
Radius of hemisphere in counts
sphereprobe.N.probe-out bit out

AUTHOR
Jeff Epler

LICENSE
GPL

LinuxCNC Documentation

2014-12-18

269

SSERIAL(9)

HAL Component

SSERIAL(9)

NAME
hostmot2 - Smart Serial LinuxCNC HAL driver for the Mesa Electronics HostMot2 Smart-Serial remote
cards

SYNOPSIS
The Mesa Smart-Serial interface is a 2.5Mbs proprietary interface between the Mesa Anything-IO cards
and a range of subsidiary devices termed "smart-serial remotes". The remote cards perform a variety of
functions, but typically they combine various classes of IO. The remot cards are self-configuring, in that
they tell the main LinuxCNC Hostmot2 driver what their pin functions are and what they should be named.
Many sserial remotes offer different pinouts depending on the mode they are started up in. This is set using
the sserial_port_N= option in the hm2_pci modparam. See the hostmot2 manpage for further details.
It is likely that this documentation will be permanently out of date.
Each Anything-IO board can attach up to 8 sserial remotes to each header (either the 5-pin headers on the
5i20/5i22/5i23/7i43 or the 25-pin connectors on the 5i25, 6i25 and 7i80). The remotes are grouped into
"ports" of up to 8 "channels". Typically each header will be a single 8 channel port, but this is not necessarily always the case.

PORTS
In addition to the per-channel/device pins detailed below there are three per-port pins and three parameters.
Pins:
(bit, in) .sserial.port-N.run: Enables the specific Smart Serial module. Setting this pin low will disable all
boards on the port and puts the port in a pass-through mode where device parameter setting is possible.
This pin defaults to TRUE and can be left unconnected. However, toggling the pin low-to-high will reenable a faulted drive so the pin could usefully be connected to the iocontrol.0.user-enable-out pin.
(u32, ro) .run_state: Shows the state of the sserial communications state-machine. This pin will generally
show a value of 0x03 in normal operation, 0x07 in setup mode and 0x00 when the "run" pin is false.
(u32, ro) .error-count: Indicates the state of the Smart Serial error handler, see the parameters sections for
more details.
Parameters:
(u32 r/w) .fault-inc: Any over-run or handshaking error in the SmartSerial communications will increment
the .fault-count pin by the amount specified by this parameter. Default = 10.
(u32 r/w) .fault-dec: Every successful read/write cycle decrements the fault counter by this amount. Default
= 1.
(u32 r/w) .fault-lim: When the fault counter reaches this threshold the Smart Serial interface on the corresponding port will be stopped and an error printed in dmesg. Together these three pins allow for control
over the degree of fault- tolerance allowed in the interface. The default values mean that if more than one
transaction in ten fails, more than 20 times, then a hard error will be raised. If the increment were to be set
to zero then no error would ever be raised, and the system would carry on regardless. Conversely setting
decrement to zero, threshold to 1 and limit to 1 means that absolutely no errors will be tolerated. (This
structure is copied directly from vehicle ECU practice)

270

2008-05-13

LinuxCNC Documentation

SSERIAL(9)

HAL Component

SSERIAL(9)

DEVICES
The other pins and parameters created in HAL depend on the devices detected. The following list of Smart
Serial devices is by no means exhaustive.

8i20

The 8i20 is a 2.2kW three-phase drive for brushless DC motors and AC servo motors. 8i20 pins
and parameters have names like "hm2_..8i20...", for example "hm2_5i23.0.8i20.1.3.current" would set the phase current for the
drive connected to the fourth channel of the second sserial port of the first 5i23 board. Note that
the sserial ports do not necessarily correlate in layout or number to the physical ports on the card.
Pins:

(float in) angle
The rotor angle of the motor in fractions of a full phase revolution. An angle of 0.5 indicates that
the motor is half a turn / 180 degrees / π radians from the zero position. The zero position is taken
to be the position that the motor adopts under no load with a poitive voltage applied to the A (or
U) phase and both B and C (or V and W) connected to -V or 0V. A 6 pole motor will have 3 zero
positions per physical rotation. Note that the 8i20 drive automatically adds the phase lead/lag
angle, and that this pin should see the raw rotor angle. There is a HAL module (bldc) which handles the complexity of differing motor and drive types.
(float, in) current
The phase current command to the drive. This is scaled from -1 to +1 for forwards and reverse
maximum currents. The absolute value of the current is set by the max_current parameter.
(float, ro) voltage
The drive bus voltage in V. This will tend to show 25.6V when the drive is unpowered and the
drive will not operate below about 50V.
(float, ro) temp
The temperature of the driver in degrees C.
(u32, ro) comms
The communication status of the drive. See the manual for more details.
(bit, ro) status and fault.
The following fault/status bits are exported. For further details see the 8i20 manual. fault.U-current / fault.U-current-not fault.V-current / fault.V-current-not fault.W-current / fault.W-current-not
fault.bus-high / fault.bus-high-not fault.bus-overv / fault.bus-overv-not fault.bus-underv /
fault.bus-underv-not fault.framingr / fault.framingr-not fault.module / fault.module-not fault.noenable / fault.no-enable-not fault.overcurrent / fault.overcurrent-not fault.overrun / fault.overrunnot fault.overtemp / fault.overtemp-not fault.watchdog / fault.watchdog-not
status.brake-old / status.brake-old-not status.brake-on / status.brake-on-not status.bus-underv / status.bus-underv-not status.current-lim / status.current-lim-no status.ext-reset / status.ext-reset-not
status.no-enable / status.no-enable-not status.pid-on / status.pid-on-not status.sw-reset / status.swreset-not status.wd-reset / status.wd-reset-not
Parameters:
The following parameters are exported. See the pdf documentation downloadable from Mesa for
further details

LinuxCNC Documentation

2008-05-13

271

SSERIAL(9)

HAL Component

SSERIAL(9)

hm2_5i25.0.8i20.0.1.angle-maxlim
hm2_5i25.0.8i20.0.1.angle-minlim
hm2_5i25.0.8i20.0.1.angle-scalemax
hm2_5i25.0.8i20.0.1.current-maxlim
hm2_5i25.0.8i20.0.1.current-minlim
hm2_5i25.0.8i20.0.1.current-scalemax
hm2_5i25.0.8i20.0.1.nvbrakeoffv
hm2_5i25.0.8i20.0.1.nvbrakeonv
hm2_5i25.0.8i20.0.1.nvbusoverv
hm2_5i25.0.8i20.0.1.nvbusundervmax
hm2_5i25.0.8i20.0.1.nvbusundervmin
hm2_5i25.0.8i20.0.1.nvkdihi
hm2_5i25.0.8i20.0.1.nvkdil
hm2_5i25.0.8i20.0.1.nvkdilo
hm2_5i25.0.8i20.0.1.nvkdp
hm2_5i25.0.8i20.0.1.nvkqihi
hm2_5i25.0.8i20.0.1.nvkqil
hm2_5i25.0.8i20.0.1.nvkqilo
hm2_5i25.0.8i20.0.1.nvkqp
hm2_5i25.0.8i20.0.1.nvmaxcurrent
hm2_5i25.0.8i20.0.1.nvrembaudrate
hm2_5i25.0.8i20.0.1.swrevision
hm2_5i25.0.8i20.0.1.unitnumber
(float, rw) max_current
Sets the maximum drive current in Amps. The default value is the maximum current programmed
into the drive EEPROM. The value must be positive, and an error will be raised if a current in
excess of the drive maximum is requested.
(u32, ro) serial_number
The serial number of the connected drive. This is also shown on the label on the drive.

7i64

The 7i64 is a 24-input 24-output IO card. 7i64 pins and parameters have names like
"hm2_..7i64.
..",
for
example
hm2_5i23.0.7i64.1.3.output-01
Pins: (bit, in) 7i64.0.0.output-NN: Writing a 1 or TRUE to this pin will enable output driver NN.
Note that the outputs are drivers (switches) rather than voltage outputs. The LED adjacent to the
connector on the board shows the status. The output can be inverted by setting a parameter.
(bit, out) 7i64.0.0.input-NN: The value of input NN. Note that the inputs are isolated and both pins
of each input must be connected (typically to signal and the ground of the signal. This need not be
the ground of the board.)
(bit, out) 7i64.0.0.input-NN-not: An inverted copy of the corresponding input.
(float, out) 7i64.0.0.analog0 & 7i64.0.0.analog1: The two analogue inputs (0 to 3.3V) on the
board.
Parameters: (bit, rw) 7i64.0.0.output-NN-invert: Setting this parameter to 1 / TRUE will invert the
output value, such that writing 0 to .gpio.NN.out will enable the output and vice-versa.

272

2008-05-13

LinuxCNC Documentation

SSERIAL(9)

7i76

HAL Component

SSERIAL(9)

The 7i76 is not only a smart-serial device. It also serves as a breakout for a number of other Hostmot2 functions. There are connections for 5 step generators (for which see the main hostmot2
manpage). The stepgen pins are associated with the 5i25 (hm2_5i25.0.stepgen.00....) whereas the
smart-serial pins are associated with the 7i76 (hm2_5i25.0.7i76.0.0.output-00).
Pins:
(float out) .7i76.0.0.analogN (modes 1 and 2 only) Analogue input values.
(float out) .7i76.0.0.fieldvoltage (mode 2 only) Field voltage monitoring pin.
(bit in) .7i76.0.0.spindir: This pin provides a means to drive the spindle VFD direction terminals
on the 7i76 board.
(bit in) .7i76.0.0.spinena: This pin drives the spindle-enable terminals on the 7i76 board.
(float in) .7i76.0.0.spinout: This controls the analogue output of the 7i76. This is intended as a
speed control signal for a VFD.
(bit out) .7i76.0.0.output-NN: (NN = 0 to 15). 16 digital outputs. The sense of the signal can be set
via a parameter
(bit out) .7i76.0.0.input-NN: (NN = 0 to 31) 32 digital inputs.
(bit in) .7i76.0.0.input-NN-not: (NN = 0 to 31) An inverted copy of the inputs provided for convenience. The two complementary pins may be connected to different signal nets.
Parameters:
(u32 ro) .7i76.0.0.nvbaudrate: Indicates the vbaud rate. This probably should not be altered, and
special utils are needed to do so.
(u32 ro) .7i76.0.0.nvunitnumber: Indicates the serial number of the device and should match a
siticker on the card. This can be useful for wokring out which card is which.
(u32 ro) .7i76.0.0.nvwatchdogtimeout: The sserial remote watchdog timeout. This is separate from
the Anything-IO card timeout. This is unlikley to need to be changed.
(bit rw) .7i76.0.0.output-NN-invert: Invert the sense of the corresponding output pin.
(bit rw) .7i76.0.0.spindir-invert: Invert the senseof the spindle direction pin.
(bit rw) .7i76.0.0.spinena-invert: Invert the sense of the spindle-enable pin.
(float rw) .7i76.0.0.spinout-maxlim: The maximum speed request allowable
(float rw) .7i76.0.0.spinout-minlim: The minimum speed request.
(float rw) .7i76.0.0.spinout-scalemax: The spindle speed scaling. This is the speed request which
would correspond to full-scale output from the spindle control pin. For example with a 10V drive
voltage and a 10000rpm scalemax a value of 10,000 rpm on the spinout pin would produce 10V
output. However, if spinout-maxlim were set to 5,000 rpm then no voltage above 5V would be output.

LinuxCNC Documentation

2008-05-13

273

SSERIAL(9)

HAL Component

SSERIAL(9)

(u32 ro) .7i76.0.0.swrevision: The onboard firmware revision number. Utilities exist to update and
change this firmware.

7i77

The 7i77 is an 6-axis servo control card. The analogue outputs are smart-serial devices but the
encoders are conventional hostmot2 encoders and further details of them may be found in the hostmot2 manpage.
Pins: (bit out) .7i77.0.0.input-NN: (NN = 0 to 31) 32 digital inputs.
(bit in) .7i77.0.0.input-NN-not: (NN = 0 to 31) An inverted copy of the inputs provided for convenience. The two complementary pins may be connected to different signal nets.
(bit out) .7i77.0.0.output-NN: (NN = 0 to 15). 16 digital outputs. The sense of the signal can be set
via a parameter
(bit in) .7i77.0.0.spindir: This pin provides a means to drive the spindle VFD direction terminals
on the 7i76 board.
(bit in) .7i77.0.0.spinena: This pin drives the spindle-enable terminals on the 7i76 board.
(float in) .7i77.0.0.spinout: This controls the analog output of the 7i77. This is intended as a speed
control signal for a VFD.
(bit in) .7i77.0.1.analogena: This pin drives the analog enable terminals on the 7i77 board.
(float in) .7i77.0.1.analogoutN: (N = 0 to 5) This controls the analog output of the 7i77.
Parameters: (bit rw) .7i77.0.0.output-NN-invert: Invert the sense of the corresponding output pin.
(bit rw) .7i77.0.0.spindir-invert: Invert the senseof the spindle direction pin.
(bit rw) .7i77.0.0.spinena-invert: Invert the sense of the spindle-enable pin.
(float rw) .7i77.0.0.spinout-maxlim: The maximum speed request allowable
(float rw) .7i77.0.0.spinout-minlim: The minimum speed request.
(float rw) .7i77.0.0.spinout-scalemax: The spindle speed scaling. This is the speed request which
would correspond to full-scale output from the spindle control pin. For example with a 10V drive
voltage and a 10000rpm scalemax a value of 10,000 rpm on the spinout pin would produce 10V
output. However, if spinout-maxlim were set to 5,000 rpm then no voltage above 5V would be output.
(float rw) .7i77.0.0.analogoutN-maxlim: (N = 0 to 5) The maximum speed request allowable
(float rw) .7i77.0.0.analogoutN-minlim: (N = 0 to 5) The minimum speed request.
//// ***** CHECK ME ***** I’m not sure about the description on analogoutN-scalemax ////
(float rw) .7i77.0.0.analogoutN-scalemax: (N = 0 to 5) The analog speed scaling. This is the speed
request which would correspond to full-scale output from the spindle control pin. For example
with a 10V drive voltage and a 10000rpm scalemax a value of 10,000 rpm on the spinout pin
would produce 10V output. However, if spinout-maxlim were set to 5,000 rpm then no voltage
above 5V would be output.

274

2008-05-13

LinuxCNC Documentation

SSERIAL(9)

7i69

HAL Component

SSERIAL(9)

The 7i69 is a 48 channel digital IO card. It can be configured in four different modes: Mode 0 B
48 pins bidirectional (all outputs can be set high then driven low to work as inputs)
Mode 1 48 pins, input only
Mode 2 48 pins, all outputs
Mode 3 24 inputs and 24 outputs.
Pins: (bit in) .7i69.0.0.output-NN: Digital output. Sense can be inverted with the corresponding
Parameter
(bit out) .7i69.0.0.input-NN: Digital input
(bit out) .7i69.0.0.input-NN-not: Digital input, inverted.
Parameters:
(u32 ro) .7i69.0.0.nvbaudrate: Indicates the vbaud rate. This probably should not be altered, and
special utils are needed to do so.
(u32 ro) .7i69.0.0.nvunitnumber: Indicates the serial number of the device and should match a
siticker on the card. This can be useful for wokring out which card is which.
(u32 ro) .7i69.0.0.nvwatchdogtimeout: The sserial remote watchdog timeout. This is separate from
the Anything-IO card timeout. This is unlikley to need to be changed.
(bit rw) .7i69.0.0.output-NN-invert: Invert the sense of the corresponding output pin.
(u32 ro) .7i69.0.0.swrevision: The onboard firmware revision number. Utilities exist to update and
change this firmware.

7i70
The 7I70 is a remote isolated 48 input card. The 7I70 inputs sense positive inputs relative to a
common field ground. Input impedance is 10K Ohms and input voltage can range from 5VDC to
32VDC. All inputs have LED status indicators. The input common field ground is galvanically
isolated from the communications link.
The 7I70 has three software selectable modes. These different modes select different sets of 7I70
data to be transferred between the host and the 7I70 during real time process data exchanges. For
high speed applications, choosing the correct mode can reduced the data transfer sizes, resulting in
higher maximum update rates.
MODE 0 Input mode (48 bits input data only
MODE 1 Input plus analog mode (48 bits input data plus 6 channels of analog data)
MODE 2 Input plus field voltage
Pins:
(float out) .7i70.0.0.analogN (modes 1 and 2 only) Analogue input values.
(float out) .7i70.0.0.fieldvoltage (mode 2 only) Field voltage monitoring pin.
(bit out) .7i70.0.0.input-NN: (NN = 0 to 47) 48 digital inputs.
(bit in) .7i70.0.0.input-NN-not: (NN = 0 to 47) An inverted copy of the inputs provided for

LinuxCNC Documentation

2008-05-13

275

SSERIAL(9)

HAL Component

SSERIAL(9)

convenience. The two complementary pins may be connected to different signal nets.
Parameters:
(u32 ro) .7i70.0.0.nvbaudrate: Indicates the vbaud rate. This probably should not be altered, and
special utils are needed to do so.
(u32 ro) .7i70.0.0.nvunitnumber: Indicates the serial number of the device and should match a
siticker on the card. This can be useful for wokring out which card is which.
(u32 ro) .7i70.0.0.nvwatchdogtimeout: The sserial remote watchdog timeout. This is separate from
the Anything-IO card timeout. This is unlikley to need to be changed.
(u32 ro) .7i69.0.0.swrevision: The onboard firmware revision number. Utilities exist to update and
change this firmware.

7i71
The 7I71 is a remote isolated 48 output card. The 48 outputs are 8VDC to 28VDC sourcing drivers
(common + field power) with 300 mA maximum current capability. All outputs have LED status
indicators.
The 7I71 has two software selectable modes. For high speed applications, choosing the correct
mode can reduced the data transfer sizes, resulting in higher maximum update rates
MODE 0 Output only mode (48 bits output data only)
MODE 1 Outputs plus read back field voltage

Pins:
(float out) .7i71.0.0.fieldvoltage (mode 2 only) Field voltage monitoring pin.
(bit out) .7i71.0.0.output-NN: (NN = 0 to 47) 48 digital outputs. The sense may be inverted by the
invert parameter.
Parameters:
(bit rw) .7i71.0.0.output-NN-invert: Invert the sense of the corresponding output pin.
(u32 ro) .7i71.0.0.nvbaudrate: Indicates the vbaud rate. This probably should not be altered, and
special utils are needed to do so.
(u32 ro) .7i71.0.0.nvunitnumber: Indicates the serial number of the device and should match a
siticker on the card. This can be useful for wokring out which card is which.
(u32 ro) .7i71.0.0.nvwatchdogtimeout: The sserial remote watchdog timeout. This is separate from
the Anything-IO card timeout. This is unlikley to need to be changed.
(u32 ro) .7i69.0.0.swrevision: The onboard firmware revision number. Utilities exist to update and
change this firmware.

276

2008-05-13

LinuxCNC Documentation

SSERIAL(9)

7i73

HAL Component

SSERIAL(9)

The 7I73 is a remote real time pendant or control panel interface.
The 7I73 supports up to four 50KHz encoder inputs for MPGs, 8 digital inputs and 6 digital outputs and up to a 64 Key keypad. If a smaller keypad is used, more digital inputs and outputs
become available. Up to eight 0.0V to 3.3V analog inputs are also provided. The 7I73 can drive a
4 line 20 character LCD for local DRO applications.
The 7I73 has 3 software selectable process data modes. These different modes select different sets
of 7I73 data to be transferred between the host and the 7 I73 during real time process data
exchanges. For high speed applications, choosing the correct mode can reduced the data transfer
sizes, resulting in higher maximum update rates
MODE 0 I/O + ENCODER
MODE 1 I/O + ENCODER +ANALOG IN
MODE 2 I/O + ENCODER +ANALOG IN FAST DISPLAY
Pins:
(float out) .7i73.0.0.analoginN: Analogue inputs. Up to 8 channels may be available dependant on
software and hardware configuration modes. (see the pdf manual downlaodable from
www.mesanet.com)
(u32 in) .7i73.0.1.display (modes 1 and 2). Data for LCD display. This pin may be conveniently
driven by the HAL "lcd" component which allows the formatted display of the values any number
of HAL pins and textual content.

(u32 in) .7i73.0.1.display32 (mode 2 only). 4 bytes of data for LCD display. This mode is not supported by the HAL "lcd" component.
(s32 out) .7i73.0.1.encN: The position of the MPG encoder counters.
(bit out) .7i73.0.1.input-NN: Up to 24 digital inputs (dependent on config)
(bit out) .7i73.0.1.input-NN-not: Inverted copy of the digital inputs
(bit in) .7i73.0.1.output-NN: Up to 22 digital outputs (dependent on config)
Parameters:
(u32 ro) .7i73.0.1.nvanalogfilter:
(u32 ro) .7i73.0.1.nvbaudrate
(u32 ro) .7i73.0.1.nvcontrast
(u32 ro) .7i73.0.1.nvdispmode
(u32 ro) .7i73.0.1.nvencmode0
(u32 ro) .7i73.0.1.nvencmode1
(u32 ro) .7i73.0.1.nvencmode2
(u32 ro) .7i73.0.1.nvencmode3
(u32 ro) .7i73.0.1.nvkeytimer
(u32 ro) .7i73.0.1.nvunitnumber
(u32 ro) .7i73.0.1.nvwatchdogtimeout
(u32 ro) .7i73.0.1.output-00-invert
The above parameters are only settable with utility software, for further
details of their use see the Mesa manual.

LinuxCNC Documentation

2008-05-13

277

SSERIAL(9)

HAL Component

SSERIAL(9)

(bit rw) .7i73.0.1.output-01-invert: Invert the corresponding output bit.
(s32 ro) .7i73.0.1.swrevision: The version of firmware installed.
TODO: Add 7i77, 7i66, 7i72, 7i83, 7i84, 7i87.

278

2008-05-13

LinuxCNC Documentation

STEPGEN(9)

HAL Component

STEPGEN(9)

NAME
stepgen − software step pulse generation

SYNOPSIS
loadrt stepgen step_type=type0[,type1...] [ctrl_type=type0[,type1...]] [user_step_type=#,#...]

DESCRIPTION
stepgen is used to control stepper motors. The maximum step rate depends on the CPU and other factors,
and is usually in the range of 5KHz to 25KHz. If higher rates are needed, a hardware step generator is a
better choice.
stepgen has two control modes, which can be selected on a channel by channel basis using ctrl_type. Possible values are "p" for position control, and "v" for velocity control. The default is position control, which
drives the motor to a commanded position, subject to acceleration and velocity limits. Velocity control
drives the motor at a commanded speed, again subject to accel and velocity limits. Usually, position mode
is used for machine axes. Velocity mode is reserved for unusual applications where continuous movement
at some speed is desired, instead of movement to a specific position. (Note that velocity mode replaces the
former component freqgen.)
stepgen can control a maximum of 16 motors. The number of motors/channels actually loaded depends on
the number of type values given. The value of each type determines the outputs for that channel. Position
or velocity mode can be individually selected for each channel. Both control modes support the same 16
possible step types.
By far the most common step type is ’0’, standard step and direction. Others include up/down, quadrature,
and a wide variety of three, four, and five phase patterns that can be used to directly control some types of
motor windings. (When used with appropriate buffers of course.)
Some of the stepping types are described below, but for more details (including timing diagrams) see the
stepgen section of the HAL reference manual.
type 0: step/dir
Two pins, one for step and one for direction. make-pulses must run at least twice for each step
(once to set the step pin true, once to clear it). This limits the maximum step rate to half (or less)
of the rate that can be reached by types 2-14. The parameters steplen and stepspace can further
lower the maximum step rate. Parameters dirsetup and dirhold also apply to this step type.
type 1: up/down
Two pins, one for ’step up’ and one for ’step down’. Like type 0, make-pulses must run twice per
step, which limits the maximum speed.
type 2: quadrature
Two pins, phase-A and phase-B. For forward motion, A leads B. Can advance by one step every
time make-pulses runs.
type 3: three phase, full step
Three pins, phase-A, phase-B, and phase-C. Three steps per full cycle, then repeats. Only one
phase is high at a time - for forward motion the pattern is A, then B, then C, then A again.
type 4: three phase, half step
Three pins, phases A through C. Six steps per full cycle. First A is high alone, then A and B
together, then B alone, then B and C together, etc.
types 5 through 8: four phase, full step
Four pins, phases A through D. Four steps per full cycle. Types 5 and 6 are suitable for use with
unipolar steppers, where power is applied to the center tap of each winding, and four open-collector transistors drive the ends. Types 7 and 8 are suitable for bipolar steppers, driven by two Hbridges.

LinuxCNC Documentation

2007-01-16

279

STEPGEN(9)

HAL Component

STEPGEN(9)

types 9 and 10: four phase, half step
Four pins, phases A through D. Eight steps per full cycle. Type 9 is suitable for unipolar drive,
and type 10 for bipolar drive.
types 11 and 12: five phase, full step
Five pins, phases A through E. Five steps per full cycle. See HAL reference manual for the patterns.
types 13 and 14: five phase, half step
Five pins, phases A through E. Ten steps per full cycle. See HAL reference manual for the patterns.
type 15: user-specified
This uses the waveform specified by the user_step_type module parameter, which may have up to
10 steps and 5 phases.

FUNCTIONS
stepgen.make-pulses (no floating-point)
Generates the step pulses, using information computed by update-freq. Must be called as frequently as possible, to maximize the attainable step rate and minimize jitter. Operates on all channels at once.
stepgen.capture-position (uses floating point)
Captures position feedback value from the high speed code and makes it available on a pin for use
elsewhere in the system. Operates on all channels at once.
stepgen.update-freq (uses floating point)
Accepts a velocity or position command and converts it into a form usable by make-pulses for
step generation. Operates on all channels at once.

PINS
stepgen.N.counts s32 out
The current position, in counts, for channel N. Updated by capture-position.
stepgen.N.position-fb float out
The current position, in length units (see parameter position-scale). Updated by capture-position. The resolution of position-fb is much finer than a single step. If you need to see individual
steps, use counts.
stepgen.N.enable bit in
Enables output steps - when false, no steps are generated.
stepgen.N.velocity-cmd float in (velocity mode only)
Commanded velocity, in length units per second (see parameter position-scale).
stepgen.N.position-cmd float in (position mode only)
Commanded position, in length units (see parameter position-scale).
stepgen.N.step bit out (step type 0 only)
Step pulse output.
stepgen.N.dir bit out (step type 0 only)
Direction output: low for forward, high for reverse.
stepgen.N.up bit out (step type 1 only)
Count up output, pulses for forward steps.
stepgen.N.down bit out (step type 1 only)
Count down output, pulses for reverse steps.
stepgen.N.phase-A thru phase-E bit out (step types 2-14 only)
Output bits. phase-A and phase-B are present for step types 2-14, phase-C for types 3-14, phaseD for types 5-14, and phase-E for types 11-14. Behavior depends on selected stepping type.

280

2007-01-16

LinuxCNC Documentation

STEPGEN(9)

HAL Component

STEPGEN(9)

PARAMETERS
stepgen.N.frequency float ro
The current step rate, in steps per second, for channel N.
stepgen.N.maxaccel float rw
The acceleration/deceleration limit, in length units per second squared.
stepgen.N.maxvel float rw
The maximum allowable velocity, in length units per second. If the requested maximum velocity
cannot be reached with the current combination of scaling and make-pulses thread period, it will
be reset to the highest attainable value.
stepgen.N.position-scale float rw
The scaling for position feedback, position command, and velocity command, in steps per length
unit.
stepgen.N.rawcounts s32 ro
The position in counts, as updated by make-pulses. (Note: this is updated more frequently than
the counts pin.)
stepgen.N.steplen u32 rw
The length of the step pulses, in nanoseconds. Measured from rising edge to falling edge.
stepgen.N.stepspace u32 rw (step types 0 and 1 only) The minimum
space between step pulses, in nanoseconds. Measured from falling edge to rising edge. The actual
time depends on the step rate and can be much longer. If stepspace is 0, then step can be asserted
every period. This can be used in conjunction with hal_parport’s auto-resetting pins to output
one step pulse per period. In this mode, steplen must be set for one period or less.
stepgen.N.dirsetup u32 rw (step type 0 only)
The minimum setup time from direction to step, in nanoseconds periods. Measured from change
of direction to rising edge of step.
stepgen.N.dirhold u32 rw (step type 0 only)
The minimum hold time of direction after step, in nanoseconds. Measured from falling edge of
step to change of direction.
stepgen.N.dirdelay u32 rw (step types 1 and higher only)
The minimum time between a forward step and a reverse step, in nanoseconds.

TIMING
There are five timing parameters which control the output waveform. No step type uses all five, and only
those which will be used are exported to HAL. The values of these parameters are in nano-seconds, so no
recalculation is needed when changing thread periods. In the timing diagrams that follow, they are identfied by the following numbers:
(1) stepgen.n.steplen
(2) stepgen.n.stepspace
(3) stepgen.n.dirhold
(4) stepgen.n.dirsetup
(5) stepgen.n.dirdelay
For step type 0, timing parameters 1 thru 4 are used. The following timing diagram shows the output waveforms, and what each parameter adjusts.
STEP
Time
DIR

_____
_____
_____
____/
\_______/
\_____________/
\______
|
|
|
|
|
|
|-(1)-|--(2)--|-(1)-|--(3)--|-(4)-|-(1)-|
|__________________
________________________________/

LinuxCNC Documentation

2007-01-16

281

STEPGEN(9)

HAL Component

STEPGEN(9)

For step type 1, timing parameters 1, 2, and 5 are used. The following timing diagram shows the output
waveforms, and what each parameter adjusts.
UP
Time
DOWN

_____
_____
__/
\_____/
\________________________________
|
|
|
|
|
|-(1)-|-(2)-|-(1)-|---(5)---|-(1)-|-(2)-|-(1)-|
|_____|
|_____|
______________________________/
\_____/
\____

For step types 2 and higher, the exact pattern of the outputs depends on the step type (see the HAL manual
for a full listing). The outputs change from one state to another at a minimum interval of steplen. When a
direction change occurs, the minimum time between the last step in one direction and the first in the other
direction is the sum of steplen and dirdelay.

Linux CNC Manual Pages

Navigation menu

Versions of this User Manual:

Views

Navigation