Raspberry Pi 4B LinuxCNC: Homing to the Origin (0, 0, 0)

My LinuxCNC 2.9.4 home position was set to coordinates I didn’t quite understand. I am documenting the Gemini-assisted troubleshooting process I used to set it to the origin (0, 0, 0). This is not a tutorial, but rather a record of my learning progression.

🐧 Index of the Complete Series.


Raspberry Pi 4B LinuxCNC: Homing to the Origin (0, 0, 0)

I am just an ordinary computer programmer and not trained in any of the electronic engineering disciplines. This LinuxCNC project is a learning process for me. This post is not meant to be a tutorial or instructional guide; it is my own documentation so I will not forget what I have learned.

I am not to be held responsible for any damages or injuries resulting from using the information presented in this post.

Setting the home coordinates to the origin (0, 0, 0) is an exercise in understanding LinuxCNC a bit better, rather than a definitive final setup.

In the last post, which accompanies this YouTube video, I mentioned that the initial homing position was unexpected, as illustrated in the screenshot below:

The tool cone moved to the shown position after clicking the Home All button in the UI. 💡 Please note: the Preview screen shows a reading of G54 X = -20.000.

I am not entirely certain how this offset happened. I can only assume that I must have configured something incorrectly or misunderstood a setting during the initial setup process. For this exercise, I want to force the homing position to (0, 0, 0) purely to gain a better understanding of how LinuxCNC handles homing sequences.

For reference, you can check out the official LinuxCNC documentation on Homing Configuration.

🙏 Please note, this was a brand new setup for the Mesa 7I96S card using the Mesa Configuration Wizard, PnCconf.

❶ I first went through the following steps suggested by Google Gemini—but unfortunately, they did not solve the issue.

⓵ In the main .ini configuration file (Test_XYZ.ini), under the respective joint blocks for the X axis ([JOINT_0]), Y axis ([JOINT_1] and [JOINT_2]), and Z axis ([JOINT_3]), I made sure HOME was set to 0.0 and added a HOME_OFFSET = 0.0 entry:

[AXIS_X]
MAX_VELOCITY = 5.0
MAX_ACCELERATION = 750.0
MIN_LIMIT = -20.0
MAX_LIMIT = 100.0

[JOINT_0]
TYPE = LINEAR
HOME = 0.0
HOME_OFFSET = 0.0
HOME_SEQUENCE = 2
...

[AXIS_Y]
MAX_VELOCITY = 25.0
MAX_ACCELERATION = 750.0
MIN_LIMIT = -0.01
MAX_LIMIT = 200.0

[JOINT_1]
TYPE = LINEAR
HOME = 0.0
HOME_OFFSET = 0.0
HOME_SEQUENCE = -3
...

[JOINT_2]
TYPE = LINEAR
HOME = 0.0
HOME_OFFSET = 0.0
HOME_SEQUENCE = -3
FERROR = 10.0
...

[AXIS_Z]
MAX_VELOCITY = 25.0
MAX_ACCELERATION = 750.0
MIN_LIMIT = -100.0
MAX_LIMIT = 0.01

[JOINT_3]
TYPE = LINEAR
HOME = 0.0
HOME_OFFSET = 0.0
HOME_SEQUENCE = 1
FERROR = 10.0
...

After saving the file and relaunching LinuxCNC, this configuration update alone did not fix the problem.

⓶ For my next attempt, I tried using the LinuxCNC UI directly. I selected the X-axis, jogged it to what should be 0, and clicked Touch Off. However, after relaunching LinuxCNC, this did not solve the issue either. 💡 At that time, I did not yet fully understand exactly what the Touch Off function does under the hood.

⓷ This third attempt involved modifying several configuration variables at once. All of the updates discussed in point ⓵ remained in place during this test.

● First, I verified that in the Test_XYZ.ini file, there were originally no active entries for HOME_SEARCH_VEL and HOME_LATCH_VEL.

● Next, I updated the HOME_SEQUENCE for each joint in the Test_XYZ.ini file to the following values:

[JOINT_0]
HOME_SEQUENCE = 1

[JOINT_1]
HOME_SEQUENCE = 1

[JOINT_2]
HOME_SEQUENCE = 1

[JOINT_3]
HOME_SEQUENCE = 0

● I then explicitly added HOME_SEARCH_VEL = 0.0 and HOME_LATCH_VEL = 0.0 to the [JOINT_0], [JOINT_1], [JOINT_2], and [JOINT_3] sections of the file:

HOME_SEARCH_VEL = 0.0
HOME_LATCH_VEL = 0.0

● Finally, inside the main HAL file (Test_XYZ.hal), I commented out the previously configured X-axis limit proximity sensor connections to isolate the software behavior:

# net x-home-sw     =>  joint.0.home-sw-in
# net x-neg-limit     =>  joint.0.neg-lim-sw-in
# net x-pos-limit     =>  joint.0.pos-lim-sw-in

( Note: Once I got the homing sequence working successfully, I re-wired the physical X-axis proximity switch sensor back up and reinstated the HAL lines above. Everything now works perfectly as expected. )

❷ Finally, ✔️ the correct resolution! This step was carried out while all of the configuration changes to the main .ini and .hal files discussed above were still in place.

I finally noticed the line G54 X = -20.000 on the Preview panel and fed this clue back to Google Gemini. Gemini accurately pointed out that there was an active Coordinate Offset “saved in LinuxCNC’s memory (usually G54 or G92). LinuxCNC remembers these offsets even if you restart the software, restart the computer, or change the .ini file config.”

The official documentation covering this behavior can be found under LinuxCNC Coordinate Systems.

Gemini proposed a clear solution: clear the active G54 Fixture Offsets and the G92 Offsets. To do this in LinuxCNC, open the MDI (Manual Data Input) tab and execute the following three commands sequentially:

G54
G10 L2 P1 X0 Y0 Z0
G92.1

I am operating largely on “faith” here 😂, as I have not studied these commands in deep technical detail yet. However, here is what they achieve:

● G54 ensures that the machine is actively using the default work coordinate system.

● The second command, G10 L2 P1 X0 Y0 Z0, clears out the G54 offsets. Alternatively, this can be done manually via the GUI: select the axis, click the Touch Off button, enter 0 in the dialog box, and hit OK (repeating for X, Y, and Z).

● G92.1 immediately clears any global, temporary axis offsets that might otherwise persist across sessions inside LinuxCNC’s internal parameters.

I didn’t inspect the /home/behai/linuxcnc/configs/Test_XYZ/linuxcnc.var file prior to executing these commands, so I don’t know exactly what numbers were overwritten. But the results speak for themselves: now, every time LinuxCNC starts, the tool cone defaults perfectly to (0, 0, 0), the Preview screen shows the coordinate accordingly, as shown below:

Because everything is already zeroed out out-of-the-box, clicking Home All now leaves the visual display completely unchanged—exactly what I wanted to achieve!

❸ I have committed both the modified .ini and .hal configuration files to GitHub for reference:

❹ This has been an incredibly interesting troubleshooting exercise. I fully recognise that I took a few shortcuts to get these quick results—but hey, we all need a quick win to feel good sometimes! 😂 This definitely won’t be the last time I look at homing configurations, and I am sure I will revisit and refine this process as my learning journey continues.

Thank you so much for reading. I hope you find this breakdown helpful for your own setups. Take care and stay safe!

✿✿✿

Feature image source: