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)

Searching Database…

175 ·GitHub
Hp-laser-1008a-macos
Что это?Это нативный драйвер macOS, позволяющий принтерам HP Laser 1003/1006/1008 (a/w) — перемаркированным Samsung SPL3 — нормально печатать через Cmd-P, ведь HP так и не выпустил для них рабочий драйвер macOS.
Это приложение, которое я открываю, или фоновый драйвер?Это драйвер/бэкенд принтера для CUPS, а не приложение с интерфейсом: пропатченный CUPS-фильтр SpliX плюс небольшой нативный USB-хелпер на IOKit (hpl1008-usbd), которые регистрируют принтер в macOS, так что любое приложение может печатать через Cmd-P.
Сначала нужны Homebrew или инструменты Xcode?Да, нужны и Homebrew, и инструменты командной строки Xcode (xcode-select --install), но только на этапе сборки.
Всё работает сразу или есть нюансы?Первая печать после простоя занимает около 10–15 секунд, потому что принтер просыпается после автоотключения и прогревает печку, — это не программная задержка. Кроме того, macOS может оставить USB-интерфейс принтера в режиме IPP-USB вместо классического raw-режима, и бэкенду приходится самому это обнаруживать и переключать обратно.
Работает ли это и на Mac с Intel или только на Apple Silicon?Он собран и протестирован специально для Mac на Apple Silicon с macOS 26, подключённых к принтеру по USB; Mac с Intel не упомянуты как поддерживаемые.
Почему бы просто не использовать универсальный драйвер PCL или PostScript?Принтер не понимает ни PCL, ни PostScript (ни AirPrint/IPP), поэтому любой универсальный драйвер просто оставляет бэкенд CUPS висеть в офлайне.
Что на самом деле было не так с существующим драйвером SpliX?SpliX отправлял геометрию заголовка страницы в 600 dpi, тогда как этот принтер читает заголовок в сетке 300 dpi и считал, что страница намного больше A4; принтер печатал одну полосу, упирался в реальный край страницы, выбрасывал лист и повторял гигантскую «оставшуюся» страницу. Патч из 10 строк (300dpi-header.patch) исправляет это несоответствие.
Будет ли работать с другими USB product ID серии HP Laser 100?Да — USB-хелпер сопоставляет по vendor ID HP (0x03F0) и дескриптору интерфейса класса принтера, а не по жёстко заданному product ID, так что другие варианты 1003/1008 должны работать как есть.
Как в прежних версиях, всё ещё нужны Docker или Python?Нет — ранние варианты запускали Linux-драйвер HP в виртуальной машине Docker/colima, а позже использовали демон на Python/pyusb, но текущая версия заменила оба нативным C-хелпером на IOKit, так что Docker, colima, ULD и Python больше не нужны.
What are similar projects?w1700k-sdr, wifit3, mac-precision-touchpad, ReBarUEFI, BlackHole, muguet, Wind-Waker-Recomp, m4-sme-exploration
Which topics is it in?daemon, driver, xcode, gplv2, homebrew, hardware, reverse-engineering, apple-silicon, c, cpp, mit, macos
Creator
Kuberwastaken
Size
0.5 MB
Stars
175
Updated
CommitOct 04
Age
2mo
Commits · 90 Days