Peripherals

Peripherals are machine mechanisms outside the core axes, spindle, and coolant controls. Their physical sequencing belongs to the machine configuration, while Ctrl provides stable program-level meanings and integration contracts where a mechanism is supported.

Choose the mechanism

Mechanism	Read this page	Ctrl integration
Power chuck, collet, or expanding mandrel	Automatic workholding	Indexed grip configuration, persistence, HAL output, and M10/M11/M14 P<device> Q<mode> meanings
Spindle gearbox	Spindle gearbox	M16 P<gear> from the GUI or part programs, with machine-owned completion
Lathe tailstock quill	Tailstock quill	M20/M21 meanings and the machine-action executor pattern

Each peripheral page defines the program-facing intent and the public Ctrl interface. The machine action controller remains responsible for valves, drives, interlocks, feedback qualification, timeouts, and lasting physical state.

Peripheral integration is functional machine control. Emergency stopping, safe pressure removal, guards, enabling devices, and other safety functions remain in the machine’s safety-rated system.

Set up shared peripheral remaps

A machine uses one Python remap component for all of its peripherals. Put remap.py and toplevel.py beside the machine INI, normally in a directory such as /data/ctrl/configs/my-machine.

Configure the shared Python environment once:

[PYTHON]
TOPLEVEL = toplevel.py
PATH_PREPEND = /data/ctrl/configs/my-machine
PATH_APPEND = /usr/share/linuxcnc/ncfiles/remap_lib/python-stdglue

Create the shared component in toplevel.py:

import hal
import remap
from stdglue import HalExecutor, init_stdglue


def __init__(self):
    init_stdglue(self)

    component = hal.component("remap") if self.task else None

    # Add the HalExecutor instances required by each peripheral here.

    if component is not None:
        component.ready()

    self.remap_hal = component

Every peripheral executor must be added before component.ready(). LinuxCNC loads the same module for its task and preview interpreters; self.task ensures that only the task interpreter creates HAL pins and operates hardware.

import remap loads the complete sibling remap.py module so LinuxCNC can resolve every function named by a REMAP entry. Commands such as M10 and M11 are not imported individually; their functions must be defined in that module.

Import the shared transaction helper once at the top of remap.py:

from stdglue import executor_execute

Each peripheral page supplies three device-specific additions:

1. Its REMAP lines under the machine’s existing [RS274NGC] section.
2. Its HalExecutor instances inside the shared __init__ function.
3. Its operation functions in the shared remap.py module.

Extend these files when adding another peripheral. Do not create a second HAL component or call component.ready() until every endpoint has been declared. See Remap a machine action for the request flow and Executor protocol for the seven-pin transaction contract.