250223 Rpi5 LinuxCNC install for Marco Reps inspired controller box Shem Johnson, 2025 Alternative title: One noob’s journey to an Ethercat LinuxCNC machine This guide is to help others who are also intrigued by ethercat builds on LinuxCNC, especially beginners like me. It can be easier to adapt a working config than create a new one, especially since ethercat builds do not have a wizard setup workflow. This guide will go through the installation process and steps to remove unneccesary files and code that would throw errors. Shout out to Dbrown11 for the Cia402 work, Marco Reps for doing what he does, and Andy Pugh who helped with the LinuxCNC issues, and RodW for doing amazing work to get it all going in LinuxCNC. Note: Use document -> line wrapping --------------- --------------- Basic Hardware --------------- --------------- Rpi 5, Rpi 5 specific 5V 5A power supply, Waveshare 27541 Ethernet + USB 3.2 PCIe HAT. The Pi needs an active cooling fan Note: Use a V30 high endurance sd card to minimize corrupted files. V10 speeds feel quite slow in comparison to V30. Can recommend Samsung 128gb pro endurance microSD card 128gb is overkill on storage but the smallest capacity that has v30 speeds. Works very well for me. Note: A 5V 3A power supply was not enough to supply the pi, HAT, and peripherals and when the CPU bogged down there would be a hard reset. The pi is very susceptible to voltage drops. Maybe why the Rpi power supply is 5.1v and not 5v? The pi5 uses a weird PD standard and uses a proprietary power supply that comms an ok to use 5A. Normal power supplies will be limited to 3A. There is a HAT (PD Power Extension Board for Raspberry Pi 5 from company 52pi) that might work, though you have to go through a 4mm x 1.7mm adapter. I simply plugged the official power supply extension lead and wired that inside the box. --------------- --------------- LinuxCNC install --------------- --------------- Main source for install: https://forum.linuxcnc.org/ethercat/45336-ethercat-installation-from-repositories-how-to-step-by-step ---- Image SD card Download and install Raspberry pi imager from https://downloads.raspberrypi.org/imager/imager_latest.exe Note: As of 17/04/2025, any 6.12 based Rpi image is still incompatible with Ethercat. This includes the newest release 2.9.4 and older images at the index of /iso ( https://www.linuxcnc.org/iso/ ) Download from this google drive (RodW) https://drive.google.com/file/d/127ibNkPRNx4Nw75wXp0th-XxiwRSNUuV/view?usp=sharing Discussed in this thread post. https://forum.linuxcnc.org/9-installing-linuxcnc/51175-linuxcnc-2-9-2-and-2-93-images-for-raspberry-pi-4b-5 The file name is rpi-5-debian-bookworm-6.6.44-rt39-arm64-ext4-2024-08-12-2032.img.xz Choose pi5, then for Choose OS, scroll to use custom and select the img above. Keep things default ---- Add file structue Open the LinuxCNC application and click ok to open an Axis sample configuration. This is an easy way to create the folders used by LinuxCNC /home/cnc/linuxcnc/configs is where the magic happens. Machines configuration goes here. /home/cnc/linuxcnc/nc_files is the default location for storing g-code, subroutines, and user-defined M-codes. ---- System menu Add a wifi-network, change the default password, and change time zone. In a terminal window, type: sudo menu-config ---- Update LinuxCNC Connect the Rpi to the internet. Open a terminal window sudo apt update sudo apt-get update ---- Install ethercat sudo apt install linuxcnc-ethercat ---- Get Ethernet NIC MAC address for Ethercat Note: if multiple Ethernet NICs are used, i.e. with a HAT, ensure that the one you use to connect to Ethercat devices is the one you add to the file. Normally, eth0 should be the Rpi ethernet port. Use that. ip a sudo geany /etc/ethercat.conf Change: MASTER0_DEVICE="" DEVICE_MODULES="” Note: device modules is a scroll down, should be in blue To: MASTER0_DEVICE="YOURMACADDRESS" DEVICE_MODULES="generic” Then save and close ---- Start Ethercat service sudo systemctl enable ethercat.service sudo systemctl start ethercat.service sudo systemctl status ethercat.service sudo chmod 666 /dev/EtherCAT0 Check if ethercat devices are connected ethercat slaves Should see operational status and the names of the connected devices ---- Set Ethercat port permissions on startup sudo geany /etc/udev/rules.d/99-ethercat.rules Add line: KERNEL=="EtherCAT[0-9]", MODE="0777" Save and exit sudo udevadm control --reload-rules Then reboot Pi ---- Install cia402 for drivers Note: The CiA 402 profile is meant to define the behavior of inverters and servo drives and is based on the CANopen protocol. Make a folder called dev in home/cnc/linuxcnc mkdir /home/cnc/linuxcnc/files cd /home/cnc/linuxcnc/files/ git clone https://github.com/dbraun1981/hal-cia402 cd hal-cia402 sudo halcompile --install cia402.comp ---- Get motion & homing files Make a folder for your motion files mkdir /home/cnc/linuxcnc/files/motion Go to https://github.com/LinuxCNC/linuxcnc/tree/master/src/emc/motion And download the Raw file of homing.h, homing.c, and motion.h Move them to /home/cnc/linuxcnc/files/motion ---- Get Marco Reps files cd /home/cnc/linuxcnc/files git clone https://github.com/marcoreps/linuxcnc_leadshine_EL8.git Copy the folder to /home/cnc/linuxcnc/configs Note: Leave the config name alone for now. Change it later if you wish so the code below works ---- Check ethercat configuration cd/home/cnc/linuxcnc/configs/linuxcnc_leadshine_EL8 halcmd loadusr -W lcec_conf ethercat-conf.xml halcmd show pin lcec should see something like this: Owner Type Dir Value Name 4 u32 OUT 0x00000001 lcec.conf.master-count 4 u32 OUT 0x00000004 lcec.conf.slave-count ---- Change HOMEBASE of homing.c With the file manager, got to your config folder and open EL8/el8_homecomp.comp change line 58 from #define HOMING_BASE /home/cnc/linuxcnc-dev/src/emc/motion/homing.c to #define HOMING_BASE /home/cnc/linuxcnc/files/motion/homing.c save and close ---- Compile homing files. NOTE of unclarity: Im not sure why Marco has two homing files, always_homed.comp and el8_homecomp.comp but he has absolute encoders so I believe he is using one to home and the second to go to the homed position without actually homing. If you have absolute encoders, compile both files. Then have two configs. For the second config, in EL8_machine.ini change HOMEMOD=always_homed to HOMEMOD=el8_homecomp.comp, and open that config if you want to home. He also has homing commented out on each drive in HAL. perhaps in a second config, he has these uncommented. To be determined. cd /home/cnc/linuxcnc/files/linuxcnc_leadshine_EL8/ sudo halcompile --install el8_homecomp.comp sudo halcompile --install always_homed.comp ---- Check Jitter Open application -> CNC -> latency test Run a test. The important number is the max jitter of the base thread. Should be no problem on a Pi 5. Without opening any other programs, should be getting something loosely similar to 7000ns servo and 14000 for base. Now try to open a couple of youtube videos and bog down the system by rapidly moving windows around, etc. I got a max jitter of 24000 so around that is fine. The servo max jitter was 15000. --------------- --------------- My Config --------------- --------------- Note: This is a walkthrough of my installation and issues along the way. May or may not be useful but I hope it captures some of the logic behind the changes. I am building a Marco Reps Clone, EL8 drivers and servos with absolute encoders, dual Y gantry system and am using an RS components VFD rebrand (RS510) of the Teco Westinghouse L510 communicating over RS485. There are files to support this VFD over RS485. ---- Fix driver stuck on preop issue: info source: https://forum.linuxcnc.org/10-advanced-configuration/54608-leadshine-el8-servo-drives-ethercat#315703 The PID numbers given by Leadshine for this drive appear to be out of date. Check if ethercat-conf.xml has the correct PID numbers With the ethercat devices connected to the Pi and ethercat running, check the PID numbers with: ethercat slaves -v Open ethercat-conf.xml and crosscheck. pid="0010c2" had to be changed to pid="0000d0" for each EL8 Servo drivers. ---- Keep Pendant files Purchased an xhc-whb04b pendant Note: This pendant works great. It is a rattmmotor WHB04B 4 axis wireless pendant. Not sure about knockoffs so maybe buy direct from rattmmotor. If you don't need the pendant: Delete xhc-whb04b.hal. Then in EL8_machine.ini, comment out or delete the line HALFILE = xhc-whb04b.hal ---- Remove unneeded code from HAL file Note: If you aren't rolling in money or get free toys from badass spindle companies, you'll have to remove the spindle from the config. This spindle is an ethercat spindle Delete servospindle.comp, Metronix_ARS2310FS_modified_eeprom.sii, Metronix_ARS2310FS_modified_ESI.xml and 2024-10-04_metronix_config.dco In EL8_machine.HAL Deleted lines specific to his spindle loadrt servospindle loadrt near loadrt dbounce loadrt conv_s32_float count=7 addf servospindle.0 servo-thread addf mult2.1 servo-thread addf mult2.2 servo-thread addf dbounce.0 servo-thread addf near.0 servo-thread addf conv-s32-float.5 servo-thread addf conv-s32-float.6 servo-thread addf read and write entries need to match the number of servos so delete these lines addf cia402.4.read-all servo-thread addf cia402.4.write-all servo-thread removed entire spindle section. Have 4 ethercat servos, so cia402 count of 4 Change loadrt cia402 count=5 to loadrt cia402 count=4 For dual Y gantry: Delete Axis A Under Axis Y, change all signal names to y0 Duplicate code. Change the duplicated code to y1 y0 has joint number 1 and y1 has 2. They are not the same. Change around Marco's order of driver assignments He has x is 3, y is 2, z is 1, a is 0. Mine is x is 0, y0 is 1, y1 is 2, z is 3. ---- Change EL8_machine.ini to match my setup. Other parameters will be changed later. Note: the motors are clearly not scaled correctly. They barely move at all under testing. Under [joint] there is scale=80 which is maybe low. Need to look into how to properly set up encoder to movement corrections. 23-bits is a whole lot of bits. change scale=80 to scale=2000 Delete Spindle section and Axis A section Change from: [KINS] JOINTS = 5 KINEMATICS = trivkins coordinates=XYZAB [TRAJ] COORDINATES = X Y Z A B to: [KINS] JOINTS = 4 KINEMATICS = trivkins coordinates=XYYZ kinstype=BOTH [TRAJ] COORDINATES = X Y Z Copy Joint 1 under Axis_Y Change [JOINT_1] to [JOINT_2] Change Axis Z to Joint 3 Then comment out #MAX_ANGULAR_VELOCITY = 2.5 This is for the servo spindle Then add this to have a minimum spindle speed, otherwise starts at 0. DEFAULT_SPINDLE_SPEED = 7200 Note: set the mimimum spindle speed for your setup so you don't hit the + button for ages before the spindle speed hits the minimum for the spindle Remove any unnecessary joints For dual axis: #*** AXIS_Y ******************************* [AXIS_Y] MAX_VELOCITY = 25.0 MAX_ACCELERATION = 750.0 MIN_LIMIT = -30000.0 MAX_LIMIT = 30000.0 [JOINT_1] TYPE = LINEAR HOME = 0.0 MIN_LIMIT = -30000.0 MAX_LIMIT = 30000.0 MAX_VELOCITY = 25.0 MAX_ACCELERATION = 750.0 FERROR = 1000 MIN_FERROR = 1000 HOME_ABSOLUTE_ENCODER = 2 [JOINT_2] TYPE = LINEAR HOME = 0.0 MIN_LIMIT = -30000.0 MAX_LIMIT = 30000.0 MAX_VELOCITY = 25.0 MAX_ACCELERATION = 750.0 FERROR = 1000 MIN_FERROR = 1000 HOME_ABSOLUTE_ENCODER = 2 #****************************************** Note: settings here are for testing purposes only and not the final numbers. Need to add: kinstype=BOTH ---- Set up L510 VFD Add this line to the HAL file loadusr -W l510_vfd --target 1 --rate 19200 --device /dev/ttyUSB0 Note: the default for the VFD is 19200, but can change. Also, with the waveshare USB to RS485 adapter plugged into the pi, use ls /dev and check the list for a device ttyUSBX where X is 0, 1, 2, etc. Use this address for the above line in the HAL file. Change if necessary Get file code for l510. cd /home/cnc/linuxcnc/files https://github.com/gitcoffey/l510_vfd.git Move l510_VFD.c to the config folder change lines 773 and 774: From haldata->motor_RPM = 1730; haldata->motor_hz = 60; To: haldata->motor_RPM = 3000; haldata->motor_hz = 50; Note: setting the RPM to 3000 is approximately the right amount for the 1.5kw spindle to match RPM. Not sure I am doing the math right here. There may be a more accurate way. Compile l5510_VFD.c cd /home/cnc/linuxcnc/configs/linuxcnc_leadshine_EL8/ sudo halcompile --userspace --install --extra-link-args="-lm -modbus" l510_vfd.c Note: sudo halcompile --install l510_VFD.c has an error "syntax error in VERSION script". Andy Pugh found some documentation for halcompile to get around this. Note: any further changes to this file and you have to recompile to take effect. Add this section to machine HAL file in the spindle section: #******************* # Spindle #******************* #for Teco Westinghouse l510 or RS components RS510 rebrand setp l510_vfd.enable 1 net speed-cmd spindle.0.speed-out-abs => l510_vfd.spindle-speed-cmd net spindle-on spindle.0.on => l510_vfd.spindle-on net spindle-fwd spindle.0.forward => l510_vfd.spindle-fwd net spindle-rev spindle.0.reverse => l510_vfd.spindle-rev net spindle-at-speed <= l510_vfd.at-speed Note: syntax is king. Normally hal pins use - "dash" as a separator and commands normally use _ "underscore". This guideline was not followed for the l510_vfd.c. The way to find this out is to add show pins and launch LinuxCNC from the command line. The pins also show up in the error message. Check the names of the pins there. ---- Resolve no tool.tbl error If you get an error about a missing tool table, go to: https://github.com/LinuxCNC/linuxcnc/blob/master/configs/sim/axis/remap/tool.tbl And download the raw file and put it in your config folder. Fill it with correct info later. ---- Resolve conflict between Pendant and machine HAL file spindle section Got an error: Debug file information: Note: Using POSIX realtime ./xhc-whb04b.hal:164: Pin 'spindle.0.speed-out-abs' was already linked to signal 'speed-cmd' 5158 Stopping realtime threads Note: xhc-whb04b.hal is opened second and the solution here is to change the signal name to the same name as EL8_machine.hal line net speed-cmd spindle.0.speed-out-abs => l510_vfd.spindle-speed-cmd Open xhc-whb04b.hal change line 160-ish from: net pdnt.spindle-speed-abs whb.halui.spindle-speed-cmd spindle.0.speed-out-abs # speed cmd from motion in rpm absolue to: net speed-cmd whb.halui.spindle-speed-cmd spindle.0.speed-out-abs # speed cmd from motion in rpm absolue Note: this matches the signal name in the Spindle section of the HAL file and therefore resolves the conflict since two signals aren't trying to use the same pins (as I understand it) Start the config and hopefully no errors --------------------- -------------------- GUI -------------------- --------------------- ---- probe_basic (qtpyvcp based) pyvcp is pretty outdated and quite difficult to work with I am told. qtpyvcp is much newer and based on pyqt5 which should be longer lived. can be found here: https://github.com/kcjengr/probe_basic for arm64 install\ qtpyvcp install instructions found here: https://www.qtpyvcp.com/ Note: there is an Rpi5 version, eg, Arm64 version. Quite recent, in 2025. The installation can be found here (arm64 pi 4 and 5 repository): https://www.qtpyvcp.com/install/apt_install.html NEW - ARM64 Raspberry Pi 4 and 5 Installation Repository: Run the following commands in the main terminal one at a time: echo 'deb [arch=arm64] https://repository.qtpyvcp.com/apt stable main' | sudo tee /etc/apt/sources.list.d/kcjengr.list curl -sS https://repository.qtpyvcp.com/repo/kcjengr.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/kcjengr.gpg gpg --keyserver keys.openpgp.org --recv-key 2DEC041F290DF85A sudo apt update sudo apt install python3-qtpyvcp sudo apt install python3-probe-basic sudo apt install python3-monokrom sudo apt install python3-turbonc Can now start LinuxCNC and you will see probe_basic which is a sim to explore. Click e-stop to get a few things going. Make a copy of probe_basic and call it probe_basic-dev Now try to match the folder structure and add in your files and replacing the HAL, ini, etc. Put all HAL files in hallib, put .ini file in the main folder (with probe_basic.ini) Error: always_homed.comp: Skeleton Homing Module Fix: ethercat-conf.xml into the same folder as the ini file To account for the change in file structure, In EL8_machine.ini change: [DISPLAY] DISPLAY = axis and [HAL] HALFILE = EL8_machine.hal HALFILE = xhc-whb04b.hal POSTGUI_HALFILE = pyvcp_panel.hal to [DISPLAY] DISPLAY = probe_basic and [HAL] HALFILE = hallib/EL8_machine.hal HALFILE = hallib/xhc-whb04b.hal POSTGUI_HALFILE = hallib/pyvcp_panel.hal changed in .ini [EMCMOT] HOMEMOD=always_homed to [EMCMOT] #HOMEMOD=always_homed HOMEMOD=el8_homecomp Can't use the machine because it is asking to be homed so switched HOMEMOD=always_homed #HOMEMOD=el8_homecomp This works and the machine doesn't need to be homed. ---- Get a homing routine. Note: I belive that the el8_homecomp.comp file that Marco included is based off the work of rodw to get torque based homing working on ethercat systems since the homing lines in HAL all say Cia402. Note: It appears the drivers can do homing entirely on their own, ie. via torque limiting or with limit switches/endstops. Homing could be done entirely outside of linuxcnc and then use an always homed setup afterward. Need to look at how to wire up endstops directly to driver. This may be a way forward with absolute encoders and avoid messiness in LinuxCNC dealing with them. This would require some way to 'e-stop' them with a button if something goes wrong. Would use CN1 pins 38 and 39 for limit reached if using endstops, and I have asked leadshine about gantry mode. There is absolutely nothing in the manual about that and they say it is one of the bigger features of the EL8 drivers. Hm. Source files: Now need to try to get el8_homecomp working. Noticed that the homing lines in the HAL are commented out. Therefore make a copy of the configuration and: change to:https://github.com/rodw-au/cia402_homecomp The homing lines below use the cia402 pins, so I believe this is the way forward. Testing: Switch to [EMCMOT] #HOMEMOD=always_homed HOMEMOD=el8_homecomp Then for each joint, change: # homing #net x-home-request joint.0.request-custom-homing => cia402.0.home #net x-homing joint.0.is-custom-homing <= cia402.0.stat-homing #net x-homed joint.0.custom-homing-finished <= cia402.0.stat-homed to # homing net x-home-request joint.0.request-custom-homing => cia402.0.home net x-homing joint.0.is-custom-homing <= cia402.0.stat-homing net x-homed joint.0.custom-homing-finished <= cia402.0.stat-homed Also added #HOME_OFFSET = 0.0 to each joint. Likely used later to square the gantry and kiss off -6 homing Ok, it did start a homing routine but tried Ref Z and got a joint 2 error which is is the y axis. Strange. Maybe because of the gantry setup. Hm. When I hit refZ, one of the y1 drive moves briefly. LinuxCNC sees that y0 and y1 have deviated and it throws a joint error. No idea why y1 is moving and not Z. Also, I have not set y0 and y1 to gantry mode on the leadshine driver side. If cia402 is using driver internal homing, then the drives won't know to move in lockstep...I believe. Check what happens if I choose refx: net y0-home and net y1-home . Not sure if they should be the same. Maybe I need to set up a 3 driver XYZ, X Y Z setup to test this. from source: http://www.linuxcnc.org/docs/html/config/ini-homing.html#_home_absolute_encoder added this to synchronize the moves. Again, not sure if this is necessary as the homing is on the drives. : [JOINT_0]HOME_SEQUENCE = 0 [JOINT_1]HOME_SEQUENCE = -1 [JOINT_2]HOME_SEQUENCE = -1 [JOINT_3]HOME_SEQUENCE = 1 --------------------- -------------------- Tips and tricks -------------------- --------------------- ---- tips for working with the terminal copy text with ctr + c paste text into terminal with shift + ctrl + c/287 up arrow to repeat a command If a text window is open, terminal will wait until it is closed to continue/give a command line ---- Tips for LinuxCNC getting a working config Launching linuxcnc from the terminal will provide more info linuxcnc In the machine HAL, can place: for arm64 install\ for arm64 install\ show pins wherever you want to see what pins have been called at that point in time. The pins will also show up in the error message ---- Test compiled code on their own You can test compiled code on their own to see what is going on. It is easier than diagnosing In terminal: halrun You will see: halcmd Then type loadusr l510_vfd where l510_vfd is your compiled code that you want to test. ---- Tips for absolute encoder in testing A few spins of the servos with the machine off can take the servos way outside of the machine limits. This is a pain with the Z axis brake engaged. Can manually hit brake with 24V but better is: USB into driver and change pr015 to 1. This disables the absolute encoder. The driver needs to be power cycled. Once power cycled, go back to and change to ---- Tips for clearing driver errors source: page 195 4.6 Auxillary function of el8 manual Press S then M to get to parameters then press M again then use down arrows to AF ACL (4clicks and looks like _CL) then press S --------------------- -------------------- Info sources -------------------- --------------------- ---- Step by step ethercat install https://forum.linuxcnc.org/ethercat/45336-ethercat-installation-from-repositories-how-to-step-by-step ---- Install Ethercat on Rpi ---- Marco Reps machine EL8 based ethercat machine https://www.youtube.com/watch?v=H1JEY2btwKk Older ethercat vid https://www.youtube.com/watch?v=FEPfznStd0s Spinogy Ethercat spindle rigid tapping https://www.youtube.com/watch?v=u8ISNu3We9g ---- Configuring I/O with Beckhoff 1100 https://github.com/pklopping/linuxcnc-ethercat-basics/tree/trunk/basic_digital_outputs ---- EL8 Drive settings Some info on settings inside EL8 driver https://forum.linuxcnc.org/ethercat/51139-leadshine-el8-configuration Change absolute encoder Pr0.15 to 1 from default 0 Change POE.31 Homing mode to -6 from default 0 Note: A few spins of the servos with the machine off can take the servos way outside of the machine limits. This is a pain with the Z axis brake engaged. Can manually hit brake with 24V but better is: USB into driver and change pr015 to 9. This disables and resets the absolute encoder. The driver needs to be power cycled. Once power cycled, go back to and change Pr0.15 to 1. This should rezero the encoder. ---- LinuxCNC Guides Swolebro simplier explanations are easy to follow. Don't look for clean wiring inspiration here :o https://www.youtube.com/watch?v=lP2-2duBYBM&list=PL9xPdBFt5g3Qnn3ZY2wYh7L2yzZ377UwI ---- Homing issues with ethercat or with absolute encoders Ethercat servo homing https://forum.linuxcnc.org/ethercat/51176-ethercat-servo-homing Cracking the Code on LinuxCNC Servo Homing Setup https://forum.linuxcnc.org/ethercat/52968-help-needed-cracking-the-code-on-linuxcnc-servo-homing-setup?start=40 CIA402 Homing module - a start https://forum.linuxcnc.org/ethercat/52272-cia402-homing-module-a-start