Updating LinuxCNC

Now your computer knows where to get the new version of the software, next we need to install it.

The process again differs depending on your platform.

The LinuxCNC distribution includes many example configurations organized in directory hierarchies named: by_machine, by_interface, and sim (simulated machines). These configurations are often used as starting points for making a new configuration, as examples for study, or as complete simulated machines that can run without special hardware or real-time kernels.

The configuration files in these directory trees have been updated for the changes required for the joints_axes updates.

Since the joints_axes updates require a number of changes to user ini files and their related halfiles, a script named update_ini is provided to automatically convert user configurations.

This script is invoked when a user starts an existing configuration for the first time after updating LinuxCNC. The script searches the user ini file for a [EMC]VERSION item. If this item 1) does not exist, or 2) exists and is set to the historical CVS value "$Revision$", or is a numerical value less than 1.1, then the update_ini script will popup a dialog to offer to edit the user files to create an updated configuration. If the user accepts, the configuration will be updated.

For example, if the user configuration is named bigmill.ini, the bigmill.ini file and its local associated hal files will be edited to incorporate joints_axes changes. All files of the initial configuration will be saved in a new directory named after the original configuration with a ".old" suffix (bigmill.old in the example).

The update_ini script handles all common user items that are found in basic machines employing identity kinematics. Less common items used in more complex machines may not be converted automatically. Examples of complex machine configurations include:

The following subsections and the section for Hal Changes list items that may require additional user edits to ini or hal files.

LinuxCNC now supports up to 8 spindles (and can be recompiled for more) Existing G-code will run without modification and most configurations will default to single spindles. To specify more than one spindle set the [TRAJ]SPINDLES= entry in the INI file and include the num_spindles= parameter for the motion module (set with either [EMCMOT]EMCMOT = motmod num_spindles= or included in a halfile loadrt entry for motmod).

The motion module num_spindles= parameter and the [TRAJ]SPINDLES= settings must match.

The spindle control pin names have been changed to make spindles look more like axes and joints. motion.spindle-speed-out is now spindle.0.speed-out for example. The automatic update script will take care of these changes. To control extra spindles the G and M-codes which control spindle speed now accept an additional "$" argument, for example M3 $2 to start the third spindle. "$" was chosen to avoid clashes with any existing code letters. It should be possible to create custom G-codes to match any other multi-spindle controller. See the G-code and M-code manuals for code changes, and man motion for the HAL pin changes.

With incorporation of joints_axes functionality, some names were changed to clarify available functionality.

The gentrivkins and gantrykins kinematics modules have been removed as their functionality is now available in the updated trivkins module.

The gentrivkins module has only been available in prior joints_axes branches. To convert, it is necessary to change the name.

Hal file examples:

Configurations using gantrykins should be updated to use trivkins with the kinstype= parameter set to BOTH (for KINEMATICS_BOTH).

Hal file example:

See the trivkins man page for additional information ($ man trivkins)

Note: the most supported usage for specifying kinematics in joints_axes is to set values in the configuration ini file [KINS} section and then reference them within the specified [HAL]HALFILES ( .hal .tcl files). For example:

Prior to joints_axes incorporation, lathes were often configured as if they were three axis (XYZ) machines with an unused axis (Y). This was convenient for sharing Hal files (especially for simulation configs) but required specification of [TRAJ]AXES =3, a dummy AXIS_Y section, and provisions for homing the unused Y coordinate. These arrangements are no longer required or recommended.

Historical lathe configurations used the default options for the trivkins kinematics module. These default options configure all axis letters (XYZABCUVW). With joints_axes incorporation, a more appropriate kinematics specification sets the coordinates to the exact ones used (XZ) and sets the number of joints accordingly to 2. There is no need for an ini file [AXIS_Y] section and only two [JOINT_N] sections need be defined.

Example ini file items for a lathe (only sections relevant to kinematics are shown):

Note that some simulation configurations may still use the historical lathe configuration precedents.

Ini file items that affect joints and axes usage must be consistent.

The motion kinematics module typically loaded with [KINS]KINEMATICS= must use a number of joints equal to the number specified with [KINS]JOINTS=.

The kinematics module must implement axis letters that are consistent with the specification used by the task module item [TRAJ]COORDINATES=.

Examples:

Three axis Cartesian machine using trivkins (KINEMATICS_IDENTITY):

Two axis lathe using trivkins (KINEMATICS_IDENTITY) with non-consecutive axis letters:

Gantry using trivkins with duplicated axis letters and KINEMATICS_BOTH to allow individual joint positioning (for homing):

Gantry using trivkins (KINEMATICS_BOTH) with duplicated axis letters and a rotary axis with skipped axis letters (A,B skipped):

Linear Delta Robot with non-identity kins (KINEMATICS_BOTH) working in Cartesian frame with an additional rotary coordinate:

Note: Some general-purpose kinematics modules (like trivkins) implement identity kinematics with support for coordinate specification (axis letters). Axis letters may be omitted. Axis letters may be duplicated. Joints are assigned to axis letters in a defined manner ($ man trivkins).

Note: For trivkins module loading, do not include spaces about the = sign or letters:

Note: Custom kinematics modules that implement non-identity kinematics (like lineardeltakins) define machine-specific relationships between a set of coordinates and a set of joints. Typically, custom kinematics modules compute the joints-axes relationships within the custom module but it is important to use consistent settings for the related ini items: [KINS]JOINTS and [TRAJ]COORDINATES. The details will usually be explained in the module man page (for example, $ man lineardeltakins).

Negative values may be used for the ini file items named [JOINT_n]HOME_SEQUENCE. Prior to joints_axes incorporation a value of -1 or the ommission of the item indicated no sequence was applicable. Now, only omission of the item is used for that purpose. See the chapter: Homing Configuration for more information.

With joints_axes, an indexer is a joint that can be homed (joint mode) but must also be unlocked from gcode. This requires a one-to-one correspondence between a single joint and an axis.

Specify the joint number that corresponds to a rotary axis (L = A,B, or C) with an ini file setting for the axis:

Specify that the joint is a locking indexer with an ini file setting for the joint (N is the joint_number_for_indexer):

Hal pins can be created to coordinate use of a locking indicator joint:

To create these hal pins for locking joints, specify all joints that are used as locking indexers with the unlock_joints_mask parameter for the motmod module. (bit0(LSB)==>joint0, bit1==>joint1, etc.)

As an example, consider a machine using trivkins kinematics with coordinates XYZB where B is a locking indexer. For trivkins, joint numbers (starting with 0) are assigned consecutively to the coordinates specified (axis coordinate letters may be omitted). For this example, X==>joint0, Y==>joint1, Z==>joint2, B==>joint3. The mask to specify joint 3 is 000001000 (binary) == 0x08 (hexadecimal)

The required ini file entries for this trivkins XYZB example are:

For more complex kinematics, select the joint number as required — there must be a one-to-one correspondence between the rotary axis and the joint number.

(See the motion man page ($ man motion) for more information on motmod)

Lines with numeric INI variables are no longer allowed to have trailing text. In earlier versions of LinuxCNC any text after the number was silently ignored, but as of this version such text is totally disallowed. This includes hash characters ("#"), which in this position are a part of the value, not a comment character.

For example, lines like this will no longer be accepted:

They could be transformed into pairs of lines like this:

In 2.7.x versions, trajectory planning ([TRAJ]) settings included:

Interim work prepared for distinct linear and angular items by renaming these items as:

As these abbreviated names were inconsistent with other name conventions and the implementation of the update_ini script, the interim naming has been corrected to use:

Prior to incorporation of joints_axes updates, wheel jogging was supported in joint mode only and controlled with hal pins:

where M is a number corresponding to an axis letter (0==>X, 1==>Y, etc.)

With incorporation of joints_axes updates, wheel jogging is available for joints in joint mode and for each axis coordinate in teleop mode. The controlling hal pins provided are:

where N is a joint number and L is an axis letter.

To use an MPG in identity kins configurations where there is a one-to-one correspondence of a joint number and an axis letter, it may be convenient to connect the corresponding hal pins. For example, if joint 1 corresponds exactly to axis letter y:

(The signal names jora_1_y_* are examples, names prior to conversion for joints_axes will depend upon the specific configuration details.)

Configurations with non-identity kinematics and configurations that use duplicated axis letters (for example, gantries using more than one joint for an axis coordinate) will require appropriate independent control logic to support both joint and teleop (world) jogging.

Hal pins are created for ini file items for both joints ([JOINT_N] stanzas) and axes ([AXIS_L] stanzas):

Note: In prior versions of LinuxCNC (before joints_axes updates), the hal pin names ini.N.* referred to axes with 0==>x, 1==>y, etc. (pins were created for all 9 axes) See the man page ($ man milltask) for more information

The number of names= instances was formerly limited to 16. Now, for realtime components (loadrt) the instances are assigned dynamically with no built-in limit. The limit of 16 still applies to names= items for userspace (loadusr) components.

For components using personality, the maximum number is now settable by a command line option -P|--personalities.

The following hal output pins were changed from parameters to pins so that they can be connected to signals:

The jog() interface includes a joint-flag to specify joint (True) or teleop (False) jogging:

With incorporation of joints_axes updates, LinuxCNC enforces the distinctions of joints and axes (coordinate letters) — but some guis (like the axis gui) may hide some of the distinctions for simple machines.

In most cases, you can think of joints as motors.

The relationships between joints and axis coordinates are determined by the mathmatical kinematics functions that describe a machine’s motion.

World coordinates (X,Y,Z,A,B,C,U,V,W) are determined by applying FORWARD kinematics operations to joint (motor) positions.

When moving in world space (e.g., gcode movements) the required joint (motor) positions are determined by applying INVERSE kinematics operations to the coordinates requested for motion in world space.

Moving in world space is possible only after homing.

For simple machines (like mills and lathes) there is a one-to-one equivalence of joints and axis coordinate letters. For example, on an XYZ mill, the relationships are typically: axisX==joint0, axisY==joint1, axisZ=joint2. This correspondence is characterized as IDENTITY kinematics and the kinematics module used is usually trivkins (trivial kinematics). (See the trivkins man page $ man trivkins)

Joint jogging (by joint number 0,1,…) is used in joint mode (usually used only BEFORE homing). When homing is completed, the jogging mode is AUTOMATICALLY switched from joint mode to world mode and axis jogging (coordinate letter X,Y,…) is used. This is appropriate for all gcode moves requested by MDI commands or by gcode programs.

Although jogging in joint mode is often never required after homing, some guis (like axis) provide a keyboard shortcut ($) to allow toggling between joint and world (teleop) modes for machines that use non-IDENTITY kinematics.

In many common situations, joint jogging is never needed since homing is accomplished using home switches and/or the various homing methods provided by LinuxCNC. One simply turns on the machine, issues the Home-All command, the machine homes and changes to world mode automatically. See Homing Configuration

Machines that do not use home switches may require manual jogging in joint mode before homing each and every joint. It is also possible to use immediate homing (see the homing docs) for joints that do not require homing to a fixed position.

Although a gui may hide joints/axes distinctions for IDENTITY kinematics machines, it is usually important to complete homing in order to run programs or use features provided by a gui.

By default, the trivkins module declares itself as having IDENTITY kinematics. The distinctions of joint/world operations can be made visible in the axis gui when using trivkins by setting the kinemetics type to a non-IDENTITY type using kinstype=both. The both setting indicates that both forward and inverse kinematics functions are available and gui provisions that hide the distinctions of joints and axis letters should not be employed. For example, for an xyz configuration, specify:

With this setting, identity kinematics will be used but the axis gui will:

Halui now supports teleop jogging resulting in some changed pin names and numerous new names for jogging-related pins.

See the man page ($ man halui) for all pin names.

The tklinuxcnc gui supports both identity and non-identity kinematics, includes gui radiobuttons and a key binding ($) for toggling joint and teleop modes. External changes to joint or teleop motion mode are detected. Jogging is supported in both joint and teleop motion modes. Note that the parameters used for jogging may not be appropriate for both modes for machines with non-identity kinematics.

OpenGL is not used by tklinuxcnc so it may be used to isolate problems and system dependencies that are exposed with more modern guis like axis.

The rudimentary backplot gui provided is available for use with identity kinematics (xyz) machine configurations.

The touchy gui continues to support the identity kinematics configurations that it supported prior to joints_axes incorporation. Jogging is done in teleop mode.

The gscreen gui continues to support the identity kinematics configurations that it supported prior to joints_axes incorporation. Jogging is done in teleop mode.

The gmoccapy gui continues to support the identity kinematics configurations that it supported prior to joints_axes incorporation. Jogging is done in teleop mode.

The HAL driver for the Contour Designs ShuttleXpress device has been renamed from "shuttlexpress" to just "shuttle". If your hal files include some variant of "loadusr shuttlexpress", replace "shuttlexpress" with "shuttle".

Support has been added for the ShuttlePRO, a bigger version of the ShuttleXpress, so the old driver name is no longer accurate.

"Home All" is now supported with the set home subcommand by using -1 for the joint number

The jogging commands have been altered to accomodate both joint (free) and teleop (world) jogging.

Note: Test for teleop mode using command: get teleop_enable if TELEOP_ENABLE=YES, use axis_letter else use joint_number

Note: Formerly, the command set jog 0 1.234 would jog the zeroth axis (X) with requested speed=1.234 in any mode (free or teleop). This command now attemps to jog the zeroth joint (Joint0) provided the mode is free (not teleop). To jog the X axis, the mode must be teleop and the corresponding command is: set jog x 1.234

The calibration/tuning tool now supports stanzas:

where N is a joint number (0 .. ([KINS]JOINTS-1) ), L is an axis coordinate letter (X,Y,Z,A,B,C,U,V,W), and S is a spindle number (0 .. 9)

Prior to joints_axes incorporation, the halfiles used in sim configs typically supported a common milling machine — a Cartesian system with trivial kinematics and three axes named X Y Z. Typical halfile entries:

Lathe configs often shared the same halfiles and used the expedient method of specifying 3 axes with Y unused. More complex sim configs provided specific sets of halfiles according to the configuration purpose.

With the incorporation of joints_axes functionality, many sims provided in the distribution now take advantage of a general purpose halfile that supports numerous configurations automatically. A typical sim config HALFILE specification is:

The basic_sim.tcl HALFILE supports a number of commonly required functions for any number of joints as specified by:

Functions supported include:

The functions are activated by default but can be excluded using options: -no_make_ddts, -no_simulated_home, -no_use_hal_manualtoolchange, -no_sim_spindle.

For example, to omit creation of ddts:

Omitting one or more of the core functions allows testing without without the function or addition of new HALFILEs to implement or expand on the functionality.

New pins (see the motion man page for more info):

--- axis.L.jog-accel-fraction joint.N.jog-accel-fraction ---

Name changes:

New pins:

See the documentation for the xhc-whb04b-6 component.

The bldc_hall3 component has been removed. The bldc component is more flexible and better tested.

Starting sequence values may be 0, 1 (or -1) only. See the "Homing Configuration" documentation for more information.

Joints using a negative HOME_SEQUENCE are not allowed to jog in joint mode in order to prevent misalignment (racking) in common gantry configurations. As always, machines with any kinematics type must be homed prior to enabling conventional world mode jogging.

Added twopass support for loadrt config modparams with multiple settings separated by blanks and enclosed with quotes. Example: