Nemonic MIP-201W Native macOS Driver

A 100% native Apple Silicon (arm64) macOS driver for the Mangoslab Nemonic MIP-201W sticky note printer.

Why this exists

The official driver provided by Mangoslab relies on an older Intel (x86_64) binary filter (rastertonemonic). On modern Apple Silicon Macs (M1/M2/M3/M4), this forces users to install Apple's Rosetta 2 translation layer. Additionally, the official driver has hardcoded paths that conflict with the strict CUPS sandbox introduced in recent versions of macOS, causing printing to fail silently.

This project completely reverse-engineers the printer's proprietary USB protocol and provides a native, Rosetta-free CUPS driver written entirely in Swift.

Features

• 100% Native Apple Silicon support: No Rosetta required.
• Bypasses cgpdftoraster: Directly reads PDF print jobs and natively rasterizes them using Apple's highly-optimized CoreGraphics engine.
• Smart Auto-Crop: Native macOS apps (like Chrome, Word, Typora) often add invisible 1-inch margins to printed pages. On an 80mm sticky note, this squishes your text into a tiny 5mm column! This driver automatically scans the rendered image, crops out the useless white space, and blows up the actual content to perfectly fit the roll.
• Hardware Safety Margin: Automatically buffers your text exactly 36 dots (~4.5mm) away from the adhesive strip so it never overlaps the sticky edge or gets clipped by the hardware lip.
• Sideways Feed Correction (Sticky mode): Because the sticky tape runs along the feed roll (the right-hand side), the physical printer is actually 90 degrees sideways compared to a standard POS receipt printer. In Sticky print mode the driver rotates jobs 90° clockwise so text reads correctly on notes with the adhesive edge.
• Receipt / Portrait mode: The same hardware can now also be used for normal receipts, tickets, or logs. Select Receipt in the Print Mode option (or use a dedicated queue) and the driver emits upright raster with no extra rotation.
• Prints Anything: Accurately reproduces system fonts, vector graphics, shapes, barcodes, and QR codes natively.

Word printing

For Microsoft Word, use the dedicated queues created by:

sudo ./setup_custom_queues.sh

Use Nemonic_Sticky for post-it notes and Nemonic_Receipt for upright receipts. In Word, select the printer queue before setting the page size so Word loads the queue-specific media list.

Recommended Word settings:

• Sticky notes: Nemonic_Sticky, 80x80mm.Fullbleed.
• Receipts: Nemonic_Receipt, 80x136mm.Fullbleed.
• Use actual size / 100% scaling for the first test print.
• Avoid fit-to-page until the controlled shell and Word baselines are known-good.

Confirmed baseline:

• Shell sticky, shell receipt, and Word receipt test prints are correct with installed build pdftonemonic build 2026-05-22-receipt-default-none.
• The correct receipt physical transform is no additional transform (None): the driver preserves Word/PDF orientation and lets the printer consume rows in the normal order.

Developer documentation

• docs/technical/developer-guide.md — CUPS argv/stdin, RGB→gray raster, correct auto-crop math (Letter + BBEdit), env vars, and debugging error_log.
• LEARNINGS.md — Hardware/protocol notes and historical pitfalls.

Before you use paper (preflight)

Check a PDF offline to test for accurate generation:

bash preflight_pdf.sh --open /path/to/same-file-you-will-print.pdf

This compiles the filter from the repo, builds the same ESC/POS bytes, counts black dots, and writes /tmp/nemonic_preflight.png. It fails (exit 1) if the stream is tiny or ink is below MIN_INK_DOTS (default 500). Open the PNG and press ⌘L once so it looks like the physical note.

You can check the exact PDF you will print (e.g. the same file from BBEdit / Print to PDF). No lp in this script — only validation.

Installation

1. Clone or download this repository.
2. Open Terminal and navigate to the directory.
3. Run the installer script with sudo:

sudo ./install.sh

The script will:

• Compile the Swift driver with xcrun --show-sdk-path (needs Command Line Tools or Xcode).
• Abort if the compiled binary is suspiciously small (so a failed compile never replaces a good filter).
• Install the binary to /Library/Printers/Nemonic/.
• Install the patched full-bleed PPD and optionally add the USB queue.

Blank pages — do this in order

1. unset NEMONIC_PREVIEW_ONLY (and remove from ~/.zshrc if set). Preview-only mode sends zero bytes to the printer.
2. git pull then sudo ./install.sh and confirm there is no ERROR line.
3. bash run_print_gates.sh then bash diagnose_print.sh (no sudo). Installed raster stdout should be tens of kB for the built-in test PDF; CUPS error_log should show the current filterBuildTag from pdftonemonic stderr on real jobs.
4. For GUI apps (e.g. BBEdit), preflight the same PDF you print: bash preflight_pdf.sh --open …. See the developer guide if Letter-sized jobs are blank but small test PDFs work.

Uninstallation

To completely remove the driver and printer queue from your system:

sudo ./uninstall.sh

How it works (Protocol Technicals)

During the reverse-engineering process, we discovered the printer accepts a slight variation of the standard ESC/POS protocol (GS v 0) wrapped in specific start/end bytes:

1. Header: STX (0x02), ESC @ (Initialize)
2. Image Header: GS v 0 0 + WidthBytes(72) + HeightDots
3. Data: Raw 1-bit monochrome pixel array (1 = black/burn, 0 = white). Note: The hardware does not mirror the X-axis natively; all orientation logic is handled mathematically in the Y-DOWN coordinate space.
4. Footer: ESC C 1, ESC l 0, ESC P, ESC i (Partial Cut), ETX (0x03)

License

MIT License. Feel free to fork, modify, and improve.

Fun Terminal Scripts

Because this driver turns your Nemonic into a physical extension of your terminal (and auto-crops whitespace), you can script almost anything to it!

We included a bundle of fun scripts you can install directly into your terminal profile (~/.zshrc):

cd fun_scripts
./install_fun_scripts.sh
source ~/.zshrc

This gives you access to 5 instant commands:

• todo "Task 1" "Task 2": Instantly prints a properly formatted checkbox to-do list.
• focus "One Task": Prints a bold, single task for you to stick to the bottom of your monitor so you don't get distracted.
• weather "London": Prints a live, minimalist ASCII-art weather forecast.
• ticket 123: (Requires GitHub CLI). Fetches a GitHub issue and prints a physical Kanban ticket for your wall.
• joke: Prints a randomized fortune quote spoken by an ASCII cow (requires fortune and cowsay).

(Note: The fun scripts use a custom, lightning-fast native Swift text-to-pdf renderer to bypass a notorious Apple CUPS sandbox bug that prevents command-line text from rendering system fonts).