title: limit_axis(9)

summary: Dynamic range based axis limits

text:
# limit_axis(9)

## NAME
limit_axis - Dynamic range based axis limits

## SYNOPSIS
loadrt limit_axis [count=N|names=name1[,name2...]] [personality=P1,P2,...]

## DESCRIPTION
limit_axis.c

Limit axis to certain limits at varying inputs For example on a spindle with C rotation, to avoid hitting a gantry when the height is above Z-10

- Use Z axis as feedback

- Use 2 ranges (0,-10) (-10, -40)

- When Z is above 10, C rotation is limited to range 0

- When Z is below 10, C rotation is limited to range 1

Usage:

loadrt limit_axis count=3 personality=2,3,2

or

loadrt limit_axis names=limit_x,limit_y,limit_z personality=2,3,2

The "personality" argument defines how many ranges are supported by each instance.

(Note that no spaces can be used in the names= and personality= parameters)

Caveats

- Searches ranges from 0 to 9 and will take the first range that matches

- Ranges are inclusive min_range <= feedback <= max_range

- Max can not be less than minimum for any group

- Sticky indicates, to not check other ranges if the feedback is still in the current range

- Enable allows for a range to be turned on/off, for cases such as avoiding a tool changer, but allowing sometimes

## FUNCTIONS
limit-axis.N (requires a floating-point thread)

## PINS
limit-axis.N.error-no-range bit out

error pin indicating that no range matches the fb

limit-axis.N.min-output float out

Minimum limit output

limit-axis.N.max-output float out

Maximum limit output

limit-axis.N.fb float in

Feedback pin, the value of this pin determines which range is active

limit-axis.N.current-range u32 out

Indicates which range is currently active

limit-axis.N.min-limit-MM float in (MM=00..personality)

The array of minimum limits to select from

limit-axis.N.max-limit-MM float in (MM=00..personality)

The array of macimum limits

limit-axis.N.min-range-MM float in (MM=00..personality)

Defines the range of values with which the fb is compared to set the range

limit-axis.N.max-range-MM float in (MM=00..personality)

Defines the range of values with which the fb is compared to set the range

limit-axis.N.enable-MM bit in (MM=00..personality)

Used to enable and disable a specific range

limit-axis.N.sticky-MM bit in (MM=00..personality)

Used to make specific range 'sticky' or not

limit-axis.N.error-range-MM bit out (MM=00..personality) (default: 1)

Error bit indicating that the fb pin falls outside all ranges

limit-axis.N.error-limit-MM bit out (MM=00..personality) (default: 1)

Error bit indicating that the max limit is not larger than the min limit

## AUTHOR
Chad Woitas

## LICENSE
GPL


lincurve

package: linuxcnc

title: lincurve(9)

summary: one-dimensional lookup table

text:
# lincurve(9)

## NAME
lincurve - one-dimensional lookup table

## SYNOPSIS
loadrt lincurve [count=N|names=name1[,name2...]] [personality=P1,P2,...]

## DESCRIPTION
This component can be used to map any floating-point input to a floating-point output. Typical uses would include linearisation of thermocouples, defining PID gains that vary with external factors or to substitute for any mathematical function where absolute accuracy is not required.

The component can be thought of as a 2-dimensional graph of points in (x,y) space joined by straight lines. The input value is located on the x axis, followed up until it touches the line, and the output of the component is set to the corresponding y-value.

The (x,y) points are defined by the x-val-NN and y-val-NN parameters which need to be set in the HAL file using "setp" commands.

The maximum number if (x,y) points supported is 16.

For input values less than the x-val-00 breakpoint the y-val-00 is returned. For x greater than the largest x-val-NN the yval corresponding to x-max is returned (ie, no extrapolation is performed.)

Sample usage: loadrt lincurve count=3 personality=4,4,4 for a set of three 4-element graphs.

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

## PINS
lincurve.N.in float in

The input value

lincurve.N.out float out

The output value

lincurve.N.out-io float io

The output value, compatible with PID gains

## PARAMETERS
lincurve.N.x-val-MM float rw (MM=00..personality)

axis breakpoints

lincurve.N.y-val-MM float rw (MM=00..personality)

output values to be interpolated

## AUTHOR
Andy Pugh

## LICENSE
GPL

branch: sisyphus


lineardeltakins

title: lineardeltakins(9)

summary: Kinematics for a linear delta robot

text:
# lineardeltakins(9)

## NAME
lineardeltakins - Kinematics for a linear delta robot

## SYNOPSIS
loadrt lineardeltakins

## KINEMATICS
The kinematics model is appropriate for a rostock/kossel-style design with three joints arranged in an equilateral triangle. (0,0) is always the center of the working volume. Joint 0 is at (0,R) and subsequent joints are 120 degrees clockwise (note that joint 0 is not at zero radians). The length of the arm is L.

Joints 0-2 are the linear carriages. Axes ABC and UVW are passed through unchanged in joints 3-8, so that e.g., A can still be used to control an extruder.

## PINS
lineardeltakins.R float in

Effective diameter of the platform. R is different than the distance from the center of the table to the center of the belt/smooth rod/extrusion that the joints ride on. In RepRap delta parlance, R is DELTA_RADIUS which is computed as

DELTA_SMOOTH_ROD_OFFSET - DELTA_EFFECTOR_OFFSET - DELTA_CARRIAGE_OFFSET.

lineardeltakins.L float in

Length of the rod connecting the carriage to the effector. In RepRap delta parlance, L is DELTA_DIAGONAL_ROD.

## NOTES
The R and L values can be adjusted while LinuxCNC is running. However, doing so while in coordinated mode will lead to a step change in joint position, which generally will trigger a following error if in joint mode with machine on.


logic

title: logic(9)

text:
# logic(9)

## NAME
logic - LinuxCNC HAL component providing configurable logic functions

## SYNOPSIS
loadrt logic [count=N|names=name1[,name2...]] personality=0xXXXX[,0xXXXX...]

count The number of logical gates.

names The named logical gates to create.

personality Comma separated list of hexadecimal number.

Each number defines the behaviour of the individual logic gate. The list must have the same number of personalities as the N count.

## DESCRIPTION
General `logic function' component. Can perform `and', `or', `nand', `nor' 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

- 2048 (0x800) if the `nand' output is desired

- 4096 (0x1000) if the `nor' output is desired

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

## FUNCTIONS
logic.N (requires a floating-point thread)

Read the inputs and toggle the output bit.

## 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]

logic.N.nand bit out [if personality & 0x800]

logic.N.nor bit out [if personality & 0x1000]

## EXAMPLES
This is an OR circuit connected to three different signals, two inputs named sig-in-0 and sig-in-1, and one output named sig-out. First the circuit is defined, then its function is connected to the servo real time thread, last, its pins are connected to the wanted signals.

```
loadrt logic count=1 personality=0x202
addf logic.0 servo-thread
net sig-in-0 => logic.0.in-00
net sig-in-1 => logic.0.in-01
net sig-out  <= logic.0.or
```

This is a named AND circuit with two inputs and one output.

```
loadrt logic names=both personality=0x102
addf both servo-thread
net sig-in-0 => both.in-00
net sig-in-1 => both.in-01
net sig-out  <= both.and
```

## SEE ALSO
and2(9), lut5(9), not(9), or2(9), xor2(9)

## AUTHOR
Jeff Epler

## LICENSE
GPL


lowpass

title: lowpass(9)

summary: Low-pass filter

text:
# lowpass(9)

## NAME
lowpass - Low-pass filter

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

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

## PINS
lowpass.N.in float in

lowpass.N.out float out

out += (in - out) * gain

lowpass.N.load bit in

When TRUE, copy in to out instead of applying the filter equation.

## PARAMETERS
lowpass.N.gain float rw

## NOTES
gain pin setting

The digital filter implemented is equivalent to a unity-gain continuous-time single-pole low-pass filter that is preceded by a zero-order-hold and sampled at a fixed period. For a pole at -a (radians/seconds) the corresponding continuous-time lowpass filter LaPlace transfer function is:

H(s) = a/(s + a)

For a sampling period T (seconds), the gain for this Hal lowpass component is:

gain = 1 - e^(-a * T)

e = 2.71828 https://en.wikipedia.org/wiki/E_(mathematical_constant)

Examples:

T = 0.001 seconds (typical servo thread period)

a = (2*pi*100) (100Hz bandwidth single pole)

gain = 0.466

T = 0.001 seconds (typical servo thread period)

a = (2*pi*10) ( 10Hz bandwidth single pole)

gain = 0.0609

T = 0.001 seconds (typical servo thread period)

a = (2*pi*1) ( 1Hz bandwidth single pole)

gain = 0.0063

## AUTHOR
Jeff Epler

## LICENSE
GPL


title: lut5(9)

text:
# lut5(9)

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

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

## DESCRIPTION
lut5 constructs a logic function with up to 5 inputs using a look-up table. The value for function can be determined by writing the truth table, and computing the sum of all the weights for which the output value would be TRUE. The weights are hexadecimal not decimal so hexadecimal math must be used to sum the weights. A wiki page has a calculator to assist in computing the proper value for function.

https://wiki.linuxcnc.org/cgi-bin/wiki.pl?Lut5

Note that LUT5 will generate any of the 4,294,967,296 logical functions of 5 inputs so AND, OR, NAND, NOR, XOR and every other combinatorial function is possible.

### Example Functions
A 5-input and function is TRUE only when all the inputs are true, so the correct value for function is 0x80000000.

A 2-input or function would be the sum of 0x2 + 0x4 + 0x8, so the correct value for function is 0xe.

A 5-input or function is TRUE whenever any of the inputs are true, so the correct value for function is 0xfffffffe. Because every weight except 0x1 is true the function is the sum of every line except the first one.

A 2-input xor function is TRUE whenever exactly one of the inputs is true, so the correct value for function is 0x6. Only in-0 and in-1 should be connected to signals, because if any other bit is TRUE then the output will be FALSE.

Weights for each line of truth table

Bit 4

Bit 3

Bit 2

Bit 1

Bit 0

Weight

0

0

0

0

0

0x1

0

0

0

0

1

0x2

0

0

0

1

0

0x4

0

0

0

1

1

0x8

0

0

1

0

0

0x10

0

0

1

0

1

0x20

0

0

1

1

0

0x40

0

0

1

1

1

0x80

0

1

0

0

0

0x100

0

1

0

0

1

0x200

0

1

0

1

0

0x400

0

1

0

1

1

0x800

0

1

1

0

0

0x1000

0

1

1

0

1

0x2000

0

1

1

1

0

0x4000

0

1

1

1

1

0x8000

1

0

0

0

0

0x10000

1

0

0

0

1

0x20000

1

0

