hp-laser-1008a-macos README

The project's README from github.com/Kuberwastaken/hp-laser-1008a-macos. As one markdown file: README.md.

HP Laser 1008a on macOS (native Cmd-P driver)

Make the HP Laser 1003 / 1006 / 1008 (a/w), HP's rebadged Samsung SPL3 laser, print from Apple Silicon macOS like a normal printer. Cmd-P from any app. No terminal, no per-job scripts.

HP never shipped a working macOS driver for these. They are not AirPrint, they do not speak PostScript or PCL, and until recently the open-source SPL/QPDL drivers did not produce a stream this exact unit accepts. This project fixes that with a small patch to SpliX and drives the printer natively.

Tested on macOS 26 (Apple Silicon). USB-connected 1003 / 1006 / 1008 (a and w).

UPDATE: this driver is now fully native (and that is what we run)

It got progressively more native, and the current version is the real deal:

  1. First it ran HP's proprietary Linux rastertospl inside a Docker/colima Linux VM (the only thing that produced correct output at the time).
  2. Then we reverse engineered the actual bug (see The story), fixed it in SpliX with a 10-line patch, and dropped Docker/colima/ULD entirely.
  3. Now the USB write is a tiny native IOKit helper too, so Python, pyusb, and libusb are gone as well.

This is what the repo ships and what we use. The entire runtime is two compiled pieces on Apple's own frameworks: a patched SpliX rastertoqpdl CUPS filter (C++, system libcups) and hpl1008-usbd (C, IOKit + CoreFoundation). No Docker, no VM, no vendor binary, no Python, no Homebrew libraries. The SPL3 fix is being upstreamed to SpliX (issue #1).

Install (one command)

Plug the printer in over USB, then paste this into Terminal:

git clone https://github.com/Kuberwastaken/hp-laser-1008a-macos.git && cd hp-laser-1008a-macos && ./install.sh

It asks for your password once, builds the two native binaries, and sets up the printer as "HP Laser 1008a". Print from any app with Cmd-P. Prerequisites: Homebrew and the Xcode command line tools (xcode-select --install), both build-time only.

Test from the terminal: lp -d HP_Laser_1008a /etc/hosts. Remove everything: ./uninstall.sh.

How it works

flowchart LR
    A[Any app, Cmd-P] --> B[CUPS]
    B --> C[cgpdftoraster<br/>CUPS raster]
    C --> D[rastertoqpdl<br/>patched SpliX, C++]
    D -->|SPL3 / QPDL| E[hpl100x backend<br/>C + IOKit, root]
    E -->|USB bulk write| F[(HP Laser 1008a)]

Two non-obvious pieces make this work:

The backend runs as root. On recent macOS only root can drive USB, and the usb backend that ships with macOS refuses this printer (it mis-reads the port status as permanently "offline"). So the USB write lives in a small CUPS backend (hpl100x:/) installed 0700 root-owned: CUPS runs it as root and it does the raw write with IOKit (IOUSBInterfaceOpenSeize + WritePipe). The rest of the chain is a normal native CUPS filter. (The backend sandbox does permit IOKit USB; only the filter sandbox blocks it.)

The printer is dual-mode and macOS flips it. Interface 0 has alt 0 = 7/1/2 (classic raw printing) and alt 1 = 7/1/4 (IPP-over-USB), sharing bulk-OUT endpoint 0x02. macOS often leaves the interface on the IPP-USB alt, where the printer expects HTTP framing and silently drops raw SPL3. The backend reads the config descriptor, finds the classic interface/alt, and SetAlternateInterfaces back to it before writing. Run sudo /usr/libexec/cups/backend/hpl100x probe to dump the descriptor.

Earlier versions streamed SPL3 to a root LaunchDaemon over 127.0.0.1:9108 because the backend sandbox was assumed to block USB. It does not, so the socket and daemon are gone (see ROADMAP.md, V2). The daemon variant still lives in daemon/ + launchd/ as a fallback.

The story

The HP Laser 100 series is a genuinely awkward printer on a Mac:

What you'd try What happens
AirPrint / driverless Not offered. Its USB HTTP endpoint serves no IPP
Generic PCL / PostScript Printer speaks neither, the CUPS backend hangs "offline"
SpliX 2.0.1 No HP Laser 10x support at all
SpliX 2.0.2 (out of the box) Garbled: striped raster at the page origin, repeated sheets
HP's macOS driver Does not exist

SpliX 2.0.2 added HP Laser 10x support (QPDL v3, a band-width table), but on the 1008a it still printed a striped patch at the top-left of every sheet and then ejected and repeated. We diagnosed it without the printer by feeding an identical raster through both HP's rastertospl and SpliX and diffing the output:

HP's own binary confirmed it: disassembling rastertospl shows it computes the header as points * 300.0 / 72.0. SpliX already had that 300-dpi code; it was just wrongly coupled to JBIG. The fix (patches/300dpi-header.patch) decouples it and gates it on specialBandWidth, which is already true for these models. Bands stay 0x11. Ten lines.

Notes

Credits

Thanks to SpliX (the SPL/QPDL engine), @ValdikSS for the HP Laser 10x support in SpliX 2.0.2, @janrueth / photovirus for the macOS build patch, and Pierov's HP Laser 107a on Linux writeup. The 300dpi-header.patch here is the missing piece for the 1003/1008 series.

License

MIT for this glue (see LICENSE). SpliX and the patches are GPLv2.

hp-laser-1008a-macos (Kuberwastaken/hp-laser-1008a-macos)

daemon
Searching Database…

175 ·GitHub
Hp-laser-1008a-macos
What is this?It is a native macOS driver that lets the HP Laser 1003/1006/1008 (a/w) printers — HP's rebadged Samsung SPL3 laser printers — print normally via Cmd-P, since HP never shipped a working macOS driver for them.
Is this an app I open, or a background driver?It's a CUPS printer driver/backend, not an app with a UI: a patched SpliX CUPS filter plus a tiny native IOKit USB helper (hpl1008-usbd) that register the printer with macOS so any app can print to it with Cmd-P.
Do I need Homebrew or Xcode tools first?Yes, both Homebrew and the Xcode command line tools (xcode-select --install) are required, but only at build time.
Does it just work right away, or are there quirks?The first print after idle takes about 10-15 seconds because the printer is waking from auto-power-off and heating its fuser, not a software delay. Also, macOS can leave the printer's USB interface in IPP-USB mode instead of classic raw mode, which the backend has to detect and switch back itself.
Does it work on Intel Macs too, or only Apple Silicon?It's built and tested specifically for Apple Silicon Macs running macOS 26, connected to the printer over USB; Intel Macs aren't mentioned as supported.
Why not just use a generic PCL or PostScript driver?The printer speaks neither PCL nor PostScript (nor AirPrint/IPP), so any generic driver just leaves the CUPS backend hanging offline.
What was actually wrong with the existing SpliX driver?SpliX sent the page-header geometry at 600 dpi while this printer reads that header on a 300 dpi grid, making it think the page was much bigger than A4; it printed one band, hit the real page edge, ejected, and repeated the giant 'remaining' page. A 10-line patch (300dpi-header.patch) fixes the mismatch.
Will it work with other HP Laser 100-series USB product IDs?Yes — the USB helper matches by HP's vendor ID (0x03F0) and the printer-class interface descriptor rather than a hardcoded product ID, so other 1003/1008 variants should work as-is.
Does this still need Docker or Python like earlier versions?No — earlier iterations ran HP's Linux driver in a Docker/colima VM and later used a Python/pyusb daemon, but the current version replaced both with a native IOKit C helper, so Docker, colima, ULD, and Python are no longer needed.
What are similar projects?w1700k-sdr, MacNativeGames, wifit3, mac-precision-touchpad, nxnative, BlackHole, ReBarUEFI, muguet
Which topics is it in?daemon, driver, xcode, gplv2, homebrew, hardware, apple-silicon, reverse-engineering, c, cpp, mit, macos
Creator
Kuberwastaken
Size
0.5 MB
Stars
175
Updated
CommitOct 04
Age
2mo
Commits · 90 Days