:lang: en
:toc:

[[cha:updating-linuxcnc]]
= Updating LinuxCNC(((Updating LinuxCNC)))

// Custom lang highlight
// must come after the doc title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

Updating LinuxCNC to a new minor release (ie to a new version in
the same stable series, for example from 2.7.0 to 2.7.1) is an
automatic process if your PC is connected to the internet. You will
see an update prompt after a minor release along with other software
updates. If you don't have an internet connection to your PC see
<<getting-started:update-no-network,Updating without Network>>.

== Upgrade to the new version

This section describes how to upgrade LinuxCNC from version 2.7 to the
new 2.8.0 version.  It assumes that you have an existing 2.7 install that you
want to update.

To upgrade LinuxCNC from a version older than 2.7, you have to first
http://linuxcnc.org/docs/2.7/html/getting-started/updating-linuxcnc.html[upgrade your old install to 2.7],
then follow these instructions to upgrade to the new version.

If you do not have an old version of LinuxCNC to upgrade, then you're
best off making a fresh install of the new version as described in the
section <<cha:getting-linuxcnc,Getting LinuxCNC>>.

Furthermore, if you are running Ubuntu Precise or Debian Wheezy it is
well worth considering making a backup of the "linuxcnc" directory on
removable media and performing a
<<cha:getting-linuxcnc,clean install of a newer OS and LinuxCNC version>>
as these releases were EOL in 2017 and 2018 respectively.
If you are running on Ubuntu Lucid then you will have to do this, as
Lucid is no longer supported by LinuxCNC (it was EOL in 2013).

To upgrade major versions like 2.7 to 2.8 when you have a network connection at
the machine you need to disable the old linuxcnc.org apt sources in the file /etc/apt/sources.list  and add a new
linuxcnc.org apt source for 2.7, then upgrade LinuxCNC.

The details will depend on which platform you're running on.  Open a
<<faq:terminal,terminal>> then type `lsb_release -ic` to find this information
out:

----
lsb_release -ic
Distributor ID: Debian
Codename:       wheezy
----

You should be running on Debian Stretch or Wheezy (as above), or Ubuntu
Precise. Packages are also available for Debian Jessie or Debian Buster
if you happen to already be running one of those.

You will also need to check which realtime kernel is being used:

----
uname -r
4.19.0-9-rt-amd64
----

If you see (as above) `-rt-` in the kernel name then you are running the
preempt-rt kernel and should install the "uspace" version of LinuxCNC.
You should also install uspace for "sim" configs on non-realtime kernels

If you see `-rtai-` in the kernel name then you are running RTAI
realtime. See below for the LinuxCNC version to install.

[[_setting_apt_sources]]
=== Apt Sources Configuration

* Open the `Software Sources` window. The process for doing this
  differs slightly on the three supported platforms:
** Debian:
*** Click on `Applications Menu`, then `System`, then
   `Synaptic Package Manager`.
*** In Synaptic, click on the `Settings` menu, then click `Repositories`
    to open the `Software Sources` window.
** Ubuntu Precise:
*** Click on the `Dash Home` icon in the top left.
*** In the `Search` field, type "software", then click on the `Ubuntu
    Software Center` icon.
*** In the Ubuntu Software Center window, click on the `Edit` menu,
    then click on `Software Sources...` to open the `Software Sources`
    window.
** Ubuntu Lucid:
*** Click the `System` menu, then `Administration`, then
    `Synaptic Package Manager`.
*** In Synaptic, click on the `Settings` menu, then click on `Repositories`
    to open the `Software Sources` window.
* In the `Software Sources` window, select the `Other Software` tab.
* Delete or un-check all the old linuxcnc.org entries (leave all
  non-linuxcnc.org lines as they are).
* Click the `Add` button and add a new apt line. The line will be
  slightly different on the different platforms:

[options="header"]
|===
| Platform                | apt source line
| Debian Stretch          | `deb http://linuxcnc.org stretch base 2.8-rtpreempt`
| Debian Wheezy           | `deb http://linuxcnc.org wheezy base 2.8-rt`
| Ubuntu Precise          | `deb http://linuxcnc.org precise base 2.8-rt`
| Debian Jessie - preempt | `deb http://linuxcnc.org jessie base 2.8-rtpreempt`
| Debian Jessie - RTAI    | `deb http://linuxcnc.org jessie base 2.8-rt`
| Debian Buster - preempt | `deb http://linuxcnc.org buster base 2.8-rtpreempt`
| Debian Buster - RTAI    | `deb http://linuxcnc.org buster base 2.8-rt`
|===

image::images/upgrading-to-2.8.png["Setting apt sources",align="center"]

* Click `Add Source`, then `Close` in the Software Sources window.
  If it pops up a window informing you that the information about
  available software is out-of-date, click the `Reload` button.

=== Upgrading to the new version

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.

==== Debian Wheezy & Stretch and Ubuntu Lucid

Debian Wheezy and Stretch both use the Synaptic Package Manager.

* Open Synaptic using the instructions in <<_setting_apt_sources,Setting apt sources>> above.
* Click the `Reload` button.
* Use the Search function to search for `linuxcnc`.
* The package is called "linuxcnc" for RTAI kernels and "linuxcnc-uspace"
  for preempt-rt.
* Click the check box to mark the new linuxcnc and linuxcnc-doc-*
  packages for upgrade. The package manager may select a number of
  additional packages to be installed, to satisfy dependencies that the
  new linuxcnc package has.
* Click the `Apply` button, and let your computer install the new
  package. The old linuxcnc package will be automatically upgraded to
  the new one.

=== Ubuntu Precise

* Click on the `Dash Home` icon in the top left.
* In the `Search` field, type "update", then click on the `Update Manager`
  icon.
* Click the `Check` button to fetch the list of packages available.
* Click the `Install Updates` button to install the new versions of
  all packages.

[[getting-started:update-no-network]]
== Updating without Network

To update without a network connection you need to download the .deb then install
it with dpkg. The .debs can be found in http://linuxcnc.org/dists/ .

You have to drill down from the above link to find the correct deb for your
installation. Open a <<faq:terminal,terminal>> and type in 'lsb_release -ic'
to find the release name of your OS.

----
> lsb_release -ic
Distributor ID: Debian
Codename:       buster
----

Pick the OS from the list then pick the major version you want like
2.8-rt for RTAI or 2.8-rtpreempt for preempt-rt.

Next pick the type of computer you have: binary-amd64 for any 64-bit x86,
binary-i386 for 32 bit, binary-armhf (32bit) or binary-arm64 (64bit) for Raspberry Pi.

Next pick the version you want from the bottom of the list like
'linuxcnc-uspace_2.8.0_amd64.deb' (choose the latest by date).
Download the deb and copy it to your home directory. You can rename the
file to something a bit shorter with the file manager like
'linuxcnc_2.8.0.deb' then open a terminal and install it with the
package manager with this command:

----
sudo dpkg -i linuxcnc_2.8.0.deb
----

== Updating Configuration Files (for 2.8.x)

The new version of LinuxCNC differs from version 2.7 in some ways that
may require changes to your machine configuration.

The main difference is that LinuxCNC no longer makes any assumptions about
which joint controls which axis. This change is generally termed
"joints-axes" after the name of the development branch where the changes
started.
This change has been in development since at least 2010, and has finally
been merged.

=== Distribution Configurations (updates for joints_axes)

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.

=== Automatic updates (update_ini script for joints_axes)

Since the joints_axes updates require a number of changes to user INI files and
their related HAL files, 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:

* gantries with two joints for an axis
* machines with jogwheels
* robots with non-identity kinematics
* configurations using haltcl files

The following subsections and the section for 'HAL Changes' list items that
may require additional user edits to INI or HAL files.

=== Multiple Spindle Support

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

=== TRAJ velocities, accelerations names

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

[source,{ini}]
----
was: [TRAJ]MAX_VELOCITY         is: [TRAJ]MAX_LINEAR_VELOCITY
was: [TRAJ]DEFAULT_VELOCITY     is: [TRAJ]DEFAULT_LINEAR_VELOCITY

was: [TRAJ]MAX_ACCELERATION     is: [TRAJ]MAX_LINEAR_ACCELERATION
was: [TRAJ]DEFAULT_ACCELERATION is: [TRAJ]DEFAULT_LINEAR_ACCELERATION
----

=== Kinematics modules

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:

[source,{hal}]
----
was: loadrt gentrivkins
 is: loadrt trivkins

was: loadrt gentrivkins coordinates=xyyz
 is: loadrt trivkins    coordinates=xyyz
----

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

HAL file example:

[source,{hal}]
----
was: loadrt gantrykins coordinates=xyyz
 is: loadrt trivkins   coordinates=xyyz kinstype=BOTH
----

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:

----
INI file:    [KINS]
             KINEMATICS = trivkins
             JOINTS = 3
             ...

HAL file:    loadrt [KINS]KINEMATICS

haltcl file: loadrt $::KINS(KINEMATICS)
----

=== Lathe Configurations

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):

[source,{ini}]
----
[KINS]
KINEMATICS = trivkins coordinates=xz
JOINTS = 2

[TRAJ]
COORDINATES = XZ
...

[AXIS_X]
...

[AXIS_Z]
...

[JOINT_0]
...

[JOINT_1]
...
----

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

=== Consistent Joints/Axes specifications

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):

[source,{ini}]
-----
[KINS]KINEMATICS  = trivkins
[KINS]JOINTS      = 3
[TRAJ]COORDINATES = XYZ
-----

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

[source,{ini}]
-----
[KINS]KINEMATICS  = trivkins coordinates=XZ
[KINS]JOINTS      = 2
[TRAJ]COORDINATES = XZ
-----

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

[source,{ini}]
-----
[KINS]KINEMATICS  = trivkins coordinates=XYYZ kinstype=BOTH
[KINS]JOINTS      = 4
[TRAJ]COORDINATES = XYYZ
-----

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

[source,{ini}]
-----
[KINS]KINEMATICS  = trivkins coordinates=XYYZC kinstype=BOTH
[KINS]JOINTS      = 5
[TRAJ]COORDINATES = XYYZC
-----

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

[source,{ini}]
-----
[KINS]KINEMATICS  = lineardeltakins
[KINS]JOINTS      = 4
[TRAJ]COORDINATES = XYZA
-----

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:

[source,{ini}]
----
This:     [KINS]KINEMATICS = trivkins coordinates=XZ
NOT This: [KINS]KINEMATICS = trivkins coordinates = X Z
----

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

=== Home sequences

*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 omission of the item indicated no sequence was applicable.
Now, only omission of the item is used for that purpose.
See the chapter: <<cha:homing-configuration,'Homing Configuration'>>
for more information.

=== Locking rotary indexer (updates for joints_axes)

With joints_axes, an indexer is a joint that can be homed (joint mode)
but must also be unlocked from G-code.  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:

[source,{ini}]
----
[AXIS_L]LOCKING_INDEXER_JOINT = joint_number_for_indexer
----

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

[source,{ini}]
----
[JOINT_N]LOCKING_INDEXER = 1
----

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

----
joint.N.unlock      (BIT output from HAL)
joint.N.is-unlocked (BIT input  to   HAL)
----

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

[source,{ini}]
----
[EMCMOT]
EMCMOT = motmod unlock_joints_mask=BITMASK
----

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:

[source,{ini}]
----
[KINS]
JOINTS = 4
KINEMATICS = trivkins coordinates=XYZB
...

[TRAJ]
COORDINATES = XYZB
...

[EMCMOT]
EMCMOT = motmod unlock_joints_mask=0x08
...

[AXIS_B]
LOCKING_INDEXER_JOINT = 3
...

[JOINT_3]
LOCKING_INDEXER = 1
...
----

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)

=== Stricter INI file syntax

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:

[source,{ini}]
-----
MAX_VELOCITY = 7.5 # This is the max velocity of the axis.
-----

They could be transformed into pairs of lines like this:

[source,{ini}]
-----
# This is the max velocity of the axis.
MAX_VELOCITY = 7.5
-----