0

1

0

0x40000

1

0

0

1

1

0x80000

1

0

1

0

0

0x100000

1

0

1

0

1

0x200000

1

0

1

1

0

0x400000

1

0

1

1

1

0x800000

1

1

0

0

0

0x1000000

1

1

0

0

1

0x2000000

1

1

0

1

0

0x4000000

1

1

0

1

1

0x8000000

1

1

1

0

0

0x10000000

1

1

1

0

1

0x20000000

1

1

1

1

0

0x40000000

1

1

1

1

1

0x80000000

## FUNCTIONS
lut5.N (requires a floating-point thread)

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

## SEE ALSO
and(9), logic(9), not(9), or2(9), xor2(9).

## AUTHOR
Jeff Epler

## LICENSE
GPL


title: maj3(9)

summary: Compute the majority of 3 inputs

text:
# maj3(9)

## NAME
maj3 - Compute the majority of 3 inputs

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

## FUNCTIONS
maj3.N (requires a floating-point thread)

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

## AUTHOR
Jeff Epler

## LICENSE
GPL


title: match8(9)

summary: 8-bit binary match detector

text:
# match8(9)

## NAME
match8 - 8-bit binary match detector

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

## FUNCTIONS
match8.N (requires a floating-point thread)

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

## AUTHOR
John Kasunich

## LICENSE
GPL


title: matrix_kb(9)

summary: Convert integers to HAL pins.

text:
# matrix_kb(9)

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

## SYNOPSIS
loadrt matrix_kb config=RxCs,RxCs... names=name1,name2...

Creates a component configured for R rows and N columns of matrix keyboard.

If the s option is specified then a set of output rows will be cyclically toggled, and a set of input columns will be scanned.

The names parameter is optional, but if used then the HAL pins and functions will use the specified names rather than the default ones. This can be useful for readability and 2-pass HAL parsing.

There must be no spaces in the parameter lists.

## DESCRIPTION
This component was written to convert matrix keyboard scancodes into HAL pins. However, it might also find uses in converting integers from 0 to N into N HAL pins.

The component can work in two ways, and the HAL pins created vary according to mode.

In the default mode the component expects to be given a scan code from a separate driver but could be any integer from any source. Most typically this will be the keypad scancode from a Mesa 7I73. The default codes for keyup and keydown are based on the Mesa 7I73 specification with 0x40 indicating a keydown and 0x80 a keyup event. If using the 7I73 it is important to match the keypad size jumpers with the HAL component. Valid configs for the 7I73 are 4x8 and 8x8. Note that the component will only work properly with the version 12 (0xC) 7I73 firmware. The firmware version is visible on the component parameters in HAL.

In the optional scan-generation mode the matrix_kb.N.keycode pin changes to an output pin and a set of output row pins and input column pins are created. These need to be connected to physical inputs and outputs to scan the matrix and return values to HAL. Note the negative-logic parameter described below, this will need to be set on the most common forms of inputs which float high when unconnected.

In both modes a set of HAL output pins are created corresponding to each node of the matrix.

## FUNCTIONS
matrix_kb.N

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

## PINS
matrix_kb.N.col-CC-in bit in

The input pin corresponding to column C.

matrix_kb.N.key.rRcC bit out

The pin corresponding to the key at row R column C of the matrix.

matrix_kb.N.keycode unsigned in or out depending on mode.

This pin should be connected to the scancode generator if hardware such as a 7I73 is being used. In this mode it is an input pin. In the internally-generated scanning mode this pin is an output, but will not normally be connected.

matrix_kb.N.row-RR-out bit out

The row scan drive pins. Should be connected to external hardware pins connected to the keypad. The row scan drive pins.Should be connected to external hardware pins connected to the keypad.

## PARAMETERS
matrix_kb.N.key_rollover unsigned r/w (default 2)

With most matrix keyboards the scancodes are only unambiguous with 1 or 2 keys pressed. With more keys pressed phantom keystrokes can appear. Some keyboards are optimised to reduce this problem, and some have internal diodes so that any number of keys may be pressed simultaneously. Increase the value of this parameter if such a keyboard is connected, or if phantom keystrokes are more acceptable than only two keys being active at one time.

matrix_kb.N.negative-logic bit r/w (default 1) only in scan mode

When no keys are pressed a typical digital input will float high. The input will then be pulled low by the keypad when the corresponding poll line is low. Set this parameter to 0 if the IO in use requires one row at a time to be high, and a high input corresponds to a button press.


title: max31855(9)

text:
# max31855(9)

## NAME
max31855 - Support for the MAX31855 Thermocouple-to-Digital converter using bitbanged spi

## SYNOPSIS
loadrt max31855 [count=N|names=name1[,name2...]] [personality=P1,P2,...]

## DESCRIPTION
The component requires at least 3 pins to bitbang spi protocol, for example:

loadrt max31855 personality=1

setp hm2_6i25.0.gpio.023.is_output true setp hm2_6i25.0.gpio.024.is_output true

net spi.clk.in hm2_6i25.0.gpio.023.out max31855.0.clk.out net spi.cs.in hm2_6i25.0.gpio.024.out max31855.0.cs.out net spi.data0.in hm2_6i25.0.gpio.033.in_not max31855.0.data.0.in

addf max31855.0.bitbang-spi servo-thread

The MAX31855 supports a range of -270C to 1800C, however linearization data is only available for the -200C to 1350C range, beyond which raw temperature is returned.

Temperature pins are provided for readings in Celsius, Fahrenheit and Kelvin, temperature values are not updated while a fault condition is present.

The personality parameter is used to indicate the number of sensors. Multiple sensors share the clk and cs pins, but connect to discrete data input pins. A maximum of 15 sensors are supported.

## FUNCTIONS
max31855.N.bitbang-spi (requires a floating-point thread)

## PINS
max31855.N.data.M.in bit in (M=0..( personality & 0xf ))

Pin(s) connected to data out.

max31855.N.cs.out bit out

Pin connected to cs, pulled low to shift data, pulled high for data refresh.

max31855.N.clk.out bit out

Pin connected to clk.

max31855.N.temp-celsius.M float out (M=0..( personality & 0xf ))

Temperature output values in Celsius.

max31855.N.temp-fahrenheit.M float out (M=0..( personality & 0xf ))

Temperature in Fahrenheit.

max31855.N.temp-kelvin.M float out (M=0..( personality & 0xf ))

Temperature in Kelvin.

max31855.N.fault.M bit out (M=0..( personality & 0xf ))

Fault condition detected.

max31855.N.fault-flags.M u32 out (M=0..( personality & 0xf ))

Fault flags: 0x1 = open sensor, 0x2 short to gnd, 0x3 short to vcc.

## AUTHOR
Joseph Calderon

## LICENSE
GPL


maxkins

title: maxkins(9)

text:
# maxkins(9)

See the file man9/kins.9.


title: mesa_7i65(9)

text:
# mesa_7i65(9)

## NAME
mesa_7i65 - Support for the Mesa 7i65 Octuple Servo Card

## SYNOPSIS
loadrt mesa_7i65

## DESCRIPTION
The component takes parameters in the form of a comma-separated list of bspi (buffered SPI) instance names, for example:

loadrt mesa_7i65 bspi_chans=hm2_5i23.0.bspi.0, hm2_5i23.0.bspi.1

The BSPI instances are printed to the dmesg buffer during the Hostmot2 setup sequence, one for each bspi instance included in the bitfile loaded to each installed card during the Hostmot2 setup sequence. Type "dmesg" at the terminal prompt to view the output.

## PINS
mesa-7i65.N.analogue.M.out float in (M=0..7)

Analogue output values. The value will be limited to a -1.0 to +1.0 range

mesa-7i65.N.analogue.M.in float out (M=0..7)

Analogue outputs read by the 7i65 (in Volts)

mesa-7i65.N.digital.M.in bit out (M=0..3)

Miscellaneous Digital Inputs

mesa-7i65.N.enable.M.out bit in (M=0..7)

Amplifier-enable control pins

mesa-7i65.N.watchdog.has-bit bit out

