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

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 (KINEMATICS_IDENTITY) with duplicated axis letters:

Gantry using trivkins (KINEMATICS_IDENTITY) 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.

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:

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

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 touchy gui continues to support the identity kinematics configurations that it supported prior to joints_axes incorporation. Jogging is done in joint mode (no coordination of joint/teleop modes with other guis is currently provided).

The gscreen gui continues to support the identity kinematics configurations that it supported prior to joints_axes incorporation. Jogging is done in joint mode by default with limited support for teleop jogging when set by a contemporaneous, cooperating gui. Note that the values used for jogging may not be appropriate for both modes.

The gmoccapy gui continues to support the identity kinematics configurations that it supported prior to joints_axes incorporation. Jogging is done in joint mode (no coordination of joint/teleop modes with other guis is currently provided).

The linuxcnclcd gui has been updated to continue support for the identity kinematics supported prior to joints_axes incorporations. Jogging is done in joint mode. Compatiblity testsing awaits users with the required hardware.

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

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, may 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:

These 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 ddts:

Omitting one or more of the core functions allow a user to test without the function or add new HALFILEs to implement or expand on the functionality.

All components and connections made by LIB:basic_sim.tcl can be viewed using halcmd. The entire hal configuration (except for userspace components loaded with loadusr) can be saved to a file using:

Use of LIB:basic_sim.tcl reduces the effort needed to make a simulation config since it handles most of the required component loading and hal connections.

The sim config Sample Configurations/sim/axis/minimal_xyz.ini demonstrates a working xyz configuration that uses LIB:basic_sim.tcl with a minimal number of ini file settings.