linuxcnc-ethercat

Beckhoff EL6001 / EL6021 serial terminals

The lcec_el6021 driver supports the Beckhoff EL6001 (RS232) and EL6021 (RS422/RS485) single-channel serial interface terminals. Instead of exporting HAL pins for the serial data itself, the driver exposes the terminal’s serial port as a userspace character device via CUSE (Character Device in Userspace):

/dev/lcec-<master>-<slave>     (default, or <ttyName> modParam)

Any application that can talk to a serial port (mb2hal, pymodbus, minimalmodbus, minicom, or plain shell redirection) can use the device directly. This makes the EL6021 a practical way to attach Modbus RTU devices (VFDs, spindles, scales, …) to an EtherCAT bus without a USB-serial adapter.

<slave idx="1" type="EL6021" name="vfd">
  <modParam name="ttyName" value="lcec-vfd0"/>
</slave>

How it works

• The driver maps the EL60xx process data (control/status word plus a 22-byte data window per direction) and runs the EL60xx handshake protocol in the realtime cycle, moving bytes between the PDO window and ring buffers. The protocol logic is ported from the IgH EtherCAT Master’s ec_tty example.
• A separate non-realtime thread per terminal hosts a CUSE character device backed by those ring buffers.
• termios settings requested by the application (tcsetattr()) are parsed and applied to the terminal at runtime via SDO writes (0x8000:01 RTS/CTS, 0x8000:11 baud rate, 0x8000:15 data frame), followed by a re-initialization of the port. So the baud rate in your mb2hal INI file actually takes effect; there is no second baud configuration to keep in sync.

Requirements

• A userspace (uspace) LinuxCNC build of lcec. RTAI/kbuild builds do not support the CUSE device.
• libfuse3 >= 3.12 at build time (libfuse3-dev) and run time, and the cuse kernel module loaded (modprobe cuse). Note that Debian 11 (bullseye) ships libfuse3 3.10, so CUSE support is disabled there and only the HAL status pins are available; Debian 12 and newer work.
• lcec must run with permission to open /dev/cuse (root, as usual for rtapi applications).

If libfuse3 is not available (or too old) at build time, the driver compiles without CUSE support and only the HAL status pins are available.

Throughput

The EL6001/EL6021 transfers at most 22 bytes per process data window. At a 1 kHz servo thread this gives roughly 11 kB/s in each direction; plenty for Modbus RTU at 38400 baud (3.8 kB/s wire rate), but large register polls will take multiple servo cycles. The 22-byte window moves roughly every second cycle due to the toggle handshake.

modParams

All modParams are optional; the defaults are the sane choice for most setups (9600 8N1, no handshake). baud, dataFrame and rtsCts are startup values only: they configure the terminal before any application connects, and are overridden as soon as an application opens the character device and sets its own termios attributes (mb2hal does this from its INI on startup). Leave them out of the XML unless the port must be usable before any app configures it.

• baud (u32, default 9600): initial baud rate. One of 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200.
• dataFrame (string, default 8N1): data bits (7/8), parity (N/E/O), stop bits (1/2).
• rtsCts (bit, default 0): enable RTS/CTS hardware handshake.
• ttyName (string): name of the character device in /dev/. Default lcec-<master>-<slave>.

HAL pins

All pins are prefixed with lcec.<master>.<slave>.:

• ser-state (u32, out): protocol state machine state (3 = ready).
• ser-baud (u32, out): baud rate currently applied to the terminal (0 while not yet initialized). Reflects runtime termios changes.
• ser-rx-bytes / ser-tx-bytes (u32, out): cumulative byte counters.
• ser-rx-dropped (u32, out): bytes dropped because the RX ring buffer was full (application not reading fast enough).
• ser-cfg-error (bit, out): a runtime SDO configuration write failed.
• ser-tty-open (bit, out): an application holds the character device open.
• ser-reset (bit, in): reset the byte/drop counters.

Supported termios settings

tcsetattr() accepts any combination of: baud rates from the baud table above, 7/8 data bits, no/even/odd parity, 1/2 stop bits, and CRTSCTS. Anything else (5/6 data bits, arbitrary BOTHER baud rates) fails with EINVAL.

TIOCINQ/FIONREAD reports bytes available. TIOCMGET reports a fixed RTS|CTS|DSR|CD set; modem control and break ioctls are accepted but are no-ops (the terminal has no physical modem lines for them).

Example: Huanyang VFD via mb2hal

mb2hal.ini fragment:

[MB2HAL_INIT]
INIT_DEBUG=3
HAL_MODULE_NAME=mb2hal.vfd
SLOWDOWN=0.0
TOTAL_TRANSACTIONS=1

[TRANSACTION_0]
LINK_TYPE=serial
SERIAL_PORT=/dev/lcec-vfd0
SERIAL_BAUD=38400
SERIAL_BITS=8
SERIAL_PARITY=none
SERIAL_STOP=1
MB_SLAVE_ID=1
MB_TX_FN=6
MB_TX_ADDR=8193
NELEMENTS=1
HAL_TX_NAME=rpm-cmd
MAX_UPDATE_RATE=0.0
DEBUG=1

Test the port before configuring mb2hal; the VFD’s maximum reliable baud rate varies by model.

This site is open source. Improve this page.