phomemo-protocol

A small, dependency-free TypeScript library for talking to Phomemo label printers: it turns an image into the printer's raster wire format, and provides a Web Serial transport for sending it over USB or Bluetooth.

Supports two printer families:

• M110 family (M110, M120, M220) — ESC N speed/darkness + 0x1f 0x11 media type header, 0x1f 0xf0 status footer.
• M02 family (M02, M02 Pro, M02S, T02) — plain ESC/POS (ESC @ / ESC a / 0x1f 0x11 0x02 0x04 header, ESC d feed + 0x1f 0x11 status-query footer). Splits tall images into multiple 255-line raster blocks, since that's the hardware's per-block limit. Experimental / untested on real M02-family hardware.

Extracted from labelync so the protocol and transport logic can be reused outside that app.

Install

npm install phomemo-protocol

Usage

The core API (phomemo-protocol) is transport- and platform-agnostic — it just turns pixels into bytes:

import { rasterizeMonochrome, buildPrintCommands } from 'phomemo-protocol';

// image: { width, height, data } — e.g. from canvas.getContext('2d').getImageData(...)
const bitmap = rasterizeMonochrome(image);

const commands = buildPrintCommands(bitmap, {
  deviceModel: 'M110',
  darkness: 0x08, // 0x01–0x0f, M110 family only
  speed: 0x05,    // 0x01–0x05, M110 family only
  paperType: 0x0a // 0x0a "Label With Gaps" / 0x0b "Continuous" / 0x26 "Label With Marks", M110 family only
});

// `commands` is an ordered array of Uint8Array chunks — write each one to
// the printer's output stream in order (see the serial transport below, or
// bring your own transport, e.g. Node's `serialport` package).

For browsers, phomemo-protocol/serial wraps the Web Serial API with the settings Phomemo printers expect. This works both for USB-connected printers and for printers paired over Bluetooth, since Chromium exposes Bluetooth SPP connections as a serial port too — see Web Serial over Bluetooth.

import { openPhomemoSerialPort, writePrintCommands, getSerialDeviceId } from 'phomemo-protocol/serial';

const port = await navigator.serial.requestPort();
await openPhomemoSerialPort(port);

const deviceId = getSerialDeviceId(port); // stable id, e.g. for remembering per-printer settings

await writePrintCommands(port, commands);

SerialPortLike in phomemo-protocol/serial is a structural type, not tied to the DOM lib's global SerialPort — pass in whatever your environment gives you for navigator.serial, as long as it has writable, open() and getInfo().

A GATT-based Bluetooth transport (Web Bluetooth, for printers that don't expose an SPP serial port) could be added later as its own phomemo-protocol/ble submodule without changing the core API.

What this library does not do

• Rendering labels/templates to an image — bring your own canvas/SVG rendering and pass the resulting pixels in.
• Remembering printer settings, auto-reconnect UX, timeouts — these are application policy, not protocol, and are left to the caller.
• Dithering — rasterizeMonochrome does simple black/white thresholding; dither the image yourself first if you want that.

Development

npm install
npm test
npm run build

Acknowledgments

• vivier/phomemo-tools — reference implementation for Phomemo printer protocols

License

MIT