In Part 1 we verified the touch plate being connected and configured right. Now it’s time to get it working.



Without the information in this thread on I wouldn’t be able to do this so credits to and especially to author Spokes who provided a tutorial and bundled the files needed on page 11 of the mentioned thread. Here is a link to zip file with his files and tutorial. While I’m, setting up my CNC with the touch plate I provide this step by step overview. I’m using LinuxCnc 2.5.0 2.5.1. 2.5.3

Create a backup

The setup and configuration changes the current setup. If for whatever reason you need to roll back this will help you out.

Locate the directory containing your configuration files. To help you identify, this typically contains files like:

  • <myname>.hal
  • <myname>.ini
  • custom.hal
  • custom_postgui.hal
  • linuxcnc.var
  • postgui_backup.hal
  • tool.tbl

Select all files in that directory and copy them to a backup directory (I called it backup1).


Add HalUi and PyVCP

Using the defaults when setting up your system with LinuxCnc some options are not enabled. Time to do it now. Start the Stepconf Wizard.

  • Press Forward
  • Select Modify your configuration.
  • Select your existing configuration file.
  • Press Forward on the Basic Machine Information screen.

You now arrive on the Advanced Configuration options screen.

Tick the boxes at the marked positions A and B. Verify the other options are the same as on the screenshot.

Download the files

You can download the zip file needed for the remaining steps:

  • here from the original post in
  • local copy (different name, same files though).

Unzip the archive in a temporary directory (on your desktop for example) and go into the folder named plasma or touchplate depending on which link you followed for the zipfile. Both archives contain the same files.

Replace custom panel

  1. Go to the directory containing your current configuration files. This is the same directory as where you created the backup from as mentioned at the top of the article.
  2. Find the file named custompanel.xml
  3. Copy (yes overwrite it) the file custompanel.xml from the unzipped archive on your desktop into the directory containing your actual configuration.

Yes indeed you just replaced your current custompanel.xml with the one from the zip archive.


A diff of the old and new file. Note: the new custompanel.xml defines two buttons. The first is required, the second optional. For now keep both the required and optional part.

Quick check

Time to verify if the steps above. Just start LinuxCnc and verify that 2 new buttons appear on the right side of the screen. No need to click anything here. Just verify you see the 2 buttons as in the screenshot below. If you don’t have these button: close LinuxCnc, restore the backup from the beginning and start over.

Close LinuxCnc and continue with the next steps.


Add the Touch Button Code

The code behind the touch off button is a classic ladder. (For the curious, documentation can be found here.)

  • Copy the file Touch_OFF_Button.clp from the unzipped archive on your desktop into the directory containing your actual configuration.

Quote from the Classic Ladder documentation:

Typically classic ladder components are placed in the custom.hal file if your working from a Stepconf generated configuration. These must not be placed in the custom_postgui.hal file or the Ladder Editor menu will be grayed out.

  • In the directory containing your actual configuration open the file custom.hal and verify that it contains only lines starting with a # character. (This is the case with a default install.)
  • If so then copy the file custom.hal from the unzipped archive on your desktop into the directory containing your actual configuration and replace the original with the new one. (If not you can try to copy the contents of the custom.hal from the unzipped archive on your desktop and append it to your custom.hal file of your current configuration.)

The same thing for the custom_postgui.hal file, here we go:

  • In the directory containing your actual configuration open the file custom_postgui.hal and verify that it contains only lines starting with a # character. (This is the case with a default install.)
  • If so then copy the file custom_postgui.hal from the unzipped archive on your desktop into the directory containing your actual configuration and replace the original with the new one. (If not you can try to copy the contents of the custom_postgui.hal from the unzipped archive on your desktop and append it to your custom_postgui.hal file of your current configuration.)

Using the latest and greatest

When using LinuxCnc 2.5.0 as I do the custom.hal file now actually contains too much information (and it will not work).

  • Go to the directory containing your actual configuration files
  • Edit custom.hal with a text editor (like gedit)  and remove these two lines:

loadrt classicladder_rt
addf classicladder.0.refresh servo-thread

Keeping true to the work done by the good people on the original method as described there was followed to the letter. But for recent versions of LinuxCnc the modification as described above is mandatory.


Update the “.ini” file

Last steps of the process, you are nearly there.

  • In the directory containing your actual configuration locate the one file with extension ini <myname>.ini where <myname> can be any text, depending on how you named your cnc setup in LinuxCnc.

With the .ini file located you need to verify one entry.

  • Open <myname>.ini with a text editor (like gedit). Scroll down until you see the [DISPLAY] section. Verify that one of the lines there states:
    • PYVCP = custompanel.xml

The entry should already be there. If not add it manually, but most likely you forgot a step somewhere along the line (better to start over from the beginning).
Last modification.
  • Open <myname>.ini with a text editor (like gedit)
  • Find the section named: [HALUI]
  • Now add the following 4 lines:
MDI_COMMAND = G38.2 Z-2 f16
MDI_COMMAND = G92 x2 y-.5
  • Save your .ini file

Note: The mentioned thread on says that instead of the G92 command it recommended to use G10 L20 P0. Next article on that. 🙂


Time to launch