Indicates the status of the 7i65 Watchdog (which is separate from the FPGA card watchdog

## PARAMETERS
mesa-7i65.N.scale-M float rw (M=0..7) (default: 10)

Analogue output scale factor. For example if the scale is 7 then an input of 1.0 will give 7V on the output terminals

mesa-7i65.N.is-bipolar-M bit rw (M=0..7) (default: 1)

Set this value to TRUE for a plus/minus "scale" output. Set to 0 for a 0-"scale" output

## AUTHOR
Andy Pugh / Cliff Blackburn

## LICENSE
GPL


title: mesa_pktgyro_test(9)

text:
# mesa_pktgyro_test(9)

## NAME
mesa_pktgyro_test - PktUART simple test with Microstrain 3DM-GX3-15 gyro

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

## DESCRIPTION
This component is written in order to test the PktUART driver for Mesa. It resembles partly Andy Pugh's mesa_uart.comp .

This module uses the names= mode of loadrt declaration to specify which PktUART instances to enable. A check is included to ensure that the count= option is not used instead. For simplicity we test only one PktUART instance, therefore load the component like this:

loadrt mesa_uart names=hm2_5i25.0.pktuart.0

The PktUART instance names are printed to the dmesg buffer during the Hostmot2 setup sequence, one for each PktUART instance included in the bitfile loaded to each installed card during the Hostmot2 setup sequence. Type "dmesg" at the terminal prompt to view the output. If you want to work with more than one PktUART instance, consult Andy Pugh's mesa_uart.comp

In order to compile and install do: halcompile --install src/hal/drivers/mesa_pktgyro_test.comp

The component exports only one function, namely receive, which needs to be added to a realtime thread. To test this component set DEBUG=5 before and execute this HAL script: loadrt hostmot2 loadrt hm2_pci loadrt mesa_pktgyro_test names=hm2_5i25.0.pktuart.0 loadrt threads name1=test1 period1=10000000 addf hm2_5i25.0.pktuart.0.receive test1 start

Check linuxcnc.log for debug output.

## FUNCTIONS
mesa-pktgyro-test.N.receive (requires a floating-point thread)

## PINS
mesa-pktgyro-test.N.rxbytes s32 out

Number of Bytes received or negative Error code

## AUTHOR
Boris Skegin

## LICENSE
GPL


title: mesa_uart(9)

text:
# mesa_uart(9)

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

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

## DESCRIPTION
This component creates 16 input and 16 output pins. It transmits {name}.N.tx-bytes on the selected UART every thread cycle and reads up to 16 bytes each cycle out of the receive FIFO and writes the values to the associated output pins. {name}.rx-bytes indicates how many pins have been written to. (pins > rx-bytes simply hold their previous value)

This module uses the names= mode of loadrt declaration to specify which UART instances to enable. A check is included to ensure that the count= option is not used instead.

The component takes parameters in the form of a comma-separated list of UART instance names, for example:

loadrt mesa_uart names=hm2_5i23.0.uart.0,hm2_5i23.0.uart.7

Note that no spaces are allowed in the string unless it is delimited by double quotes.

The UART instance names are printed to the dmesg buffer during the Hostmot2 setup sequence, one for each UART instance included in the bitfile loaded to each installed card during the Hostmot2 setup sequence. Type "dmesg" at the terminal prompt to view the output.

The component exports two functions, send and receive, which need to be added to a realtime thread.

The above example will output data on UART channels 0 and 7 and the pins will have the names of the individual UARTS. (they need not be on the same card, or even the same bus).

Read the documents on "halcompile" for help with writing realtime components: http://linuxcnc.org/docs/html/hal/comp.html

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

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

## PINS
mesa-uart.N.tx-data-MM u32 in (MM=00..15)

Data to be transmitted

mesa-uart.N.rx-data-MM u32 out (MM=00..15)

Data received

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


message

title: message(9)

summary: Display a message

text:
# message(9)

## NAME
message - Display a message

## SYNOPSIS
loadrt message [count=N|names=name1[,name2...]] [messages=N]

messages

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

## DESCRIPTION
Allows HAL pins to trigger a message. Example hal commands:

loadrt message names=oillow,oilpressure,inverterfail messages="Slideway oil low,No oil pressure,Spindle inverter fault"

addf oillow servo-thread

addf oilpressure servo-thread

addf inverterfail servo-thread

setp oillow.edge 0 #this pin should be active low

net no-oil classicladder.0.out-21 oillow.trigger

net no-pressure classicladder.0.out-22 oilpressure.trigger

net no-inverter classicladder.0.out-23 inverterfail.trigger

When any pin goes active, the corresponding message will be displayed.

## FUNCTIONS
message.N (requires a floating-point thread)

Display a message

## PINS
message.N.trigger bit in (default: FALSE)

signal that triggers the message

message.N.force bit in (default: FALSE)

A FALSE->TRUE transition forces the message to be displayed again if the trigger is active

## PARAMETERS
message.N.edge bit rw (default: TRUE)

Selects the desired edge: FALSE means falling, TRUE means rising

## AUTHOR
Les Newell

## LICENSE
GPL v2


millturn

title: millturn(9)

text:
# millturn(9)

## NAME
millturn - Switchable kinematics for a mill-turn machine

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

## DESCRIPTION
This is a switchable kinematics module using 3 cartesian linear joints (XYZ) and 1 angular joint (A). The module contains two kinematic models:

type0 (default) is a mill (XYZA) configuration with A being a rotary axis.

type1 is a turn (Z-YX) configuration with A configured to be a spindle.

For an example configuration, run the sim config: 'configs/sim/axis/vismach/millturn/millturn.ini'.

Further explanations can be found in the README in 'configs/sim/axis/vismach/millturn'.

millturn.comp was constructed by modifying the template file: userkins.comp.

For more information on how to modify userkins.comp run: $ man userkins. Also, see additional information inside: 'userkins.comp'.

For information on kinematics in general see the kinematics document chapter (docs/src/motion/kinematics.txt) and for switchable kinematics in particular see the switchkins document chapter (docs/src/motion/switchkins.txt)

## FUNCTIONS
millturn.N.fdemo (requires a floating-point thread)

## PINS
millturn.N.fpin s32 out (default: 0)

pin to demonstrate use of a conventional (non-kinematics) function fdemo

## AUTHOR
David Mueller

## LICENSE
GPL


minmax

title: minmax(9)

text:
# minmax(9)

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

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

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

## PINS
minmax.N.in float in

minmax.N.reset bit in

When reset is asserted, 'in' is copied to the outputs

minmax.N.max float out

minmax.N.min float out

## AUTHOR
Jeff Epler

## LICENSE
GPL


motion

title: motion(9)

text:
# motion(9)

## NAME
motion - accepts NML motion commands, interacts with HAL in realtime

## SYNOPSIS
loadrt motmod [base_period_nsec=period] [base_thread_fp=0 or 1] [servo_period_nsec=period] [traj_period_nsec=period] [num_joints=[1-16]] [num_dio=[1-64]] [num_aio=[1-64]] [num_misc_error=[0-64] | names_misc_errors] [num_spindles=[1-8]] [unlock_joints_mask=jointmask] [num_extrajoints=[0-16]]

The limits for the following items are compile-time settings:

num_joints: Maximum number of joints is set by EMCMOT_MAX_JOINTS.

num_dio: Maximum number of digital inputs is set by EMCMOT_MAX_DIO.

num_aio: Maximum number of analog inputs is set by EMCMOT_MAX_AIO.

num_misc_error: Maximum number of extra error inputs is set by EMCMOT_MAX_MISC_ERRORS.

names_misc_errors: A comma-separated list of names for extra error inputs.

This parameter is mutually exclusive with num_misc_error. If using num_misc_error the additional error input pins will have names like motion.misc-error-00 whereas names_misc_errors=overtemp,undertemp will create hal pins motion.err-overtemp and motion.err-undertemp

num_spindles: Maximum number of spindles is set by EMCMOT_MAX_SPINDLES

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 "joint" or "axis" are are read and updated by the motion-controller function.

## DESCRIPTION
base_thread_fp is deprecated and has no effect. All threads now unconditionally save and restore floating-point state.

These pins and parameters are created by the realtime motmod module. This module provides a HAL interface for LinuxCNC's motion planner. Basically motmod takes in a list of waypoints and generates a nice blended and constraint-limited stream of joint positions to be fed to the motor drives.

The optional num_extrajoints parameter specifies a quantity of joints that participate in homing but are not used by kinematics transformations. After homing, control of an 'extra' joint is transferred to a posthome command HAL pin (joint.N.posthome-cmd) and the motor feedback value is ignored. 'Extra' joints must be managed by independent motion planners/controllers (typically using limit3 HAL components). Extra joints maybe unhomed only when motion is disabled.

The maximum num_extrajoints value is equal to the num_joints value. (Note that using the maximum value would allow no operation in world coordinates). The num_joints value must be equal to the sum of the number of joints used for kinematics calculations plus the number of 'extra' joints.

The num_joints parameter is conventionally set using the INI file setting [KINS]JOINTS=value. The num_extrajoints is set by the additional motmod parameter [EMCMOT]motmod num_extrajoints=value. Hal pin numbering for all joints is zero based [0 ... num_joints-1]. When specified, 'extra' joints are assigned the last num_extrajoints in the numbering sequence. For example, specifying [KINS]JOINTS=5 and [EMCMOT]motmod num_extrajoints=2 for a 3 joint trivkins configuration [KINS] KINEMATICS=trivkins coordinates=xyz uses joints 0,1,2 for the kinematic joints and joints 3,4 for the 'extra' joints.

## MOTION PINS
motion-command-handler.time OUT S32

Time (in CPU clocks) for the motion module motion-command-handler

motion-controller.time OUT S32

Time (in CPU clocks) for the motion module motion-controller

motion.adaptive-feed IN FLOAT

When adaptive feed is enabled with M52 P1, the commanded velocity is multiplied by this value. This effect is multiplicative with the NML-level feed override value and motion.feed-hold. Negative values are valid and will run the G-code path in reverse.

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"

motion.current-vel OUT FLOAT

Current cartesian velocity

motion.digital-in-NN IN BIT

These pins are used by M66 Pnn wait-for-input mode.

motion.digital-out-NN OUT BIT

These pins are controlled by the M62 through M65 words.

motion.distance-to-go OUT FLOAT

Distance remaining in the current move

motion.enable IN BIT

If this bit is driven FALSE, motion stops, the machine is placed in the "machine off" state, and a message is displayed for the operator. For normal motion, drive this bit TRUE.

motion.eoffset-active OUT BIT

Indicates external offsets are active (non-zero)

motion.eoffset-limited OUT BIT

Indicates motion with external offsets was limited by a soft limit constraint ([AXIS_L]MIN_LIMIT,MAX_LIMIT).

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. Note: feed-hold applies to G-code commands -- not jogs.

motion.feed-inhibit IN BIT

When this pin is TRUE, machine motion is inhibited for G-code commands. If the machine is performing a spindle synchronized move when this pin goes TRUE, the spindle synchronized motion will finish, and any following moves will be inhibited (this is to prevent damage to the machine, the tool, or the work piece).

If the machine is in the middle of a (non-spindle synchronized) move when this pin goes TRUE, the machine will decelerate to a stop at the maximum allowed acceleration rate.

Motion resumes when this pin goes FALSE.

Note: feed-inhibit applies to G-code commands -- not jogs.

motion.feed-upm OUT FLOAT

Current feed rate in G-code program units per minute for motion.motion-type feed(2) and arc(3). Value is the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). Value is zero if motion.feed-hold or motion.feed-inhibit are asserted. If units (G20 or G21) are not specified in the G-code file then units will be the last units used.

motion.feed-inches-per-minute OUT FLOAT

Current feed rate in inches per minute for motion.motion-type feed(2) and arc(3). Value is the inch equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). Value is zero if motion.feed-hold or motion.feed-inhibit are asserted.

motion.feed-inches-per-second OUT FLOAT

Current feed rate in inches per second for motion.motion-type feed(2) and arc(3). Value is the inch equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). Value is zero if motion.feed-hold or motion.feed-inhibit are asserted.

motion.feed-mm-per-minute OUT FLOAT

Current feed rate in mm per minute for motion.motion-type feed(2) and arc(3). Value is the mm equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). Value is zero if motion.feed-hold or motion.feed-inhibit are asserted.

motion.feed-mm-per-second OUT FLOAT

Current feed rate in mm per second for motion.motion-type feed(2) and arc(3). Value is the mm equivalent of the G-code program F value multiplied by the current feed override value and the motion.adaptive-feed setting (if M52 active). Value is zero if motion.feed-hold or motion.feed-inhibit are asserted.

motion.homing-inhibit IN BIT

If this bit is TRUE, initiation of any joint homing move (including "Home All") is disallowed and an error is reported. By default, homing is allowed in joint mode whenever motion is enabled.

motion.is-all-homed OUT BIT

TRUE if all active joints is homed.

motion.jog-inhibit IN BIT

If this bit is TRUE, jogging of any joint or axis is disallowed and an error is reported.

motion.jog-stop IN BIT

If any jog is active when the pin state changes to TRUE then that jog will be stopped following the associated acceleration values.

motion.jog-stop-immediate IN BIT

If any jog is active when the pin state changes to TRUE then that jog will be stopped immediately.

