histobins

title: histobins(9)

text:
# histobins(9)

## NAME
histobins - histogram bins utility for scripts/hal-histogram

## SYNOPSIS
Usage:

Read availablebins pin for the number of bins available.

Set the minvalue, binsize, and nbins pins.

Ensure nbins <= availablebins

For nbins = N, the bins are numbered: 0 ... N-1

Iterate:

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

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

Read outputs: binvalue, pextra, nextra pins.

(binvalue is count for the indexed bin)

(pextra is count for all inputs > maxvalue)

(nextra is count for all bins < minvalue)

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

then binvalue == -1.

The input-error pin is set when input rules are violated

and updates cease.

The reset pin may be used to restart.

The input used is selected based on pintype:

pintype inputpin

------- -----------

0 input

1 input-s32

2 input-u32

3 input-bit

Additional output statistics pins:

input-min

input-max

nsamples

variance

mean

The method input pin selects an alternate variance calculation.

Maintainers note: hardcoded for MAXBINNUMBER==200

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

## PINS
histobins.N.pintype u32 in

histobins.N.input float in

histobins.N.input-s32 s32 in

histobins.N.input-u32 u32 in

histobins.N.input-bit bit in

histobins.N.nbins u32 in (default: 20)

histobins.N.binsize float in (default: 1)

histobins.N.minvalue float in (default: 0)

histobins.N.index s32 in

histobins.N.check s32 out

histobins.N.reset bit in

histobins.N.method bit in

histobins.N.input-error bit out

histobins.N.binvalue float out

histobins.N.pextra float out

histobins.N.nextra float out

histobins.N.input-min float out

histobins.N.input-max float out

histobins.N.nsamples u32 out

histobins.N.variance float out

histobins.N.mean float out

histobins.N.availablebins s32 out (default: 200)

## AUTHOR
Dewey Garrett

## LICENSE
GPL


package: linuxcnc

title: hm2_7i43(9)

text:
# hm2_7i43(9)

## NAME
hm2_7i43 - LinuxCNC HAL driver for the Mesa Electronics 7i43 EPP Anything IO board with HostMot2 firmware.

## SYNOPSIS
loadrt hm2_7i43 [ioaddr=N[,N...]] [ioaddr_hi=N[,N...]] [epp_wide=N[,N...]] [config="str[,str...]"] [debug_epp=N[,N...]]

ioaddr [default: 0 (parport0)]

The base address of the parallel port. The number of ioaddr indexes/addresses given is used by the driver to determine how many boards to search for.

ioaddr_hi [default: 0]

The secondary address of the parallel port, used to set EPP mode. 0 means to use ioaddr + 0x400.

epp_wide [default: 1]

Set to zero to disable the "wide EPP mode". "Wide" mode allows a 16- and 32-bit EPP transfers, which can reduce the time spent in the read and write functions. However, this may not work on all EPP parallel ports.

config [default: ""]

HostMot2 config strings, described in the hostmot2(9) manpage.

debug_epp [default: 0]

Developer/debug use only! Enable debug logging of most EPP transfers.

## DESCRIPTION
hm2_7i43 is a device driver that interfaces the Mesa 7i43 board with the HostMot2 firmware to the LinuxCNC HAL. Both the 200K and the 400K FPGAs are supported.

The driver talks with the 7i43 over the parallel port, not over USB. USB can be used to power the 7i43, but not to talk to it. USB communication with the 7i43 will not be supported any time soon, since USB has poor real-time qualities.

The driver programs the board's FPGA with firmware when it registers the board with the hostmot2 driver. The firmware to load is specified in the config modparam, as described in the hostmot2(9) manpage, in the config modparam section.

## Jumper settings
To send the FPGA configuration from the PC, the board must be configured to get its firmware from the EPP port. To do this, jumpers W4 and W5 must both be down, ie toward the USB connector.

The board must be configured to power on whether or not the USB interface is active. This is done by setting jumper W7 up, ie away from the edge of the board.

## Communicating with the board
The 7i43 communicates with the LinuxCNC computer over EPP, the Enhanced Parallel Port. This provides about 1 MBps of throughput, and the communication latency is very predictable and reasonably low.

The parallel port must support EPP 1.7 or EPP 1.9. EPP 1.9 is preferred, but EPP 1.7 will work too. The EPP mode of the parallel port is sometimes a setting in the BIOS.

Note that the popular "NetMOS" aka "MosChip 9805" PCI parport cards do not work. They do not meet the EPP spec, and cannot be reliably used with the 7i43. You have to find another card, sorry.

EPP is very reliable under normal circumstances, but bad cabling or excessively long cabling runs may cause communication timeouts. The driver exports a parameter named hm2_7i43.<BoardNum>.io_error to inform HAL of this condition. When the driver detects an EPP timeout, it sets io_error to True and stops communicating with the 7i43 board. Setting io_error back to False makes the driver start trying to communicate with the 7i43 again.

Access to the EPP bus is not threadsafe: only one realtime thread may access the EPP bus.

## SEE ALSO
hostmot2(9)

## LICENSE
GPL


title: hm2_7i90(9)

text:
# hm2_7i90(9)

## NAME
hm2_7i90 - LinuxCNC HAL driver for the Mesa Electronics 7i90 EPP Anything IO board with HostMot2 firmware.

## SYNOPSIS
loadrt hm2_7i90 [ioaddr=N[,N...]] [ioaddr_hi=N[,N...]] [epp_wide=N[,N...]] [debug_epp=N[,N...]]

ioaddr [default: 0 (parport0)]

The base address of the parallel port. The number of ioaddr indexes/addresses given is used by the driver to determine how many boards to search for. Previously the number of config strings was used, but a blank config string is perfectly acceptable for 7i90.

ioaddr_hi [default: 0]

The secondary address of the parallel port, used to set EPP mode. 0 means to use ioaddr + 0x400.

epp_wide [default: 1]

Set to zero to disable the "wide EPP mode". "Wide" mode allows a 16- and 32-bit EPP transfers, which can reduce the time spent in the read and write functions. However, this may not work on all EPP parallel ports.

config [default: ""]

HostMot2 config strings, described in the hostmot2(9) manpage.

debug_epp [default: 0]

Developer/debug use only! Enable debug logging of most EPP transfers.

## DESCRIPTION
hm2_7i90 is a device driver that interfaces the Mesa 7i90 board with the HostMot2 firmware to the LinuxCNC HAL.

The 7i90 firmware is stored on the 7i90 itself, it is not programmed by the driver at load time. The 7i90 firmware can be changed using the mesaflash program.

The driver talks with the 7i90 over the parallel port, via EPP.

## Communicating with the board
The 7i90 communicates with the LinuxCNC computer over EPP, the Enhanced Parallel Port. This provides about 1 MBps of throughput, and the communication latency is very predictable and reasonably low.

The parallel port must support EPP 1.7 or EPP 1.9. EPP 1.9 is preferred, but EPP 1.7 will work too. The EPP mode of the parallel port is sometimes a setting in the BIOS.

Note that the popular "NetMOS" aka "MosChip 9805" PCI parport cards do not work. They do not meet the EPP spec, and cannot be reliably used with the 7i90. You have to find another card, sorry.

EPP is very reliable under normal circumstances, but bad cabling or excessively long cabling runs may cause communication timeouts. The driver exports a parameter named hm2_7i90.<BoardNum>.io_error to inform HAL of this condition. When the driver detects an EPP timeout, it sets io_error to True and stops communicating with the 7i90 board. Setting io_error back to False makes the driver start trying to communicate with the 7i90 again.

Access to the EPP bus is not threadsafe: only one realtime thread may access the EPP bus.

## SEE ALSO
hostmot2(9)

## LICENSE
GPL


title: hm2_eth(9)

text:
# hm2_eth(9)

## NAME
hm2_eth - LinuxCNC HAL driver for the Mesa Electronics Ethernet Anything IO boards, with HostMot2 firmware.

## SYNOPSIS
loadrt hm2_eth [config="str[,str...]"] [board_ip=ip[,ip...]] [board_mac=mac[,mac...]]

config [default: ""]

HostMot2 config strings, described in the hostmot2(9) manpage.

board_ip [default: ""]

The IP address of the board(s), separated by commas. As shipped, the board address is 192.168.1.121.

## DESCRIPTION
hm2_eth is a device driver that interfaces Mesa's ethernet based Anything I/O boards (with the HostMot2 firmware) to the LinuxCNC HAL. The supported boards are: 7I76E, 7I80DB, 7I80HD, 7I92, 7I93, 7I94, 7I95, 7I96, 7I96S, 7I97, 7I98. It also supports boards with the litehm2 firmware (https://github.com/sensille/litehm2). The board must have its firmware loaded on the board by the mesaflash(1) program.

hm2_eth is only available when LinuxCNC is configured with "uspace" realtime.

## INTERFACE CONFIGURATION
hm2_eth should be used on a dedicated network interface, with only a cable between the PC and the board. Wireless and USB network interfaces are not suitable.

These instructions assume your dedicated network interface is "eth1", 192.168.1/24 is an unused private network, that the hostmot2 board is using the default address of 192.168.1.121, that you are using Debian 7 or similar, and that you do not otherwise use iptables. If any of these are false, you will need to modify the instructions accordingly. After following all the instructions, reboot so that the changes take effect.

It is particularly important to check that the network 192.168.1/24 is not already the private network used by your internet router, because this is a commonly-used value. If you use another network, you will also need to reconfigure the hostmot2 card to use an IP address on that network by using the mesaflash(1) utility and change jumper settings. Typically, you will choose one of the networks in the Private IPv4 address space. One common alternative is PC address 10.10.10.1, hostmot2 address 10.10.10.10.

Use of the dedicated ethernet interface while LinuxCNC is running can cause violation of realtime guarantees. hm2_eth will automatically mitigate most accidental causes of interference.

### Configure network with static address
Add these lines to the file /etc/network/interfaces to configure eth1 with a static address:

```
auto eth1
iface eth1 inet static

    address 192.168.1.1

    hardware-irq-coalesce-rx-usecs 0
```

## PACKET LOSS
While ethernet is fairly resistant to electrical noise, many systems will not have 100% perfect packet reception. The hm2_eth driver has a limited ability to deal with lost packets. Packet loss is detected by transmitting an expected read or write packet count with each request, and checking the value with each read response. When a lost packet is detected, the packet-error pin is asserted in that cycle, the packet-error-level pin is increased, and if it reaches a threshold then a permanent low-level I/O error is signaled.

However, not all hm2 special functions know how to properly recover from lost packets. For instance, the encoder special function does not properly manage the index feature when packets are lost. The author believes that this can lead to rare failures in home-to-index, which can have severe consequences.

On the other hand, pid-stepper systems will run properly for extended periods of time with packet loss on the order of .01%, as long as following error is increased enough that having stale position feedback does not trigger a following error. Altering the HAL configuration so that during transient packet loss the pid and motion feedback value is equal to the command value, instead of the stale feedback value, appears to improve tuning. This can be accomplished with a mux2(9) component for each feedback signal, using packet-error as the mux2 sel input.

## PINS
In addition to the pins documented in hostmot2(9), hm2_eth(9) creates additional pins:

(bit, out) hm2_<BoardType>.<BoardNum>.packet-error

This pin is TRUE when the most recent cycle detected a read or write error, and FALSE at other times.

(s32, out) hm2_<BoardType>.<BoardNum>.packet-error-level

This pin shows the current error level, with higher numbers indicating a greater number of recent detected errors. The error level is always in the range from 0 to packet-error-limit, inclusive.

(bit, out) hm2_<BoardType>.<BoardNum>.packet-error-exceeded

This pin is TRUE when the current error level is equal to the maximum, and FALSE at other times.

## PARAMETERS
In addition to the parameters documented in hostmot2(9), hm2_eth(9) creates additional parameters:

(s32, rw) hm2_<BoardType>.<BoardNum>.packet-error-decrement

The amount deducted from packet-error-level in a cycle without detected read or write errors, without going below zero.

(s32, rw) hm2_<BoardType>.<BoardNum>.packet-error-increment

The amount added to packet-error-level in a cycle without detected read or write errors, without going above packet-error-limit.

(s32, rw) hm2_<BoardType>.<BoardNum>.packet-error-limit

The level at which a detected read or write error is treated as a permanent error. When this error level is reached, the board's io-error pin becomes TRUE and the condition must be manually reset.

(s32, rw) hm2_<BoardType>.<BoardNum>.packet-read-timeout

The length of time that must pass before a read request times out. If the value is less than or equal to 0, it is interpreted as 80% of the thread period. If the value is less than 100, it is interpreted as a percentage of the thread period. Otherwise, it is interpreted as a time in nanoseconds. In any case, the timeout is never less than 100 microseconds. Setting this value too low can cause spurious read errors. Setting it too high can cause realtime delay errors.

## NOTES
hm2_eth uses an iptables chain called "hm2-eth-rules-output. That technology is common to control network access to (INPUT chain), through (FORWARD chain) or from (OUTPUT chain) your computer. Someone who has configured a firewall on Linux has encountered iptables and is familiar with that technology. This chain contains additional rules to control network interface while HAL is running. The chain is created if it does not exist, and a jump to it is inserted at the beginning of the OUTPUT chain if it is not there already. If you have an existing iptables setup, you can insert a direct jump from OUTPUT to hm2-eth-rules-output in an order appropriate to your local network.

At (normal) exit, hm2_eth will remove the rules. After a crash, you can manually clear the rules with sudo iptables -F hm2-eth-rules-output; the rules are also removed by a reboot.

"hardware-irq-coalesce-rx-usecs" decreases time waiting to receive a packet on most systems, but on at least some Marvel-chipset NICs it is harmful. If the line does not improve system performance, then remove it. A reboot is required for the value to be set back to its power-on default. This requires the ethtool package to be installed.

## BUGS
Some hostmot2 functions such uart are coded in a way that causes additional latency when used with hm2_eth.

On the 7i92, the HAL pins for the LEDs are called CR01..CR04, but the silkscreens are CR3..CR6. Depending on the FPGA firmware, the LEDs may initially be under control of the ethernet engine. This can be changed until power cycle with

```
elbpcom 01D914000000
```

Depending on firmware version, this driver may cause the hardware error LED to light even though the driver and hardware are functioning normally. This will reportedly be fixed in future bitfile updates from Mesa.

## SEE ALSO
hostmot2(9), elbpcom(1)

## LICENSE
GPL


title: hm2_modbus(9)

text:
# hm2_modbus(9)

## NAME
hm2_modbus - A hostmot2 driver that implements the Modbus protocol using the PktUART ports.

## SYNOPSIS
loadrt hm2_modbus ports=... mbccbs=...

ports [default: <empty>]

A comma separated list of PktUART HAL names to use as Modbus hardware channel. Each must be matched with an MBCCB file specified in the mbccbs parameter. Example: ports="hm2_7i96s.0.pktuart.0","hm2_5i25.0.pktuart.2"

mbccbs [default: <empty>]

A comma separated list of "Modbus Command Control Binary" (MBCCB) file paths to use for each PktUART port as specified in the ports parameter. The path should be an absolute path to prevent nasty surprises. Example: mbccbs="/path/to/rly-and-spindle.mbccb","/path/to/lightsparks.mbccb"

debug [default: -1]

Set the message level of the running process. The message level is set if debug is set to a positive value between 0 and 5, where 0 means no messages at all and 5 means everything. A value of -1 does not touch the current message level. Caveat Emptor: the driver must be compiled with debug messages enabled for it to start emitting messages at the debug level. Changing the message level is process-wide and all modules within the process will spit out messages at the requested level. This may cause quite some clutter in your terminal.

## DESCRIPTION
The hm2_modbus driver implements the Modbus protocol and maps HAL pins to Modbus devices' coils, inputs and registers. The mappings may be a complex combination of types and pins. The configuration format is described in mesambccc(1).

The Mesa FPGA board must be flashed with a PktUART capable bit-file. It is recommended to use an FPGA bit-file that supports PktUART version 3 or later. The hm2_modbus driver will run with PktUART version 2, but it will lack several important bug fixes and features, like 2 stop-bits, correct and extended inter-frame delay for high speed communication and inter-character delay measurements. Warnings will be emitted if communication settings cannot be honored by the older PktUART version. PktUART versions older than 2 are not supported and the driver will abort with an error if encountered.

The driver exports a set of HAL pins and parameters that can be used to inspect status and alter some settings in a live environment.

Up to eight instances are supported, which are instantiated by setting the ports and mbccbs parameters. The instances are named hm2_modbus.0, hm2_modbus.1, etc.. The pin names generated by the driver will always be prefixed with the driver’s name.

```
loadrt hm2_modbus ports="7i96s.0.pktuart.0" mbccbs="/path/to/myfile.mbccb"
```

The driver exports one function named process, which must be added to the servo-thread after hostmot2’s read function and before hostmot2’s write function:

```
addf hm2_7i96s.0.read     servo-thread
...
# Add any functions here that process data that will be sent to
# the Modbus device(s).
...
addf hm2_modbus.0.process servo-thread
...
# Add any functions here that process data received from the
# Modbus device(s).
...
addf hm2_7i96s.0.write    servo-thread
```

There are no software limits to how many Modbus devices may share one and the same physical bus and by extension the same hm2_modbus instance. The Modbus protocol limits the number of devices to 247 (available device IDs). However, the practical limit will be effective communication speed and bus load.

### PARAMETERS
Exported parameters for driver instance N:

hm2_modbus.N.baudrate (u32, readonly)

The communication baudrate.

hm2_modbus.N.drivedelay (u32, readonly)

The transmitter wait time between enabling the transmitter and start sending in bit-times.

hm2_modbus.N.icdelay (u32, readonly)

The maximum inter-character delay accepted in received frames in bit-times. Set to zero (0) when disabled.

hm2_modbus.N.parity' (u32, readonly)

The communication parity (0=None, 1=Odd, 2=Even).

hm2_modbus.N.rxdelay (u32, readonly)

The inter-frame delay required before a packet is accepted in bit-times.

hm2_modbus.N.stopbits (u32, readonly)

The communication number of stopbits (1 or 2).

hm2_modbus.N.txdelay (u32, readonly)

The inter-frame delay inserted after a packet in bit-times.

The parameters are all read/only. There is normally no need to alter any parameters. Any tuning of values should be done in the mbccs/mbccb file.

### PINS
Each driver instance N exports the following pins to control the instance’s operation and indicate the instance’s status:

hm2_modbus.N.fault (bit, output)

Indicates a fault condition.

hm2_modbus.N.fault-command (u32, output)

The command index that caused the last fault condition.

hm2_modbus.N.last-error-code (u32, output)

The errno value of the error that caused the fault condition.

hm2_modbus.N.reset (bit, input)

Reset all commands error counters and re-enable disabled commands on the rising edge of the input pin.

hm2_modbus.N.suspend (bit, input)

Suspend all activity while set. The default can be set in the MBCCB file. Suspended start (when set in the MBCCB file) can ensure that all HAL files and commands are parsed and executed (like setp and sets commands) before Modbus communication starts. This enables you to setup scale and offset pins without bad values being pushed to the Modbus device(s). The last HAL command after setting all relevant pins and signals would be to enable Modbus communication by isssuing (replace N with actual instance number):

setp hm2_modbus.N.suspend false It may be necessary to issue a delay command as the first or last init command to ensure flushing all pins before reading pin data that will be transferred to the Modbus device(s). See also writeflush attribute in the MBCCB file.

It is possible to suspend the Modbus communication by setting the suspend pin to true in a live and running system. The suspend pin is probed every time at the end of the <commands> list and execution will become suspended if the pin is true.

Command pins

Each command in the MBCCB file (not init commands) will generate a set of pins to reflect the current state, where MM is the command number counting from zero (00):

hm2_modbus.N.command.MM.disable (bit, input)

Disable this command on the rising edge of this pin. You need to use the command’s corresponding reset pin to re-enable it.

hm2_modbus.N.command.MM.disabled (bit, output)

Set if the command is no longer sent in the commands loop.

hm2_modbus.N.command.MM.error-code (u32, output)

The errno code of the last error. The following error codes can be set:

•5, 0x05 (EIO): The receiver detected an overrun, a false start-bit or wrong parity.

•9, 0x09 (EBADF): The reply returned an unsupported function.

•11, 0x0b (EAGAIN): The command was manually disabled in the mbccb or via the disable pin.

•22, 0x16 (EINVAL): An invalid value was detected (internal error).

•27, 0x1b (EFBIG): The received data packet size exceeds the internally allocated buffer.

•34, 0x22 (ERANGE): The received data packet was too small or the message’s length indicator was wrong.

•42, 0x2a (ENOMSG): The inter-character delay was too long and the packet was dropped.

•44, 0x2c (ECHRNG): The reply had a different function than the sent function.

•52, 0x34 (EBADE): The CRC of the received packet was wrong.

•74, 0x4a (EBADMSG): The reply had the error-bit set.

•75, 0x4b (EOVERFLOW): The received packet was larger than the maximum 256 bytes.

•90, 0x5a (EMSGSIZE): The message did not fit into the maximum PDU size of 253.

