LinuxCNC Documentation

SYNOPSIS

Custom Homing module loaded with [EMCMOT]HOMEMOD=homecomp

DESCRIPTION

Example of a plug-in homing module buildable with halcompile. Demonstrates the required code structure for #includes, function definitions, HAL pins, etc.

The complete homing module interface (every function a homing module must export, when motmod calls it, and what it should do) is documented in src/emc/motion/homing.h.

Build modes:

  • Skeleton (default). If HOMING_BASE is not #defined, the module implements the full homing API but runs no real homing state machine. A hal pin motion.allow-sim-homed (default true) gates the simulated homed state: with it set, all joints are immediately reported as homed, which is useful for bring-up and config testing on hardware without working home switches. With it cleared, each joint reports homed only while its joint.N.home-sw-in pin is true, showing how HAL inputs feed the homing API.

  • Custom (advanced). If HOMING_BASE is #defined to the absolute path of a checkout’s src/emc/motion/homing.c, this component #includes that file with CUSTOM_HOMEMODULE defined. This brings in the static base_*() helpers from homing.c so user code can call them or override the per-joint state machine. This is the same pattern used historically by user_homecomp templates; it requires a full LinuxCNC source checkout because homing.c is not installed.

The custom module is an example only: it adds per-joint hal pins joint.N.request-custom-homing and joint.N.is-custom-homing so the operator can pick which joints get the custom path. Requested joints are simply marked homed immediately; a real custom module would run its own state machine here instead of calling base_1joint_state_machine().

To avoid updates that overwrite this template, best practice is to rename the file and its component name (example: user_homecomp.comp, user_homecomp).

The renamed component can be built and installed with halcompile and then substituted for the default homing module (homemod) using:

$ linuxcnc -m user_homecomp someconfig.ini

or by inifile setting:

[EMCMOT]
HOMEMOD=user_homecomp

Note: If using a deb install:

  1. halcompile is provided by the package linuxcnc-dev

  2. This source file for BRANCHNAME (master, 2.9, etc.) is downloadable from github: https://github.com/LinuxCNC/linuxcnc/blob/BRANCHNAME/src/hal/components/homecomp.comp

PINS

homecomp.N.is-module bool out (default: 1)

AUTHOR

Dewey Garrett

LICENSE

GPL