updating-linuxcnc.txt
1 [[cha:updating-linuxcnc]] 2 3 = Updating LinuxCNC 4 5 Updating LinuxCNC to a new minor release (ie to a new version in 6 the same stable series, for example from 2.7.0 to 2.7.1) is an 7 automatic process if your PC is connected to the internet. You will 8 see an update prompt after a minor release along with other software 9 updates. If you don't have an internet connection to your PC see 10 <<getting-started:update-no-network,Updating without Network>>. 11 12 == Upgrade to the new version 13 14 This section describes how to upgrade LinuxCNC from version 2.7 to the 15 new version. It assumes that you have an existing 2.7 install that you 16 want to update. 17 18 To upgrade LinuxCNC from a version older than 2.7, you have to first 19 http://linuxcnc.org/docs/2.7/html/getting-started/updating-linuxcnc.html[upgrade 20 your old install to 2.7], then follow these instructions to upgrade to 21 the new version. 22 23 If you do not have an old version of LinuxCNC to upgrade, then you're 24 best off making a fresh install of the new version as described in the 25 section <<cha:getting-linuxcnc,Getting LinuxCNC>>. 26 27 To upgrade major versions like 2.6 to 2.7 when you have a network connection at 28 the machine you need to disable the old linuxcnc.org apt sources and add a new 29 linuxcnc.org apt source for 2.7, then upgrade LinuxCNC. 30 31 The details will depend on which platform you're running on. Open a 32 <<faq:terminal,terminal>> then type `lsb_release -ic` to find this information 33 out: 34 35 ---- 36 lsb_release -ic 37 Distributor ID: Debian 38 Codename: wheezy 39 ---- 40 41 You should be running on Debian Wheezy (as above), or Ubuntu Precise, 42 or Ubuntu Lucid. 43 44 45 === Setting apt sources 46 47 * Open the `Software Sources` window. The process for doing this 48 differs slightly on the three supported platforms: 49 50 ** Debian Wheezy: 51 52 *** Click on `Applications Menu`, then `System`, then 53 `Synaptic Package Manager`. 54 55 *** In Synaptic, click on the `Settings` menu, then click `Repositories` 56 to open the `Software Sources` window. 57 58 ** Ubuntu Precise: 59 60 *** Click on the `Dash Home` icon in the top left. 61 62 *** In the `Search` field, type "software", then click on the `Ubuntu 63 Software Center` icon. 64 65 *** In the Ubuntu Software Center window, click on the `Edit` menu, 66 then click on `Software Sources...` to open the `Software Sources` 67 window. 68 69 ** Ubuntu Lucid: 70 71 *** Click the `System` menu, then `Administration`, then 72 `Synaptic Package Manager`. 73 74 *** In Synaptic, click on the `Settings` menu, then click `Repositories` 75 to open the `Software Sources` window. 76 77 * In the `Software Sources` window, select the `Other Software` tab. 78 79 * Delete or un-check all the old linuxcnc.org entries (leave all 80 non-linuxcnc.org lines as they are). 81 82 * Click the `Add` button and add a new apt line. The line will be 83 slightly different on the different platforms: 84 85 [options="header"] 86 |==== 87 | Platform | apt source line 88 | Debian Wheezy | `deb http://linuxcnc.org wheezy base 2.7-rtai` 89 | Ubuntu Precise | `deb http://linuxcnc.org precise base 2.7-rtai` 90 | Ubuntu Lucid | `deb http://linuxcnc.org lucid base 2.7-rtai` 91 |==== 92 93 image::images/upgrading-to-2.7.png[align="left", alt="Setting apt sources"] 94 95 * Click `Add Source`, then `Close` in the Software Sources window. 96 If it pops up a window informing you that the information about 97 available software is out-of-date, click the `Reload` button. 98 99 === Upgrading to the new version 100 101 Now your computer knows where to get the new version of the software, 102 next we need to install it. 103 104 The process again differs depending on your platform. 105 106 ==== Debian Wheezy and Ubuntu Lucid 107 108 Debian Wheezy and Ubuntu Lucid both use the Synaptic Package Manager. 109 110 * Open Synaptic using the instructions in <<_setting_apt_sources,Setting 111 apt sources>> above. 112 113 * Click the `Reload` button. 114 115 * Use the Search function to search for `linuxcnc`. 116 117 * Click the check box to mark the new linuxcnc and linuxcnc-doc-* 118 packages for upgrade. The package manager may select a number of 119 additional packages to be installed, to satisfy dependencies that the 120 new linuxcnc package has. 121 122 * Click the `Apply` button, and let your computer install the new 123 package. The old linuxcnc package will be automatically upgraded to 124 the new one. 125 126 === Ubuntu Precise 127 128 * Click on the `Dash Home` icon in the top left. 129 130 * In the `Search` field, type "update", then click on the `Update Manager` 131 icon. 132 133 * Click the `Check` button to fetch the list of packages available. 134 135 * Click the `Install Updates` button to install the new versions of 136 all packages. 137 138 == Updating without Network 139 [[getting-started:update-no-network]] 140 141 To update without a network connection you need to download the deb then install 142 it with dpkg. The buildbot builds new debs each time something is updated and 143 stores them at http://buildbot.linuxcnc.org/dists/ 144 145 You have to drill down from the above link to find the correct deb for your 146 installation. Open a <<faq:terminal,terminal>> and type in 'lsb_release -ic' 147 to find the name of your OS. 148 149 ---- 150 > lsb_release -ic 151 Distributor ID: Debian 152 Codename: wheezy 153 ---- 154 155 Pick the OS from the list then pick the major version you want like 2.7-rt for 156 real time or 2.7-sim for the simulator only. 157 158 Next pick the type of computer you have i386 for 32 bit and amd64 for 64 bit. 159 160 Next pick the version you want from the bottom of the list like 161 'linuxcnc_2.7.4.46.g5954dcf_i386.deb'. Download the deb and copy it to your 162 home directory. You can rename the file to something a bit shorter with the file 163 manager like 'linuxcnc_2.7.4.deb' then open a terminal and install it with the 164 package manager with this command 'sudo dpkg -i linuxcnc_2.7.4.deb' 165 166 ---- 167 sudo dpkg -i linuxcnc_2.7.4.deb 168 ---- 169 170 == Updating Configuration Files (for 2.8.x) 171 172 The new version of LinuxCNC differs from version 2.7 in some ways that 173 may require changes to your machine configuration. 174 175 === Distribution Configurations (updates for joints_axes) 176 177 The LinuxCNC distribution includes many example configurations organized in 178 directory hierarchies named: by_machine, by_interface, and sim (simulated 179 machines). These configurations are often used as starting points for making a 180 new configuration, as examples for study, or as complete simulated machines that 181 can run without special hardware or real-time kernels. 182 183 The configuration files in these directory trees have been updated for the 184 changes required for the joints_axes updates. 185 186 === Automatic updates (update_ini script for joints_axes) 187 188 Since the joints_axes updates require a number of changes to user ini files and 189 their related halfiles, a script named update_ini is provided to automatically 190 convert user configurations. 191 192 This script is invoked when a user starts an existing configuration for the 193 first time after updating LinuxCNC. The script searches the user ini file for 194 a [EMC]VERSION item. If this item 1) does not exist, or 2) exists and is set 195 to the historical CVS value "$Revision$", or is a numerical value less than 196 1.0, then the update_ini script will popup a dialog to offer to edit the user 197 files to create an updated configuration. If the user accepts, the 198 configuration will be updated. 199 200 For example, if the user configuration is named bigmill.ini, the bigmill.ini file 201 and its local associated hal files will be edited to incorporate joints_axes 202 changes. All files of the initial configuration will be saved in a new directory 203 named after the original configuration with a ".old" suffix (bigmill.old in the 204 example). 205 206 The update_ini script handles all common user items that are found in basic 207 machines employing identity kinematics. Less common items used in more complex 208 machines may not be converted automatically. Examples of complex machine 209 configurations include: 210 211 * gantries with two joints for an axis 212 * machines with jogwheels 213 * robots with non-identity kinematics 214 * configurations using haltcl files 215 216 The following subsections and the section for 'Hal Changes' list items that 217 may require additional user edits to ini or hal files. 218 219 === Multiple Spindle Support 220 221 LinuxCNC now supports up to 8 spindles (and can be recompiled for more) 222 Existing G-code will run without modification and most configurations 223 will default to single spindles. To specify more than one spindle 224 set the [TRAJ]SPINDLES= entry in the INI file *and* include the num_spindles= 225 parameter for the motion module (set with either [EMCMOT]EMCMOT = motmod num_spindles= 226 or included in a halfile loadrt entry for motmod). 227 228 The motion module num_spindles= parameter and the [TRAJ]SPINDLES= settings 229 *must* match. 230 231 The spindle control pin names have been changed to make spindles look 232 more like axes and joints. motion.spindle-speed-out is now spindle.0.speed-out 233 for example. The automatic update script will take care of these changes. 234 To control extra spindles the G and M-codes which control spindle speed 235 now accept an additional "$" argument, for example M3 $2 to start the 236 third spindle. "$" was chosen to avoid clashes with any existing code 237 letters. It should be possible to create custom G-codes to match any 238 other multi-spindle controller. 239 See the G-code and M-code manuals for code changes, and man motion for 240 the HAL pin changes. 241 242 === TRAJ velocities, accelerations names 243 244 With incorporation of joints_axes functionality, some names were 245 changed to clarify available functionality. 246 247 ---- 248 was: [TRAJ]MAX_VELOCITY is: [TRAJ]MAX_LINEAR_VELOCITY 249 was: [TRAJ]DEFAULT_VELOCITY is: [TRAJ]DEFAULT_LINEAR_VELOCITY 250 251 was: [TRAJ]MAX_ACCELERATION is: [TRAJ]MAX_LINEAR_ACCELERATION 252 was: [TRAJ]DEFAULT_ACCELERATION is: [TRAJ]DEFAULT_LINEAR_ACCELERATION 253 ---- 254 255 === Kinematics modules 256 257 The gentrivkins and gantrykins kinematics modules have been removed as their 258 functionality is now available in the updated trivkins module. 259 260 The gentrivkins module has only been available in prior joints_axes 261 branches. To convert, it is necessary to change the name. 262 263 Hal file examples: 264 265 ---- 266 was: loadrt gentrivkins 267 is: loadrt trivkins 268 269 was: loadrt gentrivkins coordinates=xyyz 270 is: loadrt trivkins coordinates=xyyz 271 ---- 272 273 Configurations using gantrykins should be updated to use trivkins with the 274 kinstype= parameter set to BOTH (for KINEMATICS_BOTH). 275 276 Hal file example: 277 278 ---- 279 was: loadrt gantrykins coordinates=xyyz 280 is: loadrt trivkins coordinates=xyyz kinstype=BOTH 281 ---- 282 283 See the trivkins man page for additional information ('$ man trivkins') 284 285 Note: the most supported usage for specifying kinematics in joints_axes 286 is to set values in the configuration ini file [KINS} section and then 287 reference them within the specified [HAL]HALFILES ( .hal .tcl files). For 288 example: 289 290 ---- 291 inifile: [KINS] 292 KINEMATICS = trivkins 293 JOINTS = 3 294 ... 295 296 halfile: loadrt [KINS]KINEMATICS 297 298 haltclfile: loadrt $::KINS(KINEMATICS) 299 ---- 300 301 === Lathe Configurations 302 303 Prior to joints_axes incorporation, lathes were often configured as if they 304 were three axis (XYZ) machines with an unused axis (Y). This was convenient 305 for sharing Hal files (especially for simulation configs) but required 306 specification of [TRAJ]AXES =3, a 'dummy' AXIS_Y section, and provisions for 307 homing the unused Y coordinate. These arrangements are no longer required 308 or recommended. 309 310 Historical lathe configurations used the default options for the trivkins 311 kinematics module. These default options configure all axis letters 312 (XYZABCUVW). With joints_axes incorporation, a more appropriate kinematics 313 specification sets the coordinates to the exact ones used (XZ) and sets the 314 number of joints accordingly to 2. There is no need for an ini file [AXIS_Y] 315 section and only two [JOINT_N] sections need be defined. 316 317 Example ini file items for a lathe (only sections relevant to kinematics 318 are shown): 319 320 ---- 321 [KINS] 322 KINEMATICS = trivkins coordinates=xz 323 JOINTS = 2 324 325 [TRAJ] 326 COORDINATES = XZ 327 ... 328 329 [AXIS_X] 330 ... 331 332 [AXIS_Z] 333 ... 334 335 [JOINT_0] 336 ... 337 338 [JOINT_1] 339 ... 340 ---- 341 342 Note that some simulation configurations may still use the historical lathe 343 configuration precedents. 344 345 === Consistent Joints/Axes specifications 346 347 Ini file items that affect joints and axes usage must be consistent. 348 349 The motion kinematics module typically loaded with '[KINS]KINEMATICS=' must 350 use a number of joints equal to the number specified with '[KINS]JOINTS='. 351 352 The kinematics module must implement axis letters that are consistent with the 353 specification used by the task module item '[TRAJ]COORDINATES='. 354 355 Examples: 356 357 Three axis Cartesian machine using trivkins (KINEMATICS_IDENTITY): 358 ----- 359 [KINS]KINEMATICS = trivkins 360 [KINS]JOINTS = 3 361 [TRAJ]COORDINATES = XYZ 362 ----- 363 364 Two axis lathe using trivkins (KINEMATICS_IDENTITY) with non-consecutive 365 axis letters: 366 ----- 367 [KINS]KINEMATICS = trivkins coordinates=XZ 368 [KINS]JOINTS = 2 369 [TRAJ]COORDINATES = XZ 370 ----- 371 372 Gantry using trivkins with duplicated axis letters and KINEMATICS_BOTH to 373 allow individual joint positioning (for homing): 374 ----- 375 [KINS]KINEMATICS = trivkins coordinates=XYYZ kinstype=BOTH 376 [KINS]JOINTS = 4 377 [TRAJ]COORDINATES = XYYZ 378 ----- 379 380 Gantry using trivkins (KINEMATICS_BOTH) with duplicated axis letters 381 and a rotary axis with skipped axis letters (A,B skipped): 382 ----- 383 [KINS]KINEMATICS = trivkins coordinates=XYYZC kinstype=BOTH 384 [KINS]JOINTS = 5 385 [TRAJ]COORDINATES = XYYZC 386 ----- 387 388 Linear Delta Robot with non-identity kins (KINEMATICS_BOTH) working in Cartesian frame 389 with an additional rotary coordinate: 390 ----- 391 [KINS]KINEMATICS = lineardeltakins 392 [KINS]JOINTS = 4 393 [TRAJ]COORDINATES = XYZA 394 ----- 395 396 Note: Some general-purpose kinematics modules (like trivkins) implement 397 identity kinematics with support for coordinate specification (axis letters). 398 Axis letters may be omitted. Axis letters may be duplicated. 399 Joints are assigned to axis letters in a defined manner ('$ man trivkins'). 400 401 Note: For trivkins module loading, do not include spaces about the = sign or letters: 402 403 This: [KINS]KINEMATICS = trivkins coordinates=XZ 404 NOT This: [KINS]KINEMATICS = trivkins coordinates = X Z 405 406 Note: Custom kinematics modules that implement non-identity kinematics (like 407 lineardeltakins) define machine-specific relationships between a set 408 of coordinates and a set of joints. Typically, custom kinematics modules 409 compute the joints-axes relationships within the custom module but it is 410 important to use consistent settings for the related ini items: '[KINS]JOINTS' 411 and '[TRAJ]COORDINATES'. The details will usually be explained in the 412 module man page (for example, '$ man lineardeltakins'). 413 414 415 === Home sequences 416 417 *Negative* values may be used for the ini file items 418 named [JOINT_n]HOME_SEQUENCE. Prior to joints_axes incorporation a value 419 of -1 or the ommission of the item indicated no sequence was applicable. 420 Now, only omission of the item is used for that purpose. 421 See the chapter: <<cha:homing-configuration, 'Homing Configuration'>> 422 for more information. 423 424 === Locking rotary indexer (updates for joints_axes) 425 426 With joints_axes, an indexer is a joint that can be homed (joint mode) 427 but must also be unlocked from gcode. This requires a one-to-one 428 correspondence between a single joint and an axis. 429 430 Specify the joint number that corresponds to a rotary axis (L = A,B, or C) 431 with an ini file setting for the axis: 432 433 ---- 434 [AXIS_L]LOCKING_INDEXER_JOINT = joint_number_for_indexer 435 ---- 436 437 Specify that the joint is a locking indexer with an ini file setting 438 for the joint (N is the joint_number_for_indexer): 439 440 ---- 441 [JOINT_N]LOCKING_INDEXER = 1 442 ---- 443 444 Hal pins can be created to coordinate use of a locking indicator joint: 445 446 ---- 447 joint.N.unlock (BIT output from Hal) 448 joint.N.is-unlocked (BIT input to Hal) 449 ---- 450 451 To create these hal pins for locking joints, specify all joints that 452 are used as locking indexers with the 'unlock_joints_mask' parameter for 453 the motmod module. (bit0(LSB)==>joint0, bit1==>joint1, etc.) 454 455 ---- 456 [EMCMOT] 457 EMCMOT = motmod unlock_joints_mask=BITMASK 458 ---- 459 460 As an example, consider a machine using trivkins kinematics with coordinates 461 XYZB where B is a locking indexer. For trivkins, joint numbers (starting 462 with 0) are assigned consecutively to the coordinates specified (axis 463 coordinate letters may be omitted). For this example, X==>joint0, Y==>joint1, 464 Z==>joint2, B==>joint3. The mask to specify joint 3 is 000001000 (binary) == 465 0x08 (hexadecimal) 466 467 The required ini file entries for this trivkins XYZB example are: 468 ---- 469 [KINS] 470 JOINTS = 4 471 KINEMATICS = trivkins coordinates=XYZB 472 ... 473 474 [TRAJ] 475 COORDINATES = XYZB 476 ... 477 478 [EMCMOT] 479 EMCMOT = motmod unlock_joints_mask=0x08 480 ... 481 482 [AXIS_B] 483 LOCKING_INDEXER_JOINT = 3 484 ... 485 486 [JOINT_3] 487 LOCKING_INDEXER = 1 488 ... 489 ---- 490 491 For more complex kinematics, select the joint number as required -- there must 492 be a one-to-one correspondence between the rotary axis and the joint number. 493 494 (See the motion man page ('$ man motion') for more information on motmod) 495 496 === Stricter INI file syntax 497 498 Lines with numeric INI variables are no longer allowed to have trailing 499 text. In earlier versions of LinuxCNC any text after the number was 500 silently ignored, but as of this version such text is totally disallowed. 501 This includes hash characters ("#"), which in this position are a part of the value, not a comment character. 502 503 For example, lines like this will no longer be accepted: 504 ----- 505 MAX_VELOCITY = 7.5 # This is the max velocity of the axis. 506 ----- 507 508 They could be transformed into pairs of lines like this: 509 ----- 510 # This is the max velocity of the axis. 511 MAX_VELOCITY = 7.5 512 ----- 513 514 === [TRAJ] settings 515 516 In 2.7.x versions, trajectory planning ([TRAJ]) settings included: 517 518 ---- 519 [TRAJ] 520 DEFAULT_ACCELERATION 521 MAX_ACCELERATION 522 ---- 523 524 Interim work prepared for distinct linear and angular items by 525 renaming these items as: 526 527 ---- 528 [TRAJ] 529 DEFAULT_LINEAR_ACCEL 530 MAX_LINEAR_ACCEL 531 ---- 532 533 As these abbreviated names were inconsistent with other name 534 conventions and the implementation of the update_ini script, 535 the interim naming has been corrected to use: 536 537 ---- 538 [TRAJ] 539 DEFAULT_LINEAR_ACCELERATION 540 MAX_LINEAR_ACCELERATION 541 ---- 542 543 [NOTE] 544 545 Support for specifying trajectory planning angular default and maximum 546 accelerations has not been implemented. 547 548 549 == Hal Changes (updates for joints_axes 2.8.x) 550 551 === Wheel or MPG (manual pulse generator) jogging 552 553 Prior to incorporation of joints_axes updates, wheel jogging was 554 supported in joint mode only and controlled with hal pins: 555 556 ---- 557 bit IN axis.M.jog-enable 558 float IN axis.M.jog-scale 559 s32 IN axis.M.jog-counts 560 bit IN axis.M.jog-vel-mode 561 ---- 562 563 where 'M' is a number corresponding to an axis letter (0==>X, 1==>Y, etc.) 564 565 With incorporation of joints_axes updates, wheel jogging is available 566 for joints in joint mode and for each axis coordinate in teleop mode. The 567 controlling hal pins provided are: 568 569 ---- 570 bit IN joint.N.jog-enable 571 float IN joint.N.jog-scale 572 s32 IN joint.N.jog-counts 573 bit IN joint.N.jog-vel-mode 574 575 bit IN axis.L.jog-enable 576 float IN axis.L.jog-scale 577 s32 IN axis.L.jog-counts 578 bit IN axis.L.jog-vel-mode 579 ---- 580 581 where 'N' is a joint number and 'L' is an axis letter. 582 583 To use an MPG in identity kins configurations where there is a one-to-one 584 correspondence of a joint number and an axis letter, it may be convenient to 585 connect the corresponding hal pins. For example, if joint 1 corresponds 586 exactly to axis letter y: 587 588 ---- 589 net jora_1_y_enable => joint.1.jog-enable => axis.y.jog-enable 590 net jora_1_y_scale => joint.1.jog-scale => axis.y.jog-scale 591 net jora_1_y_counts => joint.1.jog-counts => axis.y.jog-counts 592 net jora_1_y_vel-mode => joint.1.jog-counts => axis.y.jog-vel-mode 593 ---- 594 595 (The signal names jora_1_y_* are examples, names prior to conversion 596 for joints_axes will depend upon the specific configuration details.) 597 598 Configurations with non-identity kinematics and configurations that use 599 duplicated axis letters (for example, gantries using more than one joint for an 600 axis coordinate) will require appropriate independent control logic to support 601 both joint and teleop (world) jogging. 602 603 === Ini Hal pins 604 605 Hal pins are created for ini file items for both joints ([JOINT_N] stanzas) 606 and axes ([AXIS_L] stanzas): 607 608 For N = 0 ... [KINS](JOINTS -1) 609 Ini File Item hal pin name 610 [JOINT_N]BACKLASH ini.N.backlash 611 [JOINT_N]FERROR ini.N.ferror 612 [JOINT_N]MIN_FERROR ini.N.min_ferror 613 [JOINT_N]MIN_LIMIT ini.N.min_limit 614 [JOINT_N]MAX_LIMIT ini.N.max_limit 615 [JOINT_N]MAX_VELOCITY ini.N.max_velocity 616 [JOINT_N]MAX_ACCELERATION ini.N.max_acceleration 617 [JOINT_N]HOME ini.N.home 618 [JOINT_N]HOME_OFFSET ini.N.home_offset 619 620 For L = x y z a b c u v w: 621 Ini File Item hal pin name 622 [AXIS_L]MIN_LIMIT ini.L.min_limit 623 [AXIS_L]MAX_LIMIT ini.L.max_limit 624 [AXIS_L]MAX_VELOCITY ini.L.max_velocity 625 [AXIS_L]MAX_ACCELERATION ini.L.max_acceleration 626 627 Note: In prior versions of LinuxCNC (before joints_axes updates), the 628 hal pin names 'ini.N.*' referred to axes with 0==>x, 1==>y, etc. 629 (pins were created for all 9 axes) 630 See the man page ('$ man milltask') for more information 631 632 == Hal Changes (Other 2.8.x) 633 634 === halcompile 635 636 The number of names= instances was formerly limited to 16. Now, 637 for realtime components (loadrt) the instances are assigned 638 dynamically with no built-in limit. The limit of 16 still 639 applies to names= items for userspace (loadusr) components. 640 641 For components using 'personality', the maximum number is now 642 settable by a command line option -P|--personalities. 643 644 === Parameter to Pin changes 645 646 The following hal output pins were changed from parameters to pins 647 so that they can be connected to signals: 648 649 ---- 650 motion.servo.last-period (servo last period in clks) 651 motion.servo.last-period_ns (kernel-dependent availability) 652 ---- 653 654 == Interface changes for joints_axes 2.8.x 655 656 === python linuxcnc module 657 658 The jog() interface includes a 'joint-flag' to specify joint (True) 659 or teleop (False) jogging: 660 661 ---- 662 jog(command, joint-flag, axis-or-joint-number, velocity[, distance]]) 663 664 jog(linuxcnc.JOG_STOP, joint-flag, axis-or-joint-number) 665 jog(linuxcnc.JOG_CONTINUOUS, joint-flag, joint-flag, velocity) 666 jog(linuxcnc.JOG_INCREMENT, joint-flag, axis-or-joint-number, velocity, distance) 667 ---- 668 669 == GUIs (updates for joints_axes 2.8.x) 670 671 === Notes on joint/axis jogging, homing, and kinematics 672 673 With incorporation of joints_axes updates, LinuxCNC enforces the 674 distinctions of joints and axes (coordinate letters) -- but some 675 guis (like the axis gui) may hide some of the distinctions for 676 simple machines. 677 678 In most cases, you can think of joints as 'motors'. 679 680 The relationships between joints and axis coordinates are 681 determined by the mathmatical kinematics functions that describe a 682 machine's motion. 683 684 World coordinates (X,Y,Z,A,B,C,U,V,W) are determined by applying 685 'FORWARD' kinematics operations to joint (motor) positions. 686 687 When moving in world space (e.g., gcode movements) the required 688 joint (motor) positions are determined by applying 'INVERSE' 689 kinematics operations to the coordinates requested for motion 690 in world space. 691 692 Moving in world space is possible only 'after' homing. 693 694 For simple machines (like mills and lathes) there is a one-to-one 695 equivalence of joints and axis coordinate letters. For example, 696 on an XYZ mill, the relationships are typically: axisX==joint0, 697 axisY==joint1, axisZ=joint2. This correspondence is 698 characterized as 'IDENTITY' kinematics and the kinematics module 699 used is usually trivkins (trivial kinematics). (See the trivkins 700 man page '$ man trivkins') 701 702 Joint jogging (by joint number 0,1,...) is used in joint mode 703 (usually used only 'BEFORE' homing). When homing is completed, 704 the jogging mode is 'AUTOMATICALLY' switched from joint mode to 705 world mode and axis jogging (coordinate letter X,Y,...) is used. 706 This is appropriate for all gcode moves requested by MDI commands 707 or by gcode programs. 708 709 Although jogging in joint mode is often never required after 710 homing, some guis (like axis) provide a keyboard shortcut ('$') 711 to allow toggling between joint and world (teleop) modes for 712 machines that use 'non-IDENTITY' kinematics. 713 714 In many common situations, joint jogging is never needed since 715 homing is accomplished using home switches and/or the various homing 716 methods provided by LinuxCNC. One simply turns on 717 the machine, issues the Home-All command, the machine homes and 718 changes to world mode automatically. See 719 <<cha:homing-configuration,Homing Configuration>> 720 721 Machines that do not use home switches may require manual jogging 722 in joint mode before homing each and every joint. It is also 723 possible to use immediate homing (see the homing docs) for joints 724 that do not require homing to a fixed position. 725 726 Although a gui may hide joints/axes distinctions for 'IDENTITY' 727 kinematics machines, it is usually important to complete homing 728 in order to run programs or use features provided by a gui. 729 730 By default, the trivkins module declares itself as having 731 'IDENTITY' kinematics. The distinctions of joint/world 732 operations can be made visible in the axis gui when using 733 trivkins by setting the kinemetics type to a 'non-IDENTITY' type 734 using 'kinstype=both'. The 'both' setting indicates that both 735 forward and inverse kinematics functions are available and gui 736 provisions that hide the distinctions of joints and axis letters 737 should not be employed. For example, for an xyz configuration, 738 specify: 739 740 ---- 741 [KINS] 742 KINEMATICS = trivkins coordinates=xyz kinstype=both 743 ---- 744 745 With this setting, identity kinematics will be used but the axis 746 gui will: 747 748 . show joint numbers prior to homing 749 . show axis letters after successful homing 750 . support toggling between joint and teleop modes with the '$' key 751 752 === Halui 753 754 Halui now supports teleop jogging resulting in some changed pin names and 755 numerous new names for jogging-related pins. 756 757 See the man page ('$ man halui') for all pin names. 758 759 ==== TELEOP jogging (also called axis or world jogging) 760 761 New pins for teleop jogging are: 762 763 ---- 764 new: halui.axis.jog-speed 765 new: halui.axis.jog-deadband 766 767 new: halui.axis.L.plus 768 new: halui.axis.L.minus 769 ... etc. 770 ---- 771 772 where 'L' is a letter corresponding to one of the axis letters specified by 773 [TRAJ]COORDINATES or 'selected' for the axis selected by the 774 halui.axis.L.select pins. 775 776 ==== Joint jogging 777 778 All pins for joint jogging were renamed for specificity: 779 780 ---- 781 was: halui.jog-speed is: halui.joint.jog-speed 782 was: halui.jog-deadband is: halui.joint.jog-deadband 783 784 was: halui.jog.N.plus is: halui.joint.N.plus 785 was: halui.jog.N.minus is: halui.joint.N.minus 786 ... etc. ... etc. 787 ---- 788 789 where 'N' is a joint number (0 ... num_noints-1) or 'selected' 790 for the joint selected by the halui.joint.N.select pins. 791 792 ==== Aditional pin renames 793 794 The hal pins for 'selected' joints were renamed for consistency 795 with related pins. 796 797 ---- 798 was: halui.joint.selected.is_homed 799 is: halui.joint.selected.is-homed 800 801 was: halui.joint.selected.on-soft-limit 802 is: halui.joint.selected.on-soft-min-limit 803 ---- 804 805 === AXIS GUI 806 807 ==== Identity Kinematics 808 809 The axis gui continues to support identity kinematics configurations. This gui 810 hides the distinctions of axes and joints in order to simplify the display and 811 usage of simple machines. 812 813 ==== Special case kinematics 814 815 Some machines, typically gantrys, may use a configuration with more than 816 one joint assigned to an axis letter. This can be done with the trivkins 817 kinematics module using repeated coordinate letters. For example, a 818 machine configured with ini settings: 819 820 ---- 821 [KINS] 822 KINEMATICS = trivkins coordinates=XYYZ kinstype=BOTH 823 ... 824 [TRAJ] 825 COORDINATES = XYYZ 826 ... 827 ---- 828 829 This machine, after homing, has a one-to-one correspondence between a single 830 axis letter (Y) and a pair of joints (1,2). Using 'kinematics=BOTH' allows 831 control of individual joints in joint mode 'if/when required'. 832 833 ==== Non-identity kinematics 834 835 The axis gui supports configurations using non-identity kinematics with: 836 837 . Key binding ('$') to toggle joint or teleop mode 838 . Preview Tab display of joints or axes according to joint or teleop mode 839 . Preview Tab display of 'Home' and 'Limit' icons in joint mode 840 . Preview Tab display of 'All-homed' and 'Any-limit icons in teleop mode 841 . DRO Tab display of joint or axes according to joint or teleop mode 842 . Jogging is supported in both joint and teleop motion modes 843 . External changes to the joint/teleop motion mode are detected. 844 845 ==== Home icons 846 847 For identity kinematics, 'Home' icons are shown for the correspoinding 848 (one-to-one) axis letter when a joint is homed. 849 850 For non-identity kinematics, 'Home' icons are shown for individual joints when 851 a joint is homed in joint display mode. An 'All-homed' icon is displayed for 852 all axis letters when ALL joints are homed in world display mode. 853 854 ==== Limit icons 855 856 For identity kinematics, 'Limit' icons are shown for the corresponding 857 (one-to-one) axis letter when a joint limit is active. 858 859 For non-identity kinematics, 'Limit' icons are shown for individual joints when 860 the joint limit is active in joint display mode. An 'Any-Limit' icon is displayed 861 if any joint is at a limit in teleop display mode. 862 863 ==== Key bindings for a fourth axis 864 865 In the AXIS gui, jogging keys are assigned to axes in a configurable 866 fashion. For 3-axis machines, XYZA machines, and lathes the default is 867 the same as in 2.7. For other machines, the 4 pairs of jogging keys are 868 assigned to the first 4 axes that exist in the order XYZ ABC UVW. 869 These assignments can be controlled by new inifile directives in the 870 <<sec:display-section,[DISPLAY] section of the inifile>> 871 872 Note that the parameters used for jogging may not be appropriate for both modes 873 for machines with non-identity kinematics. 874 875 876 === tklinuxcnc 877 878 The tklinuxcnc gui supports both identity and non-identity kinematics, includes 879 gui radiobuttons and a key bindiing ('$') for toggling joint and teleop modes. 880 External changes to joint or teleop motion mode are detected. 881 Jogging is supported in both joint and teleop motion modes. 882 Note that the parameters used for jogging may not be appropriate for both modes 883 for machines with non-identity kinematics. 884 885 OpenGL is not used by tklinuxcnc so it may be used to isolate problems and 886 system dependencies that are exposed with more modern guis like axis. 887 888 The rudimentary backplot gui provided is available for use with identity kinematics 889 (xyz) machine configurations. 890 891 ==== emcsh commands 892 893 The code of emcsh.cc provides the set of tcl commands used by tklinuxcnc. The 894 commands are available to tcl applications as the tcl package named 'Linuxcnc'. 895 A number of commands previously required the use of a numeric argument to 896 specify an axis coordinate (0-->X, 1-->Y, ..., 8-->W). These commands have 897 been simplified to use an argument that is just the coordinate letter. 898 899 Commands now using a coordinate letter argument are: 900 901 . emc_pos_offset 902 . emc_abs_cmd_pos 903 . emc_abs_act_pos 904 . emc_rel_cmd_pos 905 . emc_rel_act_pos 906 . emc_tool_offset 907 . emc_probed_pos 908 909 === touchy 910 911 The touchy gui continues to support the identity kinematics configurations 912 that it supported prior to joints_axes incorporation. Jogging is done in 913 teleop mode. 914 915 === gscreen 916 917 The gscreen gui continues to support the identity kinematics configurations 918 that it supported prior to joints_axes incorporation. Jogging is done in 919 teleop mode. 920 921 === gmoccapy 922 923 The gmoccapy gui continues to support the identity kinematics configurations 924 that it supported prior to joints_axes incorporation. Jogging is done in 925 teleop mode. 926 927 928 === `shuttlexpress` driver renamed to `shuttle` 929 930 The HAL driver for the Contour Designs ShuttleXpress device has been 931 renamed from "shuttlexpress" to just "shuttle". If your hal files include 932 some variant of "loadusr shuttlexpress", replace "shuttlexpress" with 933 "shuttle". 934 935 Support has been added for the ShuttlePRO, a bigger version of the 936 ShuttleXpress, so the old driver name is no longer accurate. 937 938 939 === linuxcncrsh 940 941 "Home All" is now supported with the set home subcommand 942 by using -1 for the joint number 943 944 The jogging commands have been altered to accomodate both joint (free) 945 and teleop (world) jogging. 946 947 ---- 948 was: set jog joint_number speed 949 is: set jog joint_number|axis_letter speed 950 951 was: set jog_incr joint_number speed increment 952 is: set jog_incr joint_number|axis_letter speed increment 953 954 was: set jog_stop 955 is: set jog_stop joint_number|axis_letter 956 ---- 957 958 Note: Test for teleop mode using command: get teleop_enable 959 if TELEOP_ENABLE=YES, use axis_letter 960 else use joint_number 961 962 Note: Formerly, the command 'set jog 0 1.234' would jog the zeroth 963 axis (X) with requested speed=1.234 in any mode (free or teleop). 964 This command now attemps to jog the zeroth joint (Joint0) provided 965 the mode is free (not teleop). To jog the X axis, the mode 966 must be teleop and the corresponding command is: 'set jog x 1.234' 967 968 == Tools 969 970 === Calibration (emccalib.tcl) 971 972 The calibration/tuning tool now supports stanzas: 973 974 [JOINT_N], [AXIS_L], [SPINDLE_S], [TUNE] 975 976 where N is a joint number (0 .. ([KINS]JOINTS-1) ), 977 L is an axis coordinate letter (X,Y,Z,A,B,C,U,V,W), 978 and S is a spindle number (0 .. 9) 979 980 [NOTE] 981 982 The number of allowed spindles is 8 but legacy configurations 983 may include a stanza [SPINDLE_9] unrelated to an actual spindle 984 number. 985 986 [NOTE] 987 988 The [TUNE] stanza may be used for specifying tunable items 989 not relevant to the other supported stanzas. 990 991 == Obsolete Guis (removed for 2.8.x) 992 993 The guis 'mini', 'keystick', and 'xlinuxcnc' have been removed in 994 conjunction with updates for joints_axes. All related source code, 995 examples, and documentation are available in the git repository. 996 997 == Deprecated Guis (marked at 2.8.x) 998 999 The 'linuxcnclcd' gui is a candidate for removal. 1000 Should this component be removed, all related source code, examples, 1001 and documentation will be available in the git repository. 1002 1003 == Simulator configurations (updates for joints axes 2.8.x) 1004 1005 === Pre-joints_axes 1006 1007 Prior to joints_axes incorporation, the halfiles used in sim configs 1008 typically supported a common milling machine -- a Cartesian system with 1009 trivial kinematics and three axes named 'X Y Z'. Typical halfile 1010 entries: 1011 1012 ---- 1013 [HAL] 1014 HALFILE = core_sim.hal 1015 HALFILE = sim_spindle_encoder.hal 1016 HALFILE = axis_manualtoolchange.hal 1017 HALFILE = simulated_home.hal 1018 ---- 1019 1020 Lathe configs often shared the same halfiles and used the expedient 1021 method of specifying 3 axes with 'Y' unused. More complex sim configs 1022 provided specific sets of halfiles according to the configuration 1023 purpose. 1024 1025 === Post-joints_axes 1026 1027 With the incorporation of joints_axes functionality, many sims provided 1028 in the distribution now take advantage of a general purpose halfile that 1029 supports numerous configurations automatically. A typical sim config 1030 HALFILE specification is: 1031 1032 ---- 1033 [HAL] 1034 HALFILE = LIB:basic_sim.tcl 1035 ---- 1036 1037 The basic_sim.tcl HALFILE supports a number of commonly required 1038 functions for any number of joints as specified by: 1039 1040 ---- 1041 [KINS] 1042 ... 1043 JOINTS = number_of_joints 1044 ... 1045 ---- 1046 1047 Functions supported include: 1048 1049 . 'ddts' -- differentiator hal components are loaded and connected 1050 for each joint (and xy, xyz for trivkins machines) 1051 1052 . 'simulated_home' -- a sim_home_switch hal component is loaded and 1053 connected for each joint. The homing conditions are specified by the 1054 usual [JOINT_n]HOME_* ini file items. 1055 1056 . 'use_hal_manualtoolchange' -- the user space hal_manualtoolchange 1057 component is loaded and connected. 1058 1059 . 'sim_spindle' -- the sim_spindle component is loaded and connected to 1060 additional loaded hal components to simulate the inertia of a rotating 1061 spindle mass. 1062 1063 The functions are activated by default but can be excluded using 1064 options: '-no_make_ddts', '-no_simulated_home', '-no_use_hal_manualtoolchange', 1065 '-no_sim_spindle'. 1066 1067 For example, to omit creation of ddts: 1068 1069 ---- 1070 HALFILE = LIB:basic_sim.tcl -no_make_ddts 1071 ---- 1072 1073 Omitting one or more of the core functions allows testing without without 1074 the function or addition of new HALFILEs to implement or expand on the 1075 functionality. 1076 1077 ==== Equivalent Hal commands file 1078 1079 When LIB:basic_sim.tcl is used, an equivalent halfile is created (in the 1080 configuration directory) to show the halcmd commands issued. The file 1081 name is based on the name of the inifile with '_cmds' appended to 1082 the basename and a conventional '.hal' file extension. Example: 1083 1084 ---- 1085 inifilename: example.ini 1086 equivalent_halfilename: example_cmds.hal 1087 ---- 1088 1089 The equivalent halfile file supersedes previous instances of files with 1090 the same filename. Inifile variables substitutions specified in the 1091 inifile and interpreted by halcmd are automatically substituted in the 1092 created halfile. If there are [HAL]HALFILEs specified before 1093 LIB:basic_sim.tcl, their halcmd commands are included too. 1094 1095 The equivalent halfile can be used to create a new configuration based on 1096 the original configuration made with LIB:basic_sim.tcl with the 1097 following steps: 1098 1099 1) Run the simulator configuration to create a new equivalent halfile, 1100 for example: 'example_cmds.hal'. 1101 1102 To use this new equivalent halfile in the original simulator 1103 configuration inifile (or a copy of it), edit to change: 1104 1105 ---- 1106 [HAL] 1107 HALFILE = LIB:basic_sim.tcl other_parameters 1108 ---- 1109 1110 to: 1111 1112 ---- 1113 [HAL] 1114 HALFILE = ./example_cmds.hal 1115 ---- 1116 1117 ==== Notes 1118 1119 All components and connections made by LIB:basic_sim.tcl can be viewed 1120 using halcmd. The entire hal configuration (except for userspace 1121 components loaded with loadusr) can be saved to a file using: 1122 1123 ---- 1124 $ halcmd save > hal.save 1125 ---- 1126 1127 Use of LIB:basic_sim.tcl reduces the effort needed to make a simulation 1128 config since it handles most of the required component loading and hal 1129 connections. 1130 1131 The sim config 'Sample Configurations/sim/axis/minimal_xyz.ini' 1132 demonstrates a working xyz configuration that uses LIB:basic_sim.tcl 1133 with a minimal number of ini file settings. 1134 1135 == Miscellaneous updates for 2.8.x 1136 1137 Commits to unreleased branches may make changes that affect testers 1138 and early-adopters of the unreleased software. 1139 1140 === Motion pins 1141 1142 New pins (see the motion man page for more info): 1143 1144 --- 1145 axis.L.jog-accel-fraction 1146 joint.N.jog-accel-fraction 1147 --- 1148 1149 === Hal pins 1150 1151 Name changes: 1152 1153 ---- 1154 was: axis.L.vel-cmd 1155 is: axis.l.teleop-vel-cmd 1156 ---- 1157 1158 New pins: 1159 1160 ---- 1161 motion.homing-inhibit (see motion manpage) 1162 ---- 1163 1164 === Hal component updates 1165 1166 . siggen: new pin 'reset' to set output signal values to predefined state 1167 . biquad: pins 'type,f0,Q,s1,s2' were formerly params 1168 1169 === XHC-HB04 Pendant Support 1170 1171 ==== xhc_hb04_util.comp (helper component) 1172 1173 Remove unused pin 'jogenable-off' 1174 1175 Add pin 'amux-enable' so that the multiplexed acceleration reductions are now 1176 enabled by the ANDing the pins: 'is-manual' and 'amux-enable'. These two pins 1177 are typically connected to 'halui.mode.is-manual' and 'halui.mode.is-teleop' 1178 respectively. 1179 1180 ==== xhc_hb04.tcl (optional LIB configuration halfile) 1181 1182 Remove signal pendant:jogenable-off for removed pin 'pendant_util.jogenable-off' 1183 1184 Support new motion pins for reduced accelerations 1185 (axis.L.jog-accel-fraction, joint.N.jog-accel-fraction) for wheel jogging. 1186 The use of [APPLICATIONS]APP=xhc-hb04-accels is no longer supported. 1187 Reduced accels are applied for wheel jogging only (not for nml commands 1188 issued by guis). 1189 1190 === [JOINT_n]HOME_SEQUENCE Starting values 1191 1192 Starting sequence values may be 0, 1 (or -1) only. See the 1193 "Homing Configuration" documentation for more information. 1194 1195 === [JOINT_n]HOME_SEQUENCE Negative values 1196 1197 Joints using a negative HOME_SEQUENCE are not allowed to jog in joint 1198 mode in order to prevent misalignment (racking) in common gantry 1199 configurations. As always, machines with any kinematics type must be 1200 homed prior to enabling conventional world mode jogging. 1201 1202 === TWOPASS support for complex loadrt config= items 1203 1204 Added twopass support for loadrt config modparams with multiple 1205 settings separated by blanks and enclosed with quotes. Example: 1206 1207 ---- 1208 loadrt hm2_eth board_ip=10.10.10.10 config="num_encoders=2 num_pwmgens=2 num_stepgens=3" 1209 ---- 1210 1211 == Changes beyond 2.8.x (master branch development) 1212 1213 The master branch is version-tagged with prerelease notation, typically 1214 2.9~pre* 1215 1216 === Configuration Updates 1217 1218 ==== Inifile Settings 1219 1220 New: [JOINT_n]HOME_INDEX_NO_ENCODER_RESET -- support encoder with 1221 index that does not reset upon receipt of index pulse following 1222 assertion of index_enable. 1223 1224 === Code Updates 1225 1226 ==== Reverse Run 1227 1228 Support added for reverse run in the trajectory planner, the task, and 1229 motion modules, the python interface, the axis gui, and the test suite. 1230 1231 ==== Number of Joints 1232 1233 The maximum number of joints (EMCMOT_MAX_JOINTS) increased from 9 1234 to 16. The axis gui now supports display of up to 16 joints. 1235 1236 ==== Extra Joints 1237 1238 A new motmod parameter (num_extrajoints) specifies joints that are 1239 homed by conventional joint homing methods but controlled by new hal 1240 pins (joint.N.posthome-cmd) after homing. Such joints may be 1241 managed by independent motion planner/controllers in hal and manipulated 1242 from gcode using custom M-codes. See the motion man page for 1243 more info. 1244 1245 ==== Homing 1246 1247 A homing api is provided by src/emc/motion/homing.h to support users' 1248 custom homing code that replaces src/emc/motion/homing.c with 1249 a user-customized homing.c file. 1250 1251 ==== Other 1252 1253 lib/hallib/sim_lib.tcL: simulate encoder index if [JOINT_n]HOME_USE_INDEX 1254 is specified. 1255 1256 lib/python/vismach.py: new hal pin vismach.plotclear 1257 1258 === Hal 1259 1260 ==== Components 1261 1262 sim_home_switch: added I/O pin for index-enable 1263 1264 === Configs 1265 1266 ==== Simulation Configs 1267 1268 sim/configs/axis/axis_9axis: demonstrate simulated encoder index 1269 1270 // vim: set syntax=asciidoc: