Skip to content

Native USB transport for CH554 CDC cutters (VEVOR/Anhui Anyu) + DMPL swap_axes - #428

Open
mcmartnor wants to merge 7 commits into
inkcut:masterfrom
mcmartnor:feature/usb-transport
Open

mcmartnor wants to merge 7 commits into
inkcut:masterfrom
mcmartnor:feature/usb-transport

Conversation

@mcmartnor

@mcmartnor mcmartnor commented Aug 19, 2026 •

Copy link
Copy Markdown

Depends on #427 — this branch uses defer_to_thread from inkcut/core/utils.py, which #427 adds. Happy to rebase within a day of #427 landing, or to fold it in if you'd rather review one branch.

Summary

A native USB (libusb/pyusb) transport for cutters that never expose a serial port on macOS — specifically the CH554 CDC-class family (0483:5750: VEVOR, Anhui Anyu and many rebrands, see issue #409). Full protocol documentation: https://github.com/mcmartnor/vevor-cutter-macos

  • USB transport (transports/usb/): CDC init (SET_LINE_CODING 9600 8N1 + DTR/RTS — the firmware presents printer-class descriptors but only answers CDC), DTR/RTS keep-alive against the firmware's idle-suspend crash, self-healing connect on a worker thread (USB reset + a 1-byte pipe probe before anything is cut), and a queued writer thread with NAK-based flow control: pyusb raises a bulk-write timeout only when zero bytes transferred, so retrying the same offset is duplicate-safe — large jobs no longer overflow the cutter's tiny buffer and abort. A flush() drain barrier integrates with submit() (from Device core: reactor-free thread offload, pre-feed, flush barrier, declared-order defaults #427).
  • DMPL: correct step resolution (1016 steps/inch = 0.025 mm/step, confirmed against the manufacturer's driver data) and a swap_axes option (with a settings checkbox) for firmwares whose first DMPL coordinate drives the media feed instead of the carriage — without it, feed-to-end/pre-feed physically move the carriage on these machines.
  • Driver profiles: VEVOR KH-870 / KH-720 with correct cutting widths (78/63 cm — the advertised sizes are feed widths) and default_config presetting swap_axes/mirror so a freshly created profile cuts correctly.

Depends on defer_to_thread from #427 (cherry-pickable single commit if preferred).

Testing

Physically verified end-to-end on a VEVOR KH-870 on macOS (Apple Silicon): import → pre-feed → large multi-minute jobs with buffer back-pressure → feed past cut with correct end position. tests/test_dmpl_axes.py covers the swap-axes emission at protocol level (5 tests, no hardware needed). The transport itself is exercised by a fake-device suite I run locally; I have not included it here because it needs a stub USB layer that would be a design decision for this repo rather than mine — happy to work that up if you want it.

🤖 Generated with Claude Code

Cutters like the VEVOR/Anhui Anyu family (USB 0483:5750, CH554_CDC)
present printer-class descriptors whose class requests stall, and
macOS creates no serial port for them. This transport drives them
directly over bulk USB: CDC line coding + DTR/RTS init, a keep-alive
that prevents the firmware's idle-suspend crash, self-healing connect
on a worker thread (USB reset + a one-byte pipe probe before anything
is cut), and a queued writer thread using USB NAK as flow control —
bulk timeouts with zero bytes transferred are retried duplicate-free,
partial transfers resume from the exact offset, and flush() lets the
device layer drain the queue before a job is declared complete.

Requires pyusb/libusb. VID/PID/endpoint/baud are configurable.
Depends on inkcut.core.utils.defer_to_thread (fix/device-core).
Use the DMPL-standard 1016 steps/inch (0.025 mm/step) instead of 1021,
and add a swap_axes protocol option (with a settings checkbox) for
firmwares that drive the media feed with the FIRST coordinate and the
carriage with the second — e.g. the Anhui Anyu boards in VEVOR
cutters. Emitting (y, x) keeps Inkcut's convention (y = feed) so
feed-to-end, pre-feed and origin tracking physically reach the
rollers.
DMPL-first (the native language of this firmware; HPGL half-works but
wedges it), USB connection, correct cutting widths (78/63 cm — the
870/720 numbers are feed widths), and default_config enabling
mirror_x and DMPL swap_axes so a freshly created profile cuts with
the correct physical axes out of the box. Also normalizes the Smart 1
entry's manufacturer casing so the tree shows one VEVOR node.
@mcmartnor

Copy link
Copy Markdown
Author

Dependency note: usb.core is imported at module level inside a try/except ImportError, so an install without pyusb loads normally and logs a warning — the transport still appears in the list, and connect() raises if it's selected. pyusb isn't declared in setup.py today. I'd suggest extras_require={'usb': ['pyusb>=1.3.1']}, installed as inkcut[usb], but say the word if you'd rather it were a hard requirement. Note that this covers the Python binding only — libusb itself is a system package (brew install libusb), which the README documents.

#429 is a separate case: it shells out to poppler's pdftocairo with an Inkscape fallback, so it can't be expressed in extras_require at all.

This branch was developed against the 2.1.8 release, which predates
c7a0c68 ("Add HPGL option to separate PU/PD from moves", inkcut#425). The
view.enaml patch was generated from that older base, so applying it on
master silently reverted the separate_z_moves checkbox and turned the
line-feed padding option into a label plus a checkbox labelled "Enable".

Neither change was intended and neither has anything to do with this
branch. HPGLConfigView is restored to master's definition; the only
remaining change to this file is the DMPL swap axes option.
UsbParams exists precisely so the workers never read live Atom members
the UI can edit, but the writer still read config.endpoint and
config.chunk_size straight off the model, and the keepalive read
config.cdc_init. All three are bound to fields in settings.enaml, so
editing the USB settings during an active job could change the endpoint
or chunk size mid-payload.

The snapshot is now stored on the transport and carries chunk_size, and
both workers read it. Behaviour is unchanged unless the config is
edited while a job runs, which is the case that was broken.
@mcmartnor

Copy link
Copy Markdown
Author

Correction on this branch: an earlier revision was generated against the 2.1.8 release and inadvertently reverted c7a0c68 ("Add HPGL option to separate PU/PD from moves", #425), dropping the separate_z_moves checkbox. That was unintended and is fixed — HPGLConfigView now matches master, and the only change this branch makes to view.enaml is the DMPL swap-axes option.

view.enaml defines enamldef DMPLConfigView twice, at line 19 and again
at line 86. The second one wins, so the first has never been the view
the user sees. That was harmless while both were identical, but this
branch adds the swap-axes option to the first definition, which means
the checkbox would never have appeared in the UI.

The later duplicate is removed and the option stays on the surviving
definition. This is why the change is here rather than in a separate
commit: the feature does not work without it.
Five tests: coordinates pass through untouched by default, are
transposed with swap_axes set, the transpose applies to feed-to-end and
to mode 6 as well as ordinary moves, and the option round-trips as
config. Protocol-level only, no hardware needed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant