@thermal-label/brother-ql-core 0.6.0 → 0.6.2

package/src/network-status.ts

@@ -0,0 +1,173 @@
+import type { PrintEngine, PrinterError, StatusDetail } from '@thermal-label/contracts';
+import type { BrotherQLMedia, BrotherQLStatus } from './types.js';
+import { findMediaByDimensions, MEDIA } from './media.js';
+
+/**
+ * Values read from the standard Printer-MIB / Host-Resources-MIB
+ * (RFC 3805 / RFC 2790) of a network print server. Port 9100 carries
+ * no status, so this is the only status source on TCP; see plan 17.
+ */
+export interface PrinterMibStatus {
+  /** hrPrinterStatus: 1 other, 2 unknown, 3 idle, 4 printing, 5 warmup. */
+  printerStatus: number;
+  /** hrPrinterDetectedErrorState: 0–2 octets, bit 0 = MSB of octet 0. */
+  errorState: Uint8Array;
+  /** prtInputMediaName, e.g. `29mm x 90mm / 1.1" x 3.5"` or `62mm / 2.4"`. */
+  mediaName: string;
+  /** prtInputMediaDimFeedDir (length) / XFeedDir (width) in `dimUnit`; negative = unknown. */
+  feedDir?: number;
+  xFeedDir?: number;
+  /** prtInputDimUnit: 3 = ten-thousandths of an inch, 4 = micrometres. */
+  dimUnit?: number;
+}
+
+const PRINTER_STATE: Record<number, string> = {
+  1: 'other',
+  2: 'unknown',
+  3: 'idle',
+  4: 'printing',
+  5: 'warmup',
+};
+
+/** RFC 2790 hrPrinterDetectedErrorState bit names, index = bit. */
+const ERROR_STATE_BITS = [
+  'lowPaper',
+  'noPaper',
+  'lowToner',
+  'noToner',
+  'doorOpen',
+  'jammed',
+  'offline',
+  'serviceRequested',
+  'inputTrayMissing',
+  'outputTrayMissing',
+  'markerSupplyMissing',
+  'outputNearFull',
+  'outputFull',
+  'inputTrayEmpty',
+  'overduePreventMaint',
+] as const;
+
+/** Bit → contracts error code + message; unlisted set bits become `system_error`. */
+const ERROR_STATE_CODES: Record<number, { code: string; message: string }> = {
+  1: { code: 'no_media', message: 'No media' },
+  4: { code: 'cover_open', message: 'Cover open' },
+  5: { code: 'cutter_jam', message: 'Jammed' },
+  6: { code: 'not_ready', message: 'Offline' },
+  7: { code: 'system_error', message: 'Service requested' },
+  13: { code: 'no_media', message: 'Input tray empty' },
+};
+
+/** Warning-only bits: reported as a details row, never an error. */
+const ERROR_STATE_WARNINGS: Record<number, string> = {
+  0: 'Media low',
+};
+
+function errorStateBit(errorState: Uint8Array, bit: number): boolean {
+  const octet = errorState[bit >> 3];
+  return octet !== undefined && (octet & (0x80 >> (bit & 7))) !== 0;
+}
+
+/**
+ * Parse the metric half of a Brother `prtInputMediaName`.
+ * `"29mm x 90mm / …"` → 29×90 die-cut, `"62mm / …"` → 62 continuous.
+ * The `Dia` form is the reference's naming for round labels and is
+ * unverified on the wire. Anything else → `undefined`.
+ */
+export function parseMediaName(name: string): { widthMm: number; heightMm?: number } | undefined {
+  const metric = name.split('/')[0] ?? '';
+  const m = /^\s*(\d+(?:\.\d+)?)\s*mm(?:\s*(?:[x×]\s*(\d+(?:\.\d+)?)\s*mm|(dia)))?\s*$/i.exec(
+    metric,
+  );
+  if (!m?.[1]) return undefined;
+  const widthMm = Number(m[1]);
+  if (m[3]) return { widthMm, heightMm: widthMm };
+  return m[2] === undefined ? { widthMm } : { widthMm, heightMm: Number(m[2]) };
+}
+
+function dimToMm(value: number, unit: number): number | undefined {
+  if (unit === 3) return Math.round(value * 0.00254);
+  if (unit === 4) return Math.round(value / 1000);
+  return undefined;
+}
+
+/**
+ * The name string wins; the Dim OIDs are the fallback. Bench
+ * (QL-820NWB, DK-11201): `prtInputDimUnit` = 4 (micrometres) with
+ * `2900 × 9000`, which is 1/100 mm, so trusting the unit yields a
+ * 3 × 9 mm label. The name is the only value measured to be right.
+ */
+function resolveDimensions(
+  input: PrinterMibStatus,
+): { widthMm: number; heightMm: number } | undefined {
+  const parsed = parseMediaName(input.mediaName);
+  if (parsed) return { widthMm: parsed.widthMm, heightMm: parsed.heightMm ?? 0 };
+  const { xFeedDir, feedDir, dimUnit } = input;
+  if (xFeedDir === undefined || xFeedDir < 0 || dimUnit === undefined) return undefined;
+  const widthMm = dimToMm(xFeedDir, dimUnit);
+  if (widthMm === undefined) return undefined;
+  const heightMm = feedDir !== undefined && feedDir >= 0 ? dimToMm(feedDir, dimUnit) : 0;
+  return { widthMm, heightMm: heightMm ?? 0 };
+}
+
+/**
+ * Whether a roll of this width and type also exists as a two-colour
+ * variant (62 mm continuous: DK-22205 vs DK-22251). Those are
+ * indistinguishable over the network, so callers warn.
+ */
+export function hasTwoColourSibling(media: BrotherQLMedia): boolean {
+  return Object.values(MEDIA).some(
+    m => m.palette !== undefined && m.type === media.type && m.widthMm === media.widthMm,
+  );
+}
+
+/**
+ * Map Printer-MIB values onto the driver's status. `ready` requires
+ * an idle or printing state and no error bits. Two-colour rolls are
+ * invisible on every network surface (DK-22251 reads as 62 mm
+ * continuous), so the single-colour sibling is resolved and a `warn`
+ * row says so.
+ */
+export function statusFromPrinterMib(
+  input: PrinterMibStatus,
+  engine?: Pick<PrintEngine, 'headDots' | 'mediaCompatibility'>,
+): BrotherQLStatus {
+  const errors: PrinterError[] = [];
+  const details: StatusDetail[] = [
+    { label: 'Printer state', value: PRINTER_STATE[input.printerStatus] ?? 'unknown' },
+  ];
+
+  for (const [bit, name] of ERROR_STATE_BITS.entries()) {
+    if (!errorStateBit(input.errorState, bit)) continue;
+    const warning = ERROR_STATE_WARNINGS[bit];
+    if (warning !== undefined) {
+      details.push({ label: 'Media', value: warning, severity: 'warn' });
+      continue;
+    }
+    errors.push(ERROR_STATE_CODES[bit] ?? { code: 'system_error', message: name });
+  }
+
+  const dims = resolveDimensions(input);
+  const detected = dims
+    ? findMediaByDimensions(dims.widthMm, dims.heightMm, false, engine)
+    : undefined;
+  if (detected === undefined) {
+    details.push({
+      label: 'Media',
+      value: `not recognised: ${JSON.stringify(input.mediaName)}`,
+      severity: 'warn',
+    });
+  } else if (hasTwoColourSibling(detected)) {
+    details.push({ label: 'Two-colour', value: 'not detectable over network', severity: 'warn' });
+  }
+
+  const state = input.printerStatus;
+  return {
+    ready: (state === 3 || state === 4) && errors.length === 0,
+    mediaLoaded: detected !== undefined,
+    ...(detected === undefined ? {} : { detectedMedia: detected }),
+    errors,
+    details,
+    rawBytes: new Uint8Array(0),
+  };
+}

package/src/protocol.ts

@@ -249,6 +249,26 @@ function resolveEncoderGeometry(
   return resolveTapeGeometry(media, engine);
 }
 
+/**
+ * Page length for die-cut media: `dieCutMaskedAreaDots` is the
+ * reference's "print area length" (§2.3.2(b) column 4) at 300 dpi;
+ * `doubleRows` is set when the caller supplied 600 dpi rows (QL
+ * high-res, where the encoder does not duplicate lines).
+ */
+function resolveDieCutRows(
+  media: BrotherQLMedia,
+  doubleRows: boolean,
+): { rows: number; highRes: boolean } | undefined {
+  if (media.type !== 'die-cut') return undefined;
+  const area = media.dieCutMaskedAreaDots;
+  if (typeof area !== 'number') {
+    throw new Error(
+      `die-cut media ${media.id.toString()} (${media.name}) has no dieCutMaskedAreaDots; page length unknown`,
+    );
+  }
+  return { rows: doubleRows ? area * 2 : area, highRes: doubleRows };
+}
+
 interface EncodeContext {
   config: RasterProtocolConfig;
   engine?: EncoderEngine | undefined;
@@ -302,7 +322,21 @@ function encodeRasterJob(pages: PageData[], options: JobOptions, ctx: EncodeCont
     // Per §7.3: PT high-res doubles the feed margin and duplicates
     // each raster line. QL high-res leaves both untouched.
     const baseMargin = opts.marginDots ?? config.feedMarginDots;
-    const marginDots = config.duplicateRasterLines && highRes ? baseMargin * 2 : baseMargin;
+    const feedMargin = config.duplicateRasterLines && highRes ? baseMargin * 2 : baseMargin;
+
+    // Die-cut pages are fixed-length (reference §2.3.3 / §2.3.4): the
+    // printer cuts at raster count + margin, not at the gap, so the page
+    // is always the print-area length with `ESC i d` 0 and the bitmap
+    // sits centred in it. Continuous pages are the bitmap's own height.
+    const dieCut = resolveDieCutRows(media, highRes && !config.duplicateRasterLines);
+    const rowCount = dieCut?.rows ?? bitmap.heightPx;
+    const marginDots = dieCut ? 0 : feedMargin;
+    if (dieCut && bitmap.heightPx > rowCount) {
+      throw new Error(
+        `Bitmap is ${bitmap.heightPx.toString()} rows but ${media.name} prints exactly ${rowCount.toString()}${dieCut.highRes ? ' (high-res)' : ''}; resize the image`,
+      );
+    }
+    const padTop = dieCut ? Math.floor((rowCount - bitmap.heightPx) / 2) : 0;
 
     // Multi-ink media (e.g. DK-22251) requires two-color mode even for black-only jobs.
     // Auto-create an empty red plane when the tape demands it but caller didn't supply one.
@@ -317,8 +351,6 @@ function encodeRasterJob(pages: PageData[], options: JobOptions, ctx: EncodeCont
       }
     }
 
-    const rowCount = bitmap.heightPx;
-
     chunks.push(buildRasterMode());
     chunks.push(buildStatusRequest());
     chunks.push(buildPrintInfo(media, rowCount, i));
@@ -343,18 +375,20 @@ function encodeRasterJob(pages: PageData[], options: JobOptions, ctx: EncodeCont
     // Per §7.3: PT high-res duplicates each raster line. QL doesn't.
     const duplicate = config.duplicateRasterLines && highRes;
     for (let r = 0; r < rowCount; r++) {
-      const blackSrc = getRow(bitmap, r);
+      // Rows outside the bitmap (die-cut padding) stay blank.
+      const src = r - padTop;
+      const inBitmap = src >= 0 && src < bitmap.heightPx;
       const blackBytes = new Uint8Array(rowByteLen);
-      placeBits(blackSrc, bitmap.widthPx, blackBytes, leftMarginPins);
+      if (inBitmap) placeBits(getRow(bitmap, src), bitmap.widthPx, blackBytes, leftMarginPins);
       const blackPayload = compress ? packBits(blackBytes) : blackBytes;
       const blackChunk = buildRasterRow(blackPayload, 'black', twoColor);
       chunks.push(blackChunk);
       if (duplicate) chunks.push(blackChunk);
 
       if (twoColor && redBitmap !== undefined) {
-        const redSrc = getRow(redBitmap, r);
         const redBytes = new Uint8Array(rowByteLen);
-        placeBits(redSrc, redBitmap.widthPx, redBytes, leftMarginPins);
+        if (inBitmap)
+          placeBits(getRow(redBitmap, src), redBitmap.widthPx, redBytes, leftMarginPins);
         const redPayload = compress ? packBits(redBytes) : redBytes;
         const redChunk = buildRasterRow(redPayload, 'red', twoColor);
         chunks.push(redChunk);

package/src/status.ts

@@ -31,6 +31,8 @@ const ERROR_INFO_2: { bit: number; code: string; message: string }[] = [
  * Parse a Brother QL 32-byte status response.
  *
  * Fields:
+ *   byte 3  — series code (`'4'` for QL-800/810W/820NWB)
+ *   byte 4  — model code (`'8'` QL-800, `'9'` QL-810W, `'A'` QL-820NWB)
  *   byte 8  — error info 1 (bit mask, see ERROR_INFO_1)
  *   byte 9  — error info 2 (bit mask, see ERROR_INFO_2)
  *   byte 10 — media width (mm)
@@ -46,9 +48,9 @@ const ERROR_INFO_2: { bit: number; code: string; message: string }[] = [
  * `findMediaByDimensions`.
  *
  * `details` carries the contracts-standard `StatusDetail[]` diagnostic
- * rows the harness renders verbatim: the print phase (always present)
- * and the head-cooling notification (only when the printer reports
- * one).
+ * rows the harness renders verbatim: the model code and the print
+ * phase (always present) and the head-cooling notification (only when
+ * the printer reports one).
  */
 export function parseStatus(
   bytes: Uint8Array,
@@ -59,6 +61,7 @@ export function parseStatus(
   }
 
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const modelCode = formatModelCode(view.getUint8(3), view.getUint8(4));
   const errInfo1 = view.getUint8(8);
   const errInfo2 = view.getUint8(9);
   const mediaWidthMm = view.getUint8(10);
@@ -87,15 +90,28 @@ export function parseStatus(
     mediaLoaded,
     ...(detected === undefined ? {} : { detectedMedia: detected }),
     errors,
-    details: buildStatusDetails(phaseType, notification),
+    details: buildStatusDetails(modelCode, phaseType, notification),
     rawBytes: bytes,
   };
 }
 
+/**
+ * Bytes 3/4 as Brother prints them in the reference (ASCII, e.g. `4A`
+ * for the QL-820NWB); hex for anything unprintable. Informational
+ * only: the USB/serial model signal a serial-port identify can use.
+ */
+function formatModelCode(series: number, model: number): string {
+  const printable = (b: number): boolean => b >= 0x21 && b <= 0x7e;
+  return printable(series) && printable(model)
+    ? String.fromCharCode(series, model)
+    : `0x${series.toString(16).padStart(2, '0')} 0x${model.toString(16).padStart(2, '0')}`;
+}
+
 /**
  * Build the contracts-standard `StatusDetail[]` rows for a parsed
  * Brother QL status.
  *
+ * - The model-code row (bytes 3/4) is always emitted.
  * - The print-phase row (byte 19) is always emitted — it is the most
  *   useful "is the device doing anything" signal for a stuck report.
  * - The head-cooling row (byte 22) is emitted only when the printer
@@ -103,8 +119,12 @@ export function parseStatus(
  *   normal idle status stays uncluttered. "Cooling started" is a
  *   `warn` (printing is paused), "cooling finished" is plain `info`.
  */
-function buildStatusDetails(phaseType: number, notification: number): StatusDetail[] {
-  const details: StatusDetail[] = [];
+function buildStatusDetails(
+  modelCode: string,
+  phaseType: number,
+  notification: number,
+): StatusDetail[] {
+  const details: StatusDetail[] = [{ label: 'Model code', value: modelCode }];
 
   details.push({
     label: 'Print phase',

package/src/types.ts

@@ -107,7 +107,11 @@ export interface BrotherQLMedia extends MediaDescriptor {
   printableDots?: number;
   leftMarginPins?: number;
   rightMarginPins?: number;
-  /** Die-cut masked area in dots (registration windows). */
+  /**
+   * Die-cut page length in dots at 300 dpi: the reference's "print area
+   * length" (§2.3.2(b) column 4). The encoder sends exactly this many
+   * rows for die-cut media; see DECISIONS D20.
+   */
   dieCutMaskedAreaDots?: number;
 }