Linux CNC Manual Pages

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 308 [warning: Documents this large are best viewed by clicking the View PDF Link!]

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 speciﬁes the conﬁguration name you would liketorun. If INIFILE is not

speciﬁed, 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 ﬁle is the main piece of an LinuxCNC conﬁguration. It is not the entire conﬁguration;

there are various other ﬁles that go with it (NML ﬁles, HAL ﬁles, TBL ﬁles, VAR ﬁles). It is, how-

ev e r, the most important one, because it is the ﬁle that holds the conﬁguration together.Itcan

adjust a lot of parameters itself, but it also tells linuxcnc which other ﬁles to load and use.

There are several ways to specify which conﬁg to use:

Specify the absolute path to an ini, e.g.

linuxcnc /usr/local/linuxcnc/conﬁgs/sim/sim.ini

Specify a relative path from the current directory,e.g.

linuxcnc conﬁgs/sim/sim.ini

Otherwise, in the case where the INIFILE is not speciﬁed, the behavior will depend on whether

you conﬁgured linuxcnc with --enable-run-in-place.Ifso, the linuxcnc conﬁg chooser will

search only the conﬁgs directory in your source tree. If not (or if you are using a packaged version

of linuxcnc), it may search several directories. The conﬁg chooser is currently set to search the

path:

˜/linuxcnc/conﬁgs:/home/buildslave/emc2-buildbot/precise-amd64-clang/docs/build/conﬁgs

EXAMPLES

linuxcnc

linuxcnc conﬁgs/sim/sim.ini

linuxcnc /etc/linuxcnc/sample-conﬁgs/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 1

LinuxCNC(1) The Enhanced Machine Controller LinuxCNC(1)

BUGS None known at this time.

AUTHOR

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

REPORTING BUGS

Report bugs to alex_joni ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

22006-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

MakeAXIS reload the currently loaded ﬁle.

--clear,-c

MakeAXIS clear the backplot.

--quit,-q

MakeAXIS 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 ﬁle 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 AlexJoni, as part of the LinuxCNC project.

REPORTING BUGS

Report bugs to alex_joni ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC Documentation 2007-04-01 3

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 ﬁle is the main piece of an LinuxCNC conﬁguration. It is not the entire conﬁguration;

there are various other ﬁles that go with it (NML ﬁles, HAL ﬁles, TBL ﬁles, VAR ﬁles). It is, how-

ev e r, the most important one, because it is the ﬁle that holds the conﬁguration together.Itcan

adjust a lot of parameters itself, but it also tells LinuxCNC which other ﬁles 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 AlexJoni, as part of the LinuxCNC project.

REPORTING BUGS

Report bugs to alex_joni ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

42007-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]compﬁle...

sudo comp [--install|--install-doc]compﬁle...

comp --compile --userspace cﬁle...

sudo comp --install --userspace cﬁle...

sudo comp --install --userspace pyﬁle...

DESCRIPTION

comp performs manydifferent functions:

• Compile .comp and .c ﬁles into .so or .ko HAL realtime components (the --compile ﬂag)

• Compile .comp and .c ﬁles into HAL userspace components (the --compile --userspace ﬂag)

• Preprocess .comp ﬁles into .c ﬁles (the --preprocess ﬂag)

• Extract documentation from .comp ﬁles into .9 manpage ﬁles (the --document ﬂag)

• Display documentation from .comp ﬁles onscreen (the --view-doc ﬂag)

•Compile and install .comp and .c ﬁles into the proper directory for HAL realtime components (the

--install ﬂag), which may require sudo to write to system directories.

• Install .c and .py ﬁles into the proper directory for HAL userspace components (the --install

--userspace ﬂag), which may require sudo to write to system directories.

•Extract documentation from .comp ﬁles into .9 manpage ﬁles in the proper system directory (the

--install ﬂag), which may require sudo to write to system directories.

• Preprocess .comp ﬁles into .c ﬁles (the --preprocess ﬂag)

SEE ALSO

Comp HAL Component Generator in the LinuxCNC documentation for a full description of the .comp syn-

tax, along with examples

pydoc hal and Creating Userspace Python Components in the LinuxCNC documentation for documenta-

tion on the Python interface to HAL components

comp(9) for documentation on the "twoinput comparator with hysteresis", a HAL realtime component

with the same name as this program

LinuxCNC Documentation 2007-10-17 5

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 halﬁle][-d] myﬁle.ui

OPTIONS

-g WxH+X+Y

This sets the initial geometry of the root window. Use ’WxH’ for just size, ’+X+Y’ for just posi-

tion, 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 speciﬁed, the

basename of the ui ﬁle is used.

-u handler

Instructs gladevcp to inspect the Python script handler for event handlers, and connect them to sig-

nals in the ui ﬁle.

-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 newtop levelwindow.

-H halﬁle

gladevcp runs halﬁle -alist of HAL commands - by executing halcmd -c halﬁle after the HAL

component is ﬁnalized.

-d enable debug output.

-R gtkrcﬁle

explicitly load a gtkrc ﬁle.

-t THEME

set gtk theme. Default is system theme. Different panels can have different themes.

-m MAXIMUM

force panel windowtomaxumize. 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 ﬁles fail. Normally not needed.

SEE ALSO

GladeVCP in the LinuxCNC documentation for a description of gladevcp’scapabilities and the associated

HAL widget set, along with examples

62010-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 mod-

busconnection.

gs2_vfd is for use with LinuxCNC

OPTIONS

-b, --bits <n>

(default 8) Set number of data bits to <n>, where n must be from 5 to 8 inclusive

-d, --device <path>

(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 hexonthe terminal.

-n, --name <string>

(default gs2_vfd) Set the name of the HAL module. The HAL comp name will be set to <string>,

and all pin and parameter names will begin with <string>.

-p, --parity [even,odd,none]

(default odd) Set serial parity to even, odd, or none.

-r,--rate <n>

(default 38400) Set baud rate to <n>. 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 <n>

(default 1) Set MODBUS target (slave)number.This must match the device number you set on the

GS2.

-A, --accel-seconds <n>

(default 10.0) Seconds to accelerate the spindle from 0 to Max RPM.

-D, --decel-seconds <n>

(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

Aofthe GS2 manual). It disables deceleration over-voltage stall prevention (see GS2 modbus

Parameter 6.05), allowing the VFD to keep braking eveninsituations where the motor is regener-

ating high voltage. The regenerated voltage gets safely dumped into the braking resistor.

PINS

GS2 VFD January 1, 2009 7

gs2_vfd(1) LinuxCNC Documentation gs2_vfd(1)

<name>.DC-bus-volts (ﬂoat, out)

from the VFD

<name>.at-speed (bit, out)

when drive isatcommanded speed

<name>.err-reset (bit, in)

reset errors sent to VFD

<name>.ﬁrmware-revision (s32, out)

from the VFD

<name>.frequency-command (ﬂoat, out)

from the VFD

<name>.frequency-out (ﬂoat, out)

from the VFD

<name>.is-stopped (bit, out)

when the VFD reports 0 Hz output

<name>.load-percentage (ﬂoat, out)

from the VFD

<name>.motor-RPM (ﬂoat, out)

from the VFD

<name>.output-current (ﬂoat, out)

from the VFD

<name>.output-voltage (ﬂoat, out)

from the VFD

<name>.power-factor (ﬂoat, out)

from the VFD

<name>.scale-frequency (ﬂoat, out)

from the VFD

<name>.speed-command (ﬂoat, 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

<name>.spindle-fwd (bit, in)

1for FWD and 0 for REV sent to VFD

<name>.spindle-on (bit, in)

1for ON and 0 for OFF sent to VFD, only on when running

<name>.spindle-rev (bit, in)

1for ON and 0 for OFF,only on when running

<name>.status-1 (s32, out)

Drive Status of the VFD (see the GS2 manual)

<name>.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 isinthe run mode is the sum of 3 (run) + 32 (freq set by

serial) + 128 (operation set by serial).

PARAMETERS

<name>.error-count (s32, RW)

8January 1, 2009 GS2 VFD

gs2_vfd(1) LinuxCNC Documentation gs2_vfd(1)

<name>.loop-time (ﬂoat, RW)

howoften the modbus is polled (default 0.1)

<name>.nameplate-HZ (ﬂoat, RW)

Nameplate Hz of motor (default 60)

<name>.nameplate-RPM (ﬂoat, RW)

Nameplate RPM of motor (default 1730)

<name>.retval (s32, RW)

the return value of an error in HAL

<name>.tolerance (ﬂoat, RW)

speed tolerance (default 0.01)

<name>.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 9

HAL_INPUT(1) HAL User’sManual HAL_INPUT(1)

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

SYNOPSIS

loadusr hal_input [-KRAL] inputspec ...

DESCRIPTION

hal_input is an interface between HAL and anyLinux input device, including USB HID devices. For each

device named, hal_input creates pins corresponding to its keys, absolute axes, and LEDs. At a ﬁxed rate of

approximately 10ms, it synchronizes the device and the HAL pins.

INPUT SPECIFICATION

The inputspec may be in one of several forms:

Astring S

Asubstring or shell-style pattern match will be tested against the "name" of the device, the "phys"

(which givesinformation about howitisconnected), and the "id", which is a string of the form

"Bus=... Vendor=... Product=... Version=...". You can viewthe name, phys, and id of attached

devices by executing less /proc/bus/input/devices.Examples:

SpaceBall

"Vendor=001f Product=0001"

serio*/input0

Anumber N

This opens /dev/input/eventN.Except for devices that are always attached to the system, this

number may change overreboots or when the device is removed. For this reason, using an integer

is not recommended.

When several devices are identiﬁed by the same string, add ":N"where Nis the indexofthe desired device.

Forexample, if Mouse matches input3 and input10,then Mouse and Mouse:0 select input3.Specifying

mouse:1 selects input10.

Fordevices that appear as multiple entries in /dev/input, these indices are likely to stay the same every time.

Formultiple 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 movedtodifferent ports or unplugged while the machine is

booted.

If the ﬁrst character of the inputspec is a "+", then hal_input requests exclusive access to the device. The

ﬁrst device matching an inputspec is used. Anynumber of inputspecsmay be used.

Asubset option may preceed eachinputspec.The subset option begins with a dash. Each letter in the sub-

set option speciﬁes a device feature to include.Features that are not speciﬁed 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

Forbuttons

input.N.btn-name bit out

input.N.btn-name-not bit out

Created for each button on the device.

10 2007-02-25 LinuxCNC Documentation

HAL_INPUT(1) HAL User’sManual HAL_INPUT(1)

Forkeys

input.N.key-name

input.N.key-name-not

Created for each key onthe device.

Forabsolute axes

input.N.abs-name-counts s32 out

input.N.abs-name-position ﬂoat out

input.N.abs-name-scale parameter ﬂoat rw

input.N.abs-name-offset parameter ﬂoat rw

input.N.abs-name-fuzz parameter s32 rw

input.N.abs-name-ﬂat 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 ﬂat 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 ﬂat are those reported by the operating system. The values of min and max are

those reported by the operating system.

Forrelative axes

input.N.rel-name-counts s32 out

input.N.rel-name-position ﬂoat out

input.N.rel-name-reset bit in

input.N.rel-name-scale parameter ﬂoat 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 anypast or current axis movement. Otherwise, counts increases or decreases accord-

ing 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 anyother value from 1 to 32. absolute,when set

true, ignores duplicate events with the same value. This allows for devices that repeat events with-

out anyuser action to work correctly. last shows the most recent count value returned by the

device, and is used in the implementation of absolute.

ForLEDs

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,

ev e nifthe device has no outputs. To change the default permission of a device, add a newﬁle to

/etc/udev/rules.d to set the device’sGROUP to "plugdev". You can do this for all input devices with this

rule: SUBSYSTEM=="input", MODE="0660", GROUP="plugdev"

Youcan also makemore speciﬁc rules for particular devices. For instance, a SpaceBall input device uses

the ’spaceball’ kernel module, so a udeventry 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.

ForUSB devices, the udevline would refer to the device’sVendor and Product values, such as

SYSFS{idProduct}=="c00e", SYSFS{idVendor}=="046d", MODE="0660", GROUP="plugdev"

LinuxCNC Documentation 2007-02-25 11

HAL_INPUT(1) HAL User’sManual HAL_INPUT(1)

for a particular logictech-brand mouse.

Formore information on writing udevrules, see udev(8).

BUGS The initial state of keys, buttons, and absolute axes are erroneously reported as FALSE or 0 until an event is

receivedfor that key,button, or axis.

SEE ALSO

udev(8)

12 2007-02-25 LinuxCNC Documentation

HALCMD(1) HAL User’sManual HALCMD(1)

NAME halcmd − manipulate the LinuxCNC HAL from the command line

SYNOPSIS

halcmd [OPTIONS][COMMAND [ARG]]

DESCRIPTION

halcmd is used to manipulate the HAL (Hardware Abstraction Layer) from the command line. halcmd can

optionally read commands from a ﬁle, allowing complexHAL conﬁgurations to be set up with a single

command.

If the readline library is available when LinuxCNC is compiled, then halcmd offers commandline editing

and completion when running interactively.Use the up arrowtorecall previous commands, and press tab to

complete the names of items such as pins and signals.

OPTIONS

-I Before tearing down the realtime environment, run an interactive halcmd. halrun only.If-I is

used, it must precede all other commandline arguments.

−f [ﬁle]Ignore commands on command line, takeinput from ﬁle instead. If ﬁle is not speciﬁed, takeinput

from stdin.

-i iniﬁle

Use variables from iniﬁle for substitutions. See SUBSTITUTION below.

−k Keep going after failed command(s). The default is to stop and return failure if anycommand

fails.

−q display errors only (default)

−Q display nothing, execute commands silently

−s Script-friendly mode. In this mode, show will not output titles for the items shown. Also, module

names will be printed instead of ID codes in pin, param, and funct listings. Threads are printed on

asingle line, with the thread period, FP usage and name ﬁrst, followed by all of the functions in

the thread, in execution order.Signals are printed on a single line, with the type, value, and signal

name ﬁrst, followed by a list of pins connected to the signal, showing both the direction and the

pin name. No prompt will be printed if both -s and -f are speciﬁed.

-R Release the HAL mutex. This is useful for recovering when a HAL component has crashed while

holding the HAL mutex.

−v display results of each command

−V display lots of debugging junk

−h [command]

display a help screen and exit, displays extended help on command if speciﬁed

COMMANDS

Commands tell halcmd what to do. Normally halcmd reads a single command from the command line and

executes it. If the ’-f’option is used to read commands from a ﬁle, halcmd reads each line of the ﬁle as a

newcommand. Anything following ’#’onaline is a comment.

loadrt modname

(load realtime module) Loads a realtime HAL module called modname.halcmd looks for the

module in a directory speciﬁed at compile time.

In systems with realtime, halcmd calls the linuxcnc_module_helper to load realtime modules.

linuxcnc_module_helper is a setuid program and is compiled with a whitelist of modules it is

allowed to load. This is currently just a list of LinuxCNC-related modules. The linuxcnc_mod-

ule_helper execs insmod, so return codes and error messages are those from insmod. Administra-

tors who wish to restrict which users can load these LinuxCNC-related kernel modules can do this

LinuxCNC Documentation 2003-12-18 13

HALCMD(1) HAL User’sManual HALCMD(1)

by setting the permissions and group on linuxcnc_module_helper appropriately.

In systems without realtime halcmd calls the rtapi_app which creates the simulated realtime

environment if it did not yet exist, and then loads the requested component with a call to

dlopen(3).

unloadrt modname

(unload realtime module) Unloads a realtime HAL module called modname.Ifmodname is "all",

it will unload all currently loaded realtime HAL modules. unloadrt also works by execing linux-

cnc_module_helper or rtapi_app,just like loadrt.

loadusr [ﬂags] unix-command

(load Userspace component) Executes the givenunix-command,usually to load a userspace com-

ponent. [ﬂags] may be one or more of:

•-W to wait for the component to become ready.The component is assumed to have the same

name as the ﬁrst argument of the command.

•-Wn name to wait for the component, which will have the givenname.

•-w to wait for the program to exit

•-i to ignore the program return value (with -w)

waitusr name

(wait for Userspace component) Waits for user space component name to disconnect from HAL

(usually on exit). The component must already be loaded. Usefull near the end of a HAL ﬁle to

wait until the user closes some user interface component before cleaning up and exiting.

unloadusr compname

(unload Userspace component) Unloads a userspace component called compname.Ifcompname

is "all", it will unload all userspace components. unloadusr works by sending SIGTERM to all

userspace components.

unload compname

Unloads a userspace component or realtime module. If compname is "all", it will unload all

userspace components and realtime modules.

newsig signame type

(OBSOLETE - use net instead) (newsignal) Creates a newHAL signal called signame that may

later be used to connect twoormore HAL component pins. type is the data type of the newsignal,

and must be one of "bit", "s32", "u32", or "ﬂoat". Fails if a signal of the same name already

exists.

delsig signame

(delete signal) Deletes HAL signal signame.Any pins currently linked to the signal will be

unlinked. Fails if signame does not exist.

sets signame value

(set signal) Sets the value of signal signame to value.Fails if signame does not exist, if it already

has a writer,orifvalue is not a legalvalue. Legalvalues depend on the signals’stype.

stype name

(signal type) Gets the type of signal name.Fails if name does not exist as a signal.

gets signame

(getsignal) Gets the value of signal signame.Fails if signame does not exist.

linkps pinname [arrow]signame

(OBSOLETE - use net instead) (link pin to signal) Establishs a link between a HAL component

pin pinname and a HAL signal signame.Any previous link to pinname will be broken. arrow can

be "=>", "<=", "<=>", or omitted. halcmd ignores arrows, but theycan be useful in command

ﬁles to document the direction of data ﬂow. Arrows should not be used on the command line since

14 2003-12-18 LinuxCNC Documentation

HALCMD(1) HAL User’sManual HALCMD(1)

the shell might try to interpret them. Fails if either pinname or signame does not exist, or if they

are not the same type type.

linksp signame [arrow]pinname

(OBSOLETE - use net instead) (link signal to pin) Works like linkps butrev erses the order of the

arguments. halcmd treats both link commands exactly the same. Use whicheveryou prefer.

linkpp pinname1 [arrow]pinname2

(OBSOLETE - use net instead) (link pin to pin) Shortcut for linkps that creates the signal (named

likethe ﬁrst pin), then links them both to that signal. halcmd treats this just as if it were:

halcmd newsig pinname1

halcmd linksp pinname1 pinname1

halcmd linksp pinname1 pinname2

net signame pinname ...

Create signname to match the type of pinname if it does not yet exist. Then, link signame to each

pinname in turn. Arrows may be used as in linkps.When linking a pin to a signal for the ﬁrst

time, the signal value will inherit the pin’sdefault value.

unlinkp pinname

(unlink pin) Breaks anyprevious link to pinname.Fails if pinname does not exist. An unlinked

pin will retain the last value of the signal it was linked to.

setp name value

(set parameter or pin) Sets the value of parameter or pin name to value.Fails if name does not

exist as a pin or parameter,ifitisaparameter that is not writable, if it is a pin that is an output, if

it is a pin that is already attached to a signal, or if value is not a legalvalue. Legalvalues depend

on the type of the pin or parameter.Ifapin and a parameter both exist with the givenname, the

parameter is acted on.

paramname =value

pinname =value

Identical to setp.This alternate form of the command may be more convenient and readable when

used in a ﬁle.

ptype name

(parameter or pin type)Gets the type of parameter or pin name.Fails if name does not exist as a

pin or parameter.Ifapin and a parameter both exist with the givenname, the parameter is acted

on.

getp name

(getparameter or pin) Gets the value of parameter or pin name.Fails if name does not exist as a

pin or parameter.Ifapin and a parameter both exist with the givenname, the parameter is acted

on.

addf functname threadname

(add function) Adds function functname to realtime thread threadname.functname will run after

anyfunctions that were previously added to the thread. Fails if either functname or threadname

does not exist, or if theyare incompatible.

delf functname threadname

(delete function) Removesfunction functname from realtime thread threadname.Fails if either

functname or threadname does not exist, or if functname is not currently part of threadname.

start Starts execution of realtime threads. Each thread periodically calls all of the functions that were

added to it with the addf command, in the order in which theywere added.

stop Stops execution of realtime threads. The threads will no longer call their functions.

LinuxCNC Documentation 2003-12-18 15

HALCMD(1) HAL User’sManual HALCMD(1)

show [item]

Prints HAL items to stdout in human readable format. item can be one of "comp"(components),

"pin", "sig"(signals), "param"(parameters), "funct"(functions), "thread", or "alias". The type

"all"can be used to showmatching items of all the preceeding types. If item is omitted, show will

print everything.

item This is equivalent to showall [item].

save [item]

Prints HAL items to stdout in the form of HAL commands. These commands can be redirected to

aﬁle and later executed using halcmd -f to restore the savedconﬁguration. item can be one of the

following: "comp"generates a loadrt command for realtime component. "sig"generates a newsig

command for each signal, and "sigu"generates a newsig command for each unlinked signal (for

use with netl and netla). "link"and "linka"both generate linkps commands for each link. (linka

includes arrows, while link does not.) "net"and "neta"both generate one newsig command for

each signal, followed by linksp commands for each pin linked to that signal. (neta includes

arrows.) "netl"generates one net command for each linked signal, and "netla"generates a similar

command using arrows. "param"generates one setp command for each parameter."thread"

generates one addf command for each function in each realtime thread. If item is omitted, save

does the equivalent of comp,sigu,link,param,and thread.

source ﬁlename.hal

Execute the commands from ﬁlename.hal.

alias type name alias

Assigns "alias"asasecond name for the pin or parameter "name". Formost operations, an alias

provides a second name that can be used to refer to a pin or parameter,both the original name and

the alias will work.

"type" must be pin or param.

"name" must be an existing name or alias of the speciﬁed type.

unalias type alias

Removesany alias from the pin or parameter alias.

"type" must be pin or param

"alias" must be an existing name or alias of the speciﬁed type.

list type [pattern]

Prints the names of HAL items of the speciﬁed type.

’type’ is ’comp’, ’pin’, ’sig’, ’param’, ’funct’, or

’thread’. If ’pattern’ is speciﬁed it prints only

those names that match the pattern, which may be a

’shell glob’.

For’sig’, ’pin’and ’param’, the ﬁrst pattern may be

-tdatatype where datatype is the data type (e.g., ’ﬂoat’)

in this case, the listed pins, signals, or parameters

are restricted to the givendata type

Names are printed on a single line, space separated.

lock [all|tune|none]

Locks HAL to some degree.

none - no locking done.

tune - some tuning is possible (setp &such).

all - HAL completely locked.

unlock [all|tune]

Unlocks HAL to some degree.

tune - some tuning is possible (setp &such).

all - HAL completely unlocked.

16 2003-12-18 LinuxCNC Documentation

HALCMD(1) HAL User’sManual HALCMD(1)

status [type]

Prints status info about HAL.

’type’ is ’lock’, ’mem’, or ’all’.

If ’type’ is omitted, it assumes ’all’.

help [command]

Give help information for command.

If ’command’ is omitted, list command and brief description

SUBSTITUTION

After a command is read but before it is executed, several types of variable substitution takeplace.

Environment Variables

Environment variables have the following formats:

$ENVVAR followed by end-of-line or whitespace

$(ENVVAR)

Iniﬁle Variables

Iniﬁle variables are available only when an iniﬁle was speciﬁed with the halcmd -i ﬂag. Theyhav e the fol-

lowing formats:

[SECTION]VAR followed by end-of-line or whitespace

[SECTION](VAR)

EXAMPLES

HISTORY

BUGS None known at this time.

AUTHOR

Original version by John Kasunich, as part of the LinuxCNC project. Nowincludes major contributions by

several members of the project.

REPORTING BUGS

Report bugs to the LinuxCNC bug tracker 〈http://sf.net/p/emc/bugs/〉.

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

halrun(1) -- a convenience script to start a realtime environment, process a .hal or a .tcl ﬁle, and optionally

start an interactive command session using halcmd (described here) or haltcl(1).

LinuxCNC Documentation 2003-12-18 17

HALMETER(1) HAL User’sManual HALMETER(1)

NAME halmeter − observeHAL pins, signals, and parameters

SYNOPSIS

halmeter [-s][pin|sig|param name][-g X-positon Y-position [Width]]

DESCRIPTION

halmeter is used to observeHAL (Hardware Abstraction Layer) pins, signals, or parameters. It serves the

same purpose as a multimeter does when working on physical systems.

OPTIONS

pin name

display the HAL pin name.

sig name

display the HAL signal name.

param name

display the HAL parameter name.

If neither pin,sig,orparam are speciﬁed, the

windowstarts out blank and the user must select an item to observe.

−s small window. Non-interactive,must be used with pin,sig,orparam to select the item to display.

The item name is displayed in the title bar instead of the window, and there are no "Select" or

"Exit" buttons. Handy when you want a lot of meters in a small space.

−g geometry position. allows one to specify the intial starting position and optionally the width of the

meter.Referenced from top left of screen in pixel units. Handy when you want to load a lot of

meters in a script with out them displaying on top of each other.

USAGEUnless −s is speciﬁed, there are twobuttons, "Select" and "Exit". "Select" opens a dialog box to select the

item (pin, signal, or parameter) to be observed. "Exit" does what you expect.

The selection dialog has "OK" "Apply", and "Cancel" buttons. OK displays the selected item and closes

the dialog. "Apply" displays the selected item but keeps the selection dialog open. "Cancel" closes the dia-

log without changing the displayed item.

EXAMPLES

halmeter

Opens a meter window, with nothing initially displayed. Use the "Select" button to choose an item

to observe. Does not return until the windowisclosed.

halmeter &

Open a meter window, with nothing initially displayed. Use the "Select" button to choose an item.

Runs in the background leaving the shell free for other commands.

halmeter pin parport.0.pin-03-out &

Open a meter window, initially displaying HAL pin parport.0.pin-03-out.The "Select" button can

be used to display other items. Runs in background.

halmeter -s pin parport.0.pin-03-out &

Open a small meter window, displaying HAL pin parport.0.pin-03-out.The displayed item cannot

be changed. Runs in background.

halmeter -s pin parport.0.pin-03-out -g 100 500 &

Open a small meter window, displaying HAL pin parport.0.pin-03-out.places it 100 pixels to the

left and 500 pixels down from top of screen. The displayed item cannot be changed. Runs in

background.

18 2006-03-13 LinuxCNC Documentation

HALMETER(1) HAL User’sManual HALMETER(1)

halmeter -s pin parport.0.pin-03-out -g 100 500 400 &

Open a small meter window, displaying HAL pin parport.0.pin-03-out.places it 100 pixels to the

left and 500 pixels down from top of screen. The width will be 400 pixels (270 is default) The dis-

played item cannot be changed. Runs in background.

SEE ALSO

HISTORY

BUGS

AUTHOR

Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other mem-

bers of the LinuxCNC development team.

REPORTING BUGS

Report bugs to jmkasunich ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC Documentation 2006-03-13 19

HALRUN(1) HAL User’sManual HALRUN(1)

NAME halrun − manipulate the LinuxCNC HAL from the command line

SYNOPSIS

halrun -h

halrun [-I][halcmd_opts][ﬁlename[.hal|.tcl]]

halrun -T [halcmd_opts][ﬁlename[.hal|.tcl]]

halrun -U

DESCRIPTION

halrun is a convenience script used to manipulate the HAL (Hardware Abstraction Layer) from the com-

mand line. When invoked, halrun:

Sets up the realtime environment.

Executes a command interpreter (halcmd or haltcl).

(Optionally) runs an interactive session.

Tears down the realtime environment.

If no ﬁlename is speciﬁed, an interactive session is started.

The session will use halcmd(1) unless -T is speciﬁed in

which case haltcl(1) will be used.

If a ﬁlename is specifed and neither the -I nor the -T option

is included, the ﬁlename will be processed by the command

interpreter corresponding to the ﬁlename extension (halcmd

or haltcl). After processing, the realtime environment

will be torn down.

If a ﬁlename is specifed and the -I or -T option is included,

the ﬁle is processed by the appropriate command interpreter and

then an interactive session is started for halcmd or

haltcl according to the -I or -T option.

OPTIONS

halcmd_opts

When a .hal ﬁle is specifed, the halcmd_opts are passed to halcmd.See the man page for hal-

cmd(1). When a.tcl ﬁle is speciﬁed, the only valid options are:

-i iniﬁle

-f ﬁlename[.tcl|.hal] (alternate means of specifying a ﬁle)

-I Run an interactive halcmd session

-T Run an interactive haltcl session.

-U Forcibly cause the realtime environment to exit. It releases the HAL mutex, requests that all HAL

components unload, and stops the realtime system. -U must be the only commandline argument.

−h display a brief help screen and exit

EXAMPLES

HISTORY

BUGS None known at this time.

AUTHOR

Original version by John Kasunich, as part of the LinuxCNC Enhanced Machine Controller project. Now

includes major contributions by several members of the project.

20 2012-01-31 LinuxCNC Documentation

HALRUN(1) HAL User’sManual HALRUN(1)

REPORTING BUGS

Report bugs to the LinuxCNC bug tracker 〈URL: http://sf.net/p/emc/bugs/ 〉.

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

halcmd(1), haltcl(1)

LinuxCNC Documentation 2012-01-31 21

HALSAMPLER(1) HAL User’sManual HALSAMPLER(1)

NAME halsampler − sample data from HAL in realtime

SYNOPSIS

halsampler [options]

DESCRIPTION

sampler(9) and halsampler are used together to sample HAL data in real time and store it in a ﬁle. sam-

pler is a realtime HAL component that exports HAL pins and creates a FIFO in shared memory.Itthen

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 ﬁle or piped to some other program.

OPTIONS

-c CHAN

instructs halsampler to read from FIFO CHAN.FIFOs are numbered from zero, and the default

value is zero, so this option is not needed unless multiple FIFOs have been created.

-n COUNT

instructs halsampler to read COUNT samples from the FIFO, then exit. If -n is not speciﬁed, hal-

sampler will read continuously until it is killed.

-t instructs halsampler to tag each line by printing the sample number in the ﬁrst column.

FILENAME

instructs halsampler to write to FILENAME instead of to stdout.

USAGEAFIFO must ﬁrst be created by loading sampler(9) with halcmd loadrt or a loadrt command in a .hal ﬁle.

Then halsampler can be invokedtobegin printing data from the FIFO to stdout.

Data is printed one line per sample. If -t wasspeciﬁed, the sample number is printed ﬁrst. The data fol-

lows, in the order that the pins were deﬁned in the conﬁg string. Forexample, if the sampler conﬁg string

was"ffbs" then a typical line of output (without -t)would look like:

123.55 33.4 0 -12

halsampler prints data as fast as possible until the FIFO is empty,then it retries at regular intervals, until it

is either killed or has printed COUNT samples as requested by -n.Usually,but not always, data printed by

halsampler will be redirected to a ﬁle or piped to some other program.

The FIFO size should be chosen to absorb samples captured during anymomentary disruptions in the ﬂow

of data, such as disk seeks, terminal scrolling, or the processing limitations of subsequent program in a

pipeline. If the FIFO gets full and sampler is forced to overwrite old data, halsampler will print ’overrun’

on a line by itself to mark each gap in the sampled data. If -t wasspeciﬁed, gaps in the sequential sample

numbers in the ﬁrst column can be used to determine exactly howmanysamples were lost.

The data format for halsampler output is the same as for halstreamer(1) input, so ’wav eforms’ captured

with halsampler can be replayed using halstreamer.The -t option should not be used in this case.

EXIT STATUS

If a problem is encountered during initialization, halsampler prints a message to stderr and returns failure.

Upon printing COUNT samples (if -n wasspeciﬁed) it will shut down and return success. If it is termi-

nated before printing the speciﬁed number of samples, it returns failure. This means that when -n is not

speciﬁed, it will always return failure when terminated.

SEE ALSO

sampler(9) streamer(9) halstreamer(1)

22 2006-11-18 LinuxCNC Documentation

HALSAMPLER(1) HAL User’sManual HALSAMPLER(1)

HISTORY

BUGS

AUTHOR

Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other mem-

bers of the LinuxCNC development team.

REPORTING BUGS

Report bugs to jmkasunich ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC Documentation 2006-11-18 23

HALSTREAMER(1) HAL User’sManual HALSTREAMER(1)

NAME halstreamer − stream ﬁle data into HAL in real time

SYNOPSIS

halstreamer [options]

DESCRIPTION

streamer(9) and halstreamer are used together to stream data from a ﬁle into the HAL in real time.

streamer is a realtime HAL component that exports HAL pins and creates a FIFO in shared memory.

hal_streamer is a user space program that copies data from stdin into the FIFO, so that streamer can write

it to the HAL pins.

OPTIONS

-c CHAN

instructs halstreamer to write to FIFO CHAN.FIFOs are numbered from zero, and the default

value is zero, so this option is not needed unless multiple FIFOs have been created.

FILENAME

instructs halsampler to read from FILENAME instead of from stdin.

USAGEAFIFO must ﬁrst be created by loading streamer(9) with halcmd loadrt or a loadrt command in a .hal

ﬁle. Then halstreamer can be invokedtobegin writing data into the FIFO.

Data is read from stdin, and is almost always either redirected from a ﬁle or piped from some other pro-

gram, since keyboard input would be unable to keep up with evenslowstreaming rates.

Each line of input must match the pins that are attached to the FIFO, for example, if the streamer conﬁg

string was "ffbs" then each line of input must consist of twoﬂoats, a bit, and a signed integer,inthat order

and separated by whitespace. Floats must be formatted as required by strtod(3), signed and unsigned inte-

gers must be formated as required by strtol(3) and strtoul(3), and bits must be either ’0’ or ’1’.

halstreamer transfers data to the FIFO as fast as possible until the FIFO is full, then it retries at regular

intervals, until it is either killed or reads EOF from stdin. Data can be redirected from a ﬁle or piped from

some other program.

The FIFO size should be chosen to ride through anymomentary disruptions in the ﬂowofdata, such as disk

seeks. If the FIFO is big enough, halstreamer can be restarted with the same or a newﬁle before the FIFO

empties, resulting in a continuous stream of data.

The data format for halstreamer input is the same as for halsampler(1) output, so ’wav eforms’ captured

with halsampler can be replayed using halstreamer.

EXIT STATUS

If a problem is encountered during initialization, halstreamer prints a message to stderr and returns failure.

If a badly formatted line is encountered while writing to the FIFO, it prints a message to stderr,skips the

line, and continues (this behavior may be revised in the future).

Upon reading EOF from the input, it returns success. If it is terminated before the input ends, it returns

failure.

SEE ALSO

streamer(9) sampler(9) halsampler(1)

HISTORY

24 2006-11-18 LinuxCNC Documentation

HALSTREAMER(1) HAL User’sManual HALSTREAMER(1)

BUGS

AUTHOR

Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other mem-

bers of the LinuxCNC development team.

REPORTING BUGS

Report bugs to jmkasunich ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC Documentation 2006-11-18 25

HALTCL(1) HAL User’sManual HALTCL(1)

NAME haltcl − manipulate the LinuxCNC HAL from the command line using a tcl interpeter.

SYNOPSIS

haltcl [-i iniﬁle][ﬁlename]

DESCRIPTION

haltcl is used to manipulate the HAL (Hardware Abstraction Layer) from the command line using a tcl

interpreter. haltcl can optionally read commands from a ﬁle (ﬁlename), allowing complexHAL conﬁgura-

tions to be set up with a single command.

OPTIONS

-i iniﬁle

If speciﬁed, the iniﬁle is read and used to create tcl global variable arrays. An array is created for

each SECTION of the iniﬁle with elements for each ITEM in the section.

Forexample, if the iniﬁle contains:

[SECTION_A]ITEM_1 = 1

[SECTION_A]ITEM_2 = 2

[SECTION_B]ITEM_1 = 10

The corresponding tcl variables are:

SECTION_A(ITEM_1) = 1

SECTION_A(ITEM_2) = 2

SECTION_B(ITEM_1) = 10

-ini iniﬁle -- declining usage, use -i iniﬁle

ﬁlenameIf speciﬁed, the tcl commands of ﬁlename are executed. If no ﬁlename is speciﬁed, haltcl opens

an interactive session.

COMMANDS

haltcl includes the commands of a tcl interpreter augmented with commands for the hal language as

described for halcmd(1). The augmented commands can be listed with the command:

haltcl: hal --commands

addf alias delf delsig getp gets ptype stype help linkpp linkps linksp list loadrt loadusr lock net newsig

save setexact_for_test_suite_only setp sets showsource start status stop unalias unlinkp unload unloadrt

unloadusr unlock waitusr

Tw o of the augmented commands, ’list’ and ’gets’, require special treatment to avoid conﬂict with tcl built-

in commands having the same names. To use these commands, precede them with the keyword ’hal’:

hal list

hal gets

REPORTING BUGS

Report bugs to the LinuxCNC bug tracker 〈URL: http://sf.net/p/emc/bugs/ 〉.

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

26 2012-01-31 LinuxCNC Documentation

HALTCL(1) HAL User’sManual HALTCL(1)

SEE ALSO

halcmd(1), halrun(1)

LinuxCNC Documentation 2012-01-31 27

HALUI(1) HAL User Interface HALUI(1)

NAME halui − observeHAL pins and command LinuxCNC through NML

SYNOPSIS

halui [-ini <path-to-ini>]

DESCRIPTION

halui is used to build a User Interface using hardware knobs and switches. It exports a big number of pins,

and acts accordingly when these change.

OPTIONS

-ini name

use the name as the conﬁguration ﬁle. Note: halui must ﬁnd the nml ﬁle speciﬁed in the ini, usu-

ally that ﬁle is in the same folder as the ini, so it makes sense to run halui from that folder.

USAGEWhen run, halui will export a large number of pins. A user can connect those to his physical knobs &

switches & leds, and when a change is noticed halui triggers an appropriate event.

halui expects the signals to be debounced, so if needed (bad knob contact) connect the physical button to a

HAL debounce ﬁlter ﬁrst.

PINS

abort

halui.abort bit in

pin for clearing most errors

tool halui.tool.length-offset.a ﬂoat out

current applied tool length offset for the A axis

halui.tool.length-offset.b ﬂoat out

current applied tool length offset for the B axis

halui.tool.length-offset.c ﬂoat out

current applied tool length offset for the C axis

halui.tool.length-offset.u ﬂoat out

current applied tool length offset for the U axis

halui.tool.length-offset.v ﬂoat out

current applied tool length offset for the V axis

halui.tool.length-offset.w ﬂoat out

current applied tool length offset for the W axis

halui.tool.length-offset.x ﬂoat out

current applied tool length offset for the X axis

halui.tool.length-offset.y ﬂoat out

current applied tool length offset for the Y axis

halui.tool.length-offset.z ﬂoat out

current applied tool length offset for the Z axis

halui.tool.number u32 out

current selected tool

spindle

28 2006-07-22 LinuxCNC Documentation

HALUI(1) HAL User Interface HALUI(1)

halui.spindle.brake-is-on bit out

status pin that tells us if brakeison

halui.spindle.brake-off bit in

pin for deactivating the spindle brake

halui.spindle.brake-on bit in

pin for activating the spindle brake

halui.spindle.decrease bit in

arising edge on this pin decreases the current spindle speed by 100

halui.spindle.forward bit in

arising edge on this pin makes the spindle go forward

halui.spindle.increase bit in

arising edge on this pin increases the current spindle speed by 100

halui.spindle.is-on bit out

status pin telling if the spindle is on

halui.spindle.rev erse bit in

arising edge on this pin makes the spindle go reverse

halui.spindle.runs-backward bit out

status pin telling if the spindle is running backward

halui.spindle.runs-forward bit out

status pin telling if the spindle is running forward

halui.spindle.start bit in

arising edge on this pin starts the spindle

halui.spindle.stop bit in

arising edge on this pin stops the spindle

spindle override

halui.spindle-override.count-enable bit in (default: TRUE)

When TRUE, modify spindle override when counts changes.

halui.spindle-override.counts s32 in

counts X scale = spindle override percentage

halui.spindle-override.decrease bit in

pin for decreasing the SO (-=scale)

halui.spindle-override.direct-value bit in

pin to enable direct spindle override value input

halui.spindle-override.increase bit in

pin for increasing the SO (+=scale)

halui.spindle-override.scale ﬂoat in

pin for setting the scale of counts for SO

halui.spindle-override.value ﬂoat out

current FO value

program

halui.program.block-delete.is-on bit out

status pin telling that block delete is on

LinuxCNC Documentation 2006-07-22 29

HALUI(1) HAL User Interface HALUI(1)

halui.program.block-delete.off bit in

pin for requesting that block delete is off

halui.program.block-delete.on bit in

pin for requesting that block delete is on

halui.program.is-idle bit out

status pin telling that no program is running

halui.program.is-paused bit out

status pin telling that a program is paused

halui.program.is-running bit out

status pin telling that a program is running

halui.program.optional-stop.is-on bit out

status pin telling that the optional stop is on

halui.program.optional-stop.off bit in

pin requesting that the optional stop is off

halui.program.optional-stop.on bit in

pin requesting that the optional stop is on

halui.program.pause bit in

pin for pausing a program

halui.program.resume bit in

pin for resuming a program

halui.program.run bit in

pin for running a program

halui.program.step bit in

pin for stepping in a program

halui.program.stop bit in

pin for stopping a program (note: this pin does the same thing as halui.abort)

mode

halui.mode.auto bit in

pin for requesting auto mode

halui.mode.is-auto bit out

pin for auto mode is on

halui.mode.is-joint bit out

pin showing joint by joint jog mode is on

halui.mode.is-manual bit out

pin for manual mode is on

halui.mode.is-mdi bit out

pin for mdi mode is on

halui.mode.is-teleop bit out

pin showing coordinated jog mode is on

halui.mode.joint bit in

pin for requesting joint by joint jog mode

halui.mode.manual bit in

pin for requesting manual mode

30 2006-07-22 LinuxCNC Documentation

HALUI(1) HAL User Interface HALUI(1)

halui.mode.mdi bit in

pin for requesting mdi mode

halui.mode.teleop bit in

pin for requesting coordinated jog mode

mdi (optional)

halui.mdi-command-XX bit in

halui looks for ini variables named [HALUI]MDI_COMMAND, and exports a pin for each com-

mand it ﬁnds. When the pin is drivenTRUE, halui runs the speciﬁed MDI command. XX is a

twodigit number starting at 00. If no [HALUI]MDI_COMMAND variables are set in the ini ﬁle,

no halui.mdi-command-XX pins will be exported by halui.

mist halui.mist.is-on bit out

pin for mist is on

halui.mist.off bit in

pin for stopping mist

halui.mist.on bit in

pin for starting mist

max-velocity

halui.max-velocity.count-enable bit in (default: TRUE)

When TRUE, modify max velocity when counts changes.

halui.max-velocity.counts s32 in

counts from an encoder for example to change maximum velocity

halui.max-velocity.decrease bit in

pin for decreasing the maximum velocity (-=scale)

halui.max-velocity.direct-value bit in

pin for using a direct value for max velocity

halui.max-velocity.increase bit in

pin for increasing the maximum velocity (+=scale)

halui.max-velocity.scale ﬂoat in

pin for setting the scale on changing the maximum velocity

halui.max-velocity.value ﬂoat out

Current value for maximum velocity

machine

halui.machine.is-on bit out

pin for machine is On/Off

halui.machine.off bit in

pin for setting machine Off

halui.machine.on bit in

pin for setting machine On

lube halui.lube.is-on bit out

pin for lube is on

LinuxCNC Documentation 2006-07-22 31

HALUI(1) HAL User Interface HALUI(1)

halui.lube.off bit in

pin for stopping lube

halui.lube.on bit in

pin for starting lube

jointhalui.joint.N.has-fault bit out

status pin telling that joint N has a fault

halui.joint.N.home bit in

pin for homing joint N

halui.joint.N.is-homed bit out

status pin telling that joint N is homed

halui.joint.N.is-selected bit out

status pin that joint N is selected

halui.joint.N.on-hard-max-limit bit out

status pin telling that joint N is on the positive hardware limit

halui.joint.N.on-hard-min-limit bit out

status pin telling that joint N is on the negative hardware limit

halui.joint.N.on-soft-max-limit bit out

status pin telling that joint N is on the positive software limit

halui.joint.N.on-soft-min-limit bit out

status pin telling that joint N is on the negative software limit

halui.joint.N.select bit in

pin for selecting joint N

halui.joint.N.unhome bit in

pin for unhoming joint N

halui.joint.selected u32 out

selected joint

halui.joint.selected.has-fault bit out

status pin selected joint is faulted

halui.joint.selected.home bit in

pin for homing the selected joint

halui.joint.selected.is-homed bit out

status pin telling that the selected joint is homed

halui.joint.selected.on-hard-max-limit bit out

status pin telling that the selected joint is on the positive hardware limit

halui.joint.selected.on-hard-min-limit bit out

status pin telling that the selected joint is on the negative hardware limit

halui.joint.selected.on-soft-max-limit bit out

status pin telling that the selected joint is on the positive software limit

halui.joint.selected.on-soft-min-limit bit out

status pin telling that the selected joint is on the negative software limit

halui.joint.selected.unhome bit in

pin for unhoming the selected joint

32 2006-07-22 LinuxCNC Documentation

HALUI(1) HAL User Interface HALUI(1)

jog halui.jog.deadband ﬂoat in

pin for setting jog analog deadband (jog analog inputs smaller/slower than this are ignored)

halui.jog-speed ﬂoat in

pin for setting jog speed for plus/minus jogging.

halui.jog.N.analog ﬂoat in

pin for jogging the axis N using an ﬂoat value (e.g. joystick)

halui.jog.N.increment ﬂoat in

pin for setting the jog increment for axis N when using increment-plus/minus

halui.jog.N.increment-minus bit in

arising edge will will makeaxis N jog in the negative direction by the increment amount

halui.jog.N.increment-plus bit in

arising edge will will makeaxis N jog in the positive direction by the increment amount

halui.jog.N.minus bit in

pin for jogging axis N in negative direction at the halui.jog-speed velocity

halui.jog.N.plus bit in

pin for jogging axis N in positive direction at the halui.jog-speed velocity

halui.jog.selected.increment ﬂoat in

pin for setting the jog increment for the selected axis when using increment-plus/minus

halui.jog.selected.increment-minus bit in

arising edge will will makethe selected axis jog in the negative direction by the increment amount

halui.jog.selected.increment-plus bit in

arising edge will will makethe selected axis jog in the positive direction by the increment amount

halui.jog.selected.minus bit in

pin for jogging the selected axis in negative direction at the halui.jog-speed velocity

halui.jog.selected.plus

pin for jogging the selected axis bit in in positive direction at the halui.jog-speed velocity

ﬂoodhalui.ﬂood.is-on bit out

pin for ﬂood is on

halui.ﬂood.off bit in

pin for stopping ﬂood

halui.ﬂood.on bit in

pin for starting ﬂood

feed override

halui.feed-override.count-enable bit in (default: TRUE)

When TRUE, modify feed override when counts changes.

halui.feed-override.counts s32 in

counts X scale = feed override percentage

halui.feed-override.decrease bit in

pin for decreasing the FO (-=scale)

halui.feed-override.direct-value bit in

pin to enable direct value feed override input

LinuxCNC Documentation 2006-07-22 33

HALUI(1) HAL User Interface HALUI(1)

halui.feed-override.increase bit in

pin for increasing the FO (+=scale)

halui.feed-override.scale ﬂoat in

pin for setting the scale on changing the FO

halui.feed-override.value ﬂoat out

current Feed Override value

rapid override

halui.rapid-override.count-enable bit in (default: TRUE)

When TRUE, modify Rapid Override when counts changes.

halui.rapid-override.counts s32 in

counts X scale = Rapid Override percentage

halui.rapid-override.decrease bit in

pin for decreasing the Rapid Override (-=scale)

halui.rapid-override.direct-value bit in

pin to enable direct value Rapid Override input

halui.rapid-override.increase bit in

pin for increasing the Rapid Override (+=scale)

halui.rapid-override.scale ﬂoat in

pin for setting the scale on changing the Rapid Override

halui.rapid-override.value ﬂoat out

current Rapid Override value

estophalui.estop.activate bit in

pin for setting Estop (LinuxCNC internal) On

halui.estop.is-activated bit out

pin for displaying Estop state (LinuxCNC internal) On/Off

halui.estop.reset bit in

pin for resetting Estop (LinuxCNC internal) Off

axis halui.axis.N.pos-commanded ﬂoat out ﬂoat out

Commanded axis position in machine coordinates

halui.axis.N.pos-feedback ﬂoat out ﬂoat out

Feedback axis position in machine coordinates

halui.axis.N.pos-relative ﬂoat out ﬂoat out

Commanded axis position in relative coordinates

home

halui.home-all bit in

pin for requesting home-all (only available when a valid homing sequence is speciﬁed)

SEE ALSO

HISTORY

BUGS none known at this time.

34 2006-07-22 LinuxCNC Documentation

HALUI(1) HAL User Interface HALUI(1)

AUTHOR

Written by AlexJoni, as part of the LinuxCNC project. Updated by John Thornton

REPORTING BUGS

Report bugs to alex_joni ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC Documentation 2006-07-22 35

IOCONTROL(1) HAL Component IOCONTROL(1)

NAME iocontrol − accepts NML I/O commands, interacts with HAL in userspace

SYNOPSIS

loadusr io [-ini iniﬁle]

DESCRIPTION

These pins are created by the userspace IO controller,usually found in $LINUXCNC_HOME/bin/io

The signals are turned on and offinuserspace - if you have strict timing requirements or simply need more

i/o, consider using the realtime synchronized i/o provided by motion(9) instead.

The iniﬁle is searched for in the directory from which halcmd was run, unless an absolute path is speciﬁed.

PINS iocontrol.0.coolant-ﬂood

(Bit, Out) TRUE when ﬂood coolant is requested

iocontrol.0.coolant-mist

(Bit, Out) TRUE when mist coolant is requested

iocontrol.0.emc-enable-in

(Bit, In) Should be drivenFALSE when an external estop condition exists.

iocontrol.0.lube

(Bit, Out) TRUE when lube is requested

iocontrol.0.lube_level

(Bit, In) Should be drivenFALSE when lubrication tank is empty.

iocontrol.0.tool-change

(Bit, Out) TRUE when a tool change is requested

iocontrol.0.tool-changed

(Bit, In) Should be drivenTRUEwhen a tool change is completed.

iocontrol.0.tool-number

(s32, Out) Current tool number

iocontrol.0.tool-prep-number

(s32, Out) The number of the next tool, from the RS274NGC T-word

iocontrol.0.tool-prep-pocket

(s32, Out) The pocket number (location in tool storage mechanism) of the next tool, as described

in the tool table

iocontrol.0.tool-prepare

(Bit, Out) TRUE when a Tntool prepare is requested

36 2007-08-25 LinuxCNC Documentation

IOCONTROL(1) HAL Component IOCONTROL(1)

iocontrol.0.tool-prepared

(Bit, In) Should be drivenTRUEwhen a tool prepare is completed.

iocontrol.0.user-enable-out

(Bit, Out) FALSE when an internal estop condition exists

iocontrol.0.user-request-enable

(Bit, Out) TRUE when the user has requested that estop be cleared

SEE ALSO

motion(9)

LinuxCNC Documentation 2007-08-25 37

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

NAME linuxcncrsh − text-mode interface for commanding LinuxCNC overthe network

SYNOPSIS

linuxcncrsh [OPTIONS] [-- LINUXCNC_OPTIONS]

DESCRIPTION

linuxcncrsh is a user interface for LinuxCNC. Instead of popping up a GUI windowlikeaxis(1) and

touchy(1) do, it processes text-mode commands that it receivesvia the network. A human (or a program)

can interface with linuxcncrsh using telnet(1) or nc(1) or similar programs.

All features of LinuxCNC are available via the linuxcncrsh interface.

OPTIONS

-p,--port PORT_NUMBER

Specify the port for linuxcncrsh to listen on. Defaults to 5007 if omitted.

-n,--name SERVER_NAME

Sets the server name that linuxcncrsh will use to identify itself during handshaking with a new

client. Defaults to EMCNETSVR if omitted.

-w,--connectpw PASSWORD

Specify the connection password to use during handshaking with a newclient. Note that the pass-

word is sent in the clear,soitcan be read by anyone who can read packets on the network between

the server and the client. Defaults to EMC if omitted.

-e,--enablepw PASSWORD

Specify the password required to enable LinuxCNC via linuxcncrsh. Note that the password is

sent in the clear,soitcan be read by anyone who can read packets on the network between the

server and the client. Defaults to EMCTOO if omitted.

-s,--sessions MAX_SESSIONS

Specify the maximum number of simultaneous connections. Defaults to -1 (no limit) if not speci-

ﬁed.

In addition to the options listed above,linuxcncrsh accepts an optional special LINUXCNC_OPTION at

the end:

-ini LINUXCNC_INI_FILE

LinuxCNC .ini ﬁle to use. The -ini option must be preceeded by twodashes: "--". Defaults to

emc.ini if omitted.

Starting linuxcncrsh

To use linuxcncrsh instead of a normal LinuxCNC GUI likeaxis or touch, specify it in your .ini ﬁle like

this:

[DISPLAY]

DISPLAY=linuxcncrsh

To use linuxcncrsh in addition to a normal GUI, you can either start it at the end of your .hal ﬁle, or run it

by hand in a terminal window.

To start it from hal, add a line likethis to the end of your .hal ﬁle:

loadusr linuxcncrsh [OPTIONS] [-- LINUXCNC_OPTIONS]

To start it from the terminal, run linuxcncrsh manually likethis:

linuxcncrsh [OPTIONS] [-- LINUXCNC_OPTIONS]

Connecting

Once LinuxCNC is up and linuxcncrsh is running, you can connect to it using telnet or nc or similar:

telnet HOST PORT

HOST is the hostname or IP address of the computer running linuxcncrsh, and PORTis

38 May 31, 2011

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

the port it’slistening on (5007 if you did not give linuxcncrsh the --port option).

Network protocol

linuxcncrsh accepts TCP connections on the port speciﬁed by the --port option, or 5007 if not speciﬁed.

The client sends requests, and the linuxcncrsh server returns replies. Requests consist of a command word

followed by optional command-speciﬁc parameters. Requests and most request parameters are case insen-

sitive.The exceptions are passwords, ﬁle paths and text strings.

Requests to linuxcncrsh are terminated with line endings, anycombination of one or more ’\r’ and ’\n’

characters. Replies from linuxcncrsh are terminated with the sequence ´\r\n´.

The supported commands are as follows:

hello <password> <client> <version>

<password> must match linuxcncrsh’sconnect password, or "EMC" if no --connectpw was sup-

plied. The three arguments may not contain whitespace. If a valid password was entered the

server will respond with:

HELLO ACK <ServerName> <ServerVersion>

If an invalid password or anyother syntax error occurs then the server responds with:

HELLO NAK

get <subcommand> [<parameters>]

The get command takes one of the LinuxCNC sub-commands (described in the section Linux-

CNC Subcommands,below) and zero or more additional subcommand-speciﬁc parameters.

set <subcommand> <parameters>

The set command takes one of the LinuxCNC sub-commands (described in the section Linux-

CNC Subcommands,below) and one or more additional parameters.

quit The quit command disconnects the associated socket connection.

shutdown

The shutdown command tells LinuxCNC to shutdown and disconnect the session. This command

may only be issued if the Hello has been successfully negotiated and the connection has control of

the CNC (see enable subcommand in the LinuxCNC Subcommands section, below).

help The help command will return help information in text format overthe connection. If no parame-

ters are speciﬁed, it will itemize the available commands. If a command is speciﬁed, it will pro-

vide usage information for the speciﬁed command. Help will respond regardless of whether a

"Hello" has been successsfully negotiated.

LinuxCNC Subcommands

Subcommands for get and set are:

echo {on|off}

With get, anyon/offparameter is ignored and the current echo state is returned. With set, sets the

echo state as speciﬁed. Echo defaults to on when the connection is ﬁrst established. When echo is

on, all commands will be echoed upon receipt. This state is local to each connection.

verbose {on|off}

With get, anyon/offparameter is ignored and the current verbose state is returned. With set, sets

the verbose state as speciﬁed. When verbose mode is on, all set commands return positive

acknowledgement in the form SET <COMMAND> ACK, and text error messages will be issued

(FIXME: I don’tknowwhat this means). The verbose state is local to each connection, and starts

out OFF on newconnections.

enable {<passwd>|off}

The session’senable state indicates whether the current connection is enabled to perform control

functions. With get, anyparameter is ignored, and the current enable state is returned. With set

May 31, 2011 39

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

and a valid password matching linuxcncrsh’s--enablepw (EMCTOO if not speciﬁed), the current

connection is enabled for control functions. "OFF" may not be used as a password and disables

control functions for this connection.

conﬁg [TBD]

Unused, ignore for now.

comm_mode {ascii|binary}

With get, anyparameter is ignored and the current communications mode is returned. With set,

will set the communications mode to the speciﬁed mode. The ascii mode is the text request/reply

mode, the binary protocol is not currently designed or implemented.

comm_prot <version>

With get, anyparameter is ignored and the current protocol version used by the server is returned.

With set, sets the server to use the speciﬁed protocol version, provided it is lower than or equal to

the highest version number supported by the server implementation.

iniﬁle Not currently implemented! With get, returns the string "emc.ini". Should return the full path and

ﬁle name of the current conﬁguration iniﬁle. Setting this does nothing.

plat With get, returns the string "Linux".

ini <var> <section>

Not currently implemented, do not use! Should return the string value of <var> in section <sec-

tion> of the ini ﬁle.

debug <value>

With get, anyparameter is ignored and the current integer value of EMC_DEBUG is returned.

Note that the value of EMC_DEBUG returned is the from the UI’sini ﬁle, which may be different

than emc’sini ﬁle. With set, sends a command to the EMC to set the newdebug level, and sets the

EMC_DEBUG global here to the same value. This will makethe twovalues the same, since they

really ought to be the same.

set_wait {none|received|done}

The set_wait setting controls the wait after receiving a command. It can be "none" (return right

aw ay), "received" (after the command was sent and received), or "done" (after the command was

done). With get, anyparameter is ignored and the current set_wait setting is returned. With set,

set the set_wait setting to the speciﬁed value.

wait {received|done}

With set, force a wait for the previous command to be received, or done. This lets you wait in the

ev e nt that "set_wait none" is in effect.

set_timeout <timeout>

With set, set the timeout for commands to return to <timeout> seconds. Timeout is a real number.

If it’s<=0.0, it means wait forever. Default is 0.0, wait forever.

update {none|auto}

The update mode controls whether to return fresh or stale values for "get" requests. When the

update mode is "none" it returns stale values, when it’s"auto" it returns fresh values. Defaults to

"auto" for newconnections. Set this to "none" if you liketobeconfused.

error With get, returns the current error string, or "ok" if no error.

operator_display

With get, returns the current operator display string, or "ok" if none.

operator_text

With get, returns the current operator text string, or "ok" if none.

40 May 31, 2011

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

time With get, returns the time, in seconds, from the start of the epoch. This starting time depends on

the platform.

estop {on|off}

With get, ignores anyparameters and returns the current estop setting as "on" or "off". With set,

sets the estop as speciﬁed. Estop "on" means the machine is in the estop state and won’trun.

machine {on|off}

With get, ignores anyparameters and returns the current machine power setting as "on" or "off".

With set, sets the machine on or offasspeciﬁed.

mode {manual|auto|mdi}

With get, ignores anyparameters and returns the current machine mode. With set, sets the

machine mode as speciﬁed.

mist {on|off}

With get, ignores anyparameters and returns the current mist coolant setting. With set, sets the

mist setting as speciﬁed.

ﬂood {on|off}

With get, ignores anyparameters and returns the current ﬂood coolant setting. With set, sets the

ﬂood setting as speciﬁed.

lube {on|off}

With get, ignores anyparameters and returns the current lube pump setting. With set, sets the lube

pump setting as speciﬁed.

lube_level

With get, returns the lubricant levelsensor reading as "ok" or "low". With set, mocks you for

wishful thinking.

spindle {forward|rev erse|increase|decrease|constant|off}

With get, anyparameter is ignored and the current spindle state is returned as "forward", "reverse",

"increase", "decrease", or "off". With set, sets the spindle as speciﬁed. Note that "increase" and

"decrease" will cause a speed change in the corresponding direction until a "constant" command is

sent.

brake{on|off}

With get, anyparameter is ignored and the current brakesetting is returned. With set, the brakeis

set as speciﬁed.

tool With get, returns the id of the currently loaded tool.

tool_offset

With get, returns the currently applied tool length offset.

load_tool_table <ﬁle>

With set, loads the tool table speciﬁed by <ﬁle>.

home {0|1|2|...}

With set, homes the indicated axis.

jog_stop {0|1|2|...}

With set, stop anyin-progress jog on the speciﬁed axis.

jog {0|1|2|...} <speed>

With set, jog the speciﬁed axis at <speed>; sign of speed is direction.

jog_incr {0|1|2|...} <speed> <incr>

With set, jog the indicated axis by increment <incr> at the <speed>; sign of speed is direction.

feed_override <percent>

With get, anyparameter is ignored and the current feed override is returns (as a percentage of

May 31, 2011 41

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

commanded feed). With set, sets the feed override as speciﬁed.

spindle_override <percent>

With get, anyparameter is ignored and the current spindle override is returnd (as a percentage of

commanded speed). With set, sets the spindle override as speciﬁed.

abs_cmd_pos [{0|1|...}]

With get, returns the speciﬁed axis’ commanded position in absolute coordinates. If no axis is

speciﬁed, returns all axes’ commanded absolute position.

abs_act_pos [{0|1|...}]

With get, returns the speciﬁed axis’ actual position in absolute coordinates. If no axis is speciﬁed,

returns all axes’ actual absolute position.

rel_cmd_pos [{0|1|...}]

With get, returns the speciﬁed axis’ commanded position in relative coordinates, including tool

length offset. If no axis is speciﬁed, returns all axes’ commanded relative position.

rel_act_pos [{0|1|...}]

With get, returns the speciﬁed axis’ actual position in relative coordinates, including tool length

offset. If no axis is speciﬁed, returns all axes’ actual relative position.

joint_pos [{0|1|...}]

With get, returns the speciﬁed joint’sactual position in absolute coordinates, excluding tool length

offset. If no joint is speciﬁed, returns all joints’ actual absolute position.

pos_offset [{X|Y|Z|R|P|W}]

With get, returns the position offset associated with the world coordinate provided.

joint_limit [{0|1|...}]

With get, returns limit status of the speciﬁed joint as "ok", "minsoft", "minhard", "maxsoft", or

"maxhard". If no joint number is speciﬁed, returns the limit status of all joints.

joint_fault [{0|1|...}]

With get, returns the fault status of the speciﬁed joint as "ok" or "fault". If no joint number is

speciﬁed, returns the fault status of all joints.

joint_homed [{0|1|...}]

With get, returns the homed status of the speciﬁed joint as "homed" or "not". If no joint number is

speciﬁed, returns the homed status of all joints.

mdi <string>

With set, sends <string> as an MDI command.

task_plan_init

With set, initializes the program interpreter.

open <ﬁlename>

With set, opens the named ﬁle. The <ﬁlename> is opened by linuxcnc, so it should either be an

absolute path or a relative path starting in the linuxcnc working directory (the directory of the

active .ini ﬁle). Note that linuxcnc can only have one ﬁle open at a time, and it’suptothe UI (lin-

uxcncrsh or similar) to close anyopen ﬁle before opening a newﬁle. linuxcncrsh currently does

not support closing ﬁles, which rather limits the utility of this command.

run [<StartLine>]

With set, runs the opened program. If no StartLine is speciﬁed, runs from the beginning. If a

StartLine is speciﬁed, start line, runs from that line. A start line of -1 runs in verify mode.

pause With set, pause program execution.

resume With set, resume program execution.

abort

42 May 31, 2011

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

With set, abort program or MDI execution.

step With set, step the program one line.

programWith get, returns the name of the currently opened program, or "none".

program_line

With get, returns the currently executing line of the program.

program_status

With get, returns "idle", "running", or "paused".

program_codes

With get, returns the string for the currently active program codes.

joint_type [<joint>]

With get, returns "linear", "angular", or "custom" for the type of the speciﬁed joint (or for all joints

if none is speciﬁed).

joint_units [<joint>]

With get, returns "inch", "mm", "cm", or "deg", "rad", "grad", or "custom", for the corresponding

native units of the speciﬁed joint (or for all joints if none is speciﬁed). The type of the axis (linear

or angular) is used to resolvewhich type of units are returned. The units are obtained heuristically,

based on the EMC_AXIS_STAT ::units numerical value of user units per mm or deg. For linear

joints, something close to 0.03937 is deemed "inch", 1.000 is "mm", 0.1 is "cm", otherwise it’s

"custom". For angular joints, something close to 1.000 is deemed "deg", PI/180 is "rad", 100/90 is

"grad", otherwise it’s"custom".

program_units

Synonym for program_linear_units.

program_linear_units

With get, returns "inch", "mm", "cm", or "none", for the corresponding linear units that are active

in the program interpreter.

program_angular_units

With get, returns "deg", "rad", "grad", or "none" for the corresponding angular units that are active

in the program interpreter.

user_linear_units

With get, returns "inch", "mm", "cm", or "custom", for the corresponding native user linear units

of the LinuxCNC trajectory level. This is obtained heuristically,based on the

EMC_TRAJ_STAT ::linearUnits numerical value of user units per mm. Something close to

0.03937 is deemed "inch", 1.000 is "mm", 0.1 is "cm", otherwise it’s"custom".

user_angular_units

Returns "deg", "rad", "grad", or "custom" for the corresponding native user angular units of the

LinuxCNC trajectory level. Likewith linear units, this is obtained heuristically.

display_linear_units

With get, returns "inch", "mm", "cm", or "custom", for the linear units that are active inthe dis-

play.This is effectively the value of linearUnitConversion.

display_angular_units

With get, returns "deg", "rad", "grad", or "custom", for the angular units that are active inthe dis-

play.This is effectively the value of angularUnitConversion.

linear_unit_conversion {inch|mm|cm|auto}

With get, anyparameter is ignored and the active unit conversion is returned. With set, sets the

unit to be displayed. If it’s"auto", the units to be displayed match the program units.

angular_unit_conversion {deg|rad|grad|auto}

May 31, 2011 43

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

With get, anyparameter is ignored and the active unit conversion is returned. With set, sets the

units to be displayed. If it’s"auto", the units to be displayed match the program units.

probe_clear

With set, clear the probe tripped ﬂag.

probe_tripped

With get, return the probe state - has the probe tripped since the last clear?

probe_value

With get, return the current value of the probe signal.

probe With set, move tow ard a certain location. If the probe is tripped on the way stop motion, record the

position and raise the probe tripped ﬂag.

teleop_enable [on|off]

With get, anyparameter is ignored and the current teleop mode is returned. With set, sets the

teleop mode as speciﬁed.

kinematics_type

With get, returns the type of kinematics functions used (identity=1, serial=2, parallel=3, cus-

tom=4).

override_limits {on|off}

With get, anyparameter is ignored and the override_limits setting is returned. With set, the over-

ride_limits parameter is set as speciﬁed. If override_limits is on, disables end of travelhardware

limits to allowjogging offofalimit. If parameters is off, then hardware limits are enabled.

optional_stop {0|1}

With get, anyparameter is ignored and the current "optional stop on M1" setting is returned. With

set, the setting is set as speciﬁed.

Example Session

This section shows an example session. Bold items are typed by you, non-bold is machine output.

The user connects to linuxcncrsh, handshakes with the server (hello), enables machine commanding from

this session (set enable), brings the machine out of estop (set estop off) and turns it on (set machine on),

homes all the axes, switches the machine to mdi mode, sends an MDI g-code command, then disconnects

and shuts down LinuxCNC.

>telnet localhost 5007

Trying 127.0.0.1...

Connected to 127.0.0.1

Escape character is ’ˆ]’.

hello EMC user-typing-at-telnet 1.0

HELLO ACK EMCNETSVR 1.1

set enable EMCTOO

set mode manual

set estop off

set machine on

set home 0

set home 1

set home 2

44 May 31, 2011

linuxcncrsh(1) The Enhanced Machine Controller linuxcncrsh(1)

set mode mdi

set mdi g0x1

shutdown

Connection closed by foreign host.

May 31, 2011 45

milltask(1) The Enhanced Machine Controller milltask(1)

NAME milltask − Userspace task controller for LinuxCNC

DESCRIPTION

milltask is an internal process of LinuxCNC. It is generally not invokeddirectly.Itcreates the pins shown

as owned by the "inihal" component, which allowruntime modiﬁcation of certain values from the iniﬁle.

PINS

Per-axis pins

ini.#.backlash

Allows adjustment of [AXIS_#]BACKLASH

ini.#.max_acceleration

Allows adjustment of [AXIS_#]MAX_ACCELERATION

ini.#.max_velocity

Allows adjustment of [AXIS_#]MAX_VELOCITY

ini.#.max_limit

Allows adjustment of [AXIS_#]MAX_LIMIT

ini.#.min_limit

Allows adjustment of [AXIS_#]MIN_LIMIT

ini.#.ferror

Allows adjustment of [AXIS_#]FERROR

ini.#.min_ferror

Allows adjustment of [AXIS_#]MIN_FERROR

Global pins

ini.traj_default_acceleration

Allows adjustment of [TRAJ]DEFAULT_ACCELERATION

ini.traj_default_velocity

Allows adjustment of [TRAJ]DEFAULT_VELOCITY

ini.traj_max_acceleration

Allows adjustment of [TRAJ]MAX_ACCELERATION

ini.traj_max_velocity

Allows adjustment of [TRAJ]MAX_VELOCITY

BUGS These pins cannot be linked or set in a halﬁle speciﬁed by [HAL]HALFILE.InGUIs that support the fea-

ture, theycan be set by the [HAL]POSTGUI_HALFILE.

The iniﬁle is not automatically updated with these values.

46 September 30, 2014

PYVCP(1) The Enhanced Machine Controller PYVCP(1)

NAME pyvcp − Virtual Control Panel for LinuxCNC

SYNOPSIS

pyvcp [-g WxH+X+Y][-c component-name]myﬁle.xml

OPTIONS

-g WxH+X+Y

This sets the initial geometry of the root window. Use ’WxH’ for just size, ’+X+Y’ for just posi-

tion, 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 speciﬁed, the

basename of the xml ﬁle is used.

SEE ALSO

Python Virtual Control Panel in the LinuxCNC documentation for a description of the xml syntax, along

with examples

LinuxCNC Documentation 2007-04-01 47

SHUTTLEXPRESS(1) HAL User’sManual SHUTTLEXPRESS(1)

NAME shuttlexpress − control HAL pins with the ShuttleXpress device made by Contour Design

SYNOPSIS

loadusr shuttlexpress [DEVICE ...]

DESCRIPTION

shuttlexpress is a userspace HAL component that interfaces Contour Design’sShuttleXpress device with

LinuxCNC’sHAL. The ShuttleXpress has ﬁvemomentary buttons, a 10 counts/revolution jog wheel with

detents, and a 15-position spring-loaded outer wheel that returns to center when released.

If it is started without command-line arguments, it will probe all /dev/hidraw* device ﬁles for ShuttleXpress

devices, and use all devices found. If it is started with command-line arguments, only will only probe the

devices speciﬁed.

UDEV The shuttlexpress module needs read permission on the /dev/hidraw* device ﬁles. This can be accom-

plished by adding a ﬁle /etc/udev/rules.d/99-shuttlexpress.rules,with the following contents:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0020", MODE="0444"

Awarning about the Jog Wheel

The ShuttleXpress device has an internal 8-bit counter for the current jog-wheel position. The shuttlexpress

drivercan not knowthis value until the ShuttleXpress device sends its ﬁrst event. When the ﬁrst event

comes into the driver, the driveruses the device’sreported jog-wheel position to initialize counts to 0.

This means that if the ﬁrst event is generated by a jog-wheel move,that ﬁrst move will be lost.

Anyuser interaction with the ShuttleXpress device will generate an event, informing the driverofthe jog-

wheel position. So if you (for example) push one of the buttons at startup, the jog-wheel will work ﬁne and

notice the ﬁrst click.

Pins (bit out) shuttlexpress.0.button-0

(bit out) shuttlexpress.0.button-0-not

(bit out) shuttlexpress.0.button-1

(bit out) shuttlexpress.0.button-1-not

(bit out) shuttlexpress.0.button-2

(bit out) shuttlexpress.0.button-2-not

(bit out) shuttlexpress.0.button-3

(bit out) shuttlexpress.0.button-3-not

(bit out) shuttlexpress.0.button-4

(bit out) shuttlexpress.0.button-4-not

The ﬁvebuttons around the outside, starting with the

counter-clockwise-most one.

(s32 out) shuttlexpress.0.counts

Accumulated counts from the jog wheel (the inner wheel).

48 2011-01-13 LinuxCNC Documentation

SHUTTLEXPRESS(1) HAL User’sManual SHUTTLEXPRESS(1)

(s32 out) shuttlexpress.0.spring-wheel-s32

The current deﬂection of the spring-wheel (the outer wheel).

It’s0atrest, and ranges from -7 at the counter-clockwise

extreme to +7 at the clockwise extreme.

(ﬂoat out) shuttlexpress.0.spring-wheel-f

The current deﬂection of the spring-wheel (the outer wheel).

It’s0atrest, -1 at the counter-clockwise extreme, and

+1 at the clockwise extreme. (The ShuttleXpress device reports the

spring-wheel position quantized from -7 to +7, so this pin reports

only 15 discrete values in its range.)

LinuxCNC Documentation 2011-01-13 49

vfdb_vfd(1) LinuxCNC Documentation vfdb_vfd(1)

NAME vfdb_vfd -HAL userspace component for Delta VFD-B Variable FrequencyDrives

SYNOPSIS

vfdb_vfd [OPTIONS]

DESCRIPTION

This manual page explains the vfdb_vfd component. This component reads and writes to the VFD-B

device via a Modbus connection.

vfdb_vfd is for use with LinuxCNC.

QUICK START

The VFD-B ships in a conﬁguration that can not talk to this driver. The VFD-B must be reconﬁgured via

the face plate by the integrator before it will work. This section givesabrief description of what changes

need to be made, consult your Delta VFD-B manual for more details.

Switch the VFD-B to Modbus RTU frame format:

Switch parameter 09-04 from the factory default of 0 (Ascii framing) to 3, 4, or 5 (RTU

framing). The setting you choose will determine several serial parameters in addition to

the Modbus framing protocol.

Set the frequencycontrol source to be Modbus, not the keypad:

Switch parameter 02-00 from factory default of 00 (keypad control) to 5 (control from

RS-485).

Set the run/stop control source to be Modbus, not the keypad:

Switch parameter 02-01 from the factory default of 0 (control from keypad) to 3 (control

from Modbus, with Stop enabled on the keypad).

OPTIONS

-n --name <halname>

set the HAL component name

-d --debug

Turn on debugging messages. Also toggled by sending a USR1 signal to the vfdb_vfd process.

-m --modbus-debug

Turn on Modbus debugging messages. This will cause all Modbus messages to be printed in hex

on the terminal. Also toggled by sending a USR2 signal to the vfdb_vfd process.

-I --ini <iniﬁlename>

takeconﬁguration from this ini ﬁle. Defaults to environment variable INI_FILE_NAME. Most

vfdb_vfd conﬁguration comes from the ini ﬁle, not from command-line arguments.

-S --section <section name>

takeconﬁguration from this section in the ini ﬁle. Defaults to ’VFD-B’.

-r --report-device

report device propertiers on console at startup

INI CONFIG VARIABLES

DEBUGSet to a non-zero value to enable general debug output from the VFD-B driver. Optional.

MODBUS_DEBUG

Set to a non-zero value to enable modbus debug output from the VFD-B driver. Optional.

50 September 19, 2009 VFD-B VFD

vfdb_vfd(1) LinuxCNC Documentation vfdb_vfd(1)

DEVICE

Serial port device ﬁle to use for Modbus communication with the VFD-B. Defaults to

’/dev/ttyS0’.

BAUD Modbus baud rate. Defaults to 19200.

BITS Modbus data bits. Defaults to 8.

PARITYModbus parity.Defaults to Even. Accepts ’Even’, ’Odd’, or ’None’.

STOPBITS

Modbus stop bits. Defaults to 1.

TARGET

Modbus target number of the VFD-B to speak to. Defaults to 1.

POLLCYCLES

Only read the less important variables from the VFD-B once in this manypoll cycles. Defaults to

10.

RECONNECT_DELAY

If the connection to the VFD-B is broken, wait this manyseconds before reconnecting. Defaults

to 1.

MOTOR_HZ, MOTOR_RPM

The frequencyofthe motor (in Hz) and the corresponding speed of the motor (in RPM). This

information is provided by the motor manufacturer,and is generally printed on the motor’sname

plate.

PINS <name>.at-speed (bit, out)

True when drive isatcommanded speed (see speed-tolerance below)

<name>.enable (bit, in)

Enable the VFD. If False, all operating parameters are still read but control is released and panel

control is enabled (subject to VFD setup).

<name>.frequency-command (ﬂoat, out)

Current target frequencyinHZasset through speed-command (which is in RPM), from the VFD.

<name>.frequency-out (ﬂoat, out)

Current output frequencyofthe VFD.

<name>.inverter-load-percentage (ﬂoat, out)

Current load report from VFD.

<name>.is-e-stopped (bit, out)

The VFD is in emergencystop status (blinking "E" on panel).

<name>.is-stopped (bit, out)

True when the VFD reports 0 Hz output.

<name>.jog-mode (bit, in)

1for ON and 0 for OFF,enables the VFD-B ’jog mode’. Speed control is disabled. This might be

useful for spindle orientation.

<name>.max-rpm (ﬂoat, out)

Actual RPM limit based on maximum frequencythe VFD may generate, and the motors name-

plate values. For instance, if nameplate-HZ is 50, and nameplate-RPM is 1410, but the VFD may

generate up to 80Hz, then max-rpm would read as 2256 (80*1410/50). The frequencylimit is read

from the VFD at startup. To increase the upper frequencylimit, the UL and FH parameters must

be changed on the panel. See the VFD-B manual for instructions howtoset the maximum fre-

quency.

VFD-B VFD September 19, 2009 51

vfdb_vfd(1) LinuxCNC Documentation vfdb_vfd(1)

<name>.modbus-ok (bit, out)

True when the Modbus session is successfully established and the last 10 transactions returned

without error.

<name>.motor-RPM (ﬂoat, out)

Estimated current RPM value, from the VFD.

<name>.motor-RPS (ﬂoat, out)

Estimated current RPS value, from the VFD.

<name>.output-voltage (ﬂoat, out)

From the VFD.

<name>.output-current (ﬂoat, out)

From the VFD.

<name>.speed-command (ﬂoat, 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.

<name>.spindle-on (bit, in)

1for ON and 0 for OFF sent to VFD, only on when running.

<name>.max-speed (bit, in)

Ignore the loop-time paramater and run Modbus at maximum speed, at the expense of higher CPU

usage. Suggested use during spindle positioning.

<name>.status (s32, out)

Drive Status of the VFD (see the VFD manual). A bitmap.

<name>.error-count (s32, out)

Total number of transactions returning a Modbus error.

<name>.error-code (s32, out)

Most recent Error Code from VFD.

<name>.frequency-limit (ﬂoat, out)

Upper limit read from VFD setup.

PARAMETERS

<name>.loop-time (ﬂoat, RW)

Howoften the Modbus is polled (default interval 0.1 seconds).

<name>.nameplate-HZ (ﬂoat, RW)

Nameplate Hz of motor (default 50). Used to calculate target frequency(together with nameplate-

RPM )for a target RPM value as givenbyspeed-command.

<name>.nameplate-RPM (ﬂoat, RW)

Nameplate RPM of motor (default 1410)

<name>.rpm-limit (ﬂoat, RW)

Do-not-exceed soft limit for motor RPM (defaults to nameplate-RPM ).

<name>.tolerance (ﬂoat, RW)

Speed tolerance (default 0.01) for determining wether spindle is at speed (0.01 meaning: output

frequencyiswithin 1% of target frequency).

USAGEThe vfdb_vfd drivertakes precedence overpanel control while it is enabled (see .enable pin), effectively

disabling the panel. Clearing the .enable pin re-enables the panel. Pins and parameters can still be set, but

will not be written to the VFD untile the .enable pin is set. Operating parameters are still read while bus

control is disabled.

52 September 19, 2009 VFD-B VFD

vfdb_vfd(1) LinuxCNC Documentation vfdb_vfd(1)

Exiting the vfdb_vfd driverinacontrolled way will release the VFD from the bus and restore panel control.

See the LinuxCNC Integrators Manual for more information. For a detailed register description of the Delta

VFD-B, see the VFD manual.

AUTHOR

Yishin Li; based on vfd11_vfd by Michael Haberler.

LICENSE

GPL

VFD-B VFD September 19, 2009 53

vfs11_vfd(1) LinuxCNC Documentation vfs11_vfd(1)

NAME vfs11_vfd -HAL userspace component for Toshiba-Schneider VF-S11 Variable FrequencyDrives

SYNOPSIS

vfs11_vfd [OPTIONS]

DESCRIPTION

This manual page explains the vfs11_vfd component. This component reads and writes to the vfs11 via a

Modbus connection.

vfs11_vfd is for use with LinuxCNC.

OPTIONS

-n --name <halname>

set the HAL component name

-d --debug

Turn on debugging messages. Also toggled by sending a USR1 signal to the vfs11_vfd process.

-m --modbus-debug

Turn on Modbus debugging messages. This will cause all Modbus messages to be printed in hex

on the terminal. Also toggled by sending a USR2 signal to the vfs11_vfd process.

-I --ini <iniﬁlename>

takeconﬁguration from this ini ﬁle. Defaults to environment variable INI_FILE_NAME.

-S --section <section name>

takeconﬁguration from this section in the ini ﬁle. Defaults to ’VFS11’.

-r --report-device

report device propertiers on console at startup

PINS <name>.acceleration-pattern(bit, in)

when true, set acceleration and deceleration times as deﬁned in registers F500 and F501

respecitvely.Used in PID loops to choose shorter ramp times to avoid oscillation.

<name>.alarm-code (s32, out)

non-zero if drive isinalarmed state. Bitmap describing alarm information (see register FC91

description). Use err-reset (see below) to clear the alarm.

<name>.at-speed (bit, out)

when drive isatcommanded speed (see speed-tolerance below)

<name>.current-load-percentage (ﬂoat, out)

reported from the VFD

<name>.dc-brake(bit, in)

engage the DC brake. Also turns offspindle-on.

<name>.enable (bit, in)

enable the VFD. If false, all operating parameters are still read but control is released and panel

control is enabled (subject to VFD setup).

<name>.err-reset (bit, in)

reset errors (alarms a.k.a Trip and e-stop status). Resetting the VFD may cause a 2-second delay

until it’srebooted and Modbus is up again.

<name>.estop (bit, in)

put the VFD into emergency-stopped status. No operation possible until cleared with err-reset or

powercycling.

54 September 19, 2009 vfs11 VFD

vfs11_vfd(1) LinuxCNC Documentation vfs11_vfd(1)

<name>.frequency-command (ﬂoat, out)

current target frequencyinHZasset through speed-command (which is in RPM), from the VFD

<name>.frequency-out (ﬂoat, out)

current output frequencyofthe VFD

<name>.inverter-load-percentage (ﬂoat, out)

current load report from VFD

<name>.is-e-stopped (bit, out)

the VFD is in emergencystop status (blinking "E" on panel). Use err-reset to reboot the VFD and

clear the e-stop status.

<name>.is-stopped (bit, out)

true when the VFD reports 0 Hz output

<name>.jog-mode (bit, in)

1for ON and 0 for OFF,enables the VF-S11 ’jog mode’. Speed control is disabled, and the output

frequencyisdetermined by register F262 (preset to 5Hz). This might be useful for spindle orienta-

tion.

<name>.max-rpm (ﬂoat, R)

actual RPM limit based on maximum frequencythe VFD may generate, and the motors nameplate

values. For instance, if nameplate-HZ is 50, and nameplate-RPM_ is 1410, but the VFD may gen-

erate up to 80Hz, then max-rpm would read as 2256 (80*1410/50). The frequencylimit is read

from the VFD at startup. To increase the upper frequencylimit, the UL and FH parameters must

be changed on the panel. See the VF-S11 manual for instructions howtoset the maximum fre-

quency.

<name>.modbus-ok (bit, out)

true when the Modbus session is successfully established and the last 10 transactions returned

without error.

<name>.motor-RPM (ﬂoat, out)

estimated current RPM value, from the VFD

<name>.output-current-percentage (ﬂoat, out)

from the VFD

<name>.output-voltage-percentage (ﬂoat, out)

from the VFD

<name>.output-voltage (ﬂoat, out)

from the VFD

<name>.speed-command (ﬂoat, 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

<name>.spindle-fwd (bit, in)

1for FWD and 0 for REV,sent to VFD

<name>.spindle-on (bit, in)

1for ON and 0 for OFF sent to VFD, only on when running

<name>.spindle-rev (bit, in)

1for ON and 0 for OFF,only on when running

<name>.max-speed (bit, in)

ignore the loop-time paramater and run Modbus at maximum speed, at the expense of higher CPU

usage. Suggested use during spindle positioning.

vfs11 VFD September 19, 2009 55

vfs11_vfd(1) LinuxCNC Documentation vfs11_vfd(1)

<name>.status (s32, out)

Drive Status of the VFD (see the TOSVERTVF-S11 Communications Function Instruction Man-

ual, register FD01). A bitmap.

<name>.trip-code (s32, out)

trip code if VF-S11 is in tripped state.

<name>.error-count (s32, RW)

total number of transactions returning a Modbus error

PARAMETERS

<name>.frequency-limit (ﬂoat, RO)

upper limit read from VFD setup.

<name>.loop-time (ﬂoat, RW)

howoften the Modbus is polled (default interval 0.1 seconds)

<name>.nameplate-HZ (ﬂoat, RW)

Nameplate Hz of motor (default 50). Used to calculate target frequency(together with nameplate-

RPM )for a target RPM value as givenbyspeed-command.

<name>.nameplate-RPM (ﬂoat, RW)

Nameplate RPM of motor (default 1410)

<name>.rpm-limit (ﬂoat, RW)

do-not-exceed soft limit for motor RPM (defaults to nameplate-RPM ).

<name>.tolerance (ﬂoat, RW)

speed tolerance (default 0.01) for determining wether spindle is at speed (0.01 meaning: output

frequencyiswithin 1% of target frequency)

USAGEThe vfs11_vfd drivertakes precedence overpanel control while it is enabled (see .enable pin), effectively

disabling the panel. Clearing the .enable pin re-enableds the panel. Pins and parameters can still be set, but

will not be written to the VFD untile the .enable pin is set. Operating parameters are still read while bus

control is disabled.

Exiting the vfs11_vfd driverinacontrolled will release the VFD from the bus and restore panel control.

See the LinuxCNC Integrators Manual for more information. For a detailed register description of the

Toshiba VFD’s, see the "TOSVERTVF-S11 Communications Function Instruction Manual" (Toshiba doc-

ument number E6581222) and the "TOSVERTVF-S11 Instruction manual" (Toshiba document number

E6581158).

AUTHOR

Michael Haberler; based on gs2_vfd by Steve Padnos and John Thornton.

LICENSE

GPL

56 September 19, 2009 vfs11 VFD

intro(3hal) HAL intro(3hal)

NAME hal − Introduction to the HAL API

DESCRIPTION

HAL stands for Hardware Abstraction Layer,and is used by LinuxCNC to transfer realtime data to and

from I/O devices and other low-levelmodules.

hal.h deﬁnes the API and data structures used by the HAL. This ﬁle is included in both realtime and non-

realtime HAL components. HAL uses the RTPAI real time interface, and the #deﬁne symbols RTAPI and

ULAPI are used to distinguish between realtime and non-realtime code. The API deﬁned in this ﬁle is

implemented in hal_lib.c and can be compiled for linking to either realtime or user space HAL components.

The HAL is a very modular approach to the lowlev e lparts of a motion control system. The goal of the

HAL is to allowasystems integrator to connect a group of software components together to meet whatever

I/O requirements he (or she) needs. This includes realtime and non-realtime I/O, as well as basic motor

control up to and including a PID position loop. What these functions have incommon is that theyall

process signals. In general, a signal is a data item that is updated at regular intervals. For example, a PID

loop gets position command and feedback signals, and produces a velocity command signal.

HAL is based on the approach used to design electronic circuits. In electronics, off-the-shelf components

likeintegrated circuits are placed on a circuit board and their pins are interconnected to build whatever

overall function is needed. The individual components may be as simple as an op-amp, or as complexasa

digital signal processor.Each component can be individually tested, to makesure it works as designed.

After the components are placed in a larger circuit, the signals connecting them can still be monitored for

testing and troubleshooting.

Likeelectronic components, HAL components have pins, and the pins can be interconnected by signals.

In the HAL, a signal contains the actual data value that passes from one pin to another.When a signal is

created, space is allocated for the data value. A pin on the other hand, is a pointer,not a data value. When

apin is connected to a signal, the pin’spointer is set to point at the signal’sdata value. This allows the

component to access the signal with very little run-time overhead. (If apin is not linked to anysignal, the

pointer points to a dummy location, so the realtime code doesn’thav e to deal with null pointers or treat

unlinked variables as a special case in anyway.)

There are three approaches to writing a HAL component. Those that do not require hard realtime perfor-

mance can be written as a single user mode process. Components that need hard realtime performance but

have simple conﬁguration and init requirements can be done as a single kernel module, using either pre-

deﬁned init info, or insmod-time parameters. Finally,complexcomponents may use both a kernel module

for the realtime part, and a user space process to handle ini ﬁle access, user interface (possibly including

GUI features), and other details.

HAL uses the RTAPI/ULAPI interface. If RTAPI is #deﬁned hal_lib.c would generate a kernel module

hal_lib.o that is insmoded and provides the functions for all kernel module based components. The same

source ﬁle compiled with the ULAPI #deﬁne would makeauser space hal_lib.o that is staticlly linked to

user space code to makeuser space executables. The variable lists and link information are stored in a

block of shared memory and protected with mutexes, so that kernel modules and anyofsev eral user mode

programs can access the data.

REALTIME CONSIDERATIONS

Foranexplanation of realtime considerations, see intro(3rtapi).

LinuxCNC Documentation 2006-10-12 57

intro(3hal) HAL intro(3hal)

HAL STATUS CODES

Except as noted in speciﬁc manual pages, HAL returns negative errno values for errors, and nonnegative

values for success.

SEE ALSO

intro(3rtapi)

58 2006-10-12 LinuxCNC Documentation

hal_add_funct_to_thread(3hal) HAL hal_add_funct_to_thread(3hal)

NAME hal_add_funct_to_thread − cause a function to be executed at regular intervals

SYNTAX

int hal_add_funct_to_thread(const char *funct_name,const char *thread_name,

int position)

int hal_del_funct_from_thread(const char *funct_name,const char *thread_name)

ARGUMENTS

funct_name

The name of the function

thread_name

The name of the thread

position

The desired location within the thread. This determines when the function will run, in relation to

other functions in the thread. Apositive number indicates the desired location as measured from

the beginning of the thread, and a negative ismeasured from the end. So +1 means this function

will become the ﬁrst one to run, +5 means it will be the ﬁfth one to run, -2 means it will be next to

last, and -1 means it will be last. Zero is illegal.

DESCRIPTION

hal_add_funct_to_thread adds a function exported by a realtime HAL component to a realtime thread.

This determines howoften and in what order functions are executed.

hal_del_funct_from_thread removesafunction from a thread.

RETURN VALUE

Returns a HAL status code.

REALTIME CONSIDERATIONS

Call only from realtime init code, not from user space or realtime code.

SEE ALSO

hal_thread_new(3hal),hal_export_funct(3hal)

LinuxCNC Documentation 2006-10-12 59

hal_create_thread(3hal) HAL hal_create_thread(3hal)

NAME hal_create_thread − Create a HAL thread

SYNTAX

int hal_create_thread(const char *name,unsigned long period,int uses_fp)

int hal_thread_delete(const char *name)

ARGUMENTS

name The name of the thread

period The interval, in nanoseconds, between iterations of the thread

uses_fp Must be nonzero if a function which uses ﬂoating-point will be attached to this thread.

DESCRIPTION

hal_create_thread establishes a realtime thread that will execute one or more HAL functions periodically.

All thread periods are rounded to integer multiples of the hardware timer period, and the timer period is

based on the ﬁrst thread created. Threads must be created in order,from the fastest to the slowest. HAL

assigns decreasing priorities to threads that are created later,socreating them from fastest to slowest results

in rate monotonic priority scheduling.

hal_delete_thread deletes a previously created thread.

REALTIME CONSIDERATIONS

Call only from realtime init code, not from user space or realtime code.

RETURN VALUE

Returns a HAL status code.

SEE ALSO

hal_export_funct(3hal)

60 2006-10-12 LinuxCNC Documentation

hal_exit(3hal) HAL hal_exit(3hal)

NAME hal_exit − Shut down HAL

SYNTAX

int hal_exit(int comp_id)

ARGUMENTS

comp_id

AHAL component identiﬁer returned by an earlier call to hal_init.

DESCRIPTION

hal_exit shuts down and cleans up HAL and RTAPI. It must be called prior to exit by anymodule that

called hal_init.

REALTIME CONSIDERATIONS

Call only from within user or init/cleanup code, not from realtime tasks.

RETURN VALUE

Returns a HAL status code.

LinuxCNC Documentation 2006-10-12 61

hal_export_funct(3hal) HAL hal_export_funct(3hal)

NAME hal_export_funct − create a realtime function callable from a thread

SYNTAX

typedef void(*hal_funct_t)(void * arg,long period)

int hal_export_funct(const char *name,hal_funct_t funct,void *arg,int uses_fp,int reentrant,int comp_id)

ARGUMENTS

name The name of the function.

funct The pointer to the function

arg The argument to be passed as the ﬁrst parameter of funct

uses_fp Nonzero if the function uses ﬂoating-point operations, including assignment of ﬂoating point val-

ues with "=".

reentrant

If reentrant is non-zero, the function may be preempted and called again before the ﬁrst call com-

pletes. Otherwise, it may only be added to one thread.

comp_id

AHAL component identiﬁer returned by an earlier call to hal_init.

DESCRIPTION

hal_export_funct makes a realtime function provided by a component available to the system. Asubse-

quent call to hal_add_funct_to_thread can be used to schedule the execution of the function as needed by

the system.

When this function is placed on a HAL thread, and HAL threads are started, funct is called repeatedly with

twoarguments: void *arg is the same value that was giventohal_export_funct,and long period is the

interval between calls in nanoseconds.

Each call to the function should do a small amount of work and return.

RETURN VALUE

Returns a HAL status code.

SEE ALSO

hal_create_thread(3hal),hal_add_funct_to_thread(3hal)

62 2006-10-12 LinuxCNC Documentation

hal_init(3hal) HAL hal_init(3hal)

NAME hal_init − Sets up HAL and RTAPI

SYNTAX

int hal_init(const char *modname)

ARGUMENTS

modname

The name of this hal module

DESCRIPTION

hal_init sets up HAL and RTAPI. It must be called by anymodule that intends to use the API, before any

other RTAPI calls.

modname can optionally point to a string that identiﬁes the module. The string may be no longer than

RTAPI_NAME_LEN characters. If modname is NULL,the system will assign a name.

REALTIME CONSIDERATIONS

Call only from within user or init/cleanup code, not from relatime tasks.

RETURN VALUE

On success, returns a positive integer module ID, which is used for subsequent calls to hal and rtapi APIs.

On failure, returns a HAL error code.

LinuxCNC Documentation 2006-10-12 63

hal_malloc(3hal) HAL hal_malloc(3hal)

NAME hal_malloc − Allocate space in the HAL shared memory area

SYNTAX

void *hal_malloc(long int size)

ARGUMENTS

size Givesthe size, in bytes, of the block

DESCRIPTION

hal_malloc allocates a block of memory from the main HAL shared memory area. It should be used by all

components to allocate memory for HAL pins and parameters. It allocates ‘size’ bytes, and returns a

pointer to the allocated space, or NULL (0) on error.The returned pointer will be properly aligned for any

type HAL supports. Acomponent should allocate during initialization all the memory it needs.

The allocator is very simple, and there is no ‘free’. The entire HAL shared memory area is freed when the

last component calls hal_exit.This means that if you continuously install and remove one component

while other components are present, you eventually will ﬁll up the shared memory and an install will fail.

Removing all components completely clears memory and you start fresh.

RETURN VALUE

Apointer to the allocated space, which is properly aligned for anyvariable HAL supports. Returns NULL

on error.

64 2006-10-12 LinuxCNC Documentation

hal_param_new(3hal) HAL hal_param_new(3hal)

NAME hal_param_new−Create a HAL parameter

SYNTAX

int hal_param_bit_new(const char *name,hal_param_dir_t dir,hal_bit_t * data_addr,int

comp_id)

int hal_param_ﬂoat_new(const char *name,hal_param_dir_t dir,hal_ﬂoat_t * data_addr,int

comp_id)

int hal_param_u32_new(const char *name,hal_param_dir_t dir,hal_u32_t * data_addr,int

comp_id)

int hal_param_s32_new(const char *name,hal_param_dir_t dir,hal_s32_t * data_addr,int

comp_id)

int hal_param_bit_newf(hal_param_dir_t dir,hal_bit_t * data_addr,int comp_id,const char *fmt,

...)

int hal_param_ﬂoat_newf(hal_param_dir_t dir,hal_ﬂoat_t * data_addr,int comp_id,const char

*fmt,...)

int hal_param_u32_newf(hal_param_dir_t dir,hal_u32_t * data_addr,int comp_id,const char

*fmt,...)

int hal_param_s32_newf(hal_param_dir_t dir,hal_s32_t * data_addr,int comp_id,const char

*fmt,...)

int hal_param_new(const char *name,hal_type_t type,hal_in_dir_t dir,void *data_addr,int

comp_id)

ARGUMENTS

name The name to give tothe created parameter

dir The direction of the parameter,from the viewpoint of the component. It may be one of HAL_RO,

or HAL_RW Acomponent may assign a value to anyparameter,but other programs (such as hal-

cmd) may only assign a value to a parameter that is HAL_RW.

data_addr

The address of the data, which must lie within memory allocated by hal_malloc.

LinuxCNC Documentation 2006-10-12 65

hal_param_new(3hal) HAL hal_param_new(3hal)

comp_id

AHAL component identiﬁer returned by an earlier call to hal_init.

fmt, ... Aprintf-style format string and arguments

type The type of the parameter,asspeciﬁed in hal_type_t(3hal).

DESCRIPTION

The hal_param_new family of functions create a new param object.

There are functions for each of the data types that the HAL supports. Pins may only be linked to signals of

the same type.

RETURN VALUE

Returns a HAL status code.

SEE ALSO

hal_type_t(3hal)

66 2006-10-12 LinuxCNC Documentation

parport(3hal) HAL parport(3hal)

NAME hal_parport − portable access to PC-style parallel ports

SYNTAX

#include "hal_parport.h"

int hal_parport_get(int comp_id,hal_parport_t *port,unsigned short base,unsigned short base_hi,

unsigned int modes)

void hal_parport_release(hal_parport_t *port)

ARGUMENTS

comp_id

AHAL component identiﬁer returned by an earlier call to hal_init.

port Apointer to a hal_parport_t structure

base The base address of the port (if port >= 16) or the linux port number of the port (if port < 16)

base_hi

The "high" address of the port (location of the ECP registers), 0 to use a probed high address, or -1

to disable the high address

modes Advise the driverofthe desired port modes, from <linux/parport.h>. If a linux-detected port does

not provide the requested modes, a warning is printed with rtapi_print_msg. This does not make

the port request fail, because unfortunately,manysystems that have working EPP parports are not

detected as such by Linux.

DESCRIPTION

hal_parport_get allocates a parallel port for exclusive use of the named hal component. The port must be

released with hal_parport_release before the component exits with hal_exit.

HIGH ADDRESS PROBING

If the port is a parallel port known to Linux, and Linux detected a high I/O address, this value is used. Oth-

erwise, if base+0x400 is not registered to anydevice, it is used. Otherwise, no address is used. If no high

address is detected, port->base_hi is 0.

PARPORTSTRUCTURE

typedef struct

{unsigned short base;

unsigned short base_hi;

.... // and further unspeciﬁed ﬁelds

}hal_parport_t;

RETURN VALUE

hal_parport_get returns a HAL status code. On success, port is ﬁlled out with information about the allo-

cated port. On failure, the contents of port are undeﬁned except that it is safe (but not required) to pass this

port to hal_parport_release.

hal_parport_release does not return a value. It always succeeds.

LinuxCNC Documentation 2006-10-12 67

hal_pin_new(3hal) HAL hal_pin_new(3hal)

NAME hal_pin_new−Create a HAL pin

SYNTAX

int hal_pin_bit_new(const char *name,hal_pin_dir_t dir,hal_bit_t ** data_ptr_addr,int

comp_id)

int hal_pin_ﬂoat_new(const char *name,hal_pin_dir_t dir,hal_ﬂoat_t ** data_ptr_addr,int

comp_id)

int hal_pin_u32_new(const char *name,hal_pin_dir_t dir,hal_u32_t ** data_ptr_addr,int

comp_id)

int hal_pin_s32_new(const char *name,hal_pin_dir_t dir,hal_s32_t ** data_ptr_addr,int

comp_id)

int hal_pin_bit_newf(hal_pin_dir_t dir,hal_bit_t ** data_ptr_addr,int comp_id,const char *fmt,

...)

int hal_pin_ﬂoat_newf(hal_pin_dir_t dir,hal_ﬂoat_t ** data_ptr_addr,int comp_id,const char

*fmt,...)

int hal_pin_u32_newf(hal_pin_dir_t dir,hal_u32_t ** data_ptr_addr,int comp_id,const char

*fmt,...)

int hal_pin_s32_newf(hal_pin_dir_t dir,hal_s32_t ** data_ptr_addr,int comp_id,const char

*fmt,...)

int hal_pin_new(const char *name,hal_type_t type,hal_in_dir_t dir,void **data_ptr_addr,int

comp_id)

ARGUMENTS

name The name of the pin

dir

The direction of the pin, from the viewpoint of the component. It may be one of HAL_IN,

HAL_OUT,orHAL_IO.Any number of HAL_IN or HAL_IO pins may be connected to the

same signal, but at most one HAL_OUT pin is permitted. Acomponent may assign a value to a

pin that is HAL_OUT or HAL_IO,but may not assign a value to a pin that is HAL_IN.

68 2006-10-12 LinuxCNC Documentation

hal_pin_new(3hal) HAL hal_pin_new(3hal)

data_ptr_addr

The address of the pointer-to-data, which must lie within memory allocated by hal_malloc.

comp_id

AHAL component identiﬁer returned by an earlier call to hal_init.

fmt,

Aprintf-style format string and arguments

type

The type of the param, as speciﬁed in hal_type_t(3hal).

DESCRIPTION

The hal_pin_new family of functions create a new pin object. Once apin has been created, it can be linked

to a signal object using hal_link.Apin contains a pointer,and the component that owns the pin can deref-

erence the pointer to access whateversignal is linked to the pin. (If no signal is linked, it points to a

dummy signal.)

There are functions for each of the data types that the HAL supports. Pins may only be linked to signals of

the same type.

RETURN VALUE

Returns a HAL status code.

SEE ALSO

hal_type_t(3hal),hal_link(3hal)

LinuxCNC Documentation 2006-10-12 69

funct(3hal) HAL funct(3hal)

NAME hal_ready − indicates that this component is ready

SYNTAX

hal_ready(int comp_id)

ARGUMENTS

comp_id

AHAL component identiﬁer returned by an earlier call to hal_init.

DESCRIPTION

hal_ready indicates that this component is ready (has created all its pins, parameters, and functions). This

must be called in anyrealtime HAL component before its rtapi_app_init exits, and in anyuserspace com-

ponent before it enters its main loop.

RETURN VALUE

Returns a HAL status code.

70 2006-10-12 LinuxCNC Documentation

hal_set_constructor(3hal) HAL hal_set_constructor(3hal)

NAME hal_set_constructor − Set the constructor function for this component

SYNTAX

typedef int (*hal_constructor_t)(const char *preﬁx, const char *arg); int hal_set_constructor(int comp_id,

hal_constructor_t constructor)

ARGUMENTS

comp_id AHAL component identiﬁer returned by an earlier call to hal_init.

preﬁx The preﬁx to be giventothe pins, parameters, and functions in the newinstance

argAnargument that may be used by the component to customize this istance.

DESCRIPTION

As an experimental feature in HAL 2.1, components may be constructable.Such a component may create

pins and parameters not only at the time the module is loaded, but it may create additional pins and parame-

ters, and functions on demand.

RETURN VALUE

Returns a HAL status code.

SEE ALSO

halcmd(1)

LinuxCNC Documentation 2006-10-12 71

hal_set_lock(3hal) HAL hal_set_lock(3hal)

NAME hal_set_lock, hal_get_lock − Set or get the HAL lock level

SYNTAX

int hal_set_lock(unsigned char lock_type)

int hal_get_lock()

ARGUMENTS

lock_type

The desired lock type, which may be a bitwise combination of: HAL_LOCK_LOAD,

HAL_LOCK_CONFIG,HAL_LOCK_PARAMS,orHAL_LOCK_PARAMS.

HAL_LOCK_NONE or 0 locks nothing, and HAL_LOCK_ALL locks everything.

DESCRIPTION

RETURN VALUE

hal_set_lock Returns a HAL status code. hal_get_lock returns the current HAL lock leveloraHAL status

code.

72 2006-10-12 LinuxCNC Documentation

hal_signal_new(3hal) HAL hal_signal_new(3hal)

NAME hal_signal_new, hal_signal_delete, hal_link, hal_unlink − Manipulate HAL signals

SYNTAX

int hal_signal_new(const char *signal_name,hal_type_t type)

int hal_signal_delete(const char *signal_name)

int hal_link(const char *pin_name,const char *signal_name)

int hal_unlink(const char *pin_name)

ARGUMENTS

signal_name

The name of the signal

pin_name

The name of the pin

type The type of the signal, as speciﬁed in hal_type_t(3hal).

DESCRIPTION

hal_signal_new creates a newsignal object. Once a signal has been created, pins can be linked to it with

hal_link.The signal object contains the actual storage for the signal data. Pin objects linked to the signal

have pointers that point to the data. ’name’ is the name of the newsignal. It may be no longer than

HAL_NAME_LEN characters. If there is already a signal with the same name the call will fail.

hal_link links a pin to a signal. If the pin is already linked to the desired signal, the command succeeds. If

the pin is already linked to some other signal, it is an error.Ineither case, the existing connection is not

modiﬁed. (Use ’hal_unlink’ to break an existing connection.) If the signal already has other pins linked to

it, theyare unaffected - one signal can be linked to manypins, but a pin can be linked to only one signal.

hal_unlink unlinks anysignal from the speciﬁed pin.

hal_signal_delete deletes a signal object. Anypins linked to the object are unlinked.

RETURN VALUE

Returns a HAL status code.

SEE ALSO

hal_type_t(3hal)

LinuxCNC Documentation 2006-10-12 73

hal_start_threads(3hal) HAL hal_start_threads(3hal)

NAME hal_start_threads − AllowHAL threads to begin executing

SYNTAX

int hal_start_threads()

int hal_stop_threads()

ARGUMENTS

DESCRIPTION

hal_start_threads starts all threads that have been created. This is the point at which realtime functions

start being called.

hal_stop_threads stops all threads that were previously started by hal_start_threads.Itshould be called

before anycomponent that is part of a system exits.

RETURN VALUE

Returns a HAL status code.

SEE ALSO

hal_export_funct(3hal),hal_create_thread(3hal),hal_add_funct_to_thread(3hal)

74 2006-10-12 LinuxCNC Documentation

hal_type_t(3hal) HAL hal_type_t(3hal)

NAME hal_type_t − typedefs for HAL datatypes

DESRCIPTION

typedef ... hal_bool;

Atype which may have a value of 0 or nonzero.

typedef ... hal_bit_t;

Avolatile type which may have a value of 0 or nonzero.

typedef ... hal_s32_t;

Avolatile type which may have a value from -2147483648 to 2147483647.

typedef ... hal_u32_t;

Avolatile type which may have a value from 0 to 4294967295.

typedef ... hal_ﬂoat_t;

Avolatile ﬂoating-point type, which typically has the same precision and range as the C type dou-

ble.

typedef ... real_t;

Anonvolatile ﬂoating-point type with at least as much precision as hal_ﬂoat_t.

typedef ... ireal_t;

Anonvolatile unsigned integral type the same size as hal_ﬂoat_t.

typedef enum hal_type_t;

HAL_BIT

Corresponds to the type hal_bit_t.

HAL_FLOAT

Corresponds to the type hal_ﬂoat_t.

HAL_S32

Corresponds to the type hal_s32_t.

HAL_U32

Corresponds to the type hal_u32_t.

NOTEShal_bit_t is typically a typedef to an integer type whose range is larger than just 0 and 1. When testing the

value of a hal_bit_t,nev ercompare it to 1. Prefer one of the following:

• if(b)

• if(b != 0)

It is often useful to refer to a type that can represent all the values as a hal type, but without the volatile

qualiﬁer.The following types correspond with the hal types:

hal_bit_t int

hal_s32_t __s32

hal_u32_t __u32

hal_ﬂoat_t hal_real_t

Take care not to use the types s32 and u32.These will compile in kernel modules but not in userspace, and

not for "realtime components" when using simulated (userspace) realtime.

LinuxCNC Documentation 2006-10-12 75

hal_type_t(3hal) HAL hal_type_t(3hal)

SEE ALSO

hal_pin_new(3hal),hal_param_new(3hal)

76 2006-10-12 LinuxCNC Documentation

undocumented(3hal) HAL undocumented(3hal)

NAME undocumented − undocumented functions in HAL

SEE ALSO

The header ﬁle hal.h.Most hal functions have documentation in that ﬁle.

LinuxCNC Documentation 2006-10-12 77

intro(3rtapi) RTAPI intro(3rtapi)

NAME rtapi − Introduction to the RTAPI API

DESCRIPTION

RTAPI is a library providing a uniform API for several real time operating systems. As of ver 2.1,

RTLinux, RTAI, and a pure userspace simulator are supported.

HEADER FILES

rtapi.h

The ﬁle rtapi.h deﬁnes the RTAPI for both realtime and non-realtime code. This is a change from Rev2,

where the non-realtime (user space) API was deﬁned in ulapi.h and used different function names. The

symbols RTAPI and ULAPI are used to determine which mode is being compiled, RTAPI for realtime and

ULAPI for non-realtime.

rtapi_math.h

The ﬁle rtapi_math.h deﬁnes ﬂoating-point functions and constants. It should be used instead of <math.h>

in rtapi real-time components.

rtapi_string.h

The ﬁle rtapi_string.h deﬁnes string-related functions. It should be used instead of <string.h> in rtapi real-

time components.

rtapi_byteorder.h

This ﬁle deﬁnes the preprocessor macros RTAPI_BIG_ENDIAN, RTAPI_LITTLE_ENDIAN, and

RTAPI_FLOAT_BIG_ENDIAN as true or false depending on the characteristics of the target system. It

should be used instead of <endian.h> (userspace) or <linux/byteorder.h> (kernel space).

rtapi_limits.h

This ﬁle deﬁnes the minimum and maximum value of some fundamental integral types, such as INT_MIN

and INT_MAX. This should be used instead of <limits.h> because that header ﬁle is not available to ker-

nel modules.

REALTIME CONSIDERATIONS

Userspace code

Certain functions are not available in userspace code. This includes functions that perform direct device

access such as rtapi_inb(3).

Init/cleanup code

Certain functions may only be called from realtime init/cleanup code. This includes functions that perform

memory allocation, such as rtapi_shmem_new(3).

Realtime code

Only a fewfunctions may be called from realtime code. This includes functions that perform direct device

access such as rtapi_inb(3).Itexcludes most Linux kernel APIs such as do_gettimeofday(3) and many

rtapi APIs such as rtapi_shmem_new(3).

Simulator

ForanRTAPI module to be buildable in the "sim" environment (fakerealtime system without special privi-

leges), it must not use any linux kernel APIs, and must not use the RTAPI APIs for direct device access

78 2006-10-02 LinuxCNC Documentation

intro(3rtapi) RTAPI intro(3rtapi)

such as rtapi_inb(3).This automatically includes anyhardware device drivers, and also devices which use

Linux kernel APIs to do things likecreate special devices or entries in the /proc ﬁlesystem.

RTAPI STATUS CODES

Except as noted in speciﬁc manual pages, RTAPI returns negative errno values for errors, and nonnegative

values for success.

LinuxCNC Documentation 2006-10-02 79

rtapi_app_exit(3rtapi) HAL rtapi_app_exit(3rtapi)

NAME rtapi_app_exit − User-provided function to shut down a component

SYNTAX

void rtapi_app_exit(void) { ... }

ARGUMENTS

None

DESCRIPTION

The body of rtapi_app_exit,which is provided by the component author,generally consists of a call to

rtapi_exit or hal_exit, preceded by other component-speciﬁc shutdown code.

This code is called when unloading a component which successfully initialized (i.e., returned zero from its

rtapi_app_main). It is not called when the component did not successfully initialize.

RETURN CODE

None.

REALTIME CONSIDERATIONS

Called automatically by the rtapi infrastructure in an initialization (not realtime) context.

SEE ALSO

rtapi_app_main(3rtapi),rtapi_exit(3rtapi),hal_exit(3hal)

80 2008-05-26 LinuxCNC Documentation

rtapi_app_main(3rtapi) HAL rtapi_app_main(3rtapi)

NAME rtapi_app_main − User-provided function to initialize a component

SYNTAX

#include "rtapi_app.h" int rtapi_app_main(void) { ... }

ARGUMENTS

None

DESCRIPTION

The body of rtapi_app_main,which is provided by the component author,generally consists of a call to

rtapi_init or hal_init, followed by other component-speciﬁc initialization code.

RETURN VALUE

Return 0 for success. Return a negative errno value (e.g., -EINVAL) on error.Existing code also returns

RTAPI or HAL error values, but using negative errno values givesbetter diagnostics from insmod.

REALTIME CONSIDERATIONS

Called automatically by the rtapi infrastructure in an initialization (not realtime) context.

SEE ALSO

rtapi_app_exit(3rtapi),rtapi_init(3rtapi),hal_init(3hal)

LinuxCNC Documentation 2008-05-26 81

rtapi_clock_set_period(3rtapi) RTAPI rtapi_clock_set_period(3rtapi)

NAME rtapi_clock_set_period − set the basic time interval for realtime tasks

SYNTAX

rtapi_clock_set_period(long int nsec)

ARGUMENTS

nsec The desired basic time interval for realtime tasks.

DESCRIPTION

rtapi_clock_set_period sets the basic time interval for realtime tasks. All periodic tasks will run at an

integer multiple of this period. The ﬁrst call to rtapi_clock_set_period with nsec greater than zero will

start the clock, using nsec as the clock period in nano-seconds. Due to hardware and RTOSlimitations, the

actual period may not be exactly what was requested. On success, the function will return the actual clock

period if it is available, otherwise it returns the requested period. If the requested period is outside the lim-

its imposed by the hardware or RTOS, it returns -EINVAL and does not start the clock. Once the clock is

started, subsequent calls with non-zero nsec return -EINVAL and have noeffect. Calling

rtapi_clock_set_period with nsec set to zero queries the clock, returning the current clock period, or zero

if the clock has not yet been started.

REALTIME CONSIDERATIONS

Call only from within init/cleanup code, not from realtime tasks. This function is not available from user

(non-realtime) code.

RETURN VALUE

The actual period provided by the RTOS, which may be different than the requested period, or a RTAPI sta-

tus code.

82 2006-10-12 LinuxCNC Documentation

rtapi_delay(3rtapi) RTAPI rtapi_delay(3rtapi)

NAME rtapi_delay − Busy-loop for short delays

SYNTAX

void rtapi_delay(long int nsec)

void rtapi_delay_max()

ARGUMENTS

nsec The desired delay length in nanoseconds

DESCRIPTION

rtapi_delay is a simple delay.Itisintended only for short delays, since it simply loops, wasting CPU

cycles.

rtapi_delay_max returns the max delay permitted (usually approximately 1/4 of the clock period). Any

call to rtapi_delay requesting a delay longer than the max will delay for the max time only.

rtapi_delay_max should be called before using rtapi_delay to makesure the required delays can be

achieved. The actual resolution of the delay may be as good as one nano-second, or as bad as a several

microseconds.

REALTIME CONSIDERATIONS

May be called from init/cleanup code, and from within realtime tasks.

RETURN VALUE

rtapi_delay_max returns the maximum delay permitted.

SEE ALSO

rtapi_clock_set_period(3rtapi)

LinuxCNC Documentation 2006-10-12 83

rtapi_div_u64(3rtapi) RTAPI rtapi_div_u64(3rtapi)

NAME rtapi_div_u64 − unsigned division of a 64-bit number by a 32-bit number

SYNTAX

__u64 rtapi_div_u64_rem(__u64 dividend,__u32 divisor,__u32 *remainder)

__u64 rtapi_div_u64(__u64 dividend,__u32 divisor)

__s64 rtapi_div_s64(__s64 dividend,__s32 divisor)

__s64 rtapi_div_s64_rem(__s64 dividend,__s32 divisor,__s32 *remainder)

ARGUMENTS

dividend

The value to be divided

divisor The value to divide by

remainder

Pointer to the location to store the remainder.This may not be a NULL pointer.Ifthe remainder

is not desired, call rtapi_div_u64 or rtapi_div_s64.

DESCRIPTION

Perform integer division (and optionally compute the remainder) with a 64-bit dividend and 32-bit divisor.

RETURN VALUE

The result of integer division of dividend / divisor.Inversions with the remainder argument, the remainder

is stored in the pointed-to location.

NOTESIf the result of the division does not ﬁt in the return type, the result is undeﬁned.

This function exists because in kernel space the use of the division operator on a 64-bit type can lead to an

undeﬁned symbol such as __umoddi3 when the module is loaded.

REALTIME CONSIDERATIONS

May be called from init/cleanup code and from within realtime tasks. Av ailable in userspace components.

84 2006-10-12 LinuxCNC Documentation

rtapi_exit(3rtapi) RTAPI rtapi_exit(3rtapi)

NAME rtapi_exit − Shut down RTAPI

SYNTAX

int rtapi_exit(int module_id)

ARGUMENTS

module_id

An rtapi module identiﬁer returned by an earlier call to rtapi_init.

DESCRIPTION

rtapi_exit shuts down and cleans up the RTAPI. It must be called prior to exit by anymodule that called

rtapi_init.

REALTIME CONSIDERATIONS

Call only from within user or init/cleanup code, not from relatime tasks.

RETURN VALUE

Returns a RTAPI status code.

LinuxCNC Documentation 2006-10-12 85

rtapi_get_time(3rtapi) HAL rtapi_get_time(3rtapi)

NAME rtapi_get_time − get the current time

SYNTAX

long long rtapi_get_time()

long long rtapi_get_clocks()

DESCRIPTION

rtapi_get_time returns the current time in nanoseconds. Depending on the RTOS, this may be time since

boot, or time since the clock period was set, or some other time. Its absolute value means nothing, but it is

monotonically increasing and can be used to schedule future events, or to time the duration of some activ-

ity.Returns a 64 bit value. The resolution of the returned value may be as good as one nano-second, or as

poor as several microseconds. May be called from init/cleanup code, and from within realtime tasks.

rtapi_get_clocks returns the current time in CPU clocks. It is fast, since it just reads the TSC in the CPU

instead of calling a kernel or RTOSfunction. Of course, times measured in CPU clocks are not as conve-

nient, but for relative measurements this works ﬁne. Its absolute value means nothing, but it is monotoni-

cally increasing and can be used to schedule future events, or to time the duration of some activity.(on

SMP machines, the twoTSC’smay get out of sync, so if a task reads the TSC, gets swapped to the other

CPU, and reads again, the value may decrease. RTAPI tries to force all RTtasks to run on one CPU.)

Returns a 64 bit value. The resolution of the returned value is one CPU clock, which is usually a few

nanoseconds to a fraction of a nanosecond.

Note that long long math may be poorly supported on some platforms, especially in kernel space. Also note

that rtapi_print() will NOTprint long longs. Most time measurements are relative,and should be done like

this: deltat = (long int)(end_time - start_time);

where end_time and start_time are longlong values returned from rtapi_get_time, and deltat is an ordinary

long int (32 bits). This will work for times up to a second or so, depending on the CPU clock frequency. It

is best used for millisecond and microsecond scale measurements though.

RETURN VALUE

Returns the current time in nanoseconds or CPU clocks.

NOTESCertain versions of the Linux kernel provide a global variable cpu_khz.Computing

deltat = (end_clocks - start_clocks) / cpu_khz:

givesthe duration measured in milliseconds. Computing

deltat = (end_clocks - start_clocks) * 1000000 / cpu_khz:

givesthe duration measured in nanoseconds for deltas less than about 9 trillion clocks (e.g., 3000 seconds

at 3GHz).

REALTIME CONSIDERATIONS

May be called from init/cleanup code and from within realtime tasks. Not available in userspace compo-

nents.

86 2006-10-12 LinuxCNC Documentation

rtapi_init(3rtapi) RTAPI rtapi_init(3rtapi)

NAME rtapi_init − Sets up RTAPI

SYNTAX

int rtapi_init(const char *modname)

ARGUMENTS

modname

The name of this rtapi module

DESCRIPTION

rtapi_init sets up the RTAPI. It must be called by anymodule that intends to use the API, before anyother

RTAPI calls.

modname can optionally point to a string that identiﬁes the module. The string will be truncated at

RTAPI_NAME_LEN characters. If modname is NULL,the system will assign a name.

REALTIME CONSIDERATIONS

Call only from within user or init/cleanup code, not from relatime tasks.

RETURN VALUE

On success, returns a positive integer module ID, which is used for subsequent calls to rtapi_xxx_new,

rtapi_xxx_delete, and rtapi_exit. On failure, returns an RTAPI error code.

LinuxCNC Documentation 2006-10-12 87

rtapi_module_param(3rtapi) RTAPI rtapi_module_param(3rtapi)

NAME rtapi_module_param − Specifying module parameters

SYNTAX

RTAPI_MP_INT(var,description)

RTAPI_MP_LONG(var,description)

RTAPI_MP_STRING(var,description)

RTAPI_MP_ARRAY_INT(var,num,description)

RTAPI_MP_ARRAY_LONG(var,num,description)

RTAPI_MP_ARRAY_STRING(var,num,description)

MODULE_LICENSE(license)

MODULE_AUTHOR(author)

MODULE_DESCRIPTION(description)

EXPORT_FUNCTION(function)

ARGUMENTS

var The variable where the parameter should be stored

description

Ashort description of the parameter or module

num The maximum number of values for an array parameter

license The license of the module, for instance "GPL"

author The author of the module

function

The pointer to the function to be exported

DESCRIPTION

These macros are portable ways to declare kernel module parameters. Theymust be used in the global

scope, and are not followed by a terminating semicolon. Theymust be used after the associated variable or

function has been deﬁned.

NOTESEXPORT_FUNCTION makes a symbol available for use by a subsequently loaded component. It is unre-

lated to hal functions, which are described in hal_export_funct(3hal)

Interpretation of license strings

MODULE_LICENSE follows the kernel’sdeﬁnition of license strings. Notably,"GPL" indicates "GNU

Public License v2 or later". (emphasis ours).

88 2006-10-12 LinuxCNC Documentation

rtapi_module_param(3rtapi) RTAPI rtapi_module_param(3rtapi)

"GPL" GNU Public License v2 or later

"GPL v2"

GNU Public License v2

"GPL and additional rights"

GNU Public License v2 rights and more

"Dual BSD/GPL"

GNU Public License v2 or BSD license choice

"Dual MIT/GPL"

GNU Public License v2 or MIT license choice

"Dual MPL/GPL"

GNU Public License v2 or Mozilla license choice

"Proprietary"

Non-free products

It is still good practice to include a license block which indicates the author,copyright date, and disclaimer

of warranty as recommended by the GNU GPL.

REALTIME CONSIDERATIONS

Not available in userspace code.

LinuxCNC Documentation 2006-10-12 89

rtapi_mutex(3rtapi) RTAPI rtapi_mutex(3rtapi)

NAME rtapi_mutex−Mutex-related functions

SYNTAX

int rtapi_mutex_try(unsigned long *mutex)

void rtapi_mutex_get(unsigned long *mutex)

void rtapi_mutex_give(unsigned long *mutex)

ARGUMENTS

mutex Apointer to the mutex.

DESCRIPTION

rtapi_mutex_try makes a non-blocking attempt to get the mutex. If the mutexisavailable, it returns 0,

and the mutexisnolonger available. Otherwise, it returns a nonzero value.

rtapi_mutex_get blocks until the mutexisavailable.

rtapi_mutex_give releases a mutexacquired by rtapi_mutex_try or rtapi_mutex_get.

REALTIME CONSIDERATIONS

rtapi_mutex_give and rtapi_mutex_try may be used from user,init/cleanup, and realtime code.

rtapi_mutex_get may not be used from realtime code.

RETURN VALUE

rtapi_mutex_try returns 0 for if the mutexwas claimed, and nonzero otherwise.

rtapi_mutex_get and rtapi_mutex_gif have noreturn value.

90 2006-10-12 LinuxCNC Documentation

rtapi_outb(3rtapi) RTAPI rtapi_outb(3rtapi)

NAME rtapi_outb, rtapi_inb − Perform hardware I/O

SYNTAX

void rtapi_outb(unsigned char byte,unsigned int port)

unsigned char rtapi_inb(unsigned int port)

ARGUMENTS

port The address of the I/O port

byte The byte to be written to the port

DESCRIPTION

rtapi_outb writes a byte to a hardware I/O port. rtapi_inb reads a byte from a hardware I/O port.

REALTIME CONSIDERATIONS

May be called from init/cleanup code and from within realtime tasks. Not available in userspace compo-

nents.

RETURN VALUE

rtapi_inb returns the byte read from the givenI/O port

NOTESThe I/O address should be within a region previously allocated by rtapi_request_region.Otherwise,

another real-time module or the Linux kernel might attempt to access the I/O region at the same time.

SEE ALSO

rtapi_region(3rtapi)

LinuxCNC Documentation 2006-10-12 91

rtapi_print(3rtapi) RTAPI rtapi_print(3rtapi)

NAME rtapi_print, rtapi_print_msg − print diagnostic messages

SYNTAX

void rtapi_print(const char *fmt,...)

void rtapi_print_msg(int level, const char *fmt,...)

typedef void(*rtapi_msg_handler_t)(msg_level_t level,const char *msg);

void rtapi_set_msg_handler(rtapi_msg_handler_t handler);

rtapi_msg_handler_t rtapi_set_msg_handler(void);

ARGUMENTS

level Amessage level: One of RTAPI_MSG_ERR,RTAPI_MSG_WARN,RTAPI_MSG_INFO,or

RTAPI_MSG_DBG.

handler

Afunction to call from rtapi_print or rtapi_print_msg to actually output the message.

fmt

... Other arguments are as for printf(3).

DESCRIPTION

rtapi_print and rtapi_print_msg work likethe standard C printf functions, except that a reduced set of

formatting operations are supported.

Depending on the RTOS, the default may be to print the message to stdout, stderr,akernel log, etc. In

RTAPI code, the action may be changed by a call to rtapi_set_msg_handler.ANULL argument to

rtapi_set_msg_handler restores the default handler. rtapi_msg_get_handler returns the current handler.

When the message came from rtapi_print,level is RTAPI_MSG_ALL.

rtapi_print_msg works likertapi_print but only prints if level is less than or equal to the current message

level.

REALTIME CONSIDERATIONS

rtapi_print and rtapi_print_msg May be called from user,init/cleanup, and realtime code.

rtapi_get_msg_handler and ftapi_set_msg_handler may be called from realtime init/cleanup code. A

message handler passed to rtapi_set_msg_handler may only call functions that can be called from real-

time code.

RETURN VALUE

None.

92 2006-10-12 LinuxCNC Documentation

rtapi_print(3rtapi) RTAPI rtapi_print(3rtapi)

SEE ALSO

rtapi_set_msg_level(3rtapi),rtapi_get_msg_level(3rtapi),printf(3)

LinuxCNC Documentation 2006-10-12 93

rtapi_prio(3rtapi) RTAPI rtapi_prio(3rtapi)

NAME rtapi_prio − thread priority functions

SYNTAX

int rtapi_prio_highest()

int rtapi_prio_lowest()

int rtapi_prio_next_higher(int prio)

int rtapi_prio_next_lower(int prio)

ARGUMENTS

prio Avalue returned by a prior rtapi_prio_xxx call

DESCRIPTION

The rtapi_prio_xxxx functions provide a portable way to set task priority.The mapping of actual priority

to priority number depends on the RTOS. Priorities range from rtapi_prio_lowest to rtapi_prio_highest,

inclusive.Touse this API, use one of twomethods:

1) Set your lowest priority task to rtapi_prio_lowest,and for each task of the next lowest priority,set

their priorities to rtapi_prio_next_higher(previous).

2) Set your highest priority task to rtapi_prio_highest,and for each task of the next highest priority,

set their priorities to rtapi_prio_next_lower(previous).

N.B. A high priority task will pre-empt or interrupt a lower priority task. Linux is always the lowest prior-

ity!

REALTIME CONSIDERATIONS

Call these functions only from within init/cleanup code, not from realtime tasks.

RETURN VALUE

Returns an opaque real-time priority number.

SEE ALSO

rtapi_task_new(3rtapi)

94 2006-10-12 LinuxCNC Documentation

rtapi_region(3rtapi) RTAPI rtapi_region(3rtapi)

NAME rtapi_region − functions to manage I/O memory regions

SYNTAX

void *rtapi_request_region(unsigned long base,unsigned long int size,const char *name)

void rtapi_release_region(unsigned long base,unsigned long int size)

ARGUMENTS

base The base address of the I/O region

size The size of the I/O region

name The name to be shown in /proc/ioports

DESCRIPTION

rtapi_request_region reserves I/O memory starting at base and going for size bytes.

REALTIME CONSIDERATIONS

May be called from realtime init/cleanup code only.

BUGS On kernels before 2.4.0, rtapi_request_region always suceeds.

RETURN VALUE

rtapi_request_region returns NULL if the allocation fails, and a non-NULL value otherwise.

rtapi_release_region has no return value.

LinuxCNC Documentation 2006-10-12 95

rtapi_set_msg_level(3rtapi) RTAPI rtapi_set_msg_level(3rtapi)

NAME rtapi_get_msg_level, rtapi_set_msg_level−Get or set the logging level

SYNTAX

int rtapi_set_msg_level(int level)

int rtapi_get_msg_level()

ARGUMENTS

level The desired logging level

DESCRIPTION

Get or set the RTAPI message levelused by rtapi_print_msg.Depending on the RTOS, this levelmay

apply to a single RTAPI module, or it may apply to a group of modules.

REALTIME CONSIDERATIONS

May be called from user,init/cleanup, and realtime code.

RETURN VALUE

rtapi_set_msg_levelreturns a status code, and rtapi_get_msg_levelreturns the current level.

SEE ALSO

rtapi_print_msg(3rtapi)

96 2006-10-12 LinuxCNC Documentation

rtapi_shmem(3rtapi) RTAPI rtapi_shmem(3rtapi)

NAME rtapi_shmem − Functions for managing shared memory blocks

SYNTAX

int rtapi_shmem_new(int key,int module_id,unsigned long int size)

int rtapi_shmem_delete(int shmem_id,int module_id)

int rtapi_shmem_getptr(int shmem_id,void ** ptr)

ARGUMENTS

keyIdentiﬁes the memory block. Ke y must be nonzero. All modules wishing to use the same memory

must use the same key.

module_id

Module identiﬁer returned by a prior call to rtapi_init.

size The desired size of the shared memory block, in bytes

ptr The pointer to the shared memory block. Note that the block may be mapped at a different

address for different modules.

DESCRIPTION

rtapi_shmem_new allocates a block of shared memory. keyidentiﬁes the memory block, and must be non-

zero. All modules wishing to access the same memory must use the same key.module_id is the ID of the

module that is making the call (see rtapi_init). The block will be at least size bytes, and may be rounded

up. Allocating manysmall blocks may be very wasteful. When aparticular block is allocated for the ﬁrst

time, the ﬁrst 4 bytes are zeroed. Subsequent allocations of the same block by other modules or processes

will not touch the contents of the block. Applications can use those bytes to see if theyneed to initialize

the block, or if another module already did so. On success, it returns a positive integer ID, which is used

for all subsequent calls dealing with the block. On failure it returns a negative error code.

rtapi_shmem_delete frees the shared memory block associated with shmem_id.module_id is the ID of the

calling module. Returns a status code.

rtapi_shmem_getptr sets *ptr to point to shared memory block associated with shmem_id.

REALTIME CONSIDERATIONS

rtapi_shmem_getptr may be called from user code, init/cleanup code, or realtime tasks.

rtapi_shmem_new and rtapi_shmem_dete may not be called from realtime tasks.

RETURN VALUE

LinuxCNC Documentation 2006-10-12 97

rtapi_snprintf(3rtapi) RTAPI rtapi_snprintf(3rtapi)

NAME rtapi_snprintf, rtapi_vsnprintf − Perform snprintf-likestring formatting

SYNTAX

int rtapi_snprintf(char *buf,unsigned long int size,const char *fmt,...)

int rtapi_vsnprintf(char *buf,unsigned long int size,const char *fmt,va_list apfB)

ARGUMENTS

As for snprintf(3) or vsnprintf(3).

DESCRIPTION

These functions work likethe standard C printf functions, except that a reduced set of formatting operations

are supported.

In particular: formatting of long long values is not supported. Formatting of ﬂoating-point values is done as

though with %A evenwhen other formats like%fare speciﬁed.

REALTIME CONSIDERATIONS

May be called from user,init/cleanup, and realtime code.

RETURN VALUE

The number of characters written to buf.

SEE ALSO

printf(3)

98 2006-10-12 LinuxCNC Documentation

rtapi_task_new(3rtapi) RTAPI rtapi_task_new(3rtapi)

NAME rtapi_task_new−create a realtime task

SYNTAX

int rtapi_task_new(void (*taskcode)(void*), void *arg,int prio,unsigned long stacksize,int

uses_fp)

int rtapi_task_delete(int task_id)

ARGUMENTS

taskcode

Apointer to the function to be called when the task is started

arg An argument to be passed to the taskcode function when the task is started

prio Atask priority value returned by rtapi_prio_xxxx

uses_fp Aﬂag that tells the OS whether the task uses ﬂoating point or not.

task_id Atask ID returned by a previous call to rtapi_task_new

DESCRIPTION

rtapi_task_new creates but does not start a realtime task. The task is created in the "paused" state. To

start it, call either rtapi_task_start for periodic tasks, or rtapi_task_resume for free-running tasks.

REALTIME CONSIDERATIONS

Call only from within init/cleanup code, not from realtime tasks.

RETURN VALUE

On success, returns a positive integer task ID. This ID is used for all subsequent calls that need to act on

the task. On failure, returns an RTAPI status code.

SEE ALSO

rtapi_prio(3rtapi),rtapi_task_start(3rtapi),rtapi_task_wait(3rtapi),rtapi_task_resume(3rtapi)

LinuxCNC Documentation 2006-10-12 99

rtapi_task_pause(3rtapi) RTAPI rtapi_task_pause(3rtapi)

NAME rtapi_task_pause, rtapi_task_resume − pause and resume real-time tasks

SYNTAX

void rtapi_task_pause(int task_id)

void rtapi_task_resume(int task_id)

ARGUMENTS

task_id An RTAPI task identiﬁer returned by an earlier call to rtapi_task_new.

DESCRIPTION

rtapi_task_resume starts a task in free-running mode. The task must be in the "paused" state.

Afree running task runs continuously until either:

1) It is prempted by a higher priority task. It will resume as soon as the higher priority task releases

the CPU.

2) It calls a blocking function, like rtapi_sem_take.Itwill resume when the function unblocks.

3) It is returned to the "paused" state by rtapi_task_pause.May be called from init/cleanup code,

and from within realtime tasks.

rtapi_task_pause causes a task to stop execution and change to the "paused" state. The task can

be free-running or periodic. Note that rtapi_task_pause may called from anytask, or from init or

cleanup code, not just from the task that is to be paused. The task will resume execution when

either rtapi_task_resume or rtapi_task_start (depending on whether this is a free-running or

periodic task) is called.

REALTIME CONSIDERATIONS

May be called from init/cleanup code, and from within realtime tasks.

RETURN VALUE

An RTAPI status code.

SEE ALSO

rtapi_task_new(3rtapi),rtapi_task_start(3rtapi)

100 2006-10-12 LinuxCNC Documentation

rtapi_task_start(3rtapi) RTAPI rtapi_task_start(3rtapi)

NAME rtapi_task_start − start a realtime task in periodic mode

SYNTAX

int rtapi_task_start(int task_id,unsigned long period_nsec)

ARGUMENTS

task_id Atask ID returned by a previous call to rtapi_task_new

period_nsec

The clock period in nanoseconds between iterations of a periodic task

DESCRIPTION

rtapi_task_start starts a task in periodic mode. The task must be in the paused state.

REALTIME CONSIDERATIONS

Call only from within init/cleanup code, not from realtime tasks.

RETURN VALUE

Returns an RTAPI status code.

SEE ALSO

rtapi_task_new(3rtapi),rtapi_task_pause(3rtapi),rtapi_task_resume(3rtapi)

LinuxCNC Documentation 2006-10-12 101

rtapi_task_wait(3rtapi) RTAPI rtapi_task_wait(3rtapi)

NAME rtapi_task_wait − suspend execution of this periodic task

SYNTAX

void rtapi_task_wait()

DESCRIPTION

rtapi_task_wait suspends execution of the current task until the next period. The task must be periodic. If

not, the result is undeﬁned.

REALTIME CONSIDERATIONS

Call only from within a periodic realtime task

RETURN VALUE

None

SEE ALSO

rtapi_task_start(3rtapi),rtapi_task_pause(3rtapi)

102 2006-10-12 LinuxCNC Documentation

undocumented(3rtapi) RTAPI undocumented(3rtapi)

NAME undocumented − undocumented functions in RTAPI

SEE ALSO

The header ﬁle rtapi.h.Most rtapi functions have documentation in that ﬁle.

LinuxCNC Documentation 2006-10-12 103

ABS(9) HAL Component ABS(9)

NAME abs − Compute the absolute value and sign of the input signal

SYNOPSIS

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

FUNCTIONS

abs.N(requires a ﬂoating-point thread)

PINS abs.N.in ﬂoat in

Analog input value

abs.N.out ﬂoat out

Analog output value, always positive

abs.N.sign bit out

Sign of input, false for positive,true for negative

abs.N.is-positive bit out

TRUE if input is positive,FALSE if input is 0 or negative

abs.N.is-negative bit out

TRUE if input is negative,FALSE if input is 0 or positive

LICENSE

GPL

104 2014-12-18 LinuxCNC Documentation

ABS_S32(9) HAL Component ABS_S32(9)

NAME abs_s32 − Compute the absolute value and sign of the input signal

SYNOPSIS

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

FUNCTIONS

abs-s32.N

PINS abs-s32.N.in s32 in

input value

abs-s32.N.out s32 out

output value, always non-negative

abs-s32.N.sign bit out

Sign of input, false for positive,true for negative

abs-s32.N.is-positive bit out

TRUE if input is positive,FALSE if input is 0 or negative

abs-s32.N.is-negative bit out

TRUE if input is negative,FALSE if input is 0 or positive

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 105

AND2(9) HAL Component AND2(9)

NAME and2 − Two-input AND gate

SYNOPSIS

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

FUNCTIONS

and2.N

PINS and2.N.in0 bit in

and2.N.in1 bit in

and2.N.out bit out

out is computed from the value of in0 and in1 according to the following rule:

in0=TRUE in1=TRUE

out=TRUE

Otherwise,

out=FALSE

LICENSE

GPL

106 2014-12-18 LinuxCNC Documentation

AT_PID(9) HAL Component AT_PID(9)

NAME at_pid − proportional/integral/derivative controller with auto tuning

SYNOPSIS

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

DESCRIPTION

at_pid is a classic Proportional/Integral/Derivative controller,used to control position or speed feedback

loops for servomotors and other closed-loop applications.

at_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 sepa-

rated by commas.

The num_chan= and names= speciﬁers are mutually exclusive.Ifneither num_chan= nor names= are

speciﬁed, 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.

at_pid has a built in auto tune mode. It works by setting up a limit cycle to characterize the process. From

this, Pgain/Igain/Dgain or Pgain/Igain/FF1 can be determined using Ziegler-Nichols. When using FF1,

scaling must be set so that output is in user units per second.

During auto tuning, the command input should not change. The limit cycle is setup around the commanded

position. No initial tuning values are required to start auto tuning. Only tune-cycles,tune-effort and tune-

mode need be set before starting auto tuning. When auto tuning completes, the tuning parameters will be

set. If running from LinuxCNC, the FERROR setting for the axis being tuned may need to be loosened up

as it must be larger than the limit cycle amplitude in order to avoid a following error.

To perform auto tuning, takethe following steps. Move the axis to be tuned, to somewhere near the center

of it’stravel. Set tune-cycles (the default value should be ﬁne in most cases) and tune-mode.Set tune-

effort to a small value. Set enable to true. Set tune-mode to true. Set tune-start to true. If no oscillation

occurs, or the oscillation is too small, slowly increase tune-effort.Auto tuning can be aborted at anytime

by setting enable or tune-mode to false.

NAMING

The names for pins, parameters, and functions are preﬁxed as:

pid.N. for N=0,1,...,num-1 when using num_chan=num

nameN. for nameN=name1,name2,... when using names=name1,name2,...

The pid.N. format is shown in the following descriptions.

FUNCTIONS

pid.N.do-pid-calcs (uses ﬂoating-point)

Does the PID calculations for control loop N.

PINS pid.N.command ﬂoat in

The desired (commanded) value for the control loop.

pid.N.feedback ﬂoat in

The actual (feedback) value, from some sensor such as an encoder.

LinuxCNC Documentation 2007-05-12 107

AT_PID(9) HAL Component AT_PID(9)

pid.N.error ﬂoat out

The difference between command and feedback.

pid.N.output ﬂoat out

The output of the PID loop, which goes to some actuator such as a motor.

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.tune-mode bit in

When true, enables auto tune mode. When false, normal PID calculations are performed.

pid.N.tune-start bit io

When set to true, starts auto tuning. Cleared when the auto tuning completes.

PARAMETERS

pid.N.Pgain ﬂoat rw

Proportional gain. Results in a contribution to the output that is the error multiplied by Pgain.

pid.N.Igain ﬂoat rw

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)of0.2, and if Igain is 20, the integral term would add 4.0 to the output.

pid.N.Dgain ﬂoat rw

Derivative gain. Results in a contribution to the output that is the rate of change (derivative)ofthe

error multiplied by Dgain.For example an error that changed from 0.02 to 0.03 over0.2 seconds

would result in an error derivative (errorD)ofof0.05, and if Dgain is 5, the derivative term would

add 0.25 to the output.

pid.N.bias ﬂoat rw

bias is a constant amount that is added to the output. In most cases it should be left at zero. How-

ev e r, itcan sometimes be useful to compensate for offsets in servoampliﬁers, or to balance the

weight of an object that movesvertically. bias is turned offwhen the PID loop is disabled, just like

all other components of the output. If a non-zero output is needed evenwhen the PID loop is dis-

abled, it should be added with an external HAL sum2 block.

pid.N.FF0 ﬂoat rw

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. Forvelocity loops, FF0

can compensate for friction or motor counter-EMF and may permit better tuning if used properly.

pid.N.FF1 ﬂoat rw

First order feed-forward term. Produces a contribution to the output that FF1 multiplied by the

derivative ofthe 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 ﬂoat rw

Second order feed-forward term. Produces a contribution to the output that is FF2 multiplied by

the second derivative ofthe commanded value. For position loops, the contribution is proportional

to acceleration, and can be used to compensate for inertia. Forvelocity loops, it should usually be

left at zero.

pid.N.deadband ﬂoat rw

Deﬁnes a range of "acceptable" error.Ifthe absolute value of error is less than deadband,itwill

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 twoadjacent encoder values. When

108 2007-05-12 LinuxCNC Documentation

AT_PID(9) HAL Component AT_PID(9)

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 ﬂoat rw

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 integrat-

ing, to prevent windup and overshoot.

pid.N.maxerror ﬂoat rw

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 ﬂoat rw

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 out-

put spikes due to steps on the command and/or feedback. Not normally needed.

pid.N.maxerrorI ﬂoat rw

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 ﬂoat rw

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

astep change on the command. Not normally needed.

pid.N.maxcmdDD ﬂoat rw

Limit on command second derivative.The command second derivative used by FF2 will be lim-

ited to this value, unless the value is zero. Can be used to prevent FF2 from producing large out-

put spikes if there is a step change on the command. Not normally needed.

pid.N.tune-type u32 rw

When set to 0, Pgain/Igain/Dgain are caclulated. When set to 1, Pgain/Igain/FF1 are calculated.

pid.N.tune-cycles u32 rw

Determines the number of cycles to run to characterize the process. tune-cycles actually sets the

number of half cycles. More cycles results in a more accurate characterization as the average of all

cycles is used.

pid.N.tune-effort ﬂoat rw

Determines the effor used in setting up the limit cycle in the process. tune-effort should be set to

apositive value less than maxoutput.Start with something small and work up to a value that

results in a good portion of the maximum motor current being used. The smaller the value, the

smaller the amplitude of the limit cycle.

pid.N.errorI ﬂoat 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 ﬂoat ro (only if debug=1)

Derivative oferror.This is the value that is multiplied by Dgain to produce the Derivative term of

the output.

pid.N.commandD ﬂoat ro (only if debug=1)

Derivative ofcommand. This is the value that is multiplied by FF1 to produce the ﬁrst order feed-

forward term of the output.

LinuxCNC Documentation 2007-05-12 109

AT_PID(9) HAL Component AT_PID(9)

pid.N.commandDD ﬂoat ro (only if debug=1)

Second derivative ofcommand. This is the value that is multiplied by FF2 to produce the second

order feed-forward term of the output.

pid.N.ultimate-gain ﬂoat ro (only if debug=1)

Determined from process characterization. ultimate-gain is the ratio of tune-effort to the limit

cycle amplitude multipled by 4.0 divided by Pi. pid.N.ultimate-period ﬂoat ro (only if debug=1)

Determined from process characterization. ultimate-period is the period of the limit cycle.

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 unmodiﬁed 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,ortowrite their own version of at_pid.How-

ev e r, the default behavior should not be changed.

110 2007-05-12 LinuxCNC Documentation

BIN2GRAY(9) HAL Component BIN2GRAY(9)

NAME bin2gray − convert a number to the gray-code representation

SYNOPSIS

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

DESCRIPTION

Converts a number into gray-code

FUNCTIONS

bin2gray.N

PINS bin2gray.N.in u32 in

binary code in

bin2gray.N.out u32 out

gray code out

AUTHOR

andy pugh

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 111

BIQUAD(9) HAL Component BIQUAD(9)

NAME biquad − Biquad IIR ﬁlter

SYNOPSIS

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

DESCRIPTION

Biquad IIR ﬁlter.Implements the following transfer function: H(z) = (n0 + n1z-1 + n2z-2) / (1+ d1z-1 +

d2z-2)

FUNCTIONS

biquad.N(requires a ﬂoating-point thread)

PINS biquad.N.in ﬂoat in

Filter input.

biquad.N.out ﬂoat out

Filter output.

biquad.N.enable bit in (default: 0)

Filter enable. When false, the in is passed to out without anyﬁltering. A transition from false to

true causes ﬁlter coefﬁcients to be calculated according to parameters

biquad.N.valid bit out (default: 0)

When false, indicates an error occured when caclulating ﬁlter coefﬁcients.

PARAMETERS

biquad.N.type u32 rw (default: 0)

Filter type determines the type of ﬁlter coefﬁcients calculated. When 0, coefﬁcients must be

loaded directly.When 1, a lowpass ﬁlter is created. When 2, a notch ﬁlter is created.

biquad.N.f0 ﬂoat rw (default: 250.0)

The corner frequencyofthe ﬁlter.

biquad.N.Q ﬂoat rw (default: 0.7071)

The Q of the ﬁlter.

biquad.N.d1 ﬂoat rw (default: 0.0)

1st-delayed denominator coef

biquad.N.d2 ﬂoat rw (default: 0.0)

2nd-delayed denominator coef

biquad.N.n0 ﬂoat rw (default: 1.0)

non-delayed numerator coef

biquad.N.n1 ﬂoat rw (default: 0.0)

1st-delayed numerator coef

biquad.N.n2 ﬂoat rw (default: 0.0)

2nd-delayed numerator coef

biquad.N.s1 ﬂoat rw (default: 0.0)

biquad.N.s2 ﬂoat rw (default: 0.0)

LICENSE

GPL

112 2014-12-18 LinuxCNC Documentation

BITSLICE(9) HAL Component BITSLICE(9)

NAME bitslice − Converts an unsigned-32 input into individual bits

SYNOPSIS

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

DESCRIPTION

This component creates individual bit-outputs for each bit of an unsigned-32 input. The number of bits can

be limited by the "personality" modparam. The inverse process can be perfomed by the weighted_sum

HAL component.

FUNCTIONS

bitslice.N

PINS bitslice.N.in u32 in

The input value

bitslice.N.out-MM bit out (MM=00..personality)

AUTHOR

Andy Pugh

LICENSE

GPL2+

LinuxCNC Documentation 2014-12-18 113

BITWISE(9) HAL Component BITWISE(9)

NAME bitwise − Computes various bitwise operations on the twoinput values

SYNOPSIS

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

FUNCTIONS

bitwise.N

PINS bitwise.N.in0 u32 in

First input value

bitwise.N.in1 u32 in

Second input value

bitwise.N.out-and u32 out

The bitwise AND of the twoinputs

bitwise.N.out-or u32 out

The bitwise OR of the twoinputs

bitwise.N.out-xor u32 out

The bitwise XOR of the twoinputs

bitwise.N.out-nand u32 out

The inverse of the bitwise AND

bitwise.N.out-nor u32 out

The inverse of the bitwise OR

bitwise.N.out-xnor u32 out

The inverse of the bitwise XOR

AUTHOR

Andy Pugh

LICENSE

GPL 2+

114 2014-12-18 LinuxCNC Documentation

BLDC(9) HAL Component BLDC(9)

NAME bldc − BLDC and AC-servocontrol component

SYNOPSIS

loadrt bldc personality=P

DESCRIPTION

This component is designed as an interface between the most common forms of three-phase motor feed-

back devices and the corresponding types of drive.Howev erthere is no requirement that the motor and

drive should necessarily be of inherently compatible types.

SYNOPSIS

(ignore the auto-generated SYNOPSIS above)

loadrt bldc cfg=qi6,aH

Each instance of the component is deﬁned by a group of letters describing the input and output

types. A comma separates individual instances of the component.

Tags Input type deﬁnitions are all lower-case.

nNo motor feedback. This mode could be used to drive ACinduction motors, but is also potentially useful

for creating free-running motor simulators for drive testing.

hHall sensor input. Brushless DC motors (electronically commutated permanent magnet 3-phase motors)

typically use a set of three Hall sensors to measure the angular position of the rotor.Alower-case hin the

cfg string indicates that these should be used.

aAbsolute encoder input. (Also possibly used by some forms of Resolver conversion hardware). The pres-

ence of this tag over-rides all other inputs. Note that the component still requires to be be connected to the

rawcounts encoder pin to prevent loss of commutation on index-reset.

qIncremental (quadrature) encoder input. If this input is used then the rotor will need to be homed before

the motor can be run.

iUse the indexofanincremental encoder as a home reference.

fUse a 4-bit Gray-scale patttern to determine rotor alignment. This scheme is only used on the Fanuc "Red

Cap" motors. This mode could be used to control one of these motors using a non-Fanuc drive.

Output type descriptions are all upper-case.

Defaults The component will always calculate rotor angle, phase angle and the absolute value of the input

value for interfacing with drivessuch as the Mesa 8i20. It will also default to three individual, bipolar

phase output values if no other output type modiﬁers are used.

BBit leveloutputs. Either 3 or 6 logic-leveloutputs indicating which high or lowgate drivers on an exter-

nal drive should be used.

6Create 6 rather than the default 3 outputs. In the case of numeric value outputs these are separate positive

and negative drive amplitudes. Both have positive magnitude.

HEmulated Hall sensor output. This mode can be used to control a drive which expects 3x Hall signals, or

to convert between a motor with one hall pattern and a drive which expects a different one.

FEmulated Fanuc Red Cap Gray-code encoder output. This mode might be used to drive a non-Fanuc

LinuxCNC Documentation 2014-12-18 115

BLDC(9) HAL Component BLDC(9)

motor using a Fanuc drive intended for the "Red-Cap" motors.

TForce Trapezoidal mode.

OPERATING MODES

The component can control a drive ineither Trapezoidal or Sinusoidal mode, but will always default to

sinusoidal if the input and output modes allowit. This can be over-ridden by the Ttag. Sinusoidal commu-

tation is signiﬁcantly smoother (trapezoidal commutation induces 13% torque ripple).

ROTORHOMING.

To use an encoder for commutation a reference 0-degrees point must be found. The component uses the

convention that motor zero is the point that an unloaded motor aligns to with a positive voltage on the A (or

U) terminal and the B & C (or V and W) terminals connected together and to -vevoltage. There will be two

such positions on a 4-pole motor,3ona6-pole and so on. Theyare all functionally equivalent as far as

driving the motor is concerned. If the motor has Hall sensors then the motor can be started in trapezoidal

commutation mode, and will switch to sinusoidal commutation when an alignment is found. If the mode is

qh then the ﬁrst Hall state-transition will be used. If the mode is qhi then the encoder indexwill be used.

This givesamore accurate homing position if the distance in encoder counts between motor zero and

encoder indexisknown. Toforce homing to the Hall edges instead simply omit the i.

Motors without Hall sensors may be homed in synchronous/direct mode. The better of these options is to

home to the encoder zero using the iq conﬁg parameter.When the init pin goes high the motor will rotate

(in a direction determined by the re v pin) until the encoder indicates an index-latch (the servothread runs

too slowly to rely on detecting an encoder indexdirectly). If there is no encoder indexorits location rela-

tive tomotor zero can not be found, then an alternative istouse magnetic homing using the qconﬁg. In this

mode the motor will go through an alignment sequence ending at motor zero when the init pin goes high It

will then set the ﬁnal position as motor zero. Unfortunately the motor is rather springy in this mode and so

alignment is likely to be fairly sensitive toload.

FUNCTIONS

bldc.N(requires a ﬂoating-point thread)

PINS bldc.N.hall1 bit in [if personality & 0x01]

Hall sensor signal 1

bldc.N.hall2 bit in [if personality & 0x01]

Hall sensor signal 2

bldc.N.hall3 bit in [if personality & 0x01]

Hall sensor signal 3

bldc.N.hall-error bit out [if personality & 0x01]

Indicates that the selected hall pattern givesinconsistent rotor position data. This can be due to the

pattern being wrong for the motor,orone or more sensors being unconnected or broken. A consis-

tent pattern is not neceesarily valid, but an inconsistent one can neverbevalid.

bldc.N.C1 bit in [if ( personality & 0x10 )]

Fanuc Gray-code bit 0 input

bldc.N.C2 bit in [if ( personality & 0x10 )]

Fanuc Gray-code bit 1 input

bldc.N.C4 bit in [if ( personality & 0x10 )]

Fanuc Gray-code bit 2 input

116 2014-12-18 LinuxCNC Documentation

BLDC(9) HAL Component BLDC(9)

bldc.N.C8 bit in [if ( personality & 0x10 )]

Fanuc Gray-code bit 3 input

bldc.N.value ﬂoat in

PWM master amplitude input

bldc.N.lead-angle ﬂoat in [if personality & 0x06] (default: 90)

The phase lead between the electrical vector and the rotor position in degrees

bldc.N.rev bit in

Set this pin true to reverse the motor.Neg ative PWM amplitudes will also reverse the motor and

there will generally be a Hall pattern that runs the motor in each direction too.

bldc.N.frequency ﬂoat in [if ( personality & 0x0F ) == 0]

Frequencyinput for motors with no feedback at all, or those with only an index(which is ignored)

bldc.N.initvalue ﬂoat in [if personality & 0x04] (default: 0.2)

The current to be used for the homing sequence in applications where an incremental encoder is

used with no hall-sensor feedback

bldc.N.rawcounts s32 in [if personality & 0x06] (default: 0)

Encoder counts input. This must be linked to the encoder rawcounts pin or encoder indexresets

will cause the motor commutation to fail

bldc.N.index-enable bit io [if personality & 0x08]

This pin should be connected to the associated encoder index-enable pin to zero the encoder when

it passes indexThis is only used indicate to the bldc control component that an indexhas been

seen

bldc.N.init bit in [if ( personality & 0x05 ) == 4]

Arising edge on this pin starts the motor alignment sequence. This pin should be connected in

such a way that the motors re-align anytime that encoder monitoring has been interrupted. Typi-

cally this will only be at machine power-off. The alignment process involves powering the motor

phases in such a way as to put the motor in a known position. The encoder counts are then stored

in the offset parameter.The alignement process will tend to cause a following error if it is trig-

gered while the axis is enabled, so should be set before the matching axis.N.enable pin. The com-

plementary init-done pin can be used to handle the required sequencing.

Both pins can be ignored if the encoder offset is known explicitly,such as is the case with an abso-

lute encoder.Inthat case the offset parameter can be set directly in the HAL ﬁle

bldc.N.init-done bit out [if ( personality & 0x05 ) == 4] (default: 0)

Indicates homing sequence complete

bldc.N.A-value ﬂoat out [if ( personality & 0xF00 ) == 0]

Output amplitude for phase A

bldc.N.B-value ﬂoat out [if ( personality & 0xF00 ) == 0]

Output amplitude for phase B

bldc.N.C-value ﬂoat out [if ( personality & 0xF00 ) == 0]

Output amplitude for phase C

bldc.N.A-on bit out [if ( personality & 0xF00 ) == 0x100]

Output bit for phase A

bldc.N.B-on bit out [if ( personality & 0xF00 ) == 0x100]

Output bit for phase B

bldc.N.C-on bit out [if ( personality & 0xF00 ) == 0x100]

Output bit for phase C

LinuxCNC Documentation 2014-12-18 117

BLDC(9) HAL Component BLDC(9)

bldc.N.A-high ﬂoat out [if ( personality & 0xF00 ) == 0x200]

High-side driverfor phase A

bldc.N.B-high ﬂoat out [if ( personality & 0xF00 ) == 0x200]

High-side driverfor phase B

bldc.N.C-high ﬂoat out [if ( personality & 0xF00 ) == 0x200]

High-side driverfor phase C

bldc.N.A-low ﬂoat out [if ( personality & 0xF00 ) == 0x200]

Low-side driverfor phase A

bldc.N.B-low ﬂoat out [if ( personality & 0xF00 ) == 0x200]

Low-side driverfor phase B

bldc.N.C-low ﬂoat out [if ( personality & 0xF00 ) == 0x200]

Low-side driverfor phase C

bldc.N.A-high-on bit out [if ( personality & 0xF00 ) == 0x300]

High-side driverfor phase A

bldc.N.B-high-on bit out [if ( personality & 0xF00 ) == 0x300]

High-side driverfor phase B

bldc.N.C-high-on bit out [if ( personality & 0xF00 ) == 0x300]

High-side driverfor phase C

bldc.N.A-low-on bit out [if ( personality & 0xF00 ) == 0x300]

Low-side driverfor phase A

bldc.N.B-low-on bit out [if ( personality & 0xF00 ) == 0x300]

Low-side driverfor phase B

bldc.N.C-low-on bit out [if ( personality & 0xF00 ) == 0x300]

Low-side driverfor phase C

bldc.N.hall1-out bit out [if ( personality & 0x400 )]

Hall 1 output

bldc.N.hall2-out bit out [if ( personality & 0x400 )]

Hall 2 output

bldc.N.hall3-out bit out [if ( personality & 0x400 )]

Hall 3 output

bldc.N.C1-out bit out [if ( personality & 0x800 )]

Fanuc Gray-code bit 0 output

bldc.N.C2-out bit out [if ( personality & 0x800 )]

Fanuc Gray-code bit 1 output

bldc.N.C4-out bit out [if ( personality & 0x800 )]

Fanuc Gray-code bit 2 output

bldc.N.C8-out bit out [if ( personality & 0x800 )]

Fanuc Gray-code bit 3 output

bldc.N.phase-angle ﬂoat out (default: 0)

Phase angle including lead/lag angle after encoder zeroing etc. Useful for angle/current drives.

This value has a range of 0 to 1 and measures electrical revolutions. It will have two zeros for a 4

pole motor,three for a 6-pole etc

bldc.N.rotor-angle ﬂoat out (default: 0)

Rotor angle after encoder zeroing etc. Useful for angle/current driveswhich add their own phase

offset such as the 8i20. This value has a range of 0 to 1 and measures electrical revolutions. It will

have two zeros for a 4 pole motor,three for a 6-pole etc

118 2014-12-18 LinuxCNC Documentation

BLDC(9) HAL Component BLDC(9)

bldc.N.out ﬂoat out

Current output, including the effect of the dir pin and the alignment sequence

bldc.N.out-dir bit out

Direction output, high if /fBvalue/fR is negative XOR /fBrev/fR is true.

bldc.N.out-abs ﬂoat out

Absolute value of the input value

PARAMETERS

bldc.N.in-type s32 r (default: -1)

state machine output, will probably hide after debug

bldc.N.out-type s32 r (default: -1)

state machine output, will probably hide after debug

bldc.N.scale s32 rw [if personality & 0x06] (default: 512)

The number of encoder counts per rotor revolution.

bldc.N.poles s32 rw [if personality & 0x06] (default: 4)

The number of motor poles. The encoder scale will be divided by this value to determine the num-

ber of encoder counts per electrical revolution

bldc.N.encoder-offset s32 rw [if personality & 0x0A] (default: 0)

The offset, in encoder counts, between the motor electrical zero and the encoder zero modulo the

number of counts per electrical revolution

bldc.N.offset-measured s32 r [if personality & 0x04] (default: 0)

The encoder offset measured by the homing sequence (in certain modes)

bldc.N.drive-offset ﬂoat rw (default: 0)

The angle, in degrees, applied to the commanded angle by the drive indegrees. This value is only

used during the homing sequence of driveswith incremental encoder feedback. It is used to back-

calculate from commanded angle to actual phase angle. It is only relevant to driveswhich expect

rotor-angle input rather than phase-angle demand. Should be 0 for most drives.

bldc.N.output-pattern u32 rw [if personality & 0x400] (default: 25)

Commutation pattern to be output in Hall Signal translation mode. See the description of /fBpat-

tern/fR for details

bldc.N.pattern u32 rw [if personality & 0x01] (default: 25)

Commutation pattern to use, from 0 to 47. Default is type 25. Every plausible combination is

included. The table shows the excitation pattern along the top, and the pattern code on the left

hand side. The table entries are the hall patterns in H1, H2, H3 order.Common patterns are: 0 (30

degree commutation) and 26, its reverse. 17 (120 degree). 18 (alternate 60 degree). 21 (300

degree, Bodine). 22 (240 degree). 25 (60 degree commutation).

Note that a number of incorrect commutations will have non-zero net torque which might look as

if theywork, but don’treally.

If your motor lacks documentation it might be worth trying every pattern.

LinuxCNC Documentation 2014-12-18 119

BLDC(9) HAL Component BLDC(9)

Phases, Source - Sink

pat B-A C-A C-B A-B A-C B-C

0000 001 011 111 110 100

1001 000 010 110 111 101

2000 010 011 111 101 100

3001 011 010 110 100 101

4010 011 001 101 100 110

5011 010 000 100 101 111

6010 000 001 101 111 110

7011 001 000 100 110 111

8000 001 101 111 110 010

9001 000 100 110 111 011

10 000 010 110 111 101 001

11 001 011 111 110 100 000

12 010 011 111 101 100 000

13 011 010 110 100 101 001

14 010 000 100 101 111 011

15 011 001 101 100 110 010

16 000 100 101 111 011 010

17 001 101 100 110 010 011

18 000 100 110 111 011 001

19 001 101 111 110 010 000

20 010 110 111 101 001 000

21 011 111 110 100 000 001

22 010 110 100 101 001 011

23 011 111 101 100 000 010

24 100 101 111 011 010 000

25 101 100 110 010 011 001

26 100 110 111 011 001 000

27 101 111 110 010 000 001

28 110 111 101 001 000 010

29 111 110 100 000 001 011

30 110 100 101 001 011 010

31 111 101 100 000 010 011

32 100 101 001 011 010 110

33 101 100 000 010 011 111

34 100 110 010 011 001 101

35 101 111 011 010 000 100

36 110 111 011 001 000 100

37 111 110 010 000 001 101

38 110 100 000 001 011 111

39 111 101 001 000 010 110

40 100 000 001 011 111 110

41 101 001 000 010 110 111

42 100 000 010 011 111 101

43 101 001 011 010 110 100

44 110 010 011 001 101 100

45 111 011 010 000 100 101

46 110 010 000 001 101 111

47 111 011 001 000 100 110

120 2014-12-18 LinuxCNC Documentation

BLDC(9) HAL Component BLDC(9)

AUTHOR

Andy Pugh

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 121

BLDC_HALL3(9) HAL Component BLDC_HALL3(9)

NAME bldc_hall3 − 3-wire BLDC motor driverusing Hall sensors and trapezoidal commutation.

SYNOPSIS

The functionality of this component is nowincluded in the generic "bldc" component. This component is

likely to be removedinafuture release

DESCRIPTION

This component produces a 3-wire bipolar output. This suits upstream drivers that interpret a negative input

as a low-side drive and positive asahigh-side drive.This includes the Hostmot2 3pwmgen function, which

is likely to be the most common application of this component.

FUNCTIONS

bldc-hall3.N(requires a ﬂoating-point thread)

Interpret Hall sensor patterns and set 3-phase amplitudes

PINS bldc-hall3.N.hall1 bit in

Hall sensor signal 1

bldc-hall3.N.hall2 bit in

Hall sensor signal 2

bldc-hall3.N.hall3 bit in

Hall sensor signal 3

bldc-hall3.N.value ﬂoat in

PWM master amplitude input

bldc-hall3.N.dir bit in

Forwards / reverse selection. Negative PWM amplitudes will also reverse the motor and there will

generally be a pattern that runs the motor in each direction too.

bldc-hall3.N.A-value ﬂoat out

Output amplitude for phase A

bldc-hall3.N.B-value ﬂoat out

Output amplitude for phase B

bldc-hall3.N.C-value ﬂoat out

Output amplitude for phase C

PARAMETERS

bldc-hall3.N.pattern u32 rw (default: 25)

Commutation pattern to use, from 0 to 47. Default is type 25. Every plausible combination is

included. The table shows the excitation pattern along the top, and the pattern code on the left

hand side. The table entries are the hall patterns in H1, H2, H3 order.Common patterns are: 0 (30

degree commutation) and 26, its reverse. 17 (120 degree). 18 (alternate 60 degree). 21 (300

degree, Bodine). 22 (240 degree). 25 (60 degree commutation).

Note that a number of incorrect commutations will have non-zero net torque which might look as

if theywork, but don’treally.

If your motor lacks documentation it might be worth trying every pattern.

122 2014-12-18 LinuxCNC Documentation

BLDC_HALL3(9) HAL Component BLDC_HALL3(9)

Phases, Source - Sink

pat B-A C-A C-B A-B A-C B-C

0000 001 011 111 110 100

1001 000 010 110 111 101

2000 010 011 111 101 100

3001 011 010 110 100 101

4010 011 001 101 100 110

5011 010 000 100 101 111

6010 000 001 101 111 110

7011 001 000 100 110 111

8000 001 101 111 110 010

9001 000 100 110 111 011

10 000 010 110 111 101 001

11 001 011 111 110 100 000

12 010 011 111 101 100 000

13 011 010 110 100 101 001

14 010 000 100 101 111 011

15 011 001 101 100 110 010

16 000 100 101 111 011 010

17 001 101 100 110 010 011

18 000 100 110 111 011 001

19 001 101 111 110 010 000

20 010 110 111 101 001 000

21 011 111 110 100 000 001

22 010 110 100 101 001 011

23 011 111 101 100 000 010

24 100 101 111 011 010 000

25 101 100 110 010 011 001

26 100 110 111 011 001 000

27 101 111 110 010 000 001

28 110 111 101 001 000 010

29 111 110 100 000 001 011

30 110 100 101 001 011 010

31 111 101 100 000 010 011

32 100 101 001 011 010 110

33 101 100 000 010 011 111

34 100 110 010 011 001 101

35 101 111 011 010 000 100

36 110 111 011 001 000 100

37 111 110 010 000 001 101

38 110 100 000 001 011 111

39 111 101 001 000 010 110

40 100 000 001 011 111 110

41 101 001 000 010 110 111

42 100 000 010 011 111 101

43 101 001 011 010 110 100

44 110 010 011 001 101 100

45 111 011 010 000 100 101

46 110 010 000 001 101 111

47 111 011 001 000 100 110

LinuxCNC Documentation 2014-12-18 123

BLDC_HALL3(9) HAL Component BLDC_HALL3(9)

SEE ALSO

bldc_hall6 6-wire unipolar driverfor BLDC motors.

AUTHOR

Andy Pugh

LICENSE

GPL

124 2014-12-18 LinuxCNC Documentation

BLEND(9) HAL Component BLEND(9)

NAME blend − Perform linear interpolation between twovalues

SYNOPSIS

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

FUNCTIONS

blend.N(requires a ﬂoating-point thread)

PINS blend.N.in1 ﬂoat in

First input. If select is equal to 1.0, the output is equal to in1

blend.N.in2 ﬂoat in

Second input. If select is equal to 0.0, the output is equal to in2

blend.N.select ﬂoat in

Select input. Forvalues between 0.0 and 1.0, the output changes linearly from in2 to in1

blend.N.out ﬂoat out

Output value.

PARAMETERS

blend.N.open bit rw

If true, select values outside the range 0.0 to 1.0 give values outside the range in2 to in1. If false,

outputs are clamped to the the range in2 to in1

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 125

CHARGE_PUMP(9) HAL Component CHARGE_PUMP(9)

NAME charge_pump − Create a square-wav e for the ’charge pump’ input of some controller boards

SYNOPSIS

loadrt charge_pump

DESCRIPTION

The ’Charge Pump’ should be added to the base thread function. When enabled the output is on for one

period and offfor one period. Tocalculate the frequencyofthe output 1/(period time in seconds x 2) = hz.

Forexample if you have a base period of 100,000ns that is 0.0001 seconds and the formula would be

1/(0.0001 x 2) = 5,000 hz or 5 Khz. Two additional outputs are provided that run a factor of 2 and 4 slower

for hardware that requires a lower frequency.

FUNCTIONS

charge-pump

Toggle the output bit (if enabled)

PINS charge-pump.out bit out

Square wav e if ’enable’ is TRUE or unconnected, lowif’enable’ is FALSE

charge-pump.out-2 bit out

Square wav e at half the frequencyof’out’

charge-pump.out-4 bit out

Square wav e at a quarter of the frequencyof’out’

charge-pump.enable bit in (default: TRUE)

If FALSE, forces all ’out’ pins to be low

LICENSE

GPL

126 2014-12-18 LinuxCNC Documentation

CLARKE2(9) HAL Component CLARKE2(9)

NAME clarke2 − Two input version of Clarketransform

SYNOPSIS

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

DESCRIPTION

The Clarketransform can be used to translate a vector quantity from a three phase system (three compo-

nents 120 degrees apart) to a twophase Cartesian system.

clarke2 implements a special case of the Clarketransform, which only needs twoofthe three input phases.

In a three wire three phase system, the sum of the three phase currents or voltages must always be zero. As

aresult only twoofthe three are needed to completely deﬁne the current or voltage. clarke2 assumes that

the sum is zero, so it only uses phases A and B of the input. Since the H (homopolar) output will always be

zero in this case, it is not generated.

FUNCTIONS

clarke2.N(requires a ﬂoating-point thread)

PINS clarke2.N.a ﬂoat in

clarke2.N.b ﬂoat in

ﬁrst twophases of three phase input

clarke2.N.x ﬂoat out

clarke2.N.y ﬂoat out

cartesian components of output

SEE ALSO

clarke3 for the general case, clarkeinv for the inverse transform.

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 127

CLARKE3(9) HAL Component CLARKE3(9)

NAME clarke3 − Clarke(3phase to cartesian) transform

SYNOPSIS

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

DESCRIPTION

The Clarketransform can be used to translate a vector quantity from a three phase system (three compo-

nents 120 degrees apart) to a twophase Cartesian system (plus a homopolar component if the three phases

don’tsum to zero).

clarke3 implements the general case of the transform, using all three phases. If the three phases are known

to sum to zero, see clarke2 for a simpler version.

FUNCTIONS

clarke3.N(requires a ﬂoating-point thread)

PINS clarke3.N.a ﬂoat in

clarke3.N.b ﬂoat in

clarke3.N.c ﬂoat in

three phase input vector

clarke3.N.x ﬂoat out

clarke3.N.y ﬂoat out

cartesian components of output

clarke3.N.h ﬂoat out

homopolar component of output

SEE ALSO

clarke2 for the ’a+b+c=0’ case, clarkeinv for the inverse transform.

LICENSE

GPL

128 2014-12-18 LinuxCNC Documentation

CLARKEINV(9) HAL Component CLARKEINV(9)

NAME clarkeinv−Inv e rse Clarketransform

SYNOPSIS

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

DESCRIPTION

The inverse Clarketransform can be used rotate a vector quantity and then translate it from Cartesian coor-

dinate system to a three phase system (three components 120 degrees apart).

FUNCTIONS

clarkeinv.N(requires a ﬂoating-point thread)

PINS clarkeinv.N.x ﬂoat in

clarkeinv.N.y ﬂoat in

cartesian components of input

clarkeinv.N.h ﬂoat in

homopolar component of input (usually zero)

clarkeinv.N.theta ﬂoat in

rotation angle: 0.00 to 1.00 = 0 to 360 degrees

clarkeinv.N.a ﬂoat out

clarkeinv.N.b ﬂoat out

clarkeinv.N.c ﬂoat out

three phase output vector

SEE ALSO

clarke2 and clarke3 for the forward transform.

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 129

CLASSICLADDER(9) HAL Component CLASSICLADDER(9)

NAME classicladder − realtime software plc based on ladder logic

SYNOPSIS

loadrt classicladder_rt [numRungs=N][numBits=N][numWords=N][numTimers=N][numMonosta-

bles=N][numCounters=N][numPhysInputs=N][numPhysOutputs=N][numArithmExpr=N][num-

Sections=N][numSymbols=N][numS32in=N][numS32out=N][numFloatIn=N][numFloatOut=N]

DESCRIPTION

These pins and parameters are created by the realtime classicladder_rt module. Each period (minimum

1000000 ns), classicladder reads the inputs, evaluates the ladder logic deﬁned in the GUI, and then writes

the outputs.

PINS classicladder.0.in-NN IN bit

These bit signal pins map to %INN variables in classicladder

classicladder.0.out-NN OUT bit

These bit signal pins map to %QNN variables in classicladder Output from classicladder

classicladder.0.s32in-NN IN s32

Integer input from classicladder These s32 signal pins map to %IWNN variables in classicladder

classicladder.0.s32out-NN OUT s32

Integer output from classicladder These s32 signal pins map to %QWNN variables in classiclad-

der

classicladder.0.ﬂoatin-NN IN ﬂoat

Integer input from classicladder These ﬂoat signal pins map to %IFNN variables in classicladder

These are truncated to S32 values internally.eg7.5 will be 7

classicladder.0.ﬂoatout-NN OUT ﬂoat

Float output from classicladder These ﬂoat signal pins map to %QFNN variables in classicladder

classicladder.0.hide_gui IN bit

This bit pin hides the classicladder window, while still having the userspace code run. This is usu-

ally desirable when modbus is used, as modbus requires the userspace code to run.

PARAMETERS

classicladder.0.refresh.time RO s32

Tells you howlong the last refresh took

classicladder.0.refresh.tmax RW s32

Tells you howlong the longest refresh took

classicladder.0.ladder-state RO s32

Tells you if the program is running or not

FUNCTIONS

130 2008-11-23 LinuxCNC Documentation

CLASSICLADDER(9) HAL Component CLASSICLADDER(9)

classicladder.0.refresh FP

The rung update rate. Add this to the servothread. You can added it to a faster thread but it Will

update no faster than once every 1 millisecond (1000000 ns).

BUGS See http://wiki.linuxcnc.org/cgi-bin/wiki.pl?ClassicLadder_Ver_7.124 for the latest.

SEE ALSO

Classicladder chapters in the LinuxCNC documentation for a full description of the Classicladder syntax

and examples

http://wiki.linuxcnc.org/cgi-bin/wiki.pl?ClassicLadder_Ver_7.124

LinuxCNC Documentation 2008-11-23 131

COMP(9) HAL Component COMP(9)

NAME comp − Two input comparator with hysteresis

SYNOPSIS

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

FUNCTIONS

comp.N(requires a ﬂoating-point thread)

Update the comparator

PINS comp.N.in0 ﬂoat in

Inverting input to the comparator

comp.N.in1 ﬂoat in

Non-inverting input to the comparator

comp.N.out bit out

Normal output. True when in1 >in0 (see parameter hyst for details)

comp.N.equal bit out

Match output. True when difference between in1 and in0 is less than hyst/2

PARAMETERS

comp.N.hyst ﬂoat rw (default: 0.0)

Hysteresis of the comparator (default 0.0)

With zero hysteresis, the output is true when in1 >in0.With nonzero hysteresis, the output

switches on and offattwo different values, separated by distance hyst around the point where in1

=in0.Keep in mind that ﬂoating point calculations are neverabsolute and it is wise to always set

hyst if you intend to use equal

LICENSE

GPL

132 2014-12-18 LinuxCNC Documentation

CONSTANT(9) HAL Component CONSTANT(9)

NAME constant − Use a parameter to set the value of a pin

SYNOPSIS

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

FUNCTIONS

constant.N(requires a ﬂoating-point thread)

PINS constant.N.out ﬂoat out

PARAMETERS

constant.N.value ﬂoat rw

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 133

CONV_BIT_S32(9) HAL Component CONV_BIT_S32(9)

NAME conv_bit_s32 − Convert a value from bit to s32

SYNOPSIS

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

FUNCTIONS

conv-bit-s32.N

Update ’out’ based on ’in’

PINS conv-bit-s32.N.in bit in

conv-bit-s32.N.out s32 out

LICENSE

GPL

134 2014-12-18 LinuxCNC Documentation

CONV_BIT_U32(9) HAL Component CONV_BIT_U32(9)

NAME conv_bit_u32 − Convert a value from bit to u32

SYNOPSIS

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

FUNCTIONS

conv-bit-u32.N

Update ’out’ based on ’in’

PINS conv-bit-u32.N.in bit in

conv-bit-u32.N.out u32 out

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 135

CONV_FLOAT_S32(9) HAL Component CONV_FLOAT_S32(9)

NAME conv_ﬂoat_s32 − Convert a value from ﬂoat to s32

SYNOPSIS

loadrt conv_ﬂoat_s32 [count=N|names=name1[,name2...]]

FUNCTIONS

conv-ﬂoat-s32.N(requires a ﬂoating-point thread)

Update ’out’ based on ’in’

PINS conv-ﬂoat-s32.N.in ﬂoat in

conv-ﬂoat-s32.N.out s32 out

conv-ﬂoat-s32.N.out-of-range bit out

TRUE when ’in’ is not in the range of s32

PARAMETERS

conv-ﬂoat-s32.N.clamp bit rw

If TRUE, then clamp to the range of s32. If FALSE, then allowthe value to "wrap around".

LICENSE

GPL

136 2014-12-18 LinuxCNC Documentation

CONV_FLOAT_U32(9) HAL Component CONV_FLOAT_U32(9)

NAME conv_ﬂoat_u32 − Convert a value from ﬂoat to u32

SYNOPSIS

loadrt conv_ﬂoat_u32 [count=N|names=name1[,name2...]]

FUNCTIONS

conv-ﬂoat-u32.N(requires a ﬂoating-point thread)

Update ’out’ based on ’in’

PINS conv-ﬂoat-u32.N.in ﬂoat in

conv-ﬂoat-u32.N.out u32 out

conv-ﬂoat-u32.N.out-of-range bit out

TRUE when ’in’ is not in the range of u32

PARAMETERS

conv-ﬂoat-u32.N.clamp bit rw

If TRUE, then clamp to the range of u32. If FALSE, then allowthe value to "wrap around".

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 137

CONV_S32_BIT(9) HAL Component CONV_S32_BIT(9)

NAME conv_s32_bit − Convert a value from s32 to bit

SYNOPSIS

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

FUNCTIONS

conv-s32-bit.N

Update ’out’ based on ’in’

PINS conv-s32-bit.N.in s32 in

conv-s32-bit.N.out bit out

conv-s32-bit.N.out-of-range bit out

TRUE when ’in’ is not in the range of bit

PARAMETERS

conv-s32-bit.N.clamp bit rw

If TRUE, then clamp to the range of bit. If FALSE, then allowthe value to "wrap around".

LICENSE

GPL

138 2014-12-18 LinuxCNC Documentation

CONV_S32_FLOAT(9) HAL Component CONV_S32_FLOAT(9)

NAME conv_s32_ﬂoat − Convert a value from s32 to ﬂoat

SYNOPSIS

loadrt conv_s32_ﬂoat [count=N|names=name1[,name2...]]

FUNCTIONS

conv-s32-ﬂoat.N(requires a ﬂoating-point thread)

Update ’out’ based on ’in’

PINS conv-s32-ﬂoat.N.in s32 in

conv-s32-ﬂoat.N.out ﬂoat out

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 139

CONV_S32_U32(9) HAL Component CONV_S32_U32(9)

NAME conv_s32_u32 − Convert a value from s32 to u32

SYNOPSIS

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

FUNCTIONS

conv-s32-u32.N

Update ’out’ based on ’in’

PINS conv-s32-u32.N.in s32 in

conv-s32-u32.N.out u32 out

conv-s32-u32.N.out-of-range bit out

TRUE when ’in’ is not in the range of u32

PARAMETERS

conv-s32-u32.N.clamp bit rw

If TRUE, then clamp to the range of u32. If FALSE, then allowthe value to "wrap around".

LICENSE

GPL

140 2014-12-18 LinuxCNC Documentation

CONV_U32_BIT(9) HAL Component CONV_U32_BIT(9)

NAME conv_u32_bit − Convert a value from u32 to bit

SYNOPSIS

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

FUNCTIONS

conv-u32-bit.N

Update ’out’ based on ’in’

PINS conv-u32-bit.N.in u32 in

conv-u32-bit.N.out bit out

conv-u32-bit.N.out-of-range bit out

TRUE when ’in’ is not in the range of bit

PARAMETERS

conv-u32-bit.N.clamp bit rw

If TRUE, then clamp to the range of bit. If FALSE, then allowthe value to "wrap around".

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 141

CONV_U32_FLOAT(9) HAL Component CONV_U32_FLOAT(9)

NAME conv_u32_ﬂoat − Convert a value from u32 to ﬂoat

SYNOPSIS

loadrt conv_u32_ﬂoat [count=N|names=name1[,name2...]]

FUNCTIONS

conv-u32-ﬂoat.N(requires a ﬂoating-point thread)

Update ’out’ based on ’in’

PINS conv-u32-ﬂoat.N.in u32 in

conv-u32-ﬂoat.N.out ﬂoat out

LICENSE

GPL

142 2014-12-18 LinuxCNC Documentation

CONV_U32_S32(9) HAL Component CONV_U32_S32(9)

NAME conv_u32_s32 − Convert a value from u32 to s32

SYNOPSIS

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

FUNCTIONS

conv-u32-s32.N

Update ’out’ based on ’in’

PINS conv-u32-s32.N.in u32 in

conv-u32-s32.N.out s32 out

conv-u32-s32.N.out-of-range bit out

TRUE when ’in’ is not in the range of s32

PARAMETERS

conv-u32-s32.N.clamp bit rw

If TRUE, then clamp to the range of s32. If FALSE, then allowthe value to "wrap around".

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 143

COUNTER(9) HAL Component COUNTER(9)

NAME counter − counts input pulses (DEPRECATED)

SYNOPSIS

loadrt counter [num_chan=N]

DESCRIPTION

counter is a deprecated HAL component and will be removedinafuture release. Use the encoder compo-

nent with encoder.X.counter-mode set to TRUE.

counter is a HAL component that provides software- based counting that is useful for spindle position

sensing and maybe other things. Instead of using a real encoder that outputs quadrature, some lathes have a

sensor that generates a simple pulse stream as the spindle turns and an indexpulse once per revolution.

This component simply counts up when a "count" pulse (phase-A) is received, and if reset is enabled, resets

when the "index" (phase-Z) pulse is received.

This is of course only useful for a unidirectional spindle, as it is not possible to sense the direction of rota-

tion.

counter conforms to the "canonical encoder" interface described in the HAL manual.

FUNCTIONS

counter.capture-position (uses ﬂoating-point)

Updates the counts, position and velocity outputs based on internal counters.

counter.update-counters

Samples the phase-A and phase-Z inputs and updates internal counters.

PINS counter.N.phase-A bit in

The primary input signal. The internal counter is incremented on each rising edge.

counter.N.phase-Z bit in

The indexinput signal. When the index-enable pin is TRUE and a rising edge on phase-Z is

seen, index-enable is set to FALSE and the internal counter is reset to zero.

counter.N.index-enable bit io

counter.N.reset bit io

counter.N.counts signed out

counter.N.position ﬂoat out

counter.N.velocity ﬂoat out

These pins function according to the canonical digital encoder interface.

counter.N.position-scale ﬂoat rw

This parameter functions according to the canonical digital encoder interface.

counter.N.rawcounts signed ro

The internal counts value, updated from update-counters and reﬂected in the output pins at the

next call to capture-position.

SEE ALSO

encoder(9).inthe LinuxCNC documentation.

144 2007-01-19 LinuxCNC Documentation

DDT(9) HAL Component DDT(9)

NAME ddt − Compute the derivative ofthe input function

SYNOPSIS

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

FUNCTIONS

ddt.N(requires a ﬂoating-point thread)

PINS ddt.N.in ﬂoat in

ddt.N.out ﬂoat out

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 145

DEADZONE(9) HAL Component DEADZONE(9)

NAME deadzone − Return the center if within the threshold

SYNOPSIS

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

FUNCTIONS

deadzone.N(requires a ﬂoating-point thread)

Update out based on in and the parameters.

PINS deadzone.N.in ﬂoat in

deadzone.N.out ﬂoat out

PARAMETERS

deadzone.N.center ﬂoat rw (default: 0.0)

The center of the dead zone

deadzone.N.threshhold ﬂoat rw (default: 1.0)

The dead zone is center ±(threshhold/2)

LICENSE

GPL

146 2014-12-18 LinuxCNC Documentation

DEBOUNCE(9) HAL Component DEBOUNCE(9)

NAME debounce − ﬁlter noisy digital inputs

SYNOPSIS

loadrt debounce cfg=size[,size,...]

Creates debounce groups with the number of ﬁlters speciﬁed by (size). Every ﬁlter in the same group has

the same sample rate and delay.For example cfg=2,3 creates twoﬁlter groups with 2 ﬁlters in the ﬁrst

group and 3 ﬁlters in the second group.

DESCRIPTION

The debounce ﬁlter works by incrementing a counter wheneverthe input is true, and decrementing the

counter when it is false. If the counter decrements to zero, the output is set false and the counter ignores

further decrements. If the counter increments up to a threshold, the output is set true and the counter

ignores further increments. If the counter is between zero and the threshold, the output retains its previous

state. The threshold determines the amount of ﬁltering: a threshold of 1 does no ﬁltering at all, and a

threshold of N requires a signal to be present for N samples before the output changes state.

FUNCTIONS

debounce.G

Sample all the input pins in group G and update the output pins.

PINS debounce.G.F.in bit in

The F’th input pin in group G.

debounce.G.F.out bit out

The F’th output pin in group G. Reﬂects the last "stable" input seen on the corresponding input

pin.

debounce.G.delay signed rw

Sets the amount of ﬁltering for all pins in group G.

LinuxCNC Documentation 2007-01-16 147

EDGE(9) HAL Component EDGE(9)

NAME edge − Edge detector

SYNOPSIS

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

FUNCTIONS

edge.NProduce output pulses from input edges

PINS edge.N.in bit in

edge.N.out bit out

Goes high when the desired edge is seen on ’in’

edge.N.out-invert bit out

Goes lowwhen the desired edge is seen on ’in’

PARAMETERS

edge.N.both bit rw (default: FALSE)

If TRUE, selects both edges. Otherwise, selects one edge according to in-edge

edge.N.in-edge bit rw (default: TRUE)

If both is FALSE, selects the one desired edge: TRUE means falling, FALSE means rising

edge.N.out-width-ns s32 rw (default: 0)

Time in nanoseconds of the output pulse

edge.N.time-left-ns s32 r

Time left in this output pulse

edge.N.last-in bit r

Previous input value

LICENSE

GPL

148 2014-12-18 LinuxCNC Documentation

ENCODER(9) HAL Component ENCODER(9)

NAME encoder − software counting of quadrature encoder signals

SYNOPSIS

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

DESCRIPTION

encoder is used to measure position by counting the pulses generated by a quadrature encoder.Asasoft-

ware-based implementation it is much less expensive than hardware, but has a limited maximum count rate.

The limit is in the range of 10KHz to 50KHz, depending on the computer speed and other factors. If better

performance is needed, a hardware encoder counter is a better choice. Some hardware-based systems can

count at MHz rates.

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 sepa-

rated by commas.

The num_chan= and names= speciﬁers are mutually exclusive.Ifneither num_chan= nor names= are

speciﬁed, the default value is three.

encoder has a one-phase, unidirectional mode called counter.Inthis mode, the phase-B input is ignored;

the counts increase on each rising edge of phase-A.This mode may be useful for counting a unidirectional

spindle with a single input line, though the noise-resistant characteristics of quadrature are lost.

FUNCTIONS

encoder.update-counters (no ﬂoating-point)

Does the actual counting, by sampling the encoder signals and decoding the quadrature wav e-

forms. Must be called as frequently as possible, preferably twice as fast as the maximum desired

count rate. Operates on all channels at once.

encoder.capture-position (uses ﬂoating point)

Captures the rawcounts from update-counters and performs scaling and other necessary conver-

sion, handles counter rollover, etc. Can (and should) be called less frequently than update-coun-

ters.Operates on all channels at once.

NAMING

The names for pins and parameters are preﬁxed as:

encoder.N. for N=0,1,...,num-1 when using num_chan=num

nameN. for nameN=name1,name2,... when using names=name1,name2,...

The encoder.N. format is shown in the following descriptions.

PINS encoder.N.counter-mode bit i/o

Enables counter mode. When true, the counter counts each rising edge of the phase-A input,

ignoring the value on phase-B. This is useful for counting the output of a single channel (non-

quadrature) sensor.When false (the default), it counts in quadrature mode.

encoder.N.counts s32 out

Position in encoder counts.

encoder.N.index-enable bit i/o

When true, counts and position are reset to zero on the next rising edge of Phase-Z.Atthe same

time, index-enable is reset to zero to indicate that the rising edge has occurred.

LinuxCNC Documentation 2009-04-15 149

ENCODER(9) HAL Component ENCODER(9)

encoder.N.phase-A bit in

Quadrature input for encoder channel N.

encoder.N.phase-B bit in

Quadrature input.

encoder.N.phase-Z bit in

Indexpulse input.

encoder.N.position ﬂoat out

Position in scaled units (see position-scale)

encoder.N.position-interpolated ﬂoat out

Position in scaled units, interpolated between encoder counts. Only valid when velocity is approx-

imately constant and above min-velocity-estimate.Donot use for position control.

encoder.N.position-scale ﬂoat i/o

Scale factor,incounts per length unit. Forexample, if position-scale is 500, then 1000 counts of

the encoder will be reported as a position of 2.0 units.

encoder.N.rawcounts s32 out

The rawcount, as determined by update-counters.This value is updated more frequently than

counts and position.Itisalso unaffected by reset or the indexpulse.

encoder.N.reset bit in

When true, counts and position are reset to zero immediately.

encoder.N.velocity ﬂoat out

Velocity in scaled units per second. encoder uses an algorithm that greatly reduces quantization

noise as compared to simply differentiating the position output. When the magnitude of the true

velocity is belowmin-velocity-estimate, the velocity output is 0.

encoder.N.x4-mode bit i/o

Enables times-4 mode. When true (the default), the counter counts each edge of the quadrature

waveform (four counts per full cycle). When false, it only counts once per full cycle. In counter-

mode,this parameter is ignored.

encoder.N.latch-input bit in

encoder.N.latch-falling bit in (default: TRUE)

encoder.N.latch-rising bit in (default: TRUE)

encoder.N.counts-latched s32 out

encoder.N.position-latched ﬂoat out

Update counts-latched and position-latched on the rising and/or falling edges of latch-input as

indicated by latch-rising and latch-falling.

encoder.N.counter-mode bit rw

Enables counter mode. When true, the counter counts each rising edge of the phase-A input,

ignoring the value on phase-B. This is useful for counting the output of a single channel (non-

quadrature) sensor.When false (the default), it counts in quadrature mode. encoder.N.capture-

position.tmax s32 rw Maximum number of CPU cycles it took to execute this function.

PARAMETERS

Parameter names for num_chan= speciﬁer are:

encoder.N.the_parameter_name

Parameter names for names= speciﬁer are:

nameN.the_parameter_name

encoder.N.min-velocity-estimate ﬂoat rw (default: 1.0)

Determine the minimum true velocity magnitude at which velocity will be estimated as nonzero

and postition-interpolated will be interpolated. The units of min-velocity-estimate are the same

as the units of velocity.Setting this parameter too lowwill cause it to takealong time for velocity

150 2009-04-15 LinuxCNC Documentation

ENCODER(9) HAL Component ENCODER(9)

to go to 0 after encoder pulses have stopped arriving.

LinuxCNC Documentation 2009-04-15 151

ENCODER_RATIO(9) HAL Component ENCODER_RATIO(9)

NAME encoder_ratio − an electronic gear to synchronize twoaxes

SYNOPSIS

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

DESCRIPTION

encoder_ratio can be used to synchronize twoaxes(likean"electronic gear"). It counts encoder pulses

from both axes in software, and produces an error value that can be used with a PID loop to makethe slave

encoder track the master encoder with a speciﬁc ratio.

This module supports up to eight axis pairs. The number of pairs is set by the module parameter

num_chan.Alternatively,specify names= and unique names separated by commas.

The num_chan= and names= speciﬁers are mutually exclusive.Ifneither num_chan= nor names= are

speciﬁed, the default value is one.

FUNCTIONS

encoder-ratio.sample

Read all input pins. Must be called at twice the maximum desired count rate.

encoder-ratio.update (uses ﬂoating-point)

Updates all output pins. May be called from a slower thread.

NAMING

The names for pins and parameters are preﬁxed as:

encoder-ratio.N. for N=0,1,...,num-1 when using num_chan=num

nameN. for nameN=name1,name2,... when using names=name1,name2,...

The encoder-ratio.N. format is shown in the following descriptions.

PINS encoder-ratio.N.master-A bit in

encoder-ratio.N.master-B bit in

encoder-ratio.N.slave-A bit in

encoder-ratio.N.slave-B bit in

The encoder channels of the master and slave axes

encoder-ratio.N.enable bit in

When the enable pin is FALSE, the error pin simply reports the slave axis position, in revolutions.

As such, it would normally be connected to the feedback pin of a PID block for closed loop con-

trol of the slave axis. Normally the command input of the PID block is left unconnected (zero), so

the slave axis simply sits still. Howeverwhen the enable input goes TRUE, the error pin becomes

the slave position minus the scaled master position. The scale factor is the ratio of master teeth to

slave teeth. As the master moves, error becomes non-zero, and the PID loop will drive the slave

axis to track the master.

encoder-ratio.N.error ﬂoat out

The error in the position of the slave (in revolutions)

PARAMETERS

encoder-ratio.N.master-ppr unsigned rw

encoder-ratio.N.slave-ppr unsigned rw

The number of pulses per revolution of the master and slave axes

152 2007-01-16 LinuxCNC Documentation

ENCODER_RATIO(9) HAL Component ENCODER_RATIO(9)

encoder-ratio.N.master-teeth unsigned rw

encoder-ratio.N.slave-teeth unsigned rw

The number of "teeth" on the master and slave gears.

SEE ALSO

encoder(9)

LinuxCNC Documentation 2007-01-16 153

ESTOP_LATCH(9) HAL Component ESTOP_LATCH(9)

NAME estop_latch − Software ESTOP latch

SYNOPSIS

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

DESCRIPTION

This component can be used as a part of a simple software ESTOP chain.

It has twostates: "OK" and "Faulted".

The initial state is "Faulted". When faulted, the out-ok output is false, the fault-out output is true, and the

watchdog output is unchanging.

The state changes from "Faulted" to "OK" when all these conditions are true:

•fault-in is false

•ok-in is true

•reset changes from false to true

When "OK", the out-ok output is true, the fault-out output is false, and the watchdog output is toggling.

The state changes from "OK" to "Faulted" when any of the following are true:

•fault-in is true

•ok-in is false

To facilitate using only a single fault source, ok-in and fault-en are both set to the non-fault-causing value

when no signal is connected. Forestop-latch to everbeable to signal a fault, at least one of these inputs

must be connected.

Typically,anexternal fault or estop input is connected to fault-in,iocontrol.0.user-request-enable is con-

nected to reset,and ok-out is connected to iocontrol.0.emc-enable-in.

In morecomplex systems, it may be moreappropriate to use classicladder to manage the software

portion of the estop chain.

FUNCTIONS

estop-latch.N

PINS estop-latch.N.ok-in bit in (default: true)

estop-latch.N.fault-in bit in (default: false)

estop-latch.N.reset bit in

estop-latch.N.ok-out bit out (default: false)

estop-latch.N.fault-out bit out (default: true)

estop-latch.N.watchdog bit out

LICENSE

GPL

154 2014-12-18 LinuxCNC Documentation

FEEDCOMP(9) HAL Component FEEDCOMP(9)

NAME feedcomp − Multiply the input by the ratio of current velocity to the feed rate

SYNOPSIS

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

FUNCTIONS

feedcomp.N(requires a ﬂoating-point thread)

PINS feedcomp.N.out ﬂoat out

Proportionate output value

feedcomp.N.in ﬂoat in

Reference value

feedcomp.N.enable bit in

Turn compensation on or off

feedcomp.N.vel ﬂoat in

Current velocity

PARAMETERS

feedcomp.N.feed ﬂoat rw

Feed rate reference value

NOTESNote that if enable is false, out = in

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 155

FLIPFLOP(9) HAL Component FLIPFLOP(9)

NAME ﬂipﬂop − D type ﬂip-ﬂop

SYNOPSIS

loadrt ﬂipﬂop [count=N|names=name1[,name2...]]

FUNCTIONS

ﬂipﬂop.N

PINS ﬂipﬂop.N.data bit in

data input

ﬂipﬂop.N.clk bit in

clock, rising edge writes data to out

ﬂipﬂop.N.set bit in

when true, force out true

ﬂipﬂop.N.reset bit in

when true, force out false; overrides set

ﬂipﬂop.N.out bit io

output

LICENSE

GPL

156 2014-12-18 LinuxCNC Documentation

GANTRYKINS(9) HAL Component GANTRYKINS(9)

NAME gantrykins − A kinematics module that maps one axis to multiple joints

SYNOPSIS

loadrt gantrykins coordinates=axisletters

Specifying gantry joint mapping via loadrt

The coordinates= parameter speciﬁes the initial gantry joint mapping. Each axis letter is mapped to a

joint, starting from 0. So coordinates=XYYZ maps the X axis to joint 0, the Y axis to joint 1 and 2, and

the Z axis to joint 3. If not speciﬁed, the default mapping is coordinates=XYZABC.Coordinate letters

may be speciﬁed in uppercase or lowercase.

Anote about joints and axes

LinuxCNC makes a distinction between joints and axes: a joint is something controlled by a motor,and an

axis is a coordinate you can move via G-code. Youcan also jog joints or jog axes.

Agantry has twojoints controlling one axis, and this requires a bit of special care.

Homing always happens in joint mode (aka Free mode). The twojoints of a gantry’saxis must be homed

together,sotheymust have the same [AXIS_n]HOME_SEQUENCE in the .ini ﬁle.

Jogging of a gantry must happen in world mode (aka Teleop mode). If you jog a gantry in joint mode (Free

mode), you will move just one of the joints, and the gantry will rack. In contrast, if you jog a gantry in

world mode (Teleop mode), it’sthe axis that jogs: linuxcnc will coordinate the motion of the twojoints that

makeupthe axis, both joints will move together,and the gantry will stay square.

The Axis GUI has provisions for jogging in joint mode (Free) and in world mode (Teleop). Use the "$"

hotkey,orthe Viewmenu to switch between them.

Joint-mode (aka Free mode) supports continuous and incremental jogging. World-mode (aka Teleop mode)

only supports continuous jogging.

KINEMATICS

In the inverse kinematics, each joint gets the value of its corresponding axis. In the forward kinematics,

each axis gets the value of the highest numbered corresponding joint. Forexample, with coordi-

nates=XYYZ the Y axis position comes from joint 2, not joint 1.

FUNCTIONS

None.

PINS None.

PARAMETERS

gantrykins.joint-N(s32)

Speciﬁes the axis mapped to joint N.The values 0 through 8 correspond to the axes XYZ-

ABCUVW.Itispreferable to use the "coordinates=" parameter at loadrt-time rather than setting

the joint-N parameters later,because the gantrykins module prints the joint-to-axis mapping at

loadrt-time, and having that output correct is nice.

LinuxCNC Documentation 2010-10-12 157

GANTRYKINS(9) HAL Component GANTRYKINS(9)

NOTESgantrykins must be loaded before motion.

SEE ALSO

Kinematics section in the LinuxCNC documentation

LICENSE

GPL

158 2010-10-12 LinuxCNC Documentation

GEARCHANGE(9) HAL Component GEARCHANGE(9)

NAME gearchange − Select from one twospeed ranges

SYNOPSIS

The output will be a value scaled for the selected gear,and clamped to the min/max values for that gear.

The scale of gear 1 is assumed to be 1, so the output device scale should be chosen accordingly.The scale

of gear 2 is relative togear 1, so if gear 2 runs the spindle 2.5 times as fast as gear 1, scale2 should be set to

2.5.

FUNCTIONS

gearchange.N(requires a ﬂoating-point thread)

PINS gearchange.N.sel bit in

Gear selection input

gearchange.N.speed-in ﬂoat in

Speed command input

gearchange.N.speed-out ﬂoat out

Speed command to DAC/PWM

gearchange.N.dir-in bit in

Direction command input

gearchange.N.dir-out bit out

Direction output - possibly inverted for second gear

PARAMETERS

gearchange.N.min1 ﬂoat rw (default: 0)

Minimum allowed speed in gear range 1

gearchange.N.max1 ﬂoat rw (default: 100000)

Maximum allowed speed in gear range 1

gearchange.N.min2 ﬂoat rw (default: 0)

Minimum allowed speed in gear range 2

gearchange.N.max2 ﬂoat rw (default: 100000)

Maximum allowed speed in gear range 2

gearchange.N.scale2 ﬂoat rw (default: 1.0)

Relative scale of gear 2 vs. gear 1 Since it is assumed that gear 2 is "high gear", scale2 must be

greater than 1, and will be reset to 1 if set lower.

gearchange.N.rev erse bit rw (default: 0)

Set to 1 to reverse the spindle in second gear

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 159

gladevcp(9) HAL Component gladevcp(9)

NAME gladevcp − displays Virtual control Panels built with GTK / GLADE

SYNOPSIS

loadusr gladevcp [-c componentname0xN][-g WxH+Xoffset+Yoffset0xN][-H halcmdﬁle] [-x win-

dowid] gladeﬁle.glade

DESCRIPTION

gladevcp parses a glade ﬁle and displays the widgets in a window. Then calls gladevcp_makepins which

again parses the gladeﬁle looking for speciﬁc HAL widgets then makes HAL pins and sets up updating for

them. The HAL component name defaults to the basename of the glade ﬁle. The -x option directs glade-

vcp to reparent itself under this X windowidinstead of creating its own toplevelwindow. The -H option

passes an input ﬁle for halcmd to be run after the gladevcp component is initialized. This is used in Axis

when running gladevcp under a tab with the EMBED_TAB_NAME/EMBED_TAB_COMMAND ini ﬁle

feature.

gladevcp supports gtkbuilder or libglade ﬁles though some widgets are not fully supported in gtkbuilder

yet.

ISSUESFornow system links need to be added in the glade library folders to point to our newwidgets and catalog

ﬁles. look in lib/python/gladevcp/READ_ME for details

160 2010-08-24 LinuxCNC Documentation

GRAY2BIN(9) HAL Component GRAY2BIN(9)

NAME gray2bin − convert a gray-code input to binary

SYNOPSIS

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

DESCRIPTION

Converts a gray-coded number into the corresponding binary value

FUNCTIONS

gray2bin.N

PINS gray2bin.N.in u32 in

gray code in

gray2bin.N.out u32 out

binary code out

AUTHOR

andy pugh

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 161

HM2_7I43(9) HAL Component HM2_7I43(9)

NAME hm2_7i43 − LinuxCNC HAL driverfor the Mesa Electronics 7i43 EPP Anything IO board with HostMot2

ﬁrmware.

SYNOPSIS

loadrt hm2_7i43 [ioaddr=N[,N...]] [ioaddr_hi=N[,N...]] [epp_wide=N[,N...]] [conﬁg="str[,str...]"]

[debug_epp=N[,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. 0means to use ioaddr +

0x400.

epp_wide [default: 1]

Set to zero to disable the "wide EPP mode". "Wide" mode allows a 16- and 32-bit EPP trans-

fers, which can reduce the time spent in the read and write functions. However, this may not

work on all EPP parallel ports.

conﬁg [default: ""]

HostMot2 conﬁg strings, described in the hostmot2(9) manpage.

debug_epp [default: 0]

Developer/debug use only! Enable debug logging of most EPP transfers.

DESCRIPTION

hm2_7i43 is a device driverthat interfaces the Mesa 7i43 board with the HostMot2 ﬁrmware to the Linux-

CNC HAL. Both the 200K and the 400K FPGAs are supported.

The drivertalks with the 7i43 overthe parallel port, not overUSB. USB can be used to power the 7i43, but

not to talk to it. USB communication with the 7i43 will not be supported anytime soon, since USB has

poor real-time qualities.

The driverprograms the board’sFPGA with ﬁrmware when it registers the board with the hostmot2 driver.

The old bﬂoad(1) ﬁrmware loading method is not used anymore. Instead the ﬁrmware to load is speciﬁed

in the conﬁg modparam, as described in the hostmot2(9) manpage, in the conﬁg modparam section.

Some parallel ports require special initialization before theycan be used. LinuxCNC provides a kernel

driverthat does this initialization called probe_parport. Load this driverbefore loading hm2_7i43, by

putting "loadrt probe_parport" in your .hal ﬁle.

Jumper settings

To send the FPGA conﬁguration from the PC, the board must be conﬁgured to get its ﬁrmware from the

EPP port. To dothis, jumpers W4 and W5 must both be down, ie toward the USB connector.

The board must be conﬁgured to power on whether or not the USB interface is active.This is done by set-

ting jumper W7 up, ie awayfrom the edge of the board.

Communicating with the board

The 7i43 communicates with the LinuxCNC computer overEPP,the Enhanced Parallel Port. This provides

about 1 MBps of throughput, and the communication latencyisvery predictable and reasonably low.

The parallel port must support EPP 1.7 or EPP 1.9. EPP 1.9 is prefered, but EPP 1.7 will work too. The

EPP mode of the parallel port is sometimes a setting in the BIOS.

Note that the popular "NetMOS" aka "MosChip 9805" PCI parport cards do not work.Theydonot meet

the EPP spec, and cannot be reliably used with the 7i43. Youhav e to ﬁnd another card, sorry.

EPP is very reliable under normal circumstances, but bad cabling or excessively long cabling runs may

162 2008-05-13 LinuxCNC Documentation

HM2_7I43(9) HAL Component HM2_7I43(9)

cause communication timeouts. The driverexports a parameter named hm2_7i43.<BoardNum>.io_error to

inform HAL of this condition. When the driverdetects an EPP timeout, it sets io_error to True and stops

communicating with the 7i43 board. Setting io_error back to False makes the driverstart trying to commu-

nicate with the 7i43 again.

Access to the EPP bus is not threadsafe: only one realtime thread may access the EPP bus.

SEE ALSO

hostmot2(9)

LICENSE

GPL

LinuxCNC Documentation 2008-05-13 163

HM2_7I90(9) HAL Component HM2_7I90(9)

NAME hm2_7i90 − LinuxCNC HAL driverfor the Mesa Electronics 7i90 EPP Anything IO board with HostMot2

ﬁrmware.

SYNOPSIS

loadrt hm2_7i90 [ioaddr=N[,N...]] [ioaddr_hi=N[,N...]] [epp_wide=N[,N...]] [debug_epp=N[,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. 0means to use ioaddr +

0x400.

epp_wide [default: 1]

Set to zero to disable the "wide EPP mode". "Wide" mode allows a 16- and 32-bit EPP trans-

fers, which can reduce the time spent in the read and write functions. However, this may not

work on all EPP parallel ports.

debug_epp [default: 0]

Developer/debug use only! Enable debug logging of most EPP transfers.

DESCRIPTION

hm2_7i90 is a device driverthat interfaces the Mesa 7i90 board with the HostMot2 ﬁrmware to the Linux-

CNC HAL.

The 7i90 ﬁrmware is ﬁxed, it is not programmed by the driveratload time.

The drivertalks with the 7i90 overthe parallel port, via EPP.

Some parallel ports require special initialization before theycan be used. LinuxCNC provides a kernel

driverthat does this initialization called probe_parport. Load this driverbefore loading hm2_7i90, by

putting "loadrt probe_parport" in your .hal ﬁle.

The hm2_7i90 driverrequires an in-kernel EPP communications API. This is provided by the ’epp’ driver.

Load this driverbefore loading hm2_7i90, by putting ’loadrt epp’ in your .hal ﬁle.

Communicating with the board

The 7i90 communicates with the LinuxCNC computer overEPP,the Enhanced Parallel Port. This provides

about 1 MBps of throughput, and the communication latencyisvery predictable and reasonably low.

The parallel port must support EPP 1.7 or EPP 1.9. EPP 1.9 is prefered, but EPP 1.7 will work too. The

EPP mode of the parallel port is sometimes a setting in the BIOS.

Note that the popular "NetMOS" aka "MosChip 9805" PCI parport cards do not work.Theydonot meet

the EPP spec, and cannot be reliably used with the 7i90. Youhav e to ﬁnd another card, sorry.

EPP is very reliable under normal circumstances, but bad cabling or excessively long cabling runs may

cause communication timeouts. The driverexports a parameter named hm2_7i90.<BoardNum>.io_error to

inform HAL of this condition. When the driverdetects an EPP timeout, it sets io_error to True and stops

communicating with the 7i90 board. Setting io_error back to False makes the driverstart trying to commu-

nicate with the 7i90 again.

Access to the EPP bus is not threadsafe: only one realtime thread may access the EPP bus.

SEE ALSO

hostmot2(9)

164 2013-10-27 LinuxCNC Documentation

HM2_7I90(9) HAL Component HM2_7I90(9)

LICENSE

GPL

LinuxCNC Documentation 2013-10-27 165

HM2_PCI(9) HAL Component HM2_PCI(9)

NAME hm2_pci − LinuxCNC HAL driverfor the Mesa Electronics PCI-based Anything IO boards, with HostMot2

ﬁrmware.

SYNOPSIS

loadrt hm2_pci [conﬁg="str[,str...]"]

conﬁg [default: ""]

HostMot2 conﬁg strings, described in the hostmot2(9) manpage.

DESCRIPTION

hm2_pci is a device driverthat interfaces Mesa’sPCI and PC-104/Plus based Anything I/O boards (with the

HostMot2 ﬁrmware) to the LinuxCNC HAL.

The supported boards are: the 5i20, 5i21, 5i22, 5i23, 5i24, and 5i25 (all on PCI); the 4i65, 4i68, and 4i69

(on PC-104/Plus), and the 3x20 (using a 6i68 or 7i68 carrier card) and 6i25 (on PCI Express).

The driveroptionally programs the board’sFPGA with ﬁrmware when it registers the board with the host-

mot2 driver. The ﬁrmware to load is speciﬁed in the conﬁg modparam, as described in the hostmot2(9)

manpage, in the conﬁg modparam section.

SEE ALSO

hostmot2(9)

LICENSE

GPL

166 2008-05-13 LinuxCNC Documentation

HOSTMOT2(9) HAL Component HOSTMOT2(9)

NAME hostmot2 − LinuxCNC HAL driverfor the Mesa Electronics HostMot2 ﬁrmware.

SYNOPSIS

See the conﬁg modparam section belowfor Mesa card conﬁguration. 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 driverthat interfaces the Mesa HostMot2 ﬁrmware to the LinuxCNC HAL. This

driverbyitself does nothing, the boards that actually run the ﬁrmware require their own drivers before any-

thing 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 ﬁrmware provides modules such as encoders, PWM generators, step/dir generators, and gen-

eral purpose I/O pins (GPIOs). These things are called "Modules". The ﬁrmware is conﬁgured, at

ﬁrmware compile time, to provide zero or more instances of each of these Modules.

Board I/O Pins

The HostMot2 ﬁrmware 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 conﬁgured, at board-driverload time, to serveone of twopurposes: either as a particu-

lar 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’spins are used by the Module

instances.

The user can disable Module instances at board-driverload time, by specifying a hostmot2 conﬁg string

modparam. Anypins which belong to Module instances that have been disabled automatically become

GPIOs.

All IO pins have some HAL presence, whether theybelong 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 ﬂexible

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.

conﬁg modparam

All the board-drivermodules (hm2_pci and hm2_7i43) accept a load-time modparam of type string array,

named "conﬁg". This array has one conﬁg string for each board the drivershould use. Each board’sconﬁg

string is passed to and parsed by the hostmot2 driverwhen the board-driverregisters the board.

The conﬁg 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 conﬁg array from each other.

Forexample, if your control computer has one 5i20 and one 5i23 you might load the hm2_pci driverwith a

HAL command (in halcmd) something likethis:

loadrt hm2_pci conﬁg="ﬁrmware=hm2/5i20/SVST8_4.BIT num_encoders=3 num_pwmgens=3 num_stepgens=3,ﬁrmwar

Note: this assumes that the hm2_pci driverdetects the 5i20 ﬁrst and the 5i23 second. If the detection order

does not match the order of the conﬁg strings, the hostmot2 driverwill refuse to load the ﬁrmware and the

board-driver(hm2_pci or hm2_7i43) will fail to load. To the best of my knowledge, there is no way to pre-

dict 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 movedaround. Best to try loading it and see what the detection order is.

The valid entries in the format string are:

[ﬁrmware=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]

ﬁrmware [optional]

Load the ﬁrmware speciﬁed by F into the FPGA on this board. If no "ﬁrmware=F"

string is speciﬁed, the FPGA will not be re-programmed but may continue to run a previ-

ously downloaded ﬁrmware.

The requested ﬁrmware F is fetched by udev. udevsearches for the ﬁrmware in the sys-

tem’sﬁrmware search path, usually /lib/ﬁrmware. F typically has the form

"hm2/<BoardType>/ﬁle.bit"; a typical value for F might be "hm2/5i20/SVST8_4.BIT".

The hostmot2 ﬁrmware ﬁles are supplied by the hostmot2-ﬁrmware packages, available

from linuxcnc.organd can normally be installed by entering the command "sudo apt-get

install hostmot2-ﬁrmware-5i23" to install the support ﬁles for the 5i23 for example.

The 5i25 / 6i25 come pre-programmed with ﬁrmware and no "ﬁrmware=" string should

be used with these cards. Tochange the ﬁrmware on a 5i25 or 6i25 the "mesaﬂash" utility

should be used (available from Mesa). It is perfectly valid and reasonable to load these

cards with no conﬁg 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 num-

ber to 0. There is only everone 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 ﬁrst 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

ﬁrmware, the board will fail to register.

168 2008-05-13 LinuxCNC Documentation

HOSTMOT2(9) HAL Component HOSTMOT2(9)

ssi_chan_N [optional, default: ""]

Speciﬁes howthe bit stream from a Synchronous Serial Interface device will be inter-

preted. There should be an entry for each device connected. Only channels with a format

speciﬁer 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: ""]

Speciﬁes howthe bit stream from a Fanuc absolute encoder will be interpreted. There

should be an entry for each device connected. Only channels with a format speciﬁer will

be enabled. (as the software can not guess data rates and bit lengths)

num_resolvers [optional, default: -1]

Only enable the ﬁrst N resolvers. If N = -1 then all resolvers are enabled. This module

does not work with generic resolvers (unlikethe 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 ﬁrst 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

ﬁrmware, the board will fail to register.

num_3pwmgens [optional, default: -1]

Only enable the ﬁrst 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 ﬁrmware, the board will fail to register.

num_stepgens [optional, default: -1]

Only enable the ﬁrst N stepgens. If N is -1, all stepgens are enabled. If N is 0, no step-

gens are enabled. If N is greater than the number of stepgens available in the ﬁrmware,

the board will fail to register.

stepgen_width [optional, default: 2]

Used to mask extra, unwanted, stepgen pins. Stepper drivestypically

require only twopins (step and dir) but the Hostmot2 stepgen can drive

up to 8 output pins for specialised applications (depending on

ﬁrmware). 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 ﬁrmware used and the number of physical con-

nections on the board. These are arranged in 1-4 ports of 1 to 8 chan-

nels.

Some Smart Serial (SSLBP) cards offer more than one load-time con-

ﬁguration, 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 anyposition disables that channel

and makes the corresponding FPGA pins available as GPIO.

The string can be up to 8 characters long, and if it deﬁnes 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 driverwill auto-detect connected devices, no further conﬁg-

uration should be needed. Unconnected channels will default to GPIO,

LinuxCNC Documentation 2008-05-13 169

HOSTMOT2(9) HAL Component HOSTMOT2(9)

butthe pin values will vary semi-randomly during boot when card-

detection runs, to it is best to actively disable anychannel that is to be

used for GPIO.

num_bspis [optional, default: -1]

Only enable the ﬁrst N Buffered SPI drivers. If N is -1 then all the driv-

ers are enabled. Each BSPI drivercan address 16 devices.

num_leds [optional, default: -1]

Only enable the ﬁrst 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 speciﬁed, this turns on a rawaccess mode, whereby a user can peek

and pokethe ﬁrmware from HAL. See RawMode below.

dpll The hm2dpll module has pins like"hm2_<BoardType>.<BoardNum>.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 speciﬁed 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:

(ﬂoat, in) hm2_<BoardType>.<BoardNum>.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

slowencoders it will need to be increased.

(ﬂoat, in) hm2_<BoardType>.<BoardNum>.dpll.base-freq-khz

This pin sets the base frequencyofthe phase-locked loop. by default it will be

set to the nominal frequencyofthe thread in which the PLL is running and wil

not normally need to be changed.

(ﬂoat, out) hm2_<BoardType>.<BoardNum>.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_<BoardType>.<BoardNum>.dpll.time-const"

The ﬁlter time-constant for the PLL. Default 40960 (0xA000)

(u32, in) hm2_<BoardType>.<BoardNum>.dpll.plimit"

Sets the phase adjustment limit of the PLL. If the value is zero then the PLL will

free-run at the base frequencyindependent of the servothread rate. This is prob-

ably 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_<BoardType>.<BoardNum>.dpll.ddsize

Used internally by the driver, likely to disappear.

(u32, in) hm2_<BoardType>.<BoardNum>.dpll.prescale

Prescale factor for the rate generator.Default 1.

encoderEncoders have names like"hm2_<BoardType>.<BoardNum>.encoder.<Instance>".

"Instance" is a two-digit number that corresponds to the HostMot2 encoder instance num-

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

ﬁrst 5i20 board is: hm2_5i20.0.encoder.01.position (this assumes that the ﬁrmware in that

board is conﬁgured so that this HAL object is available)

Each encoder uses three or four input IO pins, depending on howthe ﬁrmware was com-

piled. 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 compo-

nent. Each encoder instance has the following pins and parameters:

Pins:

(s32 out) count

Number of encoder counts since the previous reset.

(ﬂoat out) position

Encoder position in position units (count / scale).

(ﬂoat 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 driverdoes not reset this pin to

FALSE after resetting the count to 0, that is the user’sjob.

(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 indexorreset.

Parameters:

LinuxCNC Documentation 2008-05-13 171

HOSTMOT2(9) HAL Component HOSTMOT2(9)

(ﬂoat r/w) scale

Converts from ’count’ units to ’position’ units.

(bit r/w) index-invert

If set to True, the rising edge of the Indexinput pin triggers the Indexevent (if

index-enable is True). If set to False, the falling edge triggers.

(bit r/w) index-mask

If set to True, the Indexinput 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 Indextohav e 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) ﬁlter

If set to True (the default), the quadrature counter needs 15 clocks to register a

change on anyofthe three input lines (anypulse 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.

(ﬂoat 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 drivercan 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 speciﬁes howlong 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 moni-

tor whether the problem has been addressed by conﬁg changes. Solutions to the problem

dpend on whether the encoder read is being triggered by the hm2dpll phase-locked-loop

timer (described above)orbythe 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 speciﬁed in the loadrt command line. Atypical 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 low-

levelcode.

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 deﬁned, eveniftheyare not used. There is a limit of 64 bits in total.

The valid format characters and the pins theycreate are:

p: (Pad). Does not create anypins, used to ignore sections of the bit stream that are not

required.

b: (Boolean).

(bit, out) hm2_XiXX.N.ssi.MM.<name>. If anybits in the designated ﬁeld

width are non-zero then the HAL pin will be "true".

(bit, out) hm2_XiXX.N.ssi.MM.<name>-not. An inverted version of the above,

the HAL pin will be "true" if all bits in the ﬁeld are zero.

u: (Unsigned)

(ﬂoat, out) hm2_XiXX.N.ssi.MM.<name>. 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 ﬁeld 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)

(ﬂoat, out) hm2_XiXX.N.ssi.MM.<name>. The value of the bits interpreted as

a2scomplement signed number then scaled similarly to the unsigned variant,

except symmetrical around zero.

f: (bitField)

(bit, out) hm2_XiXX.N.ssi.MM.<name>-NN. The value of each individual bit

in the data ﬁeld. NN starts at 00 up to the number of bits in the ﬁeld.

(bit, out) hm2_XiXX.N.ssi.MM.<name>-NN-not. An inverted version of the

individual bit values.

e: (Encoder)

(s32, out) hm2_XiXX.N.ssi.MM.<name>.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.<name>.rawcounts. The lower 32 bits of the

total encoder counts. The pin is not affected by reset and index.

(ﬂoat, out) hm2_XiXX.N.ssi.MM.<name>.position. The encoder position in

machine units. This is calculated from the full 64-bit buffers so will showatrue

value evenafter the counts pins have wrapped. It is zeroed by reset and index

enable.

(bit, IO) hm2_XiXX.N.ssi.MM.<name>.index-enable. When this pin is set

"true" the module will wait until the rawencoder counts next passes through an

integer multiple of the number of counts speciﬁed by counts-per-revparameter

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.<name>.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 full-

turn counts in separate, non-contiguous ﬁelds. This tag deﬁnes the high-order

bits of such an encoder module. There can be only one h and one l tag per chan-

nel, the behaviour with multiple such channels will be undeﬁned.

l: (Split encoder,low-order bits)

Loworder bits (see "h")

g: (Gray-code). This is a modiﬁer 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:

Tw o parameters is universally created for all SSI instances

(ﬂoat r/w) hm2_XiXX.N.ssi.MM.frequency-khz

This parameter sets the SSI clock frequency. The units are kHz, so 500 will give

aclock frequencyof500,000 Hz.

(u32 r/w) hm2_XiXX.N.ssi.MM.timer-num

This parameter allocates the SSI module to a speciﬁc hm2dpll timer instance.

This pin is only of use in ﬁrmwares 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,bysetting to a nonexistent timer

number,orto0.

Other parameters depend on the data types speciﬁed in the conﬁg string.

p: (Pad) No Parameters.

b: (Boolean) No Parameters.

u: (Unsigned)

(ﬂoat, r/w) hm2_XiXX.N.ssi.MM.<name>.scalemax. The scaling factor for the

channel.

s: (Signed)

(ﬂoat, r/w) hm2_XiXX.N.ssi.MM.<name>.scalemax. The scaling factor for the

channel.

f: (bitField): No parameters.

e: (Encoder):

(ﬂoat, r/w) hm2_XiXX.N.ssi.MM.<name>.scale: (ﬂoat, r.w) The encoder scale

in counts per machine unit.

(u32, r/w) hm2_XiXX.N.ssi.MM.<name>.counts-per-rev(u32, r/w) Used to

emulate the indexbehaviour of an incemental+indexencoder.This would nor-

mally be set to the actual counts per revofthe encoder,but can be anywhole

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 syn-

chronous 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 mod-

ule 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 conﬁg changes. Solutions to the

problem dpend on whether the encoder read is being triggered by the hm2dpll phase-

locked-loop timer (described above)orbythe 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 speciﬁed in the loadrt command line and followclosely the format

deﬁned above for SSI. Currently data packets of up to 96 bits are supported by the Lin-

uxCNC driver, although the Mesa Hostmot2 module can handle 512 bit packets. It should

be possible to extend the number of packets supported by the driverifthere is a require-

ment to do so.

Fanuc encoder.

The pins and format speciﬁer for this module are identical to the SSI module described

above,except that at least one pre-conﬁgured format is provided. A modparam of

fanuc_chan_N=AA64 (case sensitive)will conﬁgure 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 commu-

tation

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 Rawcounts, 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

resolverResolvers have names likehm2_<BoardType>.<BoardNum>.resolver.<Instance>.

<Instance is a 2-digit number,which for the 7i49 board will be between 00 and 05. This

function only works with the Mesa Resolver interface boards (of which the 7i49 is the

only example at the time of writing). This board uses an SPI interface to the FPGA card,

and will only work with the correct ﬁrmware. The pins allocated will be listed in the

dmesg output, but are unlikely to be usefully probed with HAL tools.

Pins:

(ﬂoat, out) angle

This pin indicates the angular position of the resolver.Itisanumber between 0

and 1 for each electrical rotation.

LinuxCNC Documentation 2008-05-13 175

HOSTMOT2(9) HAL Component HOSTMOT2(9)

(ﬂoat, out) position

Calculated from the number of complete and partial revolutions since startup,

reset, or index-reset multiplied by the scale parameter.

(ﬂoat, out) velocity

Calculated from the rotational velocity and the velocity-scale parameter.The

default scale is electrical rotations per second.

(s32, out) count

This pins outputs a simulated encoder count at 2ˆ24 counts per rev(16777216

counts).

(s32, out) rawcounts

This is identical to the counts pin, except it is not reset by the ’index’ or ’reset’

pins. This is the pin which would be linked to the bldc HAL component if the

resolver was being used to commutate a motor.

(bit, in) reset

Resets the position and counts pins to zero immediately.

(bit, in/out) index-enable

When this pin is set high the position and counts pins will be reset the next time

the resolver passes through the zero position. At the same time the pin is driven

lowtoindicate to connected modules that the indexhas been seen, and that the

counters have been reset.

(bit, out) error

Indicates an error in the particular channel. If this value is "true" then the

reported position and velocity are invalid.

Parameters:

(ﬂoat, read/write) scale

The position scale, in machine units per resolver electrical revolution.

(ﬂoat, read/write) velocity-scale

The conversion factor between resolver rotation speed and machine velocity.A

value of 1 will typically give motor speed in rps, a value of 0.01666667 will give

(approximate) RPM.

(u32, read/write) index-divisor (default 1)

The resolver component emulates an indexataﬁxedpoint in the sin/cos cycle.

Some resolvers have multiple cycles per rev(often related to the number of pole-

pairs on the attached motor). LinuxCNC requires an indexonce per revolution

for proper threading etc. This parameter should be set to the number of cycles

per revofthe resolver.CAUTION: Which pseudo-indexisused will not neces-

sarily be consistent between LinuxCNC runs. Do not expect to re-start a thread

after restarting LinuxCNC. It is not appropriate to use this parameter for index-

homing of axis drives.

176 2008-05-13 LinuxCNC Documentation

HOSTMOT2(9) HAL Component HOSTMOT2(9)

(ﬂoat, read/write) excitation-khz

This pin sets the excitation frequencyfor the resolver.This pin is module-level

rather than instance-levelasall resolvers share the same excitation frequency.

Valid values are 10 (˜10kHz), 5 (˜5kHz) and 2.5 (˜2.5kHz). The actual fre-

quencydepends on the FPGA frequency, and theycorrespond to

CLOCK_LOW/5000, CLOCK_LOW/10000 and CLOCK_LOW/20000 respec-

tively.The parameter will be set to the closest available of the three frequencies.

Avalue of -1 (the default) indicates that the current setting should be retained.

pwmgen

pwmgens have names like"hm2_<BoardType>.<BoardNum>.pwmgen.<Instance>".

"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 ﬁrst

7i43 board is: hm2_7i43.0.pwmgen.03.enable (this assumes that the ﬁrmware in that

board is conﬁgured 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 anysig-

nals.

(ﬂoat input) value

The current pwmgen command value, in arbitrary units.

Parameters:

(ﬂoat 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 out-

side 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 com-

ponent. This parameter may be changed at runtime, but most of the time you

probably want to set it at startup and then leave italone. 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 speciﬁes the PWM frequency, inHz, of all the pwmgen instances running

in the PWM modes (modes 1 and 2). This is the frequencyofthe variable-duty-

cycle wav e.Its effective range is from 1 Hz up to 193 kHz. Note that the max

frequencyisdetermined by the ClockHigh frequencyofthe 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 frequencytoo high, it will be

clipped to the max supported frequencyofthe board. Frequencies belowabout 5

Hz are not terribly accurate, but above 5 Hzthey’re pretty close. The default

pwm_frequencyis20,000 Hz (20 kHz).

(u32 rw) pdm_frequency

This speciﬁes the PDM frequency, inHz, of all the pwmgen instances running in

PDM mode (mode 3). This is the "pulse slot frequency"; the frequencyatwhich

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_frequencyseconds. For example, setting the pdm_frequencyto2e6 (2

MHz) and the duty cycle to 50% results in a 1 MHz square wav e,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 frequencyis

determined by the ClockHigh frequencyofthe 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 fre-

quencies. If the user attempts to set the frequencytoo high, it will be clipped to

the max supported frequencyofthe board. The default pdm_frequencyis

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_<BoardType>.<BoardNum>.3pwm-

gen.<Instance>"where <Instance> 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 ﬁrst three pins are the high side drivers, the second three are their comple-

mentary low-side drivers. The enable bit is intended to control the servoampliﬁer.The

input bit is a fault bit, typically wired to over-current detection. When set the PWM gen-

erator 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:

(ﬂoat input) A-value, B-value, C-value: The PWM command value for each phase, lim-

ited to +/- "scale". Defaults to zero which is 50% duty cycle on high-side and low-side-

pins (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 lowthe 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 lowside 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 phys-

ical fault pin until the "enable" pin is set to high.

Parameters:

(u32 rw) deadtime

Sets the dead-time between the high-side driverturning offand the low-side

driverturning on and vice-versa. Deadtime is subtracted from on time and added

to offtime 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 wav es(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 speciﬁed in nS and defaults to a rather conservative 5000nS. Setting this

parameter to too lowavalue 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.

(ﬂoat rw) scale

Sets the half-scale of the speciﬁed 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 trig-

gered with the pin high, and 0 means that a fault it triggered when the pin is

pulled low. Default 0, fault = lowsothat 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.

stepgenstepgens have names like"hm2_<BoardType>.<BoardNum>.stepgen.<Instance>".

"Instance" is a two-digit number that corresponds to the HostMot2 stepgen instance num-

ber.There are ’num_stepgens’ instances, starting with 00.

So, for example, the HAL pin that has the current position feedback from the ﬁrst 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)

ﬁrmware in that board is conﬁgured 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:

(ﬂoat 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).

(ﬂoat 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).

(ﬂoat output) position-fb

Feedback position in arbitrary position units. This is similar to "counts/posi-

tion_scale", but has ﬁner than step resolution.

(ﬂoat 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:

(ﬂoat r/w) position-scale

Converts from counts to position units. position = counts / position_scale

(ﬂoat r/w) maxvel

Maximum speed, in position units per second. If set to 0, the driverwill always

use the maximum possible velocity based on the current step timings and posi-

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

(ﬂoat r/w) maxaccel

Maximum acceleration, in position units per second per second. Defaults to 1.0.

If set to 0, the driverwill not limit its acceleration at all - this requires that the

position-cmd or velocity-cmd pin is driveninaway that does not exceed the

machine’scapabilities. 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 nanosec-

onds.

(u32 r/w) dirhold

Minimum duration of stable Direction signal after a step ends, in nanoseconds.

(u32 r/w) step_type

Output format, likethe step_type modparam to the software stegen(9) compo-

nent. 0 =Step/Dir,1=Up/Down, 2 = Quadrature, 3+ = table-lookup mode. In

this mode the step_type parameter determines howlong the step sequence is.

Additionally the stepgen_width parameter in the loadrt conﬁg string must be set

to suit the number of pins per stepgen required. Anystepgen 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 ﬁrmwares 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 ta-

ble-data-0 = 0x00000001 would set stepgen pin 0 (always called "Step" in the

dmesg output) on the ﬁrst 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 or7i64 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 con-

nected in anyorder to anyactive channel of an active port. (see the conﬁg modparam

deﬁnition above).

Forfull 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) driverisunusual in that it does not create anyHAL pins.

Instead the driverexports a set of functions that can be used by a sub -driverfor the

attached hardware. Typically these would be written in the "comp" pre-processing lan-

guage: 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_fun-

tion and man hm2_bspi_set_write_function for the exported functions.

The names of the available channels are printed to standard output during the driverload-

ing process and takethe form hm2_<board name>.<board index>.bspi.<index> For

example hm2_5i23.0.bspi.0

UART The UARTdriveralso does not create anyHAL pins, instead it declares twosimple

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://linux-

cnc.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_set-

up.

The names of the available uart channels are printed to standard output during the driver

loading process and takethe form hm2_<board name>.<board index>uart.<index> 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 conﬁgured at run-time to be inputs, outputs, or

open drains, and have a HAL interface that exposes this ﬂexibility.IOpins 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_<BoardType>.<BoardNum>.gpio.<IONum>". IONum is

athree-digit number.The mapping from IONum to connector and pin-on-that-connector

is written to the syslog when the driverloads, and it’sdocumented in Mesa’smanual 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

ﬁrmware in that board is conﬁgured so that this HAL object is available)

The HAL parameter that controls whether the last GPIO of the ﬁrst 5i22 is an input or an

output is: hm2_5i22.0.gpio.095.is_output (this assumes that the ﬁrmware in that board is

conﬁgured 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 docu-

ment). 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 drivenbyother 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 noeffect. 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 behavesasanormal output pin: the IO pin on the

connector is driventothe value speciﬁed by the "out" HAL pin (possibly

inverted), and the value of the "in" and "in_not" HAL pins is undeﬁned. If this

parameter is true, the GPIO behavesasanopen-drain pin. Writing 0 to the "out"

HAL pin drivesthe IO pin low, writing 1 to the "out" HAL pin puts the IO pin in

ahigh-impedance state. In this high-impedance state the IO pin ﬂoats (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<NN>

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 ﬁrmware may include a watchdog Module; if it does, the hostmot2 driver

will use it. The HAL representation of the watchdog is named "hm2_<Board-

Type>.<BoardNum>.watchdog".

The watchdog starts out asleep and inactive.Once you access the board the ﬁrst time by

running anythe 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’sI/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 ﬁrwmare modules is not disturbed (except for

the conﬁguration 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 conﬁguration chosen at load-time.

If the ﬁrmware 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 opera-

tion.

Parameters:

(u32 read/write) timeout_ns

Watchdog timeout, in nanoseconds. This is initialized to 5,000,000 (5 millisec-

onds) 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" conﬁg keyword is speciﬁed, some extra debugging pins are made

available in HAL. The rawmode HAL pin names begin with "hm2_<Board-

Type>.<BoardNum>.raw".

With Rawmode enabled, a user may peek and pokethe ﬁrmware from HAL, and may

dump the internal state of the hostmot2 drivertothe 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 driverwill write its

representation of the board’sinternal 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_<BoardType>.<BoardNum>.read

This reads the encoder counters, stepgen feedbacks, and GPIO input pins from

the FPGA.

hm2_<BoardType>.<BoardNum>.write

This updates the PWM duty cycles, stepgen rates, and GPIO outputs on the

FPGA. Anychanges to conﬁguration pins such as stepgen timing, GPIO inver-

sions, etc, are also effected by this function.

hm2_<BoardType>.<BoardNum>.pet-watchdog

Pet the watchdog to keep it from biting us for a while.

hm2_<BoardType>.<BoardNum>.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 faster-

than-servothread. (This function is not available on the 7i43 due to limitations

of the EPP bus.)

hm2_<BoardType>.<BoardNum>.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.Nor-

mally only .write() is used. The only reason to call this function is if you want

to do GPIO things in a faster-than-servothread. (This function is not available

on the 7i43 due to limitations of the EPP bus.)

hm2_<BoardType>.<BoardNum>.trigger-encoders

This function will only appear if the ﬁrmware contains a BiSS, Fanuc or SSI

encoder module and if the ﬁrmare does not contain a hm2dpll module (qv) or if

the modparam contains num_dplls=0. This function should be inserted ﬁrst 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 ﬁn-

ished 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 servocycle 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’sdocumentation for the Anything I/O boards, at <http://www.mesanet.com>

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 ﬂoating-point thread)

PINS hypot.N.in0 ﬂoat in

hypot.N.in1 ﬂoat in

hypot.N.in2 ﬂoat in

hypot.N.out ﬂoat 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 ﬁlter with integer inputs and outputs

SYNOPSIS

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

DESCRIPTION

While it may ﬁnd 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 likeastep 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 neverbemore than about 2e9/scale

pulses seen on the MPG. Choose gain according to the smoothing leveldesired. Divide the axis.N.jog-

scale values by scale.

FUNCTIONS

ilowpass.N(requires a ﬂoating-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 ﬁlter of gain per period.

PARAMETERS

ilowpass.N.scale ﬂoat rw (default: 1024)

Ascale factor applied to the output value of the low-pass ﬁlter.

ilowpass.N.gain ﬂoat 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

JeffEpler <jepler@unpythonic.net>

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 ﬂoating-point thread)

PINS integ.N.in ﬂoat in

integ.N.gain ﬂoat in (default: 1.0)

integ.N.out ﬂoat 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 ﬂoat in (default: 1e20)

integ.N.min ﬂoat 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 howclose 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 ﬂoating-point thread)

PINS invert.N.in ﬂoat in

Analog input value

invert.N.out ﬂoat out

Analog output value

PARAMETERS

invert.N.deadband ﬂoat 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, takehigher power-values for higher dead-

bands (>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 ﬂoating-point thread)

PINS joyhandle.N.in ﬂoat in

joyhandle.N.out ﬂoat out

PARAMETERS

joyhandle.N.power ﬂoat rw (default: 2.0)

joyhandle.N.deadband ﬂoat rw (default: 0.)

joyhandle.N.scale ﬂoat rw (default: 1.)

joyhandle.N.offset ﬂoat 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 deﬁnitions 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 kinemat-

ics deﬁnitions 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 predeﬁned 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

Givessix degrees of freedom in position and orientation (XYZABC). The location of the motors is deﬁned

at compile time.

maxkins − 5-axis kinematics example

Kinematics for Chris Radek’stabletop 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

ﬁle, 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-Hartenbergdeﬁnition for the joint and links. The DH deﬁnitions are the ones

used by John J Craig in "Introduction to Robotics: Mechanics and Control" The parameters for the manipu-

lator are deﬁned by hal pins.

genserkins.A-N

genserkins.ALPHA-N

genserkins.D-N

Parameters describing the Nth joint’sgeometry.

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,ifneg a -

tive theyintroduce 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 knob2ﬂoat − Convert counts (probably from an encoder) to a ﬂoat value

SYNOPSIS

loadrt knob2ﬂoat [count=N|names=name1[,name2...]]

FUNCTIONS

knob2ﬂoat.N(requires a ﬂoating-point thread)

PINS knob2ﬂoat.N.counts s32 in

Counts

knob2ﬂoat.N.enable bit in

When TRUE, output is controlled by count, when FALSE, output is ﬁxed

knob2ﬂoat.N.scale ﬂoat in

Amount of output change per count

knob2ﬂoat.N.out ﬂoat out

Output value

PARAMETERS

knob2ﬂoat.N.max-out ﬂoat rw (default: 1.0)

Maximum output value, further increases in count will be ignored

knob2ﬂoat.N.min-out ﬂoat 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

Formaxbinnumber = 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 indexpin to a bin number: 0 <= index<=maxbinnumber.

Read check pin and verify that check pin == indexpin.

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 indexisout of range ( index<0orindex>maxbinnumber)

then pbinvalue = nbinvalue = -1.

The reset pin may be used to restart.

The latencypin 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 ﬂoating-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 (ﬂoat/s32/u32/bit) in

The input pins have types matched to the format string speciﬁers.

lcd.NN.page_num (u32) in

Selects the page number.Multiple layouts may be deﬁned, and this pin switches between them.

lcd.NN.contrast (ﬂoat) 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 ﬂoating 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 likethose used in C and manyother languages in the printf and scanf func-

tions and their variants.

The component was written speciﬁcally to support the Mesa 7i73 pendant controller,howev e ritmay 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 evenagenuine 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 conﬁgured 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

ev e nifanautomatic wrap has occurred (lcd has no knowledge of the width of the lcd display.) To

print in the rightmost column it is necessary to allowthe 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 deﬁned by the hexadecimal code NN.

\\ Inserts a literal \.

Numerical formats

lcd differs slightly from the standard printf conventions. One signiﬁcant 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 ﬁeld

width includes the sign character so that negative numbers will often have a smaller valid range

than positive.Numbers that do not ﬁt in the speciﬁed width are displayed as a line of asterisks

(********).

Each format begins with a "%" symbol. (For a literal % use "%%"). Immediately after the % the

following modiﬁers may be used:

""(space) Pad the number to the speciﬁed width with spaces. This is the default and is not strictly

necessary.

"0" Pad the number to the speciﬁed width with the numeral 0.

"+" Force display of a + symbol before positive numbers. This (likethe - sign) will appear imme-

diately 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)deﬁnes the total number of

characters to display including the decimal separator and the sign. Whilst this number can be as

manydigits as required the maximum ﬁeld width is 20 characters. The inherent precison of the

"double" data type means that more than 14 digits will tend to showerrors in the least signiﬁcant

digits. The integer data types will neverﬁll more than 10 decimal digits.

Following the width speciﬁer should be the decimal speciﬁer.This can only be a full-stop charac-

ter (.) 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 howmanyplaces of decimals

to display.This entry is ignored in the case of integer formats.

All the above modiﬁers are optional, but to specify a decimal precision the decimal point must pre-

cede 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 ﬂoating-point type HAL pin. The example would

be displayed in a 9-character ﬁeld, 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 ﬁxed 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 ﬁxed 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.Awidth may be speciﬁed, though the u32 HAL

type is only 8 hexdigits 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. Val-

ues less than 32 (space) are suppressed. A width speciﬁer may be used, for example %20c might

be used to create a complete line of one character.

%b This speciﬁer has no equivalent in printf. It creates a bit (boolean) type HAL pin. The b

should be followed by twocharacters and the display will showthe ﬁrst of these when the pin is

true, and the second when false. Note that the characters follow, not preceed the "b", unlikethe

case with other formats. The characters may be "escaped" Hexvalues. 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-arrowfor 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 evenescaped 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 ﬂoating-point thread)

PINS limit1.N.in ﬂoat in

limit1.N.out ﬂoat out

PARAMETERS

limit1.N.min ﬂoat rw (default: -1e20)

limit1.N.max ﬂoat 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 slewrate 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 ﬂoating-point thread)

PINS limit2.N.in ﬂoat in

limit2.N.out ﬂoat out

limit2.N.load bit in

When TRUE, immediately set out to in,ignoring maxv

PARAMETERS

limit2.N.min ﬂoat rw (default: -1e20)

limit2.N.max ﬂoat rw (default: 1e20)

limit2.N.maxv ﬂoat 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 slewrate to less than maxv per sec-

ond, and limit its second derivative toless 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 ﬂoating-point thread)

PINS limit3.N.in ﬂoat in

limit3.N.out ﬂoat out

limit3.N.load bit in

When TRUE, immediately set out to in,ignoring maxv and maxa

limit3.N.min ﬂoat in (default: -1e20)

limit3.N.max ﬂoat in (default: 1e20)

limit3.N.maxv ﬂoat in (default: 1e20)

limit3.N.maxa ﬂoat 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ﬂoating-point input to a ﬂoating-point output. Typical uses would

include linearisation of thermocouples, deﬁning PID gains that vary with external factors or to substitute for

anymathematical function where absolute accuracyisnot 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 compo-

nent is set to the corresponding y-value.

The (x,y) points are deﬁned by the x-val-NN and y-val-NN parameters which need to be set in the HAL ﬁle

using "setp" commands.

The maximum number if (x,y) points supported is 16.

Forinput values less than the x-val-00 breakpoint the y-val-00 is returned. Forxgreater than the largest x-

val-NN the yval corresponding to x-max is returned (ie, no extrapolation is performed.)

Sample usage: loadrt lincurvecount=3 personality=4,4,4 for a set of three 4-element graphs.

FUNCTIONS

lincurve.N(requires a ﬂoating-point thread)

PINS lincurve.N.in ﬂoat in

The input value

lincurve.N.out ﬂoat out

The output value

lincurve.N.out-io ﬂoat io

The output value, compatible with PID gains

PARAMETERS

lincurve.N.x-val-MM ﬂoat rw (MM=00..personality)

axis breakpoints

lincurve.N.y-val-MM ﬂoat 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 conﬁgurable 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 hexwould 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 ﬁlter

SYNOPSIS

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

FUNCTIONS

lowpass.N(requires a ﬂoating-point thread)

PINS lowpass.N.in ﬂoat in

lowpass.N.out ﬂoat out

out += (in - out) * gain

lowpass.N.load bit in

When TRUE, copy in to out instead of applying the ﬁlter equation.

PARAMETERS

lowpass.N.gain ﬂoat rw

NOTESThe effect of a speciﬁc gain value is dependent on the period of the function that lowpass.Nis 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-uptable. 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 anyofthe 4,294,967,296 logical functions of 5 inputs so AND,OR,NAND,

NOR,XOR and every other combinatorial function is possible.

Example Functions

A5-input and function is TRUE only when all the inputs are true, so the correct value for function is

0x80000000.

A2-input or function would be the sum of 0x2 +0x4 +0x8,sothe correct value for function is 0xe.

A5-input or function is TRUE wheneverany ofthe 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 ﬁrst one.

A2-input xor function is TRUE wheneverexactly 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 anyother bit is TRUE then the output

will be FALSE.

LinuxCNC Documentation 2014-12-18 205

LUT5(9) HAL Component LUT5(9)

Weights for each line of truth table

Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Weight

00000 0x1

00001 0x2

00010 0x4

00011 0x8

00100 0x10

00101 0x20

00110 0x40

00111 0x80

01000 0x100

01001 0x200

01010 0x400

01011 0x800

01100 0x1000

01101 0x2000

01110 0x4000

01111 0x8000

10000 0x10000

10001 0x20000

10010 0x40000

10011 0x80000

10100 0x100000

10101 0x200000

10110 0x400000

10111 0x800000

110000x1000000

110010x2000000

110100x4000000

110110x8000000

111000x10000000

111010x20000000

111100x40000000

111110x80000000

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 conﬁg=RxCs,RxCs... names=name1,name2...

Creates a component conﬁgured for R rows and N columns of matrix keyboard.

If the soption is speciﬁed 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 speciﬁed 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, itmight also

ﬁnd uses in converting integers from 0 to N into N HAL pins.

The component can work in twoways, and the HAL pins created vary according to mode.

In the default mode the component expects to be givenascan code from a separate driverbut could be any

integer from anysource. 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 speciﬁcation 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 conﬁgs

for the 7i73 are 4x8 and 8x8. Note that the component will only work properly with the version 12 (0xC)

7i73 ﬁrmware. The ﬁrmware 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 rowpins and input column pins are created. These need to be connected to physical inputs and out-

puts 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 ﬂoat 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 slowthread for effective debouncing.

PINS matrix_kb.N.col-CC-in bit in

The input pin corresponding to column C.

matrix_kb.N.key.rRcCbit out

The pin corresponding to the key atrow 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 rowscan 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_rolloverunsigned r/w (default 2)

With most matrix keyboards the scancodes are only unambiguous with 1 or 2 keyspressed. With

more keyspressed phantom keystrokes can appear.Some keyboards are optimised to reduce this

problem, and some have internal diodes so that anynumber of keysmay be pressed simultane-

ously.Increase the value of this parameter if such a keyboard is connected, or if phantom key-

strokes are more acceptable than only twokeysbeing active atone time.

matrix_kb.N.negative-logic bit r/w (default 1) only in scan mode

When no keysare pressed a typical digital input will ﬂoat 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 rowatatime 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 ServoCard

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 bitﬁle loaded to each installed card during the Hostmot2 setup sequence. Type

"dmesg" at the terminal prompt to viewthe output.

PINS mesa-7i65.N.analogue.M.out ﬂoat 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 ﬂoat 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)

Ampliﬁer-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ﬂoat 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 7Vonthe

output terminals

mesa-7i65.N.is-bipolar-Mbit 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 / CliffBlackburn

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 211

MESA_UART(9) HAL Component MESA_UART(9)

NAME mesa_uart − An example component demonstrating howtoaccess 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

ev e ry 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 howmanypins have been written to. (pins > rx-bytes

simply hold their previous value)

This module uses the names= mode of loadrt declaration to speciﬁy which UARTinstances 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 UARTinstance names, for exam-

ple:

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 UARTinstance names are printed to the dmesg buffer during the Hostmot2 setup sequence, one for

each bspi instance included in the bitﬁle loaded to each installed card during the Hostmot2 setup sequence.

Type "dmesg" at the terminal prompt to viewthe output.

The component exports twofunctions, send and receive,which need to be added to a realtime thread.

The above example will output data on UARTchannels 0 and 7 and the pins will have the names of the

individual UARTS. (theyneed not be on the same card, or eventhe same bus).

Read the documents on "comp" for help with writing realtime components: http://www.linux-

cnc.org/docview/html/hal/comp.html

FUNCTIONS

mesa-uart.N.send (requires a ﬂoating-point thread)

mesa-uart.N.receive (requires a ﬂoating-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="Slidewayoil low,No oil pressure,Spindle

inverter fault"

addf oillowservo-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 anypin 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)

AFALSE->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 ﬂoating-point thread)

PINS minmax.N.in ﬂoat in

minmax.N.reset bit in

When reset is asserted, ’in’ is copied to the outputs

minmax.N.max ﬂoat out

minmax.N.min ﬂoat 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=0or1][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 ﬂoating point. Software stepping, software encoder counting,

and software pwm do not use ﬂoating point. base_thread_fp can be used to enable ﬂoating 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 inter-

face for LinuxCNC’smotion 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".

Theyare read and updated by the motion-controller function.

PINS axis.N.amp-enable-out OUT BIT

TRUE if the ampliﬁer for this joint should be enabled

axis.N.amp-fault-in IN BIT

Should be drivenTRUEifanexternal fault is detected with the ampliﬁer for this joint

axis.N.home-sw-in IN BIT

Should be drivenTRUEifthe 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’sencoder to enable homing to indexpulse

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), anychange 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 movedfor 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 howlong that might take. When TRUE, the wheel

operates in velocity mode - motion stops when the wheel stops, evenifthat 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, screwerror 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 drivenTRUEifthe negative limit switch for this joint is tripped.

axis.N.pos-lim-sw-in IN BIT

Should be drivenTRUEifthe positive limit switch for this joint is tripped.

axis.N.unlock OUT BIT

TRUE if the axis is a locked rotary and a move iscommanded.

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-levelfeed 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 drivenFALSE, 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

movestill 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 ﬁrst feed

move after each spindle start or speed change; before the start of every chain of spindle-synchro-

nized moves; and if in CSS mode, at every rapid->feed transition.

motion.spindle-brake OUT BIT

TRUE when the spindle brakeshould be applied

motion.spindle-forward OUT BIT

TRUE when the spindle should rotate forward

motion.spindle-index-enable I/O BIT

Forcorrect operation of spindle synchronized moves, this signal must be hooked to the index-

enable 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-rev erse OUT BIT

TRUE when the spindle should rotate backward

motion.spindle-revsIN FLOAT

Forcorrect 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 reg ardless of spindle direction.

motion.spindle-speed-out-rps OUT ﬂoat

Desired spindle speed in rotations per second

motion.spindle-speed-out-rps-abs OUT ﬂoat

Desired spindle speed in rotations per second, always positive reg ardless 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. Reﬂects M19 P parameter word.

motion.spindle-orient OUT BIT

Indicates start of spindle orient cycle. Set by M19. Cleared by anyofM3,M4,M5. If spindle-ori-

ent-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 spin-

dle-is-oriented was asserted, the spindle-orient pin is cleared and the spindle-locked pin is

asserted. Also, the spindle-brakepin is asserted.

motion.spindle-orient-fault IN S32

Fault code input for orient cycle. Anyvalue 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 anyofM3,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

Manyofthe pins belowserveasdebugging aids, and are subject to change or removalatany time.

axis.N.active OUT BIT

TRUE when this joint is active

axis.N.backlash-corr OUT FLOAT

Backlash or screwcompensation rawvalue

axis.N.backlash-ﬁlt OUT FLOAT

Backlash or screwcompensation ﬁltered value (respecting motion limits)

axis.N.backlash-vel OUT FLOAT

Backlash or screwcompensation 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’scommanded 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

Manyofthe parameters serveasdebugging aids, and are subject to change or removalatany time.

motion-command-handler.time

motion-command-handler.tmax

motion-controller.time

motion-controller.tmax

Showinformation 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 servothread. Typically,this number

divided by the CPU speed givesthe 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 con-

troller 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 twoinputs

SYNOPSIS

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

FUNCTIONS

mult2.N(requires a ﬂoating-point thread)

PINS mult2.N.in0 ﬂoat in

mult2.N.in1 ﬂoat in

mult2.N.out ﬂoat 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

Aclick is deﬁned as a rising edge on the ’in’ pin, followed by the ’in’ pin being True for at most ’max-

hold-ns’ nanoseconds, followed by a falling edge.

Adouble-click is deﬁned as twoclicks, separated by at most ’max-space-ns’ nanoseconds with the ’in’ pin

in the False state.

Ibet you can guess the deﬁnition of triple- and quadruple-click.

Youprobably want to run the input signal through a debounce component before feeding it to the multiclick

detector,ifthe 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 showthat 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 brieﬂy when a single-click is detected on the ’in’ pin.

multiclick.N.single-click-only bit out

Goes high brieﬂy when a single-click is detected on the ’in’ pin and no second click followed it.

multiclick.N.double-click bit out

Goes high brieﬂy when a double-click is detected on the ’in’ pin.

multiclick.N.double-click-only bit out

Goes high brieﬂy when a double-click is detected on the ’in’ pin and no third click followed it.

multiclick.N.triple-click bit out

Goes high brieﬂy when a triple-click is detected on the ’in’ pin.

multiclick.N.triple-click-only bit out

Goes high brieﬂy when a triple-click is detected on the ’in’ pin and no fourth click followed it.

multiclick.N.quadruple-click bit out

Goes high brieﬂy when a quadruple-click is detected on the ’in’ pin.

multiclick.N.quadruple-click-only bit out

Goes high brieﬂy when a quadruple-click is detected on the ’in’ pin and no ﬁfth 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’snot 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’snot 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 speciﬁed 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 ﬂoating-point thread)

PINS multiswitch.N.up bit in (default: false)

Receivessignal to toggle up

multiswitch.N.down bit in (default: false)

Receivessignal 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 ﬂoating-point thread)

PINS mux16.N.use-graycode bit in

This signiﬁes 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 out-

put between transitions of input. butmakein00 unavaliable.

mux16.N.debounce-time ﬂoat 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.selMbit in (M=0..3)

Together,these determine which inNvalue is copied to out.

mux16.N.out-f ﬂoat out

mux16.N.out-s s32 out

Follows the value of one of the inNvalues according to the four sel values and whether use-gray-

code 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 ﬂoat in (MM=00..15)

array of selectable outputs

PARAMETERS

mux16.N.elapsed ﬂoat 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 twoinput values

SYNOPSIS

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

FUNCTIONS

mux2.N(requires a ﬂoating-point thread)

PINS mux2.N.sel bit in

mux2.N.out ﬂoat out

Follows the value of in0 if sel is FALSE, or in1 if sel is TRUE

mux2.N.in1 ﬂoat in

mux2.N.in0 ﬂoat 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 ﬂoating-point thread)

PINS mux4.N.sel0 bit in

mux4.N.sel1 bit in

Together,these determine which inNvalue is copied to out.

mux4.N.out ﬂoat out

Follows the value of one of the inNvalues 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 ﬂoat in

mux4.N.in1 ﬂoat in

mux4.N.in2 ﬂoat in

mux4.N.in3 ﬂoat 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 ﬂoating-point thread)

PINS mux8.N.sel0 bit in

mux8.N.sel1 bit in

mux8.N.sel2 bit in

Together,these determine which inNvalue is copied to out.

mux8.N.out ﬂoat out

Follows the value of one of the inNvalues 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 ﬂoat in

mux8.N.in1 ﬂoat in

mux8.N.in2 ﬂoat in

mux8.N.in3 ﬂoat in

mux8.N.in4 ﬂoat in

mux8.N.in5 ﬂoat in

mux8.N.in6 ﬂoat in

mux8.N.in7 ﬂoat 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 conﬁg="bb8,fu12...."

FUNCTIONS

mux-gen.NN Depending on the data types can run in either a ﬂoating

point or non-ﬂoating 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 out-

put between transitions of input. butmakes 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 inNvalue 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 (unlikemux16) does not offer

the option of decoding gray-code, howeverthe same effect can be achievedbyarranging the order

of the input values to suit.

mux-gen.NN.out-[bit/ﬂoat/s32/u32] variable-type out

Follows the value of one of the inNvalues according to the selection bits and/or the selection num-

ber.Values will be converted/truncated according to standard C rules. This means, for example

that a ﬂoat input greater than 2147483647 will give anS32 output of -2147483648.

mux-gen.NN.in-[bit/ﬂoat/s32/u32]-MM variable-type in

The possible output values that are selected by the selection pins.

PARAMETERS

mux-gen.N.elapsed ﬂoat 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 out-

put pins. The conﬁguration 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 ﬂoat-to-unsigned mux. The code

letters are b = bit, f = ﬂoat, s = signed integer,u=unsigned integer.The ﬁrst letter code is the input type,

the second is the output type. The codes are not case-sensitive.The order of the letters is signiﬁcant but the

position in the string is not. Do not insert anyspaces in the conﬁg string. Anynon-zero ﬂoat 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 ﬂoat 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.Ifneither input nor output is

of type ﬂoat then the function is base-thread (non ﬂoating-point) safe. Anymux_generic with a ﬂoating

point input or output can only be added to a ﬂoating-point thread.

LICENSE

GPL

AUTHOR

Andy Pugh

232 2013-05-27 LinuxCNC Documentation

NEAR(9) HAL Component NEAR(9)

NAME near − Determine whether twovalues are roughly equal.

SYNOPSIS

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

FUNCTIONS

near.N(requires a ﬂoating-point thread)

PINS near.N.in1 ﬂoat in

near.N.in2 ﬂoat 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| <= differ-

ence). out is false otherwise.

PARAMETERS

near.N.scale ﬂoat rw (default: 1)

near.N.difference ﬂoat 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 ﬂoating-point thread)

Updated the output value by adding the offset to the input

offset.N.update-feedback (requires a ﬂoating-point thread)

Update the feedback value by subtracting the offset from the feedback

PINS offset.N.offset ﬂoat in

The offset value

offset.N.in ﬂoat in

The input value

offset.N.out ﬂoat out

The output value

offset.N.fb-in ﬂoat in

The feedback input value

offset.N.fb-out ﬂoat 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 ﬂoating point (typically the servothread). This means that the pulse length has to be a mul-

tiple of that thread period, typically 1mS. Forasimilar function that can run in the base thread, and which

offers higher resolution, see "edge".

FUNCTIONS

oneshot.N(requires a ﬂoating-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 ﬂoat in (default: 0)

Pulse width in seconds

oneshot.N.time-left ﬂoat out

Time left in current output pulse

PARAMETERS

oneshot.N.retriggerable bit rw (default: TRUE)

Allowadditional 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 driverfor opto22 PCI-AC5 cards

SYNOPSIS

loadrt opto_ac5 [portconﬁg0=0xN][portconﬁg1=0xN]

DESCRIPTION

These pins and parameters are created by the realtime opto_ac5 module. The portconﬁg0 and portconﬁg1

variables are used to conﬁgure the twoports of each card. The ﬁrst 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 portconﬁg0=0xfff000

If no portconﬁg variable is speciﬁed the default conﬁguration 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 repre-

sents 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 LOWgiv esTRUE

and HIGH givesFALSE.

opto_ac5.[BOARDNUMBER].port[PORTNUMBER].out-[PINNUMBER]INbit

Connect a hal bit signal to this pin to write to an i/o point of the card. The PINNUMBER repre-

sents 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 givesLOW and

FALSE givesHIGH.

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 conﬁgurations as the ﬁrst 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

ﬁt 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: ﬂoor(number of full spindle revolutions in the position sam-

pled 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 newangle.

2: the spindle rotates always rotates counterclockwise to the newangle.

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 ﬂoating-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 ﬂoat in

spindle position input, unit 1 rev

orient.N.angle ﬂoat in

orient target position in degrees, 0 <= angle < 360

orient.N.command ﬂoat out

target spindle position, input to PID command

240 2014-12-18 LinuxCNC Documentation

ORIENT(9) HAL Component ORIENT(9)

orient.N.poserr ﬂoat 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 − Driverfor 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. egloadrt pcl720 ioaddr=0x200,0x200. use 0xNNN to deﬁne addresses in

Hex

DESCRIPTION

This driversupports 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 coun-

ters/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 speciﬁed by the reset-time parameter and resets anypins for which

the reset parameter has been set. This can be used to allowstep generators to makeastep 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 anypins.

the stepgen step-space parameter should be set to 0 to makeuse 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)

speciﬁes 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 servomotors 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 sepa-

rated by commas.

The num_chan= and names= speciﬁers are mutually exclusive.Ifneither num_chan= nor names= are

speciﬁed, 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.

NAMING

The names for pins, parameters, and functions are preﬁxed as:

pid.N. for N=0,1,...,num-1 when using num_chan=num

nameN. for nameN=name1,name2,... when using names=name1,name2,...

The pid.N. format is shown in the following descriptions.

FUNCTIONS

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

PINS pid.N.command ﬂoat in

The desired (commanded) value for the control loop.

pid.N.Pgain ﬂoat in

Proportional gain. Results in a contribution to the output that is the error multiplied by Pgain.

pid.N.Igain ﬂoat 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)of0.2, and if Igain is 20, the integral term would add 4.0 to the output.

pid.N.Dgain ﬂoat in

Derivative gain. Results in a contribution to the output that is the rate of change (derivative)ofthe

error multiplied by Dgain.For example an error that changed from 0.02 to 0.03 over0.2 seconds

would result in an error derivative (errorD)ofof0.05, and if Dgain is 5, the derivative term would

add 0.25 to the output.

pid.N.feedback ﬂoat in

The actual (feedback) value, from some sensor such as an encoder.

pid.N.output ﬂoat out

The output of the PID loop, which goes to some actuator such as a motor.

pid.N.command-deriv ﬂoat in

The derivative ofthe desired (commanded) value for the control loop. If no signal is connected

then the derivative will be estimated numerically.

pid.N.feedback-deriv ﬂoat in

The derivative ofthe 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 improvedbyusing 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’starget vs. current position for error calculation, likethe motion con-

troller expects. This may maketorque-mode position loops and loops requiring a large I gain eas-

ier to tune, by eliminating velocity-dependent following error.

pid.N.error ﬂoat 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 esti-

mate. On systems which use the encoder indexpulse, this pin should be connected to the index-

enable signal. When this is not done, and FF1 is nonzero, a step change in the input command

causes a single-cycle spikeinthe PID output. On systems which use exactly one of the -deriv

inputs, this affects the D term as well.

pid.N.bias ﬂoat in

bias is a constant amount that is added to the output. In most cases it should be left at zero. How-

ev e r, itcan sometimes be useful to compensate for offsets in servoampliﬁers, or to balance the

weight of an object that movesvertically. bias is turned offwhen the PID loop is disabled, just like

all other components of the output. If a non-zero output is needed evenwhen the PID loop is dis-

abled, it should be added with an external HAL sum2 block.

pid.N.FF0 ﬂoat 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. Forvelocity loops, FF0

can compensate for friction or motor counter-EMF and may permit better tuning if used properly.

pid.N.FF1 ﬂoat in

First order feed-forward term. Produces a contribution to the output that FF1 multiplied by the

derivative ofthe 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 ﬂoat in

Second order feed-forward term. Produces a contribution to the output that is FF2 multiplied by

the second derivative ofthe commanded value. For position loops, the contribution is proportional

to acceleration, and can be used to compensate for inertia. Forvelocity loops, it should usually be

left at zero.

pid.N.deadband ﬂoat in

Deﬁnes a range of "acceptable" error.Ifthe absolute value of error is less than deadband,itwill

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 twoadjacent 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 ﬂoat 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 integrat-

ing, to prevent windup and overshoot.

244 2007-01-16 LinuxCNC Documentation

PID(9) HAL Component PID(9)

pid.N.maxerror ﬂoat 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 ﬂoat 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 out-

put spikes due to steps on the command and/or feedback. Not normally needed.

pid.N.maxerrorI ﬂoat 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 ﬂoat 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

astep change on the command. Not normally needed.

pid.N.maxcmdDD ﬂoat in

Limit on command second derivative.The command second derivative used by FF2 will be lim-

ited to this value, unless the value is zero. Can be used to prevent FF2 from producing large out-

put 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 ﬂoat out

pid.N.saturated-count s32 out

When true, the output of PID was continually saturated for this manyseconds (saturated-s)or

periods (saturated-count).

PARAMETERS

pid.N.errorI ﬂoat 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 ﬂoat ro (only if debug=1)

Derivative oferror.This is the value that is multiplied by Dgain to produce the Derivative term of

the output.

pid.N.commandD ﬂoat ro (only if debug=1)

Derivative ofcommand. This is the value that is multiplied by FF1 to produce the ﬁrst order feed-

forward term of the output.

pid.N.commandDD ﬂoat ro (only if debug=1)

Second derivative ofcommand. 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 unmodiﬁed 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,ortowrite their own version of pid.Howev er,

the default behavior should not be changed.

Negative gains may lead to unwanted behavior.Itispossible in some situations that negative FFgains

LinuxCNC Documentation 2007-01-16 245

PID(9) HAL Component PID(9)

makesense, but in general all gains should be positive.Ifsome output is in the wrong direction, negating

gains to ﬁx 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 driverand ﬁrmware 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. 0means 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 trans-

fers, 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 approxi-

mately 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_servoisaLinuxCNC software driverand associated ﬁrmware that allowthe Pluto-P board to be used

to control a servo-based CNC machine.

The driverhas 4 PWM channels, 4 quadrature channels with indexpulse, 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 man-

ual. It operates in ‘x4 mode’.

The sample rate of the encoder is 40MHz. The maximum number quadrature rate is 8191 counts per Lin-

uxCNC servocycle. For correct handling of the indexpulse, 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 ‘pwm-

gen’ component.

Internally the PWM generator is based on a 12-bit, 40MHz counter,giving 4095 duty cycles from -100% to

+100% and a frequencyofapproximately 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 ﬂoating-point thread)

Read all the inputs from the pluto-servoboard

pluto-servo.write (requires a ﬂoating-point thread)

Write all the outputs on the pluto-servoboard

PINS pluto-servo.encoder.M.count s32 out (M=0..3)

pluto-servo.encoder.M.position ﬂoat out (M=0..3)

pluto-servo.encoder.M.velocity ﬂoat 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.Mcorresponds to the pins labeled QAM,QBM,and QZMon the pinout diagram

pluto-servo.pwm.M.value ﬂoat in (M=0..3)

pluto-servo.pwm.M.enable bit in (M=0..3)

pwm.Mcorresponds to the pins labeled UPMand DNMon the pinout diagram

pluto-servo.dout.MM bit in (MM=00..19)

dout.0M corresponds to the pin labeled OUTMon the pinout diagram. Other pins are shared with

the PWM function, as follows:

Pin Shared

Label with

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)

ForM=0 through 7, din.0M corresponds to the pin labeled INMon the pinout diagram. Other pins

are shared with the encoder function, as follows:

Pin 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

248 2014-12-18 LinuxCNC Documentation

PLUTO_SERVO(9) HAL Component PLUTO_SERVO(9)

din.17 QA1

din.18 QA2

din.19 QA3

PARAMETERS

pluto-servo.encoder.M.scale ﬂoat rw (M=0..3) (default: 1)

pluto-servo.encoder.z-polarity bit rw

Set to TRUE if the indexpulse is active low,FALSE if it is active high. Affects all encoders.

pluto-servo.pwm.M.offset ﬂoat rw (M=0..3)

pluto-servo.pwm.M.scale ﬂoat rw (M=0..3) (default: 1)

pluto-servo.pwm.M.max-dc ﬂoat rw (M=0..3) (default: 1)

pluto-servo.pwm.M.min-dc ﬂoat 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 interleavedPWM) 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

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 com-

munication 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 ﬁrmware. Theyare 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 driverand ﬁrmware 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. 0means 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 approxi-

mately 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 anyone axis may give

improvedstep regularity at lowstep speeds.

DESCRIPTION

Pluto_step is a LinuxCNC software driverand associated ﬁrmware that allowthe Pluto-P board to be used

to control a stepper-based CNC machine.

The driverhas 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 wav eform includes step length/space and direction hold/setup time. Step length and direction set-

up/hold time is enforced in the FPGA. Step space is enforced by a velocity cap in the driver.

(all the following numbersare subject to change) In speedrange=0,the maximum step rate is 312.5kHz.

Forposition feedback to be accurate, the maximum step rate is 512 pulses per servocycle (so a 1kHz servo

cycle does not impose anyadditional 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 ﬂoating-point thread)

Read all the inputs from the pluto-step board

pluto-step.write (requires a ﬂoating-point thread)

Write all the outputs on the pluto-step board

PINS pluto-step.stepgen.M.position-cmd ﬂoat in (M=0..3)

pluto-step.stepgen.M.velocity-fb ﬂoat out (M=0..3)

pluto-step.stepgen.M.position-fb ﬂoat 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 OUTMon 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 INMon the pinout diagram.

PARAMETERS

pluto-step.stepgen.M.scale ﬂoat rw (M=0..3) (default: 1.0)

pluto-step.stepgen.M.maxvel ﬂoat 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

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 Linux-

CNC. Tocontinue 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 ﬂoat rw (default: .5)

pluto-step.debug-3 ﬂoat 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 frequencyand the resolution is quite limited compared to hardware-based approaches,

butinmanycases 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

Asingle 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

Tw o output pins, pwm and dir.The duty cycle on pwm varies as a function of the input value.

dir is lowfor positive inputs and high for negative inputs.

type 2: up/down

Tw o output pins, up and down.For positive inputs, the PWM/PDM wav eform appears on up,

while down is low. For negative inputs, the wav eform appears on down,while up is low. Suitable

for driving the twosides of an H-bridge to generate a bipolar output.

FUNCTIONS

pwmgen.make-pulses (no ﬂoating-point)

Generates the actual PWM wav eforms, using information computed by update.Must be called as

frequently as possible, to maximize the attainable PWM frequencyand resolution, and minimize

jitter.Operates on all channels at once.

pwmgen.update (uses ﬂoating 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 make-

pulses.Operates on all channels at once.

PINS pwmgen.N.enable bit in

Enables PWM generator N-when false, all pwmgen.Noutput pins are low.

pwmgen.N.value ﬂoat 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 wav eform.

pwmgen.N.dir bit out (output type 1 only)

Direction output: lowfor forward, high for reverse.

pwmgen.N.up bit out (output type 2 only)

PWM/PDM wav eform for positive input values, lowfor negative inputs.

pwmgen.N.down bit out (output type 2 only)

PWM/PDM wav eform for negative input values, lowfor positive inputs.

LinuxCNC Documentation 2007-01-16 253

PWMGEN(9) HAL Component PWMGEN(9)

PARAMETERS

pwmgen.N.curr-dc ﬂoat 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 ﬂoat 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 lowtime to

recharge.

pwmgen.N.min-dc ﬂoat rw

The minimum duty cycle. A value of 1.0 corresponds to 100%. Note that when the pwm genera-

tor is disabled, the outputs are constantly low, reg a rdless of the setting of min-dc.

pwmgen.N.scale ﬂoat rw

pwmgen.N.offset ﬂoat 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 ﬂoat rw

PWM frequencyinHz. The upper limit is half of the frequencyatwhich 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 pro-

duces Pulse Density Modulation instead of Pulse Width Modulation.

pwmgen.N.dither-pwm bit rw

Because software-generated PWM uses a fairly slowtimebase (several to manymicroseconds), it

has limited resolution. Forexample, 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 twoclosest values, so that the long-term average is closer to the desired level. dither-

pwm 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’sManual 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 ﬁle. sam-

pler is a realtime HAL component that exports HAL pins and creates a FIFO in shared memory.Itthen

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 ﬁle 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. Multi-

ple values of depth (separated by commas) can be speciﬁed if you need more than one FIFO (for

example if you want to sample data from twodifferent realtime threads).

cfg=string1[,string2...]

deﬁnes 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. Legalcharacters are:

F, f (ﬂoat 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.Minput

Pin for the data that will wind up in column Mof FIFO N(and in column Mof the output ﬁle).

The pin type depends on the conﬁg string.

sampler.N.curr-depth s32 output

Current number of samples in the FIFO. When this reaches depth newdata will begin overwriting

old data, and some samples will be lost.

sampler.N.full bit output

TRUE when the FIFO Nis 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 wheneverfull is true, and can be reset by the setp command.

256 2006-11-18 LinuxCNC Documentation

SAMPLER(9) HAL User’sManual SAMPLER(9)

sampler.N.sample-num s32 read/write

Anumber that identiﬁes 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 ﬁrst 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 mem-

bers of the LinuxCNC development team.

REPORTING BUGS

Report bugs to jmkasunich ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

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 ﬂoating-point thread)

PINS scale.N.in ﬂoat in

scale.N.gain ﬂoat in

scale.N.offset ﬂoat in

scale.N.out ﬂoat 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.outMbit 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 driverfor 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 volt-

ages, 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. Tofree up the I/O ports after bootup, install setserial and execute a command

like: sudo setserial /dev/ttyS0 uart none

butitisbest to ensure that the serial port is neverused or conﬁgured 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

USAGEloadrt setsserial cmd="{command} {parameter/device} {value/ﬁlename}"

Commands available are set and ﬂash.

This utility should be used under halcmd, without LinuxCNC running or anyrealtime threads running.

Atypical command sequence would be:

halrun

loadrt hostmot2 use_serial_numbers=1

loadrt hm2_pci conﬁg="ﬁrmware=hm2/5i23/svss8_8.bit"

showparam

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 driverinthe normal way.The hm2_7i43 drivershould work equally well,

as should anyfuture 7i80 driver. Ifthe card has already been strted up and a ﬁrmware has been loaded,

then the conﬁg string may be omitted.

"showparam" is optional, but provides a handy list of all the devices and parameters. It also shows the cur-

rent values of the parameters which can be useful for determining scaling. u32 pin values are always shown

in hex, but newvalues can be entered in decimal or hex. Use the Ox123ABC format to enter a hexvalue.

The next line invokessetsserial. This is run in a slightly strange way in order to have kernel-levelaccess to

aliv e Hostmot2 conﬁg. It is basically a HAL module that always fails to load. This may lead to error mes-

sages 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 windowopen to run dmesg after each command.

On exiting there will typically be a further error message related to the driverfailing to unload setsserial.

This can be ignored.

The parameter changes will not showupuntil the drivers are reloaded. //TODO// Add a "get" command to

avoid this problem.

Flashing Firmware To ﬂash newﬁrmware to an FPGA card such as the 5i25 or 5i20 the "mesaﬂash" util-

ity should be used. Setsserial is only useful for changing/updating the ﬁrmare on smart-serial remote such

as the 8i20. The ﬁrmware should be placed somewhere in the /lib/ﬁrmware/hm2 tree, where the Linux

ﬁrmware loading macros can ﬁnd it.

The ﬂashing 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 twoterminal windows, one for command entry and one to moni-

tor progress.

In the ﬁrst terminal enter

tail -f /var/log/kern.log

This terminal will nowdisplay status information.

The second windowwill be used to enter the commands. It is important that LinuxCNC and/or HAL are not

already loaded when the process is started. To ﬂash newﬁrmware it is necessary to move a jumper on the

smart-serial remote drive and to switch smart-serial communication to a slower baudrate.

Atypical command sequence is then

halrun

loadrt hostmot2 sserial_baudrate=115200

loadrt hm2_pci conﬁg="ﬁrmware=hm2/5i23/svss8_8.bit"

loadrt setsserial cmd="ﬂash hm2_5i23.0.8i20.0.1 hm2/8i20/8i20T.BIN"

exit

It is not necessary (or useful) to specify a conﬁg string in a system using the 5i25 or 6i25 cards.

Note that it is necessary to exit halrun and unload the realtime environment before ﬂashing 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 wav eforms.

It produces sine, cosine, triangle, sawtooth, and square wav esofvariable 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 sepa-

rated by commas.

The num_chan= and names= speciﬁers are mutually exclusive.Ifneither num_chan= nor names= are

speciﬁed, the default value is one.

NAMING

The names for pins, parameters, and functions are preﬁxed 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 ﬂoating-point)

Updates output pins for signal generator N.Each time it is called it calculates a newsample. It

should be called manytimes faster than the desired signal frequency, toavoid distortion and alias-

ing.

PINS siggen.N.frequency ﬂoat in

The output frequencyfor signal generator N,inHertz. The default value is 1.0 Hertz.

siggen.N.amplitude ﬂoat in

The output amplitude for signal generator N.Ifoffset is zero, the outputs will swing from -ampli-

tude to +amplitude.The default value is 1.00.

siggen.N.offset ﬂoat 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 ﬂoat out

The square wav e output. Positive while triangle and cosine are ramping upwards, and while sine

is negative.

siggen.N.sine ﬂoat out

The sine output. Lags cosine by 90 degrees.

264 2007-01-16 LinuxCNC Documentation

SIGGEN(9) HAL Component SIGGEN(9)

siggen.N.cosine ﬂoat out

The cosine output. Leads sine by 90 degrees.

siggen.N.triangle ﬂoat out

The triangle wav e 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 ﬂoat 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.Italso generates an indexpulse 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, asdoall 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 sepa-

rated by commas.

The num_chan= and names= speciﬁers are mutually exclusive.Ifneither num_chan= nor names= are

speciﬁed, the default value is one.

FUNCTIONS

sim-encoder.make-pulses (no ﬂoating-point)

Generates the actual quadrature and indexpulses. 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 ﬂoating-point)

Reads the speed command and other parameters and converts the data into a form that can be used

by make-pulses.Changes takeeffect 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 preﬁxed 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 indexpulse.

sim-encoder.N.speed ﬂoat in

The desired speed of the encoder,inuser 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 revolu-

tion. Each pulse or cycle from the encoder results in four counts, because every edge is counted.

Default value is 100 ppr,or400 counts per revolution.

sim-encoder.N.scale ﬂoat rw

Scale factor for the speed input. The speed value is divided by scale to get the actual encoder

speed in revolutions per second. Forexample, 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 indexpulse

SYNOPSIS

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

FUNCTIONS

sim-spindle.N(requires a ﬂoating-point thread)

PINS sim-spindle.N.velocity-cmd ﬂoat in

Commanded speed

sim-spindle.N.position-fb ﬂoat 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 ﬂoat rw (default: 1.0)

factor applied to velocity-cmd.

The result of ’velocity-cmd *scale’beinrev olutions per second. Forexample, 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

JeffEpler

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 269

SSERIAL(9) HAL Component SSERIAL(9)

NAME hostmot2 - Smart Serial LinuxCNC HAL driverfor 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 theycombine various classes of IO. The remot cards are self-conﬁguring, in that

theytell the main LinuxCNC Hostmot2 driverwhat their pin functions are and what theyshould be named.

Manysserial remotes offer different pinouts depending on the mode theyare 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 necessar-

ily always the case.

PORTSIn addition to the per-channel/device pins detailed belowthere are three per-port pins and three parameters.

Pins:

(bit, in) .sserial.port-N.run: Enables the speciﬁc Smart Serial module. Setting this pin lowwill 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 re-

enable a faulted drive sothe 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

showavalue 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: Anyover-run or handshaking error in the SmartSerial communications will increment

the .fault-count pin by the amount speciﬁed 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 corre-

sponding port will be stopped and an error printed in dmesg. Together these three pins allowfor control

overthe 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 everberaised, 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 ACservomotors. 8i20 pins

and parameters have names like"hm2_<BoardType>.<BoardNum>.8i20.<PortNum>.<Chan-

Num>.<Pin>", 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 ﬁrst 5i23 board. Note that

the sserial ports do not necessarily correlate in layout or number to the physical ports on the card.

Pins:

(ﬂoat 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.A6pole 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 rawrotor angle. There is a HAL module (bldc) which han-

dles the complexity of differing motor and drive types.

(ﬂoat, 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.

(ﬂoat, ro) voltage

The drive bus voltage in V.This will tend to show25.6V when the drive isunpowered and the

drive will not operate belowabout 50V.

(ﬂoat, ro) temp

The temperature of the driverindegrees 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-cur-

rent / 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.no-

enable / fault.no-enable-not fault.overcurrent / fault.overcurrent-not fault.overrun / fault.overrun-

not 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 / sta-

tus.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.sw-

reset-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

(ﬂoat, 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_<BoardType>.<BoardNum>.7i64. <PortNum>.<ChanNum>.<Pin>", 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 driverNN.

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 copyofthe corresponding input.

(ﬂoat, out) 7i64.0.0.analog0 & 7i64.0.0.analog1: The twoanalogue 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) HAL Component SSERIAL(9)

7i76 The 7i76 is not only a smart-serial device. It also serves as a breakout for a number of other Host-

mot2 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:

(ﬂoat out) .7i76.0.0.analogN (modes 1 and 2 only) Analogue input values.

(ﬂoat out) .7i76.0.0.ﬁeldvoltage (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 drivesthe spindle-enable terminals on the 7i76 board.

(ﬂoat 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 copyofthe inputs provided for conve-

nience. The twocomplementary 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 unlikleytoneed 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.

(ﬂoat rw) .7i76.0.0.spinout-maxlim: The maximum speed request allowable

(ﬂoat rw) .7i76.0.0.spinout-minlim: The minimum speed request.

(ﬂoat 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, ifspinout-maxlim were set to 5,000 rpm then no voltage above 5Vwould be out-

put.

LinuxCNC Documentation 2008-05-13 273

SSERIAL(9) HAL Component SSERIAL(9)

(u32 ro) .7i76.0.0.swrevision: The onboard ﬁrmware revision number.Utilities exist to update and

change this ﬁrmware.

7i77 The 7i77 is an 6-axis servocontrol 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 host-

mot2 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 copyofthe inputs provided for conve-

nience. The twocomplementary 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 drivesthe spindle-enable terminals on the 7i76 board.

(ﬂoat 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 drivesthe analog enable terminals on the 7i77 board.

(ﬂoat 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.

(ﬂoat rw) .7i77.0.0.spinout-maxlim: The maximum speed request allowable

(ﬂoat rw) .7i77.0.0.spinout-minlim: The minimum speed request.

(ﬂoat 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, ifspinout-maxlim were set to 5,000 rpm then no voltage above 5Vwould be out-

put.

(ﬂoat rw) .7i77.0.0.analogoutN-maxlim: (N = 0 to 5) The maximum speed request allowable

(ﬂoat 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 ////

(ﬂoat 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, ifspinout-maxlim were set to 5,000 rpm then no voltage

above 5Vwould be output.

274 2008-05-13 LinuxCNC Documentation

SSERIAL(9) HAL Component SSERIAL(9)

7i69 The 7i69 is a 48 channel digital IO card. It can be conﬁgured in four different modes: Mode 0 B

48 pins bidirectional (all outputs can be set high then drivenlow towork 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 unlikleytoneed 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 ﬁrmware revision number.Utilities exist to update and

change this ﬁrmware.

7i70

The 7I70 is a remote isolated 48 input card. The 7I70 inputs sense positive inputs relative toa

common ﬁeld ground. Input impedance is 10K Ohms and input voltage can range from 5VDC to

32VDC. All inputs have LED status indicators. The input common ﬁeld 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 ﬁeld voltage

Pins:

(ﬂoat out) .7i70.0.0.analogN (modes 1 and 2 only) Analogue input values.

(ﬂoat out) .7i70.0.0.ﬁeldvoltage (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 copyofthe inputs provided for

LinuxCNC Documentation 2008-05-13 275

SSERIAL(9) HAL Component SSERIAL(9)

convenience. The twocomplementary 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 unlikleytoneed to be changed.

(u32 ro) .7i69.0.0.swrevision: The onboard ﬁrmware revision number.Utilities exist to update and

change this ﬁrmware.

7i71

The 7I71 is a remote isolated 48 output card. The 48 outputs are 8VDC to 28VDC sourcing drivers

(common + ﬁeld power) with 300 mA maximum current capability.All outputs have LED status

indicators.

The 7I71 has twosoftware 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 ﬁeld voltage

Pins:

(ﬂoat out) .7i71.0.0.ﬁeldvoltage (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 unlikleytoneed to be changed.

(u32 ro) .7i69.0.0.swrevision: The onboard ﬁrmware revision number.Utilities exist to update and

change this ﬁrmware.

276 2008-05-13 LinuxCNC Documentation

SSERIAL(9) HAL Component SSERIAL(9)

7i73 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 out-

puts 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

4line 20 character LCD for local DROapplications.

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:

(ﬂoat out) .7i73.0.0.analoginN: Analogue inputs. Up to 8 channels may be available dependant on

software and hardware conﬁguration 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

drivenbythe HAL "lcd" component which allows the formatted display of the values anynumber

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 sup-

ported 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 conﬁg)

(bit out) .7i73.0.1.input-NN-not: Inverted copyofthe digital inputs

(bit in) .7i73.0.1.output-NN: Up to 22 digital outputs (dependent on conﬁg)

Parameters:

(u32 ro) .7i73.0.1.nvanalogﬁlter:

(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 ﬁrmware 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 twocontrol modes, which can be selected on a channel by channel basis using ctrl_type.Pos-

sible values are "p"for position control, and "v"for velocity control. The default is position control, which

drivesthe motor to a commanded position, subject to acceleration and velocity limits. Velocity control

drivesthe 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 speciﬁc 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 ﬁvephase 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

Tw o 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

Tw o pins, one for ’step up’ and one for ’step down’. Liketype 0, make-pulses must run twice per

step, which limits the maximum speed.

type 2: quadrature

Tw o pins, phase-A and phase-B. Forforward 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 Aishigh 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-collec-

tor transistors drive the ends. Types 7 and 8 are suitable for bipolar steppers, drivenbytwo H-

bridges.

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: ﬁvephase, full step

Five pins, phases A through E. Five steps per full cycle. See HAL reference manual for the pat-

terns.

types 13 and 14: ﬁvephase, half step

Five pins, phases A through E. Tensteps per full cycle. See HAL reference manual for the pat-

terns.

type 15: user-speciﬁed

This uses the wav eform speciﬁed by the user_step_type module parameter,which may have upto

10 steps and 5 phases.

FUNCTIONS

stepgen.make-pulses (no ﬂoating-point)

Generates the step pulses, using information computed by update-freq.Must be called as fre-

quently as possible, to maximize the attainable step rate and minimize jitter.Operates on all chan-

nels at once.

stepgen.capture-position (uses ﬂoating 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 ﬂoating 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 ﬂoat out

The current position, in length units (see parameter position-scale). Updated by capture-posi-

tion.The resolution of position-fb is much ﬁner 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 ﬂoat in (velocity mode only)

Commanded velocity,inlength units per second (see parameter position-scale).

stepgen.N.position-cmd ﬂoat 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: lowfor 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, phase-

Dfor 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 ﬂoat ro

The current step rate, in steps per second, for channel N.

stepgen.N.maxaccel ﬂoat rw

The acceleration/deceleration limit, in length units per second squared.

stepgen.N.maxvel ﬂoat rw

The maximum allowable velocity,inlength 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 ﬂoat 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.Ifstepspace is 0, then step can be asserted

ev e ry 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 ﬁvetiming parameters which control the output wav eform. No step type uses all ﬁve, 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, theyare ident-

ﬁed by the following numbers:

(1) stepgen.n.steplen

(2) stepgen.n.stepspace

(3) stepgen.n.dirhold

(4) stepgen.n.dirsetup

(5) stepgen.n.dirdelay

Forstep type 0, timing parameters 1 thru 4 are used. The following timing diagram shows the output wav e -

forms, and what each parameter adjusts.

_____ _____ _____

STEP ____/ \_______/ \_____________/ \______

|| || ||

Time |-(1)-|--(2)--|-(1)-|--(3)--|-(4)-|-(1)-|

|__________________

DIR ________________________________/

LinuxCNC Documentation 2007-01-16 281

STEPGEN(9) HAL Component STEPGEN(9)

Forstep 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 |-(1)-|-(2)-|-(1)-|---(5)---|-(1)-|-(2)-|-(1)-|

|_____| |_____|

DOWN ______________________________/ \_____/ \____

Forstep 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 ﬁrst in the other

direction is the sum of steplen and dirdelay.

SEE ALSO

The HAL User Manual.

282 2007-01-16 LinuxCNC Documentation

STEPTEST(9) HAL Component STEPTEST(9)

NAME steptest − Used by Stepconf to allowtesting of acceleration and velocity values for an axis.

SYNOPSIS

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

FUNCTIONS

steptest.N(requires a ﬂoating-point thread)

PINS steptest.N.jog-minus bit in

Drive TRUEtojog the axis in its minus direction

steptest.N.jog-plus bit in

Drive TRUEtojog the axis in its positive direction

steptest.N.run bit in

Drive TRUEtorun the axis near its current position_fb with a trapezoidal velocity proﬁle

steptest.N.maxvel ﬂoat in

Maximum velocity

steptest.N.maxaccel ﬂoat in

Permitted Acceleration

steptest.N.amplitude ﬂoat in

Approximate amplitude of positions to command during ’run’

steptest.N.dir s32 in

Direction from central point to test: 0 = both, 1 = positive,2=neg ative

steptest.N.position-cmd ﬂoat out

steptest.N.position-fb ﬂoat in

steptest.N.running bit out

steptest.N.run-target ﬂoat out

steptest.N.run-start ﬂoat out

steptest.N.run-low ﬂoat out

steptest.N.run-high ﬂoat out

steptest.N.pause s32 in (default: 0)

pause time for each end of run in seconds

PARAMETERS

steptest.N.epsilon ﬂoat rw (default: .001)

steptest.N.elapsed ﬂoat r

Current value of the internal timer

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 283

STREAMER(9) HAL User’sManual STREAMER(9)

NAME streamer − stream ﬁle data into HAL in real time

SYNOPSIS

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

DESCRIPTION

streamer and halstreamer(1) are used together to stream data from a ﬁle into the HAL in real time.

streamer is a realtime HAL component that exports HAL pins and creates a FIFO in shared memory.

hal_streamer is a user space program that copies data from stdin into the FIFO, so that streamer can write

it to the HAL pins.

OPTIONS

depth=depth1[,depth2...]

sets the depth of the user->realtime FIFO that streamer creates to receive data from halstreamer.

Multiple values of depth (separated by commas) can be speciﬁed if you need more than one FIFO

(for example if you want to stream data from twodifferent realtime threads).

cfg=string1[,string2...]

deﬁnes the set of HAL pins that streamer exports and later writes data to. One string must be

supplied for each FIFO, separated by commas. streamer exports one pin for each character in

string. Legalcharacters are:

F, f (ﬂoat pin)

B, b (bit pin)

S, s (s32 pin)

U, u (u32 pin)

FUNCTIONS

streamer.N

One function is created per FIFO, numbered from zero.

PINS streamer.N.pin.Moutput

Data from column Mof the data in FIFO Nappears on this pin. The pin type depends on the con-

ﬁg string.

streamer.N.curr-depth s32 output

Current number of samples in the FIFO. When this reaches zero, newdata will no longer be writ-

ten to the pins.

streamer.N.empty bit output

TRUE when the FIFO Nis empty,FALSE when valid data is available.

streamer.N.enable bit input

When TRUE, data from FIFO Nis written to the HAL pins. When false, no data is transferred.

Defaults to TRUE.

streamer.N.underruns s32 read/write

The number of times that sampler has tried to write data to the HAL pins but found no fresh data

in the FIFO. It increments wheneverempty is true, and can be reset by the setp command.

SEE ALSO

halstreamer(1) sampler(9) halsampler(1)

284 2006-11-18 LinuxCNC Documentation

STREAMER(9) HAL User’sManual STREAMER(9)

HISTORY

BUGS Should an enable HAL pin be added, to allowstreaming to be turned on and off?

AUTHOR

Original version by John Kasunich, as part of the LinuxCNC project. Improvements by several other mem-

bers of the LinuxCNC development team.

REPORTING BUGS

Report bugs to jmkasunich ATusers DOTsourceforge DOTnet

This is free software; see the source for copying conditions. There is NO warranty; not evenfor MER-

CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

LinuxCNC Documentation 2006-11-18 285

SUM2(9) HAL Component SUM2(9)

NAME sum2 − Sum of twoinputs (each with a gain) and an offset

SYNOPSIS

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

FUNCTIONS

sum2.N(requires a ﬂoating-point thread)

PINS sum2.N.in0 ﬂoat in

sum2.N.in1 ﬂoat in

sum2.N.out ﬂoat out

out = in0 * gain0 + in1 * gain1 + offset

PARAMETERS

sum2.N.gain0 ﬂoat rw (default: 1.0)

sum2.N.gain1 ﬂoat rw (default: 1.0)

sum2.N.offset ﬂoat rw

LICENSE

GPL

286 2014-12-18 LinuxCNC Documentation

SUPPLY(9) HAL Component SUPPLY(9)

NAME supply − set output pins with values from parameters (obsolete)

SYNOPSIS

loadrt supply num_chan=num

DESCRIPTION

supply wasused to allowthe inputs of other HAL components to be manipulated for testing purposes.

When it was written, the only way to set the value of an input pin was to connect it to a signal and connect

that signal to an output pin of some other component, and then let that component write the pin value. sup-

ply waswritten to be that "other component". It reads values from parameters (set with the HAL command

setp)and writes them to output pins.

Since supply waswritten, the setp command has been modiﬁed to allowittoset unconnected pins as well

as parameters. In addition, the sets command was added, which can directly set HAL signals, as long as

there are no output pins connected to them. Therefore, supply is obsolete.

supply supports a maximum of eight channels. The number of channels actually loaded is set by the

num_chan argument when the module is loaded. If numchan is not speciﬁed, the default value is one.

FUNCTIONS

supply.N.update (uses ﬂoating-point)

Updates output pins for channel N.

PINS supply.N.q bit out

Output bit, copied from parameter supply.N.d.

supply.N._q bit out

Output bit, inverted copyofparameter supply.N.d.

supply.N.variable ﬂoat out

Analog output, copied from parameter supply.N.value.

supply.N._variable ﬂoat out

Analog output, equal to -1.0 times parameter supply.N.value.

supply.N.d bit rw

Data source for qand _q output pins.

supply.N.value bit rw

Data source for variable and _variable output pins.

LinuxCNC Documentation 2007-01-16 287

THC(9) HAL Component THC(9)

NAME thc − Torch Height Control

SYNOPSIS

loadrt thc

DESCRIPTION

Torch Height Control Mesa THC > Encoder > LinuxCNC THC component

The Mesa THC sends a frequencybased on the voltage detected to the encoder.The velocity from the

encoder is converted to volts with the velocity scale parameter inside the THC component.

The THCAD card sends a frequencyat0volts so the scale offset parameter is used to zero the calculated

voltage.

Component Functions If enabled and torch is on and X + Y velocity is within tolerance of set speed allow

the THC to offset the Z axis as needed to maintain voltage.

If enabled and torch is offand the Z axis is moving up remove any correction at a rate not to exceed the rate

of movement of the Z axis.

If enabled and torch is offand there is no correction pass the Z position and feed back untouched.

If not enabled pass the Z position and feed back untouched.

Physical Connections

Plasma Torch Arc Voltage Signal => 6 x 487k 1% resistors => THC Arc Voltage In

THC FrequencySignal => Encoder #0, pin A (Input)

Plasma Torch Arc OK Signal => input pin

output pin => Plasma Torch Start Arc Contacts

HAL Plasma Connections

encoder.nn.velocity => thc.encoder-vel (tip voltage)

motion.spindle-on => output pin (start the arc)

thc.arc-ok <= motion.digital-in-00 <= input pin (arc ok signal)

HAL Motion Connections

thc.requested-vel <= motion.requested-vel

thc.current-vel <= motion.current-vel

FUNCTIONS

thc (requires a ﬂoating-point thread)

PINS thc.encoder-vel ﬂoat in

Connect to hm2_5i20.0.encoder.00.velocity

thc.current-vel ﬂoat in

Connect to motion.current-vel

thc.requested-vel ﬂoat in

Connect to motion.requested-vel

thc.volts-requested ﬂoat in

TipVolts current_vel >= min_velocity requested

288 2014-12-18 LinuxCNC Documentation

THC(9) HAL Component THC(9)

thc.vel-tol ﬂoat in

Velocity Tolerance (Corner Lock)

thc.torch-on bit in

Connect to motion.spindle-on

thc.arc-ok bit in

Arc OK from Plasma Torch

thc.enable bit in

Enable the THC, if not enabled Z position is passed through

thc.z-pos-in ﬂoat in

ZMotor Position Command in from axis.n.motor-pos-cmd

thc.z-pos-out ﬂoat out

ZMotor Position Command Out

thc.z-fb-out ﬂoat out

ZPosition Feedback to Axis

thc.volts ﬂoat out

The Calculated Volts

thc.vel-status bit out

When the THC thinks we are at requested speed

PARAMETERS

thc.vel-scale ﬂoat rw

The scale to convert the Velocity signal to Volts

thc.scale-offset ﬂoat rw

The offset of the velocity input at 0 volts

thc.velocity-tol ﬂoat rw

The deviation percent from planned velocity

thc.voltage-tol ﬂoat rw

The deviation of Tip Voltage before correction takes place

thc.correction-vel ﬂoat rw

The amount of change in user units per period to move Z tocorrect

AUTHOR

John Thornton

LICENSE

GPLv2 or greater

LinuxCNC Documentation 2014-12-18 289

THCUD(9) HAL Component THCUD(9)

NAME thcud − Torch Height Control Up/Down Input

SYNOPSIS

loadrt thcud

DESCRIPTION

Torch Height Control This THC takes either an up or a down input from a THC

If enabled and torch is on and X + Y velocity is within tolerance of set speed allowthe THC to offset the Z

axis as needed to maintain voltage.

If enabled and torch is offand the Z axis is moving up remove any correction at a rate not to exceed the rate

of movement of the Z axis.

If enabled and torch is offand there is no correction pass the Z position and feed back untouched.

If not enabled pass the Z position and feed back untouched.

Physical Connections typical paraport.0.pin-12-in <= THC controller Plasma Up paraport.0.pin-13-in <=

THC controller Plasma Down parport.0.pin-15-in <= Plasma Torch Arc Ok Signal parport.0.pin-16-out =>

Plasma Torch Start Arc Contacts

HAL Plasma Connections thc.torch-up <= paraport.0.pin-12-in thc.torch-down <= paraport.0.pin-13-in

motion.spindle-on => parport.0.pin-16-out (start the arc) thc.arc-ok <= motion.digital-in-00 <= par-

port.0.pin-15-in (arc ok signal)

HAL Motion Connections thc.requested-vel <= motion.requested-vel thc.current-vel <= motion.current-vel

Pyvcp Connections In the xml ﬁle you need something like:

<text>"THC Enable"</text>

<halpin>"thc-enable"</halpin> </checkbutton> <spinbox>

<min_>.01</min_>

<max_>1</max_>

<font>("Arial",10)</font> </spinbox>

Connect the Pyvcp pins in the postgui.hal ﬁle likethis:

net thc-enable thcud.enable <= pyvcp.thc-enable

FUNCTIONS

thcud (requires a ﬂoating-point thread)

PINS thcud.torch-up bit in

Connect to an input pin

290 2014-12-18 LinuxCNC Documentation

THCUD(9) HAL Component THCUD(9)

thcud.torch-down bit in

Connect to input pin

thcud.current-vel ﬂoat in

Connect to motion.current-vel

thcud.requested-vel ﬂoat in

Connect to motion.requested-vel

thcud.torch-on bit in

Connect to motion.spindle-on

thcud.arc-ok bit in

Arc Ok from Plasma Torch

thcud.enable bit in

Enable the THC, if not enabled Z position is passed through

thcud.z-pos-in ﬂoat in

ZMotor Position Command in from axis.n.motor-pos-cmd

thcud.z-pos-out ﬂoat out

ZMotor Position Command Out

thcud.z-fb-out ﬂoat out

ZPosition Feedback to Axis

thcud.cur-offset ﬂoat out

The Current Offset

thcud.vel-status bit out

When the THC thinks we are at requested speed

thcud.removing-offset bit out

Pin for testing

PARAMETERS

thcud.velocity-tol ﬂoat rw

The deviation percent from planned velocity

thcud.correction-vel ﬂoat rw

The Velocity to move Z tocorrect

AUTHOR

John Thornton

LICENSE

GPLv2 or greater

LinuxCNC Documentation 2014-12-18 291

THREADS(9) HAL Component THREADS(9)

NAME threads − creates hard realtime HAL threads

SYNOPSIS

loadrt threads name1=name period1=period [fp1=<0|1>] [<thread-2-info>] [<thread-3-info>]

DESCRIPTION

threads is used to create hard realtime threads which can execute HAL functions at speciﬁc intervals. It is

not a true HAL component, in that it does not export anyfunctions, pins, or parameters of its own. Once it

has created one or more threads, the threads stand alone, and the threads component can be unloaded with-

out affecting them. In fact, it can be unloaded and then reloaded to create additional threads, as manytimes

as needed.

threads can create up to three realtime threads. Threads must be created in order,from fastest to slowest.

Each thread is speciﬁed by three arguments. name1 is used to specify the name of the ﬁrst thread (thread

1). period1 is used to specify the period of thread 1 in nanoseconds. Both name and period are required.

The third argument, fp1 is optional, and is used to specify if thread 1 will be used to execute ﬂoating point

code. If not speciﬁed, it defaults to 1,which means that the thread will support ﬂoating point. Specify 0to

disable ﬂoating point support, which savesasmall amount of execution time by not saving the FPU con-

text. For additional threads, name2,period2,fp2,name3,period3,and fp3 work exactly the same. If

more than three threads are needed, unload threads, then reload it to create more threads.

FUNCTIONS

None

PINS None

PARAMETERS

None

BUGS The existence of threads might be considered a bug. Ideally,creation and deletion of threads would be

done directly with halcmd commands, such as "newthread name period", "delthread name", or similar.

However, limitations in the current HAL implementation require thread creation to takeplace in kernel

space, and loading a component is the most straightforward way to do that.

292 2007-01-16 LinuxCNC Documentation

THREADTEST(9) HAL Component THREADTEST(9)

NAME threadtest − LinuxCNC HAL component for testing thread behavior

SYNOPSIS

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

FUNCTIONS

threadtest.N.increment

threadtest.N.reset

PINS threadtest.N.count u32 out

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 293

TIME(9) HAL Component TIME(9)

NAME time − Time on in Hours, Minutes, Seconds

SYNOPSIS

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

DESCRIPTION

Time

When the time.N.start bit goes true the cycle timer resets and starts to time until time.N.start goes false. If

you connect time.N.start to halui.is-running as a cycle timer it will reset during a pause. See the example

connections belowtokeep the timer timing during a pause.

Time returns the hours, minutes, and seconds that time.N.start is true.

Sample pyVCP code to display the hours:minutes:seconds.

<pyvcp>

<hbox>

<label>

<text>"Cycle Time"</text>

<font>("Helvetica",14)</font>

</label>

<u32>

<halpin>"time-hours"</halpin>

<font>("Helvetica",14)</font>

</u32>

<label>

<font>("Helvetica",14)</font>

</label>

<u32>

<halpin>"time-minutes"</halpin>

<font>("Helvetica",14)</font>

</u32>

<label>

<font>("Helvetica",14)</font>

</label>

<u32>

<halpin>"time-seconds"</halpin>

<font>("Helvetica",14)</font>

</u32>

</hbox> </pyvcp>

In your post-gui.hal ﬁle you might use the following to connect it up

loadrt time

loadrt not

addf time.0 servo-thread

addf not.0 servo-thread

net prog-running not.0.in <= halui.program.is-idle

net cycle-timer time.0.start <= not.0.out

294 2014-12-18 LinuxCNC Documentation

TIME(9) HAL Component TIME(9)

net cycle-seconds pyvcp.time-seconds <= time.0.seconds

net cycle-minutes pyvcp.time-minutes <= time.0.minutes

net cycle-hours pyvcp.time-hours <= time.0.hours

FUNCTIONS

time.N(requires a ﬂoating-point thread)

PINS time.N.start bit in

Timer On

time.N.seconds u32 out

Seconds

time.N.minutes u32 out

Minutes

time.N.hours u32 out

Hours

AUTHOR

John Thornton

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 295

TIMEDELAY(9) HAL Component TIMEDELAY(9)

NAME timedelay − The equivalent of a time-delay relay

SYNOPSIS

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

FUNCTIONS

timedelay.N(requires a ﬂoating-point thread)

PINS timedelay.N.in bit in

timedelay.N.out bit out

Follows the value of in after applying the delays on-delay and off-delay.

timedelay.N.on-delay ﬂoat in (default: 0.5)

The time, in seconds, for which in must be true before out becomes true

timedelay.N.off-delay ﬂoat in (default: 0.5)

The time, in seconds, for which in must be false before out becomes false

timedelay.N.elapsed ﬂoat out

Current value of the internal timer

AUTHOR

JeffEpler,based on works by Stephen Wille Padnos and John Kasunich

LICENSE

GPL

296 2014-12-18 LinuxCNC Documentation

TIMEDELTA(9) HAL Component TIMEDELTA(9)

NAME timedelta − LinuxCNC HAL component that measures thread scheduling timing behavior

SYNOPSIS

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

FUNCTIONS

timedelta.N

PINS timedelta.N.out s32 out

timedelta.N.err s32 out (default: 0)

timedelta.N.min s32 out (default: 0)

timedelta.N.max s32 out (default: 0)

timedelta.N.jitter s32 out (default: 0)

timedelta.N.avg-err ﬂoat out (default: 0)

timedelta.N.reset bit in

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 297

TOGGLE(9) HAL Component TOGGLE(9)

NAME toggle − ’push-on, push-off’ from momentary pushbuttons

SYNOPSIS

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

FUNCTIONS

toggle.N

PINS toggle.N.in bit in

button input

toggle.N.out bit io

on/offoutput

PARAMETERS

toggle.N.debounce u32 rw (default: 2)

debounce delay in periods

LICENSE

GPL

298 2014-12-18 LinuxCNC Documentation

TOGGLE2NIST(9) HAL Component TOGGLE2NIST(9)

NAME toggle2nist − toggle button to nist logic

SYNOPSIS

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

DESCRIPTION

toggle2nist can be used with a momentary push button connected to a toggle component to control a device

that has seperate on and offinputs and has an is-on output. If in changes states via the toggle output

If is-on is true then on is false and offistrue.

If is-on is false the on true and offisfalse.

FUNCTIONS

toggle2nist.N(requires a ﬂoating-point thread)

PINS toggle2nist.N.in bit in

toggle2nist.N.is-on bit in

toggle2nist.N.on bit out

toggle2nist.N.off bit out

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 299

TRISTATE_BIT(9) HAL Component TRISTATE_BIT(9)

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

SYNOPSIS

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

FUNCTIONS

tristate-bit.N

If enable is TRUE, copy in to out.

PINS tristate-bit.N.in bit in

Input value

tristate-bit.N.out bit io

Output value

tristate-bit.N.enable bit in

When TRUE, copyintoout

LICENSE

GPL

300 2014-12-18 LinuxCNC Documentation

TRISTATE_FLOAT(9) HAL Component TRISTATE_FLOAT(9)

NAME tristate_ﬂoat − Place a signal on an I/O pin only when enabled, similar to a tristate buffer in electronics

SYNOPSIS

loadrt tristate_ﬂoat [count=N|names=name1[,name2...]]

FUNCTIONS

tristate-ﬂoat.N(requires a ﬂoating-point thread)

If enable is TRUE, copy in to out.

PINS tristate-ﬂoat.N.in ﬂoat in

Input value

tristate-ﬂoat.N.out ﬂoat io

Output value

tristate-ﬂoat.N.enable bit in

When TRUE, copyintoout

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 301

UPDOWN(9) HAL Component UPDOWN(9)

NAME updown − Counts up or down, with optional limits and wraparound behavior

SYNOPSIS

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

FUNCTIONS

updown.N

Process inputs and update count if necessary

PINS updown.N.countup bit in

Increment count when this pin goes from 0 to 1

updown.N.countdown bit in

Decrement count when this pin goes from 0 to 1

updown.N.reset bit in

Reset count when this pin goes from 0 to 1

updown.N.count s32 out

The current count

PARAMETERS

updown.N.clamp bit rw

If TRUE, then clamp the output to the min and max parameters.

updown.N.wrap bit rw

If TRUE, then wrap around when the count goes above orbelowthe min and max parameters.

Note that wrap implies (and overrides) clamp.

updown.N.max s32 rw (default: 0x7FFFFFFF)

If clamp or wrap is set, count will neverexceed this number

updown.N.min s32 rw

If clamp or wrap is set, count will neverbeless than this number

LICENSE

GPL

302 2014-12-18 LinuxCNC Documentation

WA TCHDOG(9) HAL Component WATCHDOG(9)

NAME watchdog − monitor multiple inputs for a "heartbeat"

SYNOPSIS

loadrt watchdog num_inputs=N

Youmust specify the number of inputs, from 1 to 32. Each input has a separate timeout value.

FUNCTIONS

process Check all input pins for transitions, clear the ok-out pin if anyinput has no transition within its

timeout period. This function does not use ﬂoating point, and should be added to a fast thread.

set-timeouts

Check for timeout changes, and convert the ﬂoat timeout inputs to int values that can be used in

process.This function also monitors enable-in for false to true transitions, and re-enables moni-

toring when such a transition is detected. This function does use ﬂoating point, and it is appropri-

ate to add it to the servothread.

PINS watchdog.input-n bit in

Input number n. The inputs are numbered from 0 to num_inputs-1.

watchdog.enable-in bit in (default: FALSE)

If TRUE, forces out-ok to be false. Additionally,ifatimeout occurs on anyinput, this pin must be

set FALSE and TRUE again to re-start the monitoring of input pins.

watchdog.ok-out bit out (default: FALSE)

OK output. This pin is true only if enable-in is TRUE and no timeout has been detected. This out-

put can be connected to the enable input of a charge_pump or stepgen (in v mode), to provide a

heartbeat signal to external monitoring hardware.

PARAMETERS

watchdog.timeout-n ﬂoat in

Timeout value for input number n. The inputs are numbered from 0 to num_inputs-1. The time-

out is in seconds, and may not be belowzero. Note that a timeout of 0.0 will likely prevent ok-out

from everbecoming true. Also note that excessively long timeouts are relatively useless for moni-

toring purposes.

LICENSE

GPL

LinuxCNC Documentation 2010-06-22 303

WCOMP(9) HAL Component WCOMP(9)

NAME wcomp − Windowcomparator

SYNOPSIS

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

FUNCTIONS

wcomp.N(requires a ﬂoating-point thread)

PINS wcomp.N.in ﬂoat in

Value being compared

wcomp.N.min ﬂoat in

Lowboundary for comparison

wcomp.N.max ﬂoat in

High boundary for comparison

wcomp.N.out bit out

True if in is strictly between min and max

wcomp.N.under bit out

True if in is less than or equal to min

wcomp.N.overbit out

True if in is greater than or equal to max

NOTESIf max <= min then the behavior is undeﬁned.

LICENSE

GPL

304 2014-12-18 LinuxCNC Documentation

WEIGHTED_SUM(9) HAL Component WEIGHTED_SUM(9)

NAME weighted_sum − convert a group of bits to an integer

SYNOPSIS

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

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

DESCRIPTION

This component is a "weighted summer": Its output is the offset plus the sum of the weight of each TRUE

input bit. The default value for each weight is 2ˆn where n is the bit number.This results in a binary to

unsigned conversion.

There is a limit of 8 weighted summers and each may have upto16input bits.

FUNCTIONS

process_wsums (requires a ﬂoating point thread)

Read all input values and update all output values.

PINS wsum.N.bit.M.in bit in

The m’thinput of weighted summer n.

wsum.N.hold bit in

When TRUE, the sum output does not change. When FALSE, the sum output tracks the bit inputs

according to the weights and offset.

wsum.N.sum signed out

The output of the weighted summer

wsum.N.bit.M.weight signed rw

The weight of the m’thinput of weighted summer n.The default value is 2ˆm.

wsum.N.offset signed rw

The offset is added to the weights corresponding to all TRUE inputs to give the ﬁnal sum.

LinuxCNC Documentation 2007-01-16 305

WJ200_VFD(9) HAL Component WJ200_VFD(9)

NAME wj200_vfd − Hitachi wj200 modbus driver

SYNOPSIS

wj200_vfd

PINS wj200-vfd.N.commanded-frequency ﬂoat in

Frequencyofvfd

wj200-vfd.N.rev erse bit in

1when reverse 0 when forward

wj200-vfd.N.run bit in

run the vfd

wj200-vfd.N.enable bit in

1toenable the vfd. 0 will remote trip the vfd, thereby disabling it.

wj200-vfd.N.is-running bit out

1when running

wj200-vfd.N.is-at-speed bit out

1when running at assigned frequency

wj200-vfd.N.is-ready bit out

1when vfd is ready to run

wj200-vfd.N.is-alarm bit out

1when vfd alarm is set

wj200-vfd.N.watchdog-out bit out

Alternates between 1 and 0 after every update cycle. Feed into a watchdog component to ensure

vfd driveriscommunicating with the vfd properly.

PARAMETERS

wj200-vfd.N.mbslaveaddr u32 rw

Modbus slave address

LICENSE

GPLv2 or greater

306 2014-12-18 LinuxCNC Documentation

XHC_HB04_UTIL(9) HAL Component XHC_HB04_UTIL(9)

NAME xhc_hb04_util − xhc-hb04 convenience utility

SYNOPSIS

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

DESCRIPTION

Provides logic for a start/pause button and an interface to halui.program.is_paused,is_idle,is_running to

generate outputs for halui.program.pause,resume,run.

Includes 4 simple lowpass ﬁlters with coef and scale pins. The coef value should be 0 <= coef <=1, smaller

coef values slowresponse. Note: the xhc_hb04 component includes smoothing so these values can usually

be left at 1.0

FUNCTIONS

xhc-hb04-util.N(requires a ﬂoating-point thread)

PINS xhc-hb04-util.N.start-or-pause bit in

xhc-hb04-util.N.is-paused bit in

xhc-hb04-util.N.is-idle bit in

xhc-hb04-util.N.is-running bit in

xhc-hb04-util.N.pause bit out

xhc-hb04-util.N.resume bit out

xhc-hb04-util.N.run bit out

xhc-hb04-util.N.in0 s32 in

xhc-hb04-util.N.in1 s32 in

xhc-hb04-util.N.in2 s32 in

xhc-hb04-util.N.in3 s32 in

xhc-hb04-util.N.out0 s32 out

xhc-hb04-util.N.out1 s32 out

xhc-hb04-util.N.out2 s32 out

xhc-hb04-util.N.out3 s32 out

xhc-hb04-util.N.scale0 ﬂoat in (default: 1.0)

xhc-hb04-util.N.scale1 ﬂoat in (default: 1.0)

xhc-hb04-util.N.scale2 ﬂoat in (default: 1.0)

xhc-hb04-util.N.scale3 ﬂoat in (default: 1.0)

xhc-hb04-util.N.coef0 ﬂoat in (default: 1.0)

xhc-hb04-util.N.coef1 ﬂoat in (default: 1.0)

xhc-hb04-util.N.coef2 ﬂoat in (default: 1.0)

xhc-hb04-util.N.coef3 ﬂoat in (default: 1.0)

LICENSE

GPL

LinuxCNC Documentation 2014-12-18 307

XOR2(9) HAL Component XOR2(9)

NAME xor2 − Two-input XOR (exclusive OR) gate

SYNOPSIS

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

FUNCTIONS

xor2.N

PINS xor2.N.in0 bit in

xor2.N.in1 bit in

xor2.N.out bit out

out is computed from the value of in0 and in1 according to the following rule:

in0=TRUE in1=FALSE

in0=FALSE in1=TRUE

out=TRUE

Otherwise,

out=FALSE

LICENSE

GPL

308 2014-12-18 LinuxCNC Documentation

Linux CNC Manual Pages

Navigation menu

Versions of this User Manual:

Views

Navigation