=== [TRAJ] settings

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

[source,{ini}]
----
[TRAJ]
DEFAULT_ACCELERATION
MAX_ACCELERATION
----

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

[source,{ini}]
----
[TRAJ]
DEFAULT_LINEAR_ACCEL
MAX_LINEAR_ACCEL
----

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:

[source,{ini}]
----
[TRAJ]
DEFAULT_LINEAR_ACCELERATION
MAX_LINEAR_ACCELERATION
----

[NOTE]
Support for specifying trajectory planning angular default and maximum
accelerations has not been implemented.


== HAL Changes (updates for joints_axes 2.8.x)

=== Wheel or MPG (manual pulse generator) jogging

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

----
bit   IN  axis.M.jog-enable
float IN  axis.M.jog-scale
s32   IN  axis.M.jog-counts
bit   IN  axis.M.jog-vel-mode
----

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:

----
bit   IN  joint.N.jog-enable
float IN  joint.N.jog-scale
s32   IN  joint.N.jog-counts
bit   IN  joint.N.jog-vel-mode

bit   IN  axis.L.jog-enable
float IN  axis.L.jog-scale
s32   IN  axis.L.jog-counts
bit   IN  axis.L.jog-vel-mode
----

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:

[source,{hal}]
----
net jora_1_y_enable   => joint.1.jog-enable => axis.y.jog-enable
net jora_1_y_scale    => joint.1.jog-scale  => axis.y.jog-scale
net jora_1_y_counts   => joint.1.jog-counts => axis.y.jog-counts
net jora_1_y_vel-mode => joint.1.jog-counts => axis.y.jog-vel-mode
----

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

=== INI HAL pins

HAL pins are created for INI file items for both joints ([JOINT_N]) and axes ([AXIS_L]):

For _N_ = 0 ... [KINS](JOINTS-1):

[source,{ini}]
----
INI file item              HAL pin name
[JOINT_N]BACKLASH          ini.N.backlash
[JOINT_N]FERROR            ini.N.ferror
[JOINT_N]MIN_FERROR        ini.N.min_ferror
[JOINT_N]MIN_LIMIT         ini.N.min_limit
[JOINT_N]MAX_LIMIT         ini.N.max_limit
[JOINT_N]MAX_VELOCITY      ini.N.max_velocity
[JOINT_N]MAX_ACCELERATION  ini.N.max_acceleration
[JOINT_N]HOME              ini.N.home
[JOINT_N]HOME_OFFSET       ini.N.home_offset
----

For _L_ = x y z a b c u v w:

[source,{ini}]
----
INI file item              HAL pin name
[AXIS_L]MIN_LIMIT          ini.L.min_limit
[AXIS_L]MAX_LIMIT          ini.L.max_limit
[AXIS_L]MAX_VELOCITY       ini.L.max_velocity
[AXIS_L]MAX_ACCELERATION   ini.L.max_acceleration
----

