Eagle 6.4 Schematics for LinuxCNC 2.5 HAL Configuration: Device Creation Checklist

I’m updating the Eagle-to-HAL script and library I used to get the Joggy Thing working, with the intent of getting a Nostromo N52 working on another LinuxCNC box.

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:

halrun
halcmd: loadrt conv_float_s32
halcmd: show all
Loaded HAL Components:
ID      Type  Name                                      PID   State
     4  RT    conv_float_s32                                  ready
     3  User  halcmd2395                                 2395 ready

Component Pins:
Owner   Type  Dir         Value  Name
     4  float IN              0  conv-float-s32.0.in
     4  s32   OUT             0  conv-float-s32.0.out
     4  bit   OUT         FALSE  conv-float-s32.0.out-of-range

... snippage ...

Parameters:
Owner   Type  Dir         Value  Name
     4  bit   RW          FALSE  conv-float-s32.0.clamp
     4  s32   RO              0  conv-float-s32.0.time
     4  s32   RW              0  conv-float-s32.0.tmax

... snippage ...

Exported Functions:
Owner   CodeAddr  Arg       FP   Users  Name
 00004  fc0a9000  fc0630b8  YES      0   conv-float-s32.0
... snippage ...

Achtung!

• The module name uses underscores as separators: loadrt conv_float_s32
• The function name uses h-y-p-h-e-n-s as separators: conv-float-s32.0
• Unlike in the Linux kernel, the two characters are not equivalent

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
  • Ctrl-U in Firefox reveals the HTML source, Ctrl-A and Ctrl-C, flip windows, then Ctrl-V
  • 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.

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.