•110, 0x6e (ETIMEDOUT): The command received no reply and timed out.

hm2_modbus.N.command.MM.errors (u32, output)

The number of consecutive errors seen in this command. The command will be disabled when this count reaches five (5). The value will be reset to zero (0) when the command succeeds.

hm2_modbus.N.command.MM.reset (bit, input)

Reset this command’s error counter and re-enable the command on the rising edge of the input pin. Note: Re-enabling the command will honor the writeflush setting of the command.

Each mbccb file will generate a set of pins as defined in the mbccb file. See mesambccc(1) for details.

## SEE ALSO
hostmot2(9), mesambccc(1).

## AUTHOR
This man page written by B.Stultiens, as part of the LinuxCNC project.

## REPORTING BUGS
Report bugs at https://github.com/LinuxCNC/linuxcnc/issues

## COPYRIGHT
Copyright © 2025 B.Stultiens

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


title: hm2_pci(9)

text:
# hm2_pci(9)

## NAME
hm2_pci - LinuxCNC HAL driver for the Mesa Electronics PCI-based Anything IO boards, with HostMot2 firmware.

## SYNOPSIS
loadrt hm2_pci [config="str[,str...]"]

config [default: ""]

HostMot2 config strings, described in the hostmot2(9) manpage.

## DESCRIPTION
hm2_pci is a device driver that interfaces Mesa's PCI and PC-104/Plus based Anything I/O boards (with the HostMot2 firmware) to the LinuxCNC HAL.

The supported boards are: the 5i20, 5i21, 5i22, 5i23, 5i24, and 5i25 (all on PCI); the 4i65, 4i68, and 4i69 (on PC-104/Plus), and the 3x20 (using a 6i68 or 7i68 carrier card) and 6i25 (on PCI Express).

The driver optionally programs the board's FPGA with firmware when it registers the board with the hostmot2 driver. The firmware to load is specified in the config modparam, as described in the hostmot2(9) manpage, in the config modparam section.

## SEE ALSO
hostmot2(9)

## LICENSE
GPL


title: hm2_rpspi(9)

text:
# hm2_rpspi(9)

## NAME
hm2_rpspi - LinuxCNC HAL driver for the Mesa Electronics SPI Anything IO boards, with HostMot2 firmware.

## SYNOPSIS
loadrt hm2_rpspi

config [default: ""]

HostMot2 config strings, described in the hostmot2(9) manpage.

spiclk_rate [default: 31250]

Specify the SPI clock rate in kHz. See SPI CLOCK RATES below.

spiclk_rate_rd [default: -1 (same as spiclk_rate)]

Specify the SPI read clock rate in kHz. Usually you read and write at the same speed. However, you may want to reduce the reading speed if the round-trip is too long (see SPI CLOCK RATES below).

spiclk_base [default: 400000000]

This is the SPI clock divider calculation fallback value. Usually, the base rate is read from /sys/kernel/debug/clk/vpu/clk_rate and used in the divider calculation (for the Rpi3 it should be 250 MHz). The spiclk_base is only used as a fallback if the system's cannot be read. It is normally safe (and recommended) that you leave this parameter as is.

You should set this manually to 250000000 if your system does not provide access to the kernel clock settings. Otherwise, your SPI clock frequency will be only 62.5% of the requested value.

spi_pull_miso [default: 1 (pull-down)]

spi_pull_mosi [default: 1 (pull-down)]

spi_pull_sclk [default: 1 (pull-down)]

Enable or disable pull-up/pull-down on the SPI lines. A value of 0 disables any pull-up/down on the pin. A value of 1 means pull-down and 2 means pull-up. The chip enable line(s) are always pull-up enabled.

spi_probe [default: 1]

Probe SPI port and CE lines for a card. This is a bit-field indicating which combinations of SPI and CE should be probed:

- 1 = SPI0/CE0,

- 2 = SPI0/CE1,

- 4 = SPI1/CE0,

- 8 = SPI1/CE1,

- 16 = SPI1/CE2. The probe is performed exactly in above order. Any boards found will be numbered 0...4 in the order found. See also INTERFACE CONFIGURATION below.

It is an error if a probe fails and the driver will abort. The SPI0/SPI1 peripherals are located at GPIO pins (with 40-pin I/O header pin-number in parentheses):

- SPI0: MOSI=10(19), MISO=9(21), SCLK=11(23), CE0=8(24), CE1=7(26)

- SPI1: MOSI=20(38), MISO=19(35), SCLK=21(40), CE0=18(12), CE1=17(11), CE2=16(36)

spi_debug [default: -1]

Set the message level of the running process. The message level is set if spi_debug is set to a positive value between 0 and 5, where 0 means no messages at all and 5 means everything. A value of -1 does not touch the current message level. Caveat Emptor: changing the message level is process-wide and all modules within the process will spit out messages at the requested level. This may cause quite some clutter in your terminal.

## DESCRIPTION
hm2_rpspi is a device driver for the Raspberry Pi 2/3 that interfaces Mesa's SPI based Anything I/O boards (with the HostMot2 firmware) to the LinuxCNC HAL. This driver is not based on the linux spidev driver, but on a dedicated BCM2835-SPI driver.

It is strongly recommended that you unload/disable the kernel's spidev driver by disabling it using raspi-config. Please note that having both kernel and user-space SPI drivers installed can result in unexpected interactions and system instabilities.

The supported boards are: 7I90HD.