Start LinuxCnc

  • If you get any errors when starting LinuxCnc please reread the section “Using the latest and greatest” and remove 2 lines from custom.hal.

Verify the buttons are on the right.

Switch to MDI mode and the buttons should be active!

Be careful when testing the touch off plate!


19 Responses to “LinuxCnc – Touch plate – Part 2”
  1. Jeppe says:

    Very nice and guiding presentation!
    I wish more people in the Linux world had the ability to explain things that you have.

  2. Gururaj says:


    This is really very relevant article for people who wants to add the probing feature of Linux CNC. I totally agree with you that there are lots of info on the thread you mentioned under credits heading (

    One small request. In the both the zip files you shared (local copy: and the one from cnczone: the third MDI command for “Z rapid away” is commented out. i.e the following line must be un-commented so that Z will move away from the touch plate after the probing has been done.

    net rapid-away classicladder.0.out-02 => halui.mdi-command-02.

    I spent almost three complete days to figure this out (Spent time in analyzing ladder diagram, Gcode etc :)). If you can make this change in the shared zip file or post this comment in your website, it may help others to resolve the issue I faced.


  3. Joe Hildreth says:

    Just wanted to confirm this is a great how-to. I have followed your instructions and read the thread you linked above a few times and it works. Thanks for taking the time to share it. Also, I have a couple of questions.

    1) May I reproduce the concept of your work? I am building a KRMx01 router to replace my JGRO machine and as written, this plan uses Mach3 for the controller. I plan on giving details on how to use LinuxCNC with the router and other electronics and motors as well. This would be a nice addition to that. I will give you credit and a link as well. I am a ways off from completing the project, you you can follow my progress if you like by going to

    2) I used both the G92 and the G20 L10 P1 commands to try to figure out the difference. It seems to me they pretty much produce the same results. My question is, when I do a manual touch off, the plot of the paths will move to a new position. When it is done programatically (if that’s a word) with the touch off button, the plot does not move. For completeness, and a great visual indicator, is it possible to get the plot to move when the touch off is complete?

    Thanks again for your hard work. Simply a great job you have done.


  4. Mehis says:

    Good work!

    Followed these instructions. Works excellent after some justifications, but I noted that after automatic homing to x0 y0 z150 coordinates became as writed on HALUI section of ___.ini file. some has gone wrong, I think.

    Thanks to author!

  5. sad says:

    thanks a lot for this tutorial.
    i would like to use the touch plate for woodworking, placing the plate on top of workpiece, but any plate have some thickness.
    so, my question is: is it possible to set an offset (the same of plate thickness) on the configuration files to get the right touch off?
    best regards

  6. Bob says:

    I was wondering the same thing. Where do we set the offset for the thickness of the plate.


    • Bert says:

      please download my local copy with all files and open/read de rtf document. There it explains the Z offset (thickness of touch plate). Bottom line is that the G92 Z0.25 means a 0.25 plate thickness. Please change the value as needed.

      • George says:

        Thanks for the great tutorial. I followed your instructions to the letter,to add a touch off plate to my cnc router.
        It works OK,except for one thing: The Z axis moves up,instead of down towards the touch plate!! Could you,please,help me with making it move in the right direction?

        • George says:

          Fixed it!! I just deleted the minus sign from MDI_COMMAND = G38.2 Z-2 f16 and it works now. The Z axis moves down.
          Greetings to all.

          • George says:

            Sorry everyone,I had to insert the minus in,then close and restart the Linuxcnc for the probe to work

  7. Bob says:

    I also have it all configured. Part 1 works fantastic. Pin 15. When I finish with part 2, does nothing. No movement or notices when either button is pushed.

    Copied backup over and tried again. 4 times.

    This is using the latest LinuxCNC 2.6.7


  8. Jeff says:

    Thank you! I am very excited to have this functional button now. I have LinuxCNC 2.5.0 and followed the directions carefully but the [HALUI] section did not show up in my .ini file but there was a [HAL] section. My solution was to place “HALUI = halui” in the [HAL] section which then invoked HALUI and created that section in my .ini which allowed me to place the MDI_COMMAND lines in there. THANK YOU for this excellent tutorial and now the capability of the touchoff plate and button. I used a PCB board and it is working great.

  9. Bernice says:

    Do you have any video of that? I’d like to find out more details.

  10. Mark says:

    Using the latest version of LinuxCNC, and part 2 is not for, anything special needed to make this work with that latest version, thanks in advance….

  11. Oscar T. says:

    Thank you very much! After so many days looking for this information, I finally found you, and with just two posts, you solved my problem!! COngratulations, very helpfull tutorial.

  12. Felisha Wild says:

    Thank you so much for this excellent tutorial. Got our auto touch plate going and it has been a huge time saver.

    Wish there was a way to hold on to the settings after running stepconfig again.

    Keep up the great work and thank you once again


  13. Joe Weissman says:

    I have been trying to install this software on LinuxCNC 2.7 and get an error referencing a line in custom_postgui.hal:

    pin ‘halui.mdi-command-00’ does not exist. ECM2 then exits.

    Any suggestions?


  14. Joe Weissman says:

    Nevermind, file edit error. its working