motion.jog-is-active OUT BIT

TRUE if any joint or axis is jogging.

motion.in-position OUT BIT

TRUE if the machine is in position (ie, not currently moving towards the commanded position).

motion.misc-error-NN IN BIT

Extra error inputs for faults such as over-temperature sensors, low coolant warnings, custom HAL component errors. If driven TRUE this will disable a machine. Similar to spindle.amp-fault-in.

motion.motion-enabled OUT BIT

motion.motion-type OUT S32

These values are from src/emc/nml_intf/motion_types.h.

0: Idle (no motion)

1: Traverse

2: Linear feed

3: Arc feed

4: Tool change

5: Probing

6: Rotary unlock for traverse

motion.on-soft-limit OUT BIT

motion.probe-input IN BIT

G38.n 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

The current program line while executing. Zero if not running or between lines while single stepping.

motion.requested-vel OUT FLOAT

The current requested velocity in user units per second. This value is the F-word setting from the G-code file, possibly reduced to accommodate machine velocity and acceleration limits. The value on this pin does not reflect the feed override or any other adjustments.

motion.servo.last-period OUT U32

The number of CPU clocks between invocations of the servo thread. Typically, this number divided by the CPU speed gives the time in seconds, and can be used to determine whether the realtime motion controller is meeting its timing constraints

motion.switchkins-type IN float

Kinematics modules that define the functions kinematicsSwitchable() and kinematicsSwitch() receive the integer value of this pin to select the machine kinematics functions. Extra G-code commands may be required to synchronize task and motion before and after changes to the pin value.

motion.teleop-mode OUT BIT

Motion mode is teleop (axis coordinate jogging available).

motion.tooloffset.L OUT FLOAT

Current tool offset for each axis where (L is the axis letter, one of: x y z a b c u v w)

motion.tp-reverse OUT BIT

Trajectory planning is reversed (reverse run)

## AXIS PINS
(L is the axis letter, one of: x y z a b c u v w)

axis.L.eoffset OUT FLOAT

Current external offset.

axis.L.eoffset-clear IN BIT

Clear external offset request

axis.L.eoffset-counts IN S32

Counts input for external offset. The eoffset-counts are transferred to an internal register. The applied external offset is the product of the register counts and the eoffset-scale value. The register is reset to zero at each machine startup. If the machine is turned off with an external offset active, the eoffset-counts pin should be set to zero before restarting.

axis.L.eoffset-enable IN BIT

Enable for external offset (also requires INI file setting for [AXIS_L]OFFSET_AV_RATIO)

axis.L.eoffset-request OUT FLOAT

Debug pin for requested external offset.

axis.L.eoffset-scale IN FLOAT

Scale for external offset.

axis.L.jog-accel-fraction IN FLOAT

Sets acceleration for wheel jogging to a fraction of the INI max_acceleration for the axis. Values greater than 1 or less than zero are ignored.

axis.L.jog-counts IN S32

Connect to the "counts" pin of an external encoder to use a physical jog wheel.

axis.L.jog-enable IN BIT

When TRUE (and in manual mode), any change to "jog-counts" will result in motion. When false, "jog-counts" is ignored.

axis.L.jog-scale IN FLOAT

Sets the distance moved for each count on "jog-counts", in machine units.

axis.L.jog-vel-mode IN BIT

When FALSE (the default), the jogwheel operates in position mode. The axis will move exactly jog-scale units for each count, regardless of how long that might take. When TRUE, the wheel operates in velocity mode - motion stops when the wheel stops, even if that means the commanded motion is not completed.

axis.L.kb-jog-active OUT BIT

(free planner axis jogging active (keyboard or halui))

axis.L.pos-cmd OUT FLOAT

The axis commanded position. There may be several offsets between the axis and motor coordinates: backlash compensation, screw error compensation, and home offsets. External offsets are reported separately (axis.L.eoffset).

axis.L.teleop-pos-cmd OUT FLOAT

axis.L.teleop-tp-enable OUT BIT

TRUE when the "teleop planner" is enabled for this axis.

axis.L.teleop-vel-cmd OUT FLOAT

The axis's commanded velocity.

axis.L.teleop-vel-lim OUT FLOAT

The velocity limit for the teleop planner.

axis.L.wheel-jog-active OUT BIT

## JOINT PINS
N is the joint number (0 ... num_joints-1))

(Note: pins marked (DEBUG) serve as debugging aids and are subject to change or removal at any time.)

joint.N.acc-cmd OUT FLOAT (DEBUG)

The joint's commanded acceleration.

joint.N.active OUT BIT (DEBUG)

TRUE when this joint is active.

joint.N.amp-enable-out OUT BIT

TRUE if the amplifier for this joint should be enabled.

joint.N.amp-fault-in IN BIT

Should be driven TRUE if an external fault is detected with the amplifier for this joint.

joint.N.backlash-corr OUT FLOAT (DEBUG)

Backlash or screw compensation raw value.

joint.N.backlash-filt OUT FLOAT (DEBUG)

Backlash or screw compensation filtered value (respecting motion limits).

joint.N.backlash-vel OUT FLOAT (DEBUG)

Backlash or screw compensation velocity.

joint.N.coarse-pos-cmd OUT FLOAT (DEBUG)

joint.N.error OUT BIT (DEBUG)

TRUE when this joint has encountered an error, such as a limit switch closing.

joint.N.f-error OUT FLOAT (DEBUG)

The actual following error.

joint.N.f-error-lim OUT FLOAT (DEBUG)

The following error limit.

joint.N.f-errored OUT BIT (DEBUG)

TRUE when this joint has exceeded the following error limit.

joint.N.faulted OUT BIT (DEBUG)

joint.N.free-pos-cmd OUT FLOAT (DEBUG)

The "free planner" commanded position for this joint.

joint.N.free-tp-enable OUT BIT (DEBUG)

TRUE when the "free planner" is enabled for this joint.

joint.N.free-vel-lim OUT FLOAT (DEBUG)

The velocity limit for the free planner.

joint.N.home-state OUT S32 (DEBUG)

homing state machine state

joint.N.home-sw-in IN BIT

Should be driven TRUE if the home switch for this joint is closed.

joint.N.homed OUT BIT (DEBUG)

TRUE if the joint has been homed.

joint.N.homing OUT BIT

TRUE if the joint is currently homing.

joint.N.in-position OUT BIT (DEBUG)

TRUE if the joint is using the "free planner" and has come to a stop.

joint.N.index-enable IO BIT

Should be attached to the index-enable pin of the joint's encoder to enable homing to index pulse.

joint.N.is-unlocked IN BIT

Indicates joint is unlocked (see JOINT UNLOCK PINS).

joint.N.jog-accel-fraction IN FLOAT

Sets acceleration for wheel jogging to a fraction of the INI max_acceleration for the joint. Values greater than 1 or less than zero are ignored.

joint.N.jog-counts IN S32

Connect to the "counts" pin of an external encoder to use a physical jog wheel.

joint.N.jog-enable IN BIT

When TRUE (and in manual mode), any change to "jog-counts" will result in motion. When false, "jog-counts" is ignored.

joint.N.jog-scale IN FLOAT

Sets the distance moved for each count on "jog-counts", in machine units.

joint.N.jog-vel-mode IN BIT

When FALSE (the default), the jogwheel operates in position mode. The joint will move exactly jog-scale units for each count, regardless of how long that might take. When TRUE, the wheel operates in velocity mode - motion stops when the wheel stops, even if that means the commanded motion is not completed.

joint.N.kb-jog-active OUT BIT (DEBUG)

(free planner joint jogging active (keyboard or halui))

joint.N.motor-offset OUT FLOAT (DEBUG)

joint motor offset established when joint is homed.

joint.N.motor-pos-cmd OUT FLOAT

The commanded position for this joint.

joint.N.motor-pos-fb IN FLOAT

The actual position for this joint.

joint.N.neg-hard-limit OUT BIT (DEBUG)

The negative hard limit for the joint

joint.N.neg-lim-sw-in IN BIT

Should be driven TRUE if the negative limit switch for this joint is tripped.

joint.N.pos-cmd OUT FLOAT

The joint (as opposed to motor) commanded position. There may be several offsets between the joint and motor coordinates: backlash compensation, screw error compensation, and home offsets.

joint.N.pos-fb OUT FLOAT

The joint feedback position. This value is computed from the actual motor position minus joint offsets. Useful for machine visualization.

joint.N.pos-hard-limit OUT BIT (DEBUG)

The positive hard limit for the joint.

joint.N.pos-lim-sw-in IN BIT

Should be driven TRUE if the positive limit switch for this joint is tripped.

joint.N.unlock OUT BIT

TRUE if the axis is a locked joint (typically a rotary) and a move is commanded (see JOINT UNLOCK PINS).

joint.N.vel-cmd OUT FLOAT (DEBUG)

The joint's commanded velocity.

joint.N.wheel-jog-active OUT BIT (DEBUG)

## JOINT posthome pins
Each joint designated as an 'extra' joint is provided with a HAL pin joint.N.posthome-cmd. The pin value is ignored prior to homing. After homing, the pin value is augmented by the motor offset value and routed to the joint.N.motor-pos-cmd.

## JOINT unlock pins
The joint pins used for unlocking a joint (joint.N.unlock, joint.N.is-unlocked), are created according to the unlock_joints_mask=jointmask parameter for motmod. These pins may be required for locking indexers (typically a rotary joint)

The jointmask bits are: (lsb)0:joint0, 1:joint1, 2:joint2, ...

Example: loadrt motmod ... unlock_joints_mask=0x38 creates unlock pins for joints 3,4,5

## SPINDLE PINS
(M is the spindle number (0 ... num_spindles-1))

spindle.M.amp-fault-in IN BIT

Should be driven TRUE if an external fault is detected with the amplifier for this spindle.

spindle.M.at-speed IN BIT

Motion will pause until this pin is TRUE, under the following conditions: before the first feed move after each spindle start or speed change; before the start of every chain of spindle-synchronized moves; and if in CSS mode, at every rapid->feed transition.

spindle.M.brake OUT BIT

TRUE when the spindle brake should be applied.

spindle.M.forward OUT BIT

TRUE when the spindle should rotate forward.

spindle.M.index-enable I/O BIT

For correct operation of spindle synchronized moves, this signal must be hooked to the index-enable pin of the spindle encoder.

spindle.M.inhibit IN BIT

When TRUE, the spindle speed is set and held to 0.

spindle.M.is-oriented IN BIT

Acknowledge pin for spindle-orient. Completes orient cycle. If spindle-orient was true when spindle-is-oriented was asserted, the spindle-orient pin is cleared and the spindle-locked pin is asserted. Also, the spindle-brake pin is asserted.

spindle.M.locked OUT BIT

Spindle orient complete pin. Cleared by any of M3,M4,M5.

spindle.M.on OUT BIT

TRUE when spindle should rotate.

spindle.M.orient OUT BIT

Indicates start of spindle orient cycle. Set by M19. Cleared by any of M3,M4,M5. If spindle-orient-fault is not zero during spindle-orient true, the M19 command fails with an error message.

spindle.M.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.

spindle.M.orient-fault IN S32

Fault code input for orient cycle. Any value other than zero will cause the orient cycle to abort.

spindle.M.orient-mode OUT BIT

Desired spindle rotation mode. Reflects M19 P parameter word.

spindle.M.reverse OUT BIT

TRUE when the spindle should rotate backward.

spindle.M.revs IN FLOAT

For correct operation of spindle synchronized moves, this signal must be hooked to the position pin of the spindle encoder.

spindle.M.speed-cmd-rps FLOAT OUT

Commanded spindle speed in units of revolutions per second.

spindle.M.speed-in IN FLOAT

Actual spindle speed feedback in revolutions per second; used for G96 (constant surface speed) and G95 (feed per revolution) modes.

spindle.M.speed-out OUT FLOAT

Desired spindle speed in rotations per minute.

spindle.M.speed-out-abs OUT FLOAT

Desired spindle speed in rotations per minute, always positive regardless of spindle direction.

spindle.M.speed-out-rps OUT FLOAT

Desired spindle speed in rotations per second.

spindle.M.speed-out-rps-abs OUT FLOAT

Desired spindle speed in rotations per second, always positive regardless of spindle direction.

## MOTION PARAMETERS
Many of the parameters serve as debugging aids, and are subject to change or removal at any time.

motion-command-handler.tmax RW S32

Show information about the execution time of these HAL functions in CPU clocks.

motion-command-handler.tmax-increased RO S32

motion-controller.tmax RW S32

Show information about the execution time of these HAL functions in CPU clocks.

motion-controller.tmax-increased RO BIT

motion.debug-*

These values are used for debugging purposes.

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

motion-command-handler

Receive and process incoming motion commands. The pin named motion-command-handler.time and parameters motion-command-handler.tmax,tmax-increasedare created for this function.

motion-controller

Runs the LinuxCNC motion controller. The pin named motion-controller.time and parameters motion-controller.tmax,tmax-increased are created for this function.

## BUGS
This manual page is incomplete.

Identification of pins categorized with (DEBUG) is dubious.

## SEE ALSO
iocontrol(1), milltask(1), spindle(9)


moveoff

title: moveoff(9)

summary: Component for HAL-only offsets

text:
# moveoff(9)

## NAME
moveoff - Component for HAL-only offsets

## SYNOPSIS
loadrt moveoff [count=N|names=name1[,name2...]] [personality=P1,P2,...]

## DESCRIPTION
The moveoff component is used to offset joint positions using custom HAL connections. Implementing an offset-while-program-is-paused functionality is supported with appropriate connections for the input pins. Nine joints are supported.

The axis offset pin values (offset-in-M) are continuously applied (respecting limits on value, velocity, and acceleration) to the output pins (offset-current-M, pos-plusoffset-M, fb-minusoffset-M) when both enabling input pins (apply-offsets and move-enable) are TRUE. The two enabling inputs are anded internally. A warning pin is set and a message issued if the apply-offsets pin is deasserted while offsets are applied. The warning pin remains TRUE until the offsets are removed or the apply-offsets pin is set.

Typically, the move-enable pin is connected to external controls and the apply-offsets pin is connected to halui.program.is-paused (for offsets only while paused) or set to TRUE (for continuously applied offsets).

Applied offsets are automatically returned to zero (respecting limits) when either of the enabling inputs is deactivated. The zero value tolerance is specified by the epsilon input pin value.

Waypoints are recorded when the moveoff component is enabled. Waypoints are managed with the waypoint-sample-secs and waypoint-threshold pins. When the backtrack-enable pin is TRUE, the auto-return path follows the recorded waypoints. When the memory available for waypoints is exhausted, offsets are frozen and the waypoint-limit pin is asserted. This restriction applies regardless of the state of the backtrack-enable pin. An enabling pin must be deasserted to allow a return to the original (non-offset position).

Backtracking through waypoints results in slower movement rates as the moves are point-to-point respecting velocity and acceleration settings. The velocity and acceleration limit pins can be managed dynamically to control offsets at all times.

When backtrack-enable is FALSE, the auto-return move is NOT coordinated, each axis returns to zero at its own rate. If a controlled path is wanted in this condition, each axis should be manually returned to zero before deasserting an enabling pin.

The waypoint-sample-secs, waypoint-threshold, and epsilon pins are evaluated only when the component is idle.

The offsets-applied output pin is provided to indicate the current state to a GUI so that program resumption can be managed. If the offset(s) are non-zero when the apply-offsets pin is deasserted (for example when resuming a program when offsetting during a pause), offsets are returned to zero (respecting limits) and an Error message is issued.

Caution: If offsets are enabled and applied and the machine is turned off for any reason, any external HAL logic that manages the enabling pins and the offset-in-M inputs is responsible for their state when the machine is subsequently turned on again.

This HAL-only means of offsetting is typically not known to LinuxCNC nor available in GUI preview displays. No protection is provided for offset moves that exceed soft limits managed by LinuxCNC. Since soft limits are not honored, an offset move may encounter hard limits (or CRASH if there are no limit switches). Use of the offset-min-M and offset-max-M inputs to limit travel is recommended. Triggering a hard limit will turn off the machine -- see Caution above.

The offset-in-M values may be set with inifile settings, controlled by a GUI, or managed by other HAL components and connections. Fixed values may be appropriate in simple cases where the direction and amount of offset is well-defined but a control method is required to deactivate an enabling pin in order to return offsets to zero. GUIs may provide means for users to set, increment, decrement, and accumulate offset values for each axis and may set offset-in-M values to zero before deasserting an enabling pin.

The default values for accel, vel, min, max, epsilon, waypoint-sample-secs, and waypoint-threshold may not be suitable for any particular application. This HAL component is unaware of limits enforced elsewhere by LinuxCNC. Users should test usage in a simulator application and understand all hazards before use on hardware.

The module personality item sets the number of joints supported (default==3, maximum is 9).

Use of the names= option for naming is required for compatibility with the gui provided as scripts/moveoff_gui:

loadrt moveoff names=mv personality=number_of_joints

## FUNCTIONS
moveoff.N.read-inputs (requires a floating-point thread)

Read all inputs

moveoff.N.write-outputs (requires a floating-point thread)

Write computed offset outputs (offset-current-M, pos-plusoffset-M, fb-minusoffset-M). All other outputs are updated by read-inputs().

## PINS
moveoff.N.power-on bit in

Connect to motion.motion-enabled

moveoff.N.move-enable bit in

Enable offsets (Enabling requires apply-offset TRUE also)

moveoff.N.apply-offsets bit in

Enable offsets (Enabling requires move-enable TRUE also)

moveoff.N.backtrack-enable bit in (default: 1)

Enable backtrack on auto-return

moveoff.N.epsilon float in (default: 0.0005)

When enabling pins are deactivated, return to un-offsetted position within epsilon units. Warning: values that are too small in value may cause overshoot. A minimum value of 0.0001 is silently enforced.

moveoff.N.waypoint-threshold float in (default: 0.02)

Minimum distance (in a single axis) for a new waypoint

moveoff.N.waypoint-sample-secs float in (default: 0.02)

Minimum sample interval (in seconds) for a new waypoint

moveoff.N.warning bit out

Set TRUE if apply-offsets is deasserted while offset-applied is TRUE.

moveoff.N.offset-applied bit out

TRUE if one or more offsets are applied.

moveoff.N.waypoint-limit bit out (default: 0)

Indicates waypoint limit reached (motion ceases), an enabling pin must be deasserted to initiate return to original position.

moveoff.N.waypoint-ct s32 out

Waypoint count (for debugging)

moveoff.N.waypoint-percent-used s32 out

Percent of available waypoints used

moveoff.N.offset-in-M float in (M=0..personality)

Joint offset input value

moveoff.N.pos-M float in (M=0..personality)

Joint position (typ: axis.0.motor-pos-cmd)

moveoff.N.fb-M float in (M=0..personality)

Joint feedback (typ from encoder and input to pid controller (pid.feedback))

moveoff.N.offset-current-M float out (M=0..personality)

Joint offset current value

moveoff.N.pos-plusoffset-M float out (M=0..personality)

Computed joint position plus offset (typically connect to pid command input)

moveoff.N.fb-minusoffset-M float out (M=0..personality)

Computed Joint feedback minus offset (typically connected to axis.0.motor-pos-fb)

moveoff.N.offset-vel-M float in (M=0..personality) (default: 10)

Joint offset velocity limit

moveoff.N.offset-accel-M float in (M=0..personality) (default: 100)

Joint offset acceleration limit

moveoff.N.offset-min-M float in (M=0..personality) (default: -1e20)

Minimum limit for applied joint offset (typ negative)

moveoff.N.offset-max-M float in (M=0..personality) (default: 1e20)

Maximum limit for applied offset (typ positive)

moveoff.N.dbg-waypoint-limit-test bit in

Debug input to test with limited number of waypoints

moveoff.N.dbg-state s32 out

Debug output for current state of state machine

## EXAMPLES
Example simulator configs that demonstrate the moveoff component and a simple gui (scripts/moveoff_gui) are located in configs/sim/axis/moveoff. The AXIS GUI is used for the demonstrations and the configs can be adapted for other GUIs like Touchy and Gscreen. An example with the Touchy GUI is provided in configs/sim/touchy/ngcgui/.

## SEE ALSO
moveoff_gui(1)

## AUTHOR
Dewey Garrett and Andy Pugh

## LICENSE
GPL


title: mult2(9)

summary: Product of two inputs

text:
# mult2(9)

## NAME
mult2 - Product of two inputs

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

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

## PINS
mult2.N.in0 float in

mult2.N.in1 float in

mult2.N.out float out

out = in0 * in1

## SEE ALSO

invert(9), div2(9)

## AUTHOR
John Kasunich

## LICENSE
GPL


multiclick

title: multiclick(9)

text:
# multiclick(9)

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

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

## DESCRIPTION
A click is defined as a rising edge on the 'in' pin, followed by the 'in' pin being True for at most 'max-hold-ns' nanoseconds, followed by a falling edge.

A double-click is defined as two clicks, separated by at most 'max-space-ns' nanoseconds with the 'in' pin in the False state.

I bet you can guess the definition of triple- and quadruple-click.

You probably want to run the input signal through a debounce component before feeding it to the multiclick detector, if the input is at all noisy.

The '*-click' pins go high as soon as the input detects the correct number of clicks.

The '*-click-only' pins go high a short while after the click, after the click separator space timeout has expired to show that no further click is coming. This is useful for triggering halui MDI commands.

## FUNCTIONS
multiclick.N (requires a floating-point thread)

Detect single-, double-, triple-, and quadruple-clicks

## PINS
multiclick.N.in bit in

The input line, this is where we look for clicks.

multiclick.N.single-click bit out

Goes high briefly when a single-click is detected on the 'in' pin.

multiclick.N.single-click-only bit out

Goes high briefly when a single-click is detected on the 'in' pin and no second click followed it.

multiclick.N.double-click bit out

Goes high briefly when a double-click is detected on the 'in' pin.

multiclick.N.double-click-only bit out

Goes high briefly when a double-click is detected on the 'in' pin and no third click followed it.

multiclick.N.triple-click bit out

Goes high briefly when a triple-click is detected on the 'in' pin.

multiclick.N.triple-click-only bit out

Goes high briefly when a triple-click is detected on the 'in' pin and no fourth click followed it.

multiclick.N.quadruple-click bit out

Goes high briefly when a quadruple-click is detected on the 'in' pin.

multiclick.N.quadruple-click-only bit out

Goes high briefly when a quadruple-click is detected on the 'in' pin and no fifth click followed it.

multiclick.N.state s32 out

## PARAMETERS
multiclick.N.invert-input bit rw (default: FALSE)

If FALSE (the default), clicks start with rising edges. If TRUE, clicks start with falling edges.

multiclick.N.max-hold-ns u32 rw (default: 250000000)

If the input is held down longer than this, it's not part of a multi-click. (Default 250,000,000 ns, 250 ms.)

multiclick.N.max-space-ns u32 rw (default: 250000000)

If the input is released longer than this, it's not part of a multi-click. (Default 250,000,000 ns, 250 ms.)

multiclick.N.output-hold-ns u32 rw (default: 100000000)

Positive pulses on the output pins last this long. (Default 100,000,000 ns, 100 ms.)

## AUTHOR
Sebastian Kuzminsky

## LICENSE
GPL


multiswitch

title: multiswitch(9)

text:
# multiswitch(9)

## NAME
multiswitch - This component toggles between a specified number of output bits.

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

cfg

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

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

## PINS
multiswitch.N.up bit in (default: false)

Receives signal to toggle up

multiswitch.N.down bit in (default: false)

Receives signal to toggle down

multiswitch.N.bit-MM bit out (MM=00..personality) (default: false)

Output bits

## PARAMETERS
multiswitch.N.top-position u32 rw

Number of positions

multiswitch.N.position s32 rw

Current state (may be set in the HAL)

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

## LICENSE
GPL


title: mux16(9)

summary: Select from one of sixteen input values

text:
# mux16(9)

## NAME
mux16 - Select from one of sixteen input values

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

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

## PINS
mux16.N.use-graycode bit in

This signifies the input will use Gray code instead of binary. Gray code is a good choice when using physical switches because for each increment only one select input changes at a time.

mux16.N.suppress-no-input bit in

This suppresses changing the output if all select lines are false. This stops unwanted jumps in output between transitions of input. but make in00 unavailable.

mux16.N.debounce-time float in

sets debounce time in seconds. eg. .10 = a tenth of a second input must be stable this long before outputs changes. This helps to ignore 'noisy' switches.

mux16.N.selM bit in (M=0..3)

Together, these determine which inN value is copied to out.

mux16.N.out-f float out

mux16.N.out-s s32 out

Follows the value of one of the inN values according to the four sel values and whether use-graycode is active. The s32 value will be trunuated and limited to the max and min values of signed values.

sel3=FALSE, sel2=FALSE, sel1=FALSE, sel0=FALSE

out follows in0

sel3=FALSE, sel2=FALSE, sel1=FALSE, sel0=TRUE

out follows in1

etc.

mux16.N.inMM float in (MM=00..15)

array of selectable outputs

## PARAMETERS
mux16.N.elapsed float r

Current value of the internal debounce timer

for debugging.

mux16.N.selected s32 r

Current value of the internal selection variable after conversion

for debugging

## SEE ALSO
mux2(9), mux4(9), mux8(9), mux_generic(9).

## AUTHOR
Chris S Morley

## LICENSE
GPL


title: mux2(9)

summary: Select from one of two input values

text:
# mux2(9)

## NAME
mux2 - Select from one of two input values

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

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

## PINS
mux2.N.sel bit in

mux2.N.out float out

Follows the value of in0 if sel is FALSE, or in1 if sel is TRUE

mux2.N.in1 float in

mux2.N.in0 float in

## SEE ALSO
mux4(9), mux8(9), mux16(9), mux_generic(9).

## AUTHOR
Jeff Epler

## LICENSE
GPL


title: mux4(9)

summary: Select from one of four input values

text:
# mux4(9)

## NAME
mux4 - Select from one of four input values

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

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

## PINS
mux4.N.sel0 bit in

mux4.N.sel1 bit in

Together, these determine which inN value is copied to out.

mux4.N.out float out

Follows the value of one of the inN values according to the two sel values

sel1=FALSE, sel0=FALSE

out follows in0

sel1=FALSE, sel0=TRUE

out follows in1

sel1=TRUE, sel0=FALSE

out follows in2

sel1=TRUE, sel0=TRUE

out follows in3

mux4.N.in0 float in

mux4.N.in1 float in

mux4.N.in2 float in

mux4.N.in3 float in

## SEE ALSO
mux2(9), mux8(9), mux16(9), mux_generic(9).

## AUTHOR
Jeff Epler

## LICENSE
GPL


title: mux8(9)

summary: Select from one of eight input values

text:
# mux8(9)

## NAME
mux8 - Select from one of eight input values

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

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

## PINS
mux8.N.sel0 bit in

mux8.N.sel1 bit in

mux8.N.sel2 bit in

Together, these determine which inN value is copied to out.

mux8.N.out float out

Follows the value of one of the inN values according to the three sel values

sel2=FALSE, sel1=FALSE, sel0=FALSE

out follows in0

sel2=FALSE, sel1=FALSE, sel0=TRUE

out follows in1

sel2=FALSE, sel1=TRUE, sel0=FALSE

out follows in2

sel2=FALSE, sel1=TRUE, sel0=TRUE

out follows in3

sel2=TRUE, sel1=FALSE, sel0=FALSE

out follows in4

sel2=TRUE, sel1=FALSE, sel0=TRUE

out follows in5

sel2=TRUE, sel1=TRUE, sel0=FALSE

out follows in6

sel2=TRUE, sel1=TRUE, sel0=TRUE

out follows in7

mux8.N.in0 float in

mux8.N.in1 float in

mux8.N.in2 float in

mux8.N.in3 float in

mux8.N.in4 float in

mux8.N.in5 float in

mux8.N.in6 float in

mux8.N.in7 float in

## SEE ALSO
mux2(9), mux4(9), mux16(9), mux_generic(9).

## AUTHOR
Stuart Stevenson

## LICENSE
GPL


title: mux_generic(9)

summary: choose one from several input values

text:
# mux_generic(9)

## NAME
mux_generic - choose one from several input values

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

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

## PINS
mux-gen.NN.suppress-no-input bit in

This suppresses changing the output if all select lines are false. This stops unwanted jumps in output between transitions of input but makes in00 unavailable.

mux-gen.NN.debounce-us unsigned in

sets debounce time in microseconds, e.g. 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-bit-MM bit in (M=0..N)

mux-gen.NN.sel-int unsigned in

Together, these determine which inN value is copied to output. The bit pins are interpreted as binary bits, and the result is simply added on to the integer pin input. It is expected that either one or the other would normally be used. However, the possibility exists to use a higher-order bit to "shift" the values set by the integer pin. The sel-bit pins are only created when the size of the mux_gen component is an integer power of two. This component (unlike mux16) does not offer the option of decoding Gray-code, however the same effect can be achieved by arranging the order of the input values to suit.

mux-gen.NN.out-[bit/float/s32/u32] variable-type out

Follows the value of one of the inN values according to the selection bits and/or the selection number. Values will be converted/truncated according to standard C rules. This means, for example that a float input greater than 2147483647 will give an S32 output of -2147483648.

mux-gen.NN.in-[bit/float/s32/u32]-MM variable-type in

The possible output values that are selected by the selection pins.

## PARAMETERS
mux-gen.N.elapsed float r

Current value of the internal debounce timer for debugging.

mux-gen.N.selected s32 r

Current value of the internal selection variable after conversion for debugging. Possibly useful for setting up gray-code switches.

## DESCRIPTION
This component is a more general version of the other multiplexing components. It allows the creation of arbitrary-size multiplexers (up to 1024 entries) and also supports differing data types on the input and output pins. The configuration string is a comma-separated list of code-letters and numbers, such as "bb4,fu12".

This would create a 4-element bit-to-bit mux and a 12-element float-to-unsigned mux. The code letters are b = bit, f = float, s = signed integer, u = unsigned integer. The first letter code is the input type, the second is the output type. The codes are not case-sensitive. The order of the letters is significant but the position in the string is not. Do not insert any spaces in the config string. Any non-zero float value will be converted to a "true" output in bit form. Be wary that float datatypes can be very, very, close to zero and not actually be equal to zero.

Each mux has its own HAL function and must be added to a thread separately. If neither input nor output is of type float then the function is base-thread (non floating-point) safe. Any mux_generic with a floating point input or output can only be added to a floating-point thread.

## SEE ALSO
mux2(9), mux4(9), mux8(9), mux16(9).

## AUTHOR
Andy Pugh

## LICENSE
GPL


near

title: near(9)

text:
# near(9)

## NAME
near - Determine whether two values are roughly equal.

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

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

## PINS
near.N.in1 float in

near.N.in2 float in

near.N.out bit out

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

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

near.N.difference float rw (default: 0)

## AUTHOR
Chris Radek

## LICENSE
GPL


not

title: not(9)

summary: Inverter

text:
# not(9)

## NAME
not - Inverter

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

## FUNCTIONS
not.N (requires a floating-point thread)

## PINS
not.N.in bit in

not.N.out bit out

## SEE ALSO
and2(9), logic(9), lut5(9), or2(9), xor2(9).

## AUTHOR
Jeff Epler

## LICENSE
GPL


offset

title: offset(9)

text:
# offset(9)

## NAME
offset - Adds an offset to an input, and subtracts it from the feedback value.

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

## FUNCTIONS
offset.N.update-output (requires a floating-point thread)

Updated the output value by adding the offset to the input.

offset.N.update-feedback (requires a floating-point thread)

Update the feedback value by subtracting the offset from the feedback.

## PINS
offset.N.offset float in

The offset value

offset.N.in float in

The input value

offset.N.out float out

The output value

offset.N.fb-in float in

The feedback input value

offset.N.fb-out float out

The feedback output value

## AUTHOR
Jeff Epler

## LICENSE
GPL


ohmic

title: ohmic(9)

text:
# ohmic(9)

## NAME
ohmic - LinuxCNC HAL component that uses a Mesa THCAD for ohmic sensing

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

## DESCRIPTION
Mesa THCAD Card component to scale input and outputs from the Mesa THCAD2, THCAD5, THCAD10, and THCAD300 cards.

Allows user configurable voltage thresholds for ohmic sensing.

Output pins are provided for:

ohmic-volts -the voltage sensed on ohmic sensing.

thcad-volts -the actual voltage measured by the THCAD.

ohmic-on -true if ohmic-volts >= ohmic-threshold, false if ohmic-volts <= ohmic-low.

A THCAD-5 would often be used for ohmic sensing in conjunction with a 24 Volt isolated power supply and a 390 kΩ series resistor resulting in a voltage divider of 4.9.

This would result in a full scale reading of 24.5 Volts which is above the power supply output voltage.

The circuit will remain protected by the THCAD's ability to tolerate a 500 Volt over-voltage indefinitely.

It is optional that power to the ohmic sensing circuit be disconnected unless probing is in progress.

## FUNCTIONS
ohmic.N (requires a floating-point thread)

## PINS
ohmic.N.is-probing bit in

True if probing

ohmic.N.ohmic-low float in (default: 21)

The threshold volts below which ohmic sensing is set to be false

ohmic.N.ohmic-threshold float in (default: 22)

The threshold volts above which ohmic sensing is set to be true

ohmic.N.thcad-0-volt-freq float in

0 volt calibration data for THCAD card in Hz

ohmic.N.thcad-divide float in (default: 32)

THCAD divider set by links on THCAD board (1, 32, 64, or 128)

ohmic.N.thcad-fullscale float in (default: 5)

THCAD full scale in Volt (5, 10, or 300 Volt)

ohmic.N.thcad-max-volt-freq float in

Full scale calibration data for THCAD Card in Hz

ohmic.N.velocity-in float in

The velocity returned from the THCAD and read by the Mesa encoder input

ohmic.N.volt-divider float in (default: 4.9)

The divide ratio

ohmic.N.ohmic-on bit out

True if ohmic circuit is closed (material is sensed)

ohmic.N.ohmic-volts float out

Calculated ohmic voltage

## EXAMPLES
The below HAL example assumes a THCAD5 card using a 1/32 frequency setting and a voltage divider internal to the plasma cutter with range extended to 24.5 volts by a series 390K external resistor as per the manual. Additional information and wiring diagram is contained in the Plasma Primer in the LinuxCNC documentation.

Example Calibration Data: 0V = 122.9 kHz, 10V = 925.7 kHz should be entered as 122900 and 925700.

loadrt ohmic names=ohmicsense

addf ohmicsense servo-thread

setp ohmicsense.thcad-0-volt-freq 122900

setp ohmicsense.thcad-max-volt-freq 925700

setp ohmicsense.thcad-divide 32

setp ohmicsense.thcad-fullscale 5

setp ohmicsense.volt-divider 4.9

setp ohmicsense.threshold 22

setp ohmicsense.ohmic-low 21

net ohmic-vel ohmicsense.velocity-in <= hm2_7i76e.0.encoder.00.velocity

net ohmic-enable ohmicsense.is_probing <= plasmac.ohmic-enable

net ohmic-true ohmicsense.ohmic-on => plasmac.ohmic-probe

## AUTHOR
Rod Webster

## LICENSE
GPL


oneshot

title: oneshot(9)

summary: one-shot pulse generator

text:
# oneshot(9)

## NAME
oneshot - one-shot pulse generator

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

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

## FUNCTIONS
oneshot.N (requires a floating-point thread)

Produce output pulses from input edges

## PINS
oneshot.N.in bit in

Trigger input

oneshot.N.reset bit in

Reset

oneshot.N.out bit out

Active high pulse

oneshot.N.out-not bit out

Active low pulse

oneshot.N.width float in (default: 0)

Pulse width in seconds

oneshot.N.time-left float out

Time left in current output pulse

## PARAMETERS
oneshot.N.retriggerable bit rw (default: TRUE)

Allow additional edges to extend pulse

oneshot.N.rising bit rw (default: TRUE)

Trigger on rising edge

oneshot.N.falling bit rw (default: FALSE)

Trigger on falling edge

## AUTHOR
John Kasunich

## LICENSE
GPL


title: opto_ac5(9)

text:
# opto_ac5(9)

## NAME
opto_ac5 - Realtime driver for opto22 PCI-AC5 cards

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

## DESCRIPTION
These pins and parameters are created by the realtime opto_ac5 module. The portconfig0 and portconfig1 variables are used to configure the two ports of each card. The first 24 bits of a 32 bit number represent the 24 i/o points of each port. The lowest (rightmost) bit would be HAL pin 0 which is header connector pin 47. Then next bit to the left would be HAL pin 1, header connector pin 45 and so on, until 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, e.g., loadrt opto_ac5 portconfig0=0xfff000

If no portconfig variable is specified the default configuration is 12 inputs then 12 outputs.

Up to 4 boards are supported. Boards are numbered starting at 0.

Portnumber can be 0 or 1. Port 0 is closest to the card bracket.

## PINS
opto_ac5.[BOARDNUMBER].port[PORTNUMBER].in-[PINNUMBER] OUT bit

opto_ac5.[BOARDNUMBER].port[PORTNUMBER].in-[PINNUMBER]-not OUT bit

Connect a HAL bit signal to this pin to read an i/o point from the card. The PINNUMBER represents the position in the relay rack. E.g., PINNUMBER 0 is position 0 in a opto22 relay rack and would be pin 47 on the 50 pin header connector. The -not pin is inverted so that LOW gives TRUE and HIGH gives FALSE.

opto_ac5.[BOARDNUMBER].port[PORTNUMBER].out-[PINNUMBER] IN bit

Connect a HAL bit signal to this pin to write to an i/o point of the card. The PINNUMBER represents the position in the relay rack. E.g., PINNUMBER 23 is position 23 in a opto22 relay rack and would be pin 1 on the 50 pin header connector.

opto_ac5.[BOARDNUMBER].led[NUMBER] OUT bit

Turns one of the on board LEDS on/off. LEDS are numbered 0 to 3.

## PARAMETERS
opto_ac5.[BOARDNUMBER].port[PORTNUMBER].out-[PINNUMBER]-invert W bit

When TRUE, invert the meaning of the corresponding -out pin so that TRUE gives LOW and FALSE gives HIGH.

## FUNCTIONS
opto_ac5.0.digital-read

Add this to a thread to read all the input points.

opto_ac5.0.digital-write

Add this to a thread to write all the output points and LEDS.

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

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


title: or2(9)

summary: Two-input OR gate

text:
# or2(9)

## NAME
or2 - Two-input OR gate

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

## FUNCTIONS
or2.N (requires a floating-point thread)

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

## SEE ALSO
logic(9)

## AUTHOR
Jeff Epler

## LICENSE
GPL


orient

title: orient(9)

text:
# orient(9)

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

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

## DESCRIPTION
This component is designed to support a spindle orientation PID loop by providing a command value, and fit with the motion spindle-orient support pins to support the M19 code.

The spindle is assumed to have stopped in an arbitrary position. The spindle encoder position is linked to the position pin. The current value of the position pin is sampled on a positive edge on the enable pin, and command is computed and set as follows: floor(number of full spindle revolutions in the position sampled on positive edge) plus angle/360 (the fractional revolution) +1/-1/0 depending on mode.

The mode pin is interpreted as follows:

0: the spindle rotates in the direction with the lesser angle, which may be clockwise or counterclockwise.

1: the spindle rotates always rotates clockwise to the new angle.

2: the spindle rotates always rotates counterclockwise to the new angle.

## HAL USAGE
On spindle.N.orient disconnect the spindle control and connect to the orient-pid loop:

loadrt orient names=orient

loadrt pid names=orient-pid

net orient-angle spindle.N.orient-angle orient.angle

net orient-mode spindle.N.orient-mode orient.mode

net orient-enable spindle.N.orient orient.enable orient-pid.enable

net spindle-in-pos orient.is-oriented spindle.N.is-oriented

net spindle-pos encoder.position orient.position orient-pid.feedback

net orient-command orient.command orient-pid.command

## FUNCTIONS
orient.N (requires a floating-point thread)

Update command based on enable, position, mode and angle.

## PINS
orient.N.enable bit in

enable angular output for orientation mode

orient.N.mode s32 in

0: rotate - shortest move; 1: always rotate clockwise; 2: always rotate counterclockwise

orient.N.position float in

spindle position input, unit 1 rev

orient.N.angle float in

orient target position in degrees, 0 <= angle < 360

orient.N.command float out

target spindle position, input to PID command

orient.N.poserr float out

in degrees - aid for PID tuning

orient.N.is-oriented bit out

This pin goes high when poserr < tolerance. Use to drive spindle.N.is-oriented

orient.N.tolerance float in (default: 0.5)

The tolerance in degrees for considering the align completed

## AUTHOR
Michael Haberler

## LICENSE
GPL


pentakins

title: pentakins(9)

text:
# pentakins(9)

See the file man9/kins.9.


pid

title: pid(9)

text:
# pid(9)

## NAME
pid - proportional/integral/derivative controller with automatic tuning support

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

## DESCRIPTION
pid is a classic Proportional/Integral/Derivative controller, used to control position or speed feedback loops for servo motors and other closed-loop applications.

pid supports a maximum of sixteen controllers. The number that are actually loaded is set by the num_chan argument when the module is loaded. Alternatively, specify names= and unique names separated by commas.

The num_chan= and names= specifiers are mutually exclusive. If neither num_chan= nor names= are specified, the default value is three. If debug is set to 1 (the default is 0), some additional HAL parameters will be exported, which might be useful for tuning, but are otherwise unnecessary.

In the following description, it is assumed that we are discussing position loops. However this component can be used to implement other loops such as speed loops, torch height control, and others.

Each loop has a number of pins and parameters, whose names begin with 'pid.N.', where 'N' is the channel number. Channel numbers start at zero.

The three most important pins are 'command', 'feedback', and 'output'. For a position loop, 'command' and 'feedback' are in position units. For a linear axis, this could be inches, mm, metres, or whatever is relevant. Likewise, for a angular axis, it could be degrees, radians, etc. The units of the 'output' pin represent the change needed to make the feedback match the command. As such, for a position loop 'output' is a velocity, in inches/sec, mm/sec, degrees/sec, etc.

Each loop has several other pins as well. 'error' is equal to 'command' minus 'feedback'. 'enable' is a bit that enables the loop. If 'enable' is false, all integrators are reset, and the output is forced to zero. If 'enable' is true, the loop operates normally.

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

Pgain Proportional gain

Igain Integral gain

Dgain Derivative gain

bias Constant offset on output

FF0 Zeroth order Feedforward gain

FF1 First order Feedforward gain

FF2 Second order Feedforward gain

FF3 Third order Feedforward gain

deadband Amount of error that will be ignored

maxerror Limit on error

maxerrorI Limit on error integrator

maxerrorD Limit on error differentiator

maxcmdD Limit on command differentiator

maxcmdDD Limit on command 2nd derivative

maxcmdDDD Limit on command 3rd derivative

maxoutput Limit on output value

All of the limits (max____) are implemented such that if the parameter value is zero, there is no limit.

A number of internal values which may be useful for testing and tuning are also available as parameters. To avoid cluttering the parameter list, these are only exported if "debug=1" is specified on the insmod command line.

errorI Integral of error

errorD Derivative of error

commandD Derivative of the command

commandDD 2nd derivative of the command

commandDDD 3rd derivative of the command

The PID loop calculations are as follows (see the code in pid.c for all the nitty gritty details):

```
error = command - feedback
if ( abs(error) < deadband ) then error = 0
limit error to +/- maxerror
errorI += error * period
limit errorI to +/- maxerrorI
errorD = (error - previouserror) / period
limit errorD to +/- maxerrorD
commandD = (command - previouscommand) / period
limit commandD to +/- maxcmdD
commandDD = (commandD - previouscommandD) / period
limit commandDD to +/- maxcmdDD
commandDDD = (commandDD - previouscommandDD) / period
limit commandDDD to +/- maxcmdDDD
output = bias + error * Pgain + errorI * Igain +

         errorD * Dgain + command * FF0 + commandD * FF1 +

         commandDD * FF2 + commandDDD * FF3
limit output to +/- maxoutput
```

This component has a built in auto tune mode. It works by setting up a limit cycle to characterize the process. This is called the Relay method and described in the 1984 Automation paper Automatic Tuning of Simple Regulators with Specifications on Phase and Amplitude Margins by Karl Johan Åström and Tore Hägglund (doi:10.1016/0005-1098(84)90014-1), https://lup.lub.lu.se/search/ws/files/6340936/8509157.pdf. Using this method, Pgain/Igain/Dgain or Pgain/Igain/FF1 can be determined using the Ziegler-Nichols algorithm. When using FF1 tuning, 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. Note that setting tune-mode to true disable the control loop. When auto tuning completes, the tuning parameters will be set, the output set to bias and the controller still be disabled. 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, take the following steps. Move the axis to be tuned somewhere near the center of it's travel. Set tune-cycles (the default value should be fine 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. 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 any time by setting enable or tune-mode to false.

## NAMING
The names for pins, parameters, and functions are prefixed 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 floating-point) Does the PID calculations for control loop N.

## PINS
pid.N.command float in

The desired (commanded) value for the control loop.

pid.N.Pgain float in

Proportional gain. Results in a contribution to the output that is the error multiplied by Pgain.

pid.N.Igain float in

Integral gain. Results in a contribution to the output that is the integral of the error multiplied by Igain. For example an error of 0.02 that lasted 10 seconds would result in an integrated error (errorI) of 0.2, and if Igain is 20, the integral term would add 4.0 to the output.

pid.N.Dgain float in

Derivative gain. Results in a contribution to the output that is the rate of change (derivative) of the error multiplied by Dgain. For example an error that changed from 0.02 to 0.03 over 0.2 seconds would result in an error derivative (errorD) of of 0.05, and if Dgain is 5, the derivative term would add 0.25 to the output.

pid.N.feedback float in

The actual (feedback) value, from some sensor such as an encoder.

pid.N.output float out

The output of the PID loop, which goes to some actuator such as a motor.

pid.N.command-deriv float in

The derivative of the desired (commanded) value for the control loop. If no signal is connected then the derivative will be estimated numerically.

pid.N.feedback-deriv float in

The derivative of the actual (feedback) value for the control loop. If no signal is connected then the derivative will be estimated numerically. When the feedback is from a quantized position source (e.g., encoder feedback position), behavior of the D term can be improved by using a better velocity estimate here, such as the velocity output of encoder(9) or hostmot2(9).

pid.N.error-previous-target bit in

Use previous invocation's target vs. current position for error calculation, like the motion controller expects. This may make torque-mode position loops and loops requiring a large I gain easier to tune, by eliminating velocity-dependent following error.

pid.N.error float out

The difference between command and feedback.

pid.N.enable bit in

When true, enables the PID calculations. When false, output is zero, and all internal integrators, etc, are reset.

pid.N.index-enable bit in

On the falling edge of index-enable, pid does not update the internal command derivative estimate. On systems which use the encoder index pulse, this pin should be connected to the index-enable signal. When this is not done, and FF1 is nonzero, a step change in the input command causes a single-cycle spike in the PID output. On systems which use exactly one of the -deriv inputs, this affects the D term as well.

pid.N.bias float in

bias is a constant amount that is added to the output. In most cases it should be left at zero. However, it can sometimes be useful to compensate for offsets in servo amplifiers, or to balance the weight of an object that moves vertically. bias is turned off when the PID loop is disabled, just like all other components of the output. If a non-zero output is needed even when the PID loop is disabled, it should be added with an external HAL sum2 block.

pid.N.FF0 float in

Zero order feed-forward term. Produces a contribution to the output that is FF0 multiplied by the commanded value. For position loops, it should usually be left at zero. For velocity loops, FF0 can compensate for friction or motor counter-EMF and may permit better tuning if used properly.

pid.N.FF1 float in

First order feed-forward term. Produces a contribution to the output that is FF1 multiplied by the derivative of the commanded value. For position loops, the contribution is proportional to speed, and can be used to compensate for friction or motor CEMF. For velocity loops, it is proportional to acceleration and can compensate for inertia. In both cases, it can result in better tuning if used properly.

pid.N.FF2 float in

Second order feed-forward term. Produces a contribution to the output that is FF2 multiplied by the second derivative of the commanded value. For position loops, the contribution is proportional to acceleration, and can be used to compensate for inertia. For velocity loops, the contribution is proportional to jerk, and should usually be left at zero.

pid.N.FF3 float in

Third order feed-forward term. Produces a contribution to the output that is FF3 multiplied by the third derivative of the commanded value. For position loops, the contribution is proportional to jerk, and can be used to compensate for residual errors during acceleration. For velocity loops, the contribution is proportional to snap(jounce), and should usually be left at zero.

pid.N.deadband float in

Defines a range of "acceptable" error. If the absolute value of error is less than deadband, it will be treated as if the error is zero. When using feedback devices such as encoders that are inherently quantized, the deadband should be set slightly more than one-half count, to prevent the control loop from hunting back and forth if the command is between two adjacent encoder values. When the absolute value of the error is greater than the deadband, the deadband value is subtracted from the error before performing the loop calculations, to prevent a step in the transfer function at the edge of the deadband (see BUGS).

pid.N.maxoutput float in

Output limit. The absolute value of the output will not be permitted to exceed maxoutput, unless maxoutput is zero. When the output is limited, the error integrator will hold instead of integrating, to prevent windup and overshoot.

pid.N.maxerror float in

Limit on the internal error variable used for P, I, and D. Can be used to prevent high Pgain values from generating large outputs under conditions when the error is large (for example, when the command makes a step change). Not normally needed, but can be useful when tuning non-linear systems.

pid.N.maxerrorD float in

Limit on the error derivative. The rate of change of error used by the Dgain term will be limited to this value, unless the value is zero. Can be used to limit the effect of Dgain and prevent large output spikes due to steps on the command and/or feedback. Not normally needed.

pid.N.maxerrorI float in

Limit on error integrator. The error integrator used by the Igain term will be limited to this value, unless it is zero. Can be used to prevent integrator windup and the resulting overshoot during/after sustained errors. Not normally needed.

pid.N.maxcmdD float in

Limit on command derivative. The command derivative used by FF1 will be limited to this value, unless the value is zero. Can be used to prevent FF1 from producing large output spikes if there is a step change on the command. Not normally needed.

pid.N.maxcmdDD float in

Limit on command second derivative. The command second derivative used by FF2 will be limited to this value, unless the value is zero. Can be used to prevent FF2 from producing large output spikes if there is a step change on the command. Not normally needed.

pid.N.maxcmdDDD float in

Limit on command third derivative. The command third derivative used by FF3 will be limited to this value, unless the value is zero. Can be used to prevent FF3 from producing large output spikes if there is a step change on the command. Not normally needed.

pid.N.saturated bit out

When true, the current PID output is saturated. That is,

output = ± maxoutput.

pid.N.saturated-s float out

pid.N.saturated-count s32 out

When true, the output of PID was continually saturated for this many seconds (saturated-s) or periods (saturated-count).

### Additional auto tuning pins
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.

pid.N.tune-type u32 rw

When set to 0, Pgain/Igain/Dgain are calculated. 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 float rw

Determines the effort used in setting up the limit cycle in the process. tune-effort should be set to a positive 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.ultimate-gain float ro (only if debug=1)

Determined from process characterization. ultimate-gain is the ratio of tune-effort to the limit cycle amplitude multiplied by 4.0 divided by Pi.

pid.N.ultimate-period float ro (only if debug=1)

Determined from process characterization. ultimate-period is the period of the limit cycle.

## PARAMETERS
pid.N.errorI float ro (only if debug=1)

Integral of error. This is the value that is multiplied by Igain to produce the Integral term of the output.

pid.N.errorD float ro (only if debug=1)

Derivative of error. This is the value that is multiplied by Dgain to produce the Derivative term of the output.

pid.N.commandD float ro (only if debug=1)

Derivative of command. This is the value that is multiplied by FF1 to produce the first order feed-forward term of the output.

pid.N.commandDD float ro (only if debug=1)

Second derivative of command. This is the value that is multiplied by FF2 to produce the second order feed-forward term of the output.

pid.N.commandDDD float ro (only if debug=1)

Third derivative of command. This is the value that is multiplied by FF3 to produce the third order feed-forward term of the output.

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

Negative gains may lead to unwanted behavior. It is possible in some situations that negative FF gains make sense, but in general all gains should be positive. If some output is in the wrong direction, negating gains to fix it is a mistake; set the scaling correctly elsewhere instead.