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 mesa_7i96s_7i77_xy 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. Example: `mesa_7i96s_7i77_xy.ini` Configuration File¶

Below are the different sections of the mesa_7i96s_7i77_xy.ini configuration file, with comments explaining the purpose of each parameter. Note that not all available parameters are specified in some sections. For a complete list of parameters and their documentation, consult the LinuxCNC user manual [lin23].

EMC Section: General configuration.

[EMC]
# General configuration

# Machine name, usually displayed in the interface window.
MACHINE = mesa_7i96s

# Debug flags, 0 will not print debug messages.
DEBUG = 0

# Configuration version, for LinuxCNC 2.9 it should 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]
# Graphic interface configuration

# Type of graphic interface to use.
DISPLAY = axis

# Coordinate system: RELATIVE or MACHINE.
POSITION_OFFSET = MACHINE

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

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

# Image to display on the splash screen.
INTRO_GRAPHIC = linuxcnc.gif

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

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

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

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

# Default linear velocity with manual control.
DEFAULT_LINEAR_VELOCITY = 1.000000

# Maximum allowed linear velocity with manual control.
MAX_LINEAR_VELOCITY = 10.000000

# Minimum allowed linear velocity with manual control.
MIN_LINEAR_VELOCITY = 0.000000

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

# Geometry of the 3D view in the preview window.
GEOMETRY = XY

# Refresh time in milliseconds.
CYCLE_TIME = 100

# 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.
```
67[TASK]
68# Task controller configuration
69
70# Task controller module, milltask.
71TASK = milltask
72
73# Execution period of milltask.
74CYCLE_TIME = 0.010
```

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

[RS274NGC]
# RS274NGC interpreter configuration

# Interpreter variable file.
PARAMETER_FILE = linuxcnc.var

# Startup codes for the interpreter.
RS274NGC_STARTUP_CODE = G21 G40 G90 G94 G97 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
# Not used by LinuxCNC directly, used in the HAL file.
SERVO_PERIOD = 1000000

HAL Section: HAL configuration.

[HAL]
# Hardware Abstraction Layer (HAL) configuration

# Add the HAL user interface pins.
HALUI = halui

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

# HAL file to execute after loading the graphical interface.
POSTGUI_HALFILE = postgui.hal

# HAL file 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, this section is left empty.

[HALUI]
# HAL User Interface

# MDI Command. Can be specified multiple times.
# To execute it use the halui.mdi-command-NN pin,
# where NN is the command number.
# MDI_COMMAND = G1 X0 Y0 Z0

KINS Section: Kinematics configuration.

[KINS]
# Kinematics

# Number of joints (motors).
JOINTS = 2

# Kinematics module
# Not used by LinuxCNC directly, used in the HAL file.
KINEMATICS = trivkins coordinates=XY

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.
```
140[APPLICATIONS]
141# Additional applications
142
143# Application to execute. Can be specified multiple times.
144APP=halscope 50000
```

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 =  XY

# Units for linear axes.
LINEAR_UNITS = mm

# Units for rotary axes.
ANGULAR_UNITS = degree

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

# Maximum linear acceleration, in units per second^2.
MAX_LINEAR_ACCELERATION = 20.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 be executed.
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. An example of the X-axis configuration is provided below; the Y-axis configuration 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.
```
177[AXIS_X]
178# X axis configuration
179
180# Maximum axis velocity, in units per second.
181MAX_VELOCITY = 12.0
182
183# Maximum axis acceleration, in units per second^2.
184MAX_ACCELERATION = 20.0
185
186# Minimum limit for the axis, in machine units.
187MIN_LIMIT = -5
188
189# Maximum limit for the axis, in machine units.
190MAX_LIMIT = 205.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.

For machines with Cartesian geometries, such as gantry robots, LinuxCNC includes the trivkins kinematics module. With this module, by default, there is a 1:1 correspondence between the axis coordinate letter and the joint number, i.e., JOINT_0 = X, JOINT_1 = Y, …, JOINT_8 = W.

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 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.

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 1 (X-axis), which corresponds to the stepper motor. The parameters specified below the comment “Custom configurations for the HAL file” 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]
# Configuration of the first linear motor (X axis)

# Motor type, LINEAR or ANGULAR.
TYPE = LINEAR

# Maximum tracking error, in machine units.
FERROR = 1.0

# Maximum tracking error at slow speeds.
MIN_FERROR = 0.2

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

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

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

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

# Position to which the joint will move upon completion of
# the homing process.
HOME = 0

# Used to define the homing order.
HOME_SEQUENCE = 0

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

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

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

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

# Ignore limit switches during homing.
# = YES if the same switch is used for limits and homing.
HOME_IGNORE_LIMITS = YES

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

# Use the encoder's index pulse for homing.
HOME_USE_INDEX = NO

# ---------------------------------------------------
# Custom configurations for the HAL file.
# ---------------------------------------------------

# *** Step generation configuration ***

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

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

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

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

# Step scale. position = steps / STEP_SCALE.
# To move the axis 1mm/rev with a 1.8° step motor and 1/32
# step mode, STEP_SCALE = steps / position = (32*360/1.8)/1 = 6400
STEP_SCALE = 6400

# Maximum velocity, in position units per second.
STEPGEN_MAXVEL = 17

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

# Note: It is recommended that STEPGEN_MAXVEL and STEPGEN_MAXACCEL be
# between 1% and 25% larger than MAX_VELOCITY and MAX_ACCELERATION.


# *** Encoder configuration ***

# Encoder scale. position = counts / ENCODER_SCALE.
# To get 1mm/rev with a 1000 ppr encoder (4000 cpr),
# ENCODER_SCALE = counts / position = 4000 / 1 = 4000
ENCODER_SCALE = 4000.0


# *** PID controller configuration ***

P = 50.0
I = 20.0
D = 0.0
FF0 = 0.0
FF1 = 1.0
FF2 = 0.025
BIAS = 0.0
DEADBAND = 0.0
MAX_OUTPUT = 0.0

The following code shows the configuration of joint 2 (Y-axis), which corresponds to the brushless motor. As before, the parameters specified below the comment “Custom configurations for the HAL file” 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 brushless motor is used.

[JOINT_1]
# Configuration of the second linear motor (Y axis)

# Motor type, LINEAR or ANGULAR.
TYPE = LINEAR

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

# Maximum tracking error at slow speeds.
MIN_FERROR = 0.2

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

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

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

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

# Position to which the joint will move upon completion of
# the homing process.
HOME = 0

# Used to define the homing order.
HOME_SEQUENCE = 1

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

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

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

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

# Ignore limit switches during homing.
# = YES if the same switch is used for limits and homing.
HOME_IGNORE_LIMITS = YES

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

# Use the encoder's index pulse for homing.
HOME_USE_INDEX = NO

# ---------------------------------------------------
# Custom configurations for the HAL file.
# ---------------------------------------------------

# *** Analog output configuration for +-10V ***

# Maximum velocity in units per second.
ANALOGOUT_MAXLIM = 50

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

# Analog output scale. Vout = 10 * velocity / ANALOGOUT_SCALE.
# Maximum velocity in units per second that the motor can reach.
# For a max velocity of X rpm, with Y ppr encoder (4*Y cpr),
# ANALOGOUT_SCALE = X / 60 * ENCODER_SCALE / (4*Y).
# For 3000 rpm, ANALOGOUT_SCALE = 3000 / 60 * 2048 / 2048 = 50
ANALOGOUT_SCALE = 50


# *** Encoder configuration ***

# Encoder scale. position = counts / ENCODER_SCALE.
# To get 1mm/rev with a 512 ppr encoder (2048 cpr),
# ENCODER_SCALE = counts / position = 2048 / 1 = 2048
ENCODER_SCALE = 2048.0


# *** PID controller configuration ***

P = 20.0
I = 10.0
D = 0.0
FF0 = 0.0
FF1 = 1.0
FF2 = 0.01
BIAS = 0.0
DEADBAND = 0.0
MAX_OUTPUT = 0.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. 26 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. 26 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 home-x <= stepgen.0.out net home-x => 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. Example: `mesa_7i96s_7i77_xy.hal` Configuration File¶

As noted in Section 3.6.2, a LinuxCNC configuration includes at least one .ini file and one .hal file. Below is the mesa_7i96s_7i77_xy.hal configuration file, corresponding to the mesa_7i96s_7i77_xy.ini file detailed in Section 3.8.1. Unlike the .ini format, the .hal format does not have a formal section syntax; however, for clarity, the file is presented below divided into different parts.

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

# Load kinematics module
loadrt [KINS]KINEMATICS

# Load motion controller module
# The "servo_period_nsec" option creates the "servo-thread" thread
loadrt [EMCMOT]EMCMOT servo_period_nsec=[EMCMOT]SERVO_PERIOD num_joints=[KINS]JOINTS

# Load MESA board controller
loadrt hostmot2

# Load MESA low-level Ethernet Anything IO boards controller
# (Mesa Electronics Ethernet Anything IO boards)
loadrt hm2_eth board_ip="10.68.33.122" config="num_encoders=2 num_pwmgens=0 num_stepgens=1"

# Load ladder language module
loadrt classicladder_rt

# Load pid module and create a controller for each axis
loadrt pid names=pid.x,pid.y

# Load estop_latch module to handle emergency stop
loadrt estop_latch

# Load oneshot module (pulse generator)
loadrt oneshot

# Load logic module and define a 5-input OR function
loadrt logic names=logic.fault personality=0x205

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

# Configure 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

# Configure pulse parameters of the oneshot module
setp oneshot.0.width 0.1

# Add functions to the servo thread
addf motion-command-handler servo-thread
addf motion-controller servo-thread
addf pid.x.do-pid-calcs servo-thread
addf pid.y.do-pid-calcs servo-thread
addf hm2_7i96s.0.read servo-thread
addf hm2_7i96s.0.write servo-thread
addf classicladder.0.refresh servo-thread
addf estop-latch.0 servo-thread
addf oneshot.0 servo-thread
addf logic.fault servo-thread

# Load classicladder project
loadusr classicladder myladder.clp --nogui

X-axis configuration (joint 0, stepper motor):

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

# --- PID controller parameters ---

setp pid.x.Pgain     [JOINT_0]P
setp pid.x.Igain     [JOINT_0]I
setp pid.x.Dgain     [JOINT_0]D
setp pid.x.bias      [JOINT_0]BIAS
setp pid.x.FF0       [JOINT_0]FF0
setp pid.x.FF1       [JOINT_0]FF1
setp pid.x.FF2       [JOINT_0]FF2
setp pid.x.deadband  [JOINT_0]DEADBAND
setp pid.x.maxoutput [JOINT_0]MAX_OUTPUT
setp pid.x.error-previous-target true
setp pid.x.maxerror 1


# --- Pulse 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_0]DIRSETUP
setp hm2_7i96s.0.stepgen.00.dirhold        [JOINT_0]DIRHOLD
setp hm2_7i96s.0.stepgen.00.steplen        [JOINT_0]STEPLEN
setp hm2_7i96s.0.stepgen.00.stepspace      [JOINT_0]STEPSPACE
setp hm2_7i96s.0.stepgen.00.position-scale [JOINT_0]STEP_SCALE
setp hm2_7i96s.0.stepgen.00.maxaccel       [JOINT_0]STEPGEN_MAXACCEL
setp hm2_7i96s.0.stepgen.00.maxvel         [JOINT_0]STEPGEN_MAXVEL


# --- 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 / stepgen / motion signals ---

net pid-x-index-enable => pid.x.index-enable

net pid-x-output <= pid.x.output
net pid-x-output => hm2_7i96s.0.stepgen.00.velocity-cmd

net pid-x-enable <= joint.0.amp-enable-out
net pid-x-enable => pid.x.enable
net pid-x-enable => hm2_7i96s.0.stepgen.00.enable

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

# net pid-x-pos-fb <= hm2_7i96s.0.stepgen.00.position-fb
net pid-x-pos-fb <= hm2_7i96s.0.encoder.00.position
net pid-x-pos-fb => pid.x.feedback
net pid-x-pos-fb => joint.0.motor-pos-fb


# --- Configure home / limit signals ---

net x-sw <= hm2_7i96s.0.gpio.000.in
net x-sw => joint.0.home-sw-in
net x-sw => joint.0.neg-lim-sw-in

Y-axis configuration (joint 1, brushless motor):

# MDI Command. Can be specified multiple times.
# To execute it use the halui.mdi-command-NN pin,
# where NN is the command number.
# MDI_COMMAND = G1 X0 Y0 Z0


[KINS]
# Kinematics

# Number of joints (motors).
JOINTS = 2

# Kinematics module
# Not used by LinuxCNC directly, used in the HAL file.
KINEMATICS = trivkins coordinates=XY


[APPLICATIONS]
# Additional applications

# Application to execute. Can be specified multiple times.
APP=halscope 50000


[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 =  XY

# Units for linear axes.
LINEAR_UNITS = mm

# Units for rotary axes.
ANGULAR_UNITS = degree

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

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


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

# Input/output controller module.
EMCIO = io

# Period at which EMCIO will be executed.
CYCLE_TIME = 0.100


[AXIS_X]
# X axis configuration

Other configurations:

#***************
# Other signals
#***************

# --- Igus controller alert and error signals ---

net X-alert <= hm2_7i96s.0.7i77.0.0.input-08
net X-error <= hm2_7i96s.0.7i77.0.0.input-09

net Y-alert <= hm2_7i96s.0.7i77.0.0.input-01
net Y-error <= hm2_7i96s.0.7i77.0.0.input-02


# --- External emergency stop ---

net remote-estop <= hm2_7i96s.0.7i77.0.0.input-13


# --- Fault signal (logic.fault) ---
# The fault signal will be activated if an Igus controller
# emits an error or alert signal or the user presses the
# emergency stop button (ESTOP).

net X-alert => logic.fault.in-00
net X-error => logic.fault.in-01

net Y-alert => logic.fault.in-02
net Y-error => logic.fault.in-03

net remote-estop => logic.fault.in-04


# --- 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 fault <= logic.fault.or
net fault => estop-latch.0.fault-in

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


# --- Enable motors ---

net machine-on <= halui.machine.is-on
net machine-on => hm2_7i96s.0.7i77.0.0.output-00


# --- Pulse to start brushless motor rotation program ---

net brushless-ready <= hm2_7i96s.0.7i77.0.0.input-00
net brushless-ready => oneshot.0.in

net start-brushless <= oneshot.0.out
net start-brushless => hm2_7i96s.0.7i77.0.0.output-01


# --- LED indicators panel ---

net machine-estop <= halui.estop.is-activated

net machine-estop => classicladder.0.in-00
net remote-estop => classicladder.0.in-01
net machine-on => classicladder.0.in-02

net X-error => classicladder.0.in-03
net X-alert => classicladder.0.in-08

net Y-error => classicladder.0.in-05
net Y-alert => classicladder.0.in-10

net led-red <= classicladder.0.out-00
net led-red => hm2_7i96s.0.7i77.0.0.output-02

net led-yellow <= classicladder.0.out-01
net led-yellow => hm2_7i96s.0.7i77.0.0.output-03

net led-green <= classicladder.0.out-02
net led-green => hm2_7i96s.0.7i77.0.0.output-04

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 27 and 28. 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 27 and 28.
A text input field for executing HAL commands, located at the bottom, as shown in Figures 27 and 28.
A “SHOW” tab where information about the selected element in the tree view is displayed, as shown in Fig. 27.
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. 28.
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. 27 Halshow tool showing the “SHOW” tab.¶

../../_images/halshow_watch.png — Fig. 28 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. 29. 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. 29 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. 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. 30.

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

In our testbed setup, ladder logic has been used 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, it can be loaded with the following HAL command:

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.