The board must have a compatible firmware (ie.: 7i90_spi_svst4_8.bit) loaded on the board by the mesaflash(1) program.

hm2_rpspi is only available when LinuxCNC is configured with "uspace" realtime. It works with Raspian and PREEMPT_RT kernel.

## INTERFACE CONFIGURATION
Up to five devices (7i90 boards) are supported. Two on SPI0 and three on SPI1. It is recommended that you, at most, use two devices and each device connected to a separate SPI port. You can choose which CE lines you prefer or fit the design and setup the spi_probe parameter to instruct the driver where to search for the board(s).

## REALTIME PERFORMANCE OF THE BCM2835-SPI DRIVER
TBD.

## SPI CLOCK RATES
The maximum SPI clock of the BCM2835-SPI driver and the 7i90 is documented over 32MHz. The SPI driver can provide frequencies well beyond what is acceptable for the 7i90. A safe value to start with would be 12.5 MHz (spiclk_rate=12500) and then work your way up from there.

The SPI driver generates (very) discrete clock frequency values, especially in the MHz range because of a simple clock divider structure. The base frequency is 250 MHz and the divider for SPI0/SPI1 scales using discrete factors. The following list specifies the spiclk_rate setting and the discrete SPI clock frequency (250 MHz / (2n) for n > 1):

- 62500 - 62.500 MHz,

- 41667 - 41.667 MHz,

- 31250 - 31.250 MHz,

- 25000 - 25.000 MHz,

- 20834 - 20.833 MHz,

- 17858 - 17.857 MHz,

- 15625 - 15.625 MHz,

- 13889 - 13.889 MHz,

- 12500 - 12.500 MHz,

- 11364 - 11.364 MHz,

- 10417 - 10.417 MHz,

- 9616 - 9.615 MHz,

- ....

The lowest selectable SPI clock frequency is 30 kHz (spiclk_rate=30) for SPI0 and SPI1. Theoretically, the SPI0 port could go slower, but there is no point in doing so. You should not expect any real-time performance with such slow setting, unless your machine is located next to a black hole.

The highest SPI clock frequency is, theoretically, 125 MHz. However, you will not be able to build any reliable hardware interface at that frequency. The driver limits the clock to 62.5 MHz (cpiclk_rate=62500). The chances are rather slim that you get the interface to work reliably at this frequency. The 7i90 interface only supports frequencies up to 50 MHz and that is with perfect cabling and impedance matching (in write direction only).

Writing to the 7i90 may be done faster than reading. This is especially important if you have "long" wires or any buffers on the SPI-bus path. You can set the read clock frequency to a lower value (using spiclk_rate_rd) to counter the effects of the SPI-bus round-trip needed for read actions. For example, you can write at 41.67 MHz and read at 25.00 MHz.

It should be noted that the Rpi3 must have an adequate 5V power supply and the power should be properly decoupled right on the 40-pin I/O header. At high speeds and noise on the supply, there is the possibility of noise throwing off the SoC's PLL(s), resulting in strange behaviour.

For optimal performance on the Rpi3, you must disable the "ondemand" CPU frequency governor. You may add the following to your /etc/rc.local file:

echo -n 1200000 > /sys/devices/system/cpu/cpufreq/policy0/scaling_min_freq

echo -n performance > /sys/devices/system/cpu/cpufreq/policy0/scaling_governor

Be sure to have a proper heatsink mounted on the SoC or it will get too warm and crash.

## SEE ALSO
hostmot2(9)

## LICENSE
GPL


title: hm2_spi(9)

text:
# hm2_spi(9)

## NAME
hm2_spi - LinuxCNC HAL driver for the Mesa Electronics SPI Anything IO boards, with HostMot2 firmware.

## SYNOPSIS
loadrt hm2_spi [config="str[,str...]"] [spidev_path=path[,path...]] [spidev_rate=rate[,rate...]]

config [default: ""]

HostMot2 config strings, described in the hostmot2(9) manpage.

spidev_path [default: "/dev/spidev1.0"]

The path to the spi device node, a character special device in /dev

spidev_rate [default: 24000]

The desired rate of the SPI clock in kHz. If the exact specified clock is not available, a lower clock is used. Due to shortcomings in the spidev API, it is not possible for hal to report the actual clock used.

## DESCRIPTION
hm2_spi is a device driver that interfaces Mesa's SPI based Anything I/O boards (with the HostMot2 firmware) to the LinuxCNC HAL.

The supported boards are: 7I90HD.

The board must have a compatible firmware loaded on the board by the mesaflash(1) program.

hm2_spi is only available when LinuxCNC is configured with "uspace" realtime.

## INTERFACE CONFIGURATION
It is possible for one SPI bus to connect several devices; in this configuration, a master device has several chip select lines. In order to meet realtime deadlines, hm2_spi should be used on a dedicated SPI interface not shared with any other slaves.

## REALTIME PERFORMANCE OF LINUX SPIDEV DRIVERS
As of kernel 3.8, most or all kernel SPI drivers do not achieve the high realtime response rate required for a typical LinuxCNC configuration. The driver was tested with a modified version of the spi-s3c64xx SPI driver on the Odroid U3 platform. The patched kernel resides on github.

## SPI CLOCK RATES
The maximum SPI clock of the 7i90 is documented as 50MHz. Other elements of the data path between HAL and the 7i90 may impose other limitations.

## SEE ALSO
hostmot2(9)

