title: hostmot2(9)

text:
# hostmot2(9)

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

## SYNOPSIS
See the config modparam section below for Mesa card configuration. Typically hostmot2 is loaded with no parameters unless debugging is required.

loadrt hostmot2 [debug_idrom=N] [debug_module_descriptors=N] [debug_pin_descriptors=N] [debug_modules=N]

debug_idrom [default: 0]

Developer/debug use only! Enable debug logging of the HostMot2 IDROM header.

debug_module_descriptors [default: 0]

Developer/debug use only! Enables debug logging of the HostMot2 Module Descriptors.

debug_pin_descriptors [default: 0]

Developer/debug use only! Enables debug logging of the HostMot2 Pin Descriptors.

debug_modules [default: 0]

Developer/debug use only! Enables debug logging of the HostMot2 Modules used.

use_serial_numbers [default: 0]

When creating HAL pins for smart-serial devices name the pins by the board serial number rather than which board and port they are connected to. With this option set to 1 pins will have names like hm2_8i20.1234.current rather than hm2_5i23.0.8i20.0.1.current. The identifier consists of the last 4 digits of the board serial number, which is normally on a sticker on the board. This will make configs less portable, but does mean that boards can be re-connected less carefully.

## DESCRIPTION
hostmot2 is a device driver that interfaces the Mesa or litehm2 HostMot2 firmware to the LinuxCNC HAL. This driver by itself does nothing, the boards that actually run the firmware require their own drivers before anything can happen. Currently drivers are available for PCI, Ethernet, SPI and EPP interfaced cards.

The HostMot2 firmware provides modules such as encoders, PWM generators, step/dir generators, and general purpose I/O pins (GPIOs). These things are called "Modules". The firmware is configured, at firmware compile time, to provide zero or more instances of each of these Modules.

### Board I/O Pins
The HostMot2 firmware runs on an FPGA board. The board interfaces with the computer via PCI, Ethernet, SPI, or EPP, and interfaces with motion control hardware, such as servos and stepper motors via I/O pins on the board.

Each I/O pin can be configured, at board-driver load time, to serve one of two purposes: Either as a particular I/O pin of a particular Module instance (encoder, pwmgen, stepgen etc), or as a general purpose digital I/O pin. By default all Module instances are enabled, and all the board's pins are used by the Module instances.

The user can disable Module instances at board-driver load time, by specifying a hostmot2 config string modparam. Any pins which belong to Module instances that have been disabled automatically become GPIOs.

All IO pins have some HAL presence, whether they belong to an active module instance or are full GPIOs. GPIOs can be changed (at run-time) between inputs, normal outputs, and open drains, and have a flexible HAL interface. IO pins that belong to active Module instances are constrained by the requirements of the owning Module, and have a more limited interface in HAL. This is described in the General Purpose I/O section below.

### config modparam
All the board-driver modules (hm2_pci, hm2_eth etc) accept a load-time modparam of type string array, named "config". This array has one config string for each board the driver should use. Each board's config string is passed to and parsed by the hostmot2 driver when the board-driver registers the board.

