Machine prompts

Machine prompts let a machine configuration or another installed program ask the operator to confirm a manual step or choose from a defined set of actions. The prompt catalog owns the wording, available actions, presentation, and integration contract.

Use a prompt when the operator must make a deliberate choice that ordinary machine controls do not express clearly. Typical examples include confirming that a chip tray has been reinstalled, completing a manual tool change, or selecting a recovery path after a non-safety fault.

A prompt is a functional operator interaction, not a safety function. Do not use prompt acknowledgement as an emergency-stop, guard, safe-motion, or other safety-rated signal.

Choose where to begin

Goal	Read this page
Add a manual tool-change or gearbox prompt	Use built-in prompts
Add and run one custom prompt	Create your first prompt
Write messages, details, actions, conditions, and translations	Design prompt content
Bind captured values and action results to HAL	Configure the HAL contract
Share definitions or customize a built-in workflow	Reuse and specialize templates
Submit configured prompts from installed software	Integrate a software producer

Start with the built-in prompts. Continue through the custom-prompt pages when the supplied machine workflows do not fit the operation. You only need the software-producer page when the request does not originate in HAL.

The prompt lifecycle

Every prompt request follows the same ownership cycle:

1. A producer submits a configured prompt name and a snapshot of its input values.
2. The broker validates and queues the request. One prompt is active at a time.
3. Ctrl shows the active prompt using the current locale.
4. The operator selects a declared action or, when allowed, aborts the prompt.
5. The producer reads the result and acknowledges that it has finished with the request.

For a HAL producer, the trigger’s rising edge submits the request and its falling edge acknowledges and releases it. For a software producer, these are explicit messages on a gRPC producer session.

An active prompt is not a live view of HAL or LinuxCNC. Its variables, tool information, and machine units are captured when the request is submitted. A locale change rerenders that same captured request; changing an input pin does not.

Catalog ownership

Prompt behavior lives in a machine-owned prompts.yaml catalog. It can contain:

• reusable templates that define content and, optionally, a HAL pin contract;
• configured prompts that Ctrl is allowed to display; and
• a HAL component name used to namespace all generated prompt pins.

The broker validates the entire catalog once at startup. It does not accept arbitrary dialog content from a producer at runtime. This keeps operator choices and machine-facing results reviewable in the machine configuration.