[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 of 'milltask' for
more information.

== HAL Changes (Other 2.8.x)

=== halcompile

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.

=== Parameter to Pin changes

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

----
motion.servo.last-period    (servo last period in clks)
motion.servo.last-period_ns (kernel-dependent availability)
----

== Interface changes for joints_axes 2.8.x

=== Python LinuxCNC module

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

----
jog(command, joint-flag, axis-or-joint-number, velocity[, distance])

jog(linuxcnc.JOG_STOP, joint-flag, axis-or-joint-number)
jog(linuxcnc.JOG_CONTINUOUS, joint-flag, joint-flag, velocity)
jog(linuxcnc.JOG_INCREMENT, joint-flag, axis-or-joint-number, velocity, distance)
----

== GUIs (updates for joints_axes 2.8.x)

=== Notes on joint/axis jogging, homing, and kinematics

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 mathematical 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., G-code 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 G-code moves requested by MDI commands
or by G-code 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 <<cha:homing-configuration,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:

[source,{ini}]
----
[KINS]
KINEMATICS = trivkins coordinates=xyz kinstype=both
----

With this setting, identity kinematics will be used but the AXIS
GUI will:

. show joint numbers prior to homing
. show axis letters after successful homing
. support toggling between joint and teleop modes with the '$' key

=== Halui

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.

==== TELEOP jogging (also called axis or world jogging)

New pins for teleop jogging are:

----
new: halui.axis.jog-speed
new: halui.axis.jog-deadband

new: halui.axis.L.plus
new: halui.axis.L.minus
      ... etc.
----

where _L_ is a letter corresponding to one of the axis letters specified by
[TRAJ]COORDINATES or 'selected' for the axis selected by the
halui.axis._L_.select pins.

==== Joint jogging

All pins for joint jogging were renamed for specificity:

----
was: halui.jog-speed          is: halui.joint.jog-speed
was: halui.jog-deadband       is: halui.joint.jog-deadband

was: halui.jog.N.plus         is: halui.joint.N.plus
was: halui.jog.N.minus        is: halui.joint.N.minus
      ...  etc.                    ... etc.
----

where _N_ is a joint number (0 ... _num_noints_-1) or 'selected'
for the joint selected by the halui.joint._N_.select pins.

====  Additional pin renames

The HAL pins for 'selected' joints were renamed for consistency
with related pins.

----
was: halui.joint.selected.is_homed
is: halui.joint.selected.is-homed

was: halui.joint.selected.on-soft-limit
is: halui.joint.selected.on-soft-min-limit
----

=== AXIS GUI

==== Identity Kinematics

The AXIS GUI continues to support identity kinematics configurations. This GUI
hides the distinctions of axes and joints in order to simplify the display and
usage of simple machines.

==== Special case kinematics

Some machines, typically gantrys, may use a configuration with more than
one joint assigned to an axis letter.  This can be done with the trivkins
kinematics module using repeated coordinate letters.  For example, a
machine configured with INI settings:

[source,{ini}]
----
[KINS]
KINEMATICS = trivkins coordinates=XYYZ kinstype=BOTH
...
[TRAJ]
COORDINATES = XYYZ
...
----

This machine, after homing, has a one-to-one correspondence between a single
axis letter (Y) and a pair of joints (1,2).  Using 'kinematics=BOTH' allows
control of individual joints in joint mode 'if/when required'.

==== Non-identity kinematics

The AXIS GUI supports configurations using non-identity kinematics with:

. Key binding ('$') to toggle joint or teleop mode
. Preview Tab display of joints or axes according to joint or teleop mode
. Preview Tab display of 'Home' and 'Limit' icons in joint mode
. Preview Tab display of 'All-homed' and 'Any-limit' icons in teleop mode
. DRO Tab display of joint or axes according to joint or teleop mode
. Jogging is supported in both joint and teleop motion modes.
. External changes to the joint/teleop motion mode are detected.

==== Home icons

For identity kinematics, 'Home' icons are shown for the corresponding
(one-to-one) axis letter when a joint is homed.

For non-identity kinematics, 'Home' icons are shown for individual joints when
a joint is homed in joint display mode.  An 'All-homed' icon is displayed for
all axis letters when ALL joints are homed in world display mode.

==== Limit icons

For identity kinematics, 'Limit' icons are shown for the corresponding
(one-to-one) axis letter when a joint limit is active.

For non-identity kinematics, 'Limit' icons are shown for individual joints when
the joint limit is active in joint display mode.  An 'Any-Limit' icon is displayed
if any joint is at a limit in teleop display mode.

==== Key bindings for a fourth axis

In the AXIS GUI, jogging keys are assigned to axes in a configurable
fashion.  For 3-axis machines, XYZA machines, and lathes the default is
the same as in 2.7.  For other machines, the 4 pairs of jogging keys are
assigned to the first 4 axes that exist in the order XYZ ABC UVW.
These assignments can be controlled by new INI file directives in the
<<sub:ini:sec:display,[DISPLAY] section of the INI file>>.

Note that the parameters used for jogging may not be appropriate for both modes
for machines with non-identity kinematics.

=== TkLinuxCNC

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

==== emcsh commands

The code of emcsh.cc provides the set of Tcl commands used by TkLinuxCNC.  The
commands are available to Tcl applications as the Tcl package named 'Linuxcnc'.
A number of commands previously required the use of a numeric argument to
specify an axis coordinate (0-->X, 1-->Y, ..., 8-->W).  These commands have
been simplified to use an argument that is just the coordinate letter.

Commands now using a coordinate letter argument are:

. emc_pos_offset
. emc_abs_cmd_pos
. emc_abs_act_pos
. emc_rel_cmd_pos
. emc_rel_act_pos
. emc_tool_offset
. emc_probed_pos

=== Touchy

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

=== Gscreen

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

=== GMOCCAPY

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

=== `shuttlexpress` driver renamed to `shuttle`

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.

=== linuxcncrsh

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

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

----
was: set jog      joint_number             speed
is: set jog      joint_number|axis_letter speed

was: set jog_incr joint_number             speed increment
is: set jog_incr joint_number|axis_letter speed increment

was: set jog_stop
is: set jog_stop joint_number|axis_letter
----

[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 attempts 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'.

== Tools

=== Calibration (emccalib.tcl)

The calibration/tuning tool now supports stanzas:

  [JOINT_N], [AXIS_L], [SPINDLE_S], [TUNE]

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

[NOTE]
The number of allowed spindles is 8 but legacy configurations
may include a stanza [SPINDLE_9] unrelated to an actual spindle number.

[NOTE]
The [TUNE] stanza may be used for specifying tunable items
not relevant to the other supported stanzas.

== Obsolete Guis (removed for 2.8.x)

The GUIs 'mini', 'keystick', and 'xlinuxcnc' have been removed in
conjunction with updates for joints_axes.  All related source code,
examples, and documentation are available in the git repository.

== Deprecated Guis (marked at 2.8.x)

The 'linuxcnclcd' GUI is a candidate for removal.
Should this component be removed, all related source code, examples,
and documentation will be available in the git repository.

== Simulator configurations (updates for joints axes 2.8.x)

=== Pre-joints_axes

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

[source,{ini}]
----
[HAL]
HALFILE = core_sim.hal
HALFILE = sim_spindle_encoder.hal
HALFILE = axis_manualtoolchange.hal
HALFILE = simulated_home.hal
----

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

=== Post-joints_axes

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

[source,{ini}]
----
[HAL]
HALFILE = LIB:basic_sim.tcl
----

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

[source,{ini}]
----
[KINS]
...
JOINTS = number_of_joints
...
----

Functions supported include:

. 'ddts' -- differentiator HAL components are loaded and connected
  for each joint (and xy, xyz for trivkins machines)
. 'simulated_home' -- a sim_home_switch HAL component is loaded and connected for each joint.
  The homing conditions are specified by the usual [JOINT_n]HOME_* INI file items.
. 'use_hal_manualtoolchange' -- the user space hal_manualtoolchange
  component is loaded and connected.
. 'sim_spindle' -- the sim_spindle component is loaded and connected to
  additional loaded HAL components to simulate the inertia of a rotating
  spindle mass.

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:

[source,{ini}]
----
HALFILE = LIB:basic_sim.tcl -no_make_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.

==== Equivalent HAL commands file

When LIB:basic_sim.tcl is used, an equivalent HAL file is created (in the
configuration directory) to show the halcmd commands issued.   The file
name is based on the name of the INI file with '_cmds' appended to
the basename and a conventional '.hal' file extension. Example:

----
inifilename:            example.ini
equivalent_halfilename: example_cmds.hal
----

The equivalent HAL file supersedes previous instances of files with
the same filename.  INI file variables substitutions specified in the
INI file and interpreted by halcmd are automatically substituted in the
created HAL file.  If there are [HAL]HALFILEs specified before
LIB:basic_sim.tcl, their halcmd commands are included too.

The equivalent HAL file can be used to create a new configuration based on
the original configuration made with LIB:basic_sim.tcl with the
following steps:

. Run the simulator configuration to create a new equivalent HAL file, for example: 'example_cmds.hal'.
. To use this new equivalent HAL file in the original simulator
  configuration INI file (or a copy of it), edit to change:
+
[source,{ini}]
----
[HAL]
HALFILE = LIB:basic_sim.tcl other_parameters
----
+
to:
+
[source,{ini}]
----
[HAL]
HALFILE = ./example_cmds.hal
----

==== Notes

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:

----
$ halcmd save > hal.save
----

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.

== Miscellaneous updates for 2.8.x

Commits to unreleased branches may make changes that affect testers
and early-adopters of the unreleased software.

=== Motion pins

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

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

=== HAL pins

Name changes:

----
was: axis.L.vel-cmd
is:  axis.l.teleop-vel-cmd
----

New pins:

----
motion.homing-inhibit (see motion manpage)
----

=== HAL component updates

. siggen: new pin 'reset' to set output signal values to predefined state
. biquad: pins 'type,f0,Q,s1,s2' were formerly params
. userkins: template for user-built kinematics modules using halcompile

=== XHC-HB04 Pendant Support

==== xhc_hb04_util.comp (helper component)

Remove unused pin 'jogenable-off'.

Add pin 'amux-enable' so that the multiplexed acceleration reductions are now
enabled by the ANDing the pins: 'is-manual' and 'amux-enable'.  These two pins
are typically connected to 'halui.mode.is-manual' and 'halui.mode.is-teleop'
respectively.

==== xhc_hb04.tcl (optional LIB configuration HAL file)

Remove signal pendant:jogenable-off for removed pin 'pendant_util.jogenable-off'.

Support new motion pins for reduced accelerations
(axis._L_.jog-accel-fraction, joint._N_.jog-accel-fraction) for wheel jogging.
The use of [APPLICATIONS]APP=xhc-hb04-accels is no longer supported.
Reduced accels are applied for wheel jogging only (not for nml commands
issued by GUIs).

=== XHC-WHB04B-6 pendant support

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

=== bldc3_hall

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

=== [JOINT_n]HOME_SEQUENCE Starting values

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

=== [JOINT_n]HOME_SEQUENCE Negative values

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.

=== TWOPASS support for complex loadrt config= items

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

[source,{hal}]
----
loadrt hm2_eth board_ip=10.10.10.10 config="num_encoders=2 num_pwmgens=2 num_stepgens=3"
----

== Changes beyond 2.8.x (master branch development)

The master branch is version-tagged with prerelease notation, typically
2.9~pre*

=== Python3 and GTK3

2.9 changed to Python3 and GTK3. This only affects you if you have custom glade or Python handlers in your config.

. Run py3clean in your config directory to remove any temporary files.
. Run py3clean in your LinuxCNC source directory if you compile from source.
. Run 2to3 -w on any .py files you have written.
. Make sure the interpreter in the first line of the script is Python 3, not Python 2.
. Open the ui file in glade, and save it. It should convert everything that can be converted automatically, and give you warnings.

=== LinuxCNC Startup

The main script, *linuxcnc*, supports a new option (-H dirname) to
specify an additional user-specified directory for HAL files.  This
directory is searched before the usual search of 1) the INI directory
and 2)the system HAL file library directory.

=== G-code changes
G43.2 (additional offsets) now accepts transient offsets to be added by
axis words as well as from the tool table.

=== Configuration Updates

==== INI file Settings

New: [JOINT_n]HOME_INDEX_NO_ENCODER_RESET -- support encoder with
index that does not reset upon receipt of index pulse following
assertion of index_enable.

axis.py default for [DISPLAY]GEOMETRY was:"XYZBCUVW",is:"XYZABCUVW"

=== Code Updates

Management of the internal storage of tool data and the communication
of same between EMCIO and TASK has been refactored to use memory mapped
storage.  Legacy use of nml messages for tooldata is deprecated and
may be removed before a new release.

Code references to the sequential indexes for internal tooldata have
been clarified but legacy variable names persist for *selected_pocket*
and *current_pocket*.  Variables with these names refer to the
sequential index for internal tooldata not an actual pocket number.
These variable names may be renamed in the future and require changes
to user-fielded Python remap applications that modify tool handling.

A new optional interface is provided to support management of
tool data by an external database application.

The ioControl_v2.cc file providing the userspace program iov2 has
no maintainter and its use is deprecated -- it may be removed before
the next release.

==== Reverse Run

Support added for reverse run in the trajectory planner, the task, and
motion modules, the Python interface, the AXIS GUI, and the test suite.

