To that end, here’s a checklist for creating a new Eagle device corresponding to a HAL module.

Remember: although this process has a tremendous number of moving parts, you do it exactly once when you need a device that doesn’t already exist. After that, you just click to add an existing device to your schematic, wire it up, then the tedious write-only HAL overhead happens automagically.

Cross-check the documentation with the actual component code!

The man page lists the names, pins, parameters, and suchlike, but may have typos. This isn’t a criticism, it’s a fact of life.

Before investing a ton o’ time creating an Eagle device, load the module and find out what’s really there:

Add the HAL Module to the Conversion Script

The hal-write.ulp script contains a table of all the module names, so you must update the script in parallel with the hal-config.lbr Eagle library.

However, you can create an Eagle device that is not a HAL module by omitting it from the script. In that case, the Eagle device name will become part of the net names that define and interconnect the pins, but the script will not create a statement to load a module. For example, the hal_input userspace program creates a set of pins for each input device that start with input.n, but there’s no corresponding HAL module. I’ll put up an example of all this in a bit.

Create a Schematic Symbol

The name of the symbol is not critical: CONVERT.sym

use either dashes or hyphens as you prefer

The >NAME string must be on layer 95-Names

No need for a >VALUE string, but put it on layer 96-Values if present

HAL pins become symbol pins

Use the HAL pin name, with hyphens

Set Visibility to Pin

Set Direction to in / out / io to match the HAL description

Set Function to None to indicate an ordinary net connection

Verify the pins against the HAL device!

Create a HAL Schematic Device

The new device name must match the HAL module name, with underscores, as entered in the conversion script table

CONV_FLOAT_S32.dev

Set the Prefix to the HAL function name, plus a trailing period, with hyphens

CONV-FLOAT-S32.

Create the Description using copy-and-paste from the HTML source: use the man page in the LinuxCNC doc

Delete all the boilerplate at the top, leave the centered Title, ditch the reference links

Add the symbol you created earlier or reuse an existing symbol

Set the symbol NAME to a single underscore: _

Change the Add level to must

Add a PIN_FUNCTION symbol to the device

Change the symbol name from G$1 (or whatever) to a single period: .

Change the Add Level to must

Add PIN_PARAMETER symbols as needed

Change the symbol name from G$1 (or whatever) to the parameter name preceded by a single period: .CLAMP

Change the Add Level to request

Change the Direction as needed

Add the DUMMY physical package, then connect all the pins to pads

Create a non-HAL Schematic Device

The new device name may be anything that’s not in the conversion script table

The Prefix must match the desired pin names, plus a trailing period. For hal_input pins:

INPUT.

Create the Description as above

Add the symbol you created earlier

Set the symbol NAME to a single underscore: _

Change the Add level to must

Do not add a PIN_FUNCTION symbol, because it has no corresponding module

Add PIN_PARAMETER symbols as needed

Change the symbol name from G$1 (or whatever) to the parameter name preceded by a single period: .CLAMP

Change the Add Level to request

Change the Direction as needed

Add the DUMMY physical package, then connect all the pins to pads

Devices may have multiple Symbols, with different Add Level options; can seems appropriate. As nearly as I can tell, you must name each Symbol as a suffix to the full name to differentiate them within the Device; I use a hyphen before the suffix, so that -KEYS generates INPUT.0-KEYS. Those suffixes don’t appear elsewhere in the generated HAL configuration file.

Save the library, update it in the schematic editor (Library → Update ...), and you’re set.

Although it’s tempting, do not include a version number in the library file name, because Eagle stores the file name inside the schematic file along with the devices from that file. As a result, when you bump the library version number and use devices from the new library file, the schematic depends on both library files and there’s no way within Eagle to migrate devices from one library to the other; you must delete the existing devices from the schematic and re-place them from the new library. Or you can do like I did: hand-edit the XML fields inside the library file.

Eagle HAL Device

You’ll almost certainly drive this procedure off the rails, so let me know what I’ve screwed up. It does, in fact, work wonderfully well and, as far as I’m concerned, makes HAL usable, if only because HAL is a write-only language to start with and now you need not read it to modify it.

One a day, every day…

Redshifting

(Dis)Claimer

The FTC sez I'm supposed to tell you who's slipping me baksheesh for all the glowing reviews and testimonials you'll find herein [cough].

Unless otherwise noted:

I actually bought all this crap

I get exactly bupkis from anybody

The Baksheesh tag marks the first post involving anything that might look like a freebie.

Any ads you see come from Wordpress, not me; WP controls the number of ads, their content, and their positioning. Although I do get a cut of the ad revenue, this is not, based on current evidence, a get-rich-quick scheme. You can eliminate the ads by signing in to your WP account or using an ad blocker.