The config string can contain spaces, so it is usually a good idea to wrap the whole thing in double-quotes (the " character).

The comma character (,) separates members of the config array from each other.

For example, if your control computer has one 5I20 and one 5I23 you might load the hm2_pci driver with a HAL command (in halcmd) something like this:

```
loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT num_encoders=3 num_pwmgens=3 num_stepgens=3,firmware=hm2/5i23/SVSS8_8.BIT sserial_port_0=0000 num_encoders=4"
```

Note: this assumes that the hm2_pci driver detects the 5I20 first and the 5I23 second. If the detection order does not match the order of the config strings, the hostmot2 driver will refuse to load the firmware and the board-driver (hm2_pci etc) will fail to load. To the best of my knowledge, there is no way to predict the order in which PCI boards will be detected by the driver, but the detection order will be consistent as long as PCI boards are not moved around. Best to try loading it and see what the detection order is.

The valid entries in the format string are:

[firmware=F]

[num_dplls=N]

[num_encoders=N]

[ssi_chan_N=abc%nq]

[biss_chan_N=abc%nq]

[fanuc_chan_N=abc%nq]

[num_inmuxs=N]

[num_inms=N]

[num_resolvers=N]

[num_pwmgens=N]

[num_3pwmgens=N]

[num_oneshots=N]

[num_rcpwmgens=N]

[num_stepgens=N]

[stepgen_width=N]

[sserial_port_0=00000000]

[num_bspis=N]

[num_leds=N]

[num_ssrs=N]

[num_outms=N]

[num_xy2mods=N]

[enable_raw]

firmware [optional]

Load the firmware specified by F into the FPGA on this board. If no "firmware=F" string is specified, the FPGA will not be re-programmed but may continue to run a previously downloaded firmware. The requested firmware F is fetched by udev, which searches for the firmware in the system's firmware search path, usually /lib/firmware. F typically has the form "hm2/<BoardType>/file.bit"; a typical value for F might be "hm2/5i20/SVST8_4.BIT". The hostmot2 firmware files are supplied by the hostmot2-firmware packages, available from linuxcnc.org and can normally be installed by entering the command "sudo apt-get install hostmot2-firmware-5i23" to install the support files for the 5I23 for example.

Newer FPGA cards come pre-programmed with firmware and no "firmware=" string should be used with these cards. To change the firmware on these cards the "mesaflash" utility should be used. It is perfectly valid and reasonable to load these cards with no config string at all.

num_dplls [optional, default: -1]

The hm2dpll is a phase-locked loop timer module which may be used to reduce sample and write time jitter for some hm2 modules. This parameter can be used to disable the hm2dpll by setting the number to 0. There is only ever one module of this type, with 4 timer channels, so the other valid numbers are -1 (enable all) and 1, both of which end up meaning the same thing.

num_encoders [optional, default: -1]

Only enable the first N encoders. If N is -1, all encoders are enabled. If N is 0, no encoders are enabled. If N is greater than the number of encoders available in the firmware, the board will fail to register.

ssi_chan_N [optional, default: ""]

Specifies how the bit stream from a Synchronous Serial Interface device will be interpreted. There should be an entry for each device connected. Only channels with a format specifier will be enabled (as the software can not guess data rates and bit lengths).

biss_chan_N [optional, default: ""]

As for ssi_chan_N, but for BiSS devices.

fanuc_chan_N [optional, default: ""]

Specifies how the bit stream from a Fanuc absolute encoder will be interpreted. There should be an entry for each device connected. Only channels with a format specifier will be enabled (as the software can not guess data rates and bit lengths).

num_resolvers [optional, default: -1]

Only enable the first N resolvers. If N = -1 then all resolvers are enabled. This module does not work with generic resolvers (unlike the encoder module which works with any encoder). At the time of writing this Hostmot2 Resolver function only works with the Mesa 7I49 card.

num_pwmgens [optional, default: -1]

Only enable the first N pwmgens. If N is -1, all pwmgens are enabled. If N is 0, no pwmgens are enabled. If N is greater than the number of pwmgens available in the firmware, the board will fail to register.

num_3pwmgens [optional, default: -1]

Only enable the first N Three-phase pwmgens. If N is -1, all 3pwmgens are enabled. If N is 0, no pwmgens are enabled. If N is greater than the number of pwmgens available in the firmware, the board will fail to register.

num_rcpwmgens [optional, default: -1]

Only enable the first N RC pwmgens. If N is -1, all rcpwmgens are enabled. If N is 0, no rcpwmgens are enabled. If N is greater than the number of rcpwmgens available in the firmware, the board will fail to register.

num_stepgens [optional, default: -1]

Only enable the first N stepgens. If N is -1, all stepgens are enabled. If N is 0, no stepgens are enabled. If N is greater than the number of stepgens available in the firmware, the board will fail to register.

num_xy2mods [optional, default: -1]

Only enable the first N xy2mods. If N is -1, all xy2mods are enabled. If N is 0, no xy2mods are enabled. If N is greater than the number of xy2mods available in the firmware, the board will fail to register.

stepgen_width [optional, default: 2]

Used to mask extra, unwanted, stepgen pins. Stepper drives typically require only two pins (step and dir) but the Hostmot2 stepgen can drive up to 8 output pins for specialised applications (depending on firmware). This parameter applies to all stepgen instances. Unused, masked pins will be available as GPIO.

sserial_port_N (N = 0 .. 3) [optional, default: 00000000 for all ports]

Up to 32 Smart Serial devices can be connected to a Mesa Anything IO board, depending on the firmware used and the number of physical connections on the board. These are arranged in 1-4 ports (N) of 1 to 8 channels. Some Smart Serial (SSLBP) cards offer more than one load-time configuration, for example all inputs, or all outputs, or offering additional analogue input on some digital pins. To set the modes for port 0 use for example sserial_port_0=0120xxxx. A "0" in the string sets the corresponding channel to mode 0, a "1" to mode 1, and so on up to mode 9. An "x" in any position disables that channel and makes the corresponding FPGA pins available as GPIO. The string can be up to 8 characters long, and if it defines more modes than there are channels on the port then the extras are ignored. Channel numbering is left to right so the example above would set sserial device 0.0 to mode 0, 0.1 to mode 1, 0.2 to mode 2, 0.3 to mode 0 and disables channels 0.4 onwards. The sserial driver will auto-detect connected devices, no further configuration should be needed. Unconnected channels will default to GPIO, but the pin values will vary semi-randomly during boot when card-detection runs, to it is best to actively disable any channel that is to be used for GPIO. See SSERIAL(9) for more information.

num_bspis [optional, default: -1]

Only enable the first N Buffered SPI drivers. If N is -1 then all the drivers are enabled. Each BSPI driver can address 16 devices.

num_leds [optional, default: -1]

Only enable the first N of the LEDs on the FPGA board. If N is -1, then HAL pins for all the LEDs will be created. If N=0 then no pins will be added.

num_ssrs [optional, default: -1]

Only enable the first N of the SSR modules on the FPGA board. If N is -1, then HAL pins for all the SSR outputs will be created. If N=0 then no pins will be added.

enable_raw [optional]

If specified, this turns on a raw access mode, whereby a user can peek and poke the firmware from HAL. See Raw Mode below.

### dpll
The hm2dpll module has pins like "hm2_<BoardType>.<BoardNum>.dpll" It is likely that the pin-count will decrease in the future and that some pins will become parameters. This module is a phase-locked loop that will synchronise itself with the thread in which the hostmot2 "read" function is installed and will trigger other functions that are allocated to it at a specified time before or after the "read" function runs. This can be applied to the three absolute encoder types, quadrature encoder, stepgen, and xy2mod. In the case of the absolute encoders this allows the system to trigger a data transmission just prior to the time when the HAL driver reads the data. In the case of stepgens, quadrature encoders, and the xy2mod, the timers can be used to reduce position sampling jitter. This is especially valuable with the ethernet-interfaced cards.

Pins:

(float, in) hm2_<BoardType>.<BoardNum>.dpll.NN.timer-us

This pin sets the triggering offset of the associated timer. There are 4 timers numbered 01 to 04, represented by the NN digits in the pin name. The units are microseconds (µs). Generally the value for reads will be negative, and positive for writes, so that input data is sampled prior to the main hostmot read and output data is written some time after the main hostmot2 read. For stepgen and quadrature encoders, the value needs to be more than the maximum variation between read times. -100 will suffice for most systems, and -50 will work on systems with good performance and latency.

For serial encoders, the value also needs to include the time it takes to transfer the absolute encoder position. For instance, if 50 bits must be read at 500 kHz then subtract an additional 50/500 kHz = 100 µs to get a starting value of -200.

The xy2mod uses 2 DPLL timers, one for read and one for write. The read timer value can be the same as used by the stepgen and quadrature encoders so the same timer channel can be shared. The write timer is typically set to a time after the main hostmot2 write this may take some experimentation.

(float, in) hm2_<BoardType>.<BoardNum>.dpll.base-freq-khz

This pin sets the base frequency of the phase-locked loop. By default it will be set to the nominal frequency of the thread in which the PLL is running and will not normally need to be changed.

(float, out) hm2_<BoardType>.<BoardNum>.dpll.phase-error-us

Indicates the phase error of the DPLL. If the number cycles by a large amount it is likely that the PLL has failed to achieve lock and adjustments will need to be made.

(u32, in) hm2_<BoardType>.<BoardNum>.dpll.time-const

The filter time-constant for the PLL. The default value is a compromise between insensitivity to single-cycle variations and being resilient to changes to the Linux CLOCK_MONOTONIC timescale, which can instantly change by up to ±500ppm from its nominal value, usually by timekeeping software like ntpd and ntpdate. Default 2000 (0x7d0).

(u32, in) hm2_<BoardType>.<BoardNum>.dpll.plimit

Sets the phase adjustment limit of the PLL. If the value is zero then the PLL will free-run at the base frequency independent of the servo thread rate. This is probably not what you want. Default 4194304 (0x400000) Units not known...

(u32, out) hm2_<BoardType>.<BoardNum>.dpll.ddsize

Used internally by the driver, likely to disappear.

(u32, in) hm2_<BoardType>.<BoardNum>.dpll.prescale

Prescale factor for the rate generator. Default 1.

### Encoder
Encoders have names like ""hm2_<BoardType>.<BoardNum>.encoder.<Instance>".". "Instance" is a two-digit number that corresponds to the HostMot2 encoder instance number. There are "num_encoders" instances, starting with 00.

So, for example, the HAL pin that has the current position of the second encoder of the first 5I25 board is: hm2_5i25.0.encoder.01.position (this assumes that the firmware in that board is configured so that this HAL object is available).

Each encoder uses three or four input IO pins, depending on how the firmware was compiled. Three-pin encoders use A, B, and Index (sometimes also known as Z). Four-pin encoders use A, B, Index, and Index-mask.

The hm2 encoder representation is similar to the one described by the Canonical Device Interface (in the HAL General Reference document), and to the software encoder component. Each encoder instance has the following pins and parameters:

Pins:

(s32 out) count

Number of encoder counts since the previous reset.

(float out) position

Encoder position in position units (count / scale).

(float out) position-latched

Encoder latched position in position units (count / scale).

(float out) velocity

Estimated encoder velocity in position units per second.

(float out) velocity-rpm

Estimated encoder velocity in position units per minute.

(bit in) reset

When this pin is True, the count and position pins are set to 0 (the value of the velocity pin is not affected by this). The driver does not reset this pin to FALSE after resetting the count to 0, that is the user's job.

(bit in/out) index-enable

When this pin is set to True, the count (and therefore also position) are reset to zero on the next Index (Phase-Z) pulse. At the same time, index-enable is reset to zero to indicate that the pulse has occurred.

(bit in/out) probe-enable

When this pin is set to True, the encoder count (and therefore also position) are latched on the the next probe active edge. At the same time, probe-enable is reset to zero to indicate that latch event has occurred.

(bit r/w) probe-invert

If set to True, the rising edge of the probe input pin triggers the latch event (if probe-enable is True). If set to False, the falling edge triggers.

(s32 out) rawcounts

Total number of encoder counts since the start, not adjusted for index or reset.

(bit out) input-a, input-b, input-index

Real time filtered values of A,B,Index encoder signals

(bit in) quad-error-enable

When this pin is True quadrature error reporting is enabled. when False, existing quadrature errors are cleared and error reporting is disabled.

(bit out) quad-error

This bit indicates that a quadrature sequence error has been detected. It can only be set if the corresponding quad-error-enable bit is True.

(u32 in) hm2_XXXX.N.encoder.sample-frequency

This is the sample frequency that determines all standard encoder channels digital filter time constant (see filter parameter).

(u32 in) hm2_XXXX.N.encoder.muxed-sample-frequency

This is the sample frequency that determines all muxed encoder channels digital filter time constant (see filter parameter). This also sets the encoder multiplexing frequency.

(float in) hm2_XXXX.N.encoder.muxed-skew

This sets the muxed encoder sample time delay (in ns) from the multiplex signal. Setting this properly can increase the usable multiplex frequency and compensate for cable delays (suggested value is 3* cable length in feet +20).

(bit in) hm2_XXXX.N.encoder.hires-timestamp

When this pin is True the encoder timestamp counter frequency is ~10 MHz when False the timestamp counter frequency is ~2 MHz. This should be set True for frequency counting applications to improve the resolution. It should be set False when servo thread periods longer than 1 ms are used. Parameters:

(float r/w) scale

Converts from "count" units to "position" units.

(bit r/w) index-invert

If set to True, the rising edge of the Index input pin triggers the Index event (if index-enable is True). If set to False, the falling edge triggers.

(bit r/w) index-mask

If set to True, the Index input pin only has an effect if the Index-Mask input pin is True (or False, depending on the index-mask-invert pin below).

(bit r/w) index-mask-invert

If set to True, Index-Mask must be False for Index to have an effect. If set to False, the Index-Mask pin must be True.

(bit r/w) counter-mode

Set to False (the default) for Quadrature. Set to True for Step/Dir (in which case Step is on the A pin and Dir is on the B pin).

(bit r/w) filter

If set to True (the default), the quadrature counter needs 15 sample clocks to register a change on any of the three input lines (any pulse shorter than this is rejected as noise). If set to False, the quadrature counter needs only 3 clocks to register a change. The default encoder sample clock runs at approximately 25 to 33 MHz but can be changed globally with the sample-frequency or muxed-sample-frequency pin.

(float r/w) vel-timeout

When the encoder is moving slower than one pulse for each time that the driver reads the count from the FPGA (in the hm2_read() function), the velocity is harder to estimate. The driver can wait several iterations for the next pulse to arrive, all the while reporting the upper bound of the encoder velocity, which can be accurately guessed. This parameter specifies how long to wait for the next pulse, before reporting the encoder stopped. This parameter is in seconds.

(s32 r/w) hm2_XXXX.N.encoder.timer-number (default: -1)

Sets the hm2dpll timer instance to be used to latch encoder counts. A setting of -1 does not latch encoder counts. A setting of 0 latches at the same time as the main hostmot2 read. A setting of 1..4 uses a time offset from the main hostmot2 read according to the dpll's timer-us setting. Typically, timer-us should be a negative number with a magnitude larger than the largest latency (e.g., -100 for a system with mediocre latency, -50 for a system with good latency). A negative number specifies latching the specified time before the nominal hostmot2 read time.

If no DPLL module is present in the FPGA firmware, or if the encoder module does not support DPLL, then this pin is not created.

When available, this feature should typically be enabled. Doing so generally reduces following errors.

### Synchronous Serial Interface (SSI)
(Not to be confused with the Smart Serial Interface)

One pin is created for each SSI instance regardless of data format: (bit, in) hm2_XXXX.NN.ssi.MM.data-incomplete. This pin will be set "True" if the module was still transferring data when the value was read. When this problem exists there will also be a limited number of error messages printed to the UI. This pin should be used to monitor whether the problem has been addressed by config changes. Solutions to the problem dpend on whether the encoder read is being triggered by the hm2dpll phase-locked-loop timer (described above) or by the trigger-encoders function (described below).

The names of the pins created by the SSI module will depend entirely on the format string for each channel specified in the loadrt command line. A typical format string might be ssi_chan_0=error%1bposition%24g.

This would interpret the LSB of the bit-stream as a bit-type pin named "error" and the next 24 bits as a Gray-coded encoder counter. The encoder-related HAL pins would all begin with "position".

There should be no spaces in the format string, as this is used as a delimiter by the low-level code.

The format consists of a string of alphanumeric characters that will form the HAL pin names, followed by a % symbol, a bit-count and a data type. All bits in the packet must be defined, even if they are not used. There is a limit of 64 bits in total.

The valid format characters and the pins they create are:

p: (Pad). Does not create any pins, used to ignore sections of the bit stream that are not required.

b: (Boolean).

(bit, out) hm2_XXXX.N.ssi.MM.<name>. If any bits in the designated field width are non-zero then the HAL pin will be "True".

(bit, out) hm2_XXXX.N.ssi.MM.<name>-not. An inverted version of the above, the HAL pin will be "True" if all bits in the field are zero.

u: (Unsigned)

(float, out) hm2_XXXX.N.ssi.MM.<name>. The value of the bits interpreted as an unsigned integer then scaled such that the pin value will equal the scalemax parameter value when all bits are high. (for example if the field is 8 bits wide and the scalmax parameter was 20 then a value of 255 would return 20, and 0 would return 0.

s: (Signed)

(float, out) hm2_XXXX.N.ssi.MM.<name>. The value of the bits interpreted as a 2s complement signed number then scaled similarly to the unsigned variant, except symmetrical around zero.

f: (bitField)

(bit, out) hm2_XXXX.N.ssi.MM.<name>-NN. The value of each individual bit in the data field. NN starts at 00 up to the number of bits in the field.

(bit, out) hm2_XXXX.N.ssi.MM.<name>-NN-not. An inverted version of the individual bit values.

e: (Encoder)

(s32, out) hm2_XXXX.N.ssi.MM.<name>.count. The lower 32 bits of the total encoder counts. This value is reset both by the ...reset and the ...index-enable pins.

(s32, out) hm2_XXXX.N.ssi.MM.<name>.rawcounts. The lower 32 bits of the total encoder counts. The pin is not affected by reset and index.

(float, out) hm2_XXXX.N.ssi.MM.<name>.position. The encoder position in machine units. This is calculated from the full 64-bit buffers so will show a True value even after the counts pins have wrapped. It is zeroed by reset and index enable.

(bit, IO) hm2_XXXX.N.ssi.MM.<name>.index-enable. When this pin is set "True" the module will wait until the raw encoder counts next passes through an integer multiple of the number of counts specified by counts-per-rev parameter and then it will zero the counts and position pins, and set the index-enable pin back to "False" as a signal to the system that "index" has been passed. this pin is used for spindle-synchronised motion and index-homing.

(bit, in) (bit, out) hm2_XXXX.N.ssi.MM.<name>.reset. When this pin is set high the counts and position pins are zeroed.

h: (Split encoder, high-order bits)

Some encoders (Including Fanuc) place the encoder part-turn counts and full-turn counts in separate, non-contiguous fields. This tag defines the high-order bits of such an encoder module. There can be only one h and one l tag per channel, the behaviour with multiple such channels will be undefined.

l: (Split encoder, low-order bits)

Low order bits (see "h")

g: (Gray-code). This is a modifier that indicates that the following format string is gray-code encoded.

This is only valid for encoders (e, h l) and unsigned (u) data types.

m: (Multi-turn). This is a modifier that indicates that the following

format string is a multi-turn encoder. This is only valid for encoders (e, h l). A jump in encoder position of more than half the full scale is interpreted as a full turn and the counts are wrapped. With a multi-turn encoder this is only likely to be a data glitch and will lead to a permanent offset. This flag endures that such encoders will never wrap.

Parameters:

Two parameters is universally created for all SSI instances

(float r/w) hm2_XXXX.N.ssi.MM.frequency-khz

This parameter sets the SSI clock frequency. The units are kHz, so 500 will give a clock frequency of 500,000 Hz.

(s32 r/w) hm2_XXXX.N.ssi.timer-number-num

This parameter allocates the SSI module to a specific hm2dpll timer instance. This pin is only of use in firmwares which contain a hm2dpll function and will default to 1 in cases where there is such a function, and 0 if there is not. The pin can be used to disable reads of the encoder, by setting to a nonexistent timer number, or to 0. Other parameters depend on the data types specified in the config string.

p: (Pad) No Parameters.

b: (Boolean) No Parameters.

u: (Unsigned)

(float, r/w) hm2_XXXX.N.ssi.MM.<name>-scalemax. The scaling factor for the channel.

s: (Signed)

(float, r/w) hm2_XXXX.N.ssi.MM.<name>-scalemax. The scaling factor for the channel.

f: (bitField): No parameters.

e: (Encoder):

(float, r/w) hm2_XXXX.N.ssi.MM.<name>.scale: (float, r.w) The encoder scale in counts per machine unit.

(u32, r/w) hm2_XXXX.N.ssi.MM.<name>.counts-per-rev (u32, r/w) Used to emulate the index behaviour of an incremental+index encoder. This would normally be set to the actual counts per rev of the encoder, but can be any whole number of revs. Integer divisors or multipliers of the true PPR might be useful for index-homing. Non-integer factors might be appropriate where there is a synchronous drive ratio between the encoder and the spindle or ballscrew.

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

One pin is created for each BiSS instance regardless of data format:

(bit, in) hm2_XXXX.NN.biss.MM.data-incomplete This pin will be set "True" if the module was still transferring data when the value was read. When this problem exists there will also be a limited number of error messages printed to the UI. This pin should be used to monitor whether the problem has been addressed by config changes. Solutions to the problem dpend on whether the encoder read is being triggered by the hm2dpll phase-locked-loop timer (described above) or by the trigger-encoders function (described below).

The names of the pins created by the BiSS module will depend entirely on the format string for each channel specified in the loadrt command line and follow closely the format defined above for SSI. Currently data packets of up to 96 bits are supported by the LinuxCNC driver, although the Mesa Hostmot2 module can handle 512 bit packets. It should be possible to extend the number of packets supported by the driver if there is a requirement to do so.

### Fanuc encoder
The pins and format specifier for this module are identical to the SSI module described above, except that at least one pre-configured format is provided. A modparam of fanuc_chan_N=AA64 (case sensitive) will configure the channel for a Fanuc Aa64 encoder. The pins created are:

hm2_XXXX.N.fanuc.MM.batt indicates battery state

hm2_XXXX.N.fanuc.MM.batt-not inverted version of above

hm2_XXXX.N.fanuc.MM.comm The 0-1023 absolute output for motor commutation

hm2_XXXX.N.fanuc.MM.crc The CRC checksum. Currently HAL has no way to use this

hm2_XXXX.N.fanuc.MM.encoder.count Encoder counts

hm2_XXXX.N.fanuc.MM.encoder.index-enable Simulated index. Set by counts-per-rev parameter

hm2_XXXX.N.fanuc.MM.encoder.position Counts scaled by the ...scale parameter

hm2_XXXX.N.fanuc.MM.encoder.rawcounts Raw counts, unaffected by reset or index

hm2_XXXX.N.fanuc.MM.encoder.reset If high/True then counts and position = 0

hm2_XXXX.N.fanuc.MM.valid Indicates that the absolute position is valid

hm2_XXXX.N.fanuc.MM.valid-not Inverted version

### resolver
Resolvers have names like hm2_<BoardType>.<BoardNum>.resolver.<Instance>. <Instance> is a 2-digit number, which for the 7I49 board will be between 00 and 05. This function only works with the Mesa Resolver interface boards (of which the 7I49 is the only example at the time of writing). This board uses an SPI interface to the FPGA card, and will only work with the correct firmware. The pins allocated will be listed in the dmesg output, but are unlikely to be usefully probed with HAL tools.

Pins:

(float, out) angle

This pin indicates the angular position of the resolver. It is a number between 0 and 1 for each electrical rotation.

(float, out) position

Calculated from the number of complete and partial revolutions since startup, reset, or index-reset multiplied by the scale parameter.

(float, out) velocity

Calculated from the rotational velocity and the velocity-scale parameter. The default scale is electrical rotations per second.

(float, out) velocity-rpm

Simply velocity scaled by a factor of 60 for convenience.

(s32, out) count

This pins outputs a simulated encoder count at 2^24 counts per rev (16777216 counts).

(s32, out) rawcounts

This is identical to the counts pin, except it is not reset by the "index" or "reset" pins. This is the pin which would be linked to the bldc HAL component if the resolver was being used to commutate a motor.

(bit, in) reset

Resets the position and counts pins to zero immediately.

(bit, in) joint-pos-fb

The Mesa resolver driver has the capability of emulating an absolute encoder using a position file (see the INI-config section of the manual) and the single-turn absolute operation of resolvers. At startup, and only if the use-position-file parameter is set to "True", the resolver driver will wait for a value to be written by the system to the axis.N.joint-pos-fb pin (which must be netted to this resolver pin) and will calculate the number of full turns that best matches the current reolver position. It will then pre-load the driver output with this offset. This should only be used on systems where axis movement in the unpowered state is unlikely. This feature will only work properly if the machine is initially homed to "index" and if the axis home positions are exactly zero.

(bit, in/out) index-enable

When this pin is set high the position and counts pins will be reset the next time the resolver passes through the zero position. At the same time the pin is driven low to indicate to connected modules that the index has been seen, and that the counters have been reset.

(bit, out) error

Indicates an error in the particular channel. If this value is "True" then the reported position and velocity are invalid. Parameters:

(float, read/write) scale

The position scale, in machine units per resolver electrical revolution.

(float, read/write) velocity-scale

The conversion factor between resolver rotation speed and machine velocity. A value of 1 will typically give motor speed in RPS, a value of 0.01666667 will give (approximate) RPM.

(u32, read/write) index-divisor (default 1)

The resolver component emulates an index at a fixed point in the sin/cos cycle. Some resolvers have multiple cycles per rev (often related to the number of pole-pairs on the attached motor). LinuxCNC requires an index once per revolution for proper threading etc. This parameter should be set to the number of cycles per rev of the resolver. CAUTION: Which pseudo-index is used will not necessarily be consistent between LinuxCNC runs. Do not expect to re-start a thread after restarting LinuxCNC. It is not appropriate to use this parameter for index-homing of axis drives.

(float, read/write) excitation-khz

This pin sets the excitation frequency for the resolver. This pin is module-level rather than instance-level as all resolvers share the same excitation frequency. Valid values are 10 (~10 kHz), 5 (~5 kHz) and 2.5 (~2.5 kHz). The actual frequency depends on the FPGA frequency, and they correspond to CLOCK_LOW/5000, CLOCK_LOW/10000 and CLOCK_LOW/20000 respectively. The parameter will be set to the closest available of the three frequencies. A value of -1 (the default) indicates that the current setting should be retained.

(bit, read/write) use-position-file

In conjunction with joint-pos-fb (qv) emulate absolute encoders.

### pwmgen
pwmgens have names like "hm2_<BoardType>.<BoardNum>.pwmgen.<Instance>". "Instance" is a two-digit number that corresponds to the HostMot2 pwmgen instance number. There are "num_pwmgens" instances, starting with 00.

So, for example, the HAL pin that enables output from the fourth pwmgen of the first 7I43 board is: hm2_7i43.0.pwmgen.03.enable (this assumes that the firmware in that board is configured so that this HAL object is available).

In HM2, each pwmgen uses three output IO pins: Not-Enable, Out0, and Out1.

The function of the Out0 and Out1 IO pins varies with output-type parameter (see below).

The hm2 pwmgen representation is similar to the software pwmgen component. Each pwmgen instance has the following pins and parameters:

Pins:

(bit input) enable

If True, the pwmgen will set its Not-Enable pin False and output its pulses. If "enable" is False, pwmgen will set its Not-Enable pin True and not output any signals.

(float input) value

The current pwmgen command value, in arbitrary units. Parameters:

(float rw) scale

Scaling factor to convert "value" from arbitrary units to duty cycle: dc = value / scale. Duty cycle has an effective range of -1.0 to +1.0 inclusive, anything outside that range gets clipped. The default scale is 1.0.

(s32 rw) output-type

This emulates the output_type load-time argument to the software pwmgen component. This parameter may be changed at runtime, but most of the time you probably want to set it at startup and then leave it alone. Accepted values are 1 (PWM on Out0 and Direction on Out1), 2 (Up on Out0 and Down on Out1), 3 (PDM mode, PDM on Out0 and Dir on Out1), and 4 (Direction on Out0 and PWM on Out1, "for locked antiphase").

(bit input) offset-mode

When True, offset-mode modifies the PWM behavior so that a PWM value of 0 results in a 50% duty cycle PWM output, a -1 value results in a 0% duty cycle and +1 results in a 100% duty cycle (with default scaling). This mode is used by some PWM motor drives and PWM to analog converters. Typically the direction signal is not used in this mode.

(bit input) dither

When True, dither causes the PWM output to dither between two adjacent PWM register values at the PWM frequency. This increases the PWM resolution when used for analog output purposes, increasing the maximum resolution from 12 to 16 bits. Dither is only supported with PWMGen firmware version 1 or greater and only affects PWM outputs, not PDM outputs. In addition to the per-instance HAL Parameters listed above, there are a couple of HAL Parameters that affect all the pwmgen instances:

(u32 rw) pwm_frequency

This specifies the PWM frequency, in Hz, of all the pwmgen instances running in the PWM modes (modes 1 and 2). This is the frequency of the variable-duty-cycle wave. Its effective range is from 1 Hz up to 386 kHz. Note that the max frequency is determined by the ClockHigh frequency of the Anything IO board; the 5I25 and 7I92 both have a 200 MHz clock, resulting in a 386 kHz max PWM frequency. Other boards may have different clocks, resulting in different max PWM frequencies. If the user attempts to set the frequency too high, it will be clipped to the max supported frequency of the board. Frequencies below about 5 Hz are not terribly accurate, but above 5 Hz they're pretty close. The default pwm_frequency is 20,000 Hz (20 kHz).

(u32 rw) pdm_frequency

This specifies the PDM frequency, in Hz, of all the pwmgen instances running in PDM mode (mode 3). This is the "pulse slot frequency"; the frequency at which the pdm generator in the AnyIO board chooses whether to emit a pulse or a space. Each pulse (and space) in the PDM pulse train has a duration of 1/pdm_frequency seconds. For example, setting the pdm_frequency to 2e6 (2 MHz) and the duty cycle to 50% results in a 1 MHz square wave, identical to a 1 MHz PWM signal with 50% duty cycle. The effective range of this parameter is from about 1525 Hz up to just under 200 MHz. Note that the max frequency is determined by the ClockHigh frequency of the Anything IO board; the 5I25 and 7I92 both have a 100 MHz clock, resulting in a 100 MHz max PDM frequency. Other boards may have different clocks, resulting in different max PDM frequencies. If the user attempts to set the frequency too high, it will be clipped to the max supported frequency of the board. The default pdm_frequency is 20,000 Hz (20 kHz).

### 3ppwmgen
Three-Phase PWM generators (3pwmgens) are intended for controlling the high-side and low-side gates in a 3-phase motor driver. The function is included to support the Mesa motor controller daughter-cards but can be used to control an IGBT or similar driver directly. 3pwmgens have names like "hm2_<BoardType>.<BoardNum>.3pwmgen.<Instance>" where <Instance> is a 2-digit number. There will be num_3pwmgens instances, starting at 00. Each instance allocates 7 output and one input pins on the Mesa card connectors. Outputs are: PWM A, PWM B, PWM C, /PWM A, /PWM B, /PWM C, Enable. The first three pins are the high side drivers, the second three are their complementary low-side drivers. The enable bit is intended to control the servo amplifier. The input bit is a fault bit, typically wired to over-current detection. When set the PWM generator is disabled. The three phase duty-cycles are individually controllable from -Scale to +Scale. Note that 0 corresponds to a 50% duty cycle and this is the initialization value.

Pins:

(float input) A-value, B-value, C-value: The PWM command value for each phase, limited to +/- "scale". Defaults to zero which is 50% duty cycle on high-side and low-sidepins (but see the "deadtime" parameter).

(bit input) enable

When high the PWM is enabled as long as the fault bit is not set by the external fault input pin. When low the PWM is disabled, with both high- side and low-side drivers low. This is not the same as 0 output (50% duty cycle on both sets of pins) or negative full scale (where the low side drivers are "on" 100% of the time).

(bit output) fault

Indicates the status of the fault bit. This output latches high once set by the physical fault pin until the "enable" pin is set to high. Parameters:

(u32 rw) deadtime

Sets the dead-time between the high-side driver turning off and the low-side driver turning on and vice-versa. Deadtime is subtracted from on time and added to off time symmetrically. For example with 20 kHz PWM (50 µs period), 50% duty cycle and zero dead time, the PWM and NPWM outputs would be square waves (NPWM being inverted from PWM) with high times of 25 µs. With the same settings but 1 µs of deadtime, the PWM and NPWM outputs would both have high times of 23 µs (25 - (2X 1 µs), 1 µs per edge). The value is specified in nanoseconds (ns) and defaults to a rather conservative 5000 ns. Setting this parameter to too low a value could be both expensive and dangerous as if both gates are open at the same time there is effectively a short circuit across the supply.

(float rw) scale

Sets the half-scale of the specified 3-phase PWM generator. PWM values from -scale to +scale are valid. Default is +/- 1.0

(bit rw) fault-invert

Sets the polarity of the fault input pin. A value of 1 means that a fault is triggered with the pin high, and 0 means that a fault it triggered when the pin is pulled low. Default 0, fault = low so that the PWM works with the fault pin unconnected.

(u32 rw) sample-time

Sets the time during the cycle when an ADC pulse is generated. 0 = start of PWM cycle and 1 = end. Not currently useful to LinuxCNC. Default 0.5. In addition the per-instance parameters above there is the following parameter that affects all instances:

(u32 rw) frequency

Sets the master PWM frequency. Maximum is approx 48 kHz, minimum is 1 kHz. Defaults to 20 kHz.

### oneshot
The oneshot is a hardware one-shot device suitable for various timing, delay, signal conditioning, PWM generation, and watchdog functions. The oneshot module includes 2 timers to allow variable pulse delays for applications like phase control. Trigger sources can be software, external inputs, the DPLL timer, a built in rate generator or the other timer. Oneshots have names like "hm2_<BoardType>.<BoardNum>.oneshot.<Instance>" where <Instance> is a 2-digit number. There will be num_oneshots instances, starting at 00. Each instance allocates up to two input and two output pins.

Pins:

(float rw) width1

Sets the pulse width of timer1 in ms. Default is 1 ms (1/1000 s).

(float rw) width2

Sets the pulse width of timer2 in ms. Default is 1 ms (1/1000 s).

(float rw) filter1

Sets digital filter time constant for timer1's external trigger input Filter time is in ms. Default filter time constant time is 0.1 ms. External trigger response will be delayed by the filter time setting.

(float rw) filter2

Sets digital filter time constant for timer2's external trigger input Filter time is in ms. Default filter time constant time is 0.1 ms. External trigger response will be delayed by the filter time setting.

(float rw) rate

Sets the frequency of the built in rate generator (in Hz)

(u32 rw) trigger_select1,trigger_select2

Sets the trigger source for timer1,timer2 respectively. Trigger sources are:

```
0 Trigger disabled
1 Software trigger: triggered when hal pin swtrigger1 is true
2 External hardware: trigger
3 DPLL trigger: triggered by selected DPLL timer
4 Rate trigger: triggered by build in rate generator.
5 Timer1 trigger: triggered by timer1 output
6 Timer2 trigger: triggered by timer2 output
```

(bit rw) trigger_on_rise1,trigger_on_rise2

When true, triggers timer1, timer2 respectively on the rising edge of the trigger source.

(bit rw) trigger_on_fall1,trigger_on_fall2

When true, triggers timer1, timer2 respectively on the falling edge of the trigger source.

(bit rw) retriggerable1,retriggerable2

When true, the associated timer is retriggerable, meaning the timer will reset to full time on a trigger event even during the output pulse period. When false the timer is not retriggerable, meaning it will ignore trigger events during the output pulse period.

(bit rw) enable1,enable2

trigger enable for timer1 and timer2 respectively True to enable.

(bit rw) reset1,reset2

If true, resets timer1 and timer2 respectively, aborting any pulse in progress.

(bit ro) out1,out2

Pulse output status bits for timer1 and timer2.

(bit ro) exttrigger1,exttrigger2

External trigger input status bits for timer1 and timer2. These monitor the filtered inputs.

(bit rw) swtrigger1,swtrigger2

software trigger inputs to trigger timer1 and timer2.

### rcpwmgen
The rcpwmgen is a simple PWM generator optimized for use with standard RC servos that use pulse width to determine position. rcpwmgens have names like "hm2_<BoardType>.<BoardNum>.rcpwmgen.<Instance>" where <Instance> is a 2-digit number. There will be num_rcpwmgens instances, starting at 00. Each instance allocates a single output pin. Unlike the standard PWM generator, the rcpwmgen output is specified in width rather than duty cycle so the pulse width is independent of the operating frequency. Resolution is approximately 1/2000 for standard 1 to 2 ms range RC servos.

Pins:

(float rw) rate

Sets the master RC PWM frequency. Maximum is 1 kHz, minimum is .01 Hz. Defaults to 50 Hz.

(float rw) width

Sets the per channel pulse width in (ms/scale).

(float rw) offset

Sets the per channel pulse width offset in ms. This would be set to 1.5 ms for 1-2 ms servos for a 0 center position.

(float rw) scale

Sets the per channel pulse width scaling. For example, setting the scale to 90 and the offset to 1.5 ms would result in a position range of +-45 degrees and scale in degrees for 1-2 ms servos with a full motion range of 90 degrees.

### stepgen
stepgens have names like "hm2_<BoardType>.<BoardNum>.stepgen.<Instance>". "Instance" is a two-digit number that corresponds to the HostMot2 stepgen instance number. There are "num_stepgens" instances, starting with 00.

So, for example, the HAL pin that has the current position feedback from the first stepgen of the second 5I22 board is: hm2_5i22.1.stepgen.00.position-fb (this assumes that the firmware in that board is configured so that this HAL object is available).

Each stepgen uses between 2 and 8 IO pins. The signals on these pins depends on the step_type parameter (described below).

The stepgen representation is modeled on the stepgen software component. Each stepgen instance has the following pins and parameters:

Pins:

(float input) position-cmd

Target position of stepper motion, in arbitrary position units. This pin is only used when the stepgen is in position control mode (control-type=0).

(float input) velocity-cmd

Target velocity of stepper motion, in arbitrary position units per second. This pin is only used when the stepgen is in velocity control mode (control-type=1).

(s32 output) counts

Feedback position in counts (number of steps).

(float output) position-fb

Feedback position in scaled position units. This is similar to "counts/position_scale", but has finer than step resolution.

(float output) position-latched

latched-position in scaled position units. This is similar to "counts/position_scale", but has finer than step resolution.

(float output) velocity-fb

Feedback velocity in arbitrary position units per second.

(bit input) enable

This pin enables the step generator instance. When True, the stepgen instance works as expected. When False, no steps are generated and velocity-fb goes immediately to 0. If the stepgen is moving when enable goes False it stops immediately, without obeying the maxaccel limit.

(bit input) position-reset

Resets position to 0 when True. Useful for step/dir controlled spindles when switching between spindle and joint modes.

(bit input) control-type

Switches between position control mode (0) and velocity control mode (1). Defaults to position control (0).

(bit in/out) index-enable

When this pin is set to True, the step count (and therefore also position) are reset to zero on the next stepgen index pulse. At the same time, index-enable is reset to zero to indicate that the pulse has occurred.

(bit r/w) index-invert

If set to True, the rising edge of the index input pin triggers the position clear event (if index-enable is True). If set to False, the falling edge triggers.

(bit in/out) probe-enable

When this pin is set to True, the step count (and therefore also position) are latched on the the next stepgen probe active edge. At the same time, probe-enable is reset to zero to indicate that a latch event has occurred.

(bit r/w) probe-invert

If set to True, the rising edge of the probe input pin triggers the latch event (if probe-enable is True). If set to False, the falling edge triggers. Parameters:

(float r/w) position-scale

Converts from counts to position units. position = counts / position_scale

(float r/w) maxvel

Maximum speed, in position units per second. If set to 0, the driver will always use the maximum possible velocity based on the current step timings and position-scale. The max velocity will change if the step timings or position-scale changes. Defaults to 0.

(float r/w) maxaccel

Maximum acceleration, in position units per second per second. Defaults to 1.0. If set to 0, the driver will not limit its acceleration at all. This requires that the position-cmd or velocity-cmd pin is driven in a way that does not exceed the machine's capabilities. This is probably what you want if you are going to be using the LinuxCNC trajectory planner to jog or run G-code.

(u32 r/w) steplen

Duration of the step signal, in nanoseconds.

(u32 r/w) stepspace

Minimum interval between step signals, in nanoseconds.

(u32 r/w) dirsetup

Minimum duration of stable Direction signal before a step begins, in nanoseconds.

(u32 r/w) dirhold

Minimum duration of stable Direction signal after a step ends, in nanoseconds.

(u32 r/w) step_type

Output format, like the step_type modparam to the software stepgen(9) component: 0 = Step/Dir, 1 = Up/Down, 2 = Quadrature, 3+ = table-lookup mode. In this mode the step_type parameter determines how long the step sequence is. Additionally the stepgen_width parameter in the loadrt config string must be set to suit the number of pins per stepgen required. Any stepgen pins above this number will be available for GPIO. This mask defaults to 2. The maximum length is 16. Note that Table mode is not enabled in all firmwares but if you see GPIO pins between the stepgen instances in the dmesg/log hardware pin list then the option may be available. In Quadrature mode (step_type=2), the stepgen outputs one complete Gray cycle (00 → 01 → 11 → 10 → 00) for each "step" it takes, so the scale must be divided by 4 relative to standard step/dir. In table mode up to 6 IO pins are individually controlled in an arbitrary sequence up to 16 phases long.

(bit input) swap_step_dir

This swaps the step and direction outputs on the selected stepgen. This parameter is only available if the firmware supports this option.

(u32 r/w) table-data-N

There are 4 table-data-N parameters, table-data-0 to table-data-3. These each contain 4 bytes corresponding to 4 stages in the step sequence. For example table-data-0 = 0x00000001 would set stepgen pin 0 (always called "Step" in the dmesg output) on the first phase of the step sequence, and table-data-4 = 0x20000000 would set stepgen pin 6 ("Table5Pin" in the dmesg output) on the 16th stage of the step sequence.

(s32 r/w) hm2_XXXX.N.stepgen.timer-number (default: -1)

Sets the hm2dpll timer instance to be used to latch stepgen counts. A setting of -1 does not latch stepgen counts. A setting of 0 latches at the same time as the main hostmot2 read. A setting of 1..4 uses a time offset from the main hostmot2 read according to the dpll's timer-us setting. Typically, timer-us should be a negative number with a magnitude larger than the largest latency (e.g., -100 for a system with mediocre latency, -50 for a system with good latency). A negative number specifies latching the specified time before the nominal hostmot2 read time.

If no DPLL module is present in the FPGA firmware, or if the stepgen module does not support DPLL, then this pin is not created.

When available, this feature should typically be enabled. Doing so generally reduces following errors.

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

For full details of the smart-serial devices see sserial(9).

### BSPI
The BSPI (Buffered SPI) driver is unusual in that it does not create any HAL pins. Instead the driver exports a set of functions that can be used by a sub-driver for the attached hardware. Typically, these would be written in the "comp".

pre-processing language: see http://linuxcnc.org/docs/html/hal/comp.html or man halcompile for further details. See mesa_7i65(9) and the source of mesa_7i65.comp for details of a typical sub-driver. See hm2_bspi_setup_chan(3hm2), hm2_bspi_write_chan(3hm2), hm2_tram_add_bspi_frame(3hm2), hm2_allocate_bspi_tram(3hm2), hm2_bspi_set_read_function(3hm2) and hm2_bspi_set_write_function(3hm2) for the exported functions.

The names of the available channels are printed to standard output during the driver loading process and take the form hm2_<board name>.<board index>.bspi.<index>, e.g., hm2_5i23.0.bspi.0.

### UART
The UART driver also does not create any HAL pins, instead it declares two simple read/write functions and a setup function to be utilised by user-written code. Typically this would be written in the "comp" pre-processing language: see http://linuxcnc.org/docs/html/hal/comp.html or man halcompile for further details. See mesa_uart(9) and the source of mesa_uart.comp for details of a typical sub-driver. See hm2_uart_setup_chan(3hm2), hm2_uart_send(3hm2), hm2_uart_read(3hm2) and hm2_uart_setup(3hm2).

The names of the available uart channels are printed to standard output during the driver loading process and take the form hm2_<board name>.<board index>uart.<index>, e.g., hm2_5i23.0.uart.0.

### General Purpose I/O
I/O pins on the board which are not used by a module instance are exported to HAL as "full" GPIO pins. Full GPIO pins can be configured at run-time to be inputs, outputs, or open drains, and have a HAL interface that exposes this flexibility. I/O pins that are owned by an active module instance are constrained by the requirements of the owning module, and have a restricted HAL interface.

GPIOs have names like "hm2_<BoardType>.<BoardNum>.gpio.<IONum>". IONum is a three-digit number. The mapping from IONum to connector and pin-on-that-connector is written to the syslog when the driver loads, and it is documented in Mesa's manual for the Anything I/O boards.

So, for example, the HAL pin that has the current inverted input value read from GPIO 012 of the second 7I43 board is: hm2_7i43.1.gpio.012.in-not (this assumes that the firmware in that board is configured so that this HAL object is available).

The HAL parameter that controls whether the last GPIO of the first 5I22 is an input or an output is: hm2_5i22.0.gpio.095.is_output (this assumes that the firmware in that board is configured so that this HAL object is available).

The hm2 GPIO representation is modeled after the Digital Inputs and Digital Outputs described in the Canonical Device Interface (part of the HAL General Reference document). Each GPIO can have the following HAL Pins:

(bit out) in & in_not

State (normal and inverted) of the hardware input pin. Both full GPIO pins and IO pins used as inputs by active module instances have these pins.

(bit in) out

Value to be written (possibly inverted) to the hardware output pin. Only full GPIO pins have this pin.

Each GPIO can have the following Parameters:

(bit r/w) is_output

If set to 0, the GPIO is an input. The IO pin is put in a high-impedance state (weakly pulled high), to be driven by other devices. The logic value on the IO pin is available in the "in" and "in_not" HAL pins. Writes to the "out" HAL pin have no effect. If this parameter is set to 1, the GPIO is an output; its behavior then depends on the "is_opendrain" parameter. Only full GPIO pins have this parameter.

(bit r/w) is_opendrain

This parameter only has an effect if the "is_output" parameter is True. If this parameter is False, the GPIO behaves as a normal output pin: The IO pin on the connector is driven to the value specified by the "out" HAL pin (possibly inverted), and the value of the "in" and "in_not" HAL pins is undefined. If this parameter is True, the GPIO behaves as an open-drain pin. Writing 0 to the "out" HAL pin drives the IO pin low, writing 1 to the "out" HAL pin puts the IO pin in a high-impedance state. In this high-impedance state the IO pin floats (weakly pulled high), and other devices can drive the value; the resulting value on the IO pin is available on the "in" and "in_not" pins. Only full GPIO pins and IO pins used as outputs by active module instances have this parameter.

(bit r/w) invert_output

This parameter only has an effect if the "is_output" parameter is True. If this parameter is True, the output value of the GPIO will be the inverse of the value on the "out" HAL pin. Only full GPIO pins and IO pins used as outputs by active module instances have this parameter.

When a physical I/O pin is used by a special function, the related is_output, and is_opendrain HAL parameters are aliased to the special function. For instance, if gpio 1 is taken over by pwmgen 0's first output, then aliases like hm2_7i92.0.pwmgen.00.out0.invert_output (referring to hm2_7i92.0.gpio.001.invert_output) will be automatically created. When more than one GPIO is connected to the same special function, an extra .#. is inserted so that the settings for each related GPIO can be set separately. For example, for the firmware SV12IM_2X7I48_72, the alias hm2_5i20.0.pwmgen.00.0.enable.invert_output (referring to hm2_5i20.0.gpio.000.invert_output) and hm2_5i20.0.pwmgen.00.1.enable.invert_output (referring to hm2_5i20.0.gpio.023.invert_output) are both created.

### inm and inmux
inm/inmuxs are input debouncing modules that support hardware digital filtering of input pins. In addition to the input filtering function, the inm/inmux modules support up to 4 simple quadrature counters for MPG use. The quadrature inputs for MPG encoders 0 through 3 are inm/inmux pins 0 through 7. MPG A,B inputs use the filter time constants programmed for inputs 0..7. Each inm/inmux input pin can have a slow or fast filter constant. Filter time constants are specified in units of scan times. inms have names like "hm2_<BoardType>.<BoardNum>.inm.<Instance>". inmuxes have names like "hm2_<BoardType>.<BoardNum>.inmux.<Instance>". "Instance" is a two-digit number that corresponds to the HostMot2 inm or inmux instance number. There are "num_inms" or numx_inmuxs" instances, starting with 00.

Each instance reads between 8 and 32 input pins. inm and inmux are identical except for pin names and the physical interface.

Pins:

(bit out) input and input-not

True and inverted filtered input states.

(bit out) raw-input and raw-input-not

True and inverted unfiltered input states.

(bit in) input-slow

If True, selects the long time constant filter for the corresponding input bit, if False the short time constant is used.

(s32 out) enc0-count,enc1-count,enc2-count,enc3-count

MPG counters 0 through 3.

(bit in) enc0-reset,enc1-reset,enc2-reset,enc3-reset

Reset for MPG counters 0 through 3, count is forced to 0 if true.

Parameters:

(u32 in) scan_rate

This sets the input scan rate in Hz. Default scan rate is 20 kHz (50 µs scan period).

(u32 in) fast_scans

This sets the fast time constant for all input pins. This is the time constant used when the input-slow pin for the corresponding input is False. The range is 0 to 63 scan periods and the default value is 5 = 250 µs at the default 20 kHz scan_rate.

(u32 in) slow_scans

This sets the slow time constant for all input pins. This is the time constant used when the input-slow pin for the corresponding input is True. The range is 0 to 1023 scan periods and the default value is 500 = 25 ms at the default 20 kHz scan_rate.

(bit in) enc0_4xmode, enc1_4xmode, enc2_4xmode, and enc3_4xmode

These set the MPG encoder operating modes to 4X when True and 1X when False.

(u32 out) scan_width

This read only parameter specifies the number of inputs scanned by the module.

### led
Creates HAL pins for the LEDs on the FPGA board.

Pins:

(bit in) CR<NN>

The pins are numbered from CR01 upwards with the name corresponding to the PCB silkscreen. Setting the bit to "True" or 1 lights the LED.

### Solid State Relay
SSRs have names like "hm2_<BoardType>.<BoardNum>.ssr.<Instance>". "Instance" is a two-digit number that corresponds to the HostMot2 SSR instance number. There are "num_ssrs" instances, starting with 00.

Each instance has a rate control pin and between 1 and 32 output pins.

Pins:

(u32 in) rate

Set the internal frequency of the SSR instance, in Hz (approximate). The valid range is 25 kHz to 25 MHz. Values below the minimum will use the minimum, and values above the max will use the max. 1 MHz is a typical value, and appropriate for all Mesa cards, and is the default. Set to 0 to disable this SSR instance.

(bit in) out-NN

The state of this SSR instance's NNth output. Set to 0 to make the output pins act like an open switch (no connection), set to 1 to make them act like a closed switch.

(bit in) invert-NN

Inverts the state of this SSR instance's NNth output, defaults to 0. When invert-NN is set to 1, SSR output NN is closed when the out-NN pin is 0 and open when the out-NN pin is 1.

## OutM Simple output module
OutMs have names like "hm2_<BoardType>.<BoardNum>.OutM.<Instance>". "Instance" is a two-digit number that corresponds to the HostMot2 OutM instance number. There are "num_outms" instances, starting with 00.

Each instance has between 1 and 32 output pins.

Pins:

(bit in) out-NN

The sets the state of this OutM instance's NNth output. Normally the output pin follows the state of this pin but may be inverted by the invert-nn HAL pin.

(bit in) invert-NN

Inverts the state of the this OutM instance's NNth output, defaults to 0. When invert-NN is set to 1, OutM output NN is high when the out-NN pin is 0 and low when the out-NN pin is 1.

## xy2mod
The xy2mod is a xy2-100 galvanometer interface. It supports 16 and 18 bit data modes and includes parabolic interpolation to provide position updates between servo thread invocations.

Pins:

(float in) posx_cmd, posy_cmd

X and Y position commands. Full scale is +-posn_scale default full scale (set by posx_scale and posy_scale) is +- 1

(float out) posx_fb, posy_fb

X and Y position feedback. Full scale is +-posN_scale default full scale is +- 1. This is feedback from the interpolator not the galvanometer.

(float in) velx_cmd, vely_cmd

X and Y velocity commands in units of fullscale_position/second

(float out) velx_fb, vely_fb

X and Y velocity feedback in units of fullscale_position/second

(float in) accx_cmd, accy_cmd

X and Y acceleration commands in units of fullscale_position/second^2

(float in) posx_scale, posy_scale

This sets the full scale range of the position command and feedback, default is +- 1.0.

(bit in) enable

when False, output data is 0, all interpolator values are set to 0 and overflow flags are cleared. Must be True for normal operation.

(u32 in) controlx, controly

These set the galvanometer control bits. There 3 bits per channel in 16 bit mode but just 1 control bit in 18 bit mode, so values from 0..7 are valid in 16 bit mode but only 0 and 4 are valid in 18 bit mode.

(u32 in) commandx, commandy

These set the raw 16 bit data sent to the galvanometer in command mode.

(bit in) commandmodex, commandmodey

When set, these enable the command mode where 16 bit command data is sent to the galvanometer.

(bit in) 18bitmodex, 18bitmodey

When True, these enable the 18 bit data mode for the respective channel.

(bit out) posx-overflow, posy-overflow

When true, these indicate an attempted position move beyond the full scale value.

(bit out) velx-overflow, vely-overflow

When True, these indicate an attempted velocity update move beyond the full scale value.

(u32 out) status

Raw 16 bit return status from galvanometer.

Parameters:

(s32 in) read-timer-number

Selects the DPLL timer number for pre-read sampling of the position and velocity registers. If set to -1, pre-read sampling is disabled.

(s32 in) write-timer-number

Selects the DPLL timer number for post write update of the position and velocity registers. If set to -1, post write update is disabled.

### Watchdog
The HostMot2 firmware may include a watchdog Module; if it does, the hostmot2 driver will use it. The HAL representation of the watchdog is named "hm2_<BoardType>.<BoardNum>.watchdog".

The watchdog starts out asleep and inactive. Once you access the board the first time by running the hm2 write() HAL function (see below), the watchdog wakes up. From them on it must be petted periodically or it will bite. Pet the watchdog by running the hm2 write() HAL function.

When the watchdog bites, all the board's I/O pins are disconnected from their Module instances and become high-impedance inputs (pulled high), and all communication with the board stops. The state of the HostMot2 firmware modules is not disturbed (except for the configuration of the IO pins). Encoder instances keep counting quadrature pulses, and pwm- and step-generators keep generating signals (which are *not* relayed to the motors, because the IO pins have become inputs).

Resetting the watchdog (by clearing the has_bit pin, see below) resumes communication and resets the I/O pins to the configuration chosen at load-time.

If the firmware includes a watchdog, the following HAL objects will be exported:

Pins:

(bit in/out) has_bit

True if the watchdog has bit, False if the watchdog has not bit. If the watchdog has bit and the has_bit bit is True, the user can reset it to False to resume operation. Parameters:

(u32 read/write) timeout_ns

Watchdog timeout, in nanoseconds. This is initialized to 5,000,000 (5 milliseconds) at module load time. If more than this amount of time passes between calls to the hm2 write() function, the watchdog will bite.

### Raw Mode
If the "enable_raw" config keyword is specified, some extra debugging pins are made available in HAL. The raw mode HAL pin names begin with "hm2_<BoardType>.<BoardNum>.raw".

With Raw mode enabled, a user may peek and poke the firmware from HAL, and may dump the internal state of the hostmot2 driver to the syslog.

Pins:

(u32 in) read_address

The bottom 16 bits of this is used as the address to read from.

(u32 out) read_data

Each time the hm2_read() function is called, this pin is updated with the value at .read_address.

(u32 in) write_address

The bottom 16 bits of this is used as the address to write to.

(u32 in) write_data

This is the value to write to .write_address.

(bit in) write_strobe

Each time the hm2_write() function is called, this pin is examined. If it is True, then value in .write_data is written to the address in .write_address, and .write_strobe is set back to False.

(bit in/out) dump_state

This pin is normally False. If it gets set to True the hostmot2 driver will write its representation of the board's internal state to the syslog, and set the pin back to False.

### Setting up Smart Serial devices
See setsserial(9) for the current way to set smart-serial eeprom parameters.

## FUNCTIONS
hm2_<BoardType>.<BoardNum>.read-request

On boards with long turn around time for reads (at the time of writing, this applies only to ethernet boards), this function sends a read request. When multiple boards are used, this can reduce the servo thread execution time. In this case, the appropriate thread order would be

```
addf hm2_7i80.0.read-request
addf hm2_7i80.1.read-request
addf hm2_7i80.0.read
addf hm2_7i80.1.read

```

which causes the read request to be sent to board 1 before waiting for the response to the read request to arrive from board 0.

hm2_<BoardType>.<BoardNum>.read

This reads the encoder counters, stepgen feedbacks, and GPIO input pins from the FPGA.

hm2_<BoardType>.<BoardNum>.write

This updates the PWM duty cycles, stepgen rates, and GPIO outputs on the FPGA. Any changes to configuration pins such as stepgen timing, GPIO inversions, etc., are also effected by this function.

hm2_<BoardType>.<BoardNum>.read_gpio

Read the GPIO input pins. Note that the effect of this function is a subset of the effect of the .read() function described above. Normally only .read() is used. The only reason to call this function is if you want to do GPIO things in a faster-than-servo thread. (This function is not available on the 7I43 due to limitations of the EPP bus.)

hm2_<BoardType>.<BoardNum>.write_gpio

Write the GPIO control registers and output pins. Note that the effect of this function is a subset of the effect of the .write() function described above. Normally only .write() is used. The only reason to call this function is if you want to do GPIO things in a faster-than-servo thread. (This function is not available on the 7I43 due to limitations of the EPP bus.)

hm2_<BoardType>.<BoardNum>.trigger-encoders

This function will only appear if the firmware contains a BiSS, Fanuc or SSI encoder module and if the firmware does not contain a hm2dpll module (qv) or if the modparam contains num_dplls=0. This function should be inserted first in the thread so that the encoder data is ready when the main hm2_XXXX.NN.read function runs. An error message will be printed if the encoder read is not finished in time. It may be possible to avoid this by increasing the data rate. If the problem persists and if "stale" data is acceptable then the function may be placed later in the thread, allowing a full servo cycle for the data to be transferred from the devices. If available it is better to use the synchronous hm2dpll triggering function.

## SEE ALSO
hm2_pci(9), hm2_eth(9), hm2_spi(9), hm2_rpspi(9), hm2_7i43(9), hm2_7i90(9)

Mesa's documentation for the Anything I/O boards, at http://www.mesanet.com

## LICENSE
GPL


hypot

package: linuxcnc

title: hypot(9)

text:
# hypot(9)

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

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

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

## PINS
hypot.N.in0 float in

hypot.N.in1 float in

hypot.N.in2 float in

hypot.N.out float out

out = sqrt(in0^2 + in1^2 + in2^2)

## AUTHOR
Jeff Epler

## LICENSE
GPL


ilowpass

title: ilowpass(9)

text:
# ilowpass(9)

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

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

## DESCRIPTION
While it may find other applications, this component was written to create smoother motion while jogging with an MPG.

In a machine with high acceleration, a short jog can behave almost like a step function. By putting the ilowpass component between the MPG encoder counts output and the axis jog-counts input, this can be smoothed.

Choose scale conservatively so that during a single session there will never be more than about 2e9/scale pulses seen on the MPG. Choose gain according to the smoothing level desired. Divide the axis.N.jog-scale values by scale.

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

Update the output based on the input and parameters.

## PINS
ilowpass.N.in s32 in

ilowpass.N.out s32 out

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

## PARAMETERS
ilowpass.N.scale float rw (default: 1024)

A scale factor applied to the output value of the low-pass filter.

ilowpass.N.gain float rw (default: .5)

Together with the period, sets the rate at which the output changes. Useful range is between 0 and 1, with higher values causing the input value to be tracked more quickly. For instance, a setting of 0.9 causes the output value to go 90% of the way towards the input value in each period.

## AUTHOR
Jeff Epler

## LICENSE
GPL


integ

title: integ(9)

text:
# integ(9)

## NAME
integ - Integrator with gain pin and windup limits

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

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

## PINS
integ.N.in float in

integ.N.gain float in (default: 1.0)

integ.N.out float out

The discrete integral of 'gain * in' since 'reset' was deasserted

integ.N.reset bit in

When asserted, set out to 0

integ.N.max float in (default: 1e20)

integ.N.min float in (default: -1e20)

## AUTHOR
Jeff Epler

## LICENSE
GPL


invert

title: invert(9)

summary: Compute the inverse of the input signal

text:
# invert(9)

## NAME
invert - Compute the inverse of the input signal

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

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

## PINS
invert.N.in float in

Analog input value

invert.N.out float out

Analog output value

## PARAMETERS
invert.N.deadband float rw

The out will be zero if in is between -deadband and +deadband.

## SEE ALSO

invert(9), div2(9)

## AUTHOR
Stephen Wille Padnos

## LICENSE
GPL


joyhandle

title: joyhandle(9)

text:
# joyhandle(9)

## NAME
joyhandle - sets nonlinear joypad movements, deadbands and scales

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

## DESCRIPTION
The component joyhandle uses the following formula for a non linear joypad movements:

y = (scale * (a*x^power + b*x)) + offset

The parameters a and b are adjusted in such a way, that the function starts at (deadband,offset) and ends at (1,scale+offset).

Negative values will be treated point symmetrically to origin. Values -deadband < x < +deadband will be set to zero.

Values x > 1 and x < -1 will be skipped to ±(scale+offset). Invert transforms the function to a progressive movement.

With power one can adjust the nonlinearity (default = 2). Default for deadband is 0.

Valid values are: power >= 1.0 (reasonable values are 1.x .. 4‐5, take higher power‐values for higher deadbands (>0.5), if you want to start with a nearly horizontal slope), 0 <= deadband < 0.99 (reasonable 0.1).

An additional offset component can be set in special cases (default = 0).

All values can be adjusted for each instance separately.

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

## PINS
joyhandle.N.in float in

joyhandle.N.out float out

## PARAMETERS
joyhandle.N.power float rw (default: 2.0)

joyhandle.N.deadband float rw (default: 0.)

joyhandle.N.scale float rw (default: 1.)

joyhandle.N.offset float rw (default: 0.)

joyhandle.N.inverse bit rw (default: 0)

## AUTHOR
Paul Willutzki

## LICENSE
GPL


kins

title: kins(9)

summary: kinematics definitions for LinuxCNC

text:
# kins(9)

## NAME
kins - kinematics definitions for LinuxCNC

For additional information, see the Documents 'Advanced Topics':

Kinematics

5-Axis Kinematics

Switchable Kinematics

## SYNOPSIS
loadrt trivkins (use for most cartesian machines)

loadrt corexykins

loadrt genhexkins

loadrt genserkins

loadrt lineardeltakins (see separate manpage)

loadrt maxkins

loadrt pentakins

loadrt pumakins

loadrt rosekins

loadrt rotarydeltakins

loadrt rotatekins

loadrt scarakins

loadrt tripodkins

loadrt xyzab_tdr_kins

loadrt xyzac-trt-kins

loadrt xyzbc-trt-kins

loadrt 5axiskins

## DESCRIPTION
Rather than exporting HAL pins and functions, these components provide the forward and inverse kinematics definitions for LinuxCNC.

### trivkins - generalized trivial kinematics
Joint numbers are assigned sequentially according to the axis letters specified with the coordinates= parameter.

If the coordinates= parameter is omitted, joint numbers are assigned sequentially to every known axis letter ("xyzabcuvw").

Example: loadrt trivkins

Assigns all axis letters to joint numbers in sequence:

x==joint0, y==joint1, z==joint2

a==joint3, b==joint4, c==joint5

u==joint6, v==joint7, w==joint8

Example: loadrt trivkins coordinates=xyz

Assigns: x==joint0, y==joint1, z==joint2

Example: loadrt trivkins coordinates=xz

Assigns: x==joint0, z==joint1

Example: loadrt trivkins coordinates=xyzy

Assigns: x==joint0, y0==joint1, z==joint2, y1==joint3

The default kinematics type is KINEMATICS_IDENTITY. GUIs may provide special features for configurations using this default kinematics type. For instance, the AXIS GUI automatically handles joint and world mode operations so that the distinctions between joints and axes are not visible to the operator. This is feasible since there is an exact correspondence between a joint number and its matching axis letter.

The kinematics type can be set with the kinstype= parameter:

kinstype=1 for KINEMATICS_IDENTITY (default if kinstype= omitted)

kinstype=[b|B] for KINEMATICS_BOTH

kinstype=[f|F] for KINEMATICS_FORWARD_ONLY

kinstype=[i|I] for KINEMATICS_INVERSE_ONLY

Example: loadrt trivkins coordinates=xyz kinstype=b

Use kinstype=B (KINEMATICS_BOTH) for configurations that need to move joints independently (joint mode) or as coordinated (teleop) movements in world coordinates.

When using the axis gui with KINEMATICS_BOTH, the '$' key is used to toggle between joint and teleop (world) modes.

An axis letter may be used more than once (duplicated) to assign multiple joints to a single axis coordinate letter.

Example: coordinates=xyyzw kinstype=B

Assigns: x==joint0, y==joint1 AND joint2, z==joint3, w==joint4

The above example illustrates a gantry configuration that uses duplicated coordinate letters to indicate that two joints (joint1 and joint2) move a single axis (y). Using kinstype=B allows the configuration to be toggled between joint and world modes of operation. Homing configuration options are available to synchronize the final homing move for selected joints -- see the documentation for Homing Configuration.

NOTES for duplicated coordinates:

When duplicated coordinate letters are used, specifying KINEMATICS_BOTH (kinstype=B) allows a gui to support jogging of each individual joint in joint mode. Caution is required for machines where the movement of a single joint (in a set specified by a duplicated coordinate letter) can lead to gantry racking or other unwanted outcomes. When the kinstype= parameter is omitted, operation defaults to KINEMATICS_IDENTITY (kinstype=1) and a gui may allow jogging based upon a selected axis coordinate letter (or by a keyboard key) before homing is completed and the machine is still in joint mode. The joint selected will depend upon the gui implementation but typically only one of the multiple joints in the set will jog. Consequently, specifying KINEMATICS_BOTH is recommended as it enables support for unambiguous, independent jogging of each individual joint. Machines that implement homing for all joints (including the provisions for synchronizing the final homing move for multiple joints) may be homed at machine startup and automatically switch to world mode where per-coordinate jogging is available.

### corexykins - CoreXY Kinematics
X = 0.5*(JOINT_0 + JOINT_1)

Y = 0.5*(JOINT_0 - JOINT_1)

Z = JOINT_2

[KINS]JOINTS= must specify 3 or more joints (maximum 9)

If enabled by the number of [KINS]JOINTS= specified, JOINT_3,4,5,6,7,8 correspond to coordinates A,B,C,U,V,W respectively.

### genhexkins - Hexapod Kinematics
Gives six degrees of freedom in position and orientation (XYZABC). The location of base and platform joints is defined by HAL parameters. The forward kinematics iteration is controlled by HAL pins. (See switchkins documentation for more info)

genhexkins.base.N.x

genhexkins.base.N.y

genhexkins.base.N.z

genhexkins.platform.N.x

genhexkins.platform.N.y

genhexkins.platform.N.z

Parameters describing the Nth joint's coordinates.

genhexkins.spindle-offset

Added to all joints Z coordinates to change the machine origin. Facilitates adjusting spindle position.

genhexkins.base-n.N.x

genhexkins.base-n.N.y

genhexkins.base-n.N.z

genhexkins.platform-n.N.x

genhexkins.platform-n.N.y

genhexkins.platform-n.N.z

Parameters describing unit vectors of Nth joint's axis. Used to calculate strut length correction for cardanic joints and non-captive actuators.

genhexkins.screw-lead

Lead of strut actuator screw, positive for the right-handed thread. Default is 0 (strut length correction disabled).

genhexkins.correction.N

Current values of strut length correction for non-captive actuators with cardanic joints. genhexkins.convergence-criterion Minimum error value that ends iterations with converged solution.

genhexkins.limit-iterations

Limit of iterations, if exceeded iterations stop with no convergence.

genhexkins.max-error

Maximum error value, if exceeded iterations stop with no convergence.

genhexkins.last-iterations

Number of iterations spent for the last forward kinematics solution.

genhexkins.max-iterations

Maximum number of iterations spent for a converged solution during current session.

genhexkins.tool-offset

TCP offset from platform origin along Z to implement RTCP function. To avoid joints jump change tool offset only when the platform is not tilted.

### genserkins - generalized serial kinematics
Kinematics that can model a general serial-link manipulator with up to 6 angular joints. (See switchkins documentation for more info)

The kinematics use Denavit-Hartenberg definition for the joint and links. The DH definitions are the ones used by John J Craig in "Introduction to Robotics: Mechanics and Control" The parameters for the manipulator are defined by HAL pins. Note that this uses a convention sometimes known as "Modified DH Parameters" and this must be borne in mind when setting up the system. https://w.wiki/NcY

genserkins.A-N

genserkins.ALPHA-N

genserkins.D-N

Parameters describing the Nth joint's geometry.

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

### pentakins - Pentapod Kinematics
Gives five degrees of freedom in position and orientation (XYZAB). The location of base and effector joints is defined by HAL parameters. The forward kinematics iteration is controlled by HAL pins.

pentakins.base.N.x

pentakins.base.N.y

pentakins.base.N.z

pentakins.effector.N.r

pentakins.effector.N.z

Parameters describing the Nth effector joint's radius and axial position.

pentakins.convergence-criterion

Minimum error value that ends iterations with converged solution.

pentakins.limit-iterations

Limit of iterations, if exceeded iterations stop with no convergence.

pentakins.max-error

Maximum error value, if exceeded iterations stop with no convergence.

pentakins.last-iterations

Number of iterations spent for the last forward kinematics solution.

pentakins.max-iterations

Maximum number of iterations spent for a converged solution during current session.

pentakins.tool-offset

TCP offset from effector origin along Z to implement RTCP function. To avoid joints jump change tool offset only when the platform is not tilted.

### pumakins - kinematics for puma typed robots
Kinematics for a puma-style robot with 6 joints

pumakins.A2

pumakins.A3

pumakins.D3

pumakins.D4

Describe the geometry of the robot

### rosekins - kinematics for a rose engine using
a transverse, longitudinal, and rotary joint (3 joints)

### rotarydeltakins - kinematics for a rotary delta machine
Rotary delta robot (3 Joints)

### rotatekins - Rotated Kinematics
The X and Y axes are rotated 45 degrees compared to the joints 0 and 1.

### scarakins - kinematics for SCARA-type robots
(See switchkins documentation for more info)

scarakins.D1

Vertical distance from the ground plane to the center of the inner arm.

scarakins.D2

Horizontal distance between joint[0] axis and joint[1] axis, ie. the length of the inner arm.

scarakins.D3

Vertical distance from the center of the inner arm to the center of the outer arm. May be positive or negative depending on the structure of the robot.

scarakins.D4

Horizontal distance between joint[1] axis and joint[2] axis, ie. the length of the outer arm.

scarakins.D5

Vertical distance from the end effector to the tooltip. Positive means the tooltip is lower than the end effector, and is the normal case.

scarakins.D6

Horizontal distance from the centerline of the end effector (and the joints 2 and 3 axis) and the tooltip. Zero means the tooltip is on the centerline. Non-zero values should be positive, if negative they introduce a 180 degree offset on the value of joint[3].

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

tripodkins.Bx

tripodkins.Cx

tripodkins.Cy

The location of the three motors is (0,0), (Bx,0), and (Cx,Cy)

### xyzac-trt-kins - 5 Axis mill (Table Rotary/Tilting)
Tilting table (A) and horizontal rotary mounted to table (C axis) (5 Joints 0:x,1:y,2:z,3:a,4:c) with provisions to switch between xyzac and trivkins kinematic types. The joint mapping can be altered with the coordinates parameter in the same way as supported by trivkins. (See switchkins documentation for more info)

### xyzbc-trt-kins - 5 Axis mill (Table Rotary/Tilting)
(5 Joints 0:x,1:y,2:z,3:b,4:c) with provisions to switch between xyzbc and trivkins kinematic types. The joint mapping can be altered with the coordinates parameter in the same way as supported by trivkins. (See switchkins documentation for more info)

### 5axiskins - 5 Axis bridge mill
XYZBCW -- the W coordinate values (typically used for tool motion) are incorporated into XYZ positioning. (Only 5 joints are needed by the kinematics module but an additional joint is needed to display W values). (See switchkins documentation for more info)

By default, 5axiskins uses coordinates XYZBCW assigned consecutively to joints 0..5. The module coordinates parameter may be used to assign multiple joints to an axis letter and/or to assign joints to additional coordinates A,U,V with a one-to-one correspondence to the assigned joints. Example: XYZBCWYV (8 joints total numbered 0..7) uses two joints for Y (joints 1,6) and adds an additional coordinate V that has a one-to-one relation to joint 7.

Note: These kinematics may be used with the vismach 5axisgui providing that the joint-letter assignments agree with the default ordering expected by it (XYZBCW -> joints 0..5)

## SEE ALSO
Kinematics section in the LinuxCNC documentation

The HAL component userkins.comp is a template for making kinematic modules using the halcompile tool. The unmodified template supports an identity xyz configuration that uses 3 joints. See userkins(9) for more info.


title: knob2float(9)

text:
# knob2float(9)

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

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

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

## PINS
knob2float.N.counts s32 in

Counts

knob2float.N.enable bit in

When TRUE, output is controlled by count, when FALSE, output is fixed

knob2float.N.scale float in

Amount of output change per count

knob2float.N.out float out

Output value

## PARAMETERS
knob2float.N.max-out float rw (default: 1.0)

Maximum output value, further increases in count will be ignored

knob2float.N.min-out float rw (default: 0.0)

Minimum output value, further decreases in count will be ignored

## AUTHOR
John Kasunich

## LICENSE
GPL


latencybins

title: latencybins(9)

text:
# latencybins(9)

## NAME
latencybins - comp utility for scripts/latency-histogram

## SYNOPSIS
Usage:

Read availablebins pin for the number of bins available.

Set the maxbinnumber pin for the number of ± bins.

Ensure maxbinnumber <= availablebins

For maxbinnumber = N, the bins are numbered:

-N ... 0 ... + N bins

(the -0 bin is not populated)

(total effective bins = 2*maxbinnumber +1)

Set nsbinsize pin for the binsize (ns)

Iterate:

Set index pin to a bin number: 0 <= index <= maxbinnumber.

Read check pin and verify that check pin == index pin.

Read output pins:

pbinvalue is count for bin = +index

nbinvalue is count for bin = -index

pextra is count for all bins > maxbinnumber

nextra is count for all bins < maxbinnumber

latency-min is max negative latency

latency-max is max positive latency

If index is out of range ( index < 0 or index > maxbinnumber)

then pbinvalue = nbinvalue = -1.

The reset pin may be used to restart.

The latency pin outputs the instantaneous latency.

Maintainers note: hardcoded for MAXBINNUMBER==1000

## FUNCTIONS
latencybins.N

## PINS
latencybins.N.maxbinnumber s32 in (default: 1000)

latencybins.N.index s32 in

latencybins.N.reset bit in

latencybins.N.nsbinsize s32 in

latencybins.N.check s32 out

latencybins.N.latency s32 out

latencybins.N.latency-max s32 out

latencybins.N.latency-min s32 out

latencybins.N.pbinvalue s32 out

latencybins.N.nbinvalue s32 out

latencybins.N.pextra s32 out

latencybins.N.nextra s32 out

latencybins.N.variance s32 out

latencybins.N.availablebins s32 out (default: 1000)

## AUTHOR
Dewey Garrett

## LICENSE
GPL


lcd

title: lcd(9)

summary: Stream HAL data to an LCD screen

text:
# lcd(9)

## NAME
lcd - Stream HAL data to an LCD screen

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

## FUNCTIONS
lcd (requires a floating-point thread).

All LCD instances are updated by the same function.

## PINS
lcd.NN.out (u32) out

The output byte stream is sent via this pin. One character is sent every thread invocation. There in no handshaking provided.

lcd.NN.page.PP.arg.NN (float/s32/u32/bit) in

The input pins have types matched to the format string specifiers.

lcd.NN.page_num (u32) in

Selects the page number. Multiple layouts may be defined, and this pin switches between them.

lcd.NN.contrast (float) in

Attempts to set the contrast of the LCD screen using the byte sequence ESC C and then a value from 0x20 to 0xBF (matching the Mesa 7I73). The value should be between 0 and 1.

## PARAMETERS
lcd.NN.decimal-separator (u32) rw

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

## DESCRIPTION
lcd takes format strings much like those used in C and many other languages in the printf and scanf functions and their variants.

The component was written specifically to support the Mesa 7I73 pendant controller, however, it may be of use streaming data to other character devices and, as the output format mimics the ADM3 terminal format, it could be used to stream data to a serial device. Perhaps even a genuine ADM3. The strings contain a mixture of text values (which are displayed directly), "escaped" formatting codes and numerical format descriptors. For a detailed description of formatting codes see: http://en.wikipedia.org/wiki/Printf .

The component can be configured to display an unlimited number of differently-formatted pages, which may be selected with a HAL pin.

Escaped codes

\n Inserts a clear-to-end, carriage return and line feed character. This will still linefeed and clear even if an automatic wrap has occurred (lcd has no knowledge of the width of the lcd display). To print in the rightmost column it is necessary to allow the format to wrap and omit the \n code.

\t Inserts a tab (actually 4 spaces in the current version rather than a true tab.)

\NN inserts the character defined by the hexadecimal code NN.

As the ',' character is used in the format string to separate LCD instances it must be represented by \2C in the format string (the decimal separator is handled differently).

\\ Inserts a literal \.

Numerical formats

lcd differs slightly from the standard printf conventions. One significant difference is that width limits are strictly enforced to prevent the LCD display wrapping and spoiling the layout. The field width includes the sign character so that negative numbers will often have a smaller valid range than positive. Numbers that do not fit in the specified width are displayed as a line of asterisks (********).

Each format begins with a "%" symbol. (For a literal % use "%%"). Immediately after the % the following modifiers may be used:

" " (space) Pad the number to the specified width with spaces. This is the default and is not strictly necessary.

"0" Pad the number to the specified width with the numeral 0.

"+" Force display of a + symbol before positive numbers. This (like the - sign) will appear immediately to the left of the digits for a space-padded number and in the extreme left position for a 0-padded number.

"1234567890" A numerical entry (other than the leading 0 above) defines the total number of characters to display including the decimal separator and the sign. Whilst this number can be as many digits as required, the maximum field width is 20 characters. The inherent precision of the "double" data type means that more than 14 digits will tend to show errors in the least significant digits. The integer data types will never fill more than 10 decimal digits.

Following the width specifier should be the decimal specifier. This can only be a full-stop character (.) as the comma (,) is used as the instance separator. Currently lcd does not access the locale information to determine the correct separator but the decimal-separator HAL parameter can be used to choose any desired separator.

Following the decimal separator should be a number that determines how many places of decimals to display. This entry is ignored in the case of integer formats.

All the above modifiers are optional, but to specify a decimal precision the decimal point must precede the precision, e.g., as in "%.3f". The default decimal precision is 4.

The numerical formats supported are:

%f %F (for example, %+09.3f) These create a floating-point type HAL pin. The example would be displayed in a 9-character field, with 3 places of decimals, as a decimal separator, padded to the left with 0s and with a sign displayed for both positive and negative. Conversely a plain %f would be 6 digits of decimal, variable format width, with a sign only shown for negative numbers. Both %f and %F create exactly the same format.

%i %d (For example %+ 4d) Creates a signed (s32) HAL pin. The example would display the value at a fixed 4 characters, space padded, width including the "+" giving a range of +999 to -999. %i and %d create identical output.

%u (for example %08u) Creates an unsigned (u32) HAL pin. The example would be a fixed 8 characters wide, padded with zeros.

%x, %X Creates an unsigned (u32) HAL pin and displays the value in Hexadecimal. Both %x and %X display capital letters for digits ABCDEF. A width may be specified, though the u32 HAL type is only 8 hex digits wide.

%o Creates an unsigned (u32) pin and displays the value in octal representation.

%c Creates a u32 HAL pin and displays the character corresponding to the value of the pin. Values less than 32 (space) are suppressed. A width specifier may be used, for example %20c might be used to create a complete line of one character.

%b This specifier has no equivalent in printf. It creates a bit (boolean) type HAL pin. The b should be followed by two characters and the display will show the first of these when the pin is true, and the second when false. Note that the characters follow, not precede the "b", unlike the case with other formats. The characters may be "escaped" Hex values. For example "%b\FF " will display a solid black block if true, and a space if false and "%b\7F\7E" would display right-arrow for false and left-arrow for true. An unexpected value of 'E' indicates a formatting error.

Pages The page separator is the "|" (pipe) character (if the actual character is needed then \7C may be used). A "Page" in this context refers to a separate format which may be displayed on the same display.

Instances The instance separator is the comma. This creates a completely separate lcd instance, for example to drive a second lcd display on the second 7I73. The use of comma to separate instances is built in to the modparam reading code so not even escaped commas "\," can be used. A comma may be displayed by using the \2C sequence.

## AUTHOR
Andy Pugh

## LICENSE
GPL


title: limit1(9)

text:
# limit1(9)

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

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

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

## PINS
limit1.N.in float in

limit1.N.out float out

limit1.N.min float in (default: -1e20)

limit1.N.max float in (default: 1e20)

## AUTHOR
Jeff Epler

## LICENSE
GPL


title: limit2(9)

text:
# limit2(9)

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

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

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

## PINS
limit2.N.in float in

limit2.N.out float out

limit2.N.load bit in

When TRUE, immediately set out to in, ignoring maxv

limit2.N.min float in (default: -1e20)

limit2.N.max float in (default: 1e20)

limit2.N.maxv float in (default: 1e20)

## AUTHOR
Jeff Epler

## LICENSE
GPL


title: limit3(9)

text:
# limit3(9)

## NAME
limit3 - Follow input signal while obeying limits

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

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

## PINS
limit3.N.in float in

limit3.N.enable bit in (default: 1)

1: out follows in, 0: out returns to 0 (always per constraints)

limit3.N.out float out

limit3.N.load bit in (default: 0)

When TRUE, immediately set out to in, ignoring maxv and maxa

limit3.N.min float in (default: -1e20)

limit3.N.max float in (default: 1e20)

limit3.N.maxv float in (default: 1e20)

limit3.N.maxa float in (default: 1e7)

Max Acceleration. Note that the component becomes unstable with maxa greater than about 1e7 in a 1kHz thread

limit3.N.smooth-steps u32 in (default: 2)

Smooth out acceleration this many periods before reaching input or max/min limit. Higher values avoid oscillation, but will accelerate slightly more slowly.

## AUTHOR
John Kasunich

## LICENSE
GPL