==== Number of Joints

The maximum number of joints (EMCMOT_MAX_JOINTS) increased from 9
to 16.  The AXIS GUI now supports display of up to 16 joints.

==== Extra Joints

A new motmod parameter (num_extrajoints) specifies joints that are
homed by conventional joint homing methods but controlled by new HAL
pins (joint._N_.posthome-cmd) after homing.  Such joints may be
managed by independent motion planner/controllers in HAL and manipulated
from G-code using custom M-codes.  See the motion man page for
more info.

==== Homing

A homing api is provided by src/emc/motion/homing.h to support users'
custom homing code that replaces src/emc/motion/homing.c with
a user-customized homing.c file.

==== Motion

The motion module supports kinematics modules that define new
functions kinematicsSwitchable() and kinematicsSwitch() to switch
their kinematics type.  A HAL pin, motion.switchkins-type, is
provided for use of such kinematics modules.

Provided kinematics modules that implement kinematics switching
use the switchkins.o object to supply the required rtapi_main()
and related functions.  Kinematics modules that do not support
kinematics switching use the macro "KINS_NOT_SWITCHABLE"
provided by kinematics.h.

==== Switchkins Kinematics Modules

Several kinematics modules are now switchable between their
eponymous kinematics and an alternate identity kinematics mode.

Kinematic modules supporting switchkins:

. xyzac-trt-kins table-rotary-tilting (supersedes xyzac-trt-kins)
. xyzbc-trt-kins table-rotary-tilting (supersedes xyzbc-trt-kins)
. genserkins     generalized serial-link kinematics
. genhexkins     generalized hexapod parallel kinematics
. scarakins      scara robot
. pumakins       puma robot
. 5axiskins      bridgemill (xyzbcw 6axes)

The switchkins modules above (and trivkins) support a
coordinates= parameter that optionally specifies an ordered set
of coordinate letters that are sequentially assigned to joint
numbers (beginning with joint0).

The switchkins modules above include provisions for compile-time
support of an additional user-specified kinematics type identified
on the make command line by the userkfuncs environmental
variable.  (See src/Makefile)

The userspace test program bin/genserkins has been isolated to
a single file (ugenserkins.c) since its original source file
(genserkins.c) has been refactored for switchkins support.
The userspace test program has not been actively maintained and
its use is deprecated.  The ugenserkins.c file may be removed
in the future.

==== Trajectory Planner

The trajectory planner is now implemented as a loadable module
(default:tpmod).  An alternate (user-built) planner can be loaded using
INI setting [TRAJ]TPMOD= modulename or the 'linuxcnc -t modulename' option.
The example file src/hal/components/tpcomp.com illustrates a method for
creating a module using halcompile.

==== Homing

Homing functions are now implemented by a loadable module (default:homemod).
An alternate (user-built) planner can be loaded using
INI setting [EMCMOT]HOMEMOD=modulename or the 'linuxcnc -m modulename' option.
The example file src/hal/components/homecomp.comp is a minimal example
of a homing module that can be built with halcompile.

==== Other

lib/hallib/sim_lib.tcl: simulate encoder index if [JOINT_n]HOME_USE_INDEX
is specified.

lib/python/vismach.py: new HAL pin vismach.plotclear

=== HAL

==== Components

sim_home_switch: added I/O pin for index-enable

==== Motion module pins

motion.feed-upm -- current feed in units per minute

=== Configs

==== INI file

[DISPLAY]GEOMETRY settings that include  the '!' character
specify that displayed rotations respect G5x,G92 offsets.

==== Simulation Configs

sim/configs/axis/axis_9axis: demonstrate simulated encoder index

== Changes after 2.8.x

Future versions of this document will take into account changes made to
the development branch after the latest 2.8.x release.

// vim: set syntax=asciidoc:
