Integrator Manual V2.5, 2016 05 12 AX5214 Linux CNC
User Manual: AX5214
Open the PDF directly: View PDF .
Page Count: 274
Download | |
Open PDF In Browser | View PDF |
Integrator Manual V2.5, 2016-05-12 Integrator Manual V2.5, 2016-05-12 i Integrator Manual V2.5, 2016-05-12 ii Contents I LinuxCNC Introduction 1 1 Integrator Concepts 3 1.1 Stepper Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1 Base Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.2 Step Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Servo Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.1 Basic Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.2 Proportional term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2.3 Integral term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2.4 Derivative term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2.5 Loop tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.6 Manual tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 RTAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.3.1 6 1.2 1.3 II 2 Configuration Latency Test 2.1 3 ACPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Port Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 INI Configuration 3.1 3.2 7 11 The INI File Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1.2 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.1.3 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.1.4 Custom Sections and Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 INI File Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2.1 [EMC] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2.2 [DISPLAY] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Integrator Manual V2.5, 2016-05-12 iii 3.2.3 [FILTER] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.2.4 [RS274NGC] Section 3.2.5 [EMCMOT] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.2.6 [TASK] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.2.7 [HAL] section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.2.8 [HALUI] section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.2.9 [TRAJ] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.2.10 [AXIS_] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 3.2.10.1 Homing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 3.2.10.2 Servo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 3.2.10.3 Stepper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.2.11 [EMCIO] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4 Homing Configuration 25 4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.2 Homing Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.3.1 HOME_SEARCH_VEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.3.2 HOME_LATCH_VEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.3.3 HOME_FINAL_VEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.3.4 HOME_IGNORE_LIMITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.3.5 HOME_USE_INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.6 HOME_OFFSET 4.3.7 HOME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.8 HOME_IS_SHARED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.9 HOME_SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.10 VOLATILE_HOME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.11 LOCKING_INDEXER 4.3.12 Immediate Homing 5 6 Lathe Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 30 5.1 Default Plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.2 INI Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 HAL TCL Files 31 6.1 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 6.2 Haltcl Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 6.3 Haltcl Inifile variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.4 Converting .hal files to .tcl files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.5 Haltcl Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.6 Haltcl Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.7 Haltcl Interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.8 Haltcl Distribution Examples (sim) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Integrator Manual V2.5, 2016-05-12 7 Core Components 7.1 7.2 7.3 9 34 Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 7.1.1 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7.1.2 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7.1.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 7.1.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Axis (Joints) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.2.1 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.2.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 iocontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 7.3.1 8 iv Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Stepper Configuration 39 8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 8.2 Maximum step rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 8.3 Pinout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 8.3.1 standard_pinout.hal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 8.3.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 8.3.3 Changing the standard_pinout.hal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 8.3.4 Changing polarity of a signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.3.5 Adding PWM Spindle Speed Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.3.6 Adding an enable signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.3.7 External ESTOP button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Basic HAL Tutorial 9.1 9.2 44 HAL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 9.1.1 loadrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 9.1.2 addf 9.1.3 loadusr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 9.1.4 net 9.1.5 setp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 9.1.6 sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 9.1.7 unlinkp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 9.1.8 Obsolete Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 9.1.8.1 linksp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 9.1.8.2 linkps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.1.8.3 newsig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 HAL Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.2.1 Bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Integrator Manual V2.5, 2016-05-12 9.2.2 Float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.2.3 s32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.2.4 u32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.3 HAL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 9.4 HAL Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 9.5 Logic Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 9.6 9.5.1 and2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 9.5.2 not . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 9.5.3 or2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 9.5.4 xor2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 9.5.5 Logic Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Conversion Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 9.6.1 III v weighted_sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 GUI 54 10 Python Virtual Control Panel 55 10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 10.2 Panel Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 10.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 10.4 AXIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 10.5 Stand Alone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 10.6 Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 10.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 10.6.2 General Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 10.6.2.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 10.6.2.2 Editing the XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 10.6.2.3 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 10.6.2.4 HAL Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 10.6.3 Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 10.6.4 LEDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 10.6.4.1 Round LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 10.6.4.2 Rectangle LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 10.6.5 Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 10.6.5.1 Text Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 10.6.5.2 Checkbutton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 10.6.5.3 Radiobutton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 10.6.6 Number Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 10.6.6.1 Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Integrator Manual V2.5, 2016-05-12 vi 10.6.6.2 s32 Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 10.6.6.3 u32 Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 10.6.6.4 Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 10.6.6.5 Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 10.6.7 Number Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 10.6.7.1 Spinbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 10.6.7.2 Scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 10.6.7.3 Dial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 10.6.7.4 Jogwheel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 10.6.8 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 10.6.8.1 Image Bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 10.6.8.2 Image u32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 10.6.9 Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 10.6.9.1 Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 10.6.9.2 Hbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 10.6.9.3 Vbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 10.6.9.4 Labelframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 10.6.9.5 Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 10.6.9.6 Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 11 PyVCP Examples 75 11.1 AXIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 11.2 Floating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 11.3 Jog Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 11.3.1 Create the Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 11.3.2 Make Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 11.4 Port Tester . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 11.5 GS2 RPM Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 11.5.1 The Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 11.5.2 The Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 12 Glade Virtual Control Panel 85 12.1 What is GladeVCP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 12.1.1 PyVCP versus GladeVCP at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 12.2 A Quick Tour with the Example Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 12.2.1 Exploring the example panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 12.2.2 Exploring the User Interface description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 12.2.3 Exploring the Python callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 12.3 Creating and Integrating a Glade user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Integrator Manual V2.5, 2016-05-12 vii 12.3.1 Prerequisite: Glade installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 12.3.2 Running Glade to create a new user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 12.3.3 Testing a panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 12.3.4 Preparing the HAL command file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 12.3.5 Integrating into Axis like PyVCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 12.3.6 Integrating into Axis as a tab next to DRO and Preview . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 12.3.7 Integrating into Touchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 12.4 GladeVCP command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 12.5 Understanding the gladeVCP startup process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 12.6 HAL Widget reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 12.6.1 Widget and HAL pin naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 12.6.2 Python attributes and methods of HAL Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 12.6.3 Setting pin and widget values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 12.6.4 The hal-pin-changed signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 12.6.5 Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 12.6.6 Scales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 12.6.7 SpinButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 12.6.8 Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 12.6.9 Containers: HAL_HBox and HAL_Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 12.6.10 LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 12.6.11 ProgressBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 12.6.12 ComboBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 12.6.13 Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 12.6.14 Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 12.6.15 Gremlin tool path preview for .ngc files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 12.6.16 Animated function diagrams: HAL widgets in a bitmap . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 12.7 Action Widgets reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 12.7.1 EMC Action widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 12.7.2 EMC ToggleAction widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 12.7.3 The Action_MDI Toggle and Action_MDI widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 12.7.4 A simple example: Execute MDI command on button press . . . . . . . . . . . . . . . . . . . . . . . . 104 12.7.5 Parameter passing with Action_MDI and ToggleAction_MDI widgets . . . . . . . . . . . . . . . . . . . 105 12.7.6 An advanced example: Feeding parameters to an O-word subroutine . . . . . . . . . . . . . . . . . . . . 105 12.7.7 Preparing for an MDI Action, and cleaning up afterwards . . . . . . . . . . . . . . . . . . . . . . . . . . 106 12.7.8 Using the LinuxCNC Stat object to deal with status changes . . . . . . . . . . . . . . . . . . . . . . . . 106 12.8 GladeVCP Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 12.8.1 User Defined Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 12.8.2 An example: adding custom user callbacks in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 12.8.3 HAL value change events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Integrator Manual V2.5, 2016-05-12 viii 12.8.4 Programming model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 12.8.4.1 The simple handler model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 12.8.4.2 The class-based handler model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 12.8.4.3 The get_handlers protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 12.8.5 Initialization sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 12.8.6 Multiple callbacks with the same name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 12.8.7 The GladeVCP -U flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 12.8.8 Persistent variables in GladeVCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 12.8.8.1 Persistence, program versions and the signature check . . . . . . . . . . . . . . . . . . . . . . 111 12.8.9 Using persistent variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 12.8.10 Saving the state on Gladvcp shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 12.8.11 Saving state when Ctrl-C is pressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 12.8.12 Hand-editing .ini files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 12.8.13 Adding HAL pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 12.8.14 Adding timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 12.8.15 Setting HAL widget properties programmatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 12.8.16 Examples, and rolling your own GladeVCP application . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 12.9 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 12.10Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 12.11Implementation note: Key handling in Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 12.12Adding Custom Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 13 HAL User Interface 116 13.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 13.2 Halui pin reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 14 Halui Examples 122 14.1 Remote Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 14.2 Pause & Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 IV Hardware Drivers 15 Parallel Port Driver 124 125 15.1 Parport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 15.1.1 Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 15.1.2 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 15.1.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 15.1.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 15.1.5 Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 15.1.6 Using DoubleStep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 15.2 probe_parport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 15.2.1 Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Integrator Manual V2.5, 2016-05-12 16 AX5214H Driver ix 129 16.1 Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 16.2 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 16.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 16.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 17 GS2 VFD Driver 131 17.1 Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 17.2 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 17.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 18 Mesa HostMot2 Driver 133 18.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 18.2 Firmware Binaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 18.3 Installing Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 18.4 Loading HostMot2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 18.5 Watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 18.5.1 Pins: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 18.5.2 Parameters: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 18.5.3 Functions: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 18.6 HostMot2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 18.7 Pinouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 18.8 PIN Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 18.9 Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 18.10HAL Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 18.11Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 18.12GPIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 18.12.1 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 18.12.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 18.13StepGen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 18.13.1 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 18.13.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 18.13.3 Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 18.14PWMGen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 18.14.1 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 18.14.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 18.14.3 Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 18.15Encoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 18.15.1 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Integrator Manual V2.5, 2016-05-12 x 18.15.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 18.165i25 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 18.16.1 Firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 18.16.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 18.16.3 SSERIAL Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 18.16.4 7i77 Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 18.17Example Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 19 Motenc Driver 145 19.1 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 19.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 19.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 20 Opto22 Driver 147 20.1 The Adapter Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 20.2 The Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 20.3 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 20.4 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 20.5 FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 20.6 Configuring I/O Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 20.7 Pin Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 21 Pico Drivers 150 21.1 Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 21.2 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 21.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 21.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 22 Pluto P Driver 154 22.1 General Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 22.1.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 22.1.2 Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 22.1.3 Physical Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 22.1.4 LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 22.1.5 Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 22.1.6 PC interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 22.1.7 Rebuilding the FPGA firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 22.1.8 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 22.2 Pluto Servo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 22.2.1 Pinout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Integrator Manual V2.5, 2016-05-12 xi 22.2.2 Input latching and output updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 22.2.3 HAL Functions, Pins and Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 22.2.4 Compatible driver hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 22.3 Pluto Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 22.3.1 Pinout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 22.3.2 Input latching and output updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 22.3.3 Step Waveform Timings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 22.3.4 HAL Functions, Pins and Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 23 Servo To Go Driver 161 23.1 Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 23.2 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 23.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 23.3.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 24 ShuttleXpress 163 24.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 24.2 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 24.3 Pins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 V Advanced Topics 25 Python Interface 165 166 25.1 The linuxcnc Python module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 25.2 Usage Patterns for the LinuxCNC NML interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 25.3 Reading LinuxCNC status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 25.3.1 linuxcnc.stat attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 25.3.2 The axis dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 25.4 Preparing to send commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 25.5 Sending commands through linuxcnc.command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 25.5.1 linuxcnc.command attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 25.5.2 linuxcnc.command methods: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 25.6 Reading the error channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 25.7 Reading ini file values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 25.8 The linuxcnc.positionlogger type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 25.8.1 members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 25.8.2 methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Integrator Manual V2.5, 2016-05-12 26 Kinematics xii 178 26.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 26.1.1 Joints vs. Axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 26.2 Trivial Kinematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 26.3 Non-trivial kinematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 26.3.1 Forward transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 26.3.2 Inverse transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 26.4 Implementation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 27 Stepper Tuning 182 27.1 Getting the most out of Software Stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 27.1.1 Run a Latency Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 27.1.2 Figure out what your drives expect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 27.1.3 Choose your BASE_PERIOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 27.1.4 Use steplen, stepspace, dirsetup, and/or dirhold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 27.1.5 No Guessing! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 28 PID Tuning 185 28.1 PID Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 28.1.1 Control loop basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 28.1.2 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 28.1.2.1 Proportional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 28.1.2.2 Integral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 28.1.2.3 Derivative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 28.1.3 Loop Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 28.1.3.1 Simple method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 28.1.3.2 Ziegler-Nichols method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 28.1.3.3 Final Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 VI Ladder Logic 29 Classicladder Introduction 188 189 29.1 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 29.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 29.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 29.4 Basic Latching On-Off Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Integrator Manual V2.5, 2016-05-12 30 Classicladder Programming xiii 192 30.1 Ladder Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 30.2 Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 30.3 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 30.3.1 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 30.3.2 Realtime Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 30.3.3 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 30.4 Loading the Classic Ladder user module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 30.5 Classic Ladder GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 30.5.1 Sections Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 30.5.2 Section Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 30.5.3 The Variable Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 30.5.4 Symbol Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 30.5.5 The Editor window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 30.5.6 Config Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 30.6 Ladder objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 30.6.1 CONTACTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 30.6.2 IEC TIMERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 30.6.3 TIMERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 30.6.4 MONOSTABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 30.6.5 COUNTERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 30.6.6 COMPARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 30.6.7 VARIABLE ASSIGNMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 30.6.8 COILS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 30.6.8.1 JUMP COIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.6.8.2 CALL COIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.7 Classic Ladder Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.8 GRAFCET Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 30.9 Modbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 30.9.1 MODBUS Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 30.9.2 MODBUS Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 30.9.3 Communication Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 30.9.4 MODBUS Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 30.10Setting up Classic Ladder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 30.10.1 Add the Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 30.10.2 Adding Ladder Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Integrator Manual V2.5, 2016-05-12 31 Classicladder Examples xiv 222 31.1 Wrapping Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 31.2 Reject Extra Pulses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 31.3 External E-Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 31.4 Timer/Operate Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 VII Hardware Examples 229 32 PCI Parallel Port 230 33 Spindle Control 231 33.1 0-10v Spindle Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 33.2 PWM Spindle Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 33.3 Spindle Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 33.4 Spindle Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 33.5 Spindle Soft Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 33.6 Spindle Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 33.6.1 Spindle Synchronized Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 33.6.2 Spindle At Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 34 MPG Pendant 235 35 GS2 Spindle 238 VIII Diagnostics & FAQ 36 Stepper Diagnostics 239 240 36.1 Common Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 36.1.1 Stepper Moves One Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 36.1.2 No Steppers Move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 36.1.3 Distance Not Correct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 36.2 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 36.2.1 Following Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 36.2.2 RTAPI Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 36.3 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 36.3.1 Step Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Integrator Manual V2.5, 2016-05-12 37 Linux FAQ xv 243 37.1 Automatic Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 37.2 Automatic Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 37.3 Man Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 37.4 List Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 37.5 Editing a Root File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 37.5.1 The Command Line Way . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 37.5.2 The GUI Way . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 37.5.3 Root Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 37.6 Terminal Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 37.6.1 Working Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 37.6.2 Changing Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 37.6.3 Listing files in a directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 37.6.4 Finding a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 37.6.5 Searching for Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 37.6.6 Bootup Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 37.7 Convenience Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 37.7.1 Terminal Launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 37.8 Hardware Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 37.8.1 Hardware Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 37.8.2 Monitor Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 37.9 Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 38 Glossary 247 39 Legal Section 252 39.1 Copyright Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 39.2 GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 40 Index 256 Integrator Manual V2.5, 2016-05-12 The LinuxCNC Team xvi Integrator Manual V2.5, 2016-05-12 1 / 258 Part I LinuxCNC Introduction Integrator Manual V2.5, 2016-05-12 2 / 258 This handbook is a work in progress. If you are able to help with writing, editing, or graphic preparation please contact any member of the writing team or join and send an email to emc-users@lists.sourceforge.net. Copyright © 2000-2012 LinuxCNC.org Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and one Back-Cover Text: This LinuxCNC Handbook is the product of several authors writing for linuxCNC.org. As you find it to be of value in your work, we invite you to contribute to its revision and growth. A copy of the license is included in the section entitled GNU Free Documentation License. If you do not find the license you may order a copy from Free Software Foundation, Inc. 59 Temple Place, Suite 330 Boston, MA 02111-1307 LINUX® is the registered trademark of Linus Torvalds in the U.S. and other countries. The registered trademark Linux® is used pursuant to a sublicense from LMI, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis. Integrator Manual V2.5, 2016-05-12 3 / 258 Chapter 1 Integrator Concepts 1.1 1.1.1 Stepper Systems Base Period BASE_PERIOD is the heartbeat of your LinuxCNC computer.1 Every period, the software step generator decides if it is time for another step pulse. A shorter period will allow you to generate more pulses per second, within limits. But if you go too short, your computer will spend so much time generating step pulses that everything else will slow to a crawl, or maybe even lock up. Latency and stepper drive requirements affect the shortest period you can use. Worst case latencies might only happen a few times a minute, and the odds of bad latency happening just as the motor is changing direction are low. So you can get very rare errors that ruin a part every once in a while and are impossible to troubleshoot. The simplest way to avoid this problem is to choose a BASE_PERIOD that is the sum of the longest timing requirement of your drive, and the worst case latency of your computer. This is not always the best choice. For example, if you are running a drive with a 20 us direction signal hold time requirement, and your latency test said you have a maximum latency of 11 us , then if you set the BASE_PERIOD to 20+11 = 31 us you get a not-so-nice 32,258 steps per second in one mode and 16,129 steps per second in another mode. The problem is with the 20 us hold time requirement. That plus the 11 us latency is what forces us to use a slow 31 us period. But the LinuxCNC software step generator has some parameters that let you increase the various times from one period to several. For example, if steplen 2 is changed from 1 to 2, then there will be two periods between the beginning and end of the step pulse. Likewise, if dirhold 3 is changed from 1 to 3, there will be at least three periods between the step pulse and a change of the direction pin. If we can use dirhold to meet the 20 us hold time requirement, then the next longest time is the 4.5 us high time. Add the 11 us latency to the 4.5 us high time, and you get a minimum period of 15.5 us . When you try 15.5 us , you find that the computer is sluggish, so you settle on 16 us . If we leave dirhold at 1 (the default), then the minimum time between step and direction is the 16 us period minus the 11 us latency = 5 us , which is not enough. We need another 15 us . Since the period is 16 us , we need one more period. So we change dirhold from 1 to 2. Now the minimum time from the end of the step pulse to the changing direction pin is 5+16=21 us , and we don’t have to worry about the drive stepping the wrong direction because of latency. For more information on stepgen see the stepgen section of the HAL manual. 1.1.2 Step Timing Step Timing and Step Space on some drives are different. In this case the Step point becomes important. If the drive steps on the falling edge then the output pin should be inverted. 1 This section refers to using stepgen, LinuxCNC’s built-in step generator. Some hardware devices have their own step generator and do not use LinuxCNC’s built-in one. In that case, refer to your hardware manual. 2 steplen refers to a parameter that adjusts the performance of LinuxCNC’s built-in step generator, stepgen, which is a HAL component. This parameter adjusts the length of the step pulse itself. Keep reading, all will be explained eventually. 3 dirhold refers to a parameter that adjusts the length of the direction hold time. Integrator Manual V2.5, 2016-05-12 1.2 Servo Systems 1.2.1 Basic Operation 4 / 258 Servo systems are capable of greater speed and accuracy than equivalent stepper systems, but are more costly and complex. Unlike stepper systems, servo systems require some type of position feedback device, and must be adjusted or tuned, as they don’t quite work right out of the box as a stepper system might. These differences exist because servos are a closed loop system, unlike stepper motors which are generally run open loop. What does closed loop mean? Let’s look at a simplified diagram of how a servomotor system is connected. Figure 1.1: Servo Loop This diagram shows that the input signal (and the feedback signal) drive the summing amplifier, the summing amplifier drives the power amplifier, the power amplifier drives the motor, the motor drives the load (and the feedback device), and the feedback device (and the input signal) drive the motor. This looks very much like a circle (a closed loop) where A controls B, B controls C, C controls D, and D controls A. If you have not worked with servo systems before, this will no doubt seem a very strange idea at first, especially as compared to more normal electronic circuits, where the inputs proceed smoothly to the outputs, and never go back.4 If everything controls everything else, how can that ever work, who’s in charge? The answer is that LinuxCNC can control this system, but it has to do it by choosing one of several control methods. The control method that LinuxCNC uses, one of the simplest and best, is called PID. PID stands for Proportional, Integral, and Derivative. The Proportional value determines the reaction to the current error, the Integral value determines the reaction based on the sum of recent errors, and the Derivative value determines the reaction based on the rate at which the error has been changing. They are three common mathematical techniques that are applied to the task of getting a working process to follow a set point. In the case of LinuxCNC the process we want to control is actual axis position and the set point is the commanded axis position. 4 If it helps, the closest equivalent to this in the digital world are state machines, sequential machines and so forth, where what the outputs are doing now depends on what the inputs (and the outputs) were doing before. If it doesn’t help, then nevermind. Integrator Manual V2.5, 2016-05-12 5 / 258 Figure 1.2: PID Loop By tuning the three constants in the PID controller algorithm, the controller can provide control action designed for specific process requirements. The response of the controller can be described in terms of the responsiveness of the controller to an error, the degree to which the controller overshoots the set point and the degree of system oscillation. 1.2.2 Proportional term The proportional term (sometimes called gain) makes a change to the output that is proportional to the current error value. A high proportional gain results in a large change in the output for a given change in the error. If the proportional gain is too high, the system can become unstable. In contrast, a small gain results in a small output response to a large input error. If the proportional gain is too low, the control action may be too small when responding to system disturbances. In the absence of disturbances, pure proportional control will not settle at its target value, but will retain a steady state error that is a function of the proportional gain and the process gain. Despite the steady-state offset, both tuning theory and industrial practice indicate that it is the proportional term that should contribute the bulk of the output change. 1.2.3 Integral term The contribution from the integral term (sometimes called reset) is proportional to both the magnitude of the error and the duration of the error. Summing the instantaneous error over time (integrating the error) gives the accumulated offset that should have been corrected previously. The accumulated error is then multiplied by the integral gain and added to the controller output. The integral term (when added to the proportional term) accelerates the movement of the process towards set point and eliminates the residual steady-state error that occurs with a proportional only controller. However, since the integral term is responding to accumulated errors from the past, it can cause the present value to overshoot the set point value (cross over the set point and then create a deviation in the other direction). 1.2.4 Derivative term The rate of change of the process error is calculated by determining the slope of the error over time (i.e. its first derivative with respect to time) and multiplying this rate of change by the derivative gain. The derivative term slows the rate of change of the controller output and this effect is most noticeable close to the controller set point. Hence, derivative control is used to reduce the magnitude of the overshoot produced by the integral component and improve the combined controller-process stability. Integrator Manual V2.5, 2016-05-12 1.2.5 6 / 258 Loop tuning If the PID controller parameters (the gains of the proportional, integral and derivative terms) are chosen incorrectly, the controlled process input can be unstable, i.e. its output diverges, with or without oscillation, and is limited only by saturation or mechanical breakage. Tuning a control loop is the adjustment of its control parameters (gain/proportional band, integral gain/reset, derivative gain/rate) to the optimum values for the desired control response. 1.2.6 Manual tuning A simple tuning method is to first set the I and D values to zero. Increase the P until the output of the loop oscillates, then the P should be set to be approximately half of that value for a quarter amplitude decay type response. Then increase I until any offset is correct in sufficient time for the process. However, too much I will cause instability. Finally, increase D, if required, until the loop is acceptably quick to reach its reference after a load disturbance. However, too much D will cause excessive response and overshoot. A fast PID loop tuning usually overshoots slightly to reach the set point more quickly; however, some systems cannot accept overshoot, in which case an over-damped closed-loop system is required, which will require a P setting significantly less than half that of the P setting causing oscillation. 1.3 RTAI The Real Time Application Interface (RTAI) is used to provide the best Real Time (RT) performance. The RTAI patched kernel lets you write applications with strict timing constraints. RTAI gives you the ability to have things like software step generation which require precise timing. 1.3.1 ACPI The Advanced Configuration and Power Interface (ACPI) has a lot of different functions, most of which interfere with RT performance (for example: power management, CPU power down, CPU frequency scaling, etc). The LinuxCNC kernel (and probably all RTAI-patched kernels) has ACPI disabled. ACPI also takes care of powering down the system after a shutdown has been started, and that’s why you might need to push the power button to completely turn off your computer. The RTAI group has been improving this in recent releases, so your LinuxCNC system may shut off by itself after all. Integrator Manual V2.5, 2016-05-12 7 / 258 Part II Configuration Integrator Manual V2.5, 2016-05-12 8 / 258 Chapter 2 Latency Test This test is the first test that should be performed on a PC to see if it is able to drive a CNC machine. Latency is how long it takes the PC to stop what it is doing and respond to an external request. For LinuxCNC the request is BASE_THREAD that makes the periodic heartbeat that serves as a timing reference for the step pulses. The lower the latency, the faster you can run the heartbeat, and the faster and smoother the step pulses will be. Latency is far more important than CPU speed. A lowly Pentium II that responds to interrupts within 10 microseconds each and every time can give better results than the latest and fastest P4 Hyperthreading beast. The CPU isn’t the only factor in determining latency. Motherboards, video cards, USB ports, and a number of other things can hurt the latency. The best way to find out what you are dealing with is to run the RTAI latency test. Generating step pulses in software has one very big advantage - it’s free. Just about every PC has a parallel port that is capable of outputting step pulses that are generated by the software. However, software step pulses also have some disadvantages: • limited maximum step rate • jitter in the generated pulses • loads the CPU The best way to find out how well your PC will lrun LinuxCNC is to run the HAL latency test. To run the test, open a terminal window (In Ubuntu, from Applications → Accessories → Terminal) and run the following command: latency-test You should see something like this: Integrator Manual V2.5, 2016-05-12 9 / 258 Figure 2.1: HAL Latency Test While the test is running, you should abuse the computer. Move windows around on the screen. Surf the web. Copy some large files around on the disk. Play some music. Run an OpenGL program such as glxgears. The idea is to put the PC through its paces while the latency test checks to see what the worst case numbers are. Note Do not run LinuxCNC or Stepconf while the latency test is running. The important numbers are the max jitter. In the example above, that is 9075 nanoseconds, or 9.075 microseconds. Record this number, and enter it in Stepconf when it is requested. In the example above, latency-test only ran for a few seconds. You should run the test for at least several minutes; sometimes the worst case latency doesn’t happen very often, or only happens when you do some particular action. For instance, one Intel motherboard worked pretty well most of the time, but every 64 seconds it had a very bad 300 us latency. Fortunately that was fixable, see http://wiki.linuxcnc.org/cgi-bin/wiki.pl?FixingSMIIssues So, what do the results mean? If your Max Jitter number is less than about 15-20 microseconds (15000-20000 nanoseconds), the computer should give very nice results with software stepping. If the max latency is more like 30-50 microseconds, you can still get good results, but your maximum step rate might be a little disappointing, especially if you use microstepping or have very fine pitch leadscrews. If the numbers are 100 us or more (100,000 nanoseconds), then the PC is not a good candidate for software stepping. Numbers over 1 millisecond (1,000,000 nanoseconds) mean the PC is not a good candidate for LinuxCNC, regardless of whether you use software stepping or not. Note that if you get high numbers, there may be ways to improve them. Another PC had very bad latency (several milliseconds) when using the onboard video. But a $5 used video card solved the problem. Note LinuxCNC does not require bleeding edge hardware. For more information on stepper tuning see the Stepper Tuning Chapter. Integrator Manual V2.5, 2016-05-12 2.1 10 / 258 Port Address For those who build their own hardware, one safeguard against shorting out an on-board parallel port - or even the whole motherboard - is to use an add-on parallel port card. Even if you don’t need the extra layer of safety, a parport card is a good way to add extra I/O lines with LinuxCNC. One good PCI parport card is made with the Netmos 9815 chipset. It has good +5V signals, and can come in a single or dual ports. To find the I/O addresses for these cards open a terminal window and use the list pci command: lspci -v Look for the entry with "Netmos" in it. Example of a 2-port card: 0000:01:0a.0 Communication controller: \ Netmos Technology PCI 9815 Multi-I/O Controller (rev 01) Subsystem: LSI Logic / Symbios Logic 2POS (2 port parallel adapter) Flags: medium devsel, IRQ 5 I/O ports at b800 [size=8] I/O ports at bc00 [size=8] I/O ports at c000 [size=8] I/O ports at c400 [size=8] I/O ports at c800 [size=8] I/O ports at cc00 [size=16] From experimentation, I’ve found the first port (the on-card port) uses the third address listed (c000), and the second port (the one that attaches with a ribbon cable) uses the first address listed (b800). You can then open an editor and put the addresses into the appropriate place in your .hal file. loadrt hal_parport cfg="0x378 0xc000" You must also direct LinuxCNC to run the read and write functions for the second card. For example, addf parport.1.read base-thread 1 addf parport.1.write base-thread -1 Please note that your values will differ. The Netmos cards are Plug-N-Play, and might change their settings depending on which slot you put them into, so if you like to ’get under the hood’ and re-arrange things, be sure to check these values before you start LinuxCNC. Integrator Manual V2.5, 2016-05-12 11 / 258 Chapter 3 INI Configuration 3.1 The INI File Components A typical INI file follows a rather simple layout that includes; • comments • sections • variables Each of these elements is separated on single lines. Each end of line or newline character creates a new element. 3.1.1 Comments A comment line is started with a ; or a # mark. When the ini reader sees either of these marks at the start a line, the rest of the line is ignored by the software. Comments can be used to describe what an INI element will do. ; This is my mill configuration file. # I set it up on January 12, 2012 Comments can also be used to turn off a variable. This makes it easier to pick between different variables. DISPLAY = axis # DISPLAY = touchy In this list, the DISPLAY variable will be set to axis because the other one is commented out. If someone carelessly edits a list like this and leaves two of the lines uncommented, the first one encountered will be used. Note that inside a variable, the "#" and ";" characters do not denote comments: INCORRECT = value # Correct Comment CORRECT = value # and a comment Integrator Manual V2.5, 2016-05-12 3.1.2 12 / 258 Sections Related parts of an ini file are separated into sections. A section name is enclosed in brackets like this [THIS_SECTION] The order of sections is unimportant. Sections begin at the section name and end at the next section name. The following sections are used by LinuxCNC: • [EMC] general information • [DISPLAY] settings related to the graphical user interface • [FILTER] settings input filter programs • [RS274NGC] settings used by the g-code interpreter • [EMCMOT] settings used by the real time motion controller • [TASK] settings used by the task controller • [HAL] specifies .hal files • [HALUI] MDI commands used by HALUI • [TRAJ] additional settings used by the real time motion controller • [AXIS_n] individual axis variables • [EMCIO] settings used by the I/O Controller 3.1.3 Variables A variable line is made up of a variable name, an equals sign (=), and a value. Everything from the first non-white space character after the = up to the end of the line is passed as the value, so you can embed spaces in string symbols if you want to or need to. A variable name is often called a keyword. The following sections detail each section of the configuration file, using sample values for the configuration lines. Variables that are used by LinuxCNC must always use the section names and variable names as shown. In the following example the variable MACHINE is assigned the value My Machine. Variable Example MACHINE = My Machine 3.1.4 Custom Sections and Variables Most sample configurations use custom sections and variables to put all of the settings into one location for convenience. To use a custom section variable in your HAL file add the section and variable to the INI file. Custom Section Example [OFFSETS] OFFSET_1 = 0.1234 To add a custom variable to a LinuxCNC section simply include the variable in that section. Custom Variable Example [AXIS_0] TYPE = LINEAR ... SCALE = 16000 Integrator Manual V2.5, 2016-05-12 13 / 258 To use the custom variables in your HAL file put the section and variable name in place of the value. HAL Example setp offset.1.offset [OFFSETS]OFFSET_1 setp stepgen.0.position-scale [AXIS_0]SCALE Note The value stored in the variable must match the type specified by the component pin. 3.2 3.2.1 INI File Sections [EMC] Section • VERSION = $Revision: 1.3 $ - The version number for the INI file. The value shown here looks odd because it is automatically updated when using the Revision Control System. It’s a good idea to change this number each time you revise your file. If you want to edit this manually just change the number and leave the other tags alone. • MACHINE = My Controller - This is the name of the controller, which is printed out at the top of most graphical interfaces. You can put whatever you want here as long as you make it a single line long. • DEBUG = 0 - Debug level 0 means no messages will be printed when LinuxCNC is run from a terminal. Debug flags are usually only useful to developers. See src/emc/nml_intf/emcglb.h for other settings. 3.2.2 [DISPLAY] Section Different user interface programs use different options, and not every option is supported by every user interface. The main two interfaces for LinuxCNC are AXIS and Touchy. Axis is an interface for use with normal computer and monitor, Touchy is for use with touch screens. Descriptions of the interfaces are in the Interfaces section of the User Manual. • DISPLAY = axis - The name of the user interface to use. Valid options may include: axis, touchy, keystick, mini, tklinuxcnc, xemc, • POSITION_OFFSET = RELATIVE - The coordinate system (RELATIVE or MACHINE) to show when the user interface starts. The RELATIVE coordinate system reflects the G92 and G5x coordinate offsets currently in effect. • POSITION_FEEDBACK = ACTUAL - The coordinate value (COMMANDED or ACTUAL) to show when the user interface starts. The COMMANDED position is the ideal position requested by LinuxCNC. The ACTUAL position is the feedback position of the motors. • MAX_FEED_OVERRIDE = 1.2 - The maximum feed override the user may select. 1.2 means 120% of the programmed feed rate. • MIN_SPINDLE_OVERRIDE = 0.5 - The minimum spindle override the user may select. 0.5 means 50% of the programmed spindle speed. (This is useful as it’s dangerous to run a program with a too low spindle speed). • MAX_SPINDLE_OVERRIDE = 1.0 - The maximum spindle override the user may select. 1.0 means 100% of the programmed spindle speed. • PROGRAM_PREFIX = ~/linuxcnc/nc_files - The default location for g-code files and the location for user-defined M-codes. This location is searched for the file name before the subroutine path and user M path if specified in the [RS274NGC] section. • INTRO_GRAPHIC = emc2.gif - The image shown on the splash screen. • INTRO_TIME = 5 - The maximum time to show the splash screen, in seconds. • CYCLE_TIME = 0.05 - Cycle time in seconds that display will sleep between polls. Integrator Manual V2.5, 2016-05-12 14 / 258 Note The following [DISPLAY] items are for the AXIS interface only. • DEFAULT_LINEAR_VELOCITY = .25 - The default velocity for linear jogs, in , machine units per second. • MIN_VELOCITY = .01 - The approximate lowest value the jog slider. • MAX_LINEAR_VELOCITY = 1.0 - The maximum velocity for linear jogs, in machine units per second. • MIN_LINEAR_VELOCITY = .01 - The approximate lowest value the jog slider. • DEFAULT_ANGULAR_VELOCITY = .25 - The default velocity for angular jogs, in machine units per second. • MIN_ANGULAR_VELOCITY = .01 - The approximate lowest value the angular jog slider. • MAX_ANGULAR_VELOCITY = 1.0 - The maximum velocity for angular jogs, in machine units per second. • INCREMENTS = 1 mm, .5 in, . . . - Defines the increments available for incremental jogs. The INCREMENTS can be used to override the default. The values can be decimal numbers (e.g., 0.1000) or fractional numbers (e.g., 1/16), optionally followed by a unit (cm, mm, um, inch, in or mil). If a unit is not specified the machine unit is assumed. Metric and imperial distances may be mixed: INCREMENTS = 1 inch, 1 mil, 1 cm, 1 mm, 1 um is a valid entry. • OPEN_FILE = /full/path/to/file.ngc - The file to show in the preview plot when AXIS starts. Use a blank string "" and no file will be loaded at start up. • EDITOR = gedit - The editor to use when selecting File > Edit to edit the G code from the AXIS menu. This must be configured for this menu item to work. Another valid entry is gnome-terminal -e vim. • TOOL_EDITOR = tooledit - The editor to use when editing the tool table (for example by selecting "File > Edit tool table. . . " in Axis). Other valid entries are "gedit", "gnome-terminal -e vim", and "gvim". • PYVCP = /filename.xml - The PyVCP panel description file. See the PyVCP section for more information. • LATHE = 1 - This displays in lathe mode with a top view and with Radius and Diameter on the DRO. • GEOMETRY = XYZABCUVW - Controls the preview and backplot of rotary motion. This item consists of a sequence of axis letters, optionally preceded by a "-" sign. Only axes defined in [TRAJ]AXES should be used. This sequence specifies the order in which the effect of each axis is applied, with a "-" inverting the sense of the rotation. The proper GEOMETRY string depends on the machine configuration and the kinematics used to control it. The example string GEOMETRY=XYZBCUVW is for a 5-axis machine where kinematics causes UVW to move in the coordinate system of the tool and XYZ to move in the coordinate system of the material. The order of the letters is important, because it expresses the order in which the different transformations are applied. For example rotating around C then B is different than rotating around B then C. Geometry has no effect without a rotary axis. • ARCDIVISION = 64 - Set the quality of preview of arcs. Arcs are previewed by dividing them into a number of straight lines; a semicircle is divided into ARCDIVISION parts. Larger values give a more accurate preview, but take longer to load and result in a more sluggish display. Smaller values give a less accurate preview, but take less time to load and may result in a faster display. The default value of 64 means a circle of up to 3 inches will be displayed to within 1 mil (.03%).1 • MDI_HISTORY_FILE = - The name of a local MDI history file. If this is not specified Axis will save the MDI history in .axis_mdi_history in the user’s home directory. This is useful if you have multiple configurations on one computer. Note The following [DISPLAY] item is used by the TKLinuxCNC interface only. • HELP_FILE = tklinucnc.txt - Path to help file. 1 In LinuxCNC 2.4 and earlier, the default value was 128. Integrator Manual V2.5, 2016-05-12 3.2.3 15 / 258 [FILTER] Section AXIS has the ability to send loaded files through a filter program. This filter can do any desired task: Something as simple as making sure the file ends with M2, or something as complicated as detecting whether the input is a depth image, and generating g-code to mill the shape it defines. The [FILTER] section of the ini file controls how filters work. First, for each type of file, write a PROGRAM_EXTENSION line. Then, specify the program to execute for each type of file. This program is given the name of the input file as its first argument, and must write RS274NGC code to standard output. This output is what will be displayed in the text area, previewed in the display area, and executed by LinuxCNC when Run. • PROGRAM_EXTENSION = .extension Description If your post processor outputs files in all caps you might want to add the following line: • PROGRAM_EXTENSION = .NGC XYZ Post Processor The following lines add support for the image-to-gcode converter included with LinuxCNC: • PROGRAM_EXTENSION = .png,.gif,.jpg Greyscale Depth Image – png = image-to-gcode – gif = image-to-gcode – jpg = image-to-gcode It is also possible to specify an interpreter: • PROGRAM_EXTENSION = .py Python Script – py = python In this way, any Python script can be opened, and its output is treated as g-code. One such example script is available at nc_files/holecircle.py. This script creates g-code for drilling a series of holes along the circumference of a circle. Many more g-code generators are on the LinuxCNC Wiki site http://wiki.linuxcnc.org/. If the environment variable AXIS_PROGRESS_BAR is set, then lines written to stderr of the form • FILTER_PROGRESS=%d sets the AXIS progress bar to the given percentage. This feature should be used by any filter that runs for a long time. Python filters should use the print function to output the result to Axis. This example program filters a file and adds a W axis to match the Z axis. It depends on there being a space between each axis word to work. #! /usr/bin/env python import sys def main(argv): openfile = open(argv[0], ’r’) file_in = openfile.readlines() openfile.close() file_out = [] for line in file_in: # print line if line.find(’Z’) != -1: words = line.rstrip(’\n’) Integrator Manual V2.5, 2016-05-12 16 / 258 words = words.split(’ ’) newword = ’’ for i in words: if i[0] == ’Z’: newword = ’W’+ i[1:] if len(newword) > 0: words.append(newword) newline = ’ ’.join(words) file_out.append(newline) else: file_out.append(line) for item in file_out: print "%s" % item if __name__ == "__main__": main(sys.argv[1:]) 3.2.4 [RS274NGC] Section • PARAMETER_FILE = myfile.var - The file located in the same directory as the ini file which contains the parameters used by the interpreter (saved between runs). • RS274NGC_STARTUP_CODE = G17 G20 G40 G49 G64 P0.001 G80 G90 G92 G94 G97 G98 - A string of NC codes that the interpreter is initialized with. This is not a substitute for specifying modal g-codes at the top of each ngc file, because the modal codes of machines differ, and may be changed by g-code interpreted earlier in the session. • SUBROUTINE_PATH = ncsubroutines:/tmp/testsubs:lathesubs:millsubs - Specifies a colon (:) separated list of up to 10 directories to be searched when single-file subroutines are specified in gcode. These directories are searched after searching [DISPLAY]PROGRAM_PREFIX (if it is specified) and before searching [WIZARD]WIZARD_ROOT (if specified). The paths are searched in the order that they are listed. The first matching subroutine file found in the search is used. Directories are specified relative to the current directory for the ini file or as absolute paths. The list must contain no intervening whitespace. • USER_M_PATH = myfuncs:/tmp/mcodes:experimentalmcodes - Specifies a list of colon (:) separated directories for user defined functions. Directories are specified relative to the current directory for the ini file or as absolute paths. The list must contain no intervening whitespace. A search is made for each possible user defined function, typically (M100-M199). The search order is: 1. [DISPLAY]PROGRAM_PREFIX (if specified) 2. If [DISPLAY]PROGRAM_PREFIX is not specified, search the default location: nc_files 3. Then search each directory in the list [RS274NGC]USER_M_PATH The first executable M1xx found in the search is used for each M1xx. • USER_DEFINED_FUNCTION_MAX_DIRS=5. The maximum number of directories defined at compile time. Note [WIZARD]WIZARD_ROOT is a valid search path but the Wizard has not been fully implemented and the results of using it are unpredictable. 3.2.5 [EMCMOT] Section This section is a custom section and is not used by LinuxCNC directly. Most configurations use values from this section to load the motion controller. For more information on the motion controller see the Motion Section. • EMCMOT = motmod - the motion controller name is typically used here. Integrator Manual V2.5, 2016-05-12 17 / 258 • BASE_PERIOD = 50000 - the Base task period in nanoseconds. • SERVO_PERIOD = 1000000 - This is the "Servo" task period in nanoseconds. • TRAJ_PERIOD = 100000 - This is the Trajectory Planner task period in nanoseconds. 3.2.6 [TASK] Section • TASK = milltask - Specifies the name of the task executable. The task executable does various things, such as communicate with the UIs over NML, communicate with the realtime motion planner over non-HAL shared memory, and interpret gcode. Currently there is only one task executable that makes sense for 99.9% of users, milltask. • CYCLE_TIME = 0.010 - The period, in seconds, at which TASK will run. This parameter affects the polling interval when waiting for motion to complete, when executing a pause instruction, and when accepting a command from a user interface. There is usually no need to change this number. 3.2.7 [HAL] section • TWOPASS=ON - Use two pass processing for loading HAL comps. With TWOPASS processing, all [HAL]HALFILES are first read and multiple appearances of loadrt directives for each moduleb are accumulated. No hal commands are executed in this initial pass. • HALFILE = example.hal - Execute the file example.hal at start up. If HALFILE is specified multiple times, the files are executed in the order they appear in the ini file. Almost all configurations will have at least one HALFILE, and stepper systems typically have two such files, one which specifies the generic stepper configuration (core_stepper.hal) and one which specifies the machine pin out (xxx_pinout.hal) • HALCMD = command - Execute command as a single HAL command. If HALCMD is specified multiple times, the commands are executed in the order they appear in the ini file. HALCMD lines are executed after all HALFILE lines. • SHUTDOWN = shutdown.hal - Execute the file shutdown.hal when LinuxCNC is exiting. Depending on the hardware drivers used, this may make it possible to set outputs to defined values when LinuxCNC is exited normally. However, because there is no guarantee this file will be executed (for instance, in the case of a computer crash) it is not a replacement for a proper physical e-stop chain or other protections against software failure. • POSTGUI_HALFILE = example2.hal - (Only with the TOUCHY and AXIS GUI) Execute example2.hal after the GUI has created its HAL pins. See section pyVCP with Axis Section for more information. • HALUI = halui - adds the HAL user interface pins. For more information see the HAL User Interface chapter. 3.2.8 [HALUI] section • MDI_COMMAND = G53 G0 X0 Y0 Z0 - An MDI command can be executed by using halui.mdi-command-00. Increment the number for each command listed in the [HALUI] section. 3.2.9 [TRAJ] Section The [TRAJ] section contains general parameters for the trajectory planning module in motion. • COORDINATES = X Y Z - The names of the axes being controlled. Only X, Y, Z, A, B, C, U, V, W are valid. Only axes named in COORDINATES are accepted in g-code. This has no effect on the mapping from G-code axis names (X- Y- Z-) to joint numbers—for trivial kinematics, X is always joint 0, A is always joint 3, and U is always joint 6, and so on. It is permitted to write an axis name twice (e.g., X Y Y Z for a gantry machine) but this has no effect. • AXES = 3 - One more than the number of the highest joint number in the system. For an XYZ machine, the joints are numbered 0, 1 and 2; in this case AXES should be 3. For an XYUV machine using trivial kinematics, the V joint is numbered 7 and therefore AXES should be 8. For a machine with nontrivial kinematics (e.g., scarakins) this will generally be the number of controlled joints. Integrator Manual V2.5, 2016-05-12 18 / 258 • JOINTS = 3 - (This config variable is used by the Axis GUI only, not by the trajectory planner in the motion controller.) Specifies the number of joints (motors) in the system. For example, an XYZ machine with a single motor for each axis has 3 joints. A gantry machine with one motor on each of two of the axes, and two motors on the third axis, has 4 joints. • HOME = 0 0 0 - Coordinates of the homed position of each axis. Again for a fourth axis you will need 0 0 0 0. This value is only used for machines with nontrivial kinematics. On machines with trivial kinematics this value is ignored. • LINEAR_UNITS = - Specifies the machine units for linear axes. Possible choices are (in, inch, imperial, metric, mm). This does not affect the linear units in NC code (the G20 and G21 words do this). • ANGULAR_UNITS = - Specifies the machine units for rotational axes. Possible choices are deg, degree (360 per circle), rad, radian (2pi per circle), grad, or gon (400 per circle). This does not affect the angular units of NC code. In RS274NGC, A-, B- and C- words are always expressed in degrees. • DEFAULT_VELOCITY = 0.0167 - The initial rate for jogs of linear axes, in machine units per second. The value shown in Axis equals machine units per minute. • DEFAULT_ACCELERATION = 2.0 - In machines with nontrivial kinematics, the acceleration used for "teleop" (Cartesian space) jogs, in machine units per second per second. • MAX_VELOCITY = 5.0 - The maximum velocity for any axis or coordinated move, in machine units per second. The value shown equals 300 units per minute. • MAX_ACCELERATION = 20.0 - The maximum acceleration for any axis or coordinated axis move, in machine units per second per second. • POSITION_FILE = position.txt - If set to a non-empty value, the joint positions are stored between runs in this file. This allows the machine to start with the same coordinates it had on shutdown. This assumes there was no movement of the machine while powered off. If unset, joint positions are not stored and will begin at 0 each time LinuxCNC is started. This can help on smaller machines without home switches. • NO_FORCE_HOMING = 1 - The default behavior is for LinuxCNC to force the user to home the machine before any MDI command or a program is run. Normally, only jogging is allowed before homing. Setting NO_FORCE_HOMING = 1 allows the user to make MDI moves and run programs without homing the machine first. Interfaces without homing ability will need to have this option set to 1. Warning Using this will allow the machine to go beyond the soft limits while in operation. It is not generally desirable to allow this. 3.2.10 [AXIS_ ] Section The [AXIS_0], [AXIS_1], etc. sections contains general parameters for the individual components in the axis control module. The axis section names begin numbering at 0, and run through the number of axes specified in the [TRAJ] AXES entry minus 1. Typically (but not always): • AXIS_0 = X • AXIS_1 = Y • AXIS_2 = Z • AXIS_3 = A • AXIS_4 = B • AXIS_5 = C Integrator Manual V2.5, 2016-05-12 19 / 258 • AXIS_6 = U • AXIS_7 = V • AXIS_8 = W • TYPE = LINEAR - The type of axes, either LINEAR or ANGULAR. • WRAPPED_ROTARY = 1 - When this is set to 1 for an ANGULAR axis the axis will move 0-359.999 degrees. Positive Numbers will move the axis in a positive direction and negative numbers will move the axis in the negative direction. • LOCKING_INDEXER = 1 - When this is set to 1 a G0 move for this axis will initiate an unlock with axis.N.unlock pin then wait for the axis.N.is-unlocked pin then move the axis at the rapid rate for that axis. After the move the axis.N.unlock will be false and motion will wait for axis.N.is-unlocked to go false. Moving with other axes is not allowed when moving a locked rotary axis. • UNITS = INCH - If specified, this setting overrides the related [TRAJ] UNITS setting. (e.g., [TRAJ]LINEAR_UNITS if the TYPE of this axis is LINEAR, [TRAJ]ANGULAR_UNITS if the TYPE of this axis is ANGULAR) • MAX_VELOCITY = 1.2 - Maximum velocity for this axis in machine units per second. • MAX_ACCELERATION = 20.0 - Maximum acceleration for this axis in machine units per second squared. • BACKLASH = 0.0000 - Backlash in machine units. Backlash compensation value can be used to make up for small deficiencies in the hardware used to drive an axis. If backlash is added to an axis and you are using steppers the STEPGEN_MAXACCEL must be increased to 1.5 to 2 times the MAX_ACCELERATION for the axis. • COMP_FILE = file.extension - A file holding compensation structure for the axis. The file could be named xscrew.comp, for example, for the X axis. File names are case sensitive and can contain letters and/or numbers. The values are triplets per line separated by a space. The first value is nominal (where it should be). The second and third values depend on the setting of COMP_FILE_TYPE. Currently the limit inside LinuxCNC is for 256 triplets per axis. If COMP_FILE is specified, BACKLASH is ignored. Compensation file values are in machine units. • COMP_FILE_TYPE = 0 or 1 – If 0: The second and third values specify the forward position (where the axis is while traveling forward) and the reverse position (where the axis is while traveling reverse), positions which correspond to the nominal position.’ – If 1: The second and third values specify the forward trim (how far from nominal while traveling forward) and the reverse trim (how far from nominal while traveling in reverse), positions which correspond to the nominal position. Example triplet with COMP_FILE_TYPE = 0: 1.00 1.01 0.99 + Example triplet with COMP_FILE_TYPE = 1: 1.00 0.01 -0.01 • MIN_LIMIT = -1000 - The minimum limit (soft limit) for axis motion, in machine units. When this limit is exceeded, the controller aborts axis motion. • MAX_LIMIT = 1000 - The maximum limit (soft limit) for axis motion, in machine units. When this limit is exceeded, the controller aborts axis motion. • MIN_FERROR = 0.010 - This is the value in machine units by which the axis is permitted to deviate from commanded position at very low speeds. If MIN_FERROR is smaller than FERROR, the two produce a ramp of error trip points. You could think of this as a graph where one dimension is speed and the other is permitted following error. As speed increases the amount of following error also increases toward the FERROR value. • FERROR = 1.0 - FERROR is the maximum allowable following error, in machine units. If the difference between commanded and sensed position exceeds this amount, the controller disables servo calculations, sets all the outputs to 0.0, and disables the amplifiers. If MIN_FERROR is present in the .ini file, velocity-proportional following errors are used. Here, the maximum allowable following error is proportional to the speed, with FERROR applying to the rapid rate set by [TRAJ]MAX_VELOCITY, and proportionally smaller following errors for slower speeds. The maximum allowable following error will always be greater than MIN_FERROR. This prevents small following errors for stationary axes from inadvertently aborting motion. Small following errors will always be present due to vibration, etc. The following polarity values determine how inputs are interpreted Integrator Manual V2.5, 2016-05-12 20 / 258 and how outputs are applied. They can usually be set via trial-and-error since there are only two possibilities. The LinuxCNC Servo Axis Calibration utility program (in the AXIS interface menu Machine/Calibration and in TkLinuxCNC it is under Setting/Calibration) can be used to set these and more interactively and verify their results so that the proper values can be put in the INI file with a minimum of trouble. 3.2.10.1 Homing These parameters are Homing related, for a better explanation read the Homing Configuration Chapter. • HOME = 0.0 - The position that the joint will go to upon completion of the homing sequence. • HOME_OFFSET = 0.0 - The axis position of the home switch or index pulse, in machine units. When the home point is found during the homing process, this is the position that is assigned to that point. When sharing home and limit switches and using a home sequence that will leave the home/limit switch in the toggled state the home offset can be used define the home switch position to be other than 0 if your HOME position is desired to be 0. • HOME_SEARCH_VEL = 0.0 - Initial homing velocity in machine units per second. Sign denotes direction of travel. A value of zero means assume that the current location is the home position for the machine. If your machine has no home switches you will want to leave this value at zero. • HOME_LATCH_VEL = 0.0 - Homing velocity in machine units per second to the home switch latch position. Sign denotes direction of travel. • HOME_FINAL_VEL = 0.0 - Velocity in machine units per second from home latch position to home position. If left at 0 or not included in the axis rapid velocity is used. Must be a positive number. • HOME_USE_INDEX = NO - If the encoder used for this axis has an index pulse, and the motion card has provision for this signal you may set it to yes. When it is yes, it will affect the kind of home pattern used. Currently, you can’t home to index with steppers unless you’re using stepgen in velocity mode and PID. • HOME_IGNORE_LIMITS = NO - When you use the limit switch as a home switch and the limit switch this should be set to YES. When set to YES the limit switch for this axis is ignored when homing. You must configure your homing so that at the end of your home move the home/limit switch is not in the toggled state you will get a limit switch error after the home move. • HOME_IS_SHARED = - If the home input is shared by more than one axis set to 1 to prevent homing from starting if the one of the shared switches is already closed. Set to 0 to permit homing if a switch is closed. • HOME_SEQUENCE = - Used to define the "Home All" sequence. starts at 0 and no numbers may be skipped. If left out or set to -1 the joint will not be homed by the "Home All" function. More than one axis can be homed at the same time. • VOLATILE_HOME = 0 - When enabled (set to 1) this joint will be unhomed if the Machine Power is off or if E-Stop is on. This is useful if your machine has home switches and does not have position feedback such as a step and direction driven machine. 3.2.10.2 Servo These parameters are relevant to axes controlled by servos. Warning The following are custom INI file entries that you may find in a sample INI file or a wizard generated file. These are not used by the LinuxCNC software. They are only there to put all the settings in one place. For more information on custom INI file entries see the Custom Sections and Variables subsection. The following items might be used by a PID component and the assumption is that the output is volts. Integrator Manual V2.5, 2016-05-12 21 / 258 • DEADBAND = 0.000015 - How close is close enough to consider the motor in position, in machine units. This is often set to a distance equivalent to 1, 1.5, 2, or 3 encoder counts, but there are no strict rules. Looser (larger) settings allow less servo hunting at the expense of lower accuracy. Tighter (smaller) settings attempt higher accuracy at the expense of more servo hunting. Is it really more accurate if it’s also more uncertain? As a general rule, it’s good to avoid, or at least limit, servo hunting if you can. Be careful about going below 1 encoder count, since you may create a condition where there is no place that your servo is happy. This can go beyond hunting (slow) to nervous (rapid), and even to squealing which is easy to confuse with oscillation caused by improper tuning. Better to be a count or two loose here at first, until you’ve been through gross tuning at least. Example of calculating machine units per encoder pulse to use in deciding DEADBAND value: • BIAS = 0.000 - This is used by hm2-servo and some others. Bias is a constant amount that is added to the output. In most cases it should be left at zero. However, it can sometimes be useful to compensate for offsets in servo amplifiers, or to balance the weight of an object that moves vertically. bias is turned off when the PID loop is disabled, just like all other components of the output. • P = 50 - The proportional gain for the axis servo. This value multiplies the error between commanded and actual position in machine units, resulting in a contribution to the computed voltage for the motor amplifier. The units on the P gain are volts per machine unit, e.g., • I = 0 - The integral gain for the axis servo. The value multiplies the cumulative error between commanded and actual position in machine units, resulting in a contribution to the computed voltage for the motor amplifier. The units on the I gain are volts per machine unit second, e.g., • D = 0 - The derivative gain for the axis servo. The value multiplies the difference between the current and previous errors, resulting in a contribution to the computed voltage for the motor amplifier. The units on the D gain are volts per machine unit per second, e.g., • FF0 = 0 - The 0th order feed forward gain. This number is multiplied by the commanded position, resulting in a contribution to the computed voltage for the motor amplifier. The units on the FF0 gain are volts per machine unit, e.g., • FF1 = 0 - The 1st order feed forward gain. This number is multiplied by the change in commanded position per second, resulting in a contribution to the computed voltage for the motor amplifier. The units on the FF1 gain are volts per machine unit per second, e.g., • FF2 = 0 - The 2nd order feed forward gain. This number is multiplied by the change in commanded position per second per second, resulting in a contribution to the computed voltage for the motor amplifier. The units on the FF2 gain are volts per machine unit per second per second, e.g., • OUTPUT_SCALE = 1.000 - Integrator Manual V2.5, 2016-05-12 22 / 258 • OUTPUT_OFFSET = 0.000 - These two values are the scale and offset factors for the axis output to the motor amplifiers. The second value (offset) is subtracted from the computed output (in volts), and divided by the first value (scale factor), before being written to the D/A converters. The units on the scale value are in true volts per DAC output volts. The units on the offset value are in volts. These can be used to linearize a DAC. Specifically, when writing outputs, the LinuxCNC first converts the desired output in quasi-SI units to raw actuator values, e.g., volts for an amplifier DAC. This scaling looks like: The value for scale can be obtained analytically by doing a unit analysis, i.e., units are [output SI units]/[actuator units]. For example, on a machine with a velocity mode amplifier such that 1 volt results in 250 mm/sec velocity. Note that the units of the offset are in machine units, e.g., mm/sec, and they are pre-subtracted from the sensor readings. The value for this offset is obtained by finding the value of your output which yields 0.0 for the actuator output. If the DAC is linearized, this offset is normally 0.0. The scale and offset can be used to linearize the DAC as well, resulting in values that reflect the combined effects of amplifier gain, DAC non-linearity, DAC units, etc. To do this, follow this procedure. 1. Build a calibration table for the output, driving the DAC with a desired voltage and measuring the result. 2. Do a least-squares linear fit to get coefficients a, b such that 3. Note that we want raw output such that our measured result is identical to the commanded output. This means a. b. 4. As a result, the a and b coefficients from the linear fit can be used as the scale and offset for the controller directly. See the following table for an example of voltage measurements. Table 3.1: Output Voltage Measurements Raw -10 -9 0 1 9 10 Measured -9.93 -8.83 -0.03 0.96 9.87 10.87 • MAX_OUTPUT = 10 - The maximum value for the output of the PID compensation that is written to the motor amplifier, in volts. The computed output value is clamped to this limit. The limit is applied before scaling to raw output units. The value is applied symmetrically to both the plus and the minus side. • INPUT_SCALE = 20000 - in Sample configs • ENCODER_SCALE = 20000 - in PNCconf built configs Specifies the number of pulses that corresponds to a move of one machine unit as set in the [TRAJ] section. For a linear axis one machine unit will be equal to the setting of LINEAR_UNITS. Integrator Manual V2.5, 2016-05-12 23 / 258 For an angular axis one unit is equal to the setting in ANGULAR_UNITS. A second number, if specified, is ignored. For example, on a 2000 counts per rev encoder, and 10 revs/inch gearing, and desired units of inch, we have: 3.2.10.3 Stepper These parameters are relevant to axes controlled by steppers. Warning The following are custom INI file entries that you may find in a sample INI file or a wizard generated file. These are not used by the LinuxCNC software. They are only there to put all the settings in one place. For more information on custom INI file entries see the Custom Sections and Variables subsection. The following items might be used by a stepgen component. • SCALE = 4000 - in Sample configs • STEP_SCALE = 4000 - in PNCconf built configs Specifies the number of pulses that corresponds to a move of one machine unit as set in the [TRAJ] section. For stepper systems, this is the number of step pulses issued per machine unit. For a linear axis one machine unit will be equal to the setting of LINEAR_UNITS. For an angular axis one unit is equal to the setting in ANGULAR_UNITS. For servo systems, this is the number of feedback pulses per machine unit. A second number, if specified, is ignored. For example, on a 1.8 degree stepper motor with half-stepping, and 10 revs/inch gearing, and desired machine units of inch, we have: • ENCODER_SCALE = 20000 (Optionally used in PNCconf built configs) - Specifies the number of pulses that corresponds to a move of one machine unit as set in the [TRAJ] section. For a linear axis one machine unit will be equal to the setting of LINEAR_UNITS. For an angular axis one unit is equal to the setting in ANGULAR_UNITS. A second number, if specified, is ignored. For example, on a 2000 counts per rev encoder, and 10 revs/inch gearing, and desired units of inch, we have: • STEPGEN_MAXACCEL = 21.0 - Acceleration limit for the step generator. This should be 1% to 10% larger than the axis MAX_ACCELERATION. This value improves the tuning of stepgen’s "position loop". If you have added backlash compensation to an axis then this should be 1.5 to 2 times greater than MAX_ACCELERATION. • STEPGEN_MAXVEL = 1.4 - Older configuration files have a velocity limit for the step generator as well. If specified, it should also be 1% to 10% larger than the axis MAX_VELOCITY. Subsequent testing has shown that use of STEPGEN_MAXVEL does not improve the tuning of stepgen’s position loop. 3.2.11 [EMCIO] Section • EMCIO = io - Name of IO controller program • CYCLE_TIME = 0.100 - The period, in seconds, at which EMCIO will run. Making it 0.0 or a negative number will tell EMCIO not to sleep at all. There is usually no need to change this number. Integrator Manual V2.5, 2016-05-12 24 / 258 • TOOL_TABLE = tool.tbl - The file which contains tool information, described in the User Manual. • TOOL_CHANGE_POSITION = 0 0 2 - Specifies the XYZ location to move to when performing a tool change if three digits are used. Specifies the XYZABC location when 6 digits are used. Specifies the XYZABCUVW location when 9 digits are used. Tool Changes can be combined. For example if you combine the quill up with change position you can move the Z first then the X and Y. • TOOL_CHANGE_WITH_SPINDLE_ON = 1 - The spindle will be left on during the tool change when the value is 1. Useful for lathes or machines where the material is in the spindle, not the tool. • TOOL_CHANGE_QUILL_UP = 1 - The Z axis will be moved to machine zero prior to the tool change when the value is 1. This is the same as issuing a G0 G53 Z0. • TOOL_CHANGE_AT_G30 = 1 - The machine is moved to reference point defined by parameters 5181-5186 for G30 if the value is 1. For more information on G30 and Parameters see the G Code Manual. • RANDOM_TOOLCHANGER = 1 - This is for machines that cannot place the tool back into the pocket it came from. For example, machines that exchange the tool in the active pocket with the tool in the spindle. Integrator Manual V2.5, 2016-05-12 25 / 258 Chapter 4 Homing Configuration 4.1 Overview Homing seems simple enough - just move each joint to a known location, and set LinuxCNC’s internal variables accordingly. However, different machines have different requirements, and homing is actually quite complicated. 4.2 Homing Sequence There are four possible homing sequences defined by the sign of SEARCH_VEL and LATCH_VEL, along with the associated configuration parameters as shown in the following table. Two basic conditions exist, SEARCH_VEL and LATCH_VEL are the same sign or they are opposite signs. For a more detailed description of what each configuration parameter does, see the following section. Integrator Manual V2.5, 2016-05-12 26 / 258 Figure 4.1: Homing Sequences Integrator Manual V2.5, 2016-05-12 4.3 27 / 258 Configuration The following determines exactly how the home sequence behaves. They are defined in an [AXIS] section of the inifile. Homing Type Immediate Index-only Switch-only Switch and Index SEARCH_VEL 0 0 nonzero nonzero LATCH_VEL 0 nonzero nonzero nonzero USE_INDEX NO YES NO YES Note Any other combinations may result in an error. 4.3.1 HOME_SEARCH_VEL The default value is zero. A value of zero causes LinuxCNC to assume that there is no home switch; the search stage of homing is skipped. If HOME_SEARCH_VEL is non-zero, then LinuxCNC assumes that there is a home switch. It begins by checking whether the home switch is already tripped. If tripped it backs off the switch at HOME_SEARCH_VEL. The direction of the back-off is opposite the sign of HOME_SEARCH_VEL. Then it searches for the home switch by moving in the direction specified by the sign of HOME_SEARCH_VEL, at a speed determined by its absolute value. When the home switch is detected, the joint will stop as fast as possible, but there will always be some overshoot. The amount of overshoot depends on the speed. If it is too high, the joint might overshoot enough to hit a limit switch or crash into the end of travel. On the other hand, if HOME_SEARCH_VEL is too low, homing can take a long time. 4.3.2 HOME_LATCH_VEL Specifies the speed and direction that LinuxCNC uses when it makes its final accurate determination of the home switch (if present) and index pulse location (if present). It will usually be slower than the search velocity to maximize accuracy. If HOME_SEARCH_VEL and HOME_LATCH_VEL have the same sign, then the latch phase is done while moving in the same direction as the search phase. (In that case, LinuxCNC first backs off the switch, before moving towards it again at the latch velocity.) If HOME_SEARCH_VEL and HOME_LATCH_VEL have opposite signs, the latch phase is done while moving in the opposite direction from the search phase. That means LinuxCNC will latch the first pulse after it moves off the switch. If HOME_SEARCH_VEL is zero (meaning there is no home switch), and this parameter is nonzero, LinuxCNC goes ahead to the index pulse search. If HOME_SEARCH_VEL is non-zero and this parameter is zero, it is an error and the homing operation will fail. The default value is zero. 4.3.3 HOME_FINAL_VEL It specifies the speed that LinuxCNC uses when it makes its move from HOME_OFFSET to the HOME position. If the HOME_FINAL_VEL is missing from the ini file, then the maximum joint speed is used to make this move. The value must be a positive number. 4.3.4 HOME_IGNORE_LIMITS Can hold the values YES / NO. The default value for this parameter is NO. This flag determines whether LinuxCNC will ignore the limit switch input for this axis while homing. Setting this to YES will not ignore limit inputs for other axes. If you do not have a separate home switch set this to YES and case connect the limit switch signal to the home switch input in HAL. LinuxCNC will ignore the limit switch input for this axis while homing. To use only one input for all homing and limits you will have to block the limit signals of the axes not homing in HAL and home one axis at a time. Integrator Manual V2.5, 2016-05-12 4.3.5 28 / 258 HOME_USE_INDEX Specifies whether or not there is an index pulse. If the flag is true (HOME_USE_INDEX = YES), LinuxCNC will latch on the rising edge of the index pulse. If false, LinuxCNC will latch on either the rising or falling edge of the home switch (depending on the signs of HOME_SEARCH_VEL and HOME_LATCH_VEL). The default value is NO. 4.3.6 HOME_OFFSET Contains the location of the home switch or index pulse, in joint coordinates. It can also be treated as the distance between the point where the switch or index pulse is latched and the zero point of the joint. After detecting the index pulse, LinuxCNC sets the joint coordinate of the current point to HOME_OFFSET. The default value is zero. 4.3.7 HOME The position that the joint will go to upon completion of the homing sequence. After detecting the index pulse, and setting the coordinate of that point to HOME_OFFSET, LinuxCNC makes a move to HOME as the final step of the homing process. The default value is zero. Note that even if this parameter is the same as HOME_OFFSET, the joint will slightly overshoot the latched position as it stops. Therefore there will always be a small move at this time (unless HOME_SEARCH_VEL is zero, and the entire search/latch stage was skipped). This final move will be made at the joint’s maximum velocity. Since the joint is now homed, there should be no risk of crashing the machine, and a rapid move is the quickest way to finish the homing sequence. 1 4.3.8 HOME_IS_SHARED If there is not a separate home switch input for this axis, but a number of momentary switches wired to the same pin, set this value to 1 to prevent homing from starting if one of the shared switches is already closed. Set this value to 0 to permit homing even if the switch is already closed. 4.3.9 HOME_SEQUENCE Used to define a multi-axis homing sequence HOME ALL and enforce homing order (e.g., Z may not be homed if X is not yet homed). An axis may be homed after all axes with a lower HOME_SEQUENCE have already been homed and are at the HOME_OFFSET. If two axes have the same HOME_SEQUENCE, they may be homed at the same time. If HOME_SEQUENCE is -1 or not specified then this joint will not be homed by the HOME ALL sequence. HOME_SEQUENCE numbers start with 0 and there may be no unused numbers. 4.3.10 VOLATILE_HOME If this setting is true, this axis becomes unhomed whenever the machine transitions into the OFF state. This is appropriate for any axis that does not maintain position when the axis drive is off. Some stepper drives, especially microstep drives, may need this. 4.3.11 LOCKING_INDEXER If this axis is a locking rotary indexer, it will unlock before homing, and lock afterward. 1 The distinction between home_offset and home is that home_offset first establishes the scale location on the machine by applying the home_offset value to the location where home was found, and then home says where the joint should move to on that scale. Integrator Manual V2.5, 2016-05-12 4.3.12 29 / 258 Immediate Homing If an axis does not have home switches or does not have a logical home position like a rotary axis and you want that axis to home at the current position when the "Home All" button is pressed in Axis the following ini entries for that axis are needed. 1. SEARCH_VEL = 0 2. LATCH_VEL = 0 3. USE_INDEX = NO 4. HOME_SEQUENCE = 0 Integrator Manual V2.5, 2016-05-12 30 / 258 Chapter 5 Lathe Configuration 5.1 Default Plane When LinuxCNC’s interpreter was first written, it was designed for mills. That is why the default plane is XY (G17). A normal lathe only uses the XZ plane (G18). To change the default plane place the following line in the .ini file in the RS274NGC section. RS274NGC_STARTUP_CODE = G18 The above can be overwritten in a g code program so always set important things in the preamble of the g code file. 5.2 INI Settings The following .ini settings are needed for lathe mode in Axis in addition to or replacing normal settings in the .ini file. [DISPLAY] DISPLAY = axis LATHE = 1 [TRAJ] AXES = 3 COORDINATES = X Z [AXIS_0] ... [AXIS_2] ... Integrator Manual V2.5, 2016-05-12 31 / 258 Chapter 6 HAL TCL Files The halcmd language excels in specifiying components and connections but offers no computational capabilities. As a result, ini files are limited in the clarity and brevity that is possible with higher level languages. The haltcl facility provides a means to use tcl scripting and its features for computation, looping, branching, procedures, etc. in ini files. To use this functionality, you use the tcl language and the extension .tcl for halfiles. The .tcl extension is understood by the main script (linuxcnc) that processes ini files. Haltcl files are identified in the the HAL section of ini files (just like .hal files). Example [HAL] HALFILE = conventional_file.hal HALFILE = tcl_based_file.tcl With appropriate care, .hal and .tcl files can be intermixed. 6.1 Compatibility The halcmd language used in .hal files has a simple syntax that is actually a subset of the more powerful general-purpose tcl scripting language. 6.2 Haltcl Commands Haltcl files use the tcl scripting language augmented with the specific commands of the LinuxCNC hardware abstraction layer (HAL). The hal-specific commands are. addf, alias, delf, delsig, getp, gets ptype, stype, help, linkpp, linkps, linksp, list, loadrt, loadusr, lock, net, newsig, save, setp, sets, show, source, start, status, stop, unalias, unlinkp, unload, unloadrt, unloadusr, unlock, waitusr Integrator Manual V2.5, 2016-05-12 32 / 258 Two special cases occur for the gets and list commands due to conflicts with tcl builtin commands. For haltcl, these commands must be preceded with the keyword hal. halcmd -----gets list 6.3 haltcl -----hal gets hal list Haltcl Inifile variables Inifile variables are accessible by both halcmd and haltcl but with differing syntax. LinuxCNC ini files use SECTION and ITEM specifiers to identify configuration items. [SECTION_A] ITEM1 = value_1 ITEM2 = value_2 ... [SECTION_B] ... The ini file values are accessible by text substition in .hal files using the form. [SECTION]ITEM The same ini file values are accessible in .tcl files using the form of a tcl global array variable. $::SECTION(ITEM) For example, an ini file item like: [AXIS_0] MAX_VELOCITY = 4 is expressed as [AXIS_0]MAX_VELOCITY in .hal files for halcmd and as $::AXIS_0(MAX_VELOCITY) in .tcl files for haltcl 6.4 Converting .hal files to .tcl files Existing .hal files can be converted to .tcl files by hand editing to adapt to the differences mentioned above. The process can be automated with scripts that convert using these substitutions. [SECTION]ITEM ---> $::SECTION(ITEM) gets ---> hal gets list ---> hal list 6.5 Haltcl Notes In haltcl, the value argument for the sets and setp commands is implicitly treated as an expression in the tcl language. Example # set gain to convert deg/sec to units/min for AXIS_0 radius setp scale.0.gain 6.28/360.0*$::AXIS_0(radius)*60.0 Whitespace in the bare expression is not allowed, use quotes for that: Integrator Manual V2.5, 2016-05-12 33 / 258 setp scale.0.gain "6.28 / 360.0 * $::AXIS_0(radius) * 60.0" In other contexts, such as loadrt, you must explicitly use the tcl expr command ([expr {}]) for computational expressions. Example loadrt motion base_period=[expr {500000000/$::TRAJ(MAX_PULSE_RATE)}] 6.6 Haltcl Examples Consider the topic of stepgen headroom. Software stepgen runs best with an acceleration constraint that is "a bit higher" than the one used by the motion planner. So, when using halcmd files, we force inifiles to have a manually calculated value. [AXIS_0] MAXACCEL = 10.0 STEPGEN_MAXACCEL = 10.5 With haltcl, you can use tcl commands to do the computation and eliminate the STEPGEN_MAXACCEL inifile item altogether. setp stepgen.0.maxaccel $::AXIS_0(MAXACCEL)*1.05 Another haltcl feature is looping and testing. For example, many simulator configurations use "core_sim.hal" or "core_sim9.hal" hal files. These differ because of the requirement to connect more or fewer axes. The following haltcl code would work for any combination of axes in a trivkins machine. # Create position, velocity and acceleration signals for each axis set ddt 0 foreach axis {X Y Z A B C U V W} axno {0 1 2 3 4 5 6 7 8} { # ’list pin’ returns an empty list if the pin doesn’t exist if {[hal list pin axis.$axno.motor-pos-cmd] == {}} { continue } net ${axis}pos axis.$axno.motor-pos-cmd => axis.$axno.motor-pos-fb \ => ddt.$ddt.in net ${axis}vel <= ddt.$ddt.out incr ddt net ${axis}vel => ddt.$ddt.in net ${axis}acc <= ddt.$ddt.out incr ddt } puts [show sig *vel] puts [show sig *acc] 6.7 Haltcl Interactive The halrun command recognizes haltcl files. With the -T option, haltcl can be run interaactively as a tcl interpreter. This capability is useful for testing and for standalone hal applications. Example $ halrun -T haltclfile.tcl 6.8 Haltcl Distribution Examples (sim) The configs/sim/simtcl directory includes an ini file that uses a .tcl file to demonstrate a haltcl configuration in conjunction with the usage of twopass processing. The example shows the use of tcl procedures, looping, the use of comments, and output to the terminal. Integrator Manual V2.5, 2016-05-12 34 / 258 Chapter 7 Core Components See also the man pages motion(9). 7.1 Motion These pins and parameters are created by the realtime motmod module. This module provides a HAL interface for LinuxCNC’s motion planner. Basically motmod takes in a list of waypoints and generates a nice blended and constraint-limited stream of joint positions to be fed to the motor drives. Optionally the number of Digital I/O is set with num_dio. The number of Analog I/O is set with num_aio. The default is 4 each. Pin names starting with axis are actually joint values, but the pins and parameters are still called axis.N. They are read and updated by the motion-controller function. Motion is loaded with the motmod command. A kins should be loaded before motion. loadrt motmod [base_period_nsec=period] [servo_period_nsec=period] [traj_period_nsec=period] [num_joints=[0-9] ([num_dio=1-64] num_aio=1-16])] • base_period_nsec = 50000 - the Base task period in nanoseconds. This is the fastest thread in the machine. Note On servo-based systems, there is generally no reason for base_period_nsec to be smaller than servo_period_nsec. On machines with software step generation, the base_period_nsec determines the maximum number of steps per second. In the absence of long step length and step space requirements, the absolute maximum step rate is one step per base_period_nsec. Thus, the base_period_nsec shown above gives an absolute maximum step rate of 20,000 steps per second. 50,000 ns (50 us) is a fairly conservative value. The smallest usable value is related to the Latency Test result, the necessary step length, and the processor speed. Choosing a base_period_nsec that is too low can lead to the "Unexpected real time delay" message, lockups, or spontaneous reboots. • servo_period_nsec = 1000000 - This is the Servo task period in nanoseconds. This value will be rounded to an integer multiple of base_period_nsec. This period is used even on systems based on stepper motors. This is the rate at which new motor positions are computed, following error is checked, PID output values are updated, and so on. Most systems will not need to change this value. It is the update rate of the low level motion planner. • traj_period_nsec = 100000 - This is the Trajectory Planner task period in nanoseconds. This value will be rounded to an integer multiple of servo_period_nsec. Except for machines with unusual kinematics (e.g., hexapods) there is no reason to make this value larger than servo_period_nsec. Integrator Manual V2.5, 2016-05-12 7.1.1 35 / 258 Options If the number of digital I/O needed is more than the default of 4 you can add up to 64 digital I/O by using the num_dio option when loading motmod. If the number of analog I/O needed is more than the default of 4 you can add up to 16 analog I/O by using the num_aio option when loading motmod. 7.1.2 Pins These pins, parameters, and functions are created by the realtime motmod module. • motion.adaptive-feed - (float, in) When adaptive feed is enabled with M52 P1 , the commanded velocity is multiplied by this value. This effect is multiplicative with the NML-level feed override value and motion.feed-hold. • motion.analog-in-00 - (float, in) These pins (00, 01, 02, 03 or more if configured) are controlled by M66. • motion.analog-out-00 - (float, out) These pins (00, 01, 02, 03 or more if configured) are controlled by M67 or M68. • motion.coord-error - (bit, out) TRUE when motion has encountered an error, such as exceeding a soft limit • motion.coord-mode - (bit, out) TRUE when motion is in coordinated mode, as opposed to teleop mode • motion.current-vel - (float, out) The current tool velocity in user units per second. • motion.digital-in-00 - (bit, in) These pins (00, 01, 02, 03 or more if configured) are controlled by M62-65. • motion.digital-out-00 - (bit, out) These pins (00, 01, 02, 03 or more if configured) are controlled by the M62-65. • motion.distance-to-go - (float,out) The distance remaining in the current move. • motion.enable - (bit, in) If this bit is driven FALSE, motion stops, the machine is placed in the machine off state, and a message is displayed for the operator. For normal motion, drive this bit TRUE. • motion.feed-hold - (bit, in) When Feed Stop Control is enabled with M53 P1, and this bit is TRUE, the feed rate is set to 0. • motion.in-position - (bit, out) TRUE if the machine is in position. • motion.motion-enabled - (bit, out) TRUE when in machine on state. • motion.on-soft-limit - (bit, out) TRUE when the machine is on a soft limit. • motion.probe-input - (bit, in) G38.x uses the value on this pin to determine when the probe has made contact. TRUE for probe contact closed (touching), FALSE for probe contact open. • motion.program-line - (s32, out) The current program line while executing. Zero if not running or between lines while single stepping. • motion.requested-vel - (float, out) The current requested velocity in user units per second from the F=n setting in the G Code file. No feed overrides or any other adjustments are applied to this pin. • motion.spindle-at-speed - (bit, in) Motion will pause until this pin is TRUE, under the following conditions: before the first feed move after each spindle start or speed change; before the start of every chain of spindle-synchronized moves; and if in CSS mode, at every rapid to feed transition. This input can be used to ensure that the spindle is up to speed before starting a cut, or that a lathe spindle in CSS mode has slowed down after a large to small facing pass before starting the next pass at the large diameter. Many VFDs have an at speed output. Otherwise, it is easy to generate this signal with the HAL near component, by comparing requested and actual spindle speeds. • motion.spindle-brake - (bit, out) TRUE when the spindle brake should be applied. • motion.spindle-forward - (bit, out) TRUE when the spindle should rotate forward. • motion.spindle-index-enable - (bit, I/O) For correct operation of spindle synchronized moves, this pin must be hooked to the index-enable pin of the spindle encoder. Integrator Manual V2.5, 2016-05-12 36 / 258 • motion.spindle-on - (bit, out) TRUE when spindle should rotate. • motion.spindle-reverse - (bit, out) TRUE when the spindle should rotate backward • motion.spindle-revs - (float, in) For correct operation of spindle synchronized moves, this signal must be hooked to the position pin of the spindle encoder. The spindle encoder position should be scaled such that spindle-revs increases by 1.0 for each rotation of the spindle in the clockwise (M3) direction. • motion.spindle-speed-in - (float, in) Feedback of actual spindle speed in rotations per second. This is used by feed-perrevolution motion (G95). If your spindle encoder driver does not have a velocity output, you can generate a suitable one by sending the spindle position through a ddt component. If you do not have a spindle encoder, you can loop back motion.spindlespeed-out-rps. • motion.spindle-speed-out - (float, out) Commanded spindle speed in rotations per minute. Positive for spindle forward (M3), negative for spindle reverse (M4). • motion.spindle-speed-out-rps - (float, out) Commanded spindle speed in rotations per second. Positive for spindle forward (M3), negative for spindle reverse (M4). • motion.teleop-mode - (bit, out) TRUE when motion is in teleop mode, as opposed to coordinated mode • motion.tooloffset.x . . . motion.tooloffset.w - (float, out, one per axis) shows the tool offset in effect; it could come from the tool table (G43 active), or it could come from the gcode (G43.1 active) 7.1.3 Parameters Many of these parameters serve as debugging aids, and are subject to change or removal at any time. • motion-command-handler.time - (s32, RO) • motion-command-handler.tmax - (s32, RW) • motion-controller.time - (s32, RO) • motion-controller.tmax - (s32, RW) • motion.debug-bit-0 - (bit, RO) This is used for debugging purposes. • motion.debug-bit-1 - (bit, RO) This is used for debugging purposes. • motion.debug-float-0 - (float, RO) This is used for debugging purposes. • motion.debug-float-1 - (float, RO) This is used for debugging purposes. • motion.debug-float-2 - (float, RO) This is used for debugging purposes. • motion.debug-float-3 - (float, RO) This is used for debugging purposes. • motion.debug-s32-0 - (s32, RO) This is used for debugging purposes. • motion.debug-s32-1 - (s32, RO) This is used for debugging purposes. • motion.servo.last-period - (u32, RO) The number of CPU cycles between invocations of the servo thread. Typically, this number divided by the CPU speed gives the time in seconds, and can be used to determine whether the realtime motion controller is meeting its timing constraints • motion.servo.last-period-ns - (float, RO) • motion.servo.overruns - (u32, RW) By noting large differences between successive values of motion.servo.last-period , the motion controller can determine that there has probably been a failure to meet its timing constraints. Each time such a failure is detected, this value is incremented. Integrator Manual V2.5, 2016-05-12 7.1.4 37 / 258 Functions Generally, these functions are both added to the servo-thread in the order shown. • motion-command-handler - Processes motion commands coming from user space • motion-controller - Runs the LinuxCNC motion controller 7.2 Axis (Joints) These pins and parameters are created by the realtime motmod module. These are actually joint values, but the pins and parameters are still called axis.N.1 They are read and updated by the motion-controller function. 7.2.1 Pins • axis.N.active - (bit, out) • axis.N.amp-enable-out - (bit, out) TRUE if the amplifier for this joint should be enabled • axis.N.amp-fault-in - (bit, in) Should be driven TRUE if an external fault is detected with the amplifier for this joint • axis.N.backlash-corr - (float, out) • axis.N.backlash-filt - (float, out) • axis.N.backlash-vel - (float, out) • axis.N.coarse-pos-cmd - (float, out) • axis.N.error - (bit, out) • axis.N.f-error - (float, out) • axis.N.f-error-lim - (float, out) • axis.N.f-errored - (bit, out) • axis.N.faulted - (bit, out) • axis.N.free-pos-cmd - (float, out) • axis.N.free-tp-enable - (bit, out) • axis.N.free-vel-lim - (float, out) • axis.N.home-sw-in - (bit, in) Should be driven TRUE if the home switch for this joint is closed. • axis.N.homed - (bit, out) • axis.N.homing - (bit, out) TRUE if the joint is currently homing • axis.N.in-position - (bit, out) • axis.N.index-enable - (bit, I/O) • axis.N.jog-counts - (s32, in) Connect to the counts pin of an external encoder to use a physical jog wheel. • axis.N.jog-enable - (bit, in) When TRUE (and in manual mode), any change in jog-counts will result in motion. When false, jog-counts is ignored. • axis.N.jog-scale - (float, in) Sets the distance moved for each count on jog-counts, in machine units. 1 In trivial kinematics machines, there is a one-to-one correspondence between joints and axes. Integrator Manual V2.5, 2016-05-12 38 / 258 • axis.N.jog-vel-mode - (bit, in) When FALSE (the default), the jogwheel operates in position mode. The axis will move exactly jog-scale units for each count, regardless of how long that might take. When TRUE, the wheel operates in velocity mode motion stops when the wheel stops, even if that means the commanded motion is not completed. • axis.N.joint-pos-cmd - (float, out) The joint (as opposed to motor) commanded position. There may be an offset between the joint and motor positions—for example, the homing process sets this offset. • axis.N.joint-pos-fb - (float, out) The joint (as opposed to motor) feedback position. • axis.N.joint-vel-cmd - (float, out) • axis.N.kb-jog-active - (bit, out) • axis.N.motor-pos-cmd - (float, out) The commanded position for this joint. • axis.N.motor-pos-fb - (float, in) The actual position for this joint. • axis.N.neg-hard-limit - (bit, out) • axis.N.pos-lim-sw-in - (bit, in) Should be driven TRUE if the positive limit switch for this joint is closed. • axis.N.pos-hard-limit - (bit, out) • axis.N.neg-lim-sw-in - (bit, in) Should be driven TRUE if the negative limit switch for this joint is closed. • axis.N.wheel-jog-active - (bit, out) 7.2.2 Parameters • axis.N.home-state - Reflects the step of homing currently taking place. 7.3 iocontrol iocontrol - accepts NML I/O commands, interacts with HAL in userspace. The signals are turned on and off in userspace - if you have strict timing requirements or simply need more i/o, consider using the realtime synchronized i/o provided by motion instead. 7.3.1 Pins • iocontrol.0.coolant-flood - (bit, out) TRUE when flood coolant is requested. • iocontrol.0.coolant-mist - (bit, out) TRUE when mist coolant is requested. • iocontrol.0.emc-enable-in - (bit, in) Should be driven FALSE when an external E-Stop condition exists. • iocontrol.0.lube - (bit, out) TRUE when lube is commanded. • iocontrol.0.lube_level - (bit, in) Should be driven TRUE when lube level is high enough. • iocontrol.0.tool-change - (bit, out) TRUE when a tool change is requested. • iocontrol.0.tool-changed - (bit, in) Should be driven TRUE when a tool change is completed. • iocontrol.0.tool-number - (s32, out) The current tool number. • iocontrol.0.tool-prep-number - (s32, out) The number of the next tool, from the RS274NGC T-word. • iocontrol.0.tool-prepare - (bit, out) TRUE when a tool prepare is requested. • iocontrol.0.tool-prepared - (bit, in) Should be driven TRUE when a tool prepare is completed. • iocontrol.0.user-enable-out - (bit, out) FALSE when an internal E-Stop condition exists. • iocontrol.0.user-request-enable - (bit, out) TRUE when the user has requested that E-Stop be cleared. Integrator Manual V2.5, 2016-05-12 39 / 258 Chapter 8 Stepper Configuration 8.1 Introduction The preferred way to set up a standard stepper machine is with the Step Configuration Wizard. See the Getting Started Guide. This chapter describes some of the more common settings for manually setting up a stepper based system. Because of the various possibilities of configuring LinuxCNC, it is very hard to document them all, and keep this document relatively short. The most common LinuxCNC usage is for stepper based systems. These systems are using stepper motors with drives that accept step & direction signals. It is one of the simpler setups, because the motors run open-loop (no feedback comes back from the motors), yet the system needs to be configured properly so the motors don’t stall or lose steps. Most of this chapter is based on the sample config released along with LinuxCNC. The config is called stepper, and usually it is found in /etc/emc2/sample-configs/stepper. 8.2 Maximum step rate With software step generation, the maximum step rate is one step per two BASE_PERIODs for step-and-direction output. The maximum requested step rate is the product of an axis’ MAX_VELOCITY and its INPUT_SCALE. If the requested step rate is not attainable, following errors will occur, particularly during fast jogs and G0 moves. If your stepper driver can accept quadrature input, use this mode. With a quadrature signal, one step is possible for each BASE_PERIOD, doubling the maximum step rate. The other remedies are to decrease one or more of: the BASE_PERIOD (setting this too low will cause the machine to become unresponsive or even lock up), the INPUT_SCALE (if you can select different step sizes on your stepper driver, change pulley ratios, or leadscrew pitch), or the MAX_VELOCITY and STEPGEN_MAXVEL. If no valid combination of BASE_PERIOD, INPUT_SCALE, and MAX_VELOCITY is acceptable, then consider using hardware step generation (such as with the LinuxCNC-supported Universal Stepper Controller, Mesa cards, and others.) 8.3 Pinout One of the major flaws in LinuxCNC was that you couldn’t specify the pinout without recompiling the source code. LinuxCNC is far more flexible, and now (thanks to the Hardware Abstraction Layer) you can easily specify which signal goes where. See the HAL manual for more detailed information on HAL. As it is described in the HAL Introduction and tutorial, we have signals, pins and parameters inside the HAL. Integrator Manual V2.5, 2016-05-12 40 / 258 Note We are presenting one axis to keep it short, all others are similar. The ones relevant for our pinout are: signals: Xstep, Xdir & Xen pins: parport.0.pin-XX-out & parport.0.pin-XX-in Depending on what you have chosen in your .ini file you are using either standard_pinout.hal or xylotex_pinout.hal. These are two files that instruct the HAL how to link the various signals & pins. Further on we’ll investigate the standard_pinout.hal. 8.3.1 standard_pinout.hal This file contains several HAL commands, and usually looks like this: # standard pinout config file for 3-axis steppers # using a parport for I/O # # first load the parport driver loadrt hal_parport cfg="0x0378" # # next connect the parport functions to threads # read inputs first addf parport.0.read base-thread 1 # write outputs last addf parport.0.write base-thread -1 # # finally connect physical pins to the signals net Xstep => parport.0.pin-03-out net Xdir => parport.0.pin-02-out net Ystep => parport.0.pin-05-out net Ydir => parport.0.pin-04-out net Zstep => parport.0.pin-07-out net Zdir => parport.0.pin-06-out # create a signal for the estop loopback net estop-loop iocontrol.0.user-enable-out iocontrol.0.emc-enable-in # create signals for tool loading loopback net tool-prep-loop iocontrol.0.tool-prepare iocontrol.0.tool-prepared net tool-change-loop iocontrol.0.tool-change iocontrol.0.tool-changed # connect "spindle on" motion controller pin to a physical pin net spindle-on motion.spindle-on => parport.0.pin-09-out ### ### You might use something like this to enable chopper drives when machine ON ### the Xen signal is defined in core_stepper.hal ### # net Xen => parport.0.pin-01-out ### ### If you want active low for this pin, invert it like this: ### # setp parport.0.pin-01-out-invert 1 ### Integrator Manual V2.5, 2016-05-12 41 / 258 ### A sample home switch on the X axis (axis 0). make a signal, ### link the incoming parport pin to the signal, then link the signal ### to LinuxCNC’s axis 0 home switch input pin ### # net Xhome parport.0.pin-10-in => axis.0.home-sw-in ### ### ### ### ### ### # # # # Shared home switches all on one parallel port pin? that’s ok, hook the same signal to all the axes, but be sure to set HOME_IS_SHARED and HOME_SEQUENCE in the ini file. See the user manual! net net net net homeswitches homeswitches homeswitches homeswitches <= => => => parport.0.pin-10-in axis.0.home-sw-in axis.1.home-sw-in axis.2.home-sw-in ### ### Sample separate limit switches on the X axis (axis 0) ### # net X-neg-limit parport.0.pin-11-in => axis.0.neg-lim-sw-in # net X-pos-limit parport.0.pin-12-in => axis.0.pos-lim-sw-in ### ### Just like the shared home switches example, you can wire together ### limit switches. Beware if you hit one, LinuxCNC will stop but can’t tell ### you which switch/axis has faulted. Use caution when recovering from this. ### # net Xlimits parport.0.pin-13-in => axis.0.neg-lim-sw-in axis.0.pos-lim-sw-in The lines starting with # are comments, and their only purpose is to guide the reader through the file. 8.3.2 Overview There are a couple of operations that get executed when the standard_pinout.hal gets executed/interpreted: • The Parport driver gets loaded (see the Parport section of the HAL Manual for details) • The read & write functions of the parport driver get assigned to the base thread 1 • The step & direction signals for axes X,Y,Z get linked to pins on the parport • Further I/O signals get connected (estop loopback, toolchanger loopback) • A spindle-on signal gets defined and linked to a parport pin 8.3.3 Changing the standard_pinout.hal If you want to change the standard_pinout.hal file, all you need is a text editor. Open the file and locate the parts you want to change. If you want for example to change the pin for the X-axis Step & Directions signals, all you need to do is to change the number in the parport.0.pin-XX-out name: 1 the fastest thread in the LinuxCNC setup, usually the code gets executed every few tens of microseconds Integrator Manual V2.5, 2016-05-12 42 / 258 net Xstep parport.0.pin-03-out net Xdir parport.0.pin-02-out can be changed to: net Xstep parport.0.pin-02-out net Xdir parport.0.pin-03-out or basically any other out pin you like. Hint: make sure you don’t have more than one signal connected to the same pin. 8.3.4 Changing polarity of a signal If external hardware expects an “active low” signal, set the corresponding -invert parameter. For instance, to invert the spindle control signal: setp parport.0.pin-09-invert TRUE 8.3.5 Adding PWM Spindle Speed Control If your spindle can be controlled by a PWM signal, use the pwmgen component to create the signal: loadrt pwmgen output_type=0 addf pwmgen.update servo-thread addf pwmgen.make-pulses base-thread net spindle-speed-cmd motion.spindle-speed-out => pwmgen.0.value net spindle-on motion.spindle-on => pwmgen.0.enable net spindle-pwm pwmgen.0.pwm => parport.0.pin-09-out setp pwmgen.0.scale 1800 # Change to your spindle’s top speed in RPM This assumes that the spindle controller’s response to PWM is simple: 0% PWM gives 0 RPM, 10% PWM gives 180 RPM, etc. If there is a minimum PWM required to get the spindle to turn, follow the example in the nist-lathe sample configuration to use a scale component. 8.3.6 Adding an enable signal Some amplifiers (drives) require an enable signal before they accept and command movement of the motors. For this reason there are already defined signals called Xen, Yen, Zen. To connect them use the following example: net Xen parport.0.pin-08-out You can either have one single pin that enables all drives; or several, depending on the setup you have. Note, however, that usually when one axis faults, all the other drives will be disabled as well, so having only one enable signal / pin for all drives is a common practice. 8.3.7 External ESTOP button As you can see in the standard_pinout.hal file by default the stepper configuration assumes no external ESTOP button. To add a simple external button you need to replace the line: 2 An extensive explanation of hooking up ESTOP circuitry is explained in the wiki.linuxcnc.org and elsewhere in the Integrator Manual 2 Integrator Manual V2.5, 2016-05-12 43 / 258 net estop-loop iocontrol.0.user-enable-out iocontrol.0.emc-enable-in with net estop-loop parport.0.pin-01-in iocontrol.0.emc-enable-in This assumes an ESTOP switch connected to pin 01 on the parport. As long as the switch will stay pushed3 , LinuxCNC will be in the ESTOP state. When the external button gets released LinuxCNC will immediately switch to the ESTOP-RESET state, and all you need to do is switch to Machine On and you’ll be able to continue your work with LinuxCNC. 3 make sure you use a maintained switch for ESTOP. Integrator Manual V2.5, 2016-05-12 44 / 258 Chapter 9 Basic HAL Tutorial 9.1 HAL Commands More detailed information can be found in the man page for halcmd man halcmd in a terminal window. To see the HAL configuration and check the status of pins and parameters use the HAL Configuration window on the Machine menu in AXIS. To watch a pin status open the Watch tab and click on each pin you wish to watch and it will be added to the watch window. Integrator Manual V2.5, 2016-05-12 45 / 258 Figure 9.1: HAL Configuration Window 9.1.1 loadrt The command loadrt loads a real time HAL component. Real time component functions need to be added to a thread to be updated at the rate of the thread. You cannot load a user space component into the real time space. The syntax and an example: loadrt loadrt mux4 count=1 9.1.2 addf The command addf adds a real time component function to a thread. You have to add a function from a HAL real time component to a thread to get the function to update at the rate of the thread. If you used the Stepper Config Wizard to generate your config you will have two threads. • base-thread (the high-speed thread): this thread handles items that need a fast response, like making step pulses, and reading and writing the parallel port. Integrator Manual V2.5, 2016-05-12 46 / 258 • servo-thread (the slow-speed thread): this thread handles items that can tolerate a slower response, like the motion controller, ClassicLadder, and the motion command handler. The syntax and an example: addf addf mux4 servo-thread 9.1.3 loadusr The command loadusr loads a user space HAL component. User space programs are their own separate processes, which optionally talk to other HAL components via pins and parameters. You cannot load real time components into user space. Flags may be one or more of the following: -W to wait for the component to become ready. The component is assumed to have the same name as the first argument of the command. -Wn to wait for the component, which will have the given . This only applies if the component has a name option. -w to wait for the program to exit -i to ignore the program return value (with -w) -n name a component when it is a valid option for that component. The syntax and examples: loadusr loadusr halui loadusr -Wn spindle gs2_vfd -n spindle In English it means loadusr wait for name spindle component gs2_vfd name spindle. 9.1.4 net The command net creates a connection between a signal and one or more pins. If the signal does not exist net creates the new signal. This replaces the need to use the command newsig. The optional direction arrows <=, => and <=> make it easier to follow the logic when reading a net command line and are not used by the net command. The direction arrows must be separated by a space from the pin names. Syntax and Example: net signal-name pin-name net home-x axis.0.home-sw-in <= parport.0.pin-11-in In the above example home-x is the signal name, axis.0.home-sw-in is a Direction IN pin, <= is the optional direction arrow, and parport.0.pin-11-in is a Direction OUT pin. This may seem confusing but the in and out labels for a parallel port pin indicates the physical way the pin works not how it is handled in HAL. A pin can be connected to a signal if it obeys the following rules: Integrator Manual V2.5, 2016-05-12 47 / 258 • An IN pin can always be connected to a signal • An IO pin can be connected unless there’s an OUT pin on the signal • An OUT pin can be connected only if there are no other OUT or IO pins on the signal The same signal-name can be used in multiple net commands to connect additional pins, as long as the rules above are obeyed. Figure 9.2: Signal Direction This example shows the signal xStep with the source being stepgen.0.out and with two readers, parport.0.pin-02-out and parport.0.pin08-out. Basically the value of stepgen.0.out is sent to the signal xStep and that value is then sent to parport.0.pin-02-out and parport.0.pin-08-out. # signal source destination destination net xStep stepgen.0.out => parport.0.pin-02-out parport.0.pin-08-out Since the signal xStep contains the value of stepgen.0.out (the source) you can use the same signal again to send the value to another reader. To do this just use the signal with the readers on another line. net xStep => parport.0.pin-02-out I/O pins An I/O pin like encoder.N.index-enable can be read or set as allowed by the component. 9.1.5 setp The command setp sets the value of a pin or parameter. The valid values will depend on the type of the pin or parameter. It is an error if the data types do not match. Integrator Manual V2.5, 2016-05-12 48 / 258 Some components have parameters that need to be set before use. Parameters can be set before use or while running as needed. You cannot use setp on a pin that is connected to a signal. The syntax and an example: setp setp parport.0.pin-08-out TRUE 9.1.6 sets The command sets sets the value of a signal. The syntax and an example: sets net mysignal and2.0.in0 pyvcp.my-led sets mysignal 1 It is an error if: • The signal-name does not exist • If the signal already has a writer • If value is not the correct type for the signal 9.1.7 unlinkp The command unlinkp unlinks a pin from the connected signal. If no signal was connected to the pin prior running the command, nothing happens. The unlinkp command is useful for trouble shooting. The syntax and an example: unlinkp unlinkp parport.0.pin-02-out 9.1.8 Obsolete Commands The following commands are depreciated and may be removed from future versions. Any new configuration should use the net command. These commands are included so older configurations will still work. 9.1.8.1 linksp The command linksp creates a connection between a signal and one pin. The syntax and an example: linksp linksp X-step parport.0.pin-02-out The linksp command has been superseded by the net command. Integrator Manual V2.5, 2016-05-12 9.1.8.2 49 / 258 linkps The command linkps creates a connection between one pin and one signal. It is the same as linksp but the arguments are reversed. The syntax and an example: linkps linkps parport.0.pin-02-out X-Step The linkps command has been superseded by the net command. 9.1.8.3 newsig the command newsig creates a new HAL signal by the name and the data type of . Type must be bit, s32, u32 or float. Error if all ready exists. The syntax and an example: newsig newsig Xstep bit More information can be found in the HAL manual or the man pages for halrun. 9.2 9.2.1 HAL Data Bit A bit value is an on or off. • bit values = true or 1 and false or 0 (True, TRUE, true are all valid) 9.2.2 Float A float is a floating point number. In other words the decimal point can move as needed. • float values = a 64 bit floating point value, with approximately 53 bits of resolution and over 1000 bits of dynamic range. For more information on floating point numbers see: http://en.wikipedia.org/wiki/Floating_point 9.2.3 s32 An s32 number is a whole number that can have a negative or positive value. • s32 values = integer numbers -2147483648 to 2147483647 9.2.4 u32 A u32 number is a whole number that is positive only. • u32 values = integer numbers 0 to 4294967295 Integrator Manual V2.5, 2016-05-12 9.3 50 / 258 HAL Files If you used the Stepper Config Wizard to generate your config you will have up to three HAL files in your config directory. • my-mill.hal (if your config is named my-mill) This file is loaded first and should not be changed if you used the Stepper Config Wizard. • custom.hal This file is loaded next and before the GUI loads. This is where you put your custom HAL commands that you want loaded before the GUI is loaded. • custom_postgui.hal This file is loaded after the GUI loads. This is where you put your custom HAL commands that you want loaded after the GUI is loaded. Any HAL commands that use pyVCP widgets need to be placed here. 9.4 HAL Components Two parameters are automatically added to each HAL component when it is created. These parameters allow you to scope the execution time of a component. .time .tmax Time is the number of CPU cycles it took to execute the function. Tmax is the maximum number of CPU cycles it took to execute the function. Tmax is a read/write parameter so the user can set it to 0 to get rid of the first time initialization on the function’s execution time. 9.5 Logic Components HAL contains several real time logic components. Logic components follow a Truth Table that states what the output is for any given input. Typically these are bit manipulators and follow electrical logic gate truth tables. 9.5.1 and2 The and2 component is a two input and gate. The truth table below shows the output based on each combination of input. Syntax and2 [count=N] | [names=name1[,name2...]] Functions and2.n Pins and2.N.in0 (bit, in) and2.N.in1 (bit, in) and2.N.out (bit, out) Truth Table in0 False True False True in1 False False True True out False False False True Integrator Manual V2.5, 2016-05-12 9.5.2 51 / 258 not The not component is a bit inverter. Syntax not [count=n] | [names=name1[,name2...]] Functions not.all not.n Pins not.n.in (bit, in) not.n.out (bit, out) Truth Table in True False 9.5.3 out False True or2 The or2 component is a two input OR gate. Syntax or2[count=n] | [names=name1[,name2...]] Functions or2.n Pins or2.n.in0 (bit, in) or2.n.in1 (bit, in) or2.n.out (bit, out) Truth Table in0 True True False False 9.5.4 in1 False True True False xor2 The xor2 component is a two input XOR (exclusive OR)gate. Syntax xor2[count=n] | [names=name1[,name2...]] Functions out True True True False Integrator Manual V2.5, 2016-05-12 52 / 258 xor2.n Pins xor2.n.in0 (bit, in) xor2.n.in1 (bit, in) xor2.n.out (bit, out) Truth Table in0 True True False False 9.5.5 in1 False True True False out True False True False Logic Examples An and2 example connecting two inputs to one output. loadrt and2 count=1 addf and2.0 servo-thread net my-sigin1 and2.0.in0 <= parport.0.pin-11-in net my-sigin2 and2.0.in1 <= parport.0.pin-12-in net both-on parport.0.pin-14-out <= and2.0.out In the above example one copy of and2 is loaded into real time space and added to the servo thread. Next pin 11 of the parallel port is connected to the in0 bit of the and gate. Next pin 12 is connected to the in1 bit of the and gate. Last we connect the and2 out bit to the parallel port pin 14. So following the truth table for and2 if pin 11 and pin 12 are on then the output pin 14 will be on. 9.6 9.6.1 Conversion Components weighted_sum The weighted_sum converts a group of bits to an integer. The conversion is the sum of the weights of the bits that are on plus any offset. The weight of the m-th bit is 2ˆm. This is similar to a binary coded decimal but with more options. The hold bit stops processing the input changes so the sum will not change. The following syntax is used to load the weighted_sum component. loadrt weighted_sum wsum_sizes=size[,size,...] Creates weighted sum groups each with the given number of input bits (size). To update the weighted_sum you need to attach process_wsums to a thread. addf process_wsums servo-thread This updates the weighted_sum component. In the following example clipped from the HAL Configuration window in Axis the bits 0 and 2 are true and there is no offset. The weight of 0 is 1 and the weight of 2 is 4 so the sum is 5. weighted_sum Integrator Manual V2.5, 2016-05-12 Component Pins: Owner Type Dir 10 bit In 10 s32 I/O 10 bit In 10 s32 I/O 10 bit In 10 s32 I/O 10 bit In 10 s32 I/O 10 bit In 10 s32 I/O 10 s32 Out Value TRUE 1 FALSE 2 TRUE 4 FALSE 8 FALSE 0 5 53 / 258 Name wsum.0.bit.0.in wsum.0.bit.0.weight wsum.0.bit.1.in wsum.0.bit.1.weight wsum.0.bit.2.in wsum.0.bit.2.weight wsum.0.bit.3.in wsum.0.bit.3.weight wsum.0.hold wsum.0.offset wsum.0.sum Integrator Manual V2.5, 2016-05-12 54 / 258 Part III GUI Integrator Manual V2.5, 2016-05-12 55 / 258 Chapter 10 Python Virtual Control Panel 10.1 Introduction Python Virtual Control Panel The PyVCP (Python Virtual Control Panel) is designed to give the integrator the ability to customize the AXIS interface with buttons and indicators to do special tasks. Hardware machine control panels can use up a lot of I/O pins and can be expensive. That is where Virtual Control Panels have the advantage as well as it cost nothing to build a PyVCP. Virtual Control Panels can be used for testing or monitoring things to temporarily replace real I/O devices while debugging ladder logic, or to simulate a physical panel before you build it and wire it to an I/O board. The following graphic displays many of the PyVCP widgets. Integrator Manual V2.5, 2016-05-12 10.2 56 / 258 Panel Construction The layout of a PyVCP panel is specified with an XML file that contains widget tags between and . For example:If you place this text in a file called tiny.xml, and run halrun -I loadusr pyvcp -c mypanel tiny.xml Integrator Manual V2.5, 2016-05-12 57 / 258 PyVCP will create the panel for you, which includes two widgets, a Label with the text This is a LED indicator, and a LED, used for displaying the state of a HAL BIT signal. It will also create a HAL component named mypanel (all widgets in this panel are connected to pins that start with mypanel.). Since no tag was present inside the tag, PyVCP will automatically name the HAL pin for the LED widget mypanel.led.0 For a list of widgets and their tags and options, see the widget reference below. Once you have created your panel, connecting HAL signals to and from the PyVCP pins is done with the halcmd: net signal-name If you are new to HAL, the HAL basics chapter in the Integrator Manual is a good place to start. 10.3 Security Parts of PyVCP files are evaluated as Python code, and can take any action available to Python programs. Only use PyVCP .xml files from a source that you trust. 10.4 AXIS Since AXIS uses the same GUI toolkit (Tkinter) as PyVCP, it is possible to include a PyVCP panel on the right side of the normal AXIS user interface. A typical example is explained below. Place your PyVCP XML file describing the panel in the same directory where your .ini file is. Say we we want to display the current spindle speed using a Bar widget. Place the following in a file called spindle.xml: Here we’ve made a panel with a Label and a Bar widget, specified that the HAL pin connected to the Bar should be named spindle-speed, and set the maximum value of the bar to 5000 (see widget reference below for all options). To make AXIS aware of this file, and call it at start up, we need to specify the following in the [DISPLAY] section of the .ini file: PYVCP = spindle.xml To make our widget actually display the spindle-speed it needs to be hooked up to the appropriate HAL signal. A .hal file that will be run once AXIS and PyVCP have started can be specified in the [HAL] section of the .ini file: POSTGUI_HALFILE = spindle_to_pyvcp.hal This change will run the HAL commands specified in spindle_to_pyvcp.hal. In our example the contents could look like this: net spindle-rpm-filtered => pyvcp.spindle-speed assuming that a signal called spindle-rpm-filtered already exists. Note that when running together with AXIS, all PyVCP widget HAL pins have names that start with pyvcp.. Integrator Manual V2.5, 2016-05-12 58 / 258 This is what the newly created PyVCP panel should look like in AXIS. The sim/lathe configuration is already configured this way. 10.5 Stand Alone This section describes how PyVCP panels can be displayed on their own with or without LinuxCNC’s machine controller. To load a stand alone PyVCP panel with LinuxCNC use these commands: loadusr -Wn mypanel pyvcp -g WxH+X+Y -c mypanel "spindle-speed" 5000 panel_file.xml You would use this if you wanted a floating panel or a panel with a GUI other than AXIS. • -Wn panelname - makes HAL wait for the component panelname to finish loading (become ready in HAL speak) before processing more HAL commands. This is important because PyVCP panels export HAL pins, and other HAL components will need them present to connect to them. Note the capital W and lowercase n. If you use the -Wn option you must use the -c option to name the panel. • pyvcp < -g> < -c> panel.xml - builds the panel with the optional geometry and/or panelname from the xml panel file. The panel.xml can be any name that ends in .xml. The .xml file is the file that describes how to build the panel. You must add the path name if the panel is not in the directory that the HAL script is in. • -g <+X+Y> - specifies the geometry to be used when constructing the panel. The syntax is Width x Height + X Anchor + Y Anchor. You can set the size or position or both. The anchor point is the upper left corner of the panel. An example is -g 250x500+800+0 This sets the panel at 250 pixels wide, 500 pixels tall, and anchors it at X800 Y0. • -c panelname - tells PyVCP what to call the component and also the title of the window. The panelname can be any name without spaces. Integrator Manual V2.5, 2016-05-12 59 / 258 To load a stand alone PyVCP panel without LinuxCNC use this command: loadusr -Wn mypanel pyvcp -g 250x500+800+0 -c mypanel mypanel.xml The minimum command to load a pyvcp panel is: loadusr pyvcp mypanel.xml You would use this if you want a panel without LinuxCNC’s machine controller such as for testing or a standalone DRO. The loadusr command is used when you also load a component that will stop HAL from closing until it’s done. If you loaded a panel and then loaded Classic Ladder using loadusr -w classicladder, CL would hold HAL open (and the panel) until you closed CL. The -Wn above means wait for the component -Wn "name" to become ready. (name can be any name. Note the capital W and lowercase n.) The -c tells PyVCP to build a panel with the name panelname using the info in panel_file_name.xml. The name panel_file_name.xml can be any name but must end in .xml - it is the file that describes how to build the panel. You must add the path name if the panel is not in the directory that the HAL script is in. An optional command to use if you want the panel to stop HAL from continuing commands / shutting down. After loading any other components you want the last HAL command to be: waituser panelname This tells HAL to wait for component panelname to close before continuing HAL commands. This is usually set as the last command so that HAL shuts down when the panel is closed. 10.6 Widgets HAL signals come in two variants, bits and numbers. Bits are off/on signals. Numbers can be float, s32 or u32. For more information on HAL data types see the HAL manual. The PyVCP widget can either display the value of the signal with an indicator widget, or modify the signal value with a control widget. Thus there are four classes of PyVCP widgets that you can connect to a HAL signal. A fifth class of helper widgets allow you to organize and label your panel. 1. Widgets for indicating bit signals: led, rectled 2. Widgets for controlling bit signals: button, checkbutton, radiobutton 3. Widgets for indicating number signals: number, s32, u32, bar, meter 4. Widgets for controlling number signals: spinbox, scale, jogwheel 5. Helper widgets: hbox, vbox, table, label, labelframe 10.6.1 Syntax Each widget is described briefly, followed by the markup used, and a screen shot. All tags inside the main widget tag are optional. 10.6.2 General Notes At the present time, both a tag-based and an attribute-based syntax are supported. For instance, the following XML fragments are treated identically: and When the attribute-based syntax is used, the following rules are used to turn the attributes value into a Python value: Integrator Manual V2.5, 2016-05-12 60 / 258 1. If the first character of the attribute is one of the following, it is evaluated as a Python expression: {(["’ 2. If the string is accepted by int(), the value is treated as an integer 3. If the string is accepted by float(), the value is treated as floating-point 4. Otherwise, the string is accepted as a string. When the tag-based syntax is used, the text within the tag is always evaluated as a Python expression. The examples below show a mix of formats. 10.6.2.1 Comments To add a comment use the xml syntax for a comment. 10.6.2.2 Editing the XML file Edit the XML file with a text editor. In most cases you can right click on the file and select open with text editor or similar. 10.6.2.3 Colors Colors can be specified using the X11 rgb colors by name gray75 or hex #0000ff. A complete list is located here http://sedition.com/perl/rgb.html. Common Colors (colors with numbers indicate shades of that color) • white • black • blue and blue1 - 4 • cyan and cyan1 - 4 • green and green1 - 4 • yellow and yellow1 - 4 • red and red1 - 4 • purple and purple1 - 4 • gray and gray0 - 100 10.6.2.4 HAL Pins HAL pins provide a means to connect the widget to something. Once you create a HAL pin for your widget you can connect it to another HAL pin with a net command in a .hal file. For more information on the net command see the HAL Commands section of the HAL manual. Integrator Manual V2.5, 2016-05-12 10.6.3 61 / 258 Label A label is a piece of text on your panel. The label has an optional disable pin that is created when you add "my-led" True . The above code produced this example. 10.6.4 LEDs A LED is used to indicate the status of a bit halpin. The LED color will be on_color when the halpin is true, and off_color otherwise. •- sets the name of the pin, default is led.n, where n is an integer • - sets the size of the led, default is 20 • - sets the color of the LED when the pin is true. default is green • - sets the color of the LED when the pin is false. default is red • - when true adds a disable pin to the led. • - sets the color of the LED when the pin is disabled. 10.6.4.1 Round LED The above code produced this example. Integrator Manual V2.5, 2016-05-12 10.6.4.2 62 / 258 Rectangle LED This is a variant of the led widget. "my-led" 50 "green" "red" The above code produced this example. Also showing a vertical box with relief. 10.6.5 Buttons A button is used to control a BIT pin. The pin will be set True when the button is pressed and held down, and will be set False when the button is released. Buttons can use the following formatting options • RIDGE 6 "my-led" "50" "100" "green" "red" n - where n is the amount of extra horizontal extra space •n - where n is the amount of extra vertical extra space •"color" - the cursor over color •"color" - the color of the button 10.6.5.1 Text Button A text button controls a bit halpin. The halpin is false until the button is pressed then it is true. The button is a momentary button. The text button has an optional disable pin that is created when you addTrue ."coolant-chkbtn" "Coolant" The above code produced this example. The coolant checkbutton is checked. Notice the extra spaces in the Chips text to keep the checkbuttons aligned. 10.6.5.3 Radiobutton A radiobutton will set one of the halpins true. The other pins are set false. "chip-chkbtn" "Chips " The above code produced this example. Note that the HAL pins in the example above will me named my-radio.one, my-radio.two, and my-radio.three. In the image above, one is the selected value. Integrator Manual V2.5, 2016-05-12 10.6.6 64 / 258 Number Displays Number displays can use the following formatting options • ("Font Name",n) where n is the font size • ["one","two","three"] "my-radio" n where n is the overall width of the space used •pos where pos is LEFT, CENTER, or RIGHT (doesn’t work) •n where n is the amount of extra horizontal extra space •n where n is the amount of extra vertical extra space 10.6.6.1 Number The number widget displays the value of a float signal.The above code produced this example. • - is a Tkinter font type and size specification. One font that will show up to at least size 200 is courier 10 pitch, so for a really big Number widget you could specify: ("courier 10 pitch",100) • "my-number" ("Helvetica",24)"+4.4f" - is a C-style format specified that determines how the number is displayed. 10.6.6.2 s32 Number The s32 number widget displays the value of a s32 number. The syntax is the same as number except the name which is . Make sure the width is wide enough to cover the largest number you expect to use. The above code produced this example. Integrator Manual V2.5, 2016-05-12 10.6.6.3 65 / 258 u32 Number The u32 number widget displays the value of a u32 number. The syntax is the same as number except the name which is "my-number" ("Helvetica",24)"6d" 6 . 10.6.6.4 Bar A bar widget displays the value of a FLOAT signal both graphically using a bar display and numerically. The above code produced this example. 10.6.6.5 Meter Meter displays the value of a FLOAT signal using a traditional dial indicator. "my-bar" 0 123 "grey" "red" The above code produced this example. Integrator Manual V2.5, 2016-05-12 10.6.7 Number Inputs 10.6.7.1 Spinbox 66 / 258 Spinbox controls a FLOAT pin. You increase or decrease the value of the pin by either pressing on the arrows, or pointing at the spinbox and rolling your mouse-wheel. "mymeter" "Battery" "Volts" 250 0 15.5 1 0.2 (14.5,15.5,"yellow") (12,14.5,"green") (0,12,"red") The above code produced this example. 10.6.7.2 Scale Scale controls a float or a s32 pin. You increase or decrease the value of the pin be either dragging the slider, or pointing at the scale and rolling your mouse-wheel. The halpin will have both -f and -i added to it to form the float and s32 pins. Width is the width of the slider in vertical and the height of the slider in horizontal orientation. Integrator Manual V2.5, 2016-05-12 67 / 258 "my-spinbox" -12 33 0 0.1 "2.3f" ("Arial",30)("Helvetica",16) "25" "my-hscale" 0.1 HORIZONTAL -15 -33 26 ("Helvetica",16) The above code produced this example. 10.6.7.3 Dial The Dial outputs a HAL float and reacts to both mouse wheel and dragging. Double left click to increase the resolution and double right click to reduce the resolution by one digit. The output is capped by the min and max values. The"50" "my-vscale" 1 VERTICAL 100 0 is how many tick marks are on the outside of the ring (beware of high numbers). Integrator Manual V2.5, 2016-05-12 68 / 258 The above code produced this example. 10.6.7.4 Jogwheel Jogwheel mimics a real jogwheel by outputting a FLOAT pin which counts up or down as the wheel is turned, either by dragging in a circular motion, or by rolling the mouse-wheel. 200 100 -15 15 "Dial" 0 0.001 "anaout" "yellow" "green" "black" The above code produced this example. Integrator Manual V2.5, 2016-05-12 10.6.8 69 / 258 Images Image displays use only .gif image format. All of the images must be the same size. The images must be in the same directory as your ini file (or in the current directory if running from the command line with halrun/halcmd). 10.6.8.1 Image Bit The image_bit toggles between two images by setting the halpin to true or false. "my-wheel" 45 250 This example was produced from the above code. Using the two image files fwd.gif and rev.gif. FWD is displayed when selectimage is false and REV is displayed when selectimage is true. 10.6.8.2 Image u32 The image_u32 is the same as image_bit except you have essentially an unlimited number of images and you select the image by setting the halpin to a integer value with 0 for the first image in the images list and 1 for the second image etc. Integrator Manual V2.5, 2016-05-12 70 / 258 The above code produced the following example by adding the stb.gif image. Notice that the default is the min even though it is set higher than max unless there is a negative min. 10.6.9 Containers Containers are widgets that contain other widgets. Containers are used to group other widgets. 10.6.9.1 Borders Container borders are specified with two tags used together. The tag specifies the type of border and the specifies the width of the border. • type - Where type is FLAT, SUNKEN, RAISED, GROOVE, or RIDGE •n - Where n is the width of the border.The above code produced this example. 10.6.9.2 Hbox Use an Hbox when you want to stack widgets horizontally next to each other. The above code produced this example. Inside an Hbox, you can use the RIDGE 6 , , and tags to choose how items in the box behave when the window is re-sized. For details of how fill, anchor, and expand behave, refer to the Tk pack manual page, pack(3tk). By default, fill="y", anchor="center", expand="yes". 10.6.9.3 Vbox Use a Vbox when you want to stack widgets vertically on top of each other. The above code produced this example. Integrator Manual V2.5, 2016-05-12 72 / 258 Inside a Hbox, you can use the RIDGE 6 , , and tags to choose how items in the box behave when the window is re-sized. For details of how fill, anchor, and expand behave, refer to the Tk pack manual page, pack(3tk). By default, fill="x", anchor="center", expand="yes". 10.6.9.4 Labelframe A labelframe is a frame with a groove and a label at the upper-left corner. ("Helvetica",16) The above code produced this example. 10.6.9.5 Table A table is a container that allows layout in a grid of rows and columns. Each row is started by atag. A contained widget may span rows or columns through the use of the tag. The sides of the cells to which the contained widgets “stick” may be set through the use of the tag. A table expands on its flexible rows and columns. Example: The above code produced this example. 10.6.9.6 Tabs A tabbed interface can save quite a bit of space. Create one container for each tab name. Only one tabs section can exist and tabs can not be nested or stacked. The width of the widest item controls the width of the tabs.
Integrator Manual V2.5, 2016-05-12 73 / 258 The above code produced this example showing each tab selected. Integrator Manual V2.5, 2016-05-12 74 / 258 Integrator Manual V2.5, 2016-05-12 75 / 258 Chapter 11 PyVCP Examples 11.1 AXIS To create a PyVCP panel to use with the AXIS interface that is attached to the right of AXIS you need to do the following basic things. • Create an .xml file that contains your panel description and put it in your config directory. • Add the PyVCP entry to the [DISPLAY] section of the ini file with your .xml file name. • Add the POSTGUI_HALFILE entry to the [HAL] section of the ini file with the name of your postgui HAL file name. • Add the links to HAL pins for your panel in the postgui.hal file to connect your PyVCP panel to LinuxCNC. 11.2 Floating To create floating PyVCP panels that can be used with any interface you need to do the following basic things. • Create an .xml file that contains your panel description and put it in your config directory. • Add a loadusr line to your .hal file to load each panel. • Add the links to HAL pins for your panel in the postgui.hal file to connect your PyVCP panel to LinuxCNC. The following is an example of a loadusr command to load two PyVCP panels and name each one so the connection names in HAL will be known. loadusr -Wn btnpanel pyvcp -c btnpanel panel1.xml loadusr -Wn sppanel pyvcp -c sppanel panel2.xml The -Wn makes HAL Wait for name to be loaded before proceeding. The pyvcp -c makes PyVCP name the panel. The HAL pins from panel1.xml will be named btnpanel. ["Spindle", "Green Eggs", "Ham"] "spindle-speed" 5000 The HAL pins from panel2.xml will be named sppanel. Make sure the loadusr line is before any nets that make use of the PyVCP pins. Integrator Manual V2.5, 2016-05-12 11.3 76 / 258 Jog Buttons In this example we will create a PyVCP panel with jog buttons for X, Y, and Z. This configuration will be built upon a Stepconf Wizard generated configuration. First we run the Stepconf Wizard and configure our machine, then on the Advanced Configuration Options page we make a couple of selections to add a blank PyVCP panel as shown in the following figure. For this example we named the configuration pyvcp_xyz on the Basic Machine Information page of the Stepconf Wizard. Figure 11.1: XYZ Wizard Configuration The Stepconf Wizard will create several files and place them in the linuxcnc/configs/pyvcp_xyz directory. If you left the create link checked you will have a link to those files on your desktop. Integrator Manual V2.5, 2016-05-12 11.3.1 77 / 258 Create the Widgets Open up the custompanel.xml file by right clicking on it and selecting open with text editor. Between the tags we will add the widgets for our panel. Look in the PyVCP Widgets Reference section of the manual for more detailed information on each widget. In your custompanel.xml file we will add the description of the widgets. After adding the above you now will have a PyVCP panel that looks like the following attached to the right side of AXIS. It looks nice but it does not do anything until you connect the buttons to halui. If you get an error when you try and run scroll down to the bottom of the pop up window and usually the error is a spelling or syntax error and it will be there. Figure 11.2: Jog Buttons Integrator Manual V2.5, 2016-05-12 11.3.2 79 / 258 Make Connections To make the connections needed open up your custom_postgui.hal file and add the following. # connect the X PyVCP buttons net my-jogxminus halui.jog.0.minus <= pyvcp.x-minus net my-jogxplus halui.jog.0.plus <= pyvcp.x-plus # connect the Y PyVCP buttons net my-jogyminus halui.jog.1.minus <= pyvcp.y-minus net my-jogyplus halui.jog.1.plus <= pyvcp.y-plus # connect the Z PyVCP buttons net my-jogzminus halui.jog.2.minus <= pyvcp.z-minus net my-jogzplus halui.jog.2.plus <= pyvcp.z-plus # connect the PyVCP jog speed slider net my-jogspeed halui.jog-speed <= pyvcp.jog-speed-f After resetting the E-Stop and putting it into jog mode and moving the jog speed slider in the PyVCP panel to a value greater than zero the PyVCP jog buttons should work. You can not jog when running a g code file or while paused or while the MDI tab is selected. 11.4 Port Tester This example shows you how to make a simple parallel port tester using PyVCP and HAL. First create the ptest.xml file with the following code to create the panel description. ("Helvetica",16) RAISED 3 RAISED 3 RAISED 3 RAISED 3 ("Helvetica",14) "jog-speed" 1 HORIZONTAL 0 80 This will create the following floating panel which contains a couple of in pins and a couple of out pins. Figure 11.3: Port Tester Panel To run the HAL commands that we need to get everything up and running we put the following in our ptest.hal file. loadrt hal_parport cfg="0x378 out" loadusr -Wn ptest pyvcp -c ptest ptest.xml loadrt threads name1=porttest period1=1000000 addf parport.0.read porttest addf parport.0.write porttest net pin01 ptest.btn01 parport.0.pin-01-out ptest.led-01 net pin02 ptest.btn02 parport.0.pin-02-out ptest.led-02 net pin10 parport.0.pin-10-in ptest.led-10 net pin11 parport.0.pin-11-in ptest.led-11 start Integrator Manual V2.5, 2016-05-12 81 / 258 To run the HAL file we use the following command from a terminal window. ~$ halrun -I -f ptest.hal The following figure shows what a complete panel might look like. Figure 11.4: Port Tester Complete To add the rest of the parallel port pins just modify the .xml and .hal files. To show the pins after running the HAL script use the following command at the halcmd prompt: halcmd: show pin Component Pins: Owner Type Dir Value 2 bit IN FALSE 2 bit IN FALSE 2 bit IN FALSE 2 bit IN FALSE 2 bit IN FALSE 2 bit IN FALSE 2 bit IN FALSE 2 bit IN FALSE 2 bit IN FALSE 2 bit OUT TRUE 2 bit OUT FALSE 2 bit OUT TRUE 2 bit OUT FALSE 2 bit OUT TRUE 2 bit OUT FALSE 2 bit OUT TRUE 2 bit OUT FALSE 2 bit IN FALSE 2 bit OUT TRUE 2 bit OUT FALSE 2 bit IN FALSE Name parport.0.pin-01-out <== pin01 parport.0.pin-02-out <== pin02 parport.0.pin-03-out parport.0.pin-04-out parport.0.pin-05-out parport.0.pin-06-out parport.0.pin-07-out parport.0.pin-08-out parport.0.pin-09-out parport.0.pin-10-in ==> pin10 parport.0.pin-10-in-not parport.0.pin-11-in ==> pin11 parport.0.pin-11-in-not parport.0.pin-12-in parport.0.pin-12-in-not parport.0.pin-13-in parport.0.pin-13-in-not parport.0.pin-14-out parport.0.pin-15-in parport.0.pin-15-in-not parport.0.pin-16-out Integrator Manual V2.5, 2016-05-12 2 4 4 4 4 4 4 bit bit bit bit bit bit bit IN OUT OUT IN IN IN IN FALSE FALSE FALSE FALSE FALSE TRUE TRUE 82 / 258 parport.0.pin-17-out ptest.btn01 ==> pin01 ptest.btn02 ==> pin02 ptest.led-01 <== pin01 ptest.led-02 <== pin02 ptest.led-10 <== pin10 ptest.led-11 <== pin11 This will show you what pins are IN and what pins are OUT as well as any connections. 11.5 GS2 RPM Meter The following example uses the Automation Direct GS2 VDF driver and displays the RPM and other info in a PyVCP panel. This example is based on the GS2 example in the Hardware Examples section this manual. 11.5.1 The Panel To create the panel we add the following to the .xml file. RIDGE 2 "led-01" 25 "green" "red" RIDGE 2 "led-02" 25 "green" "red" Integrator Manual V2.5, 2016-05-12 80 / 258 RIDGE 2 "led-10" 25 "green" "red" RIDGE 2 "led-11" 25 "green" "red" The above gives us a PyVCP panel that looks like the following. 83 / 258 Integrator Manual V2.5, 2016-05-12 84 / 258 Figure 11.5: GS2 Panel 11.5.2 The Connections To make it work we add the following code to the custom_postgui.hal file. # display the rpm based on freq * rpm per hz loadrt mult2 addf mult2.0 servo-thread setp mult2.0.in1 28.75 net cypher_speed mult2.0.in0 <= spindle-vfd.frequency-out net speed_out pyvcp.spindle_rpm <= mult2.0.out # run led net gs2-run => pyvcp.on-led # fwd led net gs2-fwd => pyvcp.fwd-led # rev led net running-rev spindle-vfd.spindle-rev => pyvcp.rev-led Some of the lines might need some explanations. The fwd led line uses the signal created in the custom.hal file whereas the rev led needs to use the spindle-rev bit. You can’t link the spindle-fwd bit twice so you use the signal that it was linked to. Integrator Manual V2.5, 2016-05-12 85 / 258 Chapter 12 Glade Virtual Control Panel 12.1 What is GladeVCP? GladeVCP is an LinuxCNC component which adds the ability to add a new user interface panel to LinuxCNC user interfaces like Axis or Touchy. Unlike PyVCP, GladeVCP is not limitied to displaying and setting HAL pins, as arbitrary actions can be executed in Python code - in fact, a complete LinuxCNC user interface could be built with GladeVCP and Python. GladeVCP users the Glade WYSIWYG user interface editor, which makes it easy to create visually pleasing panels. It relies on the PyGTK bindings to the rich GTK+ widget set, and in fact all of these may be used in a GladeVCP application - not just the specialized widgets for interacting with HAL and LinuxCNC, which are documented here. 12.1.1 PyVCP versus GladeVCP at a glance Both support the creation of panels with HAL widgets - user interface elements like LED’s, buttons, sliders etc whose values are linked to a HAL pin, which in turn interfaces to the rest of LinuxCNC. PyVCP: • widget set: uses TkInter widgets • user interface creation: "edit XML file / run result / evaluate looks" cycle • no support for embedding user-defined event handling • no LinuxCNC interaction beyond HAL pin I/O supported GladeVCP: • widget set: relies on the GTK+ widget set. • user interface creation: uses the Glade WYSIWYG user interface editor • any HAL pin change may be directed to call back into a user-defined Python event handler • any GTK signal (key/button press, window, I/O, timer, network events) may be associated with user-defined handlers in Python • direct LinuxCNC interaction: arbitrary command execution, like initiating MDI commands to call a G-code subroutine, plus support for status change operations through Action Widgets • several independent GladeVCP panels may be run in different tabs • separation of user interface appearance and functionality: change appearance without touching any code Integrator Manual V2.5, 2016-05-12 12.2 86 / 258 A Quick Tour with the Example Panel GladeVCP panel windows may be run in three different setups: • always visible integrated into Axis at the right side, exactly like PyVCP panels • as a tab in Axis and Touchy; in Axis this would create a third tab besides the Preview and DRO tabs which must be raised explicitly • as a standalone toplevel window, which can be iconifyed/deiconified independent of the main window. Installed LinuxCNC If you’re using an installed version of LinuxCNC the examples shown below are in the configuration picker in the Sample Configurations > sim > gladevcp branch. Git Checkout The following instructions only apply if you’re using a git checkout. Open a terminal and change to the directory created by git then issue the commmands as shown. Note For the following commands to work on your git checkout you must first run make then run sudo make setuid then run . ./scripts/rip-environment. More information about a git checkout is on the linuxcnc wiki page. Run the sample GladeVCP panel integrated into Axis like PyVCP as follows: $ cd configs/sim/gladevcp $ linuxcnc gladevcp_panel.ini Run the same panel, but as a tab inside Axis: Integrator Manual V2.5, 2016-05-12 87 / 258 $ cd configs/sim/gladevcp $ linuxcnc gladevcp_tab.ini To run this panel as a standalone toplevel window besides Axis, just start Axis in the background and start gladevcp as follows: $ cd configs/sim/axis $ linuxcnc axis.ini & $ gladevcp -c gladevcp -u ../gladevcp/hitcounter.py -H ../gladevcp/manual-example.hal ../ ←gladevcp/manual-example.ui Integrator Manual V2.5, 2016-05-12 To run this panel inside Touchy: $ cd configs/sim/gladevcp $ linuxcnc gladevcp_touchy.ini 88 / 258 Integrator Manual V2.5, 2016-05-12 89 / 258 Functionally these setups are identical - they only differ in screen real estate requirements and visibility. Since it is possible to run several GladeVCP components in parallel (with different HAL component names), mixed setups are possible as well - for instance a panel on the right hand side, and one or more tabs for less-frequently used parts of the interface. 12.2.1 Exploring the example panel While running Axis, explore Show HAL Configuration - you will find the gladevcp HAL component and may observe their pin values while interacting with the widgets in the panel. The HAL setup can be found in configs/gladevcp/manual-example.hal. The example panel has two frames at the bottom. The panel is configured so that resetting ESTOP activates the Settings frame and turning the machine on enables the Commands frame at the bottom. The HAL widgets in the Settings frame are linked to LEDs and labels in the Status frame, and to the current and prepared tool number - play with them to see the effect. Executing the T RAISED 3 "spindle_rpm" "Spindle" "RPM" 200 0 3000 500 100 0,10,"yellow" RAISED 3 RAISED 2 5 "on-led" "30" "30" "green" "red" Integrator Manual V2.5, 2016-05-12RAISED 2 "fwd-led" "30" "30" "green" "red" RAISED 2 "rev-led" "30" "30" "red" "green" and M6 commands in the MDI window will change the current and prepared tool number fields. The buttons in the Commands frame are MDI Action widgets - pressing them will execute an MDI command in the interpreter. The third button Execute Oword subroutine is an advanced example - it takes several HAL pin values from the Settings frame, and passes them as parameters to the Oword subroutine. The actual parameters received by the routine are displayed by (DEBUG, ) commands - see configs/gladevcp/nc_files/oword.ngc for the subroutine body. To see how the panel is integrated into Axis, see the [DISPLAY]GLADEVCP statements in gladevcp_panel.ui, and the [DISPLAY]EMBED* and [HAL]POSTGUI_HALFILE statements in gladevcp_tab.ini respectively. 12.2.2 Exploring the User Interface description The user interface is created with the glade UI editor - to explore it, you need to have glade installed. To edit the user interface, run the command $ glade configs/gladevcp/manual-example.ui The center window shows the appearance of the UI. All user interface objects and support objects are found in the right top window, where you can select a specific widget (or by clicking on it in the center window). The properties of the selected widget are displayed, and can be changed, in the right bottom window. To see how MDI commands are passed from the MDI Action widgets, explore the widgets listed under Actions in the top right window, and in the right bottom window, unter the General tab, the MDI command property. 12.2.3 Exploring the Python callback See how a Python callback is integrated into the example: • in glade, see the hits label widget (a plain GTK+ widget) • in the button1 widget, look at the Signals tab, and find the signal pressed associated with the handler on_button_press • in ../gladevcp/hitcounter.py, see the method on_button_press and see how it sets the label property in the hits object The is just touching upon the concept - the callback mechanism will be handled in more detail in the GladeVCP Programming section. 12.3 Creating and Integrating a Glade user interface 12.3.1 Prerequisite: Glade installation To view or modify Glade UI files, you need glade installed - it is not needed just to run a GladeVCP panel. If the glade command is missing, install it with the command: Integrator Manual V2.5, 2016-05-12 90 / 258 $ sudo apt-get install glade Verify the version number to be greater than 3.6.7: $ glade --version glade3 3.6.7 12.3.2 Running Glade to create a new user interface This section just outlines the initial LinuxCNC-specific steps. For more information and a tutorial on glade, see http://glade.gnome.org. Some glade tips & tricks may also be found on youtube. Either modify an existing UI component by running glade .ui or start a new one by just running the glade command from the shell. • If LinuxCNC was not installed from a package, the LinuxCNC shell environment needs to be set up with . / scripts/rip-environment, otherwise glade won’t find the LinuxCNC-specific widgets. • When asked for unsaved Preferences, just accept the defaults and hit Close. • From Toplevel (left pane), pick Window (first icon) as top level window, which by default will be named window1. Do not change this name - GladeVCP relies on it. • In the left tab, scroll down and expand HAL Python and EMC Actions. • add a container like a HAL_Box or a HAL_Table from HAL Python to the frame • pick and place some elements like LED, button, etc. within a container This will look like so: Integrator Manual V2.5, 2016-05-12 91 / 258 Glade tends to write a lot of messages to the shell window, which mostly can be ignored. Select File→Save as, give it a name like myui.ui and make sure it’s saved as GtkBuilder file (radio button left bottom corner in Save dialog). GladeVCP will also process the older libglade format correctly but there is no point in using it. The convention for GtkBuilder file extension is .ui. 12.3.3 Testing a panel You’re now ready to give it a try (while LinuxCNC, e.g. Axis is running) it with: gladevcp myui.ui GladeVCP creates a HAL component named like the basename of the UI file - myui in this case - unless overriden by the -c option. If running Axis, just try Show HAL configuration and inspect its pins. You might wonder why widgets contained a HAL_Hbox or HAL_Table appear greyed out (inactive). HAL containers have an associated HAL pin which is off by default, which causes all contained widgets to render inactive. A common use case would be to associate these container HAL pins with halui.machine.is-on or one of the halui.mode. signals, to assure some widgets appear active only in a certain state. To just activate a container, execute the HAL command setp gladevcp. 1. 12.3.4 Preparing the HAL command file The suggested way of linking HAL pins in a GladeVCP panel is to collect them in a separate file with extension .hal. This file is passed via the POSTGUI_HALFILE= option in the HAL section of your ini file. Caution Do not add the GladeVCP HAL command file to the Axis [HAL]HALFILE= ini section, this will not have the desired effect - see the following sections. 12.3.5 Integrating into Axis like PyVCP Place the GladeVCP panel in the righthand side panel by specifying the following in the ini file: [DISPLAY] # add GladeVCP panel where PyVCP used to live: GLADEVCP= -u ../gladevcp/hitcounter.py ../gladevcp/manual-example.ui [HAL] # HAL commands for GladeVCP components in a tab must be executed via POSTGUI_HALFILE POSTGUI_HALFILE = ../gladevcp/manual-example.hal [RS274NGC] # gladevcp Demo specific Oword subs live here SUBROUTINE_PATH = ../gladevcp/nc_files/ The HAL component name of a GladeVCP application started with the the GLADEVCP option is fixed: gladevcp. The command line actually run by Axis in the above configuration is as follows: halcmd loadusr -Wn gladevcp gladevcp -c gladevcp -x {XID} This means you may add arbitrary gladevcp options here, as long as they dont collide with the above command line options. Note The [RS274NGC]SUBROUTINE_PATH= option is only set so the example panel will find the Oword subroutine for the MDI Command widget. It might not be needed in your setup. Integrator Manual V2.5, 2016-05-12 12.3.6 92 / 258 Integrating into Axis as a tab next to DRO and Preview To do so, edit your .ini file and add to the DISPLAY and HAL sections of ini file as follows: [DISPLAY] # add GladeVCP panel as a tab next to Preview/DRO: EMBED_TAB_NAME=GladeVCP demo EMBED_TAB_COMMAND=halcmd loadusr -Wn gladevcp gladevcp -c gladevcp -x {XID} -u ../gladevcp/ ←hitcounter.py ../gladevcp/manual-example.ui [HAL] # HAL commands for GladeVCP components in a tab must be executed via POSTGUI_HALFILE POSTGUI_HALFILE = ../gladevcp/manual-example.hal [RS274NGC] # gladevcp Demo specific Oword subs live here SUBROUTINE_PATH = ../gladevcp/nc_files/ Note the halcmd loadusr way of starting the tab command - this assures that POSTGUI_HALFILE will only be run after the HAL component is ready. In rare cases you might run a a command here which uses a tab but does not have an associated HAL component. Such a command can be started without halcmd loadusr, and this signifies to Axis that it does not have to wait for a HAL component since there is none. When changing the component name in the above example, note that the names used in -Wn and -c must be identical. Try it out by running Axis - there should be a new tab called GladeVCP demo near the DRO tab. Select that tab, you should see the example panel nicely fit within Axis. Note Make sure the UI file is the last option passed to GladeVCP in both the GLADEVCP= and EMBED_TAB_COMMAND= statements. 12.3.7 Integrating into Touchy To do add a GladeVCP tab to Touchy, edit your .ini file as follows: [DISPLAY] # add GladeVCP panel as a tab EMBED_TAB_NAME=GladeVCP demo EMBED_TAB_COMMAND=gladevcp -c gladevcp -x {XID} -u ../gladevcp/hitcounter.py -H ../gladevcp ←/gladevcp-touchy.hal ../gladevcp/manual-example.ui [RS274NGC] # gladevcp Demo specific Oword subs live here SUBROUTINE_PATH = ../gladevcp/nc_files/ Note the following differences to the Axis tab setup: • The HAL command file is slightly modified since Touchy does not use the halui components so its signals are not available and some shortcuts have been taken. • there is no POSTGUI_HALFILE= ini option, but passing the HAL command file on the EMBED_TAB_COMMAND= line is ok • the halcmd loaduser -Wn . . . incantation is not needed. Integrator Manual V2.5, 2016-05-12 12.4 93 / 258 GladeVCP command line options See also man gladevcp . These are the gladevcp command line options: Usage: gladevcp [options] myfile.ui Options: -h, --help show this help message and exit -c NAME Set component name to NAME. Default is base name of UI file -d Enable debug output -g GEOMETRY Set geometry WIDTHxHEIGHT+XOFFSET+YOFFSET. Values are in pixel units, XOFFSET/YOFFSET is referenced from top left of screen. Use -g WIDTHxHEIGHT for just setting size or -g +XOFFSET+YOFFSET for just position -H FILE execute hal statements from FILE with halcmd after the component is set up and ready -m MAXIMUM force panel window to maximize. Together with the -g geometry option one can move the panel to a second monitor and force it to use all of the screen -t THEME set gtk theme. Default is system theme. Different panels can have different themes. An example theme can be found in the EMC Wiki. -x XID Re-parent GladeVCP into an existing window XID instead of creating a new top level window -u FILE Use File’s as additional user defined modules with handlers -U USEROPT pass USEROPTs to Python modules 12.5 Understanding the gladeVCP startup process The integration steps outlined above look a bit tricky, and they are. It does therefore help to understand the startup process of LinuxCNC and how this relates to gladeVCP. The normal LinuxCNC startup process does the following: • the realtime environment is started • all HAL components are loaded • the HAL components are linked together through the .hal cmd scripts • task, iocontrol and eventually the user interface is started • pre-gladeVCP the assumption was: by the time the UI starts, all of HAL is loaded, plumbed and ready to go The introduction of gladeVCP brought the following issue: Integrator Manual V2.5, 2016-05-12 94 / 258 • gladeVCP panels need to be embedded in a master GUI window setup, e.g. Axis, or Touchy (embedded window or as an embedded tab) • this requires the master GUI to run before the gladeVCP window can be hooked into the master GUI • however gladeVCP is also a HAL component, and creates HAL pins of its own. • as a consequence, all HAL plumbing involving gladeVCP HAL pins as source or destination must be run after the GUI has been set up This is the purpose of the POSTGUI_HALFILE. This ini option is inspected by the GUIs. If a GUI detects this option, it runs the corresponding HAl file after any embedded gladVCP panel is set up. However, it does not check whether a gladeVCP panel is actually used, in which case the HAL cmd file is just run normally. So if you do NOT start gladeVCP through GLADEVCP or EMBED_TAB etc, but later in a separate shell window or some other mechanism, a HAL command file in POSTGUI_HALFILE will be executed too early. Assuming gladeVCP pins are referenced herein, this will fail with an error message indicating that the gladeVCP HAL component is not available. So, in case you run gladeVCP from a separate shell window (i.e. not started by the GUI in an embedded fashion): • you cannot rely on the POSTGUI_HALFILE ini option causing the HAL commands being run at the right point in time, so comment that out in the ini file • explicitly pass the HAL command file which refers to gladeVCP pins to gladeVCP with the -H option (see previous section). 12.6 HAL Widget reference GladeVcp includes a collection of Gtk widgets with attached HAL pins called HAL Widgets, intended to control, display or otherwise interact with the LinuxCNC HAL layer. They are intended to be used with the Glade user interface editor. With proper installation, the HAL Widgets should show up in Glade’s HAL Python widget group. Many HAL specific fields in the Glade General section have an associated mouse-over tool tip. HAL signals come in two variants, bits and numbers. Bits are off/on signals. Numbers can be "float", "s32" or "u32". For more information on HAL data types see the HAL manual. The GladeVcp widgets can either display the value of the signal with an indicator widget, or modify the signal value with a control widget. Thus there are four classes of GladeVcp widgets that you can connect to a HAL signal. Another class of helper widgets allow you to organize and label your panel. • Widgets for indicating "bit" signals: HAL_LED • Widgets for controlling "bit" signals: HAL_Button HAL_RadioButton HAL_CheckButton • Widgets for indicating "number" signals: HAL_Label, HAL_ProgressBar, HAL_HBar and HAL_VBar, HAL_Meter • Widgets for controlling "number" signals: HAL_SpinButton, HAL_HScale and HAL_VScale • Helper widgets: HAL_HBox and HAL_Table • Tool Path preview: HAL_Gremlin 12.6.1 Widget and HAL pin naming Most HAL widgets have a single associated HAL pin with the same HAL name as the widget (glade: General→Name). Exceptions to this rule currently are. • HAL_Spinbutton and HAL_ComboBox, which have two pins: a -f (float) and a -s (s32) pin • HAL_ProgressBar, which has a -value input pin, and a -scale input pin. Integrator Manual V2.5, 2016-05-12 12.6.2 95 / 258 Python attributes and methods of HAL Widgets HAL widgets are instances of GtKWidgets and hence inherit the methods, properties and signals of the applicable GtkWidget class. For instance, to figure out which GtkWidget-related methods, properties and signals a HAL_Button has, lookup the description of GtkButton in the PyGtk Reference Manual. An easy way to find out the inheritance relationship of a given HAL widget is as follows: run glade, place the widget in a window, and select it; then choose the Signals tab in the Properties window. For example, selecting a HAL_LED widget, this will show that a HAL_LED is derived from a GtkWidget, which in turn is derived from a GtkObject, and eventually a GObject. HAL Widgets also have a few HAL-specific Python attributes: hal_pin the underlying HAL pin Python object in case the widget has a single pin type hal_pin_s, hal_pin_f the S32 and float pins of the HAL_Spinbutton and HAL_ComboBox widgets - note these widgets do not have a hal_pin attribute! hal_pin_scale the float input pin of HAL_ProgressBar widget representing the maximum absolute value of input. The are several HAL-specific methods of HAL Widgets, but the only relevant method is: .get() Retrieve the value of the current HAL pin, where is the applicable HAL pin name listed above. 12.6.3 Setting pin and widget values As a general rule, if you need to set a HAL output widget’s value from Python code, do so by calling the underlying Gtk setter (e.g. set_active(), set_value()) - do not try to set the associated pin’s value by halcomp[pinname] =value directly because the widget will not take notice of the change!. It might be tempting to set HAL widget input pins programmatically. Note this defeats the purpose of an input pin in the first place - it should be linked to, and react to signals generated by other HAL components. While there is currently no write protection on writing to input pins in HAL Python, this doesn’t make sense. You might use setp pinname value in the associated halfile for testing though. It is perfectly OK to set an output HAL pin’s value with halcomp[pinname] =value provided this HAL pin is not associated with a widget, that is, has been created by the hal_glib.GPin(halcomp.newpin( , , ) method (see GladeVCP Programming for an example). 12.6.4 The hal-pin-changed signal Event-driven programming means that the UI tells your code when "something happens" - through a callback, like when a button was pressed. The output HAL widgets (those which display a HAL pin’s value) like LED, Bar, VBar, Meter etc, support the hal-pin-changed signal which may cause a callback into your Python code when - well, a HAL pin changes its value. This means there’s no more need for permanent polling of HAL pin changes in your code, the widgets do that in the background and let you know. Here is an example how to set a hal-pin-changed signal for a HAL_LED in the Glade UI editor: Integrator Manual V2.5, 2016-05-12 96 / 258 The example in configs/gladevcp/examples/complex shows how this is handled in Python. 12.6.5 Buttons This group of widgets are derived from various Gtk buttons and consists of HAL_Button, HAL_ToggleButton, HAL_RadioButton and CheckButton widgets. All of them have a single output BIT pin named identical to the widget. Buttons have no additional properties compared to their base Gtk classes. • HAL_Button: instantaneous action, does not retain state. Important signal: pressed • HAL_ToggleButton, HAL_CheckButton: retains on/off state. Important signal: toggled • HAL_RadioButton: a one-of-many group. Important signal: toggled (per button). • Important common methods: set_active(), get_active() • Important properties: label, image Check button: . Radio buttons: Toggle button: Tip Defining radio button groups in Glade: • decide on default active button • in the other button’s General→Group select the default active button’s name in the Choose a Radio Button in this project dialog. See configs/gladevcp/by-widget/radiobutton for a GladeVCP application and UI file for working with radio buttons. Integrator Manual V2.5, 2016-05-12 12.6.6 97 / 258 Scales HAL_HScale and HAL_VScale are derived from the GtkHScale and GtkVScale respectively. They have one output FLOAT pin with name equal to widget name. Scales have no additional properties. To make a scale useful in Glade, add an Adjustment (General→Adjustment→New or existing adjustment) and edit the adjustment object. It defines the default/min/max/increment values. Also, set adjustment Page size and Page increment to zero to avoid warnings. . Example HAL_HScale: 12.6.7 SpinButton HAL SpinButton is derived from GtkSpinButton and holds two pins: -f out FLOAT pin -s out S32 pin To be useful, Spinbuttons need an adjustment value like scales, see above. Example SpinButton: 12.6.8 . Label HAL_Label is a simple widget based on GtkLabel which represents a HAL pin value in a user-defined format. label_pin_type The pin’s HAL type (0:S32, 1:float, 2:U32), see also the tooltip on ’General→HAL pin type ’(note this is different from PyVCP which has three label widgets, one for each type). text_template Determines the text displayed - a Python format string to convert the pin value to text. Defaults to %s (values are converted by the str() function) but may contain any legit as an argument to Pythons format() method. Example: Distance:%.03f will display the text and the pin value with 3 fractional digits padded with zeros for a FLOAT pin. 12.6.9 Containers: HAL_HBox and HAL_Table Compared to their Gtk counterparts they have one input BIT pin which controls if their child widgets are sensitive or not. If the pin is low then child widgets are inactive which is the default. Tip If you find some part of your GladeVCP application is grayed out (insensitive), see whether a container’s pin is unset. Integrator Manual V2.5, 2016-05-12 12.6.10 98 / 258 LED The hal_led simulates a real indicator LED. It has a single input BIT pin which controls it’s state: ON or OFF. LEDs have several properties which control their look and feel: on_color a String defining ON color of LED. May be any valid gtk.gdk.Color name. Not working on Ubuntu 8.04. off_color String defining OFF color of LED. May be any valid gtk.gdk.Color name or special value dark. dark means that OFF color will be set to 0.4 value of ON color. Not working on Ubuntu 8.04. pick_color_on, pick_color_off Colors for ON and OFF states may be represented as #RRRRGGGGBBBB strings. These are optional properties which have precedence over on_color and off_color. led_size LED radius (for square - half of LED’s side) led_shape LED Shape. Valid values are 0 for round, 1 for oval and 2 for square shapes. led_blink_rate if set and LED is ON then it’s blinking. Blink period is equal to "led_blink_rate" specified in milliseconds. As an input widget, LED also supports the hal-pin-changed signal. If you want to get a notification in your code when the LED’s HAL pin was changed, then connect this signal to a handler, for example on_led_pin_changed and provide the handler as follows: def on_led_pin_changed(self,hal_led,data=None): print "on_led_pin_changed() - HAL pin value:",hal_led.hal_pin.get() This will be called at any edge of the signal and also during program start up to report the current value. Example LEDs: 12.6.11 . ProgressBar Note This widget might go away. Use the HAL_HBar and HAL_VBar widgets instead. The HAL_ProgressBar is derived from gtk.ProgressBar and has two float HAL input pins: the current value to be displayed -scale the maximum absolute value of input It has the following properties: Integrator Manual V2.5, 2016-05-12 99 / 258 scale value scale. set maximum absolute value of input. Same as setting the .scale pin. A float, range from -224 to +2 24. green_limit green zone limit lower limit yellow_limit yellow zone limit lower limit red_limit red zone limit lower limit text_template Text template to display the current value of the pin. Python formatting may be used for dict {"val ue":value} Example HAL_ProgressBar: 12.6.12 . ComboBox HAL_ComboBox is derived from gtk.ComboBox. It enables choice of a value from a dropdown list. It exports two HAL pins: -f the current value, type FLOAT -s the current value, type S32 It has the following property which can be set in Glade: column the column index, type S32, defaults to -1, range from -1..100 . In default mode this widgets sets the pins to the index of the chosen list entry. So if your widget has three labels, it may only assume values 0,1 and 2. In column mode (column > -1), the value reported is chosen from the ListStore array as defined in Glade. So typically your widget definition would have two columns in the ListStore , one with text displayed in the dropdown, and an int or float value to use for that choice. There’s an example in configs/gladevcp/by-widget/combobox/combobox.{py,ui} which uses column mode to pick a float value from the ListStore. If you’re confused like me about how to edit ComboBox ListStores and CellRenderer, see http://www.youtube.com/watch?v=Z5_FrW2cL8. 12.6.13 Bars HAL Bar and VBar widgets for horizontal and vertical bars representing float values. They have one input FLOAT hal pin. Both bars have the following properties: invert Swap min and max direction. An inverted HBar grows from right to left, an inverted VBar from top to bottom. Integrator Manual V2.5, 2016-05-12 100 / 258 min, max Minimum and maximum value of desired range. It is not an error condition if the current value is outside this range. zero Zero point of range. If it’s inside of min/max range then the bar will grow from that value and not from the left (or right) side of the widget. Useful to represent values that may be both positive or negative. force_width, force_height Forced width or height of widget. If not set then size will be deduced from packing or from fixed widget size and bar will fill whole area. text_template Like in Label sets text format for min/max/current values. Can be used to turn off value display. bg_color Background (inactive) color of bar. z0_color, z1_color, z2_color Colors of different value zones. Defaults are green, yellow and red. For description of zones see z*_border properties. z0_border, z1_border Define up bounds of color zones. By default only one zone is enabled. If you want more then one zone set z0_border and z1_border to desired values so zone 0 will fill from 0 to first border, zone 1 will fill from first to second border and zone 2 — from last border to 1. Borders are set as fractions, values from 0 to 1. Horizontal bar: 12.6.14 Vertical bar: . Meter HAL Meter is a widget similar to PyVCP meter - it represents a float value and has one input FLOAT hal pin. HAL Meter has the following properties: min, max Minimum and maximum value of desired range. It is not an error condition if the current value is outside this range. force_size Forced diameter of widget. If not set then size will be deduced from packing or from fixed widget size and meter will fill all available space with respect to aspect ratio. text_template Like in Label sets text format for current value. Can be used to turn off value display. label Large label above center of meter. sublabel Small label below center of meter. bg_color Background color of meter. Integrator Manual V2.5, 2016-05-12 101 / 258 z0_color, z1_color, z2_color Colors of different value zones. Defaults are green, yellow and red. For description of zones see z*_border properties. z0_border, z1_border Define up bounds of color zones. By default only one zone is enabled. If you want more then one zone set z0_border and z1_border to desired values so zone 0 will fill from min to first border, zone 1 will fill from first to second border and zone 2 — from last border to max. Borders are set as values in range min-max. Example HAL Meters: 12.6.15 . Gremlin tool path preview for .ngc files Gremlin is a plot preview widget similar to the Axis preview window. It assumes a running LinuxCNC environment like Axis or Touchy. To connect to it, inspects the INI_FILE_NAME environment variable. Gremlin displays the current .ngc file - it does monitor for changes and reloads the ngc file if the file name in Axis/Touchy changes. If you run it in a GladeVCP application when LinuxCNC is not running, you might get a traceback because the Gremlin widget can’t find LinuxCNC status, like the current file name. Gremlin does not export any HAL pins. It has the following properties: view may be any of x, y, z, p (perspective) . Defaults to z view. enable_dro boolean; whether to draw a DRO on the plot or not. Defaults to True. Integrator Manual V2.5, 2016-05-12 102 / 258 Example: 12.6.16 Animated function diagrams: HAL widgets in a bitmap For some applications it might be desirable to have background image - like a functional diagram - and position widgets at appropriate places in that diagram. A good combination is setting a bitmap background image, like from a .png file, making the gladevcp window fixed-size, and use the glade Fixed widget to position widgets on this image. The code for the below example can be found in configs/gladevcp/animated-backdrop: Integrator Manual V2.5, 2016-05-12 12.7 103 / 258 Action Widgets reference GladeVcp includes a collection of "canned actions" called EMC Action Widgets for the Glade user interface editor. Other than HAL widgets, which interact with HAL pins, EMC Actions interact with LinuxCNC and the G-code interpreter. EMC Action Widgets are derived from the Gtk.Action widget. The Action widget in a nutshell: • it is an object available in Glade • it has no visual appearance by itself • it’s purpose: associate a visible, sensitive UI component like menu, toolbutton, button with a command. See these widget’s General→Related Action property. • the "canned action" will be executed when the associated UI component is triggered (button press, menu click..) • it provides an easy way to execute commands without resorting to Python programming. The appearance of EMC Actions in Glade is roughly as follows: Integrator Manual V2.5, 2016-05-12 104 / 258 Tooltip hovers provide a description. 12.7.1 EMC Action widgets EMC Action widgets are one-shot type widgets. They implement a single action and are for use in simple buttons, menu entries or radio/check groups. 12.7.2 EMC ToggleAction widgets These are bi-modal widgets. They implement two actions or use a second (usually pressed) state to indicate that currently an action is running. Toggle actions are aimed for use in ToggleButtons, ToggleToolButtons or toggling menu items. A simplex example is the ESTOP toggle button. Currently the following widgets are available: • The ESTOP toggle sends ESTOP or ESTOP_RESET commands to LinuxCNC depending on it’s state. • The ON/OFF toggle sends STATE_ON and STATE_OFF commands. • Pause/Resume sends AUTO_PAUSE or AUTO_RESUME commands. The following toggle actions have only one associated command and use the pressed state to indicate that the requested operation is running: • The Run toggle sends an AUTO_RUN command and waits in the pressed state until the interpreter is idle again. • The Stop toggle is inactive until the interpreter enters the active state (is running G-code) and then allows user to send AUTO_ABORT command. • The MDI toggle sends given MDI command and waits for its completion in pressed inactive state. 12.7.3 The Action_MDI Toggle and Action_MDI widgets These widgets provide a means to execute arbitrary MDI commands. The Action_MDI widget does not wait for command completion as the Action_MDI Toggle does, which remains disabled until command complete. 12.7.4 A simple example: Execute MDI command on button press configs/gladevcp/mdi-command-example/whoareyou.ui is a Glade UI file which conveys the basics: Open it in Glade and study how it’s done. Start Axis, and then start this from a terminal window with gladevcp whoare you.ui. See the hal_action_mdi1 Action and it’s MDI command property - this just executes (MSG, "Hi, I’m an EMC_Action_MDI") so there should be a message popup in Axis like so: Integrator Manual V2.5, 2016-05-12 105 / 258 You’ll notice that the button associated with the Action_MDI action is grayed out if the machine is off, in E-Stop or the interpreter is running. It will automatically become active when the machine is turned on and out of E-Stop, and the program is idle. 12.7.5 Parameter passing with Action_MDI and ToggleAction_MDI widgets Optionally, MDI command strings may have parameters substituted before they are passed to the interpreter. Parameters currently may be names of HAL pins in the GladeVCP component. This is how it works: • assume you have a HAL SpinBox named speed, and you want to pass it’s current value as a parameter in an MDI command. • The HAL SpinBox will have a float-type HAL pin named speed-f (see HalWidgets description). • To substitute this value in the MDI command, insert the HAL pin name enclosed like so: ${pin-name} • for the above HAL SpinBox, we could use (MSG, "The speed is:${speed-f}") just to show what’s happening. The example UI file is configs/gladevcp/mdi-command-example/speed.ui. Here’s what you get when running it: 12.7.6 An advanced example: Feeding parameters to an O-word subroutine It’s perfectly OK to call an O-word subroutine in an MDI command, and pass HAL pin values as actual parameters. An example UI file is in configs/gladevcp/mdi-command-example/owordsub.ui. Place configs/gladevcp/nc_files/oword.ngc so Axis can find it, and run gladevcp owordsub.ui from a terminal window. This looks like so: Integrator Manual V2.5, 2016-05-12 12.7.7 106 / 258 Preparing for an MDI Action, and cleaning up afterwards The LinuxCNC G-Code interpreter has a single global set of variables, like feed, spindle speed, relative/absolute mode and others. If you use G code commands or O-word subs, some of these variables might get changed by the command or subroutine - for example, a probing subroutine will very likely set the feed value quite low. With no further precautions, your previous feed setting will be overwritten by the probing subroutine’s value. To deal with this surprising and undesirable side effect of a given O-word subroutine or G-code statement executed with an LinuxCNC ToggleAction_MDI, you might associate pre-MDI and post-MDI handlers with a given LinuxCNC ToggleAction_MDI. These handlers are optional and provide a way to save any state before executing the MDI Action, and to restore it to previous values afterwards. The signal names are mdi-command-start and mdi-command-stop; the handler names can be set in Glade like any other handler. Here’s an example how a feed value might be saved and restored by such handlers (note that LinuxCNC command and status channels are available as self.linuxcnc and self.stat through the EMC_ActionBase class: def on_mdi_command_start(self, action, userdata=None): action.stat.poll() self.start_feed = action.stat.settings[1] def on_mdi_command_stop(self, action, userdata=None): action.linuxcnc.mdi(’F%.1f’ % (self.start_feed)) while action.linuxcnc.wait_complete() == -1: pass Only the Action_MDI Toggle widget supports these signals. Note In a later release of LinuxCNC, the new M-codes M70-M72 are available which make it saving state before a subroutine call, and restoring state on return much easier. 12.7.8 Using the LinuxCNC Stat object to deal with status changes Many actions depend on LinuxCNC status - is it in manual, MDI or auto mode? is a program running, paused or idle? You cannot start an MDI command while a G-code program is running, so this needs to be taken care of. Many LinuxCNC actions take care of this themselves, and related buttons and menu entries are deactivated when the operation is currently impossible. When using Python event handlers - which are at a lower level than Actions - one needs to take care of dealing with status dependencies oneself. For this purpose, there’s the LinuxCNC Stat widget: to associate LinuxCNC status changes with event handlers. Integrator Manual V2.5, 2016-05-12 107 / 258 LinuxCNC Stat has no visible component - you just add it to your UI with Glade. Once added, you can associate handlers with its following signals: • state-related: emitted when E-Stop condition occurs, is reset, machine is turned on, or is turned off – state-estop – state-estop-reset – state-on, – state-off • mode-related: emitted when LinuxCNC enters that particular mode – mode-manual – mode-mdi – mode-auto • interpreter-related: emitted when the G-code interpreter changes into that mode – interp-run – interp-idle – interp-paused – interp-reading – interp-waiting – file-loaded – line-changed 12.8 GladeVCP Programming 12.8.1 User Defined Actions Most widget sets, and their associated user interface editors, support the concept of callbacks - functions in user-written code which are executed when something happens in the UI - events like mouse clicks, characters typed, mouse movement, timer events, window hiding and exposure and so forth. HAL output widgets typically map input-type events like a button press to a value change of the associated HAL pin by means of such a - predefined - callback. Within PyVCP, this is really the only type of event handling supported - doing something more complex, like executing MDI commands to call a G-code subroutine, is not supported. Within GladeVCP, HAL pin changes are just one type of the general class of events (called signals) in GTK+. Most widgets may originate such signals, and the Glade editor supports associating such a signal with a Python method or function name. If you decide to use user-defined actions, your job is to write a Python module whose class methods - or in the simple case, just functions - can be referred to in Glade as event handlers. GladeVCP provides a way to import your module(s) at startup and will automatically link your event handlers with the widget signals as set in the Glade UI description. 12.8.2 An example: adding custom user callbacks in Python This is just a minimal example to convey the idea - details are laid out in the rest of this section. GladeVCP can not only manipulate or display HAL pins, you can also write regular event handlers in Python. This could be used, among others, to execute MDI commands. Here’s how you do it: Write a Python module like so and save as e.g. handlers.py: Integrator Manual V2.5, 2016-05-12 108 / 258 nhits = 0 def on_button_press(gtkobj,data=None): global nhits nhits += 1 gtkobj.set_label("hits: %d" % nhits) In Glade, define a button or HAL button, select the Signals tab, and in the GtkButton properties select the pressed line. Enter on_button_press there, and save the Glade file. Then add the option -u handlers.py to the gladevcp command line. If your event handlers are spread over several files, just add multiple -u options. Now, pressing the button should change its label since it’s set in the callback function. What the -u flag does: all Python functions in this file are collected and setup as potential callback handlers for your Gtk widgets - they can be referenced from Glade Signals tabs. The callback handlers are called with the particular object instance as parameter, like the GtkButton instance above, so you can apply any GtkButton method from there. Or do some more useful stuff, like calling an MDI command! 12.8.3 HAL value change events HAL input widgets, like a LED, automatically associate their HAL pin state (on/off) with the optical appearance of the widget (LED lit/dark). Beyond this builtin functionality, one may associate a change callback with any HAL pin, including those of predefined HAL widgets. This fits nicely with the event-driven structure of a typical widget application: every activity, be it mouse click, key, timer expired, or the change of a HAL pin’s value, generates a callback and is handled by the same orthogonal mechanism. For user-defined HAL pins not associated with a particular HAL widget, the signal name is value-changed. See the Adding HAL pins section below for details. HAL widgets come with a pre-defined signal called hal-pin-changed. See the Hal Widgets section for details. 12.8.4 Programming model The overall approach is as follows: • design your UI with Glade, and set signal handlers where you want actions associated with a widget • write a Python module which contains callable objects (see handler models below) • pass your module’s path name to gladevcp with the -u option • gladevcp imports the module, inspects it for signal handlers and connects them to the widget tree • the main event loop is run. 12.8.4.1 The simple handler model For simple tasks it’s sufficient to define functions named after the Glade signal handlers. These will be called when the corresponding event happens in the widget tree. Here’s a trivial example - it assumes that the pressed signal of a Gtk Button or HAL Button is linked to a callback called on_button_press: nhits = 0 def on_button_press(gtkobj,data=None): global nhits nhits += 1 gtkobj.set_label("hits: %d" % nhits) Add this function to a Python file and run as follows: gladevcp -u .py mygui.ui Note communication between handlers has to go through global variables, which does not scale well and is positively unpythonic. This is why we came up with the class-based handler model. Integrator Manual V2.5, 2016-05-12 12.8.4.2 109 / 258 The class-based handler model The idea here is: handlers are linked to class methods. The underlying class(es) are instantiated and inspected during GladeVCP startup and linked to the widget tree as signal handlers. So the task now is to write: • one or more several class definition(s) with one or several methods, in one module or split over several modules, • a function get_handlers in each module which will return a list of class instances to GladeVCP - their method names will be linked to signal handlers Here is a minimum user-defined handler example module: class MyCallbacks : def on_this_signal(self,obj,data=None): print "this_signal happened, obj=",obj def get_handlers(halcomp,builder,useropts): return [MyCallbacks ()] Now, on_this_signal will be available as signal handler to your widget tree. 12.8.4.3 The get_handlers protocol If during module inspection GladeVCP finds a function get_handlers, it calls it as follows: get_handlers(halcomp,builder,useropts) the arguments are: • halcomp - refers to the HAL component under construction • builder - widget tree - result of reading the UI definition (either referring to a GtkBuilder or libglade-type object) • useropts - a list of strings collected from the gladevcp command line -U option GladeVCP then inspects the list of class instances and retrieves their method names. Qualifying method names are connected to the widget tree as signal handlers. Only method names which do not begin with an _ (underscore) are considered. Note that regardless whether you’re using the libglade or the new GtkBuilder format for your Glade UI, widgets can always be referred to as builder.get_object( ). Also, the complete list of widgets is available as builder. get_objects() regardless of UI format. 12.8.5 Initialization sequence It is important to know in which state of affairs your get_handlers() function is called so you know what is safe to do there and what not. First, modules are imported and initialized in command line order. After successful import, get_handlers() is called in the following state: • the widget tree is created, but not yet realized (no toplevel window.show() has been executed yet) • the halcomp HAL component is set up and all HAL widget’s pins have already been added to it • it is safe to add more HAL pins because halcomp.ready() has not yet been called at this point, so you may add your own pins, for instance in the class __init__() method. Once all modules have been imported and method names extracted, the following steps happen: Integrator Manual V2.5, 2016-05-12 110 / 258 • all qualifying method names will be connected to the widget tree with connect_signals()/signal_autoconnect() (depending on the type of UI imported - GtkBuilder vs the old libglade format). • the HAL component is finalized with halcomp.ready() • if a window ID was passed as argument, the widget tree is re-parented to run in this window, and Glade’s toplevel window1 is abandoned (see FAQ) • if a HAL command file was passed with -H halfile, it is executed with halcmd • the Gtk main loop is run. So when your handler class is initialized, all widgets are existent but not yet realized (displayed on screen). And the HAL component isn’t ready as well, so its unsafe to access pins values in your __init__() method. If you want to have a callback to execute at program start after it is safe to access HAL pins, then a connect a handler to the realize signal of the top level window1 (which might be its only real purpose). At this point GladeVCP is done with all setup tasks, the halfile has been run, and GladeVCP is about to enter the Gtk main loop. 12.8.6 Multiple callbacks with the same name Within a class, method names must be unique. However, it is OK to have multiple class instances passed to GladeVCP by get_handlers() with identically named methods. When the corresponding signal occurs, these methods will be called in definition order - module by module, and within a module, in the order class instances are returned by get_handlers(). 12.8.7 The GladeVCP -U flag Instead of extending GladeVCP for any conceivable option which could potentially be useful for a handler class, you may use the -U flag (repeatedly if you wish). This flag collects a list of strings. This list is passed to the get_handlers() function (useropts argument). Your code is free to interpret these strings as you see fit. An possible usage would be to pass them to the Python exec function in your get_handlers() as follows: debug = 0 ... def get_handlers(halcomp,builder,useropts): ... global debug # assuming there’s a global var for cmd in useropts: exec cmd in globals() This way you can pass arbitrary Python statements to your module through the gladevcp -U option, for example: gladevcp -U debug=42 -U "print ’debug=%d’ % debug" ... This should set debug to 2 and confirm that your module actually did it. 12.8.8 Persistent variables in GladeVCP A annoying aspect of GladeVCP in its earlier form and pyvcp is the fact that you may change values and HAL pins through text entry, sliders, spin boxes, toggle buttons etc, but their settings are not saved and restored at the next run of LinuxCNC - they start at the default value as set in the panel or widget definition. GladeVCP has an easy-to-use mechanism to save and restore the state of HAL widgets, and program variables (in fact any instance attribute of type int, float, bool or string). This mechanism uses the popular .ini file format to save and reload persistent attributes. Integrator Manual V2.5, 2016-05-12 12.8.8.1 111 / 258 Persistence, program versions and the signature check Imagine renaming, adding or deleting widgets in Glade: an .ini file lying around from a previous program version, or an entirely different user interface, would be not be able to restore the state properly since variables and types might have changed. GladeVCP detects this situation by a signature which depends on all object names and types which are saved and to be restored. In the case of signature mismatch, a new .ini file with default settings is generated. 12.8.9 Using persistent variables If you want any of Gtk widget state, HAL widgets output pin’s values and/or class attributes of your handler class to be retained across invocations, proceed as follows: • import the gladevcp.persistence module • decide which instance attributes, and their default values you want to have retained, if any • decide which widgets should have their state retained • describe these decisions in your handler class’ init() method through a nested dictionary as follows: def __init__(self, halcomp,builder,useropts): self.halcomp = halcomp self.builder = builder self.useropts = useropts self.defaults = { # the following names will be saved/restored as method attributes # the save/restore mechanism is strongly typed - the variables type will be derived ←from the type of the # initialization value. Currently supported types are: int, float, bool, string IniFile.vars : { ’nhits’ : 0, ’a’: 1.67, ’d’: True ,’c’ : "a string"}, # to save/restore all widget’s state which might remotely make sense, add this: IniFile.widgets : widget_defaults(builder.get_objects()) # a sensible alternative might be to retain only all HAL output widgets’ state: # IniFile.widgets: widget_defaults(select_widgets(self.builder.get_objects(), ←hal_only=True,output_only = True)), } Then associate an .ini file with this descriptor: self.ini_filename = __name__ + ’.ini’ self.ini = IniFile(self.ini_filename,self.defaults,self.builder) self.ini.restore_state(self) After restore_state(), self will have attributes set if as running the following: self.nhits = 0 self.a = 1.67 self.d = True self.c = "a string" Note that types are saved and preserved on restore. This example assumes that the ini file didn’t exist or had the default values from self.defaults. After this incantation, you can use the following IniFil methods: ini.save_state(obj) saves objs’s attributes as per IniFil.vars dictionary and the widget state as described in IniFile.widgets in self.defaults ini.create_default_ini() create a .ini file with default values ini.restore_state(obj) restore HAL out pins and obj’s attributes as saved/initialized to default as above Integrator Manual V2.5, 2016-05-12 12.8.10 112 / 258 Saving the state on Gladvcp shutdown To save the widget and/or variable state on exit, proceed as follows: • select some interior widget (type is not important, for instance a table). • in the Signals tab, select GtkObject. It should show a destroy signal in the first column. • add the handler name, e.g. on_destroy to the second column. • add a Python handler like below: import gtk ... def on_destroy(self,obj,data=None): self.ini.save_state(self) This will save state and shutdown GladeVCP properly, regardless whether the panel is embedded in Axis, or a standalone window. Caution Do not use window1 (the toplevel window) to connect a destroy event. Due to the way a GladeVCP panel interacts with Axis if a panel is embedded within Axis, window1 will not receive destroy events properly. However, since on shutdown all widgets are destroyed, anyone will do. Recommended: use a second-level widget - for instance, if you have a table container in your panel, use that. Next time you start the GladeVCP application, the widgets should come up in the state when the application was closed. Caution The GtkWidget line has a similarly sounding destroy-event - dont use that to connect to the on_destroy handler, it wont work - make sure you use the destroy event from the GtkObject line. 12.8.11 Saving state when Ctrl-C is pressed By default, the reaction of GladeVCP to a Ctrl-C event is to just exit - without saving state. To make sure that this case is covered, add a handler call on_unix_signal which will be automatically be called on Ctrl-C (actuall on the SIGINT and SIGTERM signals). Example def on_unix_signal(self,signum,stack_frame): print "on_unix_signal(): signal %d received, saving state" % (signum) self.ini.save_state(self) 12.8.12 Hand-editing .ini files You can do that, but note that the values in self.defaults override your edits if there is a syntax or type error in your edit. The error is detected, a console message will hint about that happened, and the bad inifile will be renamed to have the .BAD suffix. Subsequent bad ini files overwrite earlier .BAD files. Integrator Manual V2.5, 2016-05-12 12.8.13 113 / 258 Adding HAL pins If you need HAL pins which are not associated with a specific HAL widget, add them as follows: import hal_glib ... # in your handler class __init__(): self.example_trigger = hal_glib.GPin(halcomp.newpin(’example-trigger’, hal.HAL_BIT, hal. ←HAL_IN)) To get a callback when this pin’s value changes, associate a value-change callback with this pin, add: self.example_trigger.connect(’value-changed’, self._on_example_trigger_change) and define a callback method (or function, in this case leave out the self parameter): # note ’_’ - this method will not be visible to the widget tree def _on_example_trigger_change(self,pin,userdata=None): print "pin value changed to:" % (pin.get()) 12.8.14 Adding timers Since GladeVCP uses Gtk widgets which rely on the GObject base class, the full glib functionally is available. Here is an example for a timer callback: def _on_timer_tick(self,userdata=None): ... return True # to restart the timer; return False for on-shot ... # demonstrate a slow background timer - granularity is one second # for a faster timer (granularity 1 ms), use this: # glib.timeout_add(100, self._on_timer_tick,userdata) # 10Hz glib.timeout_add_seconds(1, self._on_timer_tick) 12.8.15 Setting HAL widget properties programmatically With glade, widget properties are typically set fixed while editing. You can, however, set widget properties at runtime, for instance from ini file values, which would typically be done in the handler initialisation code. Setting properties from HAL pin values is possible, too. In the following example (assuming a HAL Meter widget called meter), the meter’s min value is set from an INI file parameter at startup, and the max value is set via a HAL pin, which causese the widget’s scale to readjust dynamically: import import import import linuxcnc os hal hal_glib class HandlerClass: def _on_max_value_change(self,hal_pin,data=None): self.meter.max = float(hal_pin.get()) self.meter.queue_draw() # force a widget redraw def __init__(self, halcomp,builder,useropts): self.builder = builder # hal pin with change callback. # When the pin’s value changes the callback is executed. Integrator Manual V2.5, 2016-05-12 114 / 258 self.max_value = hal_glib.GPin(halcomp.newpin(’max-value’, hal.HAL_FLOAT, hal. ←HAL_IN)) self.max_value.connect(’value-changed’, self._on_max_value_change) inifile = linuxcnc.ini(os.getenv("INI_FILE_NAME")) mmin = float(inifile.find("METER", "MIN") or 0.0) self.meter = self.builder.get_object(’meter’) self.meter.min = mmin def get_handlers(halcomp,builder,useropts): return [HandlerClass(halcomp,builder,useropts)] 12.8.16 Examples, and rolling your own GladeVCP application Visit linuxcnc/configs/gladevcp for running examples and starters for your own projects. 12.9 FAQ 1. I get an unexpected unmap event in my handler function right after startup. What’s this? This is a consequence of your Glade UI file having the window1 Visible property set to True, together with re-parenting the GladeVCP window into Axis or touchy. The GladeVCP widget tree is created, including a top level window, and then reparented into Axis, leaving that toplevel window laying around orphaned. To avoid having this useless empty window hanging around, it is unmapped (made invisible), which is the cause of the unmap signal you get. Suggested fix: set window1.visible to False, and ignore an initial unmap event. 2. My GladeVCP program starts, but no window appears where I expect it to be? The window Axis allocates for GladeVCP will obtain the natural size of all its child widgets combined. It’s the child widget’s job to request a size (width and/or height). However, not all widgets do request a width greater than 0, for instance the Graph widget in its current form. If there’s such a widget in your Glade file and it’s the one which defines the layout you might want to set its width explicitly. Note that setting the window1 width and height properties in Glade does not make sense because this window will be orphaned during re-parenting and hence its geometry will have no impact on layout (see above). The general rule is: if you manually run a UI file with gladevcp and its window has reasonable geometry, it should come up in Axis properly as well. 3. I want a blinking LED, but it wont blink I ticked the checkbutton to let it blink with 100msec interval. It wont blink, and I get a startup warning: Warning: value "0" of type ‘gint’ is invalid or out of range for property ‘led-blink-rate’ of type ‘gint’? This seems to be a glade bug. Just type over the blink rate field, and save again - this works for me. 4. My gladevcp panel in Axis doesnt save state when I close Axis, although I defined an on_destroy handler linked to the window destroy signal Very likely this handler is linked to window1, which due to reparenting isnt usable for this purpose. Please link the on_destroy handler to the destroy signal of an interior window. For instance, I have a notebook inside window1, and linked on_destroy to the notebooks destroy signal, and that works fine. It doesnt work for window1. 5. I want to set the background color or text of a HAL_Label widget depending on its HAL pin value See the example in configs/gladevcp/colored-label. Setting the background color of a GtkLabel widget (and HAL_Label is derived from GtkLabel) is a bit tricky. The GtkLabel widget has no window object of its own for performance reasons, and only window objects can have a background color. The solution is to enclose the Label in an EventBox container, which has a window but is otherwise invisible - see the coloredlabel.ui file. 6. I defined a hal_spinbutton widget in glade, and set a default value property in the corresponding adjustment. It comes up with zero? Integrator Manual V2.5, 2016-05-12 115 / 258 this is due to a bug in the old Gtk version distributed with Ubuntu 8.04 and 10.04, and is likely to be the case for all widgets using adjustment. The workaround mentione for instance in http://osdir.com/ml/gtk-app-devel-list/2010-04/msg00129.html does not reliably set the HAL pin value, it is better to set it explicitly in an on_realize signal handler during widget creation. See the example in configs/gladevcp/by-widget/spinbutton. 12.10 Troubleshooting • make sure you have the development version of LinuxCNC installed. You don’t need the axisrc file any more, this was mentioned in the old GladeVcp wiki page. • run GladeVCP or Axis from a terminal window. If you get Python errors, check whether there’s still a /usr/lib/python2. 6/dist-packages/hal.so file lying around besides the newer /usr/lib/python2.6/dist-packages/_hal. so (note underscore); if yes, remove the hal.so file. It has been superseded by hal.py in the same directory and confuses the import mechanism. • if you’re using run-in-place, do a make clean to remove any accidentally left over hal.so file, then make. • if you’re using HAL_table or HAL_HBox widgets, be aware they have an HAL pin associated with it which is off by default. This pin controls whether these container’s children are active or not. 12.11 Implementation note: Key handling in Axis We believe key handling works OK, but since it is new code, we’re telling about it you so you can watch out for problems; please let us know of errors or odd behavior. This is the story: Axis uses the TkInter widget set. GladeVCP applications use Gtk widgets and run in a separate process context. They are hooked into Axis with the Xembed protocol. This allows a child application like GladeVCP to properly fit in a parent’s window, and - in theory - have integrated event handling. However, this assumes that both parent and child application properly support the Xembed protocol, which Gtk does, but TkInter doesn’t. A consequence of this is that certain keys would not be forwarded from a GladeVCP panel to Axis properly under all circumstances. One of these situations was the case when an Entry, or SpinButton widget had focus: in this case, for instance an Escape key would not have been forwarded to Axis and cause an abort as it should, with potentially disastrous consequences. Therefore, key events in GladeVCP are explicitly handled, and selectively forwarded to Axis, to assure that such situations cannot arise. For details, see the keyboard_forward() function in lib/python/gladevcp/xembed.py. 12.12 Adding Custom Widgets The LinuxCNC Wiki has information on adding custom widgets to GladeVCP. GladeVCP Custom Widgets Integrator Manual V2.5, 2016-05-12 116 / 258 Chapter 13 HAL User Interface 13.1 Introduction Halui is a HAL based user interface for LinuxCNC, it connects HAL pins to NML commands. Most of the functionality (buttons, indicators etc.) that is provided by a traditional GUI (mini, Axis, etc.), is provided by HAL pins in Halui. The easiest way to add halui is to add the following to the [HAL] section of the ini file. HALUI = halui An alternate way to invoke it is to include the following in your .hal file. Make sure you use the actual path to your ini file. loadusr halui -ini /path/to/inifile.ini 13.2 Halui pin reference A BORT • halui.abort (bit, in) - pin to send an abort message (clears out most errors) A XIS • halui.axis.n.pos-commanded (float, out) - Commanded axis position in machine coordinates • halui.axis.n.pos-feedback (float, out) - Feedback axis position in machine coordinates • halui.axis.n.pos-relative (float, out) - Commanded axis position in relative coordinates E-S TOP • halui.estop.activate (bit, in) - pin for requesting E-Stop • halui.estop.is-activated (bit, out) - indicates E-stop reset • halui.estop.reset (bit, in) - pin for requesting E-Stop reset F EED OVERRIDE • halui.feed-override.count-enable (bit, in) - must be true for counts or direct-value to work. Integrator Manual V2.5, 2016-05-12 117 / 258 • halui.feed-override.counts (s32, in) - counts * scale = FO percentage. Can be used with an encoder or direct-value. • halui.feed-override.decrease (bit, in) - pin for decreasing the FO (-=scale) • halui.feed-override.increase (bit, in) - pin for increasing the FO (+=scale) • halui.feed-override.direct-value (bit, in) - false when using encoder to change counts, true when setting counts directly. The count-enable pin must be true. • halui.feed-override.scale (float, in) - pin for setting the scale for increase and decrease of feed-override. • halui.feed-override.value (float, out) - current FO value M IST • halui.mist.is-on (bit, out) - indicates mist is on • halui.mist.off (bit, in) - pin for requesting mist off • halui.mist.on (bit, in) - pin for requesting mist on F LOOD • halui.flood.is-on (bit, out) - indicates flood is on • halui.flood.off (bit, in) - pin for requesting flood off • halui.flood.on (bit, in) - pin for requesting flood on H OMING • halui.home-all (bit, in) - pin for requesting all axis to home. This pin will only be there if HOME_SEQUENCE is set in the ini file. Jog is a number between 0 and 8 and selected. • halui.jog-deadband (float, in) - deadband for analog jogging (smaller jogging speed requests are not performed) • halui.jog-speed (float, in) - pin for setting jog speed for minus/plus jogging • halui.jog. .analog (float, in) - analog velocity input for jogging (useful with joysticks or other analog devices) • halui.jog. .increment (float,in) - pin for setting the jog increment for axis when using increment-minus or incrementplus to jog. • halui.jog. .increment-minus (bit, in) - pin for moving the axis one increment in the minus direction for each off to on transition. • halui.jog. .increment-plus (bit, in) - pin for moving the axis one increment in the plus direction for each off to on transition. • halui.jog. .minus (bit, in) - pin for jogging axis in negative direction at the halui.jog.speed velocity • halui.jog. .plus (bit, in) - pin for jogging axis in positive direction at the halui.jog.speed velocity • halui.jog.selected.increment (float,in) - pin for setting the jog increment for the selected axis when using increment-minus or incremet-plus to jog. • halui.jog.selected.increment-minus (bit, in) - pin for moving the selected axis one increment in the minus direction for each off to on transition. • halui.jog.selected.increment-plus (bit, in) - pin for moving the selected axis one increment in the plus direction for each off to on transition. Integrator Manual V2.5, 2016-05-12 118 / 258 • halui.jog.selected.minus (bit, in) - pin for jogging the selected axis in negative direction at the halui.jog.speed velocity • halui.jog.selected.plus (bit, in) - pin for jogging the selected axis in positive direction at the halui.jog.speed velocity Joint is a number between 0 and 8 and selected. • halui.joint. .has-fault (bit, out) - status pin telling the joint has a fault • halui.joint. .home (bit, in) - pin for homing the specific joint • halui.joint. .is-homed (bit, out) - status pin telling that the joint is homed • halui.joint. .is-selected bit (bit, out) - status pin a joint is selected* internal halui • halui.joint. .on-hard-max-limit (bit, out) - status pin telling joint is on the positive hardware limit switch • halui.joint. .on-hard-min-limit (bit, out) - status pin telling joint is on the negative hardware limit switch • halui.joint. .on-soft-max-limit (bit, out) - status pin telling joint is at the positive software limit • halui.joint. .on-soft-min-limit (bit, out) - status pin telling joint is at the negative software limit • halui.joint. .select (bit, in) - select joint (0..8) - internal halui • halui.joint. .unhome (bit, in) - unhomes this joint • halui.joint.selected (u32, out) - selected joint (0..8) - internal halui • halui.joint.selected.has-fault (bit, out) - status pin telling that the joint has a fault • halui.joint.selected.home (bit, in) - pin for homing the selected joint • halui.joint.selected.is-homed (bit, out) - status pin telling that the selected joint is homed • halui.joint.selected.on-hard-max-limit (bit, out) - status pin telling that the selected joint is on the positive hardware limit • halui.joint.selected.on-hard-min-limit (bit, out) - status pin telling that the selected joint is on the negative hardware limit • halui.joint.selected.on-soft-max-limit (bit, out) - status pin telling that the selected joint is on the positive software limit • halui.joint.selected.on-soft-min-limit (bit, out) - status pin telling that the selected joint is on the negative software limit • halui.joint.selected.unhome (bit, in) - pin for unhoming the selected joint. L UBE • halui.lube.is-on (bit, out) - indicates lube is on • halui.lube.off (bit, in) - pin for requesting lube off • halui.lube.on (bit, in) - pin for requesting lube on M ACHINE • halui.machine.is-on (bit, out) - indicates machine on • halui.machine.off (bit, in) - pin for requesting machine off • halui.machine.on (bit, in) - pin for requesting machine on Max Velocity The maximum linear velocity can be adjusted from 0 to the MAX_VELOCITY that is set in the [TRAJ] section of the ini file. • halui.max-velocity.count-enable (bit, in) - must be true for counts or direct-value to work. Integrator Manual V2.5, 2016-05-12 119 / 258 • halui.max-velocity.counts (s32, in) - counts * scale = MV percentage. Can be used with an encoder or direct-value. • halui.max-velocity.direct-value (bit, in) - false when using encoder to change counts, true when setting counts directly. The count-enable pin must be true. • halui.max-velocity.decrease (bit, in) - pin for decreasing max velocity • halui.max-velocity.increase (bit, in) - pin for increasing max velocity • halui.max-velocity.scale (float, in) - the amount applied to the current maximum velocity with each transition from off to on of the increase or decrease pin in machine units per second. • halui.max-velocity.value (float, out) - is the maximum linear velocity in machine units per second. MDI Sometimes the user wants to add more complicated tasks to be performed by the activation of a HAL pin. This is possible using the following MDI commands scheme: • The MDI_COMMAND is added to the ini file in the [HALUI] section. [HALUI] MDI_COMMAND = G0 X0 • When halui starts it will read the MDI_COMMAND fields in the ini, and export pins from 00 to the number of MDI_COMMAND’s found in the ini up to a maximum of 64 commands. • halui.mdi-command- (bit, in) - halui will try to send the MDI command defined in the ini. This will not always succeed, depending on the operating mode LinuxCNC is in (e.g. while in AUTO halui can’t successfully send MDI commands). If the command succeeds then it will place LinuxCNC in the MDI mode and then back to Manual mode. J OINT S ELECTION • halui.joint.select (u32, in) - select joint (0..8) - internal halui • halui.joint.selected (u32, out) - joint (0..8) selected* internal halui • halui.joint.x.select bit (bit, in) - pins for selecting a joint* internal halui • halui.joint.x.is-selected bit (bit, out) - indicates joint selected* internal halui M ODE • halui.mode.auto (bit, in) - pin for requesting auto mode • halui.mode.is-auto (bit, out) - indicates auto mode is on • halui.mode.is-joint (bit, out) - indicates joint by joint jog mode is on • halui.mode.is-manual (bit, out) - indicates manual mode is on • halui.mode.is-mdi (bit, out) - indicates mdi mode is on • halui.mode.is-teleop (bit, out) - indicates coordinated jog mode is on • halui.mode.joint (bit, in) - pin for requesting joint by joint jog mode • halui.mode.manual (bit, in) - pin for requesting manual mode • halui.mode.mdi (bit, in) - pin for requesting mdi mode • halui.mode.teleop (bit, in) - pin for requesting coordinated jog mode Integrator Manual V2.5, 2016-05-12 120 / 258 P ROGRAM • halui.program.block-delete.is-on (bit, out) - status pin telling that block delete is on • halui.program.block-delete.off (bit, in) - pin for requesting that block delete is off • halui.program.block-delete.on (bit, in) - pin for requesting that block delete is on • halui.program.is-idle (bit, out) - status pin telling that no program is running • halui.program.is-paused (bit, out) - status pin telling that a program is paused • halui.program.is-running (bit, out) - status pin telling that a program is running • halui.program.optional-stop.is-on (bit, out) - status pin telling that the optional stop is on • halui.program.optional-stop.off (bit, in) - pin requesting that the optional stop is off • halui.program.optional-stop.on (bit, in) - pin requesting that the optional stop is on • halui.program.pause (bit, in) - pin for pausing a program • halui.program.resume (bit, in) - pin for resuming a paused program • halui.program.run (bit, in) - pin for running a program • halui.program.step (bit, in) - pin for stepping in a program • halui.program.stop (bit, in) - pin for stopping a program S PINDLE OVERRIDE • halui.spindle-override.count-enable (bit, in) - must be true for counts or direct-value to work. • halui.spindle-override.counts (s32, in) - counts * scale = SO percentage • halui.spindle-override.decrease (bit, in) - pin for decreasing the SO (-=scale) • halui.spindle-override.direct-value (bit, in) - false when using encoder to change counts, true when setting counts directly. The count-enable pin must be true. • halui.spindle-override.increase (bit, in) - pin for increasing the SO (+=scale) • halui.spindle-override.scale (float, in) - pin for setting the scale on changing the SO • halui.spindle-override.value (float, out) - current SO value S PINDLE • halui.spindle.brake-is-on (bit, out) - indicates brake is on • halui.spindle.brake-off (bit, in) - pin for deactivating spindle/brake • halui.spindle.brake-on (bit, in) - pin for activating spindle-brake • halui.spindle.decrease (bit, in) - decreases spindle speed • halui.spindle.forward (bit, in) - starts the spindle with CW motion • halui.spindle.increase (bit, in)- increases spindle speed • halui.spindle.is-on (bit, out) - indicates spindle is on (either direction) • halui.spindle.reverse (bit, in)- starts the spindle with a CCW motion • halui.spindle.runs-backward (bit, out) - indicates spindle is on, and in reverse Integrator Manual V2.5, 2016-05-12 • halui.spindle.runs-forward (bit, out) - indicates spindle is on, and in forward • halui.spindle.start (bit, in) - starts the spindle • halui.spindle.stop (bit, in) - stops the spindle T OOL • halui.tool.length-offset (float, out) - indicates current applied tool-length-offset • halui.tool.number (u32, out) - indicates current selected tool 121 / 258 Integrator Manual V2.5, 2016-05-12 122 / 258 Chapter 14 Halui Examples For any Halui examples to work you need to add the following line to the [HAL] section of the ini file. HALUI = halui 14.1 Remote Start To connect a remote program start button to LinuxCNC you use the halui.program.run pin and the halui.mode. auto pin. You have to insure that it is OK to run first by using the halui.mode.is-auto pin. You do this with an and2 component. The following figure shows how this is done. When the Remote Run Button is pressed it is connected to both halui.mode.auto and and2.0.in0. If it is OK for auto mode the pin halui.mode.is-auto will be on. If both the inputs to the and2.0 component are on the and2.0.out will be on and this will start the program. Figure 14.1: Remote Start Example The hal commands needed to accomplish the above are: Integrator Manual V2.5, 2016-05-12 123 / 258 net program-start-btn halui.mode.auto and2.0.in0 <= net program-run-ok and2.0.in1 <= halui.mode.is-auto net remote-program-run halui.program.run <= and2.0.out Notice on line one that there are two reader pins, this can also be split up to two lines like this: net program-start-btn halui.mode.auto <= net program-start-btn and2.0.in0 14.2 Pause & Resume This example was developed to allow LinuxCNC to move a rotary axis on a signal from an external machine. The coordination between the two systems will be provided by two Halui components: • halui.program.is-paused • halui.program.resume In your customized hal file, add the following two lines that will be connected to your I/O to turn on the program pause or to resume when the external system wants LinuxCNC to continue. net ispaused halui.program.is paused => "your output pin" net resume halui.program.resume <= "your input pin" Your input and output pins are connected to the pins wired to the other controller. They may be parallel port pins or any other I/O pins that you have access to. This system works in the following way. When an M0 is encountered in your G-code, the halui.program.is-paused signal goes true. This turns on your output pin so that the external controller knows that LinuxCNC is paused. To resume the LinuxCNC gcode program, when the external controller is ready it will make its output true. This will signal LinuxCNC that it should resume executing Gcode. Difficulties in timing • The "resume" input return signal should not be longer than the time required to get the g-code running again. • The "is-paused" output should no longer be active by the time the "resume" signal ends. These timing problems could be avoided by using ClassicLadder to activate the "is-paused" output via a monostable timer to deliver one narrow output pulse. The "resume" pulse could also be received via a monostable timer. Integrator Manual V2.5, 2016-05-12 124 / 258 Part IV Hardware Drivers Integrator Manual V2.5, 2016-05-12 125 / 258 Chapter 15 Parallel Port Driver 15.1 Parport Parport is a driver for the traditional PC parallel port. The port has a total of 17 physical pins. The original parallel port divided those pins into three groups: data, control, and status. The data group consists of 8 output pins, the control group consists of 4 pins, and the status group consists of 5 input pins. In the early 1990’s, the bidirectional parallel port was introduced, which allows the data group to be used for output or input. The HAL driver supports the bidirectional port, and allows the user to set the data group as either input or output. If configured as output, a port provides a total of 12 outputs and 5 inputs. If configured as input, it provides 4 outputs and 13 inputs. In some parallel ports, the control group pins are open collectors, which may also be driven low by an external gate. On a board with open collector control pins, the x mode allows a more flexible mode with 8 outputs, and 9 inputs. In other parallel ports, the control group has push-pull drivers and cannot be used as an input. HAL and Open Collectors HAL cannot automatically determine if the x mode bidirectional pins are actually open collectors (OC). If they are not, they cannot be used as inputs, and attempting to drive them LOW from an external source can damage the hardware. To determine whether your port has open collector pins, load hal_parport in x mode. With no device attached, HAL should read the pin as TRUE. Next, insert a 470 ohm resistor from one of the control pins to GND. If the resulting voltage on the control pin is close to 0V, and HAL now reads the pin as FALSE, then you have an OC port. If the resulting voltage is far from 0V, or HAL does not read the pin as FALSE, then your port cannot be used in x mode. The external hardware that drives the control pins should also use open collector gates (e.g., 74LS05). On some machines, BIOS settings may affect whether x mode can be used. SPP mode is most likely to work. No other combinations are supported, and a port cannot be changed from input to output once the driver is installed. The Parport Block Diagram shows two block diagrams, one showing the driver when the data group is configured for output, and one showing it configured for input. For x mode, refer to the pin listing of halcmd show pin for pin direction assignment. The parport driver can control up to 8 ports (defined by MAX_PORTS in hal_parport.c). The ports are numbered starting at zero. 15.1.1 Installing loadrt hal_parport cfg=" " Using the Port Index I/O addresses below 16 are treated as port indexes. This is the simplest way to install the parport driver and cooperates with the Linux parport_pc driver if it is loaded. This will use the address Linux has detected for parport 0. loadrt hal_parport cfg="0" Integrator Manual V2.5, 2016-05-12 126 / 258 Using the Port Address The configure string consists of a hex port address, followed by an optional direction, repeated for each port. The direction is in, out, or x and determines the direction of the physical pins 2 through 9, and whether to create input HAL pins for the physical control pins. If the direction is not specified, the data group defaults to output. For example: loadrt hal_parport cfg="0x278 0x378 in 0x20A0 out" This example installs drivers for one port at 0x0278, with pins 2-9 as outputs (by default, since neither in nor out was specified), one at 0x0378, with pins 2-9 as inputs, and one at 0x20A0, with pins 2-9 explicitly specified as outputs. Note that you must know the base address of the parallel port to properly configure the driver. For ISA bus ports, this is usually not a problem, since the port is almost always at a well known address, like 0278 or 0378 which is typically configured in the system BIOS. The address for a PCI card is usually shown in lspci -v in an I/O ports line, or in the kernel message log after executing sudo modprobe -a parport_pc. There is no default address; if does not contain at least one address, it is an error. Figure 15.1: Parport Block Diagram 15.1.2 Pins • parport. .pin-
-out (bit) Drives a physical output pin. • parport. .pin-
-in (bit) Tracks a physical input pin. • parport. .pin-
-in-not (bit) Tracks a physical input pin, but inverted. Integrator Manual V2.5, 2016-05-12 127 / 258 For each pin, is the port number, and
is the physical pin number in the 25 pin D-shell connector. For each physical output pin, the driver creates a single HAL pin, for example: parport.0.pin-14-out. Pins 2 through 9 are part of the data group and are output pins if the port is defined as an output port. (Output is the default.) Pins 1, 14, 16, and 17 are outputs in all modes. These HAL pins control the state of the corresponding physical pins. For each physical input pin, the driver creates two HAL pins, for example: parport.0.pin-12-in and parport.0.pin-12-in-not. Pins 10, 11, 12, 13, and 15 are always input pins. Pins 2 through 9 are input pins only if the port is defined as an input port. The -in HAL pin is TRUE if the physical pin is high, and FALSE if the physical pin is low. The -in-not HAL pin is inverted — it is FALSE if the physical pin is high. By connecting a signal to one or the other, the user can determine the state of the input. In x mode, pins 1, 14, 16, and 17 are also input pins. 15.1.3 Parameters • parport. .pin-
-out-invert (bit) Inverts an output pin. • parport. .pin-
-out-reset (bit) (only for out pins) TRUE if this pin should be reset when the -reset function is executed. • parport. .reset-time’ (U32) The time (in nanoseconds) between a pin is set by write and reset by the reset function if it is enabled. The -invert parameter determines whether an output pin is active high or active low. If -invert is FALSE, setting the HAL -out pin TRUE drives the physical pin high, and FALSE drives it low. If -invert is TRUE, then setting the HAL -out pin TRUE will drive the physical pin low. 15.1.4 Functions • parport.
.read (funct) Reads physical input pins of port
and updates HAL -in and -in-not pins. • parport.read-all (funct) Reads physical input pins of all ports and updates HAL -in and -in-not pins. • parport. .write (funct) Reads HAL -out pins of port
and updates that port’s physical output pins. • parport.write-all (funct) Reads HAL -out pins of all ports and updates all physical output pins. • parport.
.reset (funct) Waits until reset-time has elapsed since the associated write, then resets pins to values indicated by -out-invert and -out-invert settings. reset must be later in the same thread as write. ’If ’-reset is TRUE, then the reset function will set the pin to the value of -out-invert. This can be used in conjunction with stepgen’s doublefreq to produce one step per period. The stepgen stepspace for that pin must be set to 0 to enable doublefreq. The individual functions are provided for situations where one port needs to be updated in a very fast thread, but other ports can be updated in a slower thread to save CPU time. It is probably not a good idea to use both an -all function and an individual function at the same time. 15.1.5 Common problems If loading the module reports insmod: error inserting ’/home/jepler/emc2/rtlib/hal_parport.ko’: -1 Device or resource busy then ensure that the standard kernel module parport_pc is not loaded1 and that no other device in the system has claimed the I/O ports. If the module loads but does not appear to function, then the port address is incorrect or the probe_parport module is required. 1 In the LinuxCNC packages for Ubuntu, the file /etc/modprobe.d/emc2 generally prevents parport_pc from being automatically loaded. Integrator Manual V2.5, 2016-05-12 15.1.6 128 / 258 Using DoubleStep To setup DoubleStep on the parallel port you must add the function parport.n.reset after parport.n.write and configure stepspace to 0 and the reset time wanted. So that step can be asserted on every period in HAL and then toggled off by parport after being asserted for time specificed by parport.n.reset-time. For example: loadrt hal_parport cfg="0x378 out" setp parport.0.reset-time 5000 loadrt stepgen step_type=0,0,0 addf parport.0.read base-thread addf stepgen.make-pulses base-thread addf parport.0.write base-thread addf parport.0.reset base-thread addf stepgen.capture-position servo-thread ... setp stepgen.0.steplen 1 setp stepgen.0.stepspace 0 More information on DoubleStep can be found on the wiki. 15.2 probe_parport In modern PCs, the parallel port may require plug and play (PNP) configuration before it can be used. The probe_parport module performs configuration of any PNP ports present, and should be loaded before hal_parport. On machines without PNP ports, it may be loaded but has no effect. 15.2.1 Installing loadrt probe_parport loadrt hal_parport ... If the Linux kernel prints a message similar to parport: PnPBIOS parport detected. when the parport_pc module is loaded (sudo modprobe -a parport_pc; sudo rmmod parport_pc) then use of this module is probably required. Integrator Manual V2.5, 2016-05-12 129 / 258 Chapter 16 AX5214H Driver The Axiom Measurement & Control AX5214H is a 48 channel digital I/O board. It plugs into an ISA bus, and resembles a pair of 8255 chips. In fact it may be a pair of 8255 chips, but I’m not sure. If/when someone starts a driver for an 8255 they should look at the ax5214 code, much of the work is already done. 16.1 Installing loadrt hal_ax5214h cfg="
" The config string consists of a hex port address, followed by an 8 character string of "I" and "O" which sets groups of pins as inputs and outputs. The first two character set the direction of the first two 8 bit blocks of pins (0-7 and 8-15). The next two set blocks of 4 pins (16-19 and 20-23). The pattern then repeats, two more blocks of 8 bits (24-31 and 32-39) and two blocks of 4 bits (40-43 and 44-47). If more than one board is installed, the data for the second board follows the first. As an example, the string "0x220 IIIOIIOO 0x300 OIOOIOIO" installs drivers for two boards. The first board is at address 0x220, and has 36 inputs (0-19 and 24-39) and 12 outputs (20-23 and 40-47). The second board is at address 0x300, and has 20 inputs (8-15, 24-31, and 40-43) and 28 outputs (0-7. 16-23, 32-39, and 44-47). Up to 8 boards may be used in one system. 16.2 Pins • (bit) ax5214. .out- — Drives a physical output pin. • (bit) ax5214. .in- — Tracks a physical input pin. • (bit) ax5214. .in- -not — Tracks a physical input pin, inverted. For each pin, is the board number (starts at zero), and is the I/O channel number (0 to 47). Note that the driver assumes active LOW signals. This is so that modules such as OPTO-22 will work correctly (TRUE means output ON, or input energized). If the signals are being used directly without buffering or isolation the inversion needs to be accounted for. The in- HAL pin is TRUE if the physical pin is low (OPTO-22 module energized), and FALSE if the physical pin is high (OPTO-22 module off). The in- -not HAL pin is inverted — it is FALSE if the physical pin is low (OPTO-22 module energized). By connecting a signal to one or the other, the user can determine the state of the input. 16.3 Parameters • (bit) ax5214. .out- -invert — Inverts an output pin. Integrator Manual V2.5, 2016-05-12 130 / 258 The -invert parameter determines whether an output pin is active high or active low. If -invert is FALSE, setting the HAL outpin TRUE drives the physical pin low, turning ON an attached OPTO-22 module, and FALSE drives it high, turning OFF the OPTO-22 module. If -invert is TRUE, then setting the HAL out- pin TRUE will drive the physical pin high and turn the module OFF. 16.4 Functions • (funct) ax5214. .read — Reads all digital inputs on one board. • (funct) ax5214. .write — Writes all digital outputs on one board. Integrator Manual V2.5, 2016-05-12 131 / 258 Chapter 17 GS2 VFD Driver This is a userspace HAL program for the GS2 series of VFD’s at Automation Direct. This component is loaded using the halcmd "loadusr" command: loadusr -Wn spindle-vfd gs2_vfd -n spindle-vfd The above command says: loadusr, wait for named to load, component gs2_vfd, named spindle-vfd 17.1 Command Line Options • -b or --bits (default 8) Set number of data bits to , where n must be from 5 to 8 inclusive • -d or --device (default /dev/ttyS0) Set the name of the serial device node to use • -g or --debug Turn on debugging messages. This will also set the verbose flag. Debug mode will cause all modbus messages to be printed in hex on the terminal. • -n or --name (default gs2_vfd) Set the name of the HAL module. The HAL comp name will be set to , and all pin and parameter names will begin with . • -p or --parity {even,odd,none} (default odd) Set serial parity to even, odd, or none. • -r or --rate (default 38400) Set baud rate to . It is an error if the rate is not one of the following: 110, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 • -s or --stopbits {1,2} (default 1) Set serial stop bits to 1 or 2 • -t or --target (default 1) Set MODBUS target (slave) number. This must match the device number you set on the GS2. • -v or --verbose Turn on debug messages. Note That if there are serial configuration errors, turning on verbose may result in a flood of timeout errors. 17.2 Pins Where is gs2_vfd or the name given during loading with the -n option. • .DC-bus-volts (float, out) The DC bus voltage of the VFD Integrator Manual V2.5, 2016-05-12 132 / 258 • .at-speed (bit, out) when drive is at commanded speed • .err-reset (bit, in) reset errors sent to VFD • .firmware-revision (s32, out) from the VFD • .frequency-command (float, out) from the VFD • .frequency-out (float, out) from the VFD • .is-stopped (bit, out) when the VFD reports 0 Hz output • .load-percentage (float, out) from the VFD • .motor-RPM (float, out) from the VFD • .output-current (float, out) from the VFD • .output-voltage (float, out) from the VFD • .power-factor (float, out) from the VFD • .scale-frequency (float, out) from the VFD • .speed-command (float, in) speed sent to VFD in RPM It is an error to send a speed faster than the Motor Max RPM as set in the VFD • .spindle-fwd (bit, in) 1 for FWD and 0 for REV sent to VFD • .spindle-rev (bit, in) 1 for REV and 0 if off • .spindle-on (bit, in) 1 for ON and 0 for OFF sent to VFD • .status-1 (s32, out) Drive Status of the VFD (see the GS2 manual) • .status-2 (s32, out) Drive Status of the VFD (see the GS2 manual) Note The status value is a sum of all the bits that are on. So a 163 which means the drive is in the run mode is the sum of 3 (run) + 32 (freq set by serial) + 128 (operation set by serial). 17.3 Parameters Where is gs2_vfd or the name given during loading with the -n option. • .error-count (s32, RW) • .loop-time (float, RW) how often the modbus is polled (default 0.1) • .nameplate-HZ (float, RW) Nameplate Hz of motor (default 60) • .nameplate-RPM (float, RW) Nameplate RPM of motor (default 1730) • .retval (s32, RW) the return value of an error in HAL • .tolerance (s32, RW) speed tolerance (default 0.01) For an example of using this component to drive a spindle see the GS2 Spindle example. Integrator Manual V2.5, 2016-05-12 133 / 258 Chapter 18 Mesa HostMot2 Driver 18.1 Introduction HostMot2 is an FPGA configuration developed by Mesa Electronics for their line of Anything I/O motion control cards. The firmware is open source, portable and flexible. It can be configured (at compile-time) with zero or more instances (an object created at runtime) of each of several Modules: encoders (quadrature counters), PWM generators, and step/dir generators. The firmware can be configured (at run-time) to connect each of these instances to pins on the I/O headers. I/O pins not driven by a Module instance revert to general-purpose bi-directional digital I/O. 18.2 Firmware Binaries 50 Pin Header FPGA cards Several pre-compiled HostMot2 firmware binaries are available for the different Anything I/O boards. (This list is incomplete, check the hostmot2-firmware distribution for up-to-date firmware lists.) • 3x20 (144 I/O pins): using hm2_pci module – 24-channel servo – 16-channel servo plus 24 step/dir generators • 5i22 (96 I/O pins): using hm2_pci module – 16-channel servo – 8-channel servo plus 24 step/dir generators • 5i20, 5i23, 4i65, 4i68 (72 I/O pins): using hm2_pci module – 12-channel servo – 8-channel servo plus 4 step/dir generators – 4-channel servo plus 8 step/dir generators • 7i43 (48 I/O pins): using hm2_7i43 module – 8-channel servo (8 PWM generators & 8 encoders) – 4-channel servo plus 4 step/dir generators DB25 FPGA cards The 5i25 Superport FPGA card is preprogrammed when purchased and does not need a firmware binary. Integrator Manual V2.5, 2016-05-12 18.3 134 / 258 Installing Firmware Depending on how you installed LinuxCNC you may have to open the Synaptic Package Manager from the System menu and install the package for your Mesa card. The quickest way to find them is to do a search for hostmot2 in the Synaptic Package Manager. Mark the firmware for installation, then apply. 18.4 Loading HostMot2 The LinuxCNC support for the HostMot2 firmware is split into a generic driver called hostmot2 and two low-level I/O drivers for the Anything I/O boards. The low-level I/O drivers are hm2_7i43 and hm2_pci (for all the PCI- and PC-104/Plus-based Anything I/O boards). The hostmot2 driver must be loaded first, using a HAL command like this: loadrt hostmot2 See the hostmot2(9) man page for details. The hostmot2 driver by itself does nothing, it needs access to actual boards running the HostMot2 firmware. The low-level I/O drivers provide this access. The low-level I/O drivers are loaded with commands like this: loadrt hm2_pci config="firmware=hm2/5i20/SVST8_4.BIT num_encoders=3 num_pwmgens=3 num_stepgens=1" The config parameters are described in the hostmot2 man page. 18.5 Watchdog The HostMot2 firmware may include a watchdog Module; if it does, the hostmot2 driver will use it. The watchdog must be petted by LinuxCNC periodically or it will bite. When the watchdog bites, all the board’s I/O pins are disconnected from their Module instances and become high-impedance inputs (pulled high), and all communication with the board stops. The state of the HostMot2 firmware modules is not disturbed (except for the configuration of the I/O Pins). Encoder instances keep counting quadrature pulses, and pwm- and step-generators keep generating signals (which are not relayed to the motors, because the I/O Pins have become inputs). Resetting the watchdog resumes communication and resets the I/O pins to the configuration chosen at load-time. If the firmware includes a watchdog, the following HAL objects will be exported: 18.5.1 Pins: • has_bit - (bit i/o) True if the watchdog has bit, False if the watchdog has not bit. If the watchdog has bit and the has_bit bit is True, the user can reset it to False to resume operation. 18.5.2 Parameters: • timeout_ns - (u32 read/write) Watchdog timeout, in nanoseconds. This is initialized to 1,000,000,000 (1 second) at module load time. If more than this amount of time passes between calls to the pet_watchdog() function, the watchdog will bite. 18.5.3 Functions: • pet_watchdog() - Calling this function resets the watchdog timer and postpones the watchdog biting until timeout_ns nanoseconds later. This function should be added to the servo thread. Integrator Manual V2.5, 2016-05-12 18.6 135 / 258 HostMot2 Functions • hm2_ . .read - Read all inputs, update input HAL pins. • hm2_ . .write - Write all outputs. • hm2_ . .pet-watchdog - Pet the watchdog to keep it from biting us for a while. • hm2_ . .read_gpio - Read the GPIO input pins only. (This function is not available on the 7i43 due to limitations of the EPP bus.) • hm2_ . .write_gpio - Write the GPIO control registers and output pins only. (This function is not available on the 7i43 due to limitations of the EPP bus.) Note The above read_gpio and write_gpio functions should not normally be needed, since the GPIO bits are read and written along with everything else in the standard read and write functions above, which are normally run in the servo thread. The read_gpio and write_gpio functions were provided in case some very fast (frequently updated) I/O is needed. These functions should be run in the base thread. If you have need for this, please send an email and tell us about it, and what your application is. 18.7 Pinouts The hostmot2 driver does not have a particular pinout. The pinout comes from the firmware that the hostmot2 driver sends to the Anything I/O board. Each firmware has different pinout, and the pinout depends on how many of the available encoders, pwmgens, and stepgens are used. To get a pinout list for your configuration after loading LinuxCNC in the terminal window type: dmesg > hm2.txt The resulting text file will contain lots of information as well as the pinout for the HostMot2 and any error and warning messages. To reduce the clutter by clearing the message buffer before loading LinuxCNC type the following in the terminal window: sudo dmesg -c Now when you run LinuxCNC and then do a dmesg > hm2.txt in the terminal only the info from the time you loaded LinuxCNC will be in your file along with your pinout. The file will be in the current directory of the terminal window. Each line will contain the card name, the card number, the I/O Pin number, the connector and pin, and the usage. From this printout you will know the physical connections to your card based on your configuration. An example of a 5i20 configuration: [HOSTMOT2] DRIVER=hm2_pci BOARD=5i20 CONFIG="firmware=hm2/5i20/SVST8_4.BIT num_encoders=1 num_pwmgens=1 num_stepgens=3" The above configuration produced this printout. [ [ [ [ [ [ [ [ 1141.053386] 1141.053394] 1141.053397] 1141.053401] 1141.053405] 1141.053408] 1141.053411] 1141.053415] hm2/hm2_5i20.0: hm2/hm2_5i20.0: hm2/hm2_5i20.0: hm2/hm2_5i20.0: hm2/hm2_5i20.0: hm2/hm2_5i20.0: hm2/hm2_5i20.0: hm2/hm2_5i20.0: 72 IO IO IO IO IO IO IO I/O Pin Pin Pin Pin Pin Pin Pin Pins used: 000 (P2-01): 001 (P2-03): 002 (P2-05): 003 (P2-07): 004 (P2-09): 005 (P2-11): 006 (P2-13): IOPort IOPort Encoder #0, pin B (Input) Encoder #0, pin A (Input) IOPort Encoder #0, pin Index (Input) IOPort Integrator Manual V2.5, 2016-05-12 [ 1141.053418] hm2/hm2_5i20.0: IO Pin 007 (P2-15): [ 1141.053422] hm2/hm2_5i20.0: IO Pin 008 (P2-17): [ 1141.053425] hm2/hm2_5i20.0: IO Pin 009 (P2-19): Output) [ 1141.053429] hm2/hm2_5i20.0: IO Pin 010 (P2-21): [ 1141.053432] hm2/hm2_5i20.0: IO Pin 011 (P2-23): ... [ 1141.053589] hm2/hm2_5i20.0: IO Pin 060 (P4-25): [ 1141.053593] hm2/hm2_5i20.0: IO Pin 061 (P4-27): [ 1141.053597] hm2/hm2_5i20.0: IO Pin 062 (P4-29): [ 1141.053601] hm2/hm2_5i20.0: IO Pin 063 (P4-31): [ 1141.053605] hm2/hm2_5i20.0: IO Pin 064 (P4-33): [ 1141.053609] hm2/hm2_5i20.0: IO Pin 065 (P4-35): [ 1141.053613] hm2/hm2_5i20.0: IO Pin 066 (P4-37): [ 1141.053616] hm2/hm2_5i20.0: IO Pin 067 (P4-39): [ 1141.053619] hm2/hm2_5i20.0: IO Pin 068 (P4-41): [ 1141.053621] hm2/hm2_5i20.0: IO Pin 069 (P4-43): [ 1141.053624] hm2/hm2_5i20.0: IO Pin 070 (P4-45): [ 1141.053627] hm2/hm2_5i20.0: IO Pin 071 (P4-47): [ 1141.053811] hm2/hm2_5i20.0: registered [ 1141.053815] hm2_5i20.0: initialized AnyIO board 136 / 258 PWMGen #0, pin Out0 (PWM or Up) (Output) IOPort PWMGen #0, pin Out1 (Dir or Down) ( ←IOPort PWMGen #0, pin Not-Enable (Output) StepGen StepGen StepGen StepGen StepGen StepGen IOPort IOPort IOPort IOPort IOPort IOPort #2, #2, #2, #2, #2, #2, pin pin pin pin pin pin Step (Output) Direction (Output) (unused) (Output) (unused) (Output) (unused) (Output) (unused) (Output) at 0000:02:02.0 Note That the I/O Pin nnn will correspond to the pin number shown on the HAL Configuration screen for GPIOs. Some of the Stepgen, Encoder and PWMGen will also show up as GPIOs in the HAL Configuration screen. 18.8 PIN Files The default pinout is described in a .PIN file (human-readable text). When you install a firmware package the .PIN files are installed in /usr/share/doc/hostmot2-firmware- / 18.9 Firmware The selected firmware (.BIT file) and configuration is uploaded from the PC motherboard to the Mesa mothercard on LinuxCNC startup. If you are using Run In Place, you must still install a hostmot2-firmware- package. There is more information about firmware and configuration in the Configurations section. 18.10 HAL Pins The HAL pins for each configuration can be seen by opening up Show HAL Configuration from the Machine menu. All the HAL pins and parameters can be found there. The following figure is of the 5i20 configuration used above. Integrator Manual V2.5, 2016-05-12 137 / 258 Figure 18.1: 5i20 HAL Pins 18.11 Configurations The Hostmot2 firmware is available in several versions, depending on what you are trying to accomplish. You can get a reminder of what a particular firmware is for by looking at the name. Let’s look at a couple of examples. In the 7i43 (two ports), SV8 (Servo 8) would be for having 8 servos or fewer, using the classic 7i33 4-axis (per port) servo board. So 8 servos would use up all 48 signals in the two ports. But if you only needed 3 servos, you could say num_encoders=3 and num_pwmgens=3 and recover 5 servos at 6 signals each, thus gaining 30 bits of GPIO. Or, in the 5i22 (four ports), SVST8_24 (Servo 8, Stepper 24) would be for having 8 servos or fewer (7i33 x2 again), and 24 steppers or fewer (7i47 x2). This would use up all four ports. If you only needed 4 servos you could say num_encoders=4 and num_pwmgens=4 and recover 1 port (and save a 7i33). And if you only needed 12 steppers you could say num_stepgens=12 and free up one port (and save a 7i47). So in this way we can save two ports (48 bits) for GPIO. Here are tables of the firmwares available in the official packages. There may be additional firmwares available at the Mesanet.com website that have not yet made it into the LinuxCNC official firmware packages, so check there too. 3x20 (6-port various) Default Configurations (The 3x20 comes in 1M, 1.5M, and 2M gate versions. So far, all firmware is available in all gate sizes.) Firmware SV24 SVST16_24 Encoder 24 16 PWMGen 24 16 StepGen 0 24 GPIO 0 0 Integrator Manual V2.5, 2016-05-12 138 / 258 5i22 (4-port PCI) Default Configurations (The 5i22 comes in 1M and 1.5M gate versions. So far, all firmware is available in all gate sizes.) Firmware SV16 SVST2_4_7I47 SVST8_8 SVST8_24 Encoder 16 4 8 8 PWM 16 2 8 8 StepGen 0 4 8 24 GPIO 0 72 0 0 StepGen 0 8 (tbl5) 4 0 0 8 (tbl5) 4 (tbl5) 4 8 0 GPIO 0 12 48 24 12 0 0 8 0 0 StepGen 0 8 (tbl5) 4 0 0 4 (tbl5) 4 GPIO 0 12 48 24 12 0 8 StepGen 0 4 8 4 4 8 GPIO 0 48 0 0 8 0 StepGen 0 4 4 GPIO 0 0 8 5i23 (3-port PCI) Default Configurations (The 5i23 has 400k gates.) Firmware SV12 SVST2_8 SVST2_4_7I47 SV12_2X7I48_72 SV12IM_2X7I48_72 SVST4_8 SVST8_4 SVST8_4IM2 SVST8_8IM2 SVTP6_7I39 Encoder 12 2 4 12 12 (+IM) 4 8 8 (+IM) 8 (+IM) 6 PWM 12 2 2 12 12 4 8 8 8 0 (6 BLDC) 5i20 (3-port PCI) Default Configurations (The 5i20 has 200k gates.) Firmware SV12 SVST2_8 SVST2_4_7I47 SV12_2X7I48_72 SV12IM_2X7I48_72 SVST8_4 SVST8_4IM2 Encoder 12 2 4 12 12 (+IM) 8 8 (+IM) PWM 12 2 2 12 12 8 8 4i68 (3-port PC/104) Default Configurations (The 4i68 has 400k gates.) Firmware SV12 SVST2_4_7I47 SVST4_8 SVST8_4 SVST8_4IM2 SVST8_8IM2 Encoder 12 4 4 8 8 (+IM) 8 (+IM) PWM 12 2 4 8 8 8 4i65 (3-port PC/104) Default Configurations (The 4i65 has 200k gates.) Firmware SV12 SVST8_4 SVST8_4IM2 Encoder 12 8 8 (+IM) PWM 12 8 8 7i43 (2-port parallel) 400k gate versions, Default Configurations Integrator Manual V2.5, 2016-05-12 Firmware SV8 SVST4_4 SVST4_6 SVST4_12 SVST2_4_7I47 Encoder 8 4 4 4 4 139 / 258 PWM 8 4 4 4 2 StepGen 0 4 (tbl5) 6 (tbl3) 12 4 GPIO 0 0 0 0 24 StepGen 0 4 (tbl5) 6 (tbl3) 4 GPIO 0 0 0 24 7i43 (2-port parallel) 200k gate versions, Default Configurations Firmware SV8 SVST4_4 SVST4_6 SVST2_4_7I47 Encoder 8 4 4 4 PWM 8 4 4 2 Even though several cards may have the same named .BIT file you cannot use a .BIT file that is not for that card. Different cards have different clock frequencies so make sure you load the proper .BIT file for your card. Custom hm2 firmwares can be created for special applications and you may see some custom hm2 firmwares in the directories with the default ones. When you load the board-driver (hm2_pci or hm2_7i43), you can tell it to disable instances of the three primary modules (pwmgen, stepgen, and encoder) by setting the count lower. Any I/O pins belonging to disabled module instances become GPIOs. 18.12 GPIO General Purpose I/O pins on the board which are not used by a module instance are exported to HAL as full GPIO pins. Full GPIO pins can be configured at run-time to be inputs, outputs, or open drains, and have a HAL interface that exposes this flexibility. I/O pins that are owned by an active module instance are constrained by the requirements of the owning module, and have a restricted HAL interface. GPIOs have names like hm2_ . .gpio. . IONum. is a three-digit number. The mapping from IONum to connector and pin-on-that-connector is written to the syslog when the driver loads, and it’s documented in Mesa’s manual for the Anything I/O boards. The hm2 GPIO representation is modeled after the Digital Inputs and Digital Outputs described in the Canonical Device Interface (part of the HAL General Reference document). GPIO pins default to input. 18.12.1 Pins • in - (Bit, Out) Normal state of the hardware input pin. Both full GPIO pins and I/O pins used as inputs by active module instances have this pin. • in_not - (Bit, Out) Inverted state of the hardware input pin. Both full GPIO pins and I/O pins used as inputs by active module instances have this pin. • out - (Bit, In) Value to be written (possibly inverted) to the hardware output pin. Only full GPIO pins have this pin. 18.12.2 Parameters • invert_output - (Bit, RW) This parameter only has an effect if the is_output parameter is true. If this parameter is true, the output value of the GPIO will be the inverse of the value on the out HAL pin. Only full GPIO pins and I/O pins used as outputs by active module instances have this parameter. To invert an active module pin you have to invert the GPIO pin not the module pin. Integrator Manual V2.5, 2016-05-12 140 / 258 • is_opendrain - (Bit, RW) This parameter only has an effect if the is_output parameter is true. If this parameter is false, the GPIO behaves as a normal output pin: the I/O pin on the connector is driven to the value specified by the out HAL pin (possibly inverted), and the value of the in and in_not HAL pins is undefined. If this parameter is true, the GPIO behaves as an open-drain pin. Writing 0 to the out HAL pin drives the I/O pin low, writing 1 to the out HAL pin puts the I/O pin in a high-impedance state. In this high-impedance state the I/O pin floats (weakly pulled high), and other devices can drive the value; the resulting value on the I/O pin is available on the in and in_not pins. Only full GPIO pins and I/O pins used as outputs by active module instances have this parameter. • is_output - (Bit, RW) If set to 0, the GPIO is an input. The I/O pin is put in a high-impedance state (weakly pulled high), to be driven by other devices. The logic value on the I/O pin is available in the in and in_not HAL pins. Writes to the out HAL pin have no effect. If this parameter is set to 1, the GPIO is an output; its behavior then depends on the is_opendrain parameter. Only full GPIO pins have this parameter. 18.13 StepGen Stepgens have names like hm2_ . .stepgen. .. Instance is a two-digit number that corresponds to the HostMot2 stepgen instance number. There are num_stepgens instances, starting with 00. Each stepgen allocates 2-6 I/O pins (selected at firmware compile time), but currently only uses two: Step and Direction outputs.1 The stepgen representation is modeled on the stepgen software component. Stepgen default is active high step output (high during step time low during step space). To invert a StepGen output pin you invert the corresponding GPIO pin that is being used by StepGen. To find the GPIO pin being used for the StepGen output run dmesg as shown above. Each stepgen instance has the following pins and parameters: 18.13.1 Pins • control-type - (Bit, In) Switches between position control mode (0) and velocity control mode (1). Defaults to position control (0). • counts - (s32, Out) Feedback position in counts (number of steps). • enable - (Bit, In) Enables output steps. When false, no steps are generated. • position-cmd - (Float, In) Target position of stepper motion, in user-defined position units. • position-fb - (Float, Out) Feedback position in user-defined position units (counts / position_scale). • velocity-cmd - (Float, In) Target velocity of stepper motion, in user-defined position units per second. This pin is only used when the stepgen is in velocity control mode (control-type=1). • velocity-fb - (Float, Out) Feedback velocity in user-defined position units per second. 18.13.2 Parameters • dirhold - (u32, RW) Minimum duration of stable Direction signal after a step ends, in nanoseconds. • dirsetup - (u32, RW) Minimum duration of stable Direction signal before a step begins, in nanoseconds. • maxaccel - (Float, RW) Maximum acceleration, in position units per second per second. If set to 0, the driver will not limit its acceleration. • maxvel - (Float, RW) Maximum speed, in position units per second. If set to 0, the driver will choose the maximum velocity based on the values of steplen and stepspace (at the time that maxvel was set to 0). • position-scale - (Float, RW) Converts from counts to position units. position = counts / position_scale 1 At present, the firmware supports multi-phase stepper outputs, but the driver doesn’t. Interested volunteers are solicited. Integrator Manual V2.5, 2016-05-12 141 / 258 • step_type - (u32, RW) Output format, like the step_type modparam to the software stegen(9) component. 0 = Step/Dir, 1 = Up/Down, 2 = Quadrature. In Quadrature mode (step_type=2), the stepgen outputs one complete Gray cycle (00 -> 01 -> 11 -> 10 -> 00) for each step it takes. • steplen - (u32, RW) Duration of the step signal, in nanoseconds. • stepspace - (u32, RW) Minimum interval between step signals, in nanoseconds. 18.13.3 Output Parameters The Step and Direction pins of each StepGen have two additional parameters. To find which I/O pin belongs to which step and direction output run dmesg as described above. • invert_output - (Bit, RW) This parameter only has an effect if the is_output parameter is true. If this parameter is true, the output value of the GPIO will be the inverse of the value on the out HAL pin. • is_opendrain - (Bit, RW) If this parameter is false, the GPIO behaves as a normal output pin: the I/O pin on the connector is driven to the value specified by the out HAL pin (possibly inverted). If this parameter is true, the GPIO behaves as an open-drain pin. Writing 0 to the out HAL pin drives the I/O pin low, writing 1 to the out HAL pin puts the I/O pin in a highimpedance state. In this high-impedance state the I/O pin floats (weakly pulled high), and other devices can drive the value; the resulting value on the I/O pin is available on the in and in_not pins. Only full GPIO pins and I/O pins used as outputs by active module instances have this parameter. 18.14 PWMGen PWMgens have names like hm2_ . .pwmgen. .. Instance is a two-digit number that corresponds to the HostMot2 pwmgen instance number. There are num_pwmgens instances, starting with 00. In HM2, each pwmgen uses three output I/O pins: Not-Enable, Out0, and Out1. To invert a PWMGen output pin you invert the corresponding GPIO pin that is being used by PWMGen. To find the GPIO pin being used for the PWMGen output run dmesg as shown above. The function of the Out0 and Out1 I/O pins varies with output-type parameter (see below). The hm2 pwmgen representation is similar to the software pwmgen component. Each pwmgen instance has the following pins and parameters: 18.14.1 Pins • enable - (Bit, In) If true, the pwmgen will set its Not-Enable pin false and output its pulses. If enable is false, pwmgen will set its Not-Enable pin true and not output any signals. • value - (Float, In) The current pwmgen command value, in arbitrary units. 18.14.2 Parameters • output-type - (s32, RW) This emulates the output_type load-time argument to the software pwmgen component. This parameter may be changed at runtime, but most of the time you probably want to set it at startup and then leave it alone. Accepted values are 1 (PWM on Out0 and Direction on Out1), 2 (Up on Out0 and Down on Out1), 3 (PDM mode, PDM on Out0 and Dir on Out1), and 4 (Direction on Out0 and PWM on Out1, for locked antiphase). • scale - (Float, RW) Scaling factor to convert value from arbitrary units to duty cycle: dc = value / scale. Duty cycle has an effective range of -1.0 to +1.0 inclusive, anything outside that range gets clipped. Integrator Manual V2.5, 2016-05-12 142 / 258 • pdm_frequency - (u32, RW) This specifies the PDM frequency, in Hz, of all the pwmgen instances running in PDM mode (mode 3). This is the pulse slot frequency; the frequency at which the pdm generator in the Anything I/O board chooses whether to emit a pulse or a space. Each pulse (and space) in the PDM pulse train has a duration of 1/pdm_frequency seconds. For example, setting the pdm_frequency to 2e6 (2 MHz) and the duty cycle to 50% results in a 1 MHz square wave, identical to a 1 MHz PWM signal with 50% duty cycle. The effective range of this parameter is from about 1525 Hz up to just under 100 MHz. Note that the max frequency is determined by the ClockHigh frequency of the Anything I/O board; the 5i20 and 7i43 both have a 100 MHz clock, resulting in a 100 Mhz max PDM frequency. Other boards may have different clocks, resulting in different max PDM frequencies. If the user attempts to set the frequency too high, it will be clipped to the max supported frequency of the board. • pwm_frequency - (u32, RW) This specifies the PWM frequency, in Hz, of all the pwmgen instances running in the PWM modes (modes 1 and 2). This is the frequency of the variable-duty-cycle wave. Its effective range is from 1 Hz up to 193 KHz. Note that the max frequency is determined by the ClockHigh frequency of the Anything I/O board; the 5i20 and 7i43 both have a 100 MHz clock, resulting in a 193 KHz max PWM frequency. Other boards may have different clocks, resulting in different max PWM frequencies. If the user attempts to set the frequency too high, it will be clipped to the max supported frequency of the board. Frequencies below about 5 Hz are not terribly accurate, but above 5 Hz they’re pretty close. 18.14.3 Output Parameters The output pins of each PWMGen have two additional parameters. To find which I/O pin belongs to which output run dmesg as described above. • invert_output - (Bit, RW) This parameter only has an effect if the is_output parameter is true. If this parameter is true, the output value of the GPIO will be the inverse of the value on the out HAL pin. • is_opendrain - (Bit, RW) If this parameter is false, the GPIO behaves as a normal output pin: the I/O pin on the connector is driven to the value specified by the out HAL pin (possibly inverted). If this parameter is true, the GPIO behaves as an open-drain pin. Writing 0 to the out HAL pin drives the I/O pin low, writing 1 to the out HAL pin puts the I/O pin in a highimpedance state. In this high-impedance state the I/O pin floats (weakly pulled high), and other devices can drive the value; the resulting value on the I/O pin is available on the in and in_not pins. Only full GPIO pins and I/O pins used as outputs by active module instances have this parameter. 18.15 Encoder Encoders have names like hm2_ . .encoder. .. Instance is a two-digit number that corresponds to the HostMot2 encoder instance number. There are num_encoders instances, starting with 00. Each encoder uses three or four input I/O pins, depending on how the firmware was compiled. Three-pin encoders use A, B, and Index (sometimes also known as Z). Four-pin encoders use A, B, Index, and Index-mask. The hm2 encoder representation is similar to the one described by the Canonical Device Interface (in the HAL General Reference document), and to the software encoder component. Each encoder instance has the following pins and parameters: 18.15.1 Pins • count - (s32, Out) Number of encoder counts since the previous reset. • index-enable - (Bit, I/O) When this pin is set to True, the count (and therefore also position) are reset to zero on the next Index (Phase-Z) pulse. At the same time, index-enable is reset to zero to indicate that the pulse has occurred. • position - (Float, Out) Encoder position in position units (count / scale). • rawcounts - (s32, Out) Total number of encoder counts since the start, not adjusted for index or reset. • reset - (Bit, In) When this pin is TRUE, the count and position pins are set to 0. (The value of the velocity pin is not affected by this.) The driver does not reset this pin to FALSE after resetting the count to 0, that is the user’s job. • velocity - (Float, Out) Estimated encoder velocity in position units per second. Integrator Manual V2.5, 2016-05-12 18.15.2 143 / 258 Parameters • counter-mode - (Bit, RW) Set to False (the default) for Quadrature. Set to True for Up/Down or for single input on Phase A. Can be used for a frequency to velocity converter with a single input on Phase A when set to true. • filter - (Bit, RW) If set to True (the default), the quadrature counter needs 15 clocks to register a change on any of the three input lines (any pulse shorter than this is rejected as noise). If set to False, the quadrature counter needs only 3 clocks to register a change. The encoder sample clock runs at 33 MHz on the PCI Anything I/O cards and 50 MHz on the 7i43. • index-invert - (Bit, RW) If set to True, the rising edge of the Index input pin triggers the Index event (if index-enable is True). If set to False, the falling edge triggers. • index-mask - (Bit, RW) If set to True, the Index input pin only has an effect if the Index-Mask input pin is True (or False, depending on the index-mask-invert pin below). • index-mask-invert - (Bit, RW) If set to True, Index-Mask must be False for Index to have an effect. If set to False, the IndexMask pin must be True. • scale - (Float, RW) Converts from count units to position units. A quadrature encoder will normally have 4 counts per pulse so a 100 PPR encoder would be 400 counts per revolution. In .counter-mode a 100 PPR encoder would have 100 counts per revelution as it only uses the rising edge of A and direction is B. • vel-timeout - (Float, RW) When the encoder is moving slower than one pulse for each time that the driver reads the count from the FPGA (in the hm2_read() function), the velocity is harder to estimate. The driver can wait several iterations for the next pulse to arrive, all the while reporting the upper bound of the encoder velocity, which can be accurately guessed. This parameter specifies how long to wait for the next pulse, before reporting the encoder stopped. This parameter is in seconds. 18.16 5i25 Configuration 18.16.1 Firmware The 5i25 firmware comes preloaded for the daughter card it is purchased with. So the firmware=xxx.BIT is not part of the hm2_pci configuration string when using a 5i25. 18.16.2 Configuration Example configurations of the 5i25/7i76 and 5i25/7i77 cards are included in the Configuration Selector. If you like to roll your own configuration the following examples show how to load the drivers in the HAL file. 5i25 + 7i76 Card # load the generic driver loadrt hostmot2 # load the PCI driver and configure loadrt hm2_pci config="num_encoders=1 num_stepgens=5 sserial_port_0=0XXX" 5i25 + 7i77 Card # load the generic driver loadrt hostmot2 # load the PCI driver and configure loadrt hm2_pci config="num_encoders=6 num_pwmgens=6 sserial_port_0=0XXX" Integrator Manual V2.5, 2016-05-12 18.16.3 144 / 258 SSERIAL Configuration The sserial_port_0=0XXX configuration string sets some options for the smart serial daughter card. These options are specific for each daughter card. See the Mesa manual for more information on the exact usuage. 18.16.4 7i77 Limits The minlimit and maxlimit are bounds on the pin value (in this case the analog out value) fullscalemax is the scale factor. These are by default set to the analog in or analog range (most likely in volts). So for example on the 7I77 +-10V analog outputs, the default values are: minlimit -10 maxlimit +10 maxfullscale 10 If you wanted to say scale the analog out of a channel to IPS for a velocity mode servo (say 24 IPS max) you could set the limits like this: minlimit -24 maxlimit +24 maxfullscale 24 If you wanted to scale the analog out of a channel to RPM for a 0 to 6000 RPM spindle with 0-10V control you could set the limits like this: minlimit 0 maxlimit 6000 maxfullscale 6000 (this would prevent unwanted negative output voltages from being set) 18.17 Example Configurations Several example configurations for Mesa hardware are included with LinuxCNC. The configurations are located in the hm2-servo and hm2-stepper sections of the Configuration Selector. Typically you will need the board installed for the configuration you pick to load. The examples are a good place to start and will save you time. Just pick the proper example from the LinuxCNC Configuration Selector and save a copy to your computer so you can edit it. To see the exact pins and parameters that your configuration gave you, open the Show HAL Configuration window from the Machine menu, or do dmesg as outlined above. Integrator Manual V2.5, 2016-05-12 145 / 258 Chapter 19 Motenc Driver Vital Systems Motenc-100 and Motenc-LITE The Vital Systems Motenc-100 and Motenc-LITE are 8- and 4-channel servo control boards. The Motenc-100 provides 8 quadrature encoder counters, 8 analog inputs, 8 analog outputs, 64 (68?) digital inputs, and 32 digital outputs. The Motenc-LITE has only 4 encoder counters, 32 digital inputs and 16 digital outputs, but it still has 8 analog inputs and 8 analog outputs. The driver automatically identifies the installed board and exports the appropriate HAL objects. Installing: loadrt hal_motenc During loading (or attempted loading) the driver prints some useful debugging messages to the kernel log, which can be viewed with dmesg. Up to 4 boards may be used in one system. 19.1 Pins In the following pins, parameters, and functions, is the board ID. According to the naming conventions the first board should always have an ID of zero. However this driver sets the ID based on a pair of jumpers on the board, so it may be non-zero even if there is only one board. • (s32) motenc. .enc- -count - Encoder position, in counts. • (float) motenc. .enc- -position - Encoder position, in user units. • (bit) motenc. .enc- -index - Current status of index pulse input. • (bit) motenc. .enc- -idx-latch - Driver sets this pin true when it latches an index pulse (enabled by latchindex). Cleared by clearing latch-index. • (bit) motenc. .enc- -latch-index - If this pin is true, the driver will reset the counter on the next index pulse. • (bit) motenc. .enc- -reset-count - If this pin is true, the counter will immediately be reset to zero, and the pin will be cleared. • (float) motenc. .dac- -value - Analog output value for DAC (in user units, see -gain and -offset) • (float) motenc. .adc- -value - Analog input value read by ADC (in user units, see -gain and -offset) • (bit) motenc. .in- - State of digital input pin, see canonical digital input. • (bit) motenc. .in- -not - Inverted state of digital input pin, see canonical digital input. Integrator Manual V2.5, 2016-05-12 146 / 258 • (bit) motenc. .out- - Value to be written to digital output, seen canonical digital output. • (bit) motenc. .estop-in - Dedicated estop input, more details needed. • (bit) motenc. .estop-in-not - Inverted state of dedicated estop input. • (bit) motenc. .watchdog-reset - Bidirectional, - Set TRUE to reset watchdog once, is automatically cleared. 19.2 Parameters • (float) motenc. .enc- -scale - The number of counts / user unit (to convert from counts to units). • (float) motenc. .dac- -offset - Sets the DAC offset. • (float) motenc.