HM2_ETH(9)

💖 HM2_ETH 💖

okay bestie, we're doing a HAL component today — this is the hm2_eth(9) page and it's genuinely iconic. It's the LinuxCNC HAL driver for Mesa Electronics Ethernet Anything IO boards running HostMot2 firmware. Yes, ethernet. Yes, it slays. Let's go ✨

---

🌸 NAME 🌸

hm2_eth — LinuxCNC HAL driver for the Mesa Electronics Ethernet Anything IO boards, with HostMot2 firmware. That's the whole vibe. 🫶

---

✨ SYNOPSIS ✨

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

• config [default: ""] — HostMot2 config strings, and the whole rundown lives in the hostmot2(9) manpage. Go read that one too, bestie.
• board_ip [default: ""] — the IP address of the board(s), separated by commas. As shipped, the board address is 192.168.1.121. 📬

ngl, board_mac is up there in the synopsis too — it's the mac address list, comma separated, same energy as board_ip. 👑

---

🦋 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. Literally its whole job. 💅

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). And listen — the board must have its firmware loaded on the board by the mesaflash(1) program. No firmware, no vibes. 🚫

hm2_eth is only available when LinuxCNC is configured with "uspace" realtime. That's the requirement, periodt.

---

🌈 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. I said what I said. 🧚

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, so it's got your back. 🫶

🎀 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

slay, that's the whole config. ✨

---

💀 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 — and this is the important part — 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. 😭 Not the vibe.

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. chef's kiss 👑

---

⭐ 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. Pick your poison, bestie. 😭

---

🔥 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. fingers crossed fr fr 🤞

---

🌟 SEE ALSO 🌟

hostmot2(9), elbpcom(1)

---

👑 LICENSE 👑

GPL

---

okay that's the whole thing, no cap 💖 this page came from the LinuxCNC Documentation, dated 2008-05-13, and you already know it's filed under HM2_ETH(9) — the 9 means kernel/dev driver section, iykyk. go wire something up and slay, bestie 🎀✨🦋