The HAL (Hardware Abstraction Layer) Handbook June 25, 2007 1 The EMC Team 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- [email protected]. Copyright (c) 2000-6 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 HAL 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 Contents I Introduction & Tutorial 8 1 Introduction 9 1.1 What is HAL? ............................................ 9 1.1.1 HAL is based on traditional system design techniques ................ 9 1.1.1.1 Part Selection ................................... 9 1.1.1.2 Interconnection Design ............................. 9 1.1.1.3 Implementation .................................. 10 1.1.1.4 Testing ....................................... 10 1.1.2 Summary .......................................... 10 1.2 HAL Concepts ........................................... 10 1.3 HAL components .......................................... 12 1.3.1 External Programs with HAL hooks ........................... 12 1.3.2 Internal Components ................................... 12 1.3.3 Hardware Drivers ..................................... 12 1.3.4 Tools and Utilities ..................................... 13 1.4 Tinkertoys, Erector Sets, Legos and the HAL ......................... 13 1.4.1 Tower ............................................ 13 1.4.2 Erector Sets ......................................... 13 1.4.3 Tinkertoys .......................................... 14 1.4.4 A Lego Example ...................................... 14 1.5 Timing Issues In HAL ....................................... 15 1.6 Dynamic Linking and Configuration .............................. 16 2 HAL Tutorial 17 2.1 Before we start ........................................... 17 2.1.1 Notation ........................................... 17 2.1.2 The RTAPI environment .................................. 17 2.2 Tab-completion ........................................... 18 2.3 A Simple Example ......................................... 18 2.3.1 Loading a realtime component .............................. 18 2.3.2 Examining the HAL .................................... 18 2.3.3 Making realtime code run ................................. 19 2.3.4 Changing parameters ................................... 20 2.3.5 Saving the HAL configuration .............................. 21 2.3.6 Restoring the HAL configuration ............................. 22 2.4 Looking at the HAL with halmeter ................................ 22 2 CONTENTS 3 2.4.1 Starting halmeter ..................................... 22 2.4.2 Using halmeter ....................................... 22 2.5 A slightly more complex example. ................................ 25 2.5.1 Installing the components ................................ 25 2.5.2 Connecting pins with signals ............................... 26 2.5.3 Setting up realtime execution - threads and functions ................ 27 2.5.4 Setting parameters ..................................... 28 2.5.5 Run it! ............................................ 29 2.6 Taking a closer look with halscope. ............................... 29 2.6.1 Starting Halscope ..................................... 29 2.6.2 Hooking up the “scope probes” .............................. 31 2.6.3 Capturing our first waveforms .............................. 32 2.6.4 Vertical Adjustments .................................... 33 2.6.5 Triggering .......................................... 33 2.6.6 Horizontal Adjustments .................................. 35 2.6.7 More Channels ....................................... 36 II HAL Reference 37 3 General Reference Information 38 3.1 Notation ............................................... 38 3.1.1 Typographical Conventions ................................ 38 3.1.2 Names ............................................ 38 3.2 General Naming Conventions .................................. 38 3.3 Hardware Driver Naming Conventions ............................. 39 3.3.1 Pin/Parameter names ................................... 39 3.3.1.1 Examples ..................................... 40 3.3.2 Function Names ...................................... 40 3.3.2.1 Examples ..................................... 40 4 Canonical Device Interfaces 41 4.1 Digital Input ............................................ 41 4.1.1 Pins ............................................. 41 4.1.2 Parameters ......................................... 41 4.1.3 Functions .......................................... 41 4.2 Digital Output ........................................... 41 4.2.1 Pins ............................................. 41 4.2.2 Parameters ......................................... 42 4.2.3 Functions .......................................... 42 4.3 Analog Input ............................................ 42 4.3.1 Pins ............................................. 42 4.3.2 Parameters ......................................... 42 4.3.3 Functions .......................................... 42 4.4 Analog Output ........................................... 42 4.4.1 Parameters ......................................... 43 4.4.2 Functions .......................................... 43 CONTENTS 4 4.5 Encoder ............................................... 43 4.5.1 Pins ............................................. 43 4.5.2 Parameters ......................................... 44 4.5.3 Functions .......................................... 44 5 Tools and Utilities 45 5.1 Halcmd ............................................... 45 5.2 Halmeter .............................................. 45 5.3 Halscope .............................................. 45 5.4 Halshow ............................................... 46 5.4.1 Hal Tree Area ........................................ 46 5.4.2 Hal Show Area ....................................... 47 5.4.3 Hal Watch Area ....................................... 50 6 Hardware Drivers 52 6.1 Parport ............................................... 52 6.1.1 Installing .......................................... 52 6.1.2 Removing .......................................... 53 6.1.3 Pins ............................................. 53 6.1.4 Parameters ......................................... 53 6.1.5 Functions .......................................... 55 6.1.6 Common problems ..................................... 55 6.2 probe_parport ........................................... 55 6.2.1 Installing .......................................... 55 6.3 AX5214H .............................................. 55 6.3.1 Installing .......................................... 56 6.3.2 Removing .......................................... 56 6.3.3 Pins ............................................. 56 6.3.4 Parameters ......................................... 56 6.3.5 Functions .......................................... 57 6.4 Servo-To-Go ............................................ 57 6.4.1 Installing: .......................................... 57 6.4.2 Removing .......................................... 57 6.4.3 Pins ............................................. 57 6.4.4 Parameters ......................................... 58 6.4.5 Functions .......................................... 58 6.5 Mesa Electronics m5i20 “Anything I/O Card” ......................... 58 6.5.1 Removing .......................................... 59 6.5.2 Pins ............................................. 59 6.5.3 Parameters ......................................... 60 6.5.4 Functions .......................................... 60 6.5.5 Connector pinout ...................................... 60 6.5.5.1 Connecor P2 ................................... 61 6.5.5.2 Connector P3 ................................... 61 6.5.5.3 Connector P4 ................................... 62 6.5.5.4 LEDs ........................................ 63 CONTENTS 5 6.6 Vital Systems Motenc-100 and Motenc-LITE .......................... 63 6.6.1 Removing .......................................... 64 6.6.2 Pins ............................................. 64 6.6.3 Parameters ......................................... 64 6.6.4 Functions .......................................... 65 6.7 Pico Systems PPMC (Parallel Port Motion Control) ...................... 65 6.7.1 Removing .......................................... 65 6.7.2 Pins ............................................. 66 6.7.3 Parameters ......................................... 66 6.7.4 Functions .......................................... 67 7 Internal Components 68 7.1 Stepgen ............................................... 68 7.1.1 Installing .......................................... 68 7.1.2 Removing .......................................... 68 7.1.3 Pins ............................................. 68 7.1.4 Parameters ......................................... 70 7.1.5 Step Types ........................................