## LICENSE
GPL


title: hm2_spix(9)

text:
# hm2_spix(9)

## NAME
hm2_spix - LinuxCNC HAL driver for the Mesa Electronics Anything IO boards with SPI enabled HostMot2 firmware.

## SYNOPSIS
loadrt hm2_spix

config [default: ""]

HostMot2 config strings, described in the hostmot2(9) manpage.

spiclk_rate [default: 25000]

Specify the SPI clock rate in kHz for each probed board. See SPI CLOCK RATES below. Each entry follows the spi_probe setting, where each probe takes the next value of the spi_rate list. A spi_rate of 0 (zero) or less automatically selects the first rate in the list. You may truncate the list to the number of boards you use.

spiclk_rate_rd [default: same as spiclk_rate]

Specify the SPI read clock rate in kHz. Usually you read and write at the same speed. However, you may want to reduce the reading speed if the round-trip is too long (see SPI CLOCK RATES below). You may truncate the list to the number of boards you use.

spi_probe [default: 1]

Probe SPI port and CE lines for a card. This is a bit-field indicating which combinations of SPI and CE should be probed: - 1 = SPI0/CE0, - 2 = SPI0/CE1, - 4 = SPI1/CE0, - 8 = SPI1/CE1, - 16 = SPI1/CE2. The probe is performed exactly in above order. Any boards found will be numbered 0...4 in the order found. It is an error if a probe fails and the driver will abort. See also INTERFACE CONFIGURATION below.

force_driver [default: <auto probe>]

Force a specific hardware driver to be selected. This is usually not necessary and the hm2_spix driver will normally select the appropriate hardware driver automatically. See also HARDWARE DRIVERS below.

spidev_path [default: <empty>]

Override the device node path to the spidev device. Default is /dev/spidevX.Y, where X.Y is {0.0, 0.1, 1.0, 1.1, 1.2} in that order. This option has only effect if the spix_spidev hardware driver is selected or forced to be used.

spi_noqueue [default: 0 (off)]

Force disable queued command processing. Normally, all requests are queued if requested by upstream and sent in one bulk transfer. This reduces overhead significantly by up to 35%. Disabling the queue makes each transfer visible and more easily debug-able. Set to any non-zero value to disable the queue.

spi_debug [default: -1]

Set the message level of the running process. The message level is set if spi_debug is set to a positive value between 0 and 5, where 0 means no messages at all and 5 means everything. A value of -1 does not touch the current message level. Caveat Emptor: changing the message level is process-wide and all modules within the process will spit out messages at the requested level. This may cause quite some clutter in your terminal.

## DESCRIPTION
hm2_spix is a device driver for all computer boards with an available SPI port, including Raspberry Pi 3, 4 and 5. The SPI port interfaces with Mesa’s SPI based Anything I/O boards with SPI enabled HostMot2 firmware to the LinuxCNC HAL.

This driver unifies all previous hostmot2 SPI hal drivers in one with dedicated hardware drivers for Raspberry Pi models 3, 4 and 5 and has a fall-back to spidev for unknown boards. Further hardware drivers may be created and integrated when requested.

The supported Mesa boards are: 7I90HD, 7I43, 7C80 and 7C81.

The board must have a compatible firmware (like: 7i90_spi_*-bit, 7c80_*.bit and 7c81_*.bit) loaded on the board by the mesaflash(1) program.

hm2_spix is only available when LinuxCNC is configured with "uspace" realtime. It works with Raspian and PREEMPT_RT kernel.

See also NOTES below.

## HARDWARE DRIVERS
The following hardware drivers are implemented and probed in order:

Driver

Board

spix_rpi3

RPi3B, RPi3A+, RPi3B+, RPi4B, RPi4CM

spix_rpi5

RPi5B, RPi5CM

spix_spidev

Any board not recognised

Probing the hardware is implemented by matching known computer boards against the device-tree compatible string-list from /proc/device-tree/compatible. Normally, the first hardware driver giving a match will be selected. However, it is possible to force a specific driver to be used using the force_driver option with the name of the driver you want to use.

## INTERFACE CONFIGURATION
Up to five device boards are supported. Two on SPI0 and three on SPI1. It is recommended that you, at most, use two devices and each device connected to a separate SPI port. You can choose which CE lines you prefer or fit your design and setup. Use the spi_probe parameter to instruct the driver where to search for the board(s).

For the Mesa 7C80 and 7C81 you’ll always want to configure SPI0/CE0. These boards have a matching 40-pin header for the computer board.

The SPI ports are located on the 40-pin header for those computer boards with a compatible header. The GPIO numbers are only guaranteed to be valid for Raspberry Pi boards.

Port SPI0:

Pin

GPIO

40-pin

Devname

MOSI

10

19

MISO

9

21

SCLK

11

23

CE0

8

24

/dev/spidev0.0

CE1

7

26

/dev/spidev0.1

Port SPI1:

Pin

GPIO

40-pin

Devname

MOSI

20

38

MISO

19

35

SCLK

21

40

CE0

18

12

/dev/spidev1.0

CE1

17

11

/dev/spidev1.1

CE2

16

36

/dev/spidev1.2

## REALTIME PERFORMANCE OF THE HM2_SPIX DRIVER
Using a RPi3 will work, but is not the best option. Currently, the RPi4 is known to work adequately. The newer RPi5 is a lot faster and will normally run a servo-thread at 1 kHz without problems.

All other computer boards and LinuxCNC configurations need to be tested thoroughly.

All other parameters: TBD.

## SPI CLOCK RATES
The SPI driver can provide frequencies beyond what is acceptable for any board. A safe value to start with would be 12.5 MHz (spiclk_rate=12500) and then work your way up from there.

The SPI driver generates (very) discrete clock frequencies, especially in the high MHz range because of a simple clock divider structure. The base frequency is different between boards and the divider for SPI0/SPI1 scales using discrete factors with formula f=trunc(base/(2*divider)). The following list specifies the highest possible spiclk_rate and spiclk_rate_rd frequencies (in kHz) for discrete divider settings:

RPi3

RPi4

RPi5

Base

400 MHz

500 MHz

200 MHz

Fastest

50000

50000

50000

40000

41666

33333

33333

35714

25000

28571

31250

20000

25000

27777

16666

22222

25000

14285

20000

22727

12500

18181

20833

11111

16666

19230

10000

15384

17857

9090

...

...

...

Slowest

SPI0:4

SPI0:4

SPI0:4

Slowest

SPI1:49

SPI1:62

SPI1:4

Note that the clock rate setting is heavily influenced by rounding and may be higher than expected if the divider rounds to the next lower value. You can check the actual clock rate by enabling informational messages (set spi_debug=3).

The slowest selectable SPI clock frequency for SPI0 and SPI1 are not for production systems. They can be selected for testing purposes. You should not expect any real-time performance with such slow setting.

The highest theoretically possible SPI clock frequency is higher than stated in the above table. However, you will not be able to build any reliable hardware interface at that frequency. The driver limits the clock to 50.0 MHz (cpiclk_rate=50000). The Mesa board interface supports frequencies up to 50 MHz and that is with good cabling in write direction only.

Writing to the Mesa board may be done faster than reading. This is especially important if you have "long" wires or any buffers on the SPI-bus path. You can set the read clock frequency to a lower value (using spiclk_rate_rd) to counter the effects of the SPI-bus round-trip needed for read actions. For example, you can write at 33.33 MHz and read at 25.00 MHz.

The maximum SPI clock of the spix_rpi5 driver has been tested up to 50 MHz write speed and 33 MHz read speed on the 7C80 and 7C81. However, it is not recommended to run at the limit on production systems. A safe setting would be to set one step below the maximum speeds.

## NOTES
If you know your setup and do not require the spix_spidev driver, then it is strongly recommended that you unload/disable the kernel’s SPI drivers dw_spi and dw_spi_mmio for the RPi5 or spi_bmc2835 for the RPi3 and RPi4. The hm2_spix hardware drivers attempt to unload the kernel driver at startup if detected and restore it at exit if initially loaded. However, there are no guarantees about the effectiveness of the module unload/load actions.

Warning: having both kernel and user-space SPI drivers installed can result in unexpected interactions and system instabilities.

The Raspberry Pi must have an adequate power supply. At high speeds and noise on the supply, there is the possibility of strange behaviour if the noise gets out of hand.

The Mesa 7C80 provides enough local power to the host via the 40-pin interface header if your external power supply is adequate (on connector TB6). The Mesa 7C81 needs an adequate external 5V power supply (on connector TB1) and feeds it directly to the host interface header.

For the Raspberry Pi 4: Be sure to have a proper heat-sink mounted on the SoC or it will get too warm and may crash.

For the Raspberry Pi 5: Be sure to have a proper active heat-sink mounted on the SoC or it will get too warm and may crash.

## SEE ALSO
hostmot2(9)

## LICENSE
GPL


homecomp

title: homecomp(9)

summary: homing module template

text:
# homecomp(9)

## NAME
homecomp - homing module template

## SYNOPSIS
Custom Homing module loaded with [EMCMOT]HOMEMOD=homecomp

## DESCRIPTION
Example of a homing module buildable with halcompile. Demonstrates required code for #includes, function definitions, etc.

If HOMING_BASE is #defined and points to a valid homing.c file, an example of a customized homing module is built. This module creates input hal pins joint.n.request-custom-homing that enable an alternate joint homing state machine for requested joints. A hal output pin joint.N.is_custom-homing verifies selection"

The customized homing module utilizes many of the base homing api routines from homing.c without modification but augments other base functions to add support for custom hal pins and custom joint homing state machines. A user-built module will likely replace additional api functions or augment them with other customizations.

If HOMING_BASE Is not #defined, an actual homing scheme is not implemented but all necessary functions are included as skeleton code. (All joints are effectively homed at all times and cannot be unhomed).

See the source code file: src/emc/motion/homing.c for the baseline implementation that includes all functions for the default homemod module.

To avoid updates that overwrite homecomp.comp, best practice is to rename the file and its component name (example: user_homecomp.comp, user_homecomp).

The (renamed) component can be built and installed with halcompile and then substituted for the default homing module (homemod) using:

$ linuxcnc -m user_homecomp someconfig.ini

or by inifile setting: [EMCMOT]HOMEMOD=user_homecomp

Note:If using a deb install:

1) halcompile is provided by the package linuxcnc-dev

2) This source file for BRANCHNAME (master,2.9,etc) is downloadable from github:

https://github.com/LinuxCNC/linuxcnc/blob/BRANCHNAME/src/hal/components/homecomp.comp

## PINS
homecomp.N.is-module bit out (default: 1)

## AUTHOR
Dewey Garrett

## LICENSE
GPL