3.8. LinuxCNC Configuration¶

As noted in Section 3.6.2, a LinuxCNC configuration comprises several files, requiring at least one INI file and one HAL file. The following sections detail the configuration of both file types, using the citic_gantry_robot configuration as an example.

3.8.1. INI Configuration¶

3.8.1.1. .ini Configuration File Format¶

An .ini file is a plain text file used for configuring applications and programs. It has a simple structure consisting of sections and key-value pairs. The basic syntax of an .ini file is as follows:

Sections: Sections serve to organize keys and values. Each section begins with its name enclosed in square brackets, followed by zero or more key-value pairs belonging to that section. The syntax for a section is:
```
[section_name]
```
Keys and Values: Within each section, keys and their corresponding values can be defined. Keys are identifiers used to access associated values. The syntax for a key-value pair is:
```
key = value
```
Keys can contain letters and underscores (_). Values can be text strings, integers, or floating-point numbers.
Comments: Comments begin with a semicolon (;) or a hash symbol (#). For example:
```
; This is a comment
# This is also a comment
```

3.8.1.2. `citic_gantry_robot.ini` Configuration File¶

Below are the different sections of the citic_gantry_robot.ini configuration file, with comments explaining the purpose of each parameter.

Note

Not all available parameters are specified in some sections. For a complete list of parameters and their documentation, consult the LinuxCNC user manual [lin23].

Note

Some parameters in INI files are used directly by LinuxCNC, but others are custom parameters added to be used in HAL files, as explained in Section 3.8.2.3. Parameters from the INI file can be accessed in HAL files using the syntax [<section>]<option>, where [<section>] is the section name in square brackets and <option> is the corresponding option name within that section.

EMC Section: General configuration.

[EMC]
# General configuration

# Machine name, can be whatever you want.
# It will normally be displayed in the interface window.
MACHINE = CITIC Gantry Robot

# Debug flags, with 0 no debug messages will be printed.
DEBUG = 0

# Configuration version, for LinuxCNC 2.9 must be 1.1.
VERSION = 1.1

DISPLAY Section: User interface configuration. The available options may depend on the specific user interface used. In this case, we are using the AXIS user interface.

[DISPLAY]
# Graphical interface configuration

# Type of graphical interface to use.
DISPLAY = axis

# Coordinate system: RELATIVE or MACHINE.
POSITION_OFFSET = MACHINE

# Coordinates to display: COMMANDED or ACTUAL.
POSITION_FEEDBACK = ACTUAL

# Override the default cone/tool base size of .5 in the graphics display.
CONE_BASESIZE = 2.0

# Maximum feed override. A feed override of 2 means
# 200% of the programmed feed rate.
MAX_FEED_OVERRIDE = 2.000000

# Image to show on the welcome screen.
INTRO_GRAPHIC = linuxcnc.gif

# Maximum time in seconds for the welcome screen.
INTRO_TIME = 5

# Default directory for G-code programs.
PROGRAM_PREFIX = /home/gtec/linuxcnc/nc_files

# Increments for moving the robot with manual control.
INCREMENTS = 5mm 1mm .5mm .1mm .05mm .01mm .005mm

# The coordinate value that will be displayed: COMMANDED or ACTUAL
POSITION_FEEDBACK = ACTUAL

# Default linear velocity with manual control, in units per second.
DEFAULT_LINEAR_VELOCITY = 100.0

# Maximum linear velocity allowed with manual control, in units per second.
MAX_LINEAR_VELOCITY = 600.0

# Minimum linear velocity allowed with manual control, in units per second.
MIN_LINEAR_VELOCITY = 0.0

# Text editor to use when clicking File -> Edit.
EDITOR = mousepad

# 3D view geometry in the preview window.
GEOMETRY = XYZ

# Update time in milliseconds.
CYCLE_TIME = 100

# PyVCP panel description file
PYVCP = gui_panel.xml

# File to open when starting LinuxCNC (optional).
OPEN_FILE = ""

TASK Section: LinuxCNC task controller configuration. The task controller is responsible for communicating with the user interface, the motion planner, and the G-code interpreter. Currently, milltask is the only task controller available. For more information, consult the LinuxCNC user manual [lin23] and the milltask man page, also available at http://linuxcnc.org/docs/devel/html/man/man1/milltask.1.html.
```
74[TASK]
75# Task controller configuration
76
77# Task controller module, milltask.
78TASK = milltask
79
80# Execution period for milltask.
81CYCLE_TIME = 0.010
```

RS274NGC Section: RS274NGC (G-code) interpreter configuration.

[RS274NGC]
# RS274NGC interpreter configuration

# Interpreter variables file.
PARAMETER_FILE = linuxcnc.var

# Startup codes for the interpreter.
# The meaning of the currently set codes are:
# - G21: set the unit system to use millimeters
# - G40: turn tool compensation off
# - G90: set distance mode to absolute positioning
# - G94: set feed rate mode to units per minute
# - G64 P0.025: configure path blending with a deviation tolerance of 0.025
RS274NGC_STARTUP_CODE = G21 G40 G90 G94 G64 P0.025

EMCMOT Section: Motion controller configuration. The EMCMOT and SERVO_PERIOD parameters are not directly used by LinuxCNC but are used to configure the motion control module in the HAL file (see Section 3.8.2).

[EMCMOT]
# Motion controller configuration

# Motion controller module, motmod.
# Not used by LinuxCNC directly, used in the HAL file.
EMCMOT = motmod

# Number of seconds to wait for the motion module
# to confirm receipt of messages from the task module.
COMM_TIMEOUT = 1.0

# Servo thread period in nanoseconds
# Not used by LinuxCNC directly, used in the HAL file.
SERVO_PERIOD = 1000000

HAL Section: HAL configuration.

[HAL]
# Hardware Abstraction Layer (HAL) configuration

# Add HAL user interface pins.
HALUI = halui

# HAL files to execute when starting LinuxCNC.
# Can be specified multiple times.
HALFILE = citic_gantry_robot.hal

# HAL files to execute after loading the graphical interface.
POSTGUI_HALFILE = gui_panel.hal

# HAL files to execute when closing LinuxCNC.
# SHUTDOWN = shutdown.hal

HALUI Section: HALUI (HAL-based user interface) configuration. The only available option is MDI_COMMAND, which allows MDI commands to be executed via HAL signals. In our case we configure two commands which will be able to be executed via the PyVCP panel (see Section 3.8.4).

[HALUI]
# HAL user interface

# MDI_COMMAND can be specified multiple times.
# To execute it use the pin halui.mdi-command-NN,
# where NN is the command number.

# Go to zero position
MDI_COMMAND = G1 X0 Y0 Z0 F5000

# Go to stop position
MDI_COMMAND = G1 X5100 Y0 Z0 F5000

KINS Section: Kinematics configuration.
```
147[KINS]
148# Kinematics
149
150# Number of joints (motors).
151JOINTS = 4
152
153# Kinematics module
154# Not used by LinuxCNC directly, used in the HAL file.
155KINEMATICS = trivkins coordinates=XXYZ kinstype=BOTH
```
For machines with Cartesian geometries, such as gantry robots, where the movement of a joint is directly proportional to the movement of the axis, LinuxCNC includes the trivkins kinematics module.

The trivkins module accepts the coordinates parameter to specify the association of axis coordinate letters with the joint number. For example, with the parameter coordinates=XZ, JOINT_0 will be assigned to X and JOINT_1 to Z. In this parameter, the same axis letter can be specified multiple times, allowing multiple joints to be assigned to the same axis. In this case, it is also necessary to use the kinstype=B parameter. For instance, with the parameters coordinates=XX and kinstype=B, both JOINT_0 and JOINT_1 will be assigned to X.

For our gantry robot system, we use the parameters coordinates=XXYZ and kinstype=B, which means that the axes-joints mapping is the following:
- X axis → JOINT_0 and JOINT_1
- Y axis → JOINT_2
- Z axis → JOINT_3
For more information about the trivkins kinematics module, consult the kins man page, also available at http://linuxcnc.org/docs/devel/html/man/man9/kins.9.html.
APPLICATIONS Section: LinuxCNC allows applications to be launched at startup. These applications must be specified within the APPLICATIONS section using the APP option, which can be used multiple times. Applications will be launched either at the beginning, before the graphical interface starts, or after a delay specified by the DELAY option.
```
158[APPLICATIONS]
159# Additional applications. Can be specified multiple times.
160# APP=halscope 50000
161# APP=halscope 100000
```

TRAJ Section: Trajectory planner configuration.

[TRAJ]
# Trajectory planner configuration

# Controlled axes. Possible values: X, Y, Z, A, B, C, U, V, W.
# An axis can be specified more than once, e.g., XXYZ.
COORDINATES = XXYZ

# Units for linear axes.
LINEAR_UNITS = mm

# Units for rotary axes.
ANGULAR_UNITS = degree

# Maximum linear velocity, in units per second.
MAX_LINEAR_VELOCITY = 600.0

# Maximum linear acceleration, in units per second^2.
MAX_LINEAR_ACCELERATION = 200.0

EMCIO Section: Input/output controller configuration. This controls input/output tasks such as coolant, tool changes, and emergency stops.

[EMCIO]
# Input/Output (I/O) controller configuration

# Input/output controller module.
EMCIO = io

# Period at which EMCIO will run.
CYCLE_TIME = 0.100

AXIS_<i> Section: Configuration for axis <i>. Possible values for <i> include X, Y, Z, A, B, C, U, V, and W. Below we show the configuration for the X-axis. The configuration for the other axes is similar.

Important

When configuring the robot’s limits (MIN_LIMIT and MAX_LIMIT parameters), it is advisable to leave some margin beyond the desired workspace. If the robot is commanded to position itself at one of the limits, it can easily exceed that limit slightly. For example, if you want your robot to operate on the X-axis between X = 0 and X = 200, you could configure MIN_LIMIT = -5 and MAX_LIMIT = 205.

[AXIS_X]
# X axis configuration

# Note: The X axis motors (Igus MOT-EC-86-C-I-A) have a a maximum speed of
# 3000 rpm and a reduction gear with ratio 0.1. The X axis moves 144 mm/rev,
# therefore the maximum speed is: 144 * 0.1 * 3000 / 60 = 720.0 mm/s.

# Maximum axis velocity, in units per second.
MAX_VELOCITY = 600.0

# Maximum axis acceleration, in units per second^2.
MAX_ACCELERATION = 200.0

# Minimum limit for the axis, in machine units.
MIN_LIMIT = -5.0

# Maximum limit for the axis, in machine units.
MAX_LIMIT = 5300.0

JOINT_<n> Section: Configuration for joint (motor) <n>, where <n> is the joint number, ranging from 0 to (<num_joints> \(-\) 1). The value of <num_joints> is set in the JOINTS option of the KINS section.

Important

Both the joint and axis configurations include MAX_VELOCITY, MAX_ACCELERATION, MIN_LIMIT, and MAX_LIMIT parameters. When the robot is not homed, LinuxCNC uses the parameters from the joint sections, however, once the robot is homed, it uses the parameters from the axis sections.

The following code shows the configuration of joint 0, which corresponds to the X1 brushless motor. The parameters specified below the comments starting with “Custom configuration:” are not directly used by LinuxCNC, they are used to configure the motor parameters in the HAL file (see Section 3.8.2).

[JOINT_0]
# X1 motor configuration

# Motor type, LINEAR or ANGULAR.
TYPE = LINEAR

# Maximum following error, in machine units.
FERROR = 10

# Maximum following error at very slow speeds.
MIN_FERROR = 1

# Maximum motor velocity, in units per second.
MAX_VELOCITY = 50.0

# Maximum motor acceleration, in units per second^2.
MAX_ACCELERATION = 20.0

# Minimum motor limit, in machine units.
MIN_LIMIT = -5.0

# Maximum motor limit, in machine units.
MAX_LIMIT = 5300.0

# Position to which the joint will move when completing the homing process.
HOME = 0

# Used to define the 'home all' sequence.
# Note: the homing of the X joints must be synchronized, so we set their
# HOME_SEQUENCE options to -1. For more details check the LinuxCNC manual.
HOME_SEQUENCE = -1

# Home switch position, in machine units.
HOME_OFFSET = -15

# Initial homing search velocity, in units per second.
HOME_SEARCH_VEL = -25

# Final homing search velocity, in units per second.
HOME_LATCH_VEL = -5

# Final homing velocity, in units per second.
HOME_FINAL_VEL = 10

# Ignore limit switches during homing.
# Must be set to YES when using the same switch for limits and homing.
HOME_IGNORE_LIMITS = YES

# The switch is shared with another joint.
HOME_IS_SHARED = 0

# Use encoder index pulse for homing.
HOME_USE_INDEX = NO

# *****************************************
# Custom configuration: +-10V analog output
# *****************************************

# Maximum velocity in units per second.
ANALOGOUT_MAXLIM = 720

# Minimum velocity in units per second.
ANALOGOUT_MINLIM = -720

# Analog output scale. Vout = 10 * velocity / ANALOGOUT_SCALE.
# Maximum velocity in units per second that the motor can reach.
# Important: must be set to the same maximum speed configured
# in the motor controller in the drive profile section.
# Note: we set it negative to reverse the direction of the movement.
ANALOGOUT_SCALE = -720

# *****************************
# Custom configuration: Encoder
# *****************************

# Encoder scale. ENCODER_SCALE = counts / Position.
# The encoder does 1000 ppr (4000 cpr). The motor (Igus MOT-EC-86-C-I-A)
# has a reduction gear with ratio 0.1 and moves the axis at 144 mm/rev.
# Therefore the encoder scale is 4000 / (144 * 0.1) = 277.7778.
# Note: we set it negative to reverse the direction of the movement.
ENCODER_SCALE = -277.7778

# *************************
# Custom configuration: PID
# *************************

P = 40
I = 5
D = 0
FF0 = 0
FF1 = 1
FF2 = 0.01
BIAS = 0
DEADBAND = 0
MAX_OUTPUT = 0

The following code shows the configuration of joint 3, which corresponds to the Z stepper motor. As before, the parameters specified below the comments starting with “Custom configuration:” are not directly used by LinuxCNC, they are used to configure the motor parameters in the HAL file (see Section 3.8.2). These parameters differ from the previous ones because now a stepper motor is used.

[JOINT_3]
# Z motor configuration

# Motor/axis physical data:
# - Motor step angle: 1.8°
# - Z axis displacement: 4 mm/rev
# Configured operating parameters:
# - Motor step mode: 1/32
# - Step pulse period: 10us
#
# Therefore, the theoretical maximum speed of the Z axis is:
# 1 / (10e-6) * 4 / (16*360/1.8) = 125 mm/s = 125 * 60 / 4 rev/min = 1875 rev/min
#
# In practice the maximum speed is approximately 1200 mm/min =
# 20 mm/s = 300 rev/min. See engine specifications: the torque after
# 100 rev/min drastically reduces when increasing rev/min.

# Motor type, LINEAR or ANGULAR.
TYPE = LINEAR

# Maximum following error, in machine units.
FERROR = 1

# Maximum following error at very slow speeds.
MIN_FERROR = 1

# Maximum motor velocity, in units per second.
MAX_VELOCITY = 20.0

# Maximum motor acceleration, in units per second^2.
MAX_ACCELERATION = 80.0

# Minimum motor limit, in machine units.
MIN_LIMIT = -1050.0

# Maximum motor limit, in machine units.
MAX_LIMIT = 5

# Position to which the joint will move when completing the homing process.
HOME = 0

# Used to define the 'home all' sequence.
HOME_SEQUENCE = 3

# Home switch position, in machine units.
HOME_OFFSET = 15

# Initial homing search velocity, in units per second.
HOME_SEARCH_VEL = 10

# Final homing search velocity, in units per second.
HOME_LATCH_VEL = 1

# Final homing velocity, in units per second.
HOME_FINAL_VEL = -10

# Ignore limit switches during homing.
# Must be set to YES when using the same switch for limits and homing.
HOME_IGNORE_LIMITS = YES

# The switch is shared with another joint.
HOME_IS_SHARED = 0

# Use encoder index pulse for homing.
HOME_USE_INDEX = NO

# *******************************************
# Custom configuration: Step signal generator
# *******************************************

# Minimum duration of stable direction signal before a step begins, in nanoseconds.
DIRSETUP = 10000

# Minimum duration of stable direction signal after a step ends, in nanoseconds.
DIRHOLD = 10000

# Duration of the step signal, in nanoseconds.
STEPLEN = 5000

# Minimum interval between step signals, in nanoseconds.
STEPSPACE = 5000

# Note: for a STEPLEN and a STEPSPACE, the maximum theoretical speed when 
# using a 1/32 step mode is: 10^9/(STEPLEN+STEPSPACE) * 4 * 1.8 / (32 * 360)
# For STEPLEN = 5000 and STEPSPACE = 5000 this is:
# 10^9/10000 * 4 * 1.8 / (32 * 360) = 62.5 mm/s

# Converts from counts to position units. position = counts / STEP_SCALE.
# The Z axis moves at 4 mm/rev, the motor has a 1.8° step, and the Igus Dryve
# controller is configured to use 1/32 step mode. Therefore, the step scale is
# (32 * 360/1.8) / 4 = 1600.
STEP_SCALE = -1600

# Maximum acceleration, in units per second^2.
STEPGEN_MAXACCEL = 100

# *****************************
# Custom configuration: Encoder
# *****************************

# Encoder scale (ENCODER_SCALE = counts / Position).
# The encoder does 500 ppr (2000 cpr), and the Z axis moves at 4 mm/rev.
# Therefore, the encoder scale is 2000 / 4 = 500.
ENCODER_SCALE = -500

# *************************
# Custom configuration: PID
# *************************

P = 5
I = 0.25
D = 0
FF0 = 0
FF1 = 1
FF2 = 0
BIAS = 0
DEADBAND = 0
MAX_OUTPUT = 0

3.8.2. HAL Configuration¶

HAL is a fundamental component of LinuxCNC, serving as an interface between the machine’s software and hardware. It provides the infrastructure for communication among the system’s numerous software and hardware components. The HAL layer is composed of components that:

Are interconnected, processing incoming data and providing outputs to other components (e.g., the motion planning algorithm instructs the motors on their movement).
Possess the ability to communicate with hardware.
Always run periodically in one of the following ways:
- As real-time components, either with an execution frequency of a few microseconds (e.g., to advance a stepper motor or read an encoder) or with a frequency less than one millisecond (e.g., to adjust the planning of subsequent movements to complete a G-code instruction).
- As non-real-time user-space components, which can be interrupted or delayed if the rest of the system is busy or overloaded.

The HAL components included with LinuxCNC are listed in the user manual [lin23], also available at http://linuxcnc.org/docs/stable/html/hal/components.html. Additionally, each component has its own man page.

3.8.2.1. Basic Concepts¶

Pins and Signals: HAL is based on the same principles used to design electrical circuits and hardware systems, employing “pins” and “signals” to represent the flow of data between HAL modules or components. In summary:
- Pins can carry boolean, float, and signed or unsigned integer values.
- Pins have a direction: input (IN), output (OUT), or input/output (I/O).
- A signal identifies a connection between pins.
Fig. 29 from the LinuxCNC documentation [lin23] illustrates the concepts of components, pins, and signals in HAL. In the figure, pin pin3-out of component.0 connects to pins pin3-in and pin4-in of component.1 (via the signal-red signal), and pin pin1-out of component.1 connects to pin pin1-in of component.0 (via the signal blue signal).

Fig. 29 HAL Concept — Connection as electrical circuits. Source: LinuxCNC documentation [lin23].¶
Parameters: HAL components can have parameters, which are input or output settings not connected to any other component. There are two types of parameters:
- Input parameters: Values that the user can adjust and that remain fixed once configured.
- Output parameters: Values that cannot be adjusted by the user. They allow for internal signals to be monitored.
Functions: Each HAL component has one or more functions that must be executed to perform the component’s task. For these functions to be executed, they must be added to a thread.
Threads: Threads enable HAL component functions to be executed at specific time intervals. When a thread is created, the time interval at which its assigned functions will be executed is specified. Subsequently, the functions of the HAL components can be added to the thread to be executed in order at the thread’s defined time interval.

3.8.2.2. Interaction with HAL and Commands¶

HAL does not interact directly with the user. LinuxCNC provides various interfaces to configure or interact with HAL:

From .hal files.
From the command line using the halcmd command.
From Python scripts.
From C/C++ programs.

Configuration or interaction with HAL using any of these interfaces is performed through commands. The complete list of commands is detailed in the halcmd man page, also available at http://linuxcnc.org/docs/html/man/man1/halcmd.1.html. The most relevant commands are:

Note

Generally, each command must be specified on a single line. If a command needs to be split across multiple lines, a backslash (\) character can be used to indicate that the line continues to the next. The backslash must be the last character before the new line.

loadrt: Loads a HAL real-time component into the system. The basic syntax of the loadrt command is:
```
loadrt <component> <options>
```
where <component> is the name of the component and <options> are the component options. For example:
```
loadrt mux4 count=1
```
addf: Adds a function to a real-time thread. The syntax of the addf command is:
```
addf <function> <thread>
```
where <function> is the name of the function and <thread> is the thread to which it will be added. For example:
```
addf mux4.0 servo-thread
```
loadusr: Loads a non-real-time HAL component into the system. Non-real-time components are separate processes that can optionally communicate with other HAL components via pins and parameters. Real-time components cannot be loaded into non-real-time space. The syntax of the loadusr command is:
```
loadusr [<flags>] <command>
```
where <command> is the program command to be executed and <flags> can be one or more of the following options:
- -i: Ignore the program’s return value (with -w).
- -w: Wait for the program to finish.
- -W: Wait for the component to be ready. It is assumed that the component will have the same name as the first argument of the command.
- -Wn <name>: Wait for the component to be ready and assign it the name <name>. This is only applicable if the component has the -n option to assign a name.
For example:
```
loadusr -Wn spindle gs2_vfd -n spindle
```
net: Creates a connection between a signal and one or more pins. The syntax is as follows:
```
net <signal> <pin>
```
where <signal> is the name of the signal and <pin> is the name of a pin. If the signal does not exist, a new signal is created. The command also allows the use of the words <=, =>, and <=>, separated by a space from the pin names, to indicate the direction of the signals between pins. These words are ignored by the command and merely serve to facilitate readability.

The following rules must be met to connect a pin to a signal:
- An input (IN) pin can always be connected to a signal.
- An input/output (I/O) pin can be connected unless there is an output (OUT) pin on the signal.
- An output (OUT) pin can be connected only if there are no other output (OUT) or input/output (I/O) pins on the signal.
The same signal name can be used in multiple net commands to connect additional pins, provided the above rules are respected.

Examples:
- ```
 net home-x joint.0.home-sw-in <= parport.0.pin-11-in
```
  where home-x is the signal name, joint.0.home-sw-in is an input (IN) pin, <= is the optional direction arrow (ignored by the command), and parport.0.pin-11-in is an output (OUT) pin.
  
  This example can also be equivalently defined in HAL by two net commands:
```
net home-x <= parport.0.pin-11-in
net home-x => joint-0.home-sw-in
```
  Note
  
  As seen in this example, although the second pin’s name has the -in suffix, HAL treats it as an output pin. Therefore, when configuring pin connections in HAL, always refer to how the pin is configured in HAL, not just its name.
- ```
net xStep stepgen.0.out => parport.0.pin-02-out parport.0.pin-08-out
```
  where xStep is the signal name, stepgen.0.out is an output pin, and parport.0.pin-02-out and parport.0.pin-08-out are input pins.
  
  This example can also be defined in HAL by two net commands as follows:
```
net xStep <= stepgen.0.out
net xStep => parport.0.pin-02-out parport.0.pin-08-out
```
setp: Sets the value of a pin or parameter. Valid values depend on the pin or parameter’s data type. The syntax of this command is:
```
setp <name> <value>
```
where <name> is the name of the pin or parameter and <value> is the value to which it is to be set. The command will fail if <name> does not exist as a pin or parameter, if it is a read-only parameter, if it is an output (OUT) pin, if it is a pin that is already connected to a signal, or if <value> is not a valid value for the pin or parameter’s data type.
sets: Sets the value of a signal. The syntax is:
```
sets <signal> <value>
```
where <signal> is the name of the signal and <value> is the value to which it is to be set. The command will fail if <signal> does not exist as a signal, if the signal is already connected to an output (OUT) pin, or if <value> is not a valid value for the signal’s data type.
unlinkp: Unlinks a pin from its connected signal. The syntax of the command is:
```
unlinkp <name>
```
where <name> is the name of the pin. If the pin does not have a connected signal, nothing happens. The command will fail if <name> does not exist as a pin.

3.8.2.3. .hal File Format¶

A .hal file is a plain text file containing HAL commands. Comments can be included by starting lines with the hash symbol (#). Options from the .ini file can be accessed with the syntax [<section>]<option>, where [<section>] is the section name in square brackets and <option> is the corresponding option name within that section.

3.8.2.4. `citic_gantry_robot.hal` Configuration File¶

As noted in Section 3.6.2, a LinuxCNC configuration includes at least one .ini file and one .hal file. Below we show several fragments of the citic_gantry_robot.hal configuration file, the main HAL file for the citic_gantry_robot.ini file as detailed in Section 3.8.1. Unlike the .ini format, the .hal format does not have a section syntax, however, for clarity, the file is presented below divided into different parts.

Note

The documentation of the different HAL components and its pins can be found in the LinuxCNC man pages [lin23]. The components and pins available in the running system can be also explored using the halcmd or halshow tools. See Section 3.8.3 for more details.

Load modules, add functions to threads, and other initial configurations:

# -----------------------------------------------------------------------------
# Modules
# -----------------------------------------------------------------------------

# **********
# Kinematics
# **********

loadrt [KINS]KINEMATICS


# **************
# Motion control
# **************
# Note that with the option "servo_period_nsec" the module will create a
# thread called "servo-thread".

loadrt [EMCMOT]EMCMOT servo_period_nsec=[EMCMOT]SERVO_PERIOD num_joints=[KINS]JOINTS

# Add motion functions to the "servo-thread" thread
addf motion-command-handler servo-thread
addf motion-controller servo-thread


# ********
# Hostmot2
# ********
# hostmot2 is the control module for MESA boards

loadrt hostmot2


# *******
# hm2_eth
# *******
# hm2_eth is the low-level controller for MESA boards with Ethernet
# (Mesa Electronics Ethernet Anything IO boards)

loadrt hm2_eth board_ip="192.168.1.121" config="num_encoders=4 num_pwmgens=0 num_stepgens=1"

# Set the watchdog timeout for the MESA 7I96S board
setp hm2_7i96s.0.watchdog.timeout_ns 5000000

# Configure the DPLL (digital phase locked loop) of the hostmot2 module
setp hm2_7i96s.0.dpll.01.timer-us -100
setp hm2_7i96s.0.stepgen.timer-number 1
setp hm2_7i96s.0.encoder.timer-number 1

# Add functions to the "servo-thread" thread
addf hm2_7i96s.0.read servo-thread
addf hm2_7i96s.0.write servo-thread


# **************
# Classic Ladder
# **************
loadrt classicladder_rt

addf classicladder.0.refresh servo-thread

# load classic ladder project
loadusr classicladder myladder.clp --nogui


# ***
# pid
# ***
# We create a PID controller for each motor

loadrt pid names=pid.x1,pid.x2,pid.y,pid.z

addf pid.x1.do-pid-calcs servo-thread
addf pid.x2.do-pid-calcs servo-thread
addf pid.y.do-pid-calcs servo-thread
addf pid.z.do-pid-calcs servo-thread


# ***********
# estop_latch
# ***********
# module to handle the emergency stop

loadrt estop_latch
addf estop-latch.0 servo-thread


# *******
# oneshot
# *******
# one-shot pulse generator

loadrt oneshot names=oneshot.analog-start,oneshot.reset

setp oneshot.analog-start.width 0.1
setp oneshot.reset.width 0.1

addf oneshot.analog-start servo-thread
addf oneshot.reset servo-thread

# *****
# logic
# *****
# Component providing configurable logic functions

# We define the following functions:
# - logic.error: OR gate with 4 inputs
# - logic.alert: OR gate with 4 inputs
# - logic.fault: OR and NOR gates with 3 inputs
# - logic.analog-enable: AND gate with 3 inputs
# - logic.analog-motors-start: AND gate with 3 inputs
# - logic.gui-goto-disable: NAND gate with 3 inputs
loadrt logic \
    names=logic.error,logic.alert,logic.fault,logic.analog-enable,logic.analog-motors-start,logic.gui-goto-disable \
    personality=0x204,0x204,0x1203,0x103,0x103,0x803

addf logic.error servo-thread
addf logic.alert servo-thread
addf logic.fault servo-thread
addf logic.analog-enable servo-thread
addf logic.analog-motors-start servo-thread
addf logic.gui-goto-disable servo-thread


# *****
# scale
# *****
loadrt scale names=scale.x.vel-rpm,scale.y.vel-rpm,scale.z.vel-rpm

addf scale.x.vel-rpm servo-thread
addf scale.y.vel-rpm servo-thread
addf scale.z.vel-rpm servo-thread

# ***
# not
# ***
loadrt not names=not.fault
addf not.fault servo-thread

Brushless motor configuration: The configuration for the brushless motor for the joint 0 (motor X1) is shown below. Configuration for the other brushless motors (joint 1 and joint 2) is similar.

# -----------------------------------------------------------------------------
# AXIS X --- JOINT 0
# -----------------------------------------------------------------------------

# PID controller parameters
setp pid.x1.Pgain     [JOINT_0]P
setp pid.x1.Igain     [JOINT_0]I
setp pid.x1.Dgain     [JOINT_0]D
setp pid.x1.bias      [JOINT_0]BIAS
setp pid.x1.FF0       [JOINT_0]FF0
setp pid.x1.FF1       [JOINT_0]FF1
setp pid.x1.FF2       [JOINT_0]FF2
setp pid.x1.deadband  [JOINT_0]DEADBAND
setp pid.x1.maxoutput [JOINT_0]MAX_OUTPUT
setp pid.x1.error-previous-target true

# +-10V analog output parameters
setp hm2_7i96s.0.7i77.0.1.analogout0-maxlim [JOINT_0]ANALOGOUT_MAXLIM
setp hm2_7i96s.0.7i77.0.1.analogout0-minlim [JOINT_0]ANALOGOUT_MINLIM
setp hm2_7i96s.0.7i77.0.1.analogout0-scalemax [JOINT_0]ANALOGOUT_SCALE

# Encoder parameters
setp hm2_7i96s.0.encoder.00.counter-mode 0
setp hm2_7i96s.0.encoder.00.filter 1
setp hm2_7i96s.0.encoder.00.scale [JOINT_0]ENCODER_SCALE

# Connect PID and motion signals
net pid-x1-output <= pid.x1.output
net pid-x1-output => hm2_7i96s.0.7i77.0.1.analogout0

net x1-enable <= joint.0.amp-enable-out
net x1-enable => pid.x1.enable

net x1-pos-cmd <= joint.0.motor-pos-cmd
net x1-pos-cmd => pid.x1.command

net x1-enc-pos <= hm2_7i96s.0.encoder.00.position
net x1-enc-pos => pid.x1.feedback
net x1-enc-pos => joint.0.motor-pos-fb

# Connect home / limit signals
net x1-sw <= hm2_7i96s.0.gpio.000.in_not
net x1-sw => joint.0.home-sw-in
net x1-sw => joint.0.neg-lim-sw-in

Stepper motor configuration: The configuration for the stepper motor for the joint 3 (motor Z1) is shown below.

# -----------------------------------------------------------------------------
# AXIS Z --- JOINT 3
# -----------------------------------------------------------------------------

# PID controller parameters
setp pid.z.Pgain     [JOINT_3]P
setp pid.z.Igain     [JOINT_3]I
setp pid.z.Dgain     [JOINT_3]D
setp pid.z.bias      [JOINT_3]BIAS
setp pid.z.FF0       [JOINT_3]FF0
setp pid.z.FF1       [JOINT_3]FF1
setp pid.z.FF2       [JOINT_3]FF2
setp pid.z.deadband  [JOINT_3]DEADBAND
setp pid.z.maxoutput [JOINT_3]MAX_OUTPUT
setp pid.z.error-previous-target true

# Step generator parameters
setp hm2_7i96s.0.stepgen.00.control-type   1  # Velocity control
setp hm2_7i96s.0.stepgen.00.step_type      0  # Step/dir
setp hm2_7i96s.0.stepgen.00.dirsetup       [JOINT_3]DIRSETUP
setp hm2_7i96s.0.stepgen.00.dirhold        [JOINT_3]DIRHOLD
setp hm2_7i96s.0.stepgen.00.steplen        [JOINT_3]STEPLEN
setp hm2_7i96s.0.stepgen.00.stepspace      [JOINT_3]STEPSPACE
setp hm2_7i96s.0.stepgen.00.position-scale [JOINT_3]STEP_SCALE
setp hm2_7i96s.0.stepgen.00.maxaccel       [JOINT_3]STEPGEN_MAXACCEL

# Encoder parameters
setp hm2_7i96s.0.encoder.03.counter-mode 0
setp hm2_7i96s.0.encoder.03.filter 1
setp hm2_7i96s.0.encoder.03.scale [JOINT_3]ENCODER_SCALE

# Connect PID and motion signals
net pid-z-output <= pid.z.output
net pid-z-output => hm2_7i96s.0.stepgen.00.velocity-cmd

net z-enable <= joint.3.amp-enable-out
net z-enable => pid.z.enable

net z-pos-cmd <= joint.3.motor-pos-cmd
net z-pos-cmd => pid.z.command

net z-enc-pos <= hm2_7i96s.0.encoder.03.position
net z-enc-pos => pid.z.feedback
net z-enc-pos => joint.3.motor-pos-fb

# Connect home / limit signals
net z-sw <= hm2_7i96s.0.gpio.003.in_not
net z-sw => joint.3.home-sw-in
net z-sw => joint.3.neg-lim-sw-in

Other configurations: Configuration for other functions such as:

Hazard light: Turn on a safety light when the machine is in motion.
Analog enable: Enable the MESA 7I77 ± 10 V analog outputs.
Step generator enable: Enable the MESA 7I96S step / direction outputs.
igus® Dryve enable inputs: Set the enable signal to high for all igus® Dryve controllers.
igus® Dryve status signals: Read ready/alert/error states from all igus® Dryve controllers.
Analog rotation program start: Generate a oneshot pulse when the igus® Dryve controllers of brushless motors are ready to start the “ADR (Analogue Rotation with Direction Definition)” program of the motor controllers.
External emergency stop: Handle the external emergency stop input signal.
Fault signal: Set a fault signal to high if any controller signals an error or alert or the external emergency stop signal is activated.
Emergency stop (ESTOP): Manage the fault / enable / reset signals.
LED control via Classic Ladder: Link classic ladder pins to the MESA 7I96S pins of the red/yellow/green LEDs. See Section 3.8.5.
GUI disable buttons: Set the disable signal of PyVCP buttons based on the machine state.
Velocity signals: Read velocity signals for all axes, to display the motor RPM in the PyVCP panel. See Section 3.8.4.

# -----------------------------------------------------------------------------
# Miscellaneous signals
# -----------------------------------------------------------------------------

# Door warning light
setp hm2_7i96s.0.7i77.0.0.output-15 1

# Analog enable
net x1-enable => logic.analog-enable.in-00
net x2-enable => logic.analog-enable.in-01
net y-enable => logic.analog-enable.in-02

net logic.analog-enable <= logic.analog-enable.and
net logic.analog-enable => hm2_7i96s.0.7i77.0.1.analogena

# Step generator enable
net z-enable => hm2_7i96s.0.stepgen.00.enable

# Enable signal
# The MESA 7i77 output 0 connects with the enable inputs (DI 7) in the
# Igus Dryve controllers. We have to set the Igus Dryve enable inputs
# to high to enable the operation of the motors.
net machine-on <= halui.machine.is-on
net machine-on => hm2_7i96s.0.7i77.0.0.output-00

# Igus Dryve alert/error/ready signals
net x1-ready <= hm2_7i96s.0.7i77.0.0.input-00
net x1-alert <= hm2_7i96s.0.7i77.0.0.input-01
net x1-error <= hm2_7i96s.0.7i77.0.0.input-02
net x2-ready <= hm2_7i96s.0.7i77.0.0.input-03
net x2-alert <= hm2_7i96s.0.7i77.0.0.input-04
net x2-error <= hm2_7i96s.0.7i77.0.0.input-05
net y-ready <= hm2_7i96s.0.7i77.0.0.input-06
net y-alert <= hm2_7i96s.0.7i77.0.0.input-07
net y-error <= hm2_7i96s.0.7i77.0.0.input-08
net z-alert <= hm2_7i96s.0.7i77.0.0.input-09
net z-error <= hm2_7i96s.0.7i77.0.0.input-10

# Analog rotation program start signal (X1, X2, and Y motors)
# The MESA 7i77 output 1 is connected with the start inputs (DI 6) in the
# Igus Dryve controllers. We have to send a pulse to the start inputs to
# run the analog rotation program configured in the Igus Dryve controllers
# for X1, X2, and Y motors.
net x1-ready => logic.analog-motors-start.in-00
net x2-ready => logic.analog-motors-start.in-01
net y-ready => logic.analog-motors-start.in-02

net analog-motors-ready <= logic.analog-motors-start.and
net analog-motors-ready => oneshot.analog-start.in

net analog-motors-start-pulse <= oneshot.analog-start.out
net analog-motors-start-pulse => hm2_7i96s.0.7i77.0.0.output-01

# External emergency stop (estop) signal
net remote-estop <= hm2_7i96s.0.7i77.0.0.input-13

# Error signal
net x1-error => logic.error.in-00
net x2-error => logic.error.in-01
net y-error => logic.error.in-02
net z-error => logic.error.in-03

net error <= logic.error.or

# Alert signal
net x1-alert => logic.alert.in-00
net x2-alert => logic.alert.in-01
net y-alert => logic.alert.in-02
net z-alert => logic.alert.in-03

net alert <= logic.alert.or

# Fault signal
# We set the fault signal if any controller signals an error or alert
# or if the user press the emergency stop (estop) button
net error => logic.fault.in-00
net alert => logic.fault.in-01
net remote-estop => logic.fault.in-02

net fault <= logic.fault.or
net not-fault <= logic.fault.nor

# Emergency stop (ESTOP)
net user-enable <= iocontrol.0.user-enable-out
net user-enable => estop-latch.0.ok-in

net user-request-enable <= iocontrol.0.user-request-enable
net user-request-enable => estop-latch.0.reset

net emc-enable <= estop-latch.0.ok-out
net emc-enable => iocontrol.0.emc-enable-in

net fault => estop-latch.0.fault-in

# Classic Ladder program for controlling LEDS
net estop <= halui.estop.is-activated

net machine-on => classicladder.0.in-00
net estop => classicladder.0.in-01
net alert => classicladder.0.in-02
net error => classicladder.0.in-03

net led-red <= classicladder.0.out-00
net led-red => hm2_7i96s.0.ssr.00.out-00

net led-yellow <= classicladder.0.out-01
net led-yellow => hm2_7i96s.0.ssr.00.out-01

net led-green <= classicladder.0.out-02
net led-green => hm2_7i96s.0.ssr.00.out-02

# Disable gui goto buttons
# The goto buttons will be disabled except when robot on, idle, and in teleop
# mode (i.e., not joint mode)
net is-idle <= halui.program.is-idle
net is-teleop <= halui.mode.is-teleop

net is-idle => logic.gui-goto-disable.in-00
net is-teleop => logic.gui-goto-disable.in-01
net machine-on => logic.gui-goto-disable.in-02

net gui-goto-disable <= logic.gui-goto-disable.nand

# Velocities
net x1-vel-cmd <= joint.0.vel-cmd
net x2-vel-cmd <= joint.1.vel-cmd
net y-vel-cmd <= joint.2.vel-cmd
net z-vel-cmd <= joint.3.vel-cmd

3.8.3. HAL Tools¶

Several HAL tools are available for real-time visualization and diagnosis of pin states. The most notable ones are described below; for a complete list of tools, consult the LinuxCNC user manual [lin23].

3.8.3.1. Halcmd¶

halcmd is a command-line tool for interacting with HAL. When halcmd is executed, the following command line will appear:

halcmd:

This prompt allows you to enter and execute HAL commands. Besides the commands detailed previously in Section 3.8.2, other commands such as show, list, or save can be very useful. These commands enable printing various elements defined in HAL, such as pins, parameters, threads, etc. The complete list of commands is detailed in the halcmd man page, also available at http://linuxcnc.org/docs/html/man/man1/halcmd.1.html.

3.8.3.2. Halshow¶

halshow is a graphical tool that allows viewing and monitoring HAL components such as pins, parameters, signals, and functions. This tool is shown in Figures 30 and 31. The tool has the following main elements:

A tree view displaying HAL pins, parameters, signals, functions, etc. This view is located on the left side of the window, as seen in Figures 30 and 31.
A text input field for executing HAL commands, located at the bottom, as shown in Figures 30 and 31.
A “SHOW” tab where information about the selected element in the tree view is displayed, as shown in Fig. 30.
A “WATCH” tab where you can monitor and set values of HAL pins or parameters. Elements can be added here by clicking on them in the tree view, as shown in Fig. 31.
A “SETTINGS” tab with various options such as refresh interval or display format of parameters.

The File menu allows saving monitored elements from the “WATCH” tab to a file, as well as loading an existing list of elements to monitor from a file.

You can open the Halshow tool from the AXIS graphical interface by clicking on Machine ‣ Show Hal Configuration.

../../_images/halshow_show.png — Fig. 30 Halshow tool showing the “SHOW” tab.¶

../../_images/halshow_watch.png — Fig. 31 Halshow tool showing the “WATCH” tab.¶

3.8.3.3. Halscope¶

halscope is a graphical tool that provides an oscilloscope for HAL. It allows capturing and displaying the values of pins, signals, and parameters over a period of time. This tool is shown in Fig. 32. The File menu allows saving the current configuration or opening a previously saved configuration. When halscope is closed, the configuration is automatically saved to the autosave.halscope file.

../../_images/hal_oscilloscope.png — Fig. 32 Halscope tool showing the values of `joint.0.motor-pos-cmd` (motor position commanded by LinuxCNC) and `joint.0.motor-pos-fb` (motor position read from the encoder) over time.¶

You can open the Halscope tool from the AXIS graphical interface by clicking on Machine ‣ Hal scope.

3.8.3.4. Halreport¶

halreport is a command-line tool that generates a report on HAL connections. The command’s help output is as follows:

Usage:
    halreport -h | --help (this help)
or
    halreport [outfilename]

The generated report displays all signal connections and indicates potential issues. The information included in the report, among other things, is:

System description and kernel version.
Signals and their connected output, input, and input/output pins.
Functions, threads, and addf commands corresponding to each pin.
Real names for pins that use aliases.
Signals without an output.
Signals without inputs.
Functions not added to threads.
Warnings about components marked as obsolete.

3.8.4. PyVCP (Python Virtual Control Panel)¶

PyVCP (Python Virtual Control Panel) is a LinuxCNC component that allows creating custom graphical user interface panels to complement the main LinuxCNC interface. These panels can be used to provide additional controls, indicators, and displays that can be tailored to specific machine requirements. The PyVCP GUI components can be connected to HAL pins for real-time interaction with the machine. Some of the PyVCP components are:

LED indicators: Visual status indicators that can show the state of a HAL pin.
Buttons: Interactive controls that can set the value of a HAL pin.
Bar displays: Graphical representations of float HAL pins.
Labels: Text displays for showing information.
Tables: Layout containers for organizing components in rows and columns.

For the complete list of components and their configuration options, consult the PyVCP section of the LinuxCNC user manual [lin23] (https://linuxcnc.org/docs/html/gui/pyvcp.html).

For our gantry robot system, we configured a PyVCP panel with LED status indicators, motor RPM displays, motor controller status indicators, and some convenient control buttons. Fig. 33 shows the LinuxCNC AXIS interface with the custom PyVCP panel integrated on the right side.

../../_images/linuxcnc_gui_pyvcp.png — Fig. 33 LinuxCNC AXIS interface showing the custom PyVCP panel with LED indicators, motor RPM displays, controller status, and control buttons.¶

3.8.4.1. PyVCP Configuration¶

PyVCP is configured in the DISPLAY section of the INI file using the PYVCP parameter:

PYVCP = gui_panel.xml

This parameter specifies the XML file that defines the panel layout and components. The XML file must be located in the same directory as the configuration files.

By default the panel appears at the right of the AXIS user interface. The panel can be also configured to appear at the bottom of the AXIS user interface by specifying the following in the [DISPLAY] section of the INI file:

PYVCP_POSITION = BOTTOM

3.8.4.2. `gui_panel.xml` Configuration File¶

The gantry robot configuration uses a PyVCP panel that provides some monitoring and control capabilities. The panel is defined in the gui_panel.xml file and includes several functional sections. Below are the different sections of the gui_panel.xml configuration file.

LED Indicators: Displays the main system status with three colored LEDs.

    <labelframe text="LED indicators">
        <label>
            <!-- vertical space -->
            <font>("DejaVu Sans",2)</font>
        </label>
        <table flexible_rows="[1]" flexible_columns="[1,3]">
            <tablesticky sticky="ns"/>
            <tablerow/>
            <led>
                <size>30</size>
                <on_color>"green2"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-green"</halpin>
            </led>
            <led>
                <size>30</size>
                <on_color>"yellow"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-yellow"</halpin>
            </led>
            <led>
                <size>30</size>
                <on_color>"red"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-red"</halpin>
            </led>
        </table>
        <label>
            <!-- vertical space -->
            <font>("DejaVu Sans",2)</font>
        </label>
    </labelframe>

Motor RPM: Shows real-time motor RPM speeds using bar displays:

    <labelframe text="Motor RPM">
        <relief>SUNKEN</relief>
        <bd>2</bd>
        <label>
            <text>"X"</text>
        </label>
        <bar>
            <halpin>"x-rpm"</halpin>
            <min_>-3000</min_>
            <max_>3000</max_>
        </bar>
        <label>
            <text>"Y"</text>
        </label>
        <bar>
            <halpin>"y-rpm"</halpin>
            <min_>-3000</min_>
            <max_>3000</max_>
        </bar>
        <label>
            <text>"Z"</text>
        </label>
        <bar>
            <halpin>"z-rpm"</halpin>
            <min_>-300</min_>
            <max_>300</max_>
        </bar>
    </labelframe>

Motor Controllers: Displays error and alert status for each motor controller, and allows sending a reset signal to the motor controllers.

    <labelframe text="Motor controllers">
        <relief>SUNKEN</relief>
        <bd>2</bd>
        <table flexible_rows="[1,2,3]" flexible_columns="[1,2,3,4,5]">
            <tablesticky sticky="ns"/>
            <tablerow/>
            <label></label>
            <label>
                <text>"X1"</text>
                <font>("DejaVu Sans",12)</font>
            </label>
            <label>
                <text>"X2"</text>
                <font>("DejaVu Sans",12)</font>
            </label>
            <label>
                <text>"Y1"</text>
                <font>("DejaVu Sans",12)</font>
            </label>
            <label>
                <text>"Z"</text>
                <font>("DejaVu Sans",12)</font>
            </label>

            <tablerow/>
            <label>
                <text>"Error"</text>
                <font>("DejaVu Sans",12)</font>
            </label>
            <led>
                <size>20</size>
                <on_color>"red"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-x1-error"</halpin>
            </led>
            <led>
                <size>20</size>
                <on_color>"red"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-x2-error"</halpin>
            </led>
            <led>
                <size>20</size>
                <on_color>"red"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-y-error"</halpin>
            </led>
            <led>
                <size>20</size>
                <on_color>"red"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-z-error"</halpin>
            </led>

            <tablerow/>
            <label>
                <text>"Alert"</text>
                <font>("DejaVu Sans",12)</font>
            </label>
            <led>
                <size>20</size>
                <on_color>"yellow"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-x1-alert"</halpin>
            </led>
            <led>
                <size>20</size>
                <on_color>"yellow"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-x2-alert"</halpin>
            </led>
            <led>
                <size>20</size>
                <on_color>"yellow"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-y-alert"</halpin>
            </led>
            <led>
                <size>20</size>
                <on_color>"yellow"</on_color>
                <off_color>"gray50"</off_color>
                <halpin>"led-z-alert"</halpin>
            </led>
        </table>
        <label>
            <!-- vertical space -->
            <font>("DejaVu Sans",2)</font>
        </label>
        <button>
            <halpin>"gui-controllers-reset-button"</halpin>
            <disable_pin>True</disable_pin>
            <text>"Reset"</text>
        </button>
    </labelframe>

Control Buttons: Provides convenient buttons for common operations:

    <button>
        <halpin>"gui-goto-zero-position-button"</halpin>
        <disable_pin>True</disable_pin>
        <text>"Go to zero"</text>
    </button>
    <label>
        <!-- vertical space -->
        <font>("DejaVu Sans",2)</font>
    </label>
    <button>
        <halpin>"gui-goto-stop-position-button"</halpin>
        <disable_pin>True</disable_pin>
        <text>"Go to stop position"</text>
    </button>

3.8.4.3. PyVCP Integration with HAL¶

Each PyVCP component that needs to interact with the machine creates a corresponding HAL pin. These pins can be connected to other HAL components in a .hal configuration file to provide the desired functionality. This file has to be specified in the POSTGUI_HALFILE parameter of the HAL section of the INI file.

Examples of PyVCP components and the corresponding HAL pins are:

LED components create input pins (e.g., pyvcp.led-green, pyvcp.led-red)
Button components create output pins (e.g., pyvcp.gui-goto-zero-position-button). Additionally, when the disable_pin parameter is set to true, a disabled pin is created (e.g., pyvcp.gui-goto-zero-position-button.disabled).
Bar displays create input pins for displaying values (e.g., pyvcp.x-rpm, pyvcp.y-rpm)

In our case, the corresponding PyVCP panel .hal file is gui_panel.hal.

3.8.4.4. `gui_panel.hal` Configuration File¶

The .hal file for our PyVCP panel is gui_panel.hal and is specified in the POSTGUI_HALFILE parameter of the HAL section of the INI file as shown in Section 3.8.1.2. This file is used to connect the PyVCP components to the HAL pins. The file is shown below.

# gui_panel.hal -- must be loaded as a postgui HAL file

# Indicator LEDs
net led-red => pyvcp.led-red
net led-yellow => pyvcp.led-yellow
net led-green => pyvcp.led-green


# Motor controller LEDs
net x1-error => pyvcp.led-x1-error
net x2-error => pyvcp.led-x2-error
net y-error => pyvcp.led-y-error
net z-error => pyvcp.led-z-error

net x1-alert => pyvcp.led-x1-alert
net x2-alert => pyvcp.led-x2-alert
net y-alert => pyvcp.led-y-alert
net z-alert => pyvcp.led-z-alert

# Motor controller reset button
net not-fault => pyvcp.gui-controllers-reset-button.disable

net gui-reset-button <= pyvcp.gui-controllers-reset-button
net gui-reset-button => oneshot.reset.in

net reset-pulse <= oneshot.reset.out
net reset-pulse => hm2_7i96s.0.7i77.0.0.output-02


# Go to buttons
net gui-goto-zero-button <= pyvcp.gui-goto-zero-position-button
net gui-goto-zero-button => halui.mdi-command-00
net gui-goto-disable => pyvcp.gui-goto-zero-position-button.disable

net gui-goto-stop-button <= pyvcp.gui-goto-stop-position-button
net gui-goto-stop-button => halui.mdi-command-01
net gui-goto-disable => pyvcp.gui-goto-stop-position-button.disable


# Scale to convert from velocity in mm/s to rpm
# - For axes X and Y:
#   The axes move 144 mm/rev and the motors have a gearbox with a
#   gear rate of 0.1. Hence the scale is: 60/(0.1*144) = 4.166666666666667
# - For axis Z:
#   The axis moves 4 mm/rev. Hence the scale is 60/4 = 15
setp scale.x.vel-rpm.gain 4.166666666666667
setp scale.x.vel-rpm.offset 0

setp scale.y.vel-rpm.gain 4.166666666666667
setp scale.y.vel-rpm.offset 0

setp scale.z.vel-rpm.gain 15
setp scale.z.vel-rpm.offset 0


# Connect axis velocities with scale components
net x1-vel-cmd => scale.x.vel-rpm.in
net y-vel-cmd => scale.y.vel-rpm.in
net z-vel-cmd => scale.z.vel-rpm.in


# Connect rpm with pyvcp display
net axis-x-motor-rpm <= scale.x.vel-rpm.out
net axis-x-motor-rpm => pyvcp.x-rpm

net axis-y-motor-rpm <= scale.y.vel-rpm.out
net axis-y-motor-rpm => pyvcp.y-rpm

net axis-z-motor-rpm <= scale.z.vel-rpm.out
net axis-z-motor-rpm => pyvcp.z-rpm

3.8.5. Ladder Logic Programming¶

LinuxCNC includes the ClassicLadder component, a free implementation of a ladder interpreter published under the LGPL.

Ladder logic, or the ladder programming language, is a method for drawing electrical logic diagrams. Originally conceived to describe control systems using relays, this approach has become a widely used graphical language for programming PLC devices. It derives its name from the fact that programs in this language resemble ladders, with two vertical rails and a series of horizontal rungs between them.

To use ClassicLadder, you must load the classicladder_rt real-time module in HAL and add the classicladder.0.refresh function to the servo-thread thread using the following commands:

loadrt classicladder_rt addf classicladder.0.refresh servo-thread

Once this is done, you can open the ClassicLadder graphical interface with the system command classicladder, or from the AXIS interface by clicking on File ‣ Ladder Editor…. The ClassicLadder graphical interface allows you to create ladder logic programs, as well as view the logical status of the different program components. This interface is composed of several windows, as shown in Fig. 34.

../../_images/linuxcnc_ladder_editor.png — Fig. 34 ClassicLadder graphical interface.¶

In our gantry robot system, we use ClassicLadder to program the operation of the LED indicator panel. The program created with ClassicLadder has been saved in the myladder.clp file. To use it in LinuxCNC, we use the following commands in the citic_gantry_robot.hal file to load the classicladder_rt module and load the myladder.clp file:

loadrt classicladder_rt

addf classicladder.0.refresh servo-thread

# load classic ladder project
loadusr classicladder myladder.clp --nogui

The LinuxCNC user manual [lin23] includes a detailed guide to ClassicLadder. Another good introduction to ClassicLadder is The Feral Engineer’s “Classicladder tutorials” series on YouTube: https://www.youtube.com/playlist?list=PLTYvfbjLClpfAfJSGhZUecgXFwVPY5e09.

3.8. LinuxCNC Configuration¶

3.8.1. INI Configuration¶

3.8.1.1. .ini Configuration File Format¶

3.8.1.2. citic_gantry_robot.ini Configuration File¶

3.8.2. HAL Configuration¶

3.8.2.1. Basic Concepts¶

3.8.2.2. Interaction with HAL and Commands¶

3.8.2.3. .hal File Format¶

3.8.2.4. citic_gantry_robot.hal Configuration File¶

3.8.3. HAL Tools¶

3.8.3.1. Halcmd¶

3.8.3.2. Halshow¶

3.8.3.3. Halscope¶

3.8.3.4. Halreport¶

3.8.4. PyVCP (Python Virtual Control Panel)¶

3.8.4.1. PyVCP Configuration¶

3.8.4.2. gui_panel.xml Configuration File¶

3.8.4.3. PyVCP Integration with HAL¶

3.8.4.4. gui_panel.hal Configuration File¶

3.8.5. Ladder Logic Programming¶

3.8.1.2. `citic_gantry_robot.ini` Configuration File¶

3.8.2.4. `citic_gantry_robot.hal` Configuration File¶

3.8.4.2. `gui_panel.xml` Configuration File¶

3.8.4.4. `gui_panel.hal